c8ctl-plugin-nano 1.67.0 → 1.69.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +51 -5
- package/agent-checkpoint.mjs +944 -0
- package/agent-resume.mjs +4 -3
- package/c8ctl-plugin.js +504 -27
- package/package.json +9 -8
package/README.md
CHANGED
|
@@ -729,12 +729,11 @@ the job with a decremented retry count. Profiles are stored in the plugin's
|
|
|
729
729
|
> `repository.sha`-detached checkout likewise recover nothing. For every transcript-only
|
|
730
730
|
> run the resume preamble points at the transcript (VERIFY-first) rather than promising
|
|
731
731
|
> a branch to check out.
|
|
732
|
-
> - **Uncommitted working-tree changes are *not* recovered**
|
|
732
|
+
> - **Uncommitted working-tree changes are *not* recovered** by default —
|
|
733
733
|
> the throwaway workspace does not persist across activations, so any delta the
|
|
734
734
|
> previous run had not committed is lost and the resumed agent re-derives it. The
|
|
735
|
-
> resume preamble states this explicitly. (
|
|
736
|
-
>
|
|
737
|
-
> increment.)
|
|
735
|
+
> resume preamble states this explicitly. **WIP checkpoints** (below, on by default
|
|
736
|
+
> for pushing jobs) recover them.
|
|
738
737
|
>
|
|
739
738
|
> Resume is **best-effort and gated to external agent jobs** (the only ones with a
|
|
740
739
|
> durable transcript). A read failure, an SDK without an AgentInstance read
|
|
@@ -747,6 +746,53 @@ the job with a decremented retry count. Profiles are stored in the plugin's
|
|
|
747
746
|
> prompt (VERIFY-first, like the transcript), and a harness that advertises
|
|
748
747
|
> `agentCapabilities._meta.planSeed` also receives it in `session/new` `_meta.plan`
|
|
749
748
|
> so it can keep working the same plan. `NANO_AGENT_PLAN=off` disables both.
|
|
749
|
+
>
|
|
750
|
+
> **WIP checkpoints (`NANO_AGENT_CHECKPOINT=auto|on|off`, default `auto`).** The worker
|
|
751
|
+
> periodically snapshots the agent's workspace — uncommitted changes *and* unpushed local
|
|
752
|
+
> commits — to `refs/nano/wip/<elementInstanceKey>` on the job's remote, without touching
|
|
753
|
+
> the agent's HEAD, index or branch (a "shadow commit" built through a temporary index).
|
|
754
|
+
> `auto` enables this only for jobs that already publish their work: a provisioned,
|
|
755
|
+
> **authenticated** clone on a working branch with `branch.push` not `false` (read-only,
|
|
756
|
+
> anonymous, detached and repo-less jobs are skipped). `on` forces it for any provisioned
|
|
757
|
+
> job; `off` disables it.
|
|
758
|
+
>
|
|
759
|
+
> - **What is left out:** `.gitignore`d paths; secret-looking paths (`.env*`, `*.pem`,
|
|
760
|
+
> `id_*`, `.npmrc`, …); files over `NANO_AGENT_CHECKPOINT_MAX_FILE_BYTES` (5 MiB); and
|
|
761
|
+
> any changed file whose *content* contains one of the job's own injected secret
|
|
762
|
+
> values, the repo token, or a common credential format (private keys, GitHub / AWS /
|
|
763
|
+
> Slack / OpenAI-style tokens).
|
|
764
|
+
> - **When:** after a completed ACP tool call or plan change (at most one per
|
|
765
|
+
> `NANO_AGENT_CHECKPOINT_MIN_INTERVAL_MS`, default 60s), on a safety-net timer
|
|
766
|
+
> (`NANO_AGENT_CHECKPOINT_INTERVAL_MS`, default 300s, `0` disables — the only trigger for
|
|
767
|
+
> pipe/PTY harnesses), and once more when a run fails or is force-stopped. Each
|
|
768
|
+
> checkpoint also sets a best-effort local `agentCheckpoint {ref, sha, head, at, reason,
|
|
769
|
+
> branch}` variable on the element instance.
|
|
770
|
+
> - **Restore:** a later activation of the same element instance restores the snapshot
|
|
771
|
+
> into the fresh clone as uncommitted changes (recovering local commits too) and tells
|
|
772
|
+
> the agent to inspect `git status`/`git diff` first.
|
|
773
|
+
> - **Cleanup:** the ref is deleted once the engine acknowledges `job.complete` for a run
|
|
774
|
+
> whose branch push succeeded. Until that ack a lost lease or failed settle redelivers
|
|
775
|
+
> the job, so the ref stays restorable. Orphans (cancelled instances, failed acks,
|
|
776
|
+
> exhausted retries) are reclaimed by a background sweep (at most hourly per remote per
|
|
777
|
+
> worker) that deletes WIP refs older than `NANO_AGENT_CHECKPOINT_TTL_MS` (7 days), or
|
|
778
|
+
> older than 1h whose element instance the engine reports `COMPLETED`/`TERMINATED`.
|
|
779
|
+
> - **Safety:** pushes use `--force-with-lease`, so a superseded worker can't clobber a
|
|
780
|
+
> newer run's checkpoint. A remote *policy* refusal (repository rules, secret push
|
|
781
|
+
> protection) or a permission error stops checkpointing for that job with a warning;
|
|
782
|
+
> network errors are retried on the next trigger.
|
|
783
|
+
>
|
|
784
|
+
> Caveats: WIP refs are visible to anyone who can read the repo; the worker can't pause
|
|
785
|
+
> the agent, so a snapshot may catch a half-written file. Everything is best-effort — a
|
|
786
|
+
> failure degrades to transcript-only resume.
|
|
787
|
+
|
|
788
|
+
> **Agent outcomes.** A harness may report an explicit end-of-task outcome in its
|
|
789
|
+
> `session/prompt` result as `_meta.outcome` — `{ "status": "completed" | "blocked",
|
|
790
|
+
> "summary": "…" }` (rusty-harness's `report_outcome` tool). It is recorded in
|
|
791
|
+
> `io.nanobpm.agentResult.outcome`. If the agent returned no result of its own, a
|
|
792
|
+
> `blocked` outcome becomes the result `{ "status": "blocked", "summary", "question" }`,
|
|
793
|
+
> so the job escalates instead of taking a re-emit nudge turn. A result written to
|
|
794
|
+
> `$AGENT_RESULT_FILE` (or the `::nano:result::` sentinel) always wins, and agents
|
|
795
|
+
> that send no outcome are handled exactly as before.
|
|
750
796
|
|
|
751
797
|
### Task envelope, sandboxes & disk hygiene
|
|
752
798
|
|
|
@@ -814,7 +860,7 @@ logged and echoed on the output envelope as `promptResourceKey` for audit (the e
|
|
|
814
860
|
only `latest`, so the key is the reproducibility handle).
|
|
815
861
|
|
|
816
862
|
On completion the plugin writes an **output envelope** back under
|
|
817
|
-
`io.nanobpm.agentResult` (`{schemaVersion, status, sandbox, image, output, truncated, stderrTruncated, exitCode, signal, error, promptResourceKey?}`). When a repository was
|
|
863
|
+
`io.nanobpm.agentResult` (`{schemaVersion, status, sandbox, image, output, truncated, stderrTruncated, exitCode, signal, error, outcome?, promptResourceKey?}`). When a repository was
|
|
818
864
|
provisioned (below) it also carries `{repository, branch, baseSha, headSha, commits[], pushed, pushError?, pushFailed?, strandedCommits?, branchMismatch?, scanError?, gitError?, pr?}`. `pushFailed` is the explicit "push failed" flag — set for a non-zero `git push` **whose result could not be confirmed as landed at the remote** (a non-fast-forward rejection, or an auth, hook, or network error), not only a server rejection. **`pushFailed` does not by itself prove a remote push was attempted or rejected:** `finalizeGit` also sets it (with `strandedCommits` and a `branchMismatch` `{expected, actual}`) when it *refuses to push at all* because the harness moved HEAD off the provisioned work branch — or left commits abandoned on another local branch — so pushing the work branch would publish stale work and strand those commits (no `git push` runs, so `pushError` is absent in that case). As a guard against false strands, a non-zero push is re-checked with `ls-remote`: if `origin/<branch>` already points at `headSha` — or the remote tip is a **descendant** of `headSha` (another actor pushed a further commit after ours landed) — the push is treated as a transport hiccup that landed after the ref was accepted (`pushed: true`, no `pushFailed`/`pushError`); otherwise `pushFailed` is set and `strandedCommits` lists the SHAs of the new commits left UNPUSHED in the throwaway workspace — together they are the recovery handle for a failed push, so consumers must not treat `pushed: false` alone as the only signal. On such a failure (a rejected push **or** a branch-mismatch refusal) the throwaway workspace is preserved **best-effort** (even under the default `--keep-runs=false`) so those SHAs stay recoverable, but this is a *recovery window, not a durable archive*: the run-directory reaper still ages it out by mtime and worker shutdown removes the namespace — copy the stranded commits out promptly (or run with `--keep-runs`). **`scanError`** flags a **best-effort/PARTIAL** `strandedCommits` list: a commit or remote-reachability scan did **not** complete, so a consumer should recover the whole preserved workspace rather than trust the list exactly. It arises two ways: (a) a **pre-push** commit-enumeration scan failed, so `finalizeGit` refused to push on an incomplete graph — **no push was attempted** (`pushError` is absent) and `strandedCommits` is a partial surfacing; or (b) a push was **ATTEMPTED and rejected** but the remote-reachability FILTER that trims already-published commits from the strand set itself failed — so `scanError` is present **alongside** `pushError`, marking the rejected-push strand list as best-effort (it may falsely include an already-landed commit). Either way `pushFailed` stays authoritative; `scanError` is how a consumer knows the strand list is inexact (recover the whole workspace) versus an exact list (a rejected push with no `scanError`).
|
|
819
865
|
|
|
820
866
|
**Git provisioning (host).** When `--sandbox none` (the default) and the envelope
|