c8ctl-plugin-nano 1.73.1 → 1.73.2

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.
Files changed (2) hide show
  1. package/agent-instance.mjs +46 -60
  2. package/package.json +8 -8
@@ -62,11 +62,13 @@ const DEFAULT_CREATE_RETRY_MAX_MS = 30000;
62
62
  const DEFAULT_PRE_MINT_BUFFER_MAX = 1000;
63
63
  const DEFAULT_PRE_MINT_BUFFER_MAX_BYTES = 8_000_000;
64
64
 
65
- // A terminal COMPLETED update is driven directly (not via the best-effort append
66
- // queue) and RETRIED a bounded number of times: on a successful job end the caller
67
- // settles the job the instant complete() returns, so there is no reactivation to
68
- // retry a rejected terminal transition — a single swallowed failure would strand the
69
- // instance non-terminal forever (issue #230).
65
+ // On a successful job end, complete() drains pending appends and drives a final
66
+ // `status: 'IDLE'` update directly (not via the best-effort append queue) and
67
+ // RETRIES transient failures a bounded number of times. Per Camunda 8.10 and
68
+ // nanobpmn parity (#274), AgentInstanceUpdateStatusEnum is
69
+ // { IDLE, THINKING, TOOL_CALLING, TOOL_DISCOVERY } — UPDATE never accepts
70
+ // COMPLETED (that returns HTTP 422); the engine itself completes all active
71
+ // AgentInstances when the owning process instance ends.
70
72
  const DEFAULT_TERMINAL_RETRY_MAX = 3;
71
73
 
72
74
  // Bound on complete()'s last-chance create attempt (issue #230). The harness awaits
@@ -261,13 +263,13 @@ export function describeSdkError(err) {
261
263
  }
262
264
 
263
265
  /**
264
- * True when an HTTP status marks a PERMANENT rejection of the terminal
265
- * status→COMPLETED update (issue #275): a 4xx (a stale lease fence, an invalid
266
- * transition, a 0-turns husk the engine refuses to terminalize) will not succeed
267
- * on a blind retry, so the producer stops retrying it immediately instead of
268
- * burning the remaining attempts against a dying lease. 5xx / network / timeout
269
- * failures are potentially transient and still retry. `null`/unknown statuses are
270
- * treated as transient (retry) — fail-safe toward recovery, not toward giving up.
266
+ * True when an HTTP status marks a PERMANENT rejection of the final
267
+ * status→IDLE update (issue #275, #274): a 4xx (a stale lease fence, an invalid
268
+ * transition, a contract error like 422) will not succeed on a blind retry, so
269
+ * the producer stops retrying it immediately instead of burning the remaining
270
+ * attempts against a dying lease. 5xx / network / timeout failures are potentially
271
+ * transient and still retry. `null`/unknown statuses are treated as transient
272
+ * (retry) — fail-safe toward recovery, not toward giving up.
271
273
  *
272
274
  * Two 4xx statuses are the exception — NOT permanent, because a retry can still
273
275
  * succeed:
@@ -633,7 +635,8 @@ function contentForResult(result) {
633
635
  * - `ingest(rawUpdate)` — feed one raw ACP `session/update` (non-blocking; the SDK
634
636
  * append is enqueued so the ACP hot path never blocks).
635
637
  * - `complete(ok)` — drain pending appends, then (on a successful job end) update
636
- * the instance status to COMPLETED. `job.complete` is unchanged and orthogonal.
638
+ * the instance status to IDLE (the engine owns COMPLETED when the process
639
+ * instance ends; issue #274). `job.complete` is unchanged and orthogonal.
637
640
  *
638
641
  * @param {object} opts
639
642
  * @param {object} opts.camunda Host SDK client (createAgentInstance/updateAgentInstance).
@@ -1867,8 +1870,10 @@ export function createAgentInstanceProducer(opts = {}) {
1867
1870
  /**
1868
1871
  * End the AgentInstance lifecycle. Flushes any pending message turn, drains the
1869
1872
  * append queue, then — only on a SUCCESSFUL job end (`ok`) — updates the instance
1870
- * status to COMPLETED (there is no separate completeAgentInstance verb). On a
1871
- * failed run the instance is left non-terminal so a retry/reactivation continues
1873
+ * status to `IDLE` (a valid update-status; Camunda 8.10 and nanobpmn reject
1874
+ * `COMPLETED` on UPDATE with HTTP 422 because `COMPLETED` is engine-owned and
1875
+ * written when the owning process instance ends, #274). On a failed run the
1876
+ * instance is left at its last active status so a retry/reactivation continues
1872
1877
  * the same instance. Best-effort; never throws; `job.complete` is unaffected.
1873
1878
  */
1874
1879
  async complete(ok = true) {
@@ -1986,36 +1991,26 @@ export function createAgentInstanceProducer(opts = {}) {
1986
1991
  elementInstanceKey,
1987
1992
  jobKey,
1988
1993
  jobLease: leaseToken,
1989
- status: 'COMPLETED',
1994
+ status: 'IDLE',
1990
1995
  }),
1991
1996
  finalizeTimeoutMs,
1992
1997
  setTimer,
1993
1998
  );
1994
1999
  } catch (err) {
1995
- // This serialized enqueue IS the terminal transition on the drain-timeout
1996
- // path — the only actor that can still terminalize the instance here. The
1997
- // generic enqueue() catch would swallow it at debug with just err.message,
1998
- // losing the HTTP status/body/correlation on the very path that already
1999
- // warned reconciliation may be needed (issue #230). Emit the SAME shaped
2000
- // status/body/correlation warning the direct terminal-retry path uses
2001
- // (with its manual-reconciliation outcome) before it is swallowed.
2002
2000
  const d = describeSdkError(err);
2003
2001
  logger?.warn?.(
2004
- `AgentInstance ${agentInstanceKey}: serialized terminal COMPLETED update ` +
2002
+ `AgentInstance ${agentInstanceKey}: serialized final IDLE update ` +
2005
2003
  `${err?.__nanoTimeout ? `timed out (bounded at ${finalizeTimeoutMs}ms)` : 'failed'} — ` +
2006
- `status=${d.status ?? 'n/a'} body=${d.body ?? 'n/a'} message=${d.message ?? 'n/a'}; ` +
2007
- `MANUAL RECONCILIATION REQUIRED — the drain did not catch up and the job has ` +
2008
- `settled with no reactivation to retry this transition ${correlation()}.`,
2004
+ `status=${d.status ?? 'n/a'} body=${d.body ?? 'n/a'} message=${d.message ?? 'n/a'} ` +
2005
+ `${correlation()}.`,
2009
2006
  );
2010
2007
  }
2011
2008
  });
2012
2009
  logger?.warn?.(
2013
2010
  `AgentInstance ${agentInstanceKey}: history drain did not settle within ` +
2014
- `${finalizeTimeoutMs}ms — terminal COMPLETED update SERIALIZED behind the ` +
2011
+ `${finalizeTimeoutMs}ms — final IDLE update SERIALIZED behind the ` +
2015
2012
  `pending appends (best-effort, ordered) rather than racing them; its outcome ` +
2016
- `is not observed here and the job settles on return, so this background write ` +
2017
- `is expected to be fence-rejected once its lease is void — MANUAL ` +
2018
- `RECONCILIATION REQUIRED (terminal status NOT confirmed) ${correlation()}.`,
2013
+ `is not observed here and the job settles on return ${correlation()}.`,
2019
2014
  );
2020
2015
  // Emit the turn counter on this path too (issue #229/#232): the aggregate
2021
2016
  // append timeout is the hardest transcript failure to diagnose, so record how
@@ -2029,7 +2024,7 @@ export function createAgentInstanceProducer(opts = {}) {
2029
2024
  `so far over ${mins}m (drain still pending — count unobserved)` +
2030
2025
  `${appendsDropped > 0 ? `, ${appendsDropped} turn(s) DROPPED (append backlog cap — transcript truncated)` : ''}, ` +
2031
2026
  `${messageChunksDropped > 0 ? `${messageChunksDropped} streaming chunk(s) DROPPED (message buffer cap), ` : ''}` +
2032
- `terminal COMPLETED update serialized behind pending appends.`,
2027
+ `final IDLE update serialized behind pending appends.`,
2033
2028
  );
2034
2029
  }
2035
2030
  return;
@@ -2037,25 +2032,27 @@ export function createAgentInstanceProducer(opts = {}) {
2037
2032
  let completedOk = false;
2038
2033
  let terminalErr = null;
2039
2034
  let terminalTimedOut = false;
2040
- // Issue #275: latches when the terminal update was rejected with a PERMANENT
2035
+ // Issue #275: latches when the final status update was rejected with a PERMANENT
2041
2036
  // (4xx) status — surfaced in the diagnostics so a fence/validation rejection
2042
- // (the stuck-instance case) is distinguishable from a transient 5xx/outage.
2037
+ // is distinguishable from a transient 5xx/outage.
2043
2038
  let terminalPermanent = false;
2044
2039
  const terminalAttempts = Math.max(1, terminalRetryMax);
2045
2040
  if (ok) {
2046
2041
  for (let attempt = 1; attempt <= terminalAttempts; attempt += 1) {
2047
2042
  try {
2048
- // BOUND each terminal update (finalizeTimeoutMs). Like the create calls,
2043
+ // BOUND each final status update (finalizeTimeoutMs). Like the create calls,
2049
2044
  // the harness awaits complete() before it settles the job, so a hung
2050
2045
  // updateAgentInstance would otherwise hold the lease until it expires and
2051
2046
  // stall settlement during an engine outage (issue #230).
2047
+ // Issue #274: send `IDLE` (valid AgentInstanceUpdateStatusEnum), never
2048
+ // `COMPLETED` — the engine owns `COMPLETED` on process-instance end.
2052
2049
  await callWithin(
2053
2050
  camunda[SDK_UPDATE]({
2054
2051
  agentInstanceKey,
2055
2052
  elementInstanceKey,
2056
2053
  jobKey,
2057
2054
  jobLease: leaseToken,
2058
- status: 'COMPLETED',
2055
+ status: 'IDLE',
2059
2056
  }),
2060
2057
  finalizeTimeoutMs,
2061
2058
  setTimer,
@@ -2070,10 +2067,9 @@ export function createAgentInstanceProducer(opts = {}) {
2070
2067
  // burns another finalizeTimeoutMs against the lease, so STOP retrying on a
2071
2068
  // timeout (the underlying call is left to settle in the background). A
2072
2069
  // plain rejection is potentially transient, so those still retry — EXCEPT
2073
- // a permanent 4xx (issue #275): a 422/409/400 terminal rejection (a stale
2074
- // lease fence, an invalid transition, a 0-turns husk the engine refuses to
2075
- // terminalize) will not succeed on a blind retry, so break immediately
2076
- // rather than burn the remaining attempts against a dying lease.
2070
+ // a permanent 4xx (issue #275/#274): a 422/409/400 rejection will not
2071
+ // succeed on a blind retry, so break immediately rather than burn the
2072
+ // remaining attempts against a dying lease.
2077
2073
  if (err && err.__nanoTimeout) {
2078
2074
  terminalTimedOut = true;
2079
2075
  break;
@@ -2087,39 +2083,29 @@ export function createAgentInstanceProducer(opts = {}) {
2087
2083
  }
2088
2084
  const terminalOk = ok && completedOk;
2089
2085
  if (ok && !completedOk) {
2090
- // The terminal transition never confirmed (every retry rejected, or a hung
2091
- // request was bounded out). The job settles now with no reactivation to try
2092
- // again, so this is NOT self-healing — surface the SDK error details and flag
2093
- // that manual reconciliation is required (issue #230).
2094
2086
  logger?.warn?.(
2095
- `AgentInstance ${agentInstanceKey}: terminal status update to COMPLETED ` +
2087
+ `AgentInstance ${agentInstanceKey}: final status update to IDLE ` +
2096
2088
  `${terminalTimedOut
2097
2089
  ? `timed out (bounded at ${finalizeTimeoutMs}ms)`
2098
2090
  : terminalPermanent
2099
2091
  ? `rejected permanently (HTTP ${terminalErr?.status ?? '4xx'}) — not retried`
2100
2092
  : `failed after ${terminalAttempts} attempt(s)`} — ` +
2101
2093
  `status=${terminalErr?.status ?? 'n/a'} ` +
2102
- `body=${terminalErr?.body ?? 'n/a'} message=${terminalErr?.message ?? 'n/a'}; ` +
2103
- `MANUAL RECONCILIATION REQUIRED — the job settles now with no reactivation to retry ` +
2104
- `this transition ${correlation()}.`,
2094
+ `body=${terminalErr?.body ?? 'n/a'} message=${terminalErr?.message ?? 'n/a'} ` +
2095
+ `${correlation()}.`,
2105
2096
  );
2106
2097
  }
2107
- // #229/#232 turn counter — "N turn(s) appended over Xm, <transition>" — so the
2108
- // 0-turns husk ("created but nothing ingested") is distinguishable from a healthy
2109
- // run at a glance. Render the HONEST terminal transition: only claim
2110
- // `status→COMPLETED` when the terminal update actually confirmed (terminalOk).
2111
- // The `!ok` (failed job end) path IS reactivatable, so it says so; but the
2112
- // terminalOk-false path is a SUCCESSFUL job end whose COMPLETED update failed —
2113
- // the caller settles the job the instant complete() returns, so there is NO
2114
- // reactivation to continue it (that would contradict the manual-reconciliation
2115
- // warning). State only that it was left non-terminal and needs reconciliation.
2098
+ // #229/#232/#274 turn counter — "N turn(s) appended over Xm, <transition>" —
2099
+ // render the HONEST final status transition: `status→IDLE` when confirmed
2100
+ // (the engine owns COMPLETED when the process instance ends), or report the
2101
+ // failed IDLE update if it was rejected.
2116
2102
  const elapsedMs = activatedAt ? Math.max(0, now() - activatedAt) : 0;
2117
2103
  const mins = (elapsedMs / 60000).toFixed(1);
2118
2104
  const transition = !ok
2119
- ? 'left non-terminal (retry/reactivation continues it)'
2105
+ ? 'left active (retry/reactivation continues it)'
2120
2106
  : terminalOk
2121
- ? 'status→COMPLETED'
2122
- : 'COMPLETED update FAILED — left non-terminal; manual reconciliation required (no reactivation on a settled job)';
2107
+ ? 'status→IDLE (engine completes on process end)'
2108
+ : 'IDLE update FAILED (engine completes on process end)';
2123
2109
  // Surface the aggregate append backlog DROP count (issue #230): the warn-once
2124
2110
  // backlog log only says drops STARTED — the operator can't quantify the loss or
2125
2111
  // tell it apart from an engine append failure without the final tally. Fold it
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "c8ctl-plugin-nano",
3
- "version": "1.73.1",
3
+ "version": "1.73.2",
4
4
  "type": "module",
5
5
  "description": "c8ctl plugin to start, inspect, and stop a local Nano BPM (nanobpmn) cluster",
6
6
  "main": "c8ctl-plugin.js",
@@ -76,12 +76,12 @@
76
76
  },
77
77
  "optionalDependencies": {
78
78
  "node-pty": "^1.0.0",
79
- "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.73.1",
80
- "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.73.1",
81
- "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.73.1",
82
- "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.73.1",
83
- "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.73.1",
84
- "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.73.1",
85
- "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.73.1"
79
+ "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.73.2",
80
+ "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.73.2",
81
+ "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.73.2",
82
+ "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.73.2",
83
+ "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.73.2",
84
+ "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.73.2",
85
+ "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.73.2"
86
86
  }
87
87
  }