@automatalabs/acp-agents 1.2.7 → 2.0.0

package/dist/runner.js

@@ -21,10 +21,12 @@ import { PooledConnection, ReattachCapabilityUnavailable, isChildCleanupError, }
 import { AcpAgentPool } from "./pool.js";
 import { TypedEventEmitter, } from "./events.js";
 import { InteractiveSession } from "./interactive.js";
-import { BUILTIN_BACKENDS, BUILTIN_BACKEND_IDS, builtinBackend, } from "./backends/builtins.js";
-import { CustomAcpBackend } from "./backends/custom.js";
+import { BUILTIN_BACKEND_IDS } from "./backends/builtins.js";
 import { registryWithRunBackends, resolveBackendRegistry, } from "./registry.js";
 import { mapThrownError } from "./errors-map.js";
+import { assertNoModelConfigOption, resolveModelRoute } from "./routing.js";
+import { assertSystemPromptSupported } from "./system-prompt.js";
+import { sessionRefFor } from "./session-ref.js";
 import { buildAuthDescriptor, } from "./auth/auth-types.js";
 import { AuthStore, classifyCredential, } from "./auth/auth-store.js";
 import { ProviderStore, providerVertexMeta } from "./provider-store.js";
@@ -1028,6 +1030,8 @@ export class AcpAgentRunner {
     prepareSession(opts, config) {
         const route = resolveModelRoute(opts.model ?? opts.tier, config.registry);
         const backend = route.backend;
+        // Refuse instructions the routed backend cannot carry BEFORE anything is acquired or sent.
+        const systemPrompt = assertSystemPromptSupported(backend, opts.systemPrompt, opts.label);
         const policy = {
             allow: opts.toolNames,
             deny: opts.disallowedToolNames,
@@ -1053,10 +1057,9 @@ export class AcpAgentRunner {
                 label: opts.label,
                 // Direct engine-call correlation on emitted events only; never sent on the ACP wire.
                 callIndex: opts.callIndex,
-                // CODEX-ONLY session instruction overrides -> session/new _meta bare keys. Additive;
-                // never hashed. The Claude backend ignores them.
-                baseInstructions: opts.baseInstructions,
-                developerInstructions: opts.developerInstructions,
+                // Backend-neutral system prompt instructions -> the backend's own session `_meta` keys
+                // (validated above). Additive; never hashed.
+                systemPrompt,
                 retainSessionLog: config.retainSessionLog,
             },
         };
@@ -1139,54 +1142,12 @@ async function applyModelSelection(session, spec, opts) {
     await session.selectModel(spec);
     opts.onModelResolved?.(spec);
 }
-function assertNoModelConfigOption(configOptions, label) {
-    if (!configOptions || !("model" in configOptions))
-        return;
-    throw new WorkflowError(`Agent call${label ? ` "${label}"` : ""} configOptions must not contain reserved option id "model"; use the model field instead`, WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, { recoverable: false, agentLabel: label });
-}
 /** Pick the backend for the effective model spec (`model` wins over `tier`). The first segment
  *  routes only when it is a registered custom or built-in harness name; everything else goes to
  *  the configured default backend without interpretation. */
 export function selectBackend(opts, registry) {
     return resolveModelRoute(opts.model ?? opts.tier, registry).backend;
 }
-/** Resolve routing and the verbatim model value together so backend choice and prefix stripping
- *  cannot drift. A registered custom name has priority over a built-in on collision. */
-function resolveModelRoute(spec, registry) {
-    if (spec === undefined)
-        return { backend: defaultBackend(registry), modelSpec: undefined };
-    const slash = spec.indexOf("/");
-    const firstSegment = asciiLowercase(slash >= 0 ? spec.slice(0, slash) : spec);
-    const inner = slash >= 0 ? spec.slice(slash + 1) : undefined;
-    const custom = registry?.get(firstSegment);
-    if (custom)
-        return { backend: new CustomAcpBackend(custom), modelSpec: inner };
-    const builtIn = builtinBackend(firstSegment);
-    if (builtIn)
-        return { backend: builtIn, modelSpec: inner };
-    return { backend: defaultBackend(registry), modelSpec: spec };
-}
-/** The re-attach handle for an open session: id + backend routing name + cwd + the
- *  agent-advertised reopen surface. Contains no secrets; JSON-round-trippable. `backendId`
- *  doubles as the `model` routing spec for loadSession/resumeSession/listSessions. */
-function sessionRefFor(session, backend, cwd) {
-    const caps = session.capabilities;
-    return {
-        sessionId: session.sessionId,
-        backendId: backend.id,
-        poolKey: backend.poolKey ?? backend.id,
-        ...(session.initializeMeta !== undefined
-            ? { initializeMeta: session.initializeMeta }
-            : {}),
-        cwd,
-        reopen: {
-            load: caps?.supportsLoadSession === true,
-            resume: caps?.supportsResumeSession === true,
-            list: caps?.supportsListSessions === true,
-            fork: caps?.supportsForkSession === true,
-        },
-    };
-}
 /** Interactive sessions are public and long-lived, so fail before spawning a dedicated process
  *  when the required worktree root is absent or not absolute. */
 function validateInteractiveCwd(cwd, label, methodName) {
@@ -1267,23 +1228,3 @@ async function disposeBestEffort(connection) {
         // Dedicated lifecycle processes are already no longer useful; never mask the request result.
     }
 }
-/** Resolve the default backend: a registered custom name wins (returned as a Backend), else
- *  the built-in id. An unknown/unset value falls back to "claude" (the historical default). */
-function defaultBackend(registry) {
-    const configured = process.env.AGENTPRISM_DEFAULT_BACKEND;
-    const name = configured === undefined ? undefined : asciiLowercase(configured);
-    if (name && registry) {
-        const config = registry.get(name);
-        if (config)
-            return new CustomAcpBackend(config);
-    }
-    if (name) {
-        const builtIn = builtinBackend(name);
-        if (builtIn)
-            return builtIn;
-    }
-    return BUILTIN_BACKENDS.claude.create();
-}
-function asciiLowercase(value) {
-    return value.replace(/[A-Z]/g, (character) => String.fromCharCode(character.charCodeAt(0) + 32));
-}

package/dist/session-ref.d.ts

@@ -0,0 +1,8 @@
+import type { AgentSessionRef } from "@automatalabs/shared-types";
+import type { SessionHandle } from "./acp-client.js";
+import type { Backend } from "./backend.js";
+/** The re-attach handle for an open session: id + backend routing name + cwd + the
+ *  agent-advertised reopen surface. Contains no secrets; JSON-round-trippable. `backendId`
+ *  doubles as the `model` routing spec for loadSession/resumeSession/listSessions. */
+export declare function sessionRefFor(session: SessionHandle, backend: Backend, cwd: string): AgentSessionRef;
+//# sourceMappingURL=session-ref.d.ts.map

package/dist/session-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-ref.d.ts","sourceRoot":"","sources":["../src/session-ref.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C;;sFAEsF;AACtF,wBAAgB,aAAa,CAAC,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,eAAe,CAiBpG"}

package/dist/session-ref.js

@@ -0,0 +1,21 @@
+/** The re-attach handle for an open session: id + backend routing name + cwd + the
+ *  agent-advertised reopen surface. Contains no secrets; JSON-round-trippable. `backendId`
+ *  doubles as the `model` routing spec for loadSession/resumeSession/listSessions. */
+export function sessionRefFor(session, backend, cwd) {
+    const caps = session.capabilities;
+    return {
+        sessionId: session.sessionId,
+        backendId: backend.id,
+        poolKey: backend.poolKey ?? backend.id,
+        ...(session.initializeMeta !== undefined
+            ? { initializeMeta: session.initializeMeta }
+            : {}),
+        cwd,
+        reopen: {
+            load: caps?.supportsLoadSession === true,
+            resume: caps?.supportsResumeSession === true,
+            list: caps?.supportsListSessions === true,
+            fork: caps?.supportsForkSession === true,
+        },
+    };
+}

package/dist/structured-tool.d.ts

@@ -5,7 +5,11 @@ export declare const STRUCTURED_OUTPUT_SERVER_NAME = "structured_output";
 export declare const STRUCTURED_OUTPUT_TOOL_DESCRIPTION: string;
 export interface StructuredOutputToolRegistration {
     readonly url: string;
+    /** Peek at the last valid capture without consuming it (the runner's single-turn read). */
     tryCaptured(): unknown | undefined;
+    /** Return the captured value and clear the slot — a capture belongs to exactly one turn, so a
+     *  long-lived registration never hands turn N's object to turn N+1. */
+    takeCaptured(): unknown | undefined;
     release(): void;
 }
 /** Runner-scoped localhost MCP host. It binds only once a schema run actually needs injection. */

package/dist/structured-tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"structured-tool.d.ts","sourceRoot":"","sources":["../src/structured-tool.ts"],"names":[],"mappings":"AASA,OAAO,EAOL,KAAK,IAAI,EACV,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAKvC,eAAO,MAAM,2BAA2B,qBAAqB,CAAC;AAC9D,eAAO,MAAM,6BAA6B,sBAAsB,CAAC;AAEjE,eAAO,MAAM,kCAAkC,QAM2C,CAAC;AAW3F,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,WAAW,IAAI,OAAO,GAAG,SAAS,CAAC;IACnC,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,kGAAkG;AAClG,qBAAa,wBAAwB;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2B;IACjD,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,aAAa,CAA4B;IACjD,OAAO,CAAC,IAAI,CAAqB;IAEjC,WAAW,IAAI,OAAO;IAItB,aAAa,IAAI,MAAM,GAAG,SAAS;IAI7B,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,gCAAgC,CAAC;IAwBpE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YAYhB,eAAe;YAoCf,aAAa;IAyB3B,OAAO,CAAC,OAAO;CAahB;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC,aAAa,CAAC,CAI9E"}
+{"version":3,"file":"structured-tool.d.ts","sourceRoot":"","sources":["../src/structured-tool.ts"],"names":[],"mappings":"AASA,OAAO,EAOL,KAAK,IAAI,EACV,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAKvC,eAAO,MAAM,2BAA2B,qBAAqB,CAAC;AAC9D,eAAO,MAAM,6BAA6B,sBAAsB,CAAC;AAEjE,eAAO,MAAM,kCAAkC,QAM2C,CAAC;AAW3F,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,2FAA2F;IAC3F,WAAW,IAAI,OAAO,GAAG,SAAS,CAAC;IACnC;2EACuE;IACvE,YAAY,IAAI,OAAO,GAAG,SAAS,CAAC;IACpC,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,kGAAkG;AAClG,qBAAa,wBAAwB;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2B;IACjD,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,aAAa,CAA4B;IACjD,OAAO,CAAC,IAAI,CAAqB;IAEjC,WAAW,IAAI,OAAO;IAItB,aAAa,IAAI,MAAM,GAAG,SAAS;IAI7B,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,gCAAgC,CAAC;IA6BpE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YAYhB,eAAe;YAoCf,aAAa;IAyB3B,OAAO,CAAC,OAAO;CAahB;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC,aAAa,CAAC,CAI9E"}

package/dist/structured-tool.js

@@ -41,6 +41,11 @@ export class StructuredOutputToolHost {
             return {
                 url: `http://${HOST}:${port}/${token}`,
                 tryCaptured: () => slot.captured,
+                takeCaptured: () => {
+                    const captured = slot.captured;
+                    slot.captured = undefined;
+                    return captured;
+                },
                 release: once(() => {
                     this.slots.delete(token);
                 }),

package/dist/system-prompt.d.ts

@@ -0,0 +1,13 @@
+import { type SystemPromptOptions } from "@automatalabs/shared-types";
+import type { Backend } from "./backend.js";
+import { type SystemPromptSupport } from "./protocol-coverage.js";
+/** Human summary of a support row for error messages: `replace and append`, `append only`, `none`. */
+export declare function describeSystemPromptSupport(support: SystemPromptSupport): string;
+/**
+ * Validate `systemPrompt` for `backend` and return it normalized (only the defined fields, or
+ * undefined when nothing was requested). Throws SCRIPT_VALIDATION_ERROR when the value is not a
+ * plain object, a field is not a non-blank string, or the backend does not carry a requested
+ * field — an unsupported instruction is refused, never silently ignored.
+ */
+export declare function assertSystemPromptSupported(backend: Pick<Backend, "id" | "systemPrompt">, systemPrompt: SystemPromptOptions | undefined, label: string | undefined): SystemPromptOptions | undefined;
+//# sourceMappingURL=system-prompt.d.ts.map

package/dist/system-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-prompt.d.ts","sourceRoot":"","sources":["../src/system-prompt.ts"],"names":[],"mappings":"AAMA,OAAO,EAAoC,KAAK,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACxG,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAA6B,KAAK,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAe7F,sGAAsG;AACtG,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAKhF;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,GAAG,cAAc,CAAC,EAC7C,YAAY,EAAE,mBAAmB,GAAG,SAAS,EAC7C,KAAK,EAAE,MAAM,GAAG,SAAS,GACxB,mBAAmB,GAAG,SAAS,CAoCjC"}

package/dist/system-prompt.js

@@ -0,0 +1,67 @@
+// Backend-neutral system prompt instructions (`SystemPromptOptions`): the one validator every
+// front door runs BEFORE a session opens — `AcpAgentRunner.prepareSession` (run / interactive /
+// reattach), the `AcpAgent` constructor, `agent.fork()`, and the cold statics. The backend maps a
+// validated value onto its own `_meta` dialect in `Backend.sessionMeta`; a backend whose
+// `Backend.systemPrompt` row does not carry a field never receives it, and the caller learns why
+// from a SCRIPT_VALIDATION_ERROR naming the backend, the field, and the escape hatch (`meta`).
+import { WorkflowError, WorkflowErrorCode } from "@automatalabs/shared-types";
+import { SYSTEM_PROMPT_UNSUPPORTED } from "./protocol-coverage.js";
+const SYSTEM_PROMPT_FIELDS = ["replace", "append"];
+function validationError(message, label) {
+    return new WorkflowError(message, WorkflowErrorCode.SCRIPT_VALIDATION_ERROR, {
+        recoverable: false,
+        agentLabel: label,
+    });
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** Human summary of a support row for error messages: `replace and append`, `append only`, `none`. */
+export function describeSystemPromptSupport(support) {
+    const supported = SYSTEM_PROMPT_FIELDS.filter((field) => support[field]);
+    if (supported.length === 0)
+        return "none";
+    if (supported.length === SYSTEM_PROMPT_FIELDS.length)
+        return supported.join(" and ");
+    return `${supported.join(", ")} only`;
+}
+/**
+ * Validate `systemPrompt` for `backend` and return it normalized (only the defined fields, or
+ * undefined when nothing was requested). Throws SCRIPT_VALIDATION_ERROR when the value is not a
+ * plain object, a field is not a non-blank string, or the backend does not carry a requested
+ * field — an unsupported instruction is refused, never silently ignored.
+ */
+export function assertSystemPromptSupported(backend, systemPrompt, label) {
+    if (systemPrompt === undefined)
+        return undefined;
+    const prefix = `Agent call${label ? ` "${label}"` : ""}`;
+    if (!isRecord(systemPrompt)) {
+        throw validationError(`${prefix} systemPrompt must be an object with optional string fields replace / append`, label);
+    }
+    const unknown = Object.keys(systemPrompt).filter((key) => !SYSTEM_PROMPT_FIELDS.includes(key));
+    if (unknown.length > 0) {
+        throw validationError(`${prefix} systemPrompt has unknown field${unknown.length > 1 ? "s" : ""} ${unknown.map((key) => `"${key}"`).join(", ")}; only replace / append are accepted (a backend's own extras go through meta)`, label);
+    }
+    const normalized = {};
+    for (const field of SYSTEM_PROMPT_FIELDS) {
+        const value = systemPrompt[field];
+        if (value === undefined)
+            continue;
+        if (typeof value !== "string" || value.trim() === "") {
+            throw validationError(`${prefix} systemPrompt.${field} must be a non-empty string`, label);
+        }
+        normalized[field] = value;
+    }
+    const requested = SYSTEM_PROMPT_FIELDS.filter((field) => normalized[field] !== undefined);
+    if (requested.length === 0)
+        return undefined;
+    const support = backend.systemPrompt ?? SYSTEM_PROMPT_UNSUPPORTED;
+    const refused = requested.filter((field) => !support[field]);
+    if (refused.length > 0) {
+        throw validationError(`${prefix} systemPrompt.${refused.join(" / ")} is not supported by backend "${backend.id}" (supported: ${describeSystemPromptSupport(support)}); ` +
+            (support.replace || support.append
+                ? "use a supported field"
+                : "this backend exposes no ACP system-prompt channel — drive its own configuration, or send its vendor `_meta` keys through the meta passthrough"), label);
+    }
+    return normalized;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automatalabs/acp-agents",
-  "version": "1.2.7",
+  "version": "2.0.0",
   "license": "Apache-2.0",
   "engines": {
     "node": ">=22"
@@ -32,12 +32,12 @@
     "@modelcontextprotocol/sdk": "^1.30",
     "typebox": "1.3.2",
     "@automatalabs/codex-acp": "2.6.0",
-    "@automatalabs/pi-acp": "0.8.0",
-    "@automatalabs/shared-types": "2.2.0"
+    "@automatalabs/pi-acp": "0.9.0",
+    "@automatalabs/shared-types": "3.0.0"
   },
   "scripts": {
     "build": "tsc -b",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc -p tsconfig.test.json --noEmit",
     "test": "tsx --test \"test/**/*.test.ts\""
   }
 }