@alpacakit/agents 0.1.0-beta.31 → 0.1.0-beta.36

package/README.md

@@ -65,6 +65,13 @@ for await (const event of handle.events) {
 const result = await handle; // await handle === await handle.result
 ```
 
+For an isolated Claude Code invocation, construct the adapter with
+`claude({ customizations: "disabled" })`. It passes `--safe-mode`,
+`--strict-mcp-config`, and `--no-session-persistence`, so Claude does not load
+the user's CLAUDE.md, skills, plugins, hooks, MCP servers, or custom commands;
+authentication remains available and the session is not persisted. Plain
+`claude()` keeps the CLI's inherited customization behavior.
+
 ### Controlled child lifecycle
 
 Embedding hosts that need durable custody of CLI workers create a
@@ -114,6 +121,21 @@ 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.
 
+Prompt bytes use the v2 controlled-process protocol. The bounded control
+frame carries only a UTF-8 byte length and SHA-256 digest; a dedicated data FD
+streams the bytes through the supervisor and shim to worker stdin with
+backpressure. A process is not ready until the shim has verified the exact
+length and digest and worker stdin has closed successfully. The old protocol
+that embedded stdin in the JSON bootstrap is not accepted. Launch transfer
+uses the configured host-idle timeout as its deadline, so a peer that never
+consumes stdin cannot leave the launch pending indefinitely.
+
+Launch transport failures throw `AgentError` with code
+`controlled_process_launch`. Its data contains the stable `failureCode`,
+`retryability`, transfer `stage`, and declared/observed byte counts, so hosts
+can route permanent contract failures separately from transient pipe or early
+exit failures without parsing messages.
+
 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.
@@ -144,6 +166,9 @@ const { output } = await runtime.agent("claude").run({
 `agent.run({ ..., contract })` returns an awaitable handle: `await` it
 for the result, or iterate `.events` to stream every repair attempt's run
 events as they happen (`for await (const event of handle.events) …`).
+Default repair attempts send only the invalid block, concise diagnostics, and
+a request for the original required shape; they do not repeat the original
+task or contract text.
 
 ## Failover across credentials and agents
 
@@ -253,19 +278,24 @@ Family-specific conventions (a fixed path env var + a keyring service)
 belong in the consumer's own convention module, not in this package — they
 are a plain instance of the same preset shape.
 
-## Host plane: skills & MCP (operator)
+## Host plane: execution availability, skills & MCP (operator)
+
+Agents expose an optional `agent.availability` facet for ambient execution
+readiness. CLI definitions receive a PATH-only default; Claude and Codex also
+run their vendor authentication-status commands with the bound `HostContext`
+environment unchanged. The result distinguishes runnable, unavailable, and
+indeterminate states and includes definition-owned remediation where relevant.
 
-Agents expose optional `agent.skills` / `agent.mcp` / `agent.doctor`
-facets for provisioning and health checks. This surface is still
-aspirational: the first slice covers Claude local-dir skills and
-Claude / Codex stdio MCP registration; broad inventory and availability
-listing are in progress.
+The separate optional `agent.skills` / `agent.mcp` / `agent.doctor` facets
+cover provisioning and health checks. Claude local-dir skills and Claude /
+Codex stdio MCP registration are implemented; broad inventory listing for
+installed skills and MCP servers remains in progress.
 
 ## Package entries
 
 | Entry | Contents |
 |---|---|
-| `.` | runtime, fleet, structured output, auth materials, guards, errors, and every extension point |
+| `.` | runtime, ambient execution availability, fleet, structured output, auth materials, guards, errors, and every extension point |
 | `/config` | machine-local profile / agent-settings / fleet-state storage |
 | `/config/xdg` | XDG Base Directory config-root preset (general apps) |
 | `/config/extension` | custom agent-config kinds (`defineAgentConfigType`) |
@@ -276,9 +306,9 @@ listing are in progress.
 ## Status
 
 Implemented: kernel (runtime, run handle, guards, classification), CLI
-blueprint with built-in `claude()` / `codex()`, structured output with
-repair, fleet with cooldown / auth-mark stores, auth materials and secret
-resolvers, `openaiCompatible` (engine port; the built-in HTTP
+blueprint with built-in `claude()` / `codex()`, ambient execution availability,
+structured output with repair, fleet with cooldown / auth-mark stores, auth
+materials and secret resolvers, `openaiCompatible` (engine port; the built-in HTTP
 chat-completions engine is the dependency-free default), and the first
 host-plane skill / MCP implementations (Claude local-dir skills plus
 Claude / Codex stdio MCP registration). Not yet implemented: the

package/dist/agents/claude.d.ts

@@ -1,5 +1,5 @@
 /**
- * Built-in claude adapter (v1 E1/E2 argv kept verbatim):
+ * Built-in claude CLI contract:
  * `claude -p [--model m] [--effort e] --output-format stream-json
  *  --permission-mode <mode> [tool args] --verbose`, prompt on stdin.
  * Read-only grants map to `--allowedTools` (`Bash(cmd:*)` for shell
@@ -16,5 +16,12 @@ export declare const CLAUDE_API_KEY_ENV_VAR = "ANTHROPIC_API_KEY";
  * the same stream format.
  */
 export declare function structuredQuotaMatcher(): FailureMatcher;
-export declare function claude(): AgentDefinition<"claude">;
+export type ClaudeOptions = {
+    /**
+     * `disabled` prevents loading user customizations while retaining auth and
+     * disables session persistence. The default `inherit` preserves CLI behavior.
+     */
+    readonly customizations?: "inherit" | "disabled";
+};
+export declare function claude(options?: ClaudeOptions): AgentDefinition<"claude">;
 //# sourceMappingURL=claude.d.ts.map

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;AAoSD,wBAAgB,MAAM,IAAI,eAAe,CAAC,QAAQ,CAAC,CAyDlD"}
+{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/agents/claude.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA8CH,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;AAsK1D;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,cAAc,CA0CvD;AAoSD,MAAM,MAAM,aAAa,GAAG;IAC1B;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,GAAG,UAAU,CAAC;CAClD,CAAC;AAEF,wBAAgB,MAAM,CAAC,OAAO,GAAE,aAAkB,GAAG,eAAe,CAAC,QAAQ,CAAC,CA2E7E"}

package/dist/agents/claude.js

@@ -1,5 +1,5 @@
 /**
- * Built-in claude adapter (v1 E1/E2 argv kept verbatim):
+ * Built-in claude CLI contract:
  * `claude -p [--model m] [--effort e] --output-format stream-json
  *  --permission-mode <mode> [tool args] --verbose`, prompt on stdin.
  * Read-only grants map to `--allowedTools` (`Bash(cmd:*)` for shell
@@ -15,6 +15,7 @@ import { isErrnoCode } from "../core/fs.js";
 import { readBoolean, readJsonRecord, readNumber, readRecord, readString, readUnknownRecord, } from "../core/json.js";
 import { AGENT_EVENT_TYPE } from "../core/run.js";
 import { TEXT_ENCODING } from "../core/values.js";
+import { cliAvailability } from "../host/availability.js";
 import { INSTALL_STATUS, MCP_TRANSPORT, SKILL_SOURCE_KIND, } from "../host/capabilities.js";
 import { withStagedGithubDirectory, } from "../host/github-dir.js";
 import { listMcpServersViaCli } from "../host/mcp-list.js";
@@ -39,9 +40,13 @@ const CLAUDE = {
         verbose: "--verbose",
         tools: "--tools",
         allowedTools: "--allowedTools",
+        safeMode: "--safe-mode",
+        strictMcpConfig: "--strict-mcp-config",
+        noSessionPersistence: "--no-session-persistence",
     },
     auth: {
         statusArgs: ["auth", "status", "--json"],
+        loginArgs: ["auth", "login", "--claudeai"],
     },
     mcp: {
         addJson: "add-json",
@@ -97,13 +102,20 @@ function grantToToolArg(grant) {
         ? `Bash(${grant.command}:*)`
         : grant.name;
 }
-function sharedArgs(ctx) {
+function sharedArgs(ctx, customizations) {
     return [
         CLAUDE.cli.prompt,
         ...(ctx.model === null ? [] : [CLAUDE.cli.model, ctx.model]),
         ...(ctx.effort === null ? [] : [CLAUDE.cli.effort, ctx.effort]),
         CLAUDE.cli.outputFormat,
         CLAUDE.cli.streamJson,
+        ...(customizations === "disabled"
+            ? [
+                CLAUDE.cli.safeMode,
+                CLAUDE.cli.strictMcpConfig,
+                CLAUDE.cli.noSessionPersistence,
+            ]
+            : []),
     ];
 }
 function parseClaudeLine(line) {
@@ -426,19 +438,20 @@ async function removeClaudeMcp(ctx, name, options) {
 async function listClaudeMcp(ctx) {
     return listMcpServersViaCli(ctx, { command: CLAUDE.command });
 }
-export function claude() {
+export function claude(options = {}) {
+    const customizations = options.customizations ?? "inherit";
     return defineCliAgent({
         id: CLAUDE.id,
         command: CLAUDE.command,
         args: {
             [SANDBOX_MODE.full]: (_sandbox, ctx) => [
-                ...sharedArgs(ctx),
+                ...sharedArgs(ctx, customizations),
                 CLAUDE.cli.permissionMode,
                 CLAUDE.cli.bypassPermissions,
                 CLAUDE.cli.verbose,
             ],
             [SANDBOX_MODE.readOnly]: (sandbox, ctx) => [
-                ...sharedArgs(ctx),
+                ...sharedArgs(ctx, customizations),
                 CLAUDE.cli.permissionMode,
                 CLAUDE.cli.defaultPermissionMode,
                 ...(sandbox.grants.length === 0
@@ -455,6 +468,23 @@ export function claude() {
         classify: [structuredQuotaMatcher()],
         // F6: Claude CLI can report a structured quota rejection on exit 0.
         classifyOnSuccess: [structuredQuotaMatcher()],
+        availability: cliAvailability({
+            command: CLAUDE.command,
+            commandMissingRemediation: {
+                detail: "Install Claude Code and ensure `claude` is on PATH.",
+                command: null,
+            },
+            authentication: {
+                args: CLAUDE.auth.statusArgs,
+                remediation: {
+                    detail: "Sign in to Claude Code.",
+                    command: {
+                        executable: CLAUDE.command,
+                        args: CLAUDE.auth.loginArgs,
+                    },
+                },
+            },
+        }),
         auth: {
             [AUTH_MATERIAL_KIND.homeDir]: homeDirHandler,
             [AUTH_MATERIAL_KIND.apiKey]: envVarAuthMaterial({

package/dist/agents/codex.d.ts

@@ -1,5 +1,5 @@
 /**
- * Built-in codex adapter (v1 E1/E2 argv kept verbatim):
+ * Built-in codex CLI contract:
  * `codex exec [--model m] [-c model_reasoning_effort="e"] --json
  *  --skip-git-repo-check --sandbox <mode> -C <workspace>`, prompt on
  * stdin. Codex sandboxing is filesystem-level, so read-only grants have

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;AAiND,wBAAgB,KAAK,IAAI,eAAe,CAAC,OAAO,CAAC,CAoEhD"}
+{"version":3,"file":"codex.d.ts","sourceRoot":"","sources":["../../src/agents/codex.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAyCH,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,CAqFhD"}

package/dist/agents/codex.js

@@ -1,5 +1,5 @@
 /**
- * Built-in codex adapter (v1 E1/E2 argv kept verbatim):
+ * Built-in codex CLI contract:
  * `codex exec [--model m] [-c model_reasoning_effort="e"] --json
  *  --skip-git-repo-check --sandbox <mode> -C <workspace>`, prompt on
  * stdin. Codex sandboxing is filesystem-level, so read-only grants have
@@ -14,6 +14,7 @@ import { CODEX_APP_SERVER_METHOD } from "../codex/protocol.js";
 import { AGENT_ERROR_CODE, AgentError, AUTH_FAILURE_REASON, } from "../core/error.js";
 import { readJsonRecord, readRecord, readString } from "../core/json.js";
 import { AGENT_EVENT_TYPE } from "../core/run.js";
+import { cliAvailability } from "../host/availability.js";
 import { INSTALL_STATUS, MCP_SCOPE, MCP_TRANSPORT, SKILL_SOURCE_KIND, } from "../host/capabilities.js";
 import { runHostCommand } from "../host/run-command.js";
 import { parseCooldownHint } from "../kernel/classify.js";
@@ -315,6 +316,23 @@ export function codex() {
                 readString(record, CODEX.json.field.type) ===
                     CODEX.json.event.turnCompleted);
         },
+        availability: cliAvailability({
+            command: CODEX.command,
+            commandMissingRemediation: {
+                detail: "Install Codex and ensure `codex` is on PATH.",
+                command: null,
+            },
+            authentication: {
+                args: CODEX.auth.statusArgs,
+                remediation: {
+                    detail: "Sign in to Codex.",
+                    command: {
+                        executable: CODEX.command,
+                        args: CODEX.auth.oauthLoginArgs,
+                    },
+                },
+            },
+        }),
         auth: {
             [AUTH_MATERIAL_KIND.homeDir]: envVarAuthMaterial({
                 set: (material) => ({ [CODEX_HOME_ENV_VAR]: material.path }),

package/dist/core/error.d.ts

@@ -13,6 +13,7 @@ export declare const AGENT_ERROR_CODE: {
     readonly limit: "limit";
     readonly cancelled: "cancelled";
     readonly outputRejected: "output_rejected";
+    readonly controlledProcessLaunch: "controlled_process_launch";
     readonly failed: "failed";
 };
 export type AgentErrorCode = (typeof AGENT_ERROR_CODE)[keyof typeof AGENT_ERROR_CODE];
@@ -23,6 +24,7 @@ export declare const AGENT_FAILURE_CLASS: {
 export type AgentFailureClass = (typeof AGENT_FAILURE_CLASS)[keyof typeof AGENT_FAILURE_CLASS];
 export declare const AGENT_INFRASTRUCTURE_FAILURE_CODE: {
     readonly controlledProcessLifecycle: "controlled_process_lifecycle";
+    readonly controlledProcessLaunch: "controlled_process_launch";
 };
 export type AgentInfrastructureFailureCode = (typeof AGENT_INFRASTRUCTURE_FAILURE_CODE)[keyof typeof AGENT_INFRASTRUCTURE_FAILURE_CODE];
 export type AgentFailureCode = AgentErrorCode | AgentInfrastructureFailureCode;
@@ -69,6 +71,28 @@ export type Issue = {
     code: string;
     message: string;
 };
+export declare const CONTROLLED_PROCESS_LAUNCH_FAILURE_CODE: {
+    readonly inputEarlyEof: "input_early_eof";
+    readonly inputOverrun: "input_overrun";
+    readonly inputDigestMismatch: "input_digest_mismatch";
+    readonly inputWriteFailed: "input_write_failed";
+    readonly inputTransferTimeout: "input_transfer_timeout";
+    readonly workerExited: "worker_exited_during_launch";
+    readonly protocolViolation: "protocol_violation";
+};
+export type ControlledProcessLaunchFailureCode = (typeof CONTROLLED_PROCESS_LAUNCH_FAILURE_CODE)[keyof typeof CONTROLLED_PROCESS_LAUNCH_FAILURE_CODE];
+export declare const CONTROLLED_PROCESS_LAUNCH_FAILURE_RETRYABILITY: {
+    readonly permanent: "permanent";
+    readonly transient: "transient";
+};
+export type ControlledProcessLaunchFailureRetryability = (typeof CONTROLLED_PROCESS_LAUNCH_FAILURE_RETRYABILITY)[keyof typeof CONTROLLED_PROCESS_LAUNCH_FAILURE_RETRYABILITY];
+export type ControlledProcessLaunchFailureData = {
+    readonly failureCode: ControlledProcessLaunchFailureCode;
+    readonly retryability: ControlledProcessLaunchFailureRetryability;
+    readonly stage: "host_to_supervisor" | "supervisor_to_shim" | "shim_to_worker" | "control_protocol";
+    readonly expectedBytes: number | null;
+    readonly actualBytes: number | null;
+};
 export type AgentErrorData = {
     [AGENT_ERROR_CODE.invalidInput]: {
         reason: string;
@@ -100,6 +124,7 @@ export type AgentErrorData = {
         issues: Issue[];
         attempts: number;
     };
+    [AGENT_ERROR_CODE.controlledProcessLaunch]: ControlledProcessLaunchFailureData;
     [AGENT_ERROR_CODE.failed]: {
         exitCode: number | null;
         stdoutTail: string | null;

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

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

package/dist/core/error.js

@@ -13,6 +13,7 @@ export const AGENT_ERROR_CODE = {
     limit: "limit",
     cancelled: "cancelled",
     outputRejected: "output_rejected",
+    controlledProcessLaunch: "controlled_process_launch",
     failed: "failed",
 };
 export const AGENT_FAILURE_CLASS = {
@@ -21,6 +22,7 @@ export const AGENT_FAILURE_CLASS = {
 };
 export const AGENT_INFRASTRUCTURE_FAILURE_CODE = {
     controlledProcessLifecycle: "controlled_process_lifecycle",
+    controlledProcessLaunch: "controlled_process_launch",
 };
 export function agentFailure(failureCode) {
     return {
@@ -56,6 +58,19 @@ export const TIMEOUT_KIND = {
     total: "total",
     idle: "idle",
 };
+export const CONTROLLED_PROCESS_LAUNCH_FAILURE_CODE = {
+    inputEarlyEof: "input_early_eof",
+    inputOverrun: "input_overrun",
+    inputDigestMismatch: "input_digest_mismatch",
+    inputWriteFailed: "input_write_failed",
+    inputTransferTimeout: "input_transfer_timeout",
+    workerExited: "worker_exited_during_launch",
+    protocolViolation: "protocol_violation",
+};
+export const CONTROLLED_PROCESS_LAUNCH_FAILURE_RETRYABILITY = {
+    permanent: "permanent",
+    transient: "transient",
+};
 const AGENT_ERROR_BRAND = Symbol.for("@alpacakit/agents.AgentError");
 export class AgentError extends Error {
     code;

package/dist/core/node-controlled-exec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node-controlled-exec.d.ts","sourceRoot":"","sources":["../../src/core/node-controlled-exec.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EACtB,MAAM,yBAAyB,CAAC;AAajC,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,qBAAqB,GAC7B,cAAc,CA0BhB"}
+{"version":3,"file":"node-controlled-exec.d.ts","sourceRoot":"","sources":["../../src/core/node-controlled-exec.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,cAAc,EACd,qBAAqB,EACtB,MAAM,yBAAyB,CAAC;AAmBjC,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,qBAAqB,GAC7B,cAAc,CAgDhB"}

package/dist/core/node-controlled-exec.js

@@ -1,5 +1,7 @@
 import path from "node:path";
 import { launchControlledProcess, recoverControlledProcess, } from "../internal/controlled-process/host-controller.js";
+import { ControlledProcessLaunchError } from "../internal/controlled-process/input-transport.js";
+import { AGENT_ERROR_CODE, AGENT_INFRASTRUCTURE_FAILURE_CODE, AgentError, infrastructureFailure, } from "./error.js";
 import { withNodeBinFirst } from "./node-ports.js";
 const PACKAGE_ROOT = path.resolve(import.meta.dirname, "../..");
 const SUPERVISOR_ENTRY_PATH = path.join(PACKAGE_ROOT, "dist/internal/controlled-process/supervisor-entry.js");
@@ -7,14 +9,35 @@ const SHIM_ENTRY_PATH = path.join(PACKAGE_ROOT, "dist/internal/controlled-proces
 export function createControlledExec(options) {
     return {
         spawn: async (worker, lifecycle) => {
-            const process = await launchControlledProcess({
-                supervisorEntryPath: SUPERVISOR_ENTRY_PATH,
-                shimEntryPath: SHIM_ENTRY_PATH,
-                runtimeDirectory: options.runtimeDirectory,
-                worker: { ...worker, env: withNodeBinFirst(worker.env) },
-                timing: options.termination,
-                lifecycle,
-            });
+            let process;
+            try {
+                process = await launchControlledProcess({
+                    supervisorEntryPath: SUPERVISOR_ENTRY_PATH,
+                    shimEntryPath: SHIM_ENTRY_PATH,
+                    runtimeDirectory: options.runtimeDirectory,
+                    worker: { ...worker, env: withNodeBinFirst(worker.env) },
+                    timing: options.termination,
+                    lifecycle,
+                });
+            }
+            catch (error) {
+                if (!(error instanceof ControlledProcessLaunchError)) {
+                    throw error;
+                }
+                throw new AgentError({
+                    code: AGENT_ERROR_CODE.controlledProcessLaunch,
+                    classification: infrastructureFailure(AGENT_INFRASTRUCTURE_FAILURE_CODE.controlledProcessLaunch),
+                    message: error.message,
+                    data: {
+                        failureCode: error.failure.code,
+                        retryability: error.failure.retryability,
+                        stage: error.failure.stage,
+                        expectedBytes: error.failure.expectedBytes,
+                        actualBytes: error.failure.actualBytes,
+                    },
+                    cause: error,
+                });
+            }
             return {
                 chunks: process.chunks,
                 completion: process.completion,

package/dist/core/node-ports.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node-ports.d.ts","sourceRoot":"","sources":["../../src/core/node-ports.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,KAAK,EACV,KAAK,EACL,IAAI,EAIJ,UAAU,EAGX,MAAM,YAAY,CAAC;AAOpB,eAAO,MAAM,WAAW,EAAE,KAOzB,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,UAEvB,CAAC;AAoBF,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC1B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUxB;AAyGD,eAAO,MAAM,QAAQ,EAAE,IAGtB,CAAC"}
+{"version":3,"file":"node-ports.d.ts","sourceRoot":"","sources":["../../src/core/node-ports.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,KAAK,EACV,KAAK,EACL,IAAI,EAIJ,UAAU,EAGX,MAAM,YAAY,CAAC;AAOpB,eAAO,MAAM,WAAW,EAAE,KAOzB,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,UAEvB,CAAC;AAoBF,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC1B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUxB;AA+HD,eAAO,MAAM,QAAQ,EAAE,IAGtB,CAAC"}

package/dist/core/node-ports.js

@@ -49,8 +49,12 @@ export function withNodeBinFirst(env) {
     return { ...env, [key]: [nodeBinDir, ...rest].join(path.delimiter) };
 }
 function spawnProcess(options) {
+    if (options.processGroup === true && process.platform === "win32") {
+        throw new Error("Process-group execution is not supported on Windows.");
+    }
     const child = spawn(options.command, options.args, {
         cwd: options.cwd,
+        detached: options.processGroup === true,
         env: withNodeBinFirst(options.env),
         stdio: ["pipe", "pipe", "pipe"],
     });
@@ -103,11 +107,27 @@ function spawnProcess(options) {
             child.stdin.end();
         },
         kill: (signal) => {
+            if (options.processGroup === true && child.pid !== undefined) {
+                try {
+                    process.kill(-child.pid, signal);
+                }
+                catch (error) {
+                    if (!isErrnoCode(error, "ESRCH")) {
+                        throw error;
+                    }
+                }
+                return;
+            }
             child.kill(signal);
         },
         awaitTerminationEscalation: () => termination,
     };
 }
+function isErrnoCode(error, code) {
+    return (error instanceof Error &&
+        "code" in error &&
+        error.code === code);
+}
 function isExecutable(candidate) {
     return new Promise((resolve) => {
         access(candidate, constants.X_OK, (error) => {

package/dist/core/ports.d.ts

@@ -23,6 +23,11 @@ export type ExecSpawnOptions = {
     cwd: string;
     env: Record<string, string>;
     stdin: string | null;
+    /**
+     * Start an independent process group and signal that group from kill().
+     * The built-in Node adapter rejects this option on Windows.
+     */
+    processGroup?: boolean;
 };
 /** Interactive spawn: stdin stays open for incremental writes. */
 export type InteractiveExecSpawnOptions = ExecSpawnOptions & {

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

@@ -1 +1 @@
-{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../../src/core/ports.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEhE,YAAY,EACV,KAAK,EACL,UAAU,EACV,cAAc,EACd,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,MAAM,SAAS,GAAG;IAAE,OAAO,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjE,MAAM,MAAM,QAAQ,GAAG;IAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAEtE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB,CAAC;AAEF,kEAAkE;AAClE,MAAM,MAAM,2BAA2B,GAAG,gBAAgB,GAAG;IAC3D,aAAa,EAAE,IAAI,CAAC;CACrB,CAAC;AAEF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IACjC,IAAI,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAAC;IAClC;;;OAGG;IACH,0BAA0B,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C;AAED,+EAA+E;AAC/E,MAAM,WAAW,sBAAuB,SAAQ,WAAW;IACzD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,IAAI,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,IAAI;IACnB,KAAK,CAAC,OAAO,EAAE,2BAA2B,GAAG,sBAAsB,CAAC;IACpE,KAAK,CAAC,OAAO,EAAE,gBAAgB,GAAG,WAAW,CAAC;IAC9C,wEAAwE;IACxE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC7E;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,SAAS,EAAE,YAAY,GAAG,IAAI,CAAC;CACrC;AAED,eAAO,MAAM,SAAS;;;;;CAKZ,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAElE,MAAM,WAAW,MAAM;IACrB,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC7D;AAED,uDAAuD;AACvD,MAAM,MAAM,KAAK,GAAG;IAClB,IAAI,EAAE,IAAI,CAAC;IACX,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,eAAe,CAAC;IACzB,IAAI,EAAE,UAAU,CAAC;IACjB,SAAS,EAAE,aAAa,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,aAE3B,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,MAExB,CAAC"}
+{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../../src/core/ports.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEhE,YAAY,EACV,KAAK,EACL,UAAU,EACV,cAAc,EACd,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,MAAM,SAAS,GAAG;IAAE,OAAO,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjE,MAAM,MAAM,QAAQ,GAAG;IAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAEtE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF,kEAAkE;AAClE,MAAM,MAAM,2BAA2B,GAAG,gBAAgB,GAAG;IAC3D,aAAa,EAAE,IAAI,CAAC;CACrB,CAAC;AAEF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IACjC,IAAI,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAAC;IAClC;;;OAGG;IACH,0BAA0B,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C;AAED,+EAA+E;AAC/E,MAAM,WAAW,sBAAuB,SAAQ,WAAW;IACzD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,IAAI,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,IAAI;IACnB,KAAK,CAAC,OAAO,EAAE,2BAA2B,GAAG,sBAAsB,CAAC;IACpE,KAAK,CAAC,OAAO,EAAE,gBAAgB,GAAG,WAAW,CAAC;IAC9C,wEAAwE;IACxE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC7E;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,SAAS,EAAE,YAAY,GAAG,IAAI,CAAC;CACrC;AAED,eAAO,MAAM,SAAS;;;;;CAKZ,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAElE,MAAM,WAAW,MAAM;IACrB,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC7D;AAED,uDAAuD;AACvD,MAAM,MAAM,KAAK,GAAG;IAClB,IAAI,EAAE,IAAI,CAAC;IACX,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,eAAe,CAAC;IACzB,IAAI,EAAE,UAAU,CAAC;IACjB,SAAS,EAAE,aAAa,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,aAE3B,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,MAExB,CAAC"}

package/dist/fleet/policy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/fleet/policy.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,gBAAgB,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEzE;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc;;;CAGjB,CAAC;AAEX,MAAM,MAAM,aAAa,GACvB,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC;AAEvD,eAAO,MAAM,mBAAmB;;;;CAItB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAC3B,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,OAAO,mBAAmB,CAAC,CAAC;AAEjE,MAAM,MAAM,aAAa,GACrB;IACE,IAAI,EAAE,OAAO,mBAAmB,CAAC,QAAQ,CAAC;IAC1C,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,aAAa,CAAC;CACtB,GACD;IAAE,IAAI,EAAE,OAAO,mBAAmB,CAAC,eAAe,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,OAAO,mBAAmB,CAAC,QAAQ,CAAA;CAAE,CAAC;AAElD,MAAM,MAAM,UAAU,GAAG,OAAO,CAC9B,cAAc,EACd,OAAO,gBAAgB,CAAC,YAAY,GAAG,OAAO,gBAAgB,CAAC,SAAS,CACzE,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;AAE9D,yEAAyE;AACzE,eAAO,MAAM,yBAAyB,UAAY,CAAC;AACnD,eAAO,MAAM,4BAA4B,SAAU,CAAC;AAEpD,eAAO,MAAM,oBAAoB,EAAE,aAiBlC,CAAC;AAEF,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,SAAS,GAC5C,aAAa,CAEf"}
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/fleet/policy.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,gBAAgB,EAAE,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEzE;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc;;;CAGjB,CAAC;AAEX,MAAM,MAAM,aAAa,GACvB,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC;AAEvD,eAAO,MAAM,mBAAmB;;;;CAItB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAC3B,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,OAAO,mBAAmB,CAAC,CAAC;AAEjE,MAAM,MAAM,aAAa,GACrB;IACE,IAAI,EAAE,OAAO,mBAAmB,CAAC,QAAQ,CAAC;IAC1C,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,aAAa,CAAC;CACtB,GACD;IAAE,IAAI,EAAE,OAAO,mBAAmB,CAAC,eAAe,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,OAAO,mBAAmB,CAAC,QAAQ,CAAA;CAAE,CAAC;AAElD,MAAM,MAAM,UAAU,GAAG,OAAO,CAC9B,cAAc,EACd,OAAO,gBAAgB,CAAC,YAAY,GAAG,OAAO,gBAAgB,CAAC,SAAS,CACzE,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;AAE9D,yEAAyE;AACzE,eAAO,MAAM,yBAAyB,UAAY,CAAC;AACnD,eAAO,MAAM,4BAA4B,SAAU,CAAC;AAEpD,eAAO,MAAM,oBAAoB,EAAE,aAoBlC,CAAC;AAEF,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,SAAS,GAC5C,aAAa,CAEf"}

package/dist/fleet/policy.js

@@ -44,6 +44,9 @@ export const defaultFailurePolicy = {
     [AGENT_ERROR_CODE.limit]: { kind: FAILURE_ACTION_KIND.terminal },
     [AGENT_ERROR_CODE.failed]: { kind: FAILURE_ACTION_KIND.terminal },
     [AGENT_ERROR_CODE.outputRejected]: { kind: FAILURE_ACTION_KIND.terminal },
+    [AGENT_ERROR_CODE.controlledProcessLaunch]: {
+        kind: FAILURE_ACTION_KIND.terminal,
+    },
 };
 export function resolveFailurePolicy(overrides) {
     return { ...defaultFailurePolicy, ...overrides };

package/dist/host/availability.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Agent execution availability (ambient, not profile-bound). Definitions own
+ * vendor-specific probes and remediation; the runtime only binds HostContext.
+ */
+import type { HostContext } from "./context.js";
+export declare const AGENT_AVAILABILITY_STATUS: {
+    readonly runnable: "runnable";
+    readonly unavailable: "unavailable";
+    readonly indeterminate: "indeterminate";
+};
+export declare const AGENT_UNAVAILABLE_REASON: {
+    readonly commandMissing: "command_missing";
+    readonly authenticationRequired: "authentication_required";
+};
+export declare const AGENT_INDETERMINATE_REASON: {
+    readonly probeTimeout: "probe_timeout";
+    readonly probeFault: "probe_fault";
+};
+export type AgentRemediation = {
+    readonly detail: string;
+    readonly command: {
+        readonly executable: string;
+        readonly args: readonly string[];
+    } | null;
+};
+export type AgentAvailability = {
+    readonly status: typeof AGENT_AVAILABILITY_STATUS.runnable;
+} | {
+    readonly status: typeof AGENT_AVAILABILITY_STATUS.unavailable;
+    readonly reason: typeof AGENT_UNAVAILABLE_REASON.commandMissing | typeof AGENT_UNAVAILABLE_REASON.authenticationRequired;
+    readonly remediation: AgentRemediation | null;
+} | {
+    readonly status: typeof AGENT_AVAILABILITY_STATUS.indeterminate;
+    readonly reason: typeof AGENT_INDETERMINATE_REASON.probeTimeout | typeof AGENT_INDETERMINATE_REASON.probeFault;
+    readonly detail: string;
+};
+export interface AgentAvailabilityCapability {
+    probe(ctx: HostContext): Promise<AgentAvailability>;
+}
+/** The single bounded default for CLI availability subprocesses. */
+export declare const DEFAULT_AGENT_AVAILABILITY_PROBE_TIMEOUT_MS = 30000;
+export type CliAvailabilityOptions = {
+    readonly command: string;
+    readonly commandMissingRemediation: AgentRemediation | null;
+    readonly authentication?: {
+        readonly args: readonly string[];
+        readonly remediation: AgentRemediation | null;
+    };
+    readonly timeoutMs?: number;
+};
+/**
+ * Build a CLI definition-side availability capability. With no
+ * authentication command this is the generic PATH-only default.
+ */
+export declare function cliAvailability(options: CliAvailabilityOptions): AgentAvailabilityCapability;
+//# sourceMappingURL=availability.d.ts.map

package/dist/host/availability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"availability.d.ts","sourceRoot":"","sources":["../../src/host/availability.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,eAAO,MAAM,yBAAyB;;;;CAI5B,CAAC;AAEX,eAAO,MAAM,wBAAwB;;;CAG3B,CAAC;AAEX,eAAO,MAAM,0BAA0B;;;CAG7B,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;KAClC,GAAG,IAAI,CAAC;CACV,CAAC;AAEF,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,yBAAyB,CAAC,QAAQ,CAAA;CAAE,GAC9D;IACE,QAAQ,CAAC,MAAM,EAAE,OAAO,yBAAyB,CAAC,WAAW,CAAC;IAC9D,QAAQ,CAAC,MAAM,EACX,OAAO,wBAAwB,CAAC,cAAc,GAC9C,OAAO,wBAAwB,CAAC,sBAAsB,CAAC;IAC3D,QAAQ,CAAC,WAAW,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAC/C,GACD;IACE,QAAQ,CAAC,MAAM,EAAE,OAAO,yBAAyB,CAAC,aAAa,CAAC;IAChE,QAAQ,CAAC,MAAM,EACX,OAAO,0BAA0B,CAAC,YAAY,GAC9C,OAAO,0BAA0B,CAAC,UAAU,CAAC;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAEN,MAAM,WAAW,2BAA2B;IAC1C,KAAK,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACrD;AAED,oEAAoE;AACpE,eAAO,MAAM,2CAA2C,QAAS,CAAC;AAElE,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,yBAAyB,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC5D,QAAQ,CAAC,cAAc,CAAC,EAAE;QACxB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;QACjC,QAAQ,CAAC,WAAW,EAAE,gBAAgB,GAAG,IAAI,CAAC;KAC/C,CAAC;IACF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC;AAiHF;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,sBAAsB,GAC9B,2BAA2B,CAqE7B"}