c8ctl-plugin-nano 1.61.2 → 1.62.0

package/README.md

@@ -236,11 +236,14 @@ How it works and why it needs no wiring:
   agent jobs at all, it and the app are already on the same engine, so *what
   agent job types exist* is answerable from that engine alone — **no cross-machine
   app discovery, no app enrol endpoint, no channel connection**.
-- **Agent-task header filter.** Not every service task is an agent task —
+- **Agent-task marker filter.** Not every service task is an agent task —
   connectors and record-keepers (e.g. `pr.record-plan`) are plain workers.
-  `--auto` keeps only leaves whose service task carries an
-  **`io.nanobpm.agentTask.`** task header (e.g. `senior:plan` carries
-  `io.nanobpm.agentTask.task.prompt`; a record-keeper does not).
+  `--auto` keeps only leaves whose service task carries the single-convention
+  external-agent marker **`<zeebe:agentDefinition agentType="external" />`** (the
+  same marker every external agent task already declares). A task can **opt out**
+  of `--auto` with `<zeebe:property name="io.nanobpm.agentTask.autoSubscribe"
+  value="false" />` — it is then served only by explicit `--job-type`/profile
+  subscription.
 - **One poller per agent job type, reconciled on change.** It opens one poller
   per agent job type and re-reads the engine periodically, adding pollers for
   newly deployed agent processes and draining pollers for undeployed ones — the

package/agent-instance.mjs

@@ -1263,6 +1263,50 @@ export function createAgentInstanceProducer(opts = {}) {
       await queue;
     },
 
+    /**
+     * Abort/discard teardown for a run ABANDONED during setup (issue #222). Unlike
+     * `complete()` this does NOT drive a terminal COMPLETED update and — critically —
+     * does NOT make a last-chance create attempt: the run is being yielded for retry,
+     * so minting an instance for it would be an orphaned side effect. It makes the
+     * producer permanently INERT so no late create can mint after the runner has
+     * returned from the abort path — closing the window the suppressed advisory flags,
+     * where a retry-pending producer (`active === false`) whose in-flight/armed
+     * `createAgentInstance` settles late would still mint a durable instance:
+     *   - `finalized = true` gates `ingest()` (drops late ACP frames), `maybeStartCreate()`
+     *     (no hot-path retry), AND `doCreate()`'s latch guard (a late create success is
+     *     dropped rather than latching a key + replaying the pre-mint buffer);
+     *   - bumping `createGen` neutralises an already in-flight attempt via the SAME
+     *     identity guard `retireCreate` uses, so its late settle is dropped even before
+     *     `finalized` is read, and frees the `creating` slot;
+     *   - the pre-mint buffer is released (it can never be replayed now);
+     *   - queued appends against an ALREADY-minted instance are drained best-effort so
+     *     they are not lost, without transitioning status.
+     * Idempotent and best-effort; never throws. Safe to call for BOTH an active
+     * producer and a retry-pending one (the two cases the advisory calls out).
+     */
+    async discard() {
+      if (finalized) {
+        try { await this.drain(); } catch { /* best effort */ }
+        return;
+      }
+      finalized = true;
+      // Neutralise any in-flight create: bump the identity past the owning attempt so
+      // its late resolve/reject is dropped by doCreate's `gen !== createGen` guard, and
+      // free the slot (a retired attempt's own finally is a no-op once we've bumped).
+      createGen += 1;
+      creating = null;
+      creatingGen = 0;
+      creatingFinal = false;
+      // The pre-mint buffer can never be replayed once finalized — release it (and its
+      // counters) rather than pin it for the life of a still-hung uncancellable POST.
+      preMintBuffer.length = 0;
+      preMintBufferBytes = 0;
+      preMintDropped = 0;
+      // Flush appends already queued against a minted instance (best effort); no
+      // terminal update — the run was abandoned, not successfully completed.
+      try { await this.drain(); } catch { /* best effort */ }
+    },
+
     /**
      * End the AgentInstance lifecycle. Flushes any pending message turn, drains the
      * append queue, then — only on a SUCCESSFUL job end (`ok`) — updates the instance

package/agentic.mjs

@@ -97,8 +97,10 @@ export * as sessionAcp from '@nanobpm/agentic/session/acp';
 // `httpC8RestReader` to enumerate deployed process definitions and read each
 // one's BPMN XML straight from the engine the worker already talks to — the
 // zero-config enrolment source. The header-filter that narrows those leaves to
-// *agent* job types lives in the plugin (`scanAgentTaskLeaves`), extending the
-// package's type/element/process-only scanner with a `zeebe:taskHeaders` read.
+// *agent* job types lives in the plugin (`scanAgentTaskLeaves`), narrowing the
+// package's type/element/process scanner to leaves carrying the single-convention
+// external-agent marker (`<zeebe:agentDefinition agentType="external">`, issue
+// #235) and dropping any opted out via `io.nanobpm.agentTask.autoSubscribe="false"`.
 // ---------------------------------------------------------------------------
 export * as demand from '@nanobpm/agentic/demand';