@alpacakit/agents 0.1.0-beta.19 → 0.1.0-beta.21

package/dist/kernel/facets.js

@@ -86,6 +86,7 @@ export function bindMcp(capability, binding) {
             if (issues.length > 0) {
                 throw new AgentError({
                     code: AGENT_ERROR_CODE.invalidInput,
+                    classification: AgentError.agentFailure(AGENT_ERROR_CODE.invalidInput),
                     message: "MCP server spec contains a literal or forbidden secret",
                     data: {
                         reason: issues

package/dist/kernel/keyed.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"keyed.d.ts","sourceRoot":"","sources":["../../src/kernel/keyed.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAG3E;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAEzE;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EACtC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,GACX,IAAI,CAWN"}
+{"version":3,"file":"keyed.d.ts","sourceRoot":"","sources":["../../src/kernel/keyed.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAG3E;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAEzE;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EACtC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,GACX,IAAI,CAaN"}

package/dist/kernel/keyed.js

@@ -26,6 +26,7 @@ export function requireKeyedHandler(record, key, agentId, what) {
     if (handler === null) {
         throw new AgentError({
             code: AGENT_ERROR_CODE.invalidInput,
+            classification: AgentError.agentFailure(AGENT_ERROR_CODE.invalidInput),
             message: `Agent "${agentId}" does not support ${what}`,
             data: { reason: `unsupported: ${what}` },
             agentId,

package/dist/kernel/login.js

@@ -57,6 +57,7 @@ function toLoginError(agentId, thrown) {
     const message = thrown instanceof Error ? thrown.message : String(thrown);
     return new AgentError({
         code: AGENT_ERROR_CODE.failed,
+        classification: AgentError.agentFailure(AGENT_ERROR_CODE.failed),
         message: redactSecrets(message),
         data: { exitCode: null, stdoutTail: null, stderrTail: null },
         cause: thrown,
@@ -66,6 +67,7 @@ function toLoginError(agentId, thrown) {
 function withAgentId(error, agentId) {
     return new AgentError({
         code: error.code,
+        classification: error.classification,
         message: error.message,
         data: error.data,
         agentId,

package/dist/kernel/options.d.ts

@@ -4,6 +4,7 @@
  * definitions only ever see the resolved types.
  */
 import { type EnvPatch } from "../core/env.js";
+import type { ChildProcessLifecycle, ControlledExec } from "../core/controlled-process.js";
 import type { GuardFactory } from "./guard.js";
 export declare const GRANT_KIND: {
     readonly shell: "shell";
@@ -44,6 +45,17 @@ export type ResolvedLimits = {
     idleMs: number | null;
     guards: GuardFactory[];
 };
+/** Optional run-scoped resources supplied by the embedding host. */
+export type ControlledChildProcessResource = {
+    readonly exec: ControlledExec;
+    readonly lifecycle: ChildProcessLifecycle;
+};
+export type RunResources = {
+    childProcess?: ControlledChildProcessResource;
+};
+export type ResolvedRunResources = {
+    childProcess: ControlledChildProcessResource | null;
+};
 type BaseRunOptions = {
     prompt: string;
     workspace: string;
@@ -52,6 +64,7 @@ type BaseRunOptions = {
     sandbox?: Sandbox;
     env?: EnvPatch;
     limits?: Limits;
+    resources?: RunResources;
     signal?: AbortSignal;
 };
 export type RunOptions = BaseRunOptions & {
@@ -65,6 +78,7 @@ export type ResolvedRunOptions = {
     sandbox: ResolvedSandbox;
     env: EnvPatch;
     limits: ResolvedLimits;
+    resources: ResolvedRunResources;
 };
 export declare function resolveSandbox(sandbox: Sandbox | undefined): ResolvedSandbox;
 export declare function resolveLimits(limits: Limits | undefined): ResolvedLimits;

package/dist/kernel/options.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../src/kernel/options.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAmB,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,eAAO,MAAM,UAAU;;;CAGb,CAAC;AAEX,MAAM,MAAM,KAAK,GACb;IAAE,IAAI,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,OAAO,UAAU,CAAC,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnD,eAAO,MAAM,YAAY;;;CAGf,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAE3E,MAAM,MAAM,OAAO,GACf;IAAE,IAAI,EAAE,OAAO,YAAY,CAAC,IAAI,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,OAAO,YAAY,CAAC,QAAQ,CAAC;IAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAA;CAAE,CAAC;AAE7D,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,OAAO,YAAY,CAAC,IAAI,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,OAAO,YAAY,CAAC,QAAQ,CAAC;IAAC,MAAM,EAAE,KAAK,EAAE,CAAA;CAAE,CAAC;AAE5D,4EAA4E;AAC5E,MAAM,MAAM,MAAM,GAAG;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,YAAY,EAAE,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,YAAY,EAAE,CAAC;CACxB,CAAC;AAEF,KAAK,cAAc,GAAG;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,GAAG,CAAC,EAAE,QAAQ,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,cAAc,GAAG;IACxC,QAAQ,CAAC,EAAE,KAAK,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,eAAe,CAAC;IACzB,GAAG,EAAE,QAAQ,CAAC;IACd,MAAM,EAAE,cAAc,CAAC;CACxB,CAAC;AAEF,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,GAAG,eAAe,CAQ5E;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,cAAc,CAMxE;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,UAAU,GAAG,kBAAkB,CAUzE"}
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../src/kernel/options.ts"],"names":[],"mappings":"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"}

package/dist/kernel/options.js

@@ -37,5 +37,8 @@ export function resolveRunOptions(options) {
         sandbox: resolveSandbox(options.sandbox),
         env: options.env ?? EMPTY_ENV_PATCH,
         limits: resolveLimits(options.limits),
+        resources: {
+            childProcess: options.resources?.childProcess ?? null,
+        },
     };
 }

package/dist/kernel/process-lifecycle-failure.d.ts

@@ -0,0 +1,5 @@
+import { AGENT_ERROR_CODE, type AgentError } from "../core/error.js";
+type ProcessLifecycleFailure = AgentError<typeof AGENT_ERROR_CODE.failed>;
+export declare function isProcessLifecycleFailure(value: unknown): value is ProcessLifecycleFailure;
+export {};
+//# sourceMappingURL=process-lifecycle-failure.d.ts.map

package/dist/kernel/process-lifecycle-failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-lifecycle-failure.d.ts","sourceRoot":"","sources":["../../src/kernel/process-lifecycle-failure.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAEhB,KAAK,UAAU,EAEhB,MAAM,kBAAkB,CAAC;AAE1B,KAAK,uBAAuB,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAC;AAE1E,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,uBAAuB,CAKlC"}

package/dist/kernel/process-lifecycle-failure.js

@@ -0,0 +1,5 @@
+import { AGENT_ERROR_CODE, AGENT_FAILURE_CLASS, isAgentError, } from "../core/error.js";
+export function isProcessLifecycleFailure(value) {
+    return (isAgentError(value, AGENT_ERROR_CODE.failed) &&
+        value.failureClass === AGENT_FAILURE_CLASS.infrastructure);
+}

package/dist/kernel/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/kernel/run.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAYH,OAAO,KAAK,EAAU,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEtD,OAAO,KAAK,EAIV,SAAS,EAEV,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,eAAe,EAAc,MAAM,iBAAiB,CAAC;AAGnE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AASvD,MAAM,MAAM,aAAa,GAAG;IAC1B,UAAU,EAAE,eAAe,CAAC;IAC5B,OAAO,EAAE,kBAAkB,CAAC;IAC5B,YAAY,EAAE,WAAW,GAAG,IAAI,CAAC;IACjC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,KAAK,EAAE,KAAK,CAAC;CACd,CAAC;AA4QF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,CAExD"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/kernel/run.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAYH,OAAO,KAAK,EAAU,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEtD,OAAO,KAAK,EAIV,SAAS,EAEV,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,eAAe,EAAc,MAAM,iBAAiB,CAAC;AAGnE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAUvD,MAAM,MAAM,aAAa,GAAG;IAC1B,UAAU,EAAE,eAAe,CAAC;IAC5B,OAAO,EAAE,kBAAkB,CAAC;IAC5B,YAAY,EAAE,WAAW,GAAG,IAAI,CAAC;IACjC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,KAAK,EAAE,KAAK,CAAC;CACd,CAAC;AA0RF,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,CAExD"}

package/dist/kernel/run.js

@@ -10,6 +10,7 @@ import { AGENT_ERROR_CODE, AgentError, isAgentError, TIMEOUT_KIND, withRunIdenti
 import { redactSecrets } from "../core/redact.js";
 import { RUN_EVENT_TYPE, RUN_OUTCOME } from "../core/run.js";
 import { createRunHandle, EventBroadcast } from "./handle.js";
+import { isProcessLifecycleFailure } from "./process-lifecycle-failure.js";
 const GUARD_POLL_MS = 1_000;
 const RUN_TRIP_KIND = {
     timeout: "timeout",
@@ -203,6 +204,7 @@ class RunDriver {
         if (trip.kind === RUN_TRIP_KIND.timeout) {
             return new AgentError({
                 code: AGENT_ERROR_CODE.timeout,
+                classification: AgentError.agentFailure(AGENT_ERROR_CODE.timeout),
                 message: `Run exceeded its ${trip.timeoutKind} timeout of ${trip.limitMs}ms`,
                 data: { kind: trip.timeoutKind, limitMs: trip.limitMs },
                 ...this.identity(),
@@ -211,6 +213,7 @@ class RunDriver {
         if (trip.kind === RUN_TRIP_KIND.limit) {
             return new AgentError({
                 code: AGENT_ERROR_CODE.limit,
+                classification: AgentError.agentFailure(AGENT_ERROR_CODE.limit),
                 message: `Guard "${trip.violation.guardId}" tripped: ${trip.violation.reason}`,
                 data: { violation: trip.violation },
                 ...this.identity(),
@@ -218,12 +221,19 @@ class RunDriver {
         }
         return new AgentError({
             code: AGENT_ERROR_CODE.cancelled,
+            classification: AgentError.agentFailure(AGENT_ERROR_CODE.cancelled),
             message: "Run was cancelled",
             data: { reason: trip.reason },
             ...this.identity(),
         });
     }
     toAgentError(thrown) {
+        // Only branded process/lifecycle cleanup evidence overrides the trip that
+        // requested termination. Ordinary adapter failures preserve the existing
+        // timeout/cancel precedence.
+        if (isProcessLifecycleFailure(thrown)) {
+            return withRunIdentity(thrown, this.identity());
+        }
         if (this.tripReason !== null) {
             return this.errorFromTrip(this.tripReason);
         }
@@ -233,6 +243,7 @@ class RunDriver {
         const message = thrown instanceof Error ? thrown.message : String(thrown);
         return new AgentError({
             code: AGENT_ERROR_CODE.failed,
+            classification: AgentError.agentFailure(AGENT_ERROR_CODE.failed),
             message: redactSecrets(message),
             data: { exitCode: null, stdoutTail: null, stderrTail: null },
             cause: thrown,

package/dist/kernel/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/kernel/runtime.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAA6B,KAAK,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EAE1B,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EACL,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,WAAW,EAOjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,KAAK,UAAU,EAAqB,MAAM,cAAc,CAAC;AAGlE,MAAM,WAAW,KAAK,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM;IAC/C,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC;IAChB,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAC9D,GAAG,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS,CAAC;IACpC,GAAG,CAAC,CAAC,EACH,OAAO,EAAE,UAAU,GAAG,oBAAoB,CAAC,CAAC,CAAC,GAC5C,SAAS,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;IACnC,IAAI,EAAE,SAAS,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM;IACtD,KAAK,CAAC,CAAC,SAAS,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACrC,MAAM,IAAI,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;IACtB,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB;AAED,MAAM,MAAM,mBAAmB,CAAC,IAAI,SAAS,SAAS,eAAe,EAAE,IAAI;IACzE,MAAM,EAAE,IAAI,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IACvB;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,KAAK,CAS1D;AAqED,wBAAgB,kBAAkB,CAChC,KAAK,CAAC,IAAI,SAAS,SAAS,eAAe,EAAE,EAC7C,OAAO,EAAE,mBAAmB,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CA8BtE"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/kernel/runtime.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAA6B,KAAK,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EAE1B,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EACL,KAAK,SAAS,EACd,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,WAAW,EAOjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,KAAK,UAAU,EAAqB,MAAM,cAAc,CAAC;AAGlE,MAAM,WAAW,KAAK,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM;IAC/C,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC;IAChB,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAC9D,GAAG,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS,CAAC;IACpC,GAAG,CAAC,CAAC,EACH,OAAO,EAAE,UAAU,GAAG,oBAAoB,CAAC,CAAC,CAAC,GAC5C,SAAS,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;IACnC,IAAI,EAAE,SAAS,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM;IACtD,KAAK,CAAC,CAAC,SAAS,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACrC,MAAM,IAAI,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;IACtB,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;CACvB;AAED,MAAM,MAAM,mBAAmB,CAAC,IAAI,SAAS,SAAS,eAAe,EAAE,IAAI;IACzE,MAAM,EAAE,IAAI,CAAC;IACb,KAAK,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IACvB;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,KAAK,CAS1D;AAqED,wBAAgB,kBAAkB,CAChC,KAAK,CAAC,IAAI,SAAS,SAAS,eAAe,EAAE,EAC7C,OAAO,EAAE,mBAAmB,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAoCtE"}

package/dist/kernel/runtime.js

@@ -84,6 +84,7 @@ export function createAgentRuntime(options) {
         if (bound.has(definition.id)) {
             throw new AgentError({
                 code: AGENT_ERROR_CODE.invalidInput,
+                classification: AgentError.agentFailure(AGENT_ERROR_CODE.invalidInput),
                 message: `Duplicate agent id "${definition.id}"`,
                 data: { reason: `agent id "${definition.id}" registered twice` },
             });
@@ -97,6 +98,7 @@ export function createAgentRuntime(options) {
             if (agent === undefined) {
                 throw new AgentError({
                     code: AGENT_ERROR_CODE.invalidInput,
+                    classification: AgentError.agentFailure(AGENT_ERROR_CODE.invalidInput),
                     message: `Unknown agent id "${id}"`,
                     data: { reason: `no agent registered with id "${id}"` },
                 });

package/dist/keyring/resolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../src/keyring/resolver.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,KAAK,mBAAmB,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;AAiBlD,wBAAgB,eAAe,CAC7B,OAAO,EAAE,sBAAsB,GAC9B,cAAc,CAEhB;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,sBAAsB,EAC/B,MAAM,EAAE,mBAAmB,GAC1B,cAAc,CA0BhB"}
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../src/keyring/resolver.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,KAAK,mBAAmB,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;AAiBlD,wBAAgB,eAAe,CAC7B,OAAO,EAAE,sBAAsB,GAC9B,cAAc,CAEhB;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,sBAAsB,EAC/B,MAAM,EAAE,mBAAmB,GAC1B,cAAc,CA4BhB"}

package/dist/keyring/resolver.js

@@ -27,6 +27,7 @@ export function createKeyringResolver(options, loader) {
             catch (error) {
                 throw new AgentError({
                     code: AGENT_ERROR_CODE.failed,
+                    classification: AgentError.agentFailure(AGENT_ERROR_CODE.failed),
                     message: `Keyring secret "${id}" could not be read`,
                     data: { exitCode: null, stdoutTail: null, stderrTail: null },
                     cause: error,
@@ -55,6 +56,7 @@ async function loadKeyringModule(loader) {
 function keyringNotInstalledError(cause) {
     return new AgentError({
         code: AGENT_ERROR_CODE.notAvailable,
+        classification: AgentError.agentFailure(AGENT_ERROR_CODE.notAvailable),
         message: "Keyring peer is not installed",
         data: { cause: NOT_AVAILABLE_CAUSE.notInstalled },
         cause,

package/dist/structured/run-structured.js

@@ -168,6 +168,7 @@ async function driveStructured(input, broadcast) {
         }
         const errorOptions = {
             code: AGENT_ERROR_CODE.outputRejected,
+            classification: AgentError.agentFailure(AGENT_ERROR_CODE.outputRejected),
             message: "Structured output contract was not satisfied within the repair budget",
             data: { issues: lastIssues, attempts: attempts.length },
             agentId: input.agentId,

package/dist/testing/fake-controlled-exec.d.ts

@@ -0,0 +1,21 @@
+import type { ChildProcessCompletion, ChildProcessIdentity, ChildProcessTerminationResult, ControlledExec } from "../core/controlled-process.js";
+import type { ExecChunk, ExecSpawnOptions } from "../core/ports.js";
+export type FakeControlledExecScript = {
+    readonly chunks?: readonly ExecChunk[];
+    readonly completion?: ChildProcessCompletion;
+    readonly completionFailure?: unknown;
+    readonly requestCompletion?: ChildProcessCompletion;
+    readonly waitsForTermination?: boolean;
+    readonly closesOutput?: boolean;
+    readonly chunkFailure?: unknown;
+};
+export type FakeControlledExec = ControlledExec & {
+    readonly spawns: ExecSpawnOptions[];
+    readonly identities: ChildProcessIdentity[];
+    readonly terminationRequests: number[];
+    readonly outputReturns: number[];
+    readonly completionSubscriptions: number[];
+    readonly recoveryCalls: ChildProcessIdentity[];
+};
+export declare function createFakeControlledExec(scripts?: readonly FakeControlledExecScript[], recoveryResults?: readonly ChildProcessTerminationResult[]): FakeControlledExec;
+//# sourceMappingURL=fake-controlled-exec.d.ts.map

package/dist/testing/fake-controlled-exec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-controlled-exec.d.ts","sourceRoot":"","sources":["../../src/testing/fake-controlled-exec.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAEV,sBAAsB,EACtB,oBAAoB,EAEpB,6BAA6B,EAC7B,cAAc,EACf,MAAM,+BAA+B,CAAC;AAOvC,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEpE,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IACvC,QAAQ,CAAC,UAAU,CAAC,EAAE,sBAAsB,CAAC;IAC7C,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IACrC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,sBAAsB,CAAC;IACpD,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;IACvC,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,cAAc,GAAG;IAChD,QAAQ,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,oBAAoB,EAAE,CAAC;IAC5C,QAAQ,CAAC,mBAAmB,EAAE,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,aAAa,EAAE,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,uBAAuB,EAAE,MAAM,EAAE,CAAC;IAC3C,QAAQ,CAAC,aAAa,EAAE,oBAAoB,EAAE,CAAC;CAChD,CAAC;AAiBF,wBAAgB,wBAAwB,CACtC,OAAO,GAAE,SAAS,wBAAwB,EAAO,EACjD,eAAe,GAAE,SAAS,6BAA6B,EAAO,GAC7D,kBAAkB,CAkJpB"}

package/dist/testing/fake-controlled-exec.js

@@ -0,0 +1,172 @@
+import { AsyncQueue } from "../core/async-queue.js";
+import { CHILD_PROCESS_ABSENCE_PROOF, CHILD_PROCESS_TERMINATION_EVIDENCE_KIND, CHILD_PROCESS_TERMINATION_KIND, CHILD_PROCESS_UNKILLABLE_REASON, } from "../core/controlled-process.js";
+const DEFAULT_COMPLETION = {
+    kind: CHILD_PROCESS_TERMINATION_KIND.absent,
+    proof: CHILD_PROCESS_ABSENCE_PROOF.supervisorProbe,
+    workerExit: { code: 0, signal: null },
+};
+const DEFAULT_REQUEST_COMPLETION = {
+    kind: CHILD_PROCESS_TERMINATION_KIND.absent,
+    proof: CHILD_PROCESS_ABSENCE_PROOF.supervisorProbe,
+    workerExit: null,
+};
+const DEFAULT_RECOVERY = {
+    kind: CHILD_PROCESS_TERMINATION_KIND.unkillable,
+    reason: CHILD_PROCESS_UNKILLABLE_REASON.supervisorUnreachable,
+};
+export function createFakeControlledExec(scripts = [], recoveryResults = []) {
+    const remaining = [...scripts];
+    const recoveries = [...recoveryResults];
+    const spawns = [];
+    const identities = [];
+    const terminationRequests = [];
+    const outputReturns = [];
+    const completionSubscriptions = [];
+    const recoveryCalls = [];
+    let nextPid = 10_000;
+    return {
+        spawns,
+        identities,
+        terminationRequests,
+        outputReturns,
+        completionSubscriptions,
+        recoveryCalls,
+        spawn: async (options, lifecycle) => {
+            const spawnIndex = spawns.length;
+            spawns.push(options);
+            terminationRequests.push(0);
+            outputReturns.push(0);
+            completionSubscriptions.push(0);
+            const identity = {
+                pid: nextPid,
+                processStartToken: `fake-process-start-token-${nextPid}`,
+            };
+            nextPid += 1;
+            identities.push(identity);
+            await lifecycle.beforeExec(identity);
+            const script = remaining.shift() ?? {};
+            const chunks = new AsyncQueue();
+            for (const chunk of script.chunks ?? []) {
+                chunks.push(chunk);
+            }
+            let resolveCompletion = () => { };
+            let rejectCompletion = () => { };
+            const completion = new Promise((resolve, reject) => {
+                resolveCompletion = resolve;
+                rejectCompletion = reject;
+            });
+            void completion.catch(() => undefined);
+            const originalThen = completion.then.bind(completion);
+            const thenProperty = ["th", "en"].join("");
+            const publicCompletion = new Proxy(completion, {
+                get: (target, property) => {
+                    if (property === thenProperty) {
+                        return (...args) => {
+                            completionSubscriptions[spawnIndex] =
+                                (completionSubscriptions[spawnIndex] ?? 0) + 1;
+                            return originalThen(...args);
+                        };
+                    }
+                    return Reflect.get(target, property, target);
+                },
+            });
+            let settled = false;
+            const settle = async (result) => {
+                if (settled) {
+                    return completion.then(() => undefined);
+                }
+                settled = true;
+                if (result.kind === CHILD_PROCESS_TERMINATION_KIND.absent ||
+                    script.closesOutput === true) {
+                    chunks.end();
+                }
+                try {
+                    if (result.kind === CHILD_PROCESS_TERMINATION_KIND.absent) {
+                        await lifecycle.afterTermination(liveOrOfflineEvidence(identity, result));
+                    }
+                    resolveCompletion(result);
+                }
+                catch (error) {
+                    rejectCompletion(error);
+                }
+            };
+            const failCompletion = () => {
+                if (settled)
+                    return;
+                settled = true;
+                chunks.end();
+                rejectCompletion(script.completionFailure);
+            };
+            if (script.waitsForTermination !== true) {
+                if (script.completionFailure !== undefined) {
+                    failCompletion();
+                }
+                else {
+                    void settle(script.completion ?? DEFAULT_COMPLETION);
+                }
+            }
+            let requested = null;
+            const output = {
+                [Symbol.asyncIterator]: () => {
+                    const iterator = chunks[Symbol.asyncIterator]();
+                    return {
+                        next: () => script.chunkFailure === undefined
+                            ? iterator.next()
+                            : Promise.reject(script.chunkFailure),
+                        return: async () => {
+                            outputReturns[spawnIndex] = (outputReturns[spawnIndex] ?? 0) + 1;
+                            chunks.end();
+                            return { value: undefined, done: true };
+                        },
+                    };
+                },
+            };
+            return {
+                chunks: output,
+                completion: publicCompletion,
+                requestTermination: () => {
+                    requested ??= (async () => {
+                        terminationRequests[spawnIndex] =
+                            (terminationRequests[spawnIndex] ?? 0) + 1;
+                        await settle(script.requestCompletion ?? DEFAULT_REQUEST_COMPLETION);
+                        return completion;
+                    })();
+                    return requested;
+                },
+            };
+        },
+        recovery: {
+            recover: async (identity, lifecycle) => {
+                recoveryCalls.push(identity);
+                const result = recoveries.shift() ?? DEFAULT_RECOVERY;
+                if (result.kind === CHILD_PROCESS_TERMINATION_KIND.absent &&
+                    result.proof !== CHILD_PROCESS_ABSENCE_PROOF.releasedReceipt) {
+                    await lifecycle.afterTermination(offlineAbsenceEvidence(identity, result.proof));
+                }
+                return result;
+            },
+        },
+    };
+}
+function liveOrOfflineEvidence(identity, result) {
+    if (result.kind === CHILD_PROCESS_TERMINATION_KIND.absent &&
+        result.workerExit !== null) {
+        return {
+            kind: CHILD_PROCESS_TERMINATION_EVIDENCE_KIND.liveChildClose,
+            identity,
+            proof: result.proof,
+            workerExit: result.workerExit,
+        };
+    }
+    if (result.kind !== CHILD_PROCESS_TERMINATION_KIND.absent) {
+        throw new Error("Only absent completion may close a child lifecycle.");
+    }
+    return offlineAbsenceEvidence(identity, result.proof);
+}
+function offlineAbsenceEvidence(identity, proof) {
+    return {
+        kind: CHILD_PROCESS_TERMINATION_EVIDENCE_KIND.offlineAbsence,
+        identity,
+        proof,
+    };
+}

package/dist/testing/fake-exec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fake-exec.d.ts","sourceRoot":"","sources":["../../src/testing/fake-exec.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,IAAI,EACJ,SAAS,EACT,QAAQ,EACR,gBAAgB,EAEhB,2BAA2B,EAC5B,MAAM,kBAAkB,CAAC;AAG1B,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,6DAA6D;IAC7D,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,OAAO,CAAC,EAAE,CACR,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE;QACR,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,IAAI,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;KAC5B,KACE,IAAI,CAAC;CACX,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG,IAAI,GAAG;IAC5B,QAAQ,CAAC,MAAM,EAAE,CAAC,gBAAgB,GAAG,2BAA2B,CAAC,EAAE,CAAC;IACpE,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,CAAC;IACjC,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACvC,CAAC;AAEF,wBAAgB,QAAQ,CAAC,OAAO,GAAE,cAAc,EAAO,GAAG,QAAQ,CA4EjE"}
+{"version":3,"file":"fake-exec.d.ts","sourceRoot":"","sources":["../../src/testing/fake-exec.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,IAAI,EACJ,SAAS,EACT,QAAQ,EACR,gBAAgB,EAEhB,2BAA2B,EAC5B,MAAM,kBAAkB,CAAC;AAG1B,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,6DAA6D;IAC7D,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,OAAO,CAAC,EAAE,CACR,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE;QACR,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,IAAI,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;KAC5B,KACE,IAAI,CAAC;CACX,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG,IAAI,GAAG;IAC5B,QAAQ,CAAC,MAAM,EAAE,CAAC,gBAAgB,GAAG,2BAA2B,CAAC,EAAE,CAAC;IACpE,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,CAAC;IACjC,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACvC,CAAC;AAWF,wBAAgB,QAAQ,CAAC,OAAO,GAAE,cAAc,EAAO,GAAG,QAAQ,CAmFjE"}

package/dist/testing/fake-exec.js

@@ -1,69 +1,79 @@
 import { AsyncQueue } from "../core/async-queue.js";
 import { OUTPUT_CHANNEL, PROCESS_SIGNAL } from "../core/values.js";
+function resolveFakeCommand(missingCommands, command) {
+    return Promise.resolve(missingCommands.has(command) ? null : `/fake/bin/${command}`);
+}
 export function fakeExec(scripts = []) {
     const remaining = [...scripts];
     const spawns = [];
     const stdinWrites = [];
     const kills = [];
     const missingCommands = new Set();
+    const spawnFake = (options) => {
+        spawns.push(options);
+        const script = remaining.shift() ?? {};
+        const killSignals = [];
+        const writes = [];
+        kills.push(killSignals);
+        stdinWrites.push(writes);
+        const chunks = new AsyncQueue();
+        let settleExit = () => { };
+        const exit = new Promise((resolve) => {
+            settleExit = resolve;
+        });
+        let settleTermination = () => { };
+        const termination = new Promise((resolve) => {
+            settleTermination = resolve;
+        });
+        let finished = false;
+        const finish = (value) => {
+            if (finished) {
+                return;
+            }
+            finished = true;
+            chunks.end();
+            settleTermination();
+            settleExit(value);
+        };
+        const controls = {
+            stdout: (text) => chunks.push({ channel: OUTPUT_CHANNEL.stdout, text }),
+            stderr: (text) => chunks.push({ channel: OUTPUT_CHANNEL.stderr, text }),
+            exit: finish,
+        };
+        for (const chunk of script.chunks ?? []) {
+            chunks.push(chunk);
+        }
+        if (script.hang !== true) {
+            finish({
+                code: script.exitCode ?? 0,
+                signal: script.exitSignal ?? null,
+            });
+        }
+        return {
+            chunks,
+            exit,
+            writeStdin: (text) => {
+                writes.push(text);
+                script.onWrite?.(text, controls);
+            },
+            endStdin: () => { },
+            kill: (signal) => {
+                killSignals.push(signal);
+                if (signal === PROCESS_SIGNAL.sigterm &&
+                    script.ignoreSigterm === true) {
+                    return;
+                }
+                finish({ code: null, signal });
+            },
+            awaitTerminationEscalation: () => termination,
+        };
+    };
     return {
         spawns,
         stdinWrites,
         kills,
         missingCommands,
-        which: (command) => Promise.resolve(missingCommands.has(command) ? null : `/fake/bin/${command}`),
-        spawn: (options) => {
-            spawns.push(options);
-            const script = remaining.shift() ?? {};
-            const killSignals = [];
-            const writes = [];
-            kills.push(killSignals);
-            stdinWrites.push(writes);
-            const chunks = new AsyncQueue();
-            for (const chunk of script.chunks ?? []) {
-                chunks.push(chunk);
-            }
-            let settleExit = () => { };
-            const exit = new Promise((resolve) => {
-                settleExit = resolve;
-            });
-            let finished = false;
-            const finish = (value) => {
-                if (finished) {
-                    return;
-                }
-                finished = true;
-                chunks.end();
-                settleExit(value);
-            };
-            const controls = {
-                stdout: (text) => chunks.push({ channel: OUTPUT_CHANNEL.stdout, text }),
-                stderr: (text) => chunks.push({ channel: OUTPUT_CHANNEL.stderr, text }),
-                exit: finish,
-            };
-            if (script.hang !== true) {
-                finish({
-                    code: script.exitCode ?? 0,
-                    signal: script.exitSignal ?? null,
-                });
-            }
-            return {
-                chunks,
-                exit,
-                writeStdin: (text) => {
-                    writes.push(text);
-                    script.onWrite?.(text, controls);
-                },
-                endStdin: () => { },
-                kill: (signal) => {
-                    killSignals.push(signal);
-                    if (signal === PROCESS_SIGNAL.sigterm &&
-                        script.ignoreSigterm === true) {
-                        return;
-                    }
-                    finish({ code: null, signal });
-                },
-            };
-        },
+        which: (command) => resolveFakeCommand(missingCommands, command),
+        spawn: spawnFake,
     };
 }

package/dist/testing/index.d.ts

@@ -5,6 +5,7 @@
  */
 export { FAKE_AGENT_BEHAVIOR_KIND, type FakeAgentBehavior, type FakeAgentCall, type FakeAgentDefinition, fakeAgent, } from "./fake-agent.js";
 export { type FakeClock, fakeClock } from "./fake-clock.js";
+export { createFakeControlledExec, type FakeControlledExec, type FakeControlledExecScript, } from "./fake-controlled-exec.js";
 export { type FakeExec, type FakeExecScript, fakeExec } from "./fake-exec.js";
 export { fakeSecretResolver } from "./fake-secrets.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,wBAAwB,EACxB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,SAAS,GACV,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,KAAK,SAAS,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,cAAc,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,wBAAwB,EACxB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,SAAS,GACV,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,KAAK,SAAS,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EACL,wBAAwB,EACxB,KAAK,kBAAkB,EACvB,KAAK,wBAAwB,GAC9B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,cAAc,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/testing/index.js

@@ -5,5 +5,6 @@
  */
 export { FAKE_AGENT_BEHAVIOR_KIND, fakeAgent, } from "./fake-agent.js";
 export { fakeClock } from "./fake-clock.js";
+export { createFakeControlledExec, } from "./fake-controlled-exec.js";
 export { fakeExec } from "./fake-exec.js";
 export { fakeSecretResolver } from "./fake-secrets.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alpacakit/agents",
-  "version": "0.1.0-beta.19",
+  "version": "0.1.0-beta.21",
   "description": "Run AI coding agents programmatically: execute, stream, classify failures, fail over.",
   "license": "MIT",
   "type": "module",
@@ -49,7 +49,7 @@
   },
   "dependencies": {
     "zod": "^4.3.6",
-    "@alpacakit/core": "0.1.0-beta.19"
+    "@alpacakit/core": "0.1.0-beta.21"
   },
   "devDependencies": {
     "typescript": "^5.9.3",