Skip to content

Push source stack branches through the CAOS server #265

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
nishu-builder wants to merge 2 commits into from
Closed

Push source stack branches through the CAOS server #265

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
56ad570
Push source stack branches through the CAOS server
nishu-builder Sep 19, 2026
176a511
Share publication recovery between branch and stack pushes
nishu-builder Sep 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions SPEC.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -642,3 +642,7 @@ See [agent publication](design/agent-publish.md) for mechanics and recovery.
The stack tool registers ordered source gitlinks and their original predecessor boundaries. Rebase replays linear histories with object-level Git merges; merge mode propagates updated predecessors
without rewriting history. A conflict keeps original pointers unchanged and records a separate editable draft plus the full conflict report. Continue explicitly acknowledges resolution. Completed
operations replace every source pointer together after checking the original inputs. No .caos/conflicts is introduced by this workflow. See [Agent stacks](design/agent-stacks.md).

The push_stack tool pins all source commits and remote-head leases, then publishes each branch through the same server path as publish_source. A rebased push explicitly enables rewrite; publication
retains the exact lease and all ordinary guards. Each branch outcome is recorded before proceeding. Recovery skips completed branches and uses the original pins. Failure stops later pushes and returns
partial receipts. PR creation and GitHub stack membership are separate from pushing.
91 changes: 20 additions & 71 deletions design/agent-github.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,12 @@
# Importing and publishing

Imports are implemented through the server endpoint, `caos import-git`, and
the agent's `import_source` tool. Publication proceeds through branches, PRs
and stacks. Separate merge drafts remain a follow-up.
Imports are implemented through the server endpoint, `caos import-git`, and the agent's `import_source` tool. Publication pushes individual branches or registered stacks of branches. Stack operations
keep merge drafts outside source history.

## Importing

`import_source(source, revision?, into)` runs inline in `std/llm-step`.
It accepts an HTTPS repository and a branch, full ref, or full commit hash.
Omitting `revision` selects the default branch. Keep `/import` for local paths.
`import_source(source, revision?, into)` runs inline in `std/llm-step`. It accepts an HTTPS repository and a branch, full ref, or full commit hash. Omitting `revision` selects the default branch. Keep
`/import` for local paths.

For each tool call:

Expand All @@ -27,18 +25,12 @@ For each tool call:
imports/repo/main.source.json provenance
```

The destination and provenance path must both be unused. An import creates
an unchanged snapshot; it does not merge into or advance another source.
Provenance records the repository, requested revision, commit, observation
time, and default branch when known. For `origin/main`, choose the repository
from the selected source's provenance and import `main` at a fresh path.
The destination and provenance path must both be unused. An import creates an unchanged snapshot; it does not merge into or advance another source. Provenance records the repository, requested
revision, commit, observation time, and default branch when known. For `origin/main`, choose the repository from the selected source's provenance and import `main` at a fresh path.

The [server endpoint](git-import.md) fetches H and its full history into private
staging, verifies them, and publishes the complete pack into the server store. It uses verified complete imports as
negotiation tips; standalone trees and blobs may still be downloaded again.
A completion marker for the same URL and H skips fetch and verification.
The endpoint handles object availability; callers handle ref resolution and
conversation state.
The [server endpoint](git-import.md) fetches H and its full history into private staging, verifies them, and publishes the complete pack into the server store. It uses verified complete imports as
negotiation tips; standalone trees and blobs may still be downloaded again. A completion marker for the same URL and H skips fetch and verification. The endpoint handles object availability; callers
handle ref resolution and conversation state.

Supply the token through the existing secret store:

Expand All @@ -50,64 +42,21 @@ reader=std/llm-step
reader=std/github
```

