c8ctl-plugin-nano 1.68.0 → 1.69.1
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 +41 -4
- package/agent-checkpoint.mjs +944 -0
- package/agent-resume.mjs +4 -3
- package/c8ctl-plugin.js +404 -18
- package/nanobpmn-binary.json +3 -3
- 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,44 @@ 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.
|
|
750
787
|
|
|
751
788
|
> **Agent outcomes.** A harness may report an explicit end-of-task outcome in its
|
|
752
789
|
> `session/prompt` result as `_meta.outcome` — `{ "status": "completed" | "blocked",
|