c8ctl-plugin-nano 1.63.2 → 1.65.0

package/README.md

@@ -1060,6 +1060,8 @@ c8ctl nano supervisor add reviewer                  # add + spawn a worker (forw
 c8ctl nano supervisor add reviewer --name reviewer-2 # a SECOND reviewer, named so it stays distinct
 c8ctl nano supervisor add reviewer --instances 3    # add 3 distinct auto-named reviewers in one call
 c8ctl nano supervisor restart reviewer             # by worker id or profile name
+c8ctl nano supervisor reload                        # adopt new code fleet-wide (rolling drain+respawn, zero downtime)
+c8ctl nano supervisor reload reviewer               # reload just one worker/profile
 c8ctl nano supervisor remove coder                 # stop + drop a worker (also: `all`)
 c8ctl nano supervisor logs reviewer --follow       # tail a worker's log (or the daemon's)
 c8ctl nano supervisor stop                          # stop the daemon and every worker
@@ -1109,6 +1111,73 @@ How it works and where things live:
 - Stopping is SIGTERM → grace → SIGKILL, per worker and for the daemon; `stop`
   always clears `supervisor.json` so a stale marker never wedges a future start.
 
+### Hot code reload: `supervisor reload` / `workforce reload`
+
+When you update the plugin on a machine that's already running a fleet
+(`c8ctl nano update`, or otherwise replacing the installed `c8ctl-plugin-nano`),
+`supervisor reload` adopts the new code **without stopping the fleet**:
+
+```bash
+c8ctl nano update            # pull the new harness onto disk
+c8ctl nano supervisor reload # roll it into the running fleet, zero downtime
+```
+
+- Each supervised worker is a **separate `nano work` process** that reads the
+  plugin from disk when it starts, so the daemon adopts new code by **rolling
+  through the workers one at a time** — gracefully draining each (the same
+  `SIGUSR2` quiesce as `stop`: it stops leasing new jobs, finishes the ones in
+  flight, and exits) and respawning it, which re-reads the updated
+  `c8ctl-plugin.js`, its sidecars, and `supervisor.dist.js`. Because only one
+  worker is down at a time, the rest of the fleet keeps serving — **zero fleet
+  downtime**. To keep it genuinely one-at-a-time, after respawning a worker the
+  daemon **waits for the replacement to report ready** (its activation loop is up
+  and leasing) before draining the next one — a bare spawn/PID is not readiness,
+  so on the normal readiness path a slow replacement can never leave two workers
+  down at once. That wait is
+  **bounded** (`NANO_SUPERVISOR_RELOAD_READY_TIMEOUT_MS`, default 30s): a
+  never-ready replacement can't wedge the roll — the daemon advances anyway. That
+  timeout fallback is the one exception to the guarantee above: when a
+  replacement never reports ready the daemon drains the next worker while the
+  previous one is still unready, so **two (or more) workers can be temporarily
+  unavailable** until the slow replacement catches up. This
+  is a *fleet-level* guarantee: a worker is drained **before** its replacement
+  spawns, so a **single-worker fleet** (or a job type served by only one worker)
+  does lose that capacity for the drain+boot window. Run more than
+  one worker for a type if you need it served continuously across a reload.
+- It **never kills in-flight work**: a reload waits indefinitely for each
+  worker's jobs to finish (adopting new code is never worth losing a running
+  job). The command **streams progress** and **Ctrl-C detaches** — the daemon
+  keeps rolling in the background (rerun `supervisor status` to check). A reload
+  is refused while another is already in progress.
+- It **stops the roll on a failed reload** (a canary): if a worker's replacement
+  crashes, fails to spawn, or is swapped out from under the roll — i.e. it has no
+  confirmed serving child — the daemon aborts the remaining pass rather than drain
+  the next worker on top of that gap (which would both break one-at-a-time and
+  risk rolling a broken replacement across the whole fleet). The remaining workers
+  are reported **skipped** and the terminal frame reports a partial failure
+  (`ok:false`), so automation sees it. A readiness *timeout* on a still-live
+  replacement is **not** a failure — it counts as reloaded and the roll continues.
+- `reload [target]` defaults to the whole fleet; pass a worker id or profile to
+  reload just those. `workforce reload` rolls only the workers a manifest owns.
+- **Not supported on Windows.** The graceful drain relies on `SIGUSR2` to quiesce
+  each worker, which Windows cannot deliver (Node maps a non-zero signal there to
+  a forceful, SIGKILL-like termination, so the child's drain handler never fires).
+  The daemon therefore **rejects `supervisor reload` / `workforce reload` on
+  Windows** rather than hang or hard-kill in-flight work — use
+  `supervisor restart <target>`, or a full `supervisor stop` + `start`, to adopt
+  new code there.
+- **Scope — workers, not the daemon.** A reload adopts all **worker-side** code
+  (job running, agent instances, git/container provisioning, the agentic
+  connection, the Effect runtime workers load — the bulk of the harness). The
+  supervisor **daemon** keeps running the code it started with: its workers are
+  its children and watch its pid, so re-exec'ing the daemon would take the fleet
+  down with it. To adopt new **supervisor** code, do a full restart
+  (`c8ctl nano supervisor stop && c8ctl nano supervisor start`) — a rare event,
+  since the daemon is a thin process manager. `supervisor status` shows an
+  `on disk:` line flagging "update available" whenever the code on disk has
+  advanced past the running daemon, so you know when a reload (or restart) is
+  worthwhile.
+
 ### Surviving SSH logout: `supervisor install` / `uninstall`
 
 On **macOS**, a supervisor started over SSH is bound to your SSH login session's
@@ -1216,6 +1285,7 @@ c8ctl nano workforce list                 # print the manifest (+ --json)
 c8ctl nano workforce start                # ensure the daemon is up, then reconcile
 c8ctl nano workforce status               # desired vs actual, per worker (+ --json)
 c8ctl nano workforce stop                 # remove this manifest's workers (+ stop an empty daemon)
+c8ctl nano workforce reload               # hot-adopt new code into this manifest's workers (rolling, zero downtime)
 c8ctl nano workforce remove qwen          # drop an entry ("all" clears the manifest)
 ```
 

package/agent-instance.mjs

@@ -19,6 +19,8 @@
 // append an AgentInstance must NEVER crash the harness or change `job.complete`
 // behaviour — the AgentInstance lifecycle is orthogonal to job completion.
 
+import { hostname } from 'node:os';
+
 import { sessionAcp as defaultSessionAcp } from './agentic.mjs';
 
 // The two AgentInstance surfaces we call on the host SDK client. A client missing
@@ -296,6 +298,49 @@ export function deriveAgentDefinition({ profile, envelope } = {}) {
   return { model, provider, systemPrompt };
 }
 
+// #243: marker discriminating the provenance blob inside a CONFIGURATION turn's
+// `content[]` from an ordinary message/tool OBJECT block. Versioned so a consumer can
+// evolve the shape without ambiguity.
+export const PROVENANCE_KIND = 'nanobpm.provenance/v1';
+
+/**
+ * #243: build the parity-safe provenance content block for the opening CONFIGURATION
+ * turn.
+ *
+ * Camunda's AgentInstance schema pins the CONFIGURATION `definition` to
+ * model/provider/systemPrompt (no metadata/attributes field), and nanobpmn promises
+ * parity — so producer-invented top-level fields are off-limits. BUT a history item's
+ * `content[]` is a discriminated union that already includes an `OBJECT` variant
+ * (`{ contentType: 'OBJECT', object: <arbitrary JSON> }`) — the SAME shape the producer
+ * already emits for a structured tool result (`contentForResult`). Ride it to attribute
+ * a run to the agent harness (`agentName`), the nano runtime (`runtimeVersion` — the
+ * plugin `package.json` version, which is one and the same as the nano supervisor
+ * version), and, best-effort, the underlying agent CLI (`agentCliVersion`), WITHOUT
+ * diverging from the Camunda API.
+ *
+ * Returns `null` when no substantive identity field is present, so a bare `host`/`pid`
+ * (diagnostics only) never emits a noisy content block.
+ *
+ * @param {object} [p]
+ * @param {object} [p.profile]         Worker profile (`name` → `agentName`).
+ * @param {string} [p.runtimeVersion]  Nano plugin/supervisor version (`pluginVersion`).
+ * @param {string} [p.agentCliVersion] Best-effort underlying-CLI version (may be blank).
+ * @param {string} [p.host]            Host name (diagnostic).
+ * @param {number} [p.pid]             Worker pid (diagnostic).
+ * @returns {{ contentType: 'OBJECT', object: object } | null}
+ */
+export function buildProvenanceContent({ profile, runtimeVersion, agentCliVersion, host, pid } = {}) {
+  const object = { kind: PROVENANCE_KIND };
+  if (isNonBlank(profile?.name)) object.agentName = String(profile.name);
+  if (isNonBlank(runtimeVersion)) object.runtimeVersion = String(runtimeVersion);
+  if (isNonBlank(agentCliVersion)) object.agentCliVersion = String(agentCliVersion);
+  if (isNonBlank(host)) object.host = String(host);
+  if (Number.isInteger(pid) && pid > 0) object.pid = pid;
+  // Only agent/runtime identity justifies a block; host/pid alone are diagnostics.
+  if (!(object.agentName || object.runtimeVersion || object.agentCliVersion)) return null;
+  return { contentType: 'OBJECT', object };
+}
+
 // Map the ACP classifier's message role to the AgentHistory role enum. ACP has no
 // distinct REASONING role, so a `reasoning` chunk folds into ASSISTANT.
 function historyRole(acpRole) {
@@ -396,6 +441,15 @@ export function createAgentInstanceProducer(opts = {}) {
     logger = console,
     now = () => Date.now(),
     sessionAcp = defaultSessionAcp,
+    // #243: durable-transcript provenance for the opening CONFIGURATION turn. The nano
+    // runtime version (== the supervisor version) and the agent harness name/CLI version
+    // ride a parity-safe OBJECT content block (see `buildProvenanceContent`). All are
+    // best-effort/optional — a blank value simply omits its field, and if none are
+    // present no provenance block is emitted. `host`/`pid` default to this process.
+    runtimeVersion = '',
+    agentCliVersion = '',
+    host = hostname(),
+    pid = process.pid,
     createRetryBaseMs = DEFAULT_CREATE_RETRY_BASE_MS,
     createRetryMaxMs = DEFAULT_CREATE_RETRY_MAX_MS,
     preMintBufferMax = DEFAULT_PRE_MINT_BUFFER_MAX,
@@ -743,11 +797,17 @@ export function createAgentInstanceProducer(opts = {}) {
   // Build the opening CONFIGURATION turn from the concrete runtime definition.
   const buildConfigTurn = () => {
     const def = deriveAgentDefinition({ profile, envelope });
+    // #243: a parity-safe provenance OBJECT (agent name, nano runtime/supervisor
+    // version, best-effort agent-CLI version) rides the CONFIGURATION turn's content[]
+    // — the same OBJECT content variant the producer already emits for tool results —
+    // so no field is invented on the Camunda-pinned CONFIGURATION definition. Omitted
+    // entirely when no substantive identity is available.
+    const provenance = buildProvenanceContent({ profile, runtimeVersion, agentCliVersion, host, pid });
     const configTurn = {
       historyItemId: `configuration:${elementInstanceKey}`,
       loopIteration: 1,
       role: 'CONFIGURATION',
-      content: [],
+      content: provenance ? [provenance] : [],
       producedAt: iso(),
       model: def.model,
       provider: def.provider,