Keep the value file ignored and run `caos secrets` to initialize its entropy.
The agent uses `/secret/github-token` for GitHub ref lookup and passes
`--github-token-file=/secret/github-token` to `import-git`. The command
forwards it in the sensitive `X-Caos-Git-Token` header; the server does not look
up the calling job's secrets.
Keep the value file ignored and run `caos secrets` to initialize its entropy. The agent uses `/secret/github-token` for GitHub ref lookup and passes `--github-token-file=/secret/github-token` to
`import-git`. The command forwards it in the sensitive `X-Caos-Git-Token` header; the server does not look up the calling job's secrets.

Ref lookup and fetch share a repository-scoped Git credential helper. Tokens
stay out of URLs, Git config, saved arguments, provenance, and logs. Automatic
GitHub credentials apply only to `github.com` on the default HTTPS port.
Public imports need no token. Importing needs neither `gh` nor another worker.
Ref lookup and fetch share a repository-scoped Git credential helper. Tokens stay out of URLs, Git config, saved arguments, provenance, and logs. Automatic GitHub credentials apply only to
`github.com` on the default HTTPS port. Public imports need no token. Importing needs neither `gh` nor another worker.

## Publishing

The [publication design](agent-publish.md) separates the remaining work:
[Branch publication](agent-publish.md) uses POST /git/push, caos push-git and publish_source to push exact commits directly from the server with an expected-head lease. The github tool runs gh with an
explicit repository for PRs, issues, review and stack metadata.

- **Branches:** `POST /git/push`, `caos push-git` and `publish_source` push
exact code commits from the server with a lease. Each layer has its own
implementation PR.
- **PRs:** separate PRs add the `std/github` worker and agent `github` tool. Next, validate the agent's create, update and review workflow using
`gh`, with explicit repositories and branch names.
- **Stacks:** keep code boundaries in gitlinks, publish bottom to top, and
use `gh stack link` with existing PR URLs. Validate linking, propagation
and landing without a source checkout in the GitHub worker.
[Stack operations](agent-stacks.md) register ordered source gitlinks, remember each layer's predecessor, and merge or rebase them using Git objects. Conflicts pause with a separate draft gitlink and
report. The agent edits the draft and explicitly continues; finished source history contains no .caos/conflicts or draft editing commits.

The TUI's `/pr` and `/publish-branch` commands are removed. The follow-ups
start with workflow instructions and integration tests using these tools.
push_stack pushes registered layers through the same server path as publish_source, recording each branch's result. Stack pushing needs no GitHub worker and creates no PRs or GitHub stack membership.
PR automation is a separate follow-up.

### Merges

This section is a follow-up proposal. Current merges still use source-tree
conflict ledgers and the publication guards described in SPEC.md.

Clean merges use the existing merge worker. On conflict, preserve the source O
and keep the attempt beside it in the conversation:

```text
feature/01-core gitlink -> O
merges/update-main/
ours gitlink -> O
theirs gitlink -> T
work gitlink -> D
conflicts Git's complete conflict report
```

D starts with Git's proposed merged tree and O as its single parent. The agent
edits this separate draft gitlink and tests it. The report stays outside the
code tree; newly created sources and drafts contain no `.caos/conflicts`.

`finish_merge(attempt="merges/update-main", target="feature/01-core")` takes
the draft's current tree R and creates `M = commit(tree=R, parents=[O,T])`.
Verify O and T against the attempt's creation record, recheck the draft, and
advance the target only if it still points to O. Otherwise retain the result
for reconciliation. Draft commits stay in conversation history, outside M's
ancestry. Test the final source before publication.

Finishing explicitly asserts resolution. Preserve Git's complete conflict
report, including messages and stage objects; deleting markers or report rows
is not proof that structural conflicts are resolved. Delegate by copying the
whole attempt with `cp -a`, harvesting the edited draft, and then finishing.
Abandoning an attempt leaves the source unchanged. Handle old source-tree
conflict ledgers before removing their compatibility cleanup.
The TUI's /pr and /publish-branch commands are removed. /import remains for local paths. Older non-stack merge operations still use the legacy source-tree conflict ledger.
Loading
Loading