@alpacakit/agents 0.1.0-beta.20 → 0.1.0-beta.24

package/README.md

@@ -65,6 +65,66 @@ for await (const event of handle.events) {
 const result = await handle; // await handle === await handle.result
 ```
 
+### Controlled child lifecycle
+
+Embedding hosts that need durable custody of CLI workers create a
+`ControlledExec` and provide it with the run-scoped lifecycle. `beforeExec`
+receives an opaque `{ pid, processStartToken }` identity before the worker
+executes. `afterTermination` runs only after the supervisor has proved the
+whole controlled process group absent and output has reached EOF; the signed
+absence is released only after that callback succeeds.
+
+```ts
+import { createControlledExec } from "@alpacakit/agents";
+
+const controlledExec = createControlledExec({
+  runtimeDirectory: "/run/my-host/agents",
+  termination: {
+    termGraceMs: 5_000,
+    killProbeTimeoutMs: 5_000,
+    probeIntervalMs: 50,
+  },
+});
+
+await runtime.agent("codex").run({
+  prompt,
+  workspace,
+  resources: {
+    childProcess: {
+      exec: controlledExec,
+      lifecycle: {
+        beforeExec: async (identity) => {
+          await processRegistry.open(identity);
+        },
+        afterTermination: async ({ identity, proof }) => {
+          await processRegistry.close({ identity, proof });
+        },
+      },
+    },
+  },
+});
+```
+
+The resource is reused for structured-repair and fleet-failover spawns. When it
+is absent, execution is ordinary unmanaged `Exec`; when present, the runtime
+uses only the supplied `ControlledExec`. Abort and early completion request
+termination through that controller exactly once. The supervisor owns signal
+escalation and reports either authenticated absence or a typed unkillable
+reason, so the runtime never falls back to direct process signaling.
+
+A naturally completed worker includes its exact `{ code, signal }` as
+`workerExit`. Abort-driven termination may complete with `workerExit: null`;
+pre-exec lifecycle failure rejects `spawn` before a process handle is returned.
+If a host restarts after persisting an identity, it can call
+`controlledExec.recovery.recover(identity, { afterTermination })`; absence is
+released only after the same lifecycle callback succeeds. Controlled execution
+is supported on Linux and macOS and fails closed on unsupported platforms or
+an insecure runtime directory.
+
+Each recovery call performs one authenticated termination convergence. A
+typed `pending` result invokes no lifecycle callback; the host owns the
+cancellable retry cadence and calls `recover` again when appropriate.
+
 ## Structured output
 
 Any Standard Schema validator (zod v4 etc.) works. Repair happens within

package/dist/agents/claude.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/agents/claude.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA6CH,OAAO,EACL,KAAK,cAAc,EAEpB,MAAM,uBAAuB,CAAC;AAM/B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAG/D,eAAO,MAAM,yBAAyB,sBAAsB,CAAC;AAC7D,eAAO,MAAM,sBAAsB,sBAAsB,CAAC;AAwJ1D;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,cAAc,CA0CvD;AA8RD,wBAAgB,MAAM,IAAI,eAAe,CAAC,QAAQ,CAAC,CAyDlD"}
+{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/agents/claude.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA6CH,OAAO,EACL,KAAK,cAAc,EAEpB,MAAM,uBAAuB,CAAC;AAM/B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAG/D,eAAO,MAAM,yBAAyB,sBAAsB,CAAC;AAC7D,eAAO,MAAM,sBAAsB,sBAAsB,CAAC;AAwJ1D;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,cAAc,CA0CvD;AAoSD,wBAAgB,MAAM,IAAI,eAAe,CAAC,QAAQ,CAAC,CAyDlD"}

package/dist/agents/claude.js

@@ -258,6 +258,7 @@ function parseSkillMetadata(markdown) {
 function skillListReadError(target, cause) {
     return new AgentError({
         code: AGENT_ERROR_CODE.failed,
+        classification: AgentError.agentFailure(AGENT_ERROR_CODE.failed),
         message: `Could not read installed claude skills: ${target}`,
         data: { exitCode: null, stdoutTail: null, stderrTail: null },
         cause,
@@ -341,6 +342,7 @@ async function assertSkillDirectory(directory) {
     }
     throw new AgentError({
         code: AGENT_ERROR_CODE.invalidInput,
+        classification: AgentError.agentFailure(AGENT_ERROR_CODE.invalidInput),
         message: `Skill source does not contain ${SKILL_MARKDOWN}: ${directory}`,
         data: { reason: `missing ${SKILL_MARKDOWN}` },
     });
@@ -363,6 +365,7 @@ async function installClaudePlugin(ctx, source, options) {
         // honest, silently ignoring the request is not.
         throw new AgentError({
             code: AGENT_ERROR_CODE.invalidInput,
+            classification: AgentError.agentFailure(AGENT_ERROR_CODE.invalidInput),
             message: "Claude plugin installation cannot overwrite an installed plugin",
             data: { reason: "plugin install does not support overwrite" },
         });

package/dist/agents/codex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codex.d.ts","sourceRoot":"","sources":["../../src/agents/codex.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAwCH,OAAO,EAAE,KAAK,cAAc,EAAqB,MAAM,uBAAuB,CAAC;AAG/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAG/D,eAAO,MAAM,kBAAkB,eAAe,CAAC;AAC/C,eAAO,MAAM,qBAAqB,mBAAmB,CAAC;AA6GtD;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,CAepD;AAyMD,wBAAgB,KAAK,IAAI,eAAe,CAAC,OAAO,CAAC,CAoEhD"}
+{"version":3,"file":"codex.d.ts","sourceRoot":"","sources":["../../src/agents/codex.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAwCH,OAAO,EAAE,KAAK,cAAc,EAAqB,MAAM,uBAAuB,CAAC;AAG/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAG/D,eAAO,MAAM,kBAAkB,eAAe,CAAC;AAC/C,eAAO,MAAM,qBAAqB,mBAAmB,CAAC;AA6GtD;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,CAepD;AAiND,wBAAgB,KAAK,IAAI,eAAe,CAAC,OAAO,CAAC,CAoEhD"}

package/dist/agents/codex.js

@@ -161,6 +161,7 @@ async function installCodexPlugin(ctx, source, options) {
         // silently ignoring the request is not (same contract as claude).
         throw new AgentError({
             code: AGENT_ERROR_CODE.invalidInput,
+            classification: AgentError.agentFailure(AGENT_ERROR_CODE.invalidInput),
             message: "Codex plugin installation cannot overwrite an installed plugin",
             data: { reason: UNSUPPORTED_PLUGIN_OVERWRITE_REASON },
         });
@@ -211,6 +212,7 @@ function assertCodexStdioMcpSupported(spec, options) {
     if (spec.cwd !== null) {
         throw new AgentError({
             code: AGENT_ERROR_CODE.invalidInput,
+            classification: AgentError.agentFailure(AGENT_ERROR_CODE.invalidInput),
             message: "Codex stdio MCP registration does not support server cwd",
             data: { reason: UNSUPPORTED_CWD_REASON },
         });
@@ -223,6 +225,7 @@ function assertCodexMcpScopeSupported(scope) {
     const reason = [UNSUPPORTED_SCOPE_REASON_PREFIX, scope].join(": ");
     throw new AgentError({
         code: AGENT_ERROR_CODE.invalidInput,
+        classification: AgentError.agentFailure(AGENT_ERROR_CODE.invalidInput),
         message: `Codex MCP registration does not support scope "${scope}"`,
         data: { reason },
     });
@@ -249,6 +252,7 @@ function installOutcomeFromCodexPlugin(name, result) {
     if (result.appsNeedingAuth.length > 0) {
         throw new AgentError({
             code: AGENT_ERROR_CODE.auth,
+            classification: AgentError.agentFailure(AGENT_ERROR_CODE.auth),
             message: CODEX_PLUGIN_AUTH_REQUIRED_MESSAGE,
             data: {
                 reason: AUTH_FAILURE_REASON.notLoggedIn,

package/dist/agents/openai-compatible/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/agents/openai-compatible/config.ts"],"names":[],"mappings":"AAKA,OAAO,EAEL,KAAK,WAAW,EACjB,MAAM,4BAA4B,CAAC;AAMpC,OAAO,KAAK,EAEV,sBAAsB,EACtB,8BAA8B,EAC/B,MAAM,YAAY,CAAC;AAmBpB,MAAM,WAAW,8BAA8B;IAC7C,SAAS,CAAC,EAAE,SAAS,MAAM,EACzB,MAAM,EAAE,sBAAsB,CAAC,EAAE,CAAC,GACjC,sBAAsB,CAAC,EAAE,CAAC,CAAC;IAC9B,OAAO,CACL,MAAM,EAAE,sBAAsB,EAC9B,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACpC,8BAA8B,CAAC;IAClC,YAAY,CACV,MAAM,EAAE,sBAAsB,EAC9B,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACpC,SAAS,WAAW,EAAE,CAAC;CAC3B;AAED,qBAAa,qCACX,YAAW,8BAA8B;IAEzC,SAAS,CAAC,EAAE,SAAS,MAAM,EACzB,MAAM,EAAE,sBAAsB,CAAC,EAAE,CAAC,GACjC,sBAAsB,CAAC,EAAE,CAAC;IAW7B,OAAO,CACL,MAAM,EAAE,sBAAsB,EAC9B,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACpC,8BAA8B;IAyCjC,YAAY,CACV,MAAM,EAAE,sBAAsB,EAC9B,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACpC,SAAS,WAAW,EAAE;IASzB,OAAO,CAAC,uBAAuB;IAuB/B,OAAO,CAAC,gBAAgB;CAYzB;AAED,eAAO,MAAM,qCAAqC,uCACL,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/agents/openai-compatible/config.ts"],"names":[],"mappings":"AAKA,OAAO,EAEL,KAAK,WAAW,EACjB,MAAM,4BAA4B,CAAC;AAMpC,OAAO,KAAK,EAEV,sBAAsB,EACtB,8BAA8B,EAC/B,MAAM,YAAY,CAAC;AAmBpB,MAAM,WAAW,8BAA8B;IAC7C,SAAS,CAAC,EAAE,SAAS,MAAM,EACzB,MAAM,EAAE,sBAAsB,CAAC,EAAE,CAAC,GACjC,sBAAsB,CAAC,EAAE,CAAC,CAAC;IAC9B,OAAO,CACL,MAAM,EAAE,sBAAsB,EAC9B,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACpC,8BAA8B,CAAC;IAClC,YAAY,CACV,MAAM,EAAE,sBAAsB,EAC9B,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACpC,SAAS,WAAW,EAAE,CAAC;CAC3B;AAED,qBAAa,qCACX,YAAW,8BAA8B;IAEzC,SAAS,CAAC,EAAE,SAAS,MAAM,EACzB,MAAM,EAAE,sBAAsB,CAAC,EAAE,CAAC,GACjC,sBAAsB,CAAC,EAAE,CAAC;IAW7B,OAAO,CACL,MAAM,EAAE,sBAAsB,EAC9B,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACpC,8BAA8B;IAyCjC,YAAY,CACV,MAAM,EAAE,sBAAsB,EAC9B,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACpC,SAAS,WAAW,EAAE;IASzB,OAAO,CAAC,uBAAuB;IA2B/B,OAAO,CAAC,gBAAgB;CAYzB;AAED,eAAO,MAAM,qCAAqC,uCACL,CAAC"}

package/dist/agents/openai-compatible/config.js

@@ -58,6 +58,7 @@ export class DefaultOpenAiCompatibleConfigResolver {
         if (!resolved.ok) {
             throw new AgentError({
                 code: AGENT_ERROR_CODE.notAvailable,
+                classification: AgentError.agentFailure(AGENT_ERROR_CODE.notAvailable),
                 message: `openaiCompatible.${label} references ${resolved.reason} environment variable: ${resolved.envName}`,
                 data: { cause: NOT_AVAILABLE_CAUSE.badConfig },
             });
@@ -65,6 +66,7 @@ export class DefaultOpenAiCompatibleConfigResolver {
         if (resolved.value.trim().length === 0) {
             throw new AgentError({
                 code: AGENT_ERROR_CODE.notAvailable,
+                classification: AgentError.agentFailure(AGENT_ERROR_CODE.notAvailable),
                 message: `openaiCompatible.${label} resolved to an empty value`,
                 data: { cause: NOT_AVAILABLE_CAUSE.badConfig },
             });
@@ -88,6 +90,7 @@ function resolveJsonTemplates(label, value, env) {
         if (!resolved.ok) {
             throw new AgentError({
                 code: AGENT_ERROR_CODE.notAvailable,
+                classification: AgentError.agentFailure(AGENT_ERROR_CODE.notAvailable),
                 message: `openaiCompatible.${label} references ${resolved.reason} environment variable: ${resolved.envName}`,
                 data: { cause: NOT_AVAILABLE_CAUSE.badConfig },
             });
@@ -139,6 +142,7 @@ function assertHttpBaseUrl(baseUrl) {
     catch {
         throw new AgentError({
             code: AGENT_ERROR_CODE.notAvailable,
+            classification: AgentError.agentFailure(AGENT_ERROR_CODE.notAvailable),
             message: `Invalid OpenAI-compatible baseUrl: ${baseUrl}`,
             data: { cause: NOT_AVAILABLE_CAUSE.badConfig },
         });
@@ -147,6 +151,7 @@ function assertHttpBaseUrl(baseUrl) {
         parsed.protocol !== HTTP_PROTOCOL.https) {
         throw new AgentError({
             code: AGENT_ERROR_CODE.notAvailable,
+            classification: AgentError.agentFailure(AGENT_ERROR_CODE.notAvailable),
             message: `Invalid OpenAI-compatible baseUrl protocol: ${parsed.protocol}`,
             data: { cause: NOT_AVAILABLE_CAUSE.badConfig },
         });

package/dist/agents/openai-compatible/fetch-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fetch-engine.d.ts","sourceRoot":"","sources":["../../../src/agents/openai-compatible/fetch-engine.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,UAAU,EAIX,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAE9D,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAEL,KAAK,+BAA+B,EACrC,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAa,8BAA8B,EAAE,MAAM,YAAY,CAAC;AA+C5E,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,WAAW,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1D;AAED,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;CAC3E;AAED,MAAM,MAAM,uCAAuC,GAAG;IACpD,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,+BAA+B,EAAE,CAAC;IAC/D,QAAQ,CAAC,WAAW,CAAC,EAAE,2BAA2B,CAAC;IACnD,QAAQ,CAAC,aAAa,CAAC,EAAE,iCAAiC,CAAC;CAC5D,CAAC;AAEF,qBAAa,2BAA4B,YAAW,sBAAsB;IACxE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6C;IACtE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA8B;IAC1D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAoC;gBAEtD,YAAY,GAAE,uCAA4C;IAUhE,YAAY,IAAI,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC;IAI9C,GAAG,CACR,MAAM,EAAE,8BAA8B,EACtC,OAAO,EAAE,kBAAkB,EAC3B,GAAG,EAAE,UAAU,GACd,QAAQ;IA+CX,OAAO,CAAC,UAAU;CAanB;AAED,qBAAa,kCACX,YAAW,2BAA2B;IAEtC,QAAQ,CAAC,WAAW,KAAwB;IAE5C,WAAW,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;CAGzD;AAED,qBAAa,wCACX,YAAW,iCAAiC;IAE5C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAIvB;IAEI,QAAQ,CACZ,QAAQ,EAAE,QAAQ,EAClB,GAAG,EAAE,UAAU,GACd,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;CAM9B;AAyID,eAAO,MAAM,6BAA6B,6BAAoC,CAAC"}
+{"version":3,"file":"fetch-engine.d.ts","sourceRoot":"","sources":["../../../src/agents/openai-compatible/fetch-engine.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,UAAU,EAIX,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAE9D,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAEL,KAAK,+BAA+B,EACrC,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAa,8BAA8B,EAAE,MAAM,YAAY,CAAC;AA+C5E,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,WAAW,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1D;AAED,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;CAC3E;AAED,MAAM,MAAM,uCAAuC,GAAG;IACpD,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,+BAA+B,EAAE,CAAC;IAC/D,QAAQ,CAAC,WAAW,CAAC,EAAE,2BAA2B,CAAC;IACnD,QAAQ,CAAC,aAAa,CAAC,EAAE,iCAAiC,CAAC;CAC5D,CAAC;AAEF,qBAAa,2BAA4B,YAAW,sBAAsB;IACxE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6C;IACtE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA8B;IAC1D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAoC;gBAEtD,YAAY,GAAE,uCAA4C;IAUhE,YAAY,IAAI,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC;IAI9C,GAAG,CACR,MAAM,EAAE,8BAA8B,EACtC,OAAO,EAAE,kBAAkB,EAC3B,GAAG,EAAE,UAAU,GACd,QAAQ;IA+CX,OAAO,CAAC,UAAU;CAenB;AAED,qBAAa,kCACX,YAAW,2BAA2B;IAEtC,QAAQ,CAAC,WAAW,KAAwB;IAE5C,WAAW,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;CAGzD;AAED,qBAAa,wCACX,YAAW,iCAAiC;IAE5C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAIvB;IAEI,QAAQ,CACZ,QAAQ,EAAE,QAAQ,EAClB,GAAG,EAAE,UAAU,GACd,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;CAM9B;AAmJD,eAAO,MAAM,6BAA6B,6BAAoC,CAAC"}

package/dist/agents/openai-compatible/fetch-engine.js

@@ -92,6 +92,7 @@ export class FetchOpenAiCompatibleEngine {
         if (decoder === undefined) {
             throw new AgentError({
                 code: AGENT_ERROR_CODE.failed,
+                classification: AgentError.agentFailure(AGENT_ERROR_CODE.failed),
                 message: "OpenAI-compatible endpoint returned an unsupported response",
                 data: { exitCode: null, stdoutTail: null, stderrTail: null },
             });
@@ -120,6 +121,7 @@ const authFailureHandler = {
     matches: (response) => isAuthHttpStatus(response.status),
     errorFor: async (response) => new AgentError({
         code: AGENT_ERROR_CODE.auth,
+        classification: AgentError.agentFailure(AGENT_ERROR_CODE.auth),
         message: `OpenAI-compatible endpoint rejected authentication with HTTP ${response.status}`,
         data: {
             reason: AUTH_REASON_BY_STATUS[response.status],
@@ -133,6 +135,7 @@ const quotaFailureHandler = {
         const retryAfter = response.headers.get(OPENAI_COMPATIBLE_HTTP_HEADER.retryAfter);
         return new AgentError({
             code: AGENT_ERROR_CODE.quota,
+            classification: AgentError.agentFailure(AGENT_ERROR_CODE.quota),
             message: "OpenAI-compatible endpoint reported a rate limit",
             data: {
                 cooldownUntil: retryAfter === null
@@ -149,6 +152,7 @@ const genericHttpFailureHandler = {
         const redactedBody = redactSecrets(body);
         return new AgentError({
             code: AGENT_ERROR_CODE.failed,
+            classification: AgentError.agentFailure(AGENT_ERROR_CODE.failed),
             message: `OpenAI-compatible endpoint failed with HTTP ${response.status}`,
             data: {
                 exitCode: null,
@@ -194,6 +198,7 @@ function normalizeRunError(error) {
     }
     return new AgentError({
         code: AGENT_ERROR_CODE.notAvailable,
+        classification: AgentError.agentFailure(AGENT_ERROR_CODE.notAvailable),
         message: error instanceof Error ? error.message : String(error),
         data: { cause: NOT_AVAILABLE_CAUSE.unreachable },
         cause: error,
@@ -209,6 +214,7 @@ function isRetryableRunError(error) {
 function unreachableError() {
     return new AgentError({
         code: AGENT_ERROR_CODE.failed,
+        classification: AgentError.agentFailure(AGENT_ERROR_CODE.failed),
         message: "OpenAI-compatible endpoint failed without an error",
         data: { exitCode: null, stdoutTail: null, stderrTail: null },
     });

package/dist/agents/openai-compatible/pi/module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../../../../src/agents/openai-compatible/pi/module.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../../../../src/agents/openai-compatible/pi/module.ts"],"names":[],"mappings":"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"}

package/dist/agents/openai-compatible/pi/module.js

@@ -36,6 +36,7 @@ export async function loadPiModule(loader) {
 export function piPeerMissingError(cause) {
     return new AgentError({
         code: AGENT_ERROR_CODE.notAvailable,
+        classification: AgentError.agentFailure(AGENT_ERROR_CODE.notAvailable),
         message: PI_PEER_MISSING_MESSAGE,
         data: { cause: NOT_AVAILABLE_CAUSE.engineMissing },
         cause,

package/dist/agents/openai-compatible/pi/sandbox.js

@@ -38,6 +38,7 @@ function createGuardedBashTool(input, allowlist) {
     if (createDefinition === undefined || createOperations === undefined) {
         throw new AgentError({
             code: AGENT_ERROR_CODE.notAvailable,
+            classification: AgentError.agentFailure(AGENT_ERROR_CODE.notAvailable),
             message: PI_SHELL_GRANT_MISSING_FACTORY_MESSAGE,
             data: { cause: NOT_AVAILABLE_CAUSE.engineMissing },
         });
@@ -63,6 +64,7 @@ function assertAllowedCommand(command, allowlist) {
     }
     throw new AgentError({
         code: AGENT_ERROR_CODE.invalidInput,
+        classification: AgentError.agentFailure(AGENT_ERROR_CODE.invalidInput),
         message: PI_BASH_COMMAND_NOT_ALLOWED_MESSAGE,
         data: { reason: PI_BASH_COMMAND_NOT_ALLOWED_REASON },
     });

package/dist/agents/openai-compatible/response.js

@@ -191,6 +191,7 @@ function invalidJsonResponseError(message, body) {
     const redactedBody = redactSecrets(body);
     return new AgentError({
         code: AGENT_ERROR_CODE.failed,
+        classification: AgentError.agentFailure(AGENT_ERROR_CODE.failed),
         message,
         data: {
             exitCode: null,

package/dist/auth/profile-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"profile-store.d.ts","sourceRoot":"","sources":["../../src/auth/profile-store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAcrE,MAAM,WAAW,YAAY;IAC3B,IAAI,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAC/B,IAAI,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C;AA6FD,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,CAE/D"}
+{"version":3,"file":"profile-store.d.ts","sourceRoot":"","sources":["../../src/auth/profile-store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAcrE,MAAM,WAAW,YAAY;IAC3B,IAAI,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAC/B,IAAI,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C;AA+FD,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,CAE/D"}

package/dist/auth/profile-store.js

@@ -22,6 +22,7 @@ const PROFILE_STORE_ERROR_REASON = {
 function profileStoreError(reason, cause) {
     return new AgentError({
         code: AGENT_ERROR_CODE.invalidInput,
+        classification: AgentError.agentFailure(AGENT_ERROR_CODE.invalidInput),
         message: `Invalid auth profile store: ${reason}`,
         data: { reason },
         ...(cause === undefined ? {} : { cause }),

package/dist/auth/secrets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../../src/auth/secrets.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE/C;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,SAAS,EAAE,eAAe,EAC1B,GAAG,EAAE,SAAS,GACb,OAAO,CAAC,MAAM,CAAC,CAqBjB;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,cAAc,CAS5C"}
+{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../../src/auth/secrets.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE/C;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,SAAS,EAAE,eAAe,EAC1B,GAAG,EAAE,SAAS,GACb,OAAO,CAAC,MAAM,CAAC,CAyBjB;AAED;;;GAGG;AACH,wBAAgB,WAAW,IAAI,cAAc,CAS5C"}

package/dist/auth/secrets.js

@@ -9,6 +9,7 @@ export async function requireSecret(resolvers, ref) {
     if (resolver === undefined) {
         throw new AgentError({
             code: AGENT_ERROR_CODE.invalidInput,
+            classification: AgentError.agentFailure(AGENT_ERROR_CODE.invalidInput),
             message: `Unknown secret resolver "${ref.resolver}"`,
             data: { reason: `no secret resolver registered for "${ref.resolver}"` },
         });
@@ -17,6 +18,7 @@ export async function requireSecret(resolvers, ref) {
     if (value === null || value === "") {
         throw new AgentError({
             code: AGENT_ERROR_CODE.auth,
+            classification: AgentError.agentFailure(AGENT_ERROR_CODE.auth),
             message: `Secret "${ref.id}" is not available from resolver "${ref.resolver}"`,
             data: {
                 reason: AUTH_FAILURE_REASON.invalidCredentials,

package/dist/codex/app-server.js

@@ -107,6 +107,7 @@ class ExecCodexAppServer {
         if (command === null) {
             throw new AgentError({
                 code: AGENT_ERROR_CODE.notAvailable,
+                classification: AgentError.agentFailure(AGENT_ERROR_CODE.notAvailable),
                 message: `Command "${this.options.command}" was not found on PATH`,
                 data: { cause: NOT_AVAILABLE_CAUSE.notInstalled },
             });
@@ -174,6 +175,7 @@ class ExecCodexAppServer {
                 process.kill(PROCESS_SIGNAL.sigkill);
                 reject(new AgentError({
                     code: AGENT_ERROR_CODE.timeout,
+                    classification: AgentError.agentFailure(AGENT_ERROR_CODE.timeout),
                     message: `Codex app-server request timed out: ${String(method)}`,
                     data: {
                         kind: TIMEOUT_KIND.total,
@@ -281,6 +283,7 @@ function appServerResponseError(method, error) {
     const detail = redactSecrets(error.message ?? "");
     return new AgentError({
         code: AGENT_ERROR_CODE.failed,
+        classification: AgentError.agentFailure(AGENT_ERROR_CODE.failed),
         message: detail === "" ? `Codex app-server request failed: ${method}` : detail,
         data: {
             exitCode: null,
@@ -293,6 +296,7 @@ function appServerMalformedResultError(method, result) {
     const detail = redactSecrets(JSON.stringify(result) ?? "");
     return new AgentError({
         code: AGENT_ERROR_CODE.failed,
+        classification: AgentError.agentFailure(AGENT_ERROR_CODE.failed),
         message: `Codex app-server returned a malformed result: ${method}`,
         data: {
             exitCode: null,
@@ -305,6 +309,7 @@ function appServerExitedError(exitCode, stderr) {
     const stderrTail = redactSecrets(stderr.slice(-OUTPUT_TAIL_CHARS));
     return new AgentError({
         code: AGENT_ERROR_CODE.failed,
+        classification: AgentError.agentFailure(AGENT_ERROR_CODE.failed),
         message: "Codex app-server exited before completing the request",
         data: {
             exitCode,
@@ -316,6 +321,7 @@ function appServerExitedError(exitCode, stderr) {
 function appServerClosedError() {
     return new AgentError({
         code: AGENT_ERROR_CODE.failed,
+        classification: AgentError.agentFailure(AGENT_ERROR_CODE.failed),
         message: "Codex app-server connection closed",
         data: { exitCode: null, stdoutTail: null, stderrTail: null },
     });

package/dist/core/controlled-process.d.ts

@@ -0,0 +1,98 @@
+import type { ValueOf } from "@alpacakit/core";
+import type { ExecChunk, ExecExit, ExecSpawnOptions } from "./ports.js";
+export declare const CHILD_PROCESS_TERMINATION_KIND: {
+    readonly absent: "absent";
+    readonly pending: "pending";
+    readonly unkillable: "unkillable";
+};
+export declare const CHILD_PROCESS_TERMINATION_EVIDENCE_KIND: {
+    readonly liveChildClose: "live_child_close";
+    readonly offlineAbsence: "offline_absence";
+};
+export declare const CHILD_PROCESS_ABSENCE_PROOF: {
+    readonly supervisorProbe: "supervisor_probe";
+    readonly bootChanged: "boot_changed";
+    readonly releasedReceipt: "released_receipt";
+};
+export declare const CHILD_PROCESS_TERMINATION_PHASE: {
+    readonly termGrace: "term_grace";
+    readonly killProbe: "kill_probe";
+};
+export declare const CHILD_PROCESS_UNKILLABLE_REASON: {
+    readonly invalidIdentity: "invalid_identity";
+    readonly bootIdentityUnavailable: "boot_identity_unavailable";
+    readonly supervisorUnreachable: "supervisor_unreachable";
+    readonly recordAuthenticationFailed: "record_authentication_failed";
+    readonly recordIdentityMismatch: "record_identity_mismatch";
+    readonly protocolFailure: "protocol_failure";
+    readonly probePermissionDenied: "probe_permission_denied";
+    readonly shimLostWithLiveGroup: "shim_lost_with_live_group";
+    readonly groupSurvivedSigkill: "group_survived_sigkill";
+};
+export type ChildProcessAbsenceProof = ValueOf<typeof CHILD_PROCESS_ABSENCE_PROOF>;
+export type ChildProcessTerminationPhase = ValueOf<typeof CHILD_PROCESS_TERMINATION_PHASE>;
+export type ChildProcessUnkillableReason = ValueOf<typeof CHILD_PROCESS_UNKILLABLE_REASON>;
+export type ChildProcessIdentity = {
+    readonly pid: number;
+    readonly processStartToken: string;
+};
+/**
+ * Local lifecycle evidence only. It is deliberately separate from the
+ * signed controlled-process record: only a live supervisor response may
+ * carry worker exit evidence, while recovery can establish absence only.
+ */
+export type ChildProcessTerminationEvidence = {
+    readonly kind: typeof CHILD_PROCESS_TERMINATION_EVIDENCE_KIND.liveChildClose;
+    readonly identity: ChildProcessIdentity;
+    readonly proof: ChildProcessAbsenceProof;
+    readonly workerExit: ExecExit;
+} | {
+    readonly kind: typeof CHILD_PROCESS_TERMINATION_EVIDENCE_KIND.offlineAbsence;
+    readonly identity: ChildProcessIdentity;
+    readonly proof: ChildProcessAbsenceProof;
+};
+export interface ChildProcessLifecycle {
+    beforeExec(identity: ChildProcessIdentity): Promise<void>;
+    afterTermination(evidence: ChildProcessTerminationEvidence): Promise<void>;
+}
+export type ChildProcessTerminationResult = {
+    readonly kind: typeof CHILD_PROCESS_TERMINATION_KIND.absent;
+    readonly proof: ChildProcessAbsenceProof;
+} | {
+    readonly kind: typeof CHILD_PROCESS_TERMINATION_KIND.pending;
+    readonly phase: ChildProcessTerminationPhase;
+    readonly retryAfterMs: number;
+} | {
+    readonly kind: typeof CHILD_PROCESS_TERMINATION_KIND.unkillable;
+    readonly reason: ChildProcessUnkillableReason;
+};
+export type ChildProcessCompletion = {
+    readonly kind: typeof CHILD_PROCESS_TERMINATION_KIND.absent;
+    readonly proof: ChildProcessAbsenceProof;
+    readonly workerExit: ExecExit | null;
+} | {
+    readonly kind: typeof CHILD_PROCESS_TERMINATION_KIND.unkillable;
+    readonly reason: ChildProcessUnkillableReason;
+    readonly workerExit: ExecExit | null;
+};
+export type ControlledExecOptions = {
+    readonly runtimeDirectory: string;
+    readonly termination: {
+        readonly termGraceMs: number;
+        readonly killProbeTimeoutMs: number;
+        readonly probeIntervalMs: number;
+    };
+};
+export interface ControlledExecProcess {
+    readonly chunks: AsyncIterable<ExecChunk>;
+    readonly completion: Promise<ChildProcessCompletion>;
+    requestTermination(): Promise<ChildProcessCompletion>;
+}
+export interface ControlledProcessRecovery {
+    recover(identity: ChildProcessIdentity, lifecycle: Pick<ChildProcessLifecycle, "afterTermination">): Promise<ChildProcessTerminationResult>;
+}
+export interface ControlledExec {
+    spawn(options: ExecSpawnOptions, lifecycle: ChildProcessLifecycle): Promise<ControlledExecProcess>;
+    readonly recovery: ControlledProcessRecovery;
+}
+//# sourceMappingURL=controlled-process.d.ts.map

package/dist/core/controlled-process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controlled-process.d.ts","sourceRoot":"","sources":["../../src/core/controlled-process.ts"],"names":[],"mappings":"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"}

package/dist/core/controlled-process.js

@@ -0,0 +1,29 @@
+export const CHILD_PROCESS_TERMINATION_KIND = {
+    absent: "absent",
+    pending: "pending",
+    unkillable: "unkillable",
+};
+export const CHILD_PROCESS_TERMINATION_EVIDENCE_KIND = {
+    liveChildClose: "live_child_close",
+    offlineAbsence: "offline_absence",
+};
+export const CHILD_PROCESS_ABSENCE_PROOF = {
+    supervisorProbe: "supervisor_probe",
+    bootChanged: "boot_changed",
+    releasedReceipt: "released_receipt",
+};
+export const CHILD_PROCESS_TERMINATION_PHASE = {
+    termGrace: "term_grace",
+    killProbe: "kill_probe",
+};
+export const CHILD_PROCESS_UNKILLABLE_REASON = {
+    invalidIdentity: "invalid_identity",
+    bootIdentityUnavailable: "boot_identity_unavailable",
+    supervisorUnreachable: "supervisor_unreachable",
+    recordAuthenticationFailed: "record_authentication_failed",
+    recordIdentityMismatch: "record_identity_mismatch",
+    protocolFailure: "protocol_failure",
+    probePermissionDenied: "probe_permission_denied",
+    shimLostWithLiveGroup: "shim_lost_with_live_group",
+    groupSurvivedSigkill: "group_survived_sigkill",
+};

package/dist/core/error.d.ts

@@ -16,6 +16,25 @@ export declare const AGENT_ERROR_CODE: {
     readonly failed: "failed";
 };
 export type AgentErrorCode = (typeof AGENT_ERROR_CODE)[keyof typeof AGENT_ERROR_CODE];
+export declare const AGENT_FAILURE_CLASS: {
+    readonly agent: "agent";
+    readonly infrastructure: "infrastructure";
+};
+export type AgentFailureClass = (typeof AGENT_FAILURE_CLASS)[keyof typeof AGENT_FAILURE_CLASS];
+export declare const AGENT_INFRASTRUCTURE_FAILURE_CODE: {
+    readonly controlledProcessLifecycle: "controlled_process_lifecycle";
+};
+export type AgentInfrastructureFailureCode = (typeof AGENT_INFRASTRUCTURE_FAILURE_CODE)[keyof typeof AGENT_INFRASTRUCTURE_FAILURE_CODE];
+export type AgentFailureCode = AgentErrorCode | AgentInfrastructureFailureCode;
+export type AgentFailure<C extends AgentErrorCode = AgentErrorCode> = {
+    readonly failureClass: typeof AGENT_FAILURE_CLASS.agent;
+    readonly failureCode: C;
+} | {
+    readonly failureClass: typeof AGENT_FAILURE_CLASS.infrastructure;
+    readonly failureCode: AgentInfrastructureFailureCode;
+};
+export declare function agentFailure<C extends AgentErrorCode>(failureCode: C): AgentFailure<C>;
+export declare function infrastructureFailure<C extends AgentErrorCode>(failureCode: AgentInfrastructureFailureCode): AgentFailure<C>;
 export declare const AUTH_FAILURE_REASON: {
     readonly notLoggedIn: "not_logged_in";
     readonly invalidApiKey: "invalid_api_key";
@@ -89,6 +108,7 @@ export type AgentErrorData = {
 };
 export type AgentErrorOptions<C extends AgentErrorCode> = {
     code: C;
+    classification: AgentFailure<C>;
     message: string;
     data: AgentErrorData[C];
     runId?: string;
@@ -99,11 +119,16 @@ export type AgentErrorOptions<C extends AgentErrorCode> = {
 };
 export declare class AgentError<C extends AgentErrorCode = AgentErrorCode> extends Error {
     readonly code: C;
+    readonly classification: AgentFailure<C>;
+    readonly failureCode: AgentFailure<C>["failureCode"];
+    readonly failureClass: AgentFailure<C>["failureClass"];
     readonly data: AgentErrorData[C];
     readonly runId: string | null;
     readonly agentId: string | null;
     readonly started: boolean;
     readonly durationMs: number;
+    static agentFailure<C extends AgentErrorCode>(failureCode: C): AgentFailure<C>;
+    static infrastructureFailure<C extends AgentErrorCode>(failureCode: AgentInfrastructureFailureCode): AgentFailure<C>;
     constructor(options: AgentErrorOptions<C>);
 }
 /**

package/dist/core/error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../src/core/error.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,eAAO,MAAM,gBAAgB;;;;;;;;;;;CAWnB,CAAC;AAEX,MAAM,MAAM,cAAc,GACxB,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,OAAO,gBAAgB,CAAC,CAAC;AAE3D,eAAO,MAAM,mBAAmB;;;;;;;;;;;CAWtB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAC3B,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,OAAO,mBAAmB,CAAC,CAAC;AAEjE,eAAO,MAAM,mBAAmB;;;;;CAKtB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAC3B,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,OAAO,mBAAmB,CAAC,CAAC;AAEjE,eAAO,MAAM,YAAY;;;CAGf,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAE3E,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,KAAK,GAAG;IAClB,IAAI,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,CAAC,gBAAgB,CAAC,YAAY,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACpD,CAAC,gBAAgB,CAAC,YAAY,CAAC,EAAE;QAAE,KAAK,EAAE,iBAAiB,CAAA;KAAE,CAAC;IAC9D,CAAC,gBAAgB,CAAC,QAAQ,CAAC,EAAE;QAAE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAC9D,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE;QAAE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAC3D,CAAC,gBAAgB,CAAC,IAAI,CAAC,EAAE;QACvB,MAAM,EAAE,iBAAiB,CAAC;QAC1B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;KACvB,CAAC;IACF,CAAC,gBAAgB,CAAC,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,WAAW,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACnE,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE;QAAE,SAAS,EAAE,cAAc,CAAA;KAAE,CAAC;IACxD,CAAC,gBAAgB,CAAC,SAAS,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IACxD,CAAC,gBAAgB,CAAC,cAAc,CAAC,EAAE;QAAE,MAAM,EAAE,KAAK,EAAE,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IACzE,CAAC,gBAAgB,CAAC,MAAM,CAAC,EAAE;QACzB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;KAC3B,CAAC;CACH,CAAC;AAIF,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,cAAc,IAAI;IACxD,IAAI,EAAE,CAAC,CAAC;IACR,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,qBAAa,UAAU,CACrB,CAAC,SAAS,cAAc,GAAG,cAAc,CACzC,SAAQ,KAAK;IACb,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC;CAiB1C;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,cAAc,EACnD,KAAK,EAAE,OAAO,EACd,IAAI,CAAC,EAAE,CAAC,GACP,KAAK,IAAI,UAAU,CAAC,CAAC,CAAC,CAQxB;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,CAAC,CAAC,SAAS,cAAc,EACtD,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EACpB,QAAQ,EAAE;IACR,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB,GACA,UAAU,CAAC,CAAC,CAAC,CAWf"}
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../src/core/error.ts"],"names":[],"mappings":"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"}

package/dist/core/error.js

@@ -15,6 +15,25 @@ export const AGENT_ERROR_CODE = {
     outputRejected: "output_rejected",
     failed: "failed",
 };
+export const AGENT_FAILURE_CLASS = {
+    agent: "agent",
+    infrastructure: "infrastructure",
+};
+export const AGENT_INFRASTRUCTURE_FAILURE_CODE = {
+    controlledProcessLifecycle: "controlled_process_lifecycle",
+};
+export function agentFailure(failureCode) {
+    return {
+        failureClass: AGENT_FAILURE_CLASS.agent,
+        failureCode,
+    };
+}
+export function infrastructureFailure(failureCode) {
+    return {
+        failureClass: AGENT_FAILURE_CLASS.infrastructure,
+        failureCode,
+    };
+}
 export const AUTH_FAILURE_REASON = {
     notLoggedIn: "not_logged_in",
     invalidApiKey: "invalid_api_key",
@@ -40,15 +59,27 @@ export const TIMEOUT_KIND = {
 const AGENT_ERROR_BRAND = Symbol.for("@alpacakit/agents.AgentError");
 export class AgentError extends Error {
     code;
+    classification;
+    failureCode;
+    failureClass;
     data;
     runId;
     agentId;
     started;
     durationMs;
+    static agentFailure(failureCode) {
+        return agentFailure(failureCode);
+    }
+    static infrastructureFailure(failureCode) {
+        return infrastructureFailure(failureCode);
+    }
     constructor(options) {
         super(options.message, options.cause === undefined ? undefined : { cause: options.cause });
         this.name = "AgentError";
         this.code = options.code;
+        this.classification = options.classification;
+        this.failureCode = options.classification.failureCode;
+        this.failureClass = options.classification.failureClass;
         this.data = options.data;
         this.runId = options.runId ?? null;
         this.agentId = options.agentId ?? null;
@@ -77,6 +108,7 @@ export function isAgentError(value, code) {
 export function withRunIdentity(error, identity) {
     return new AgentError({
         code: error.code,
+        classification: error.classification,
         message: error.message,
         data: error.data,
         runId: error.runId ?? identity.runId,