@automatalabs/acp-agents 2.0.0 → 3.0.0

package/dist/traits.d.ts

@@ -0,0 +1,51 @@
+import type { Backend } from "./backend.js";
+import type { NegotiatedCapabilities } from "./capabilities.js";
+import { type ForkSessionTraitRow, type SystemPromptSupport } from "./protocol-coverage.js";
+import type { BackendRegistry } from "./registry.js";
+/** The traits of one agent's backend: routing identity, the `session/fork` row the SDK follows,
+ *  the system-prompt channel and where that answer came from, the two vendor extensions, the
+ *  structured-output channel, and the `PromptResponse.usage` scope. Frozen; `AcpAgent#traits` and
+ *  `AcpAgent.traits()` hand out a fresh object per read. */
+export interface AcpAgentTraits {
+    /** The resolved backend id (a built-in id or a registered custom name). */
+    readonly backendId: string;
+    /** `true` for a registry (custom) backend, `false` for one of the built-in adapters — a registry
+     *  lookup, like the fork trait, so a custom entry that shadows a built-in name is `custom`. */
+    readonly custom: boolean;
+    /** The mode the SDK selects when the caller omits `mode` and the catalog advertises it. */
+    readonly defaultModeId?: string;
+    /** The `session/fork` row the SDK's fork choreography follows (`forkTraitFor`): a built-in's
+     *  `FORK_SESSION_TRAITS` row, or a custom entry's declaration. */
+    readonly fork: ForkSessionTraitRow;
+    /** Which halves of `systemPrompt` the backend carries and where the answer came from: `table`
+     *  (a built-in's `SYSTEM_PROMPT_SUPPORT` row), `advertised` (the live agent's initialize
+     *  advertisement — pi under `_meta.systemPrompt`, the Codex fork under
+     *  `agentCapabilities._meta["@automatalabs/codex-acp"]` — which wins over the table once the
+     *  connection is open), or `none` (no channel — every custom backend before open, since
+     *  `CustomAcpBackend` never carries the neutral instructions; a built-in that supports neither
+     *  half, OpenCode, still reports its all-false row as `table`). */
+    readonly systemPrompt: SystemPromptSupport & {
+        readonly source: "table" | "advertised" | "none";
+    };
+    /** `_session/steering`: the built-in `ACP_EXTENSION_SUPPORT_MATRIX` row before open (`unknown`
+     *  for a custom backend); after open, whether `initializeMeta.steering.supported === true`. */
+    readonly steering: "supported" | "not-advertised" | "unknown";
+    /** `_session/loaded_turn/query`, derived exactly like `steering` (`initializeMeta.loadedTurn`). */
+    readonly loadedTurn: "supported" | "not-advertised" | "unknown";
+    /** How a `schema` reaches this backend, from the Backend object's behavior: `client-tool` (the
+     *  injected StructuredOutput MCP tool plus the in-prompt contract — pi, OpenCode, custom),
+     *  `turn-meta` (the schema rides every turn's `_meta` — Codex), or `session-meta` (bound at
+     *  session open — Claude). */
+    readonly structuredOutput: "session-meta" | "turn-meta" | "client-tool";
+    /** What `PromptResponse.usage` covers (`PROMPT_USAGE_SCOPES`): every agent reports the turn. */
+    readonly promptUsage: "turn";
+}
+/**
+ * Describe `backend`'s traits. Without `live`, every answer comes from the tables and the Backend
+ * object; with `live` (the negotiated capabilities of an open connection) the initialize
+ * advertisements refine `systemPrompt`, `steering`, and `loadedTurn`. `registry` is the registry
+ * the backend was routed through — a registered name is a custom backend and follows its own
+ * declarations, never a built-in's rows.
+ */
+export declare function describeBackendTraits(backend: Backend, registry: BackendRegistry, live?: NegotiatedCapabilities): AcpAgentTraits;
+//# sourceMappingURL=traits.d.ts.map

package/dist/traits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traits.d.ts","sourceRoot":"","sources":["../src/traits.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAIL,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACzB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD;;;4DAG4D;AAC5D,MAAM,WAAW,cAAc;IAC7B,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;mGAC+F;IAC/F,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,2FAA2F;IAC3F,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;sEACkE;IAClE,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC;;;;;;uEAMmE;IACnE,QAAQ,CAAC,YAAY,EAAE,mBAAmB,GAAG;QAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,YAAY,GAAG,MAAM,CAAA;KAAE,CAAC;IAClG;mGAC+F;IAC/F,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,gBAAgB,GAAG,SAAS,CAAC;IAC9D,mGAAmG;IACnG,QAAQ,CAAC,UAAU,EAAE,WAAW,GAAG,gBAAgB,GAAG,SAAS,CAAC;IAChE;;;kCAG8B;IAC9B,QAAQ,CAAC,gBAAgB,EAAE,cAAc,GAAG,WAAW,GAAG,aAAa,CAAC;IACxE,gGAAgG;IAChG,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AASD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,eAAe,EACzB,IAAI,CAAC,EAAE,sBAAsB,GAC5B,cAAc,CAchB"}

package/dist/traits.js

@@ -0,0 +1,88 @@
+// Per-agent traits — what the AcpAgent SDK knows about a backend BEFORE it spawns (the executable
+// protocol-coverage tables plus the Backend object's own behavior) and what the live agent
+// ADVERTISED at initialize once a connection is open. Read-only data for callers: it never gates
+// a call by itself. The pre-open validators (`assertSystemPromptSupported`, the fork cwd rule)
+// keep reading the tables, so a refused option is refused before a process exists; the traits
+// tell the caller what the table says and, after open, what the agent actually advertised.
+import { Type } from "typebox";
+import { CODEX_CUSTOM_CAPABILITY_NAMESPACE, CODEX_META_KEYS, META_KEYS } from "@automatalabs/shared-types";
+import { LOADED_TURN_QUERY_METHOD, SESSION_STEERING_METHOD } from "./acp-client.js";
+import { forkTraitFor } from "./agent/fork.js";
+import { ACP_EXTENSION_SUPPORT_MATRIX, SYSTEM_PROMPT_UNSUPPORTED, promptUsageScope, } from "./protocol-coverage.js";
+/** A trivial schema for probing which channel `Backend.promptMeta` carries the schema on. */
+const PROBE_SCHEMA = Type.Object({ ok: Type.Boolean() });
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Describe `backend`'s traits. Without `live`, every answer comes from the tables and the Backend
+ * object; with `live` (the negotiated capabilities of an open connection) the initialize
+ * advertisements refine `systemPrompt`, `steering`, and `loadedTurn`. `registry` is the registry
+ * the backend was routed through — a registered name is a custom backend and follows its own
+ * declarations, never a built-in's rows.
+ */
+export function describeBackendTraits(backend, registry, live) {
+    const custom = registry.has(backend.id);
+    const initializeMeta = isRecord(live?.initializeMeta) ? live.initializeMeta : undefined;
+    return Object.freeze({
+        backendId: backend.id,
+        custom,
+        ...(backend.defaultModeId === undefined ? {} : { defaultModeId: backend.defaultModeId }),
+        fork: forkTraitFor(backend, registry),
+        systemPrompt: systemPromptTrait(backend, live),
+        steering: extensionTrait(backend.id, custom, SESSION_STEERING_METHOD, live, initializeMeta?.steering),
+        loadedTurn: extensionTrait(backend.id, custom, LOADED_TURN_QUERY_METHOD, live, initializeMeta?.loadedTurn),
+        structuredOutput: structuredOutputChannel(backend),
+        promptUsage: promptUsageScope(backend.id),
+    });
+}
+/** The live advertisement wins; else the Backend object's row — set only by the built-ins
+ *  (`SYSTEM_PROMPT_SUPPORT`), never by `CustomAcpBackend`, so a defined row is always `table`. */
+function systemPromptTrait(backend, live) {
+    const advertised = live ? advertisedSystemPrompt(live) : undefined;
+    if (advertised)
+        return Object.freeze({ ...advertised, source: "advertised" });
+    const table = backend.systemPrompt;
+    if (!table)
+        return Object.freeze({ ...SYSTEM_PROMPT_UNSUPPORTED, source: "none" });
+    return Object.freeze({ replace: table.replace, append: table.append, source: "table" });
+}
+/** The live system-prompt advertisement, when the agent made one: the bare `_meta.systemPrompt`
+ *  block (`{ replace, append }` booleans — pi), else the Codex fork's namespaced capability block
+ *  (`baseInstructions` => replace, `developerInstructions` => append). An agent that advertises
+ *  neither (Claude) returns undefined and the table stands. */
+function advertisedSystemPrompt(live) {
+    const initializeMeta = isRecord(live.initializeMeta) ? live.initializeMeta : undefined;
+    const bare = initializeMeta?.[META_KEYS.systemPrompt];
+    if (isRecord(bare))
+        return { replace: bare.replace === true, append: bare.append === true };
+    const agentMeta = isRecord(live.agent._meta) ? live.agent._meta : undefined;
+    const namespace = agentMeta?.[CODEX_CUSTOM_CAPABILITY_NAMESPACE];
+    if (isRecord(namespace) &&
+        (CODEX_META_KEYS.baseInstructions in namespace || CODEX_META_KEYS.developerInstructions in namespace)) {
+        return {
+            replace: namespace[CODEX_META_KEYS.baseInstructions] === true,
+            append: namespace[CODEX_META_KEYS.developerInstructions] === true,
+        };
+    }
+    return undefined;
+}
+function extensionTrait(backendId, custom, method, live, advertisement) {
+    if (live)
+        return isRecord(advertisement) && advertisement.supported === true ? "supported" : "not-advertised";
+    if (custom)
+        return "unknown";
+    const row = ACP_EXTENSION_SUPPORT_MATRIX.find((candidate) => candidate.agent === backendId && candidate.method === method);
+    return row?.disposition ?? "unknown";
+}
+/** Derived from the Backend object's behavior, never its id: a backend that opts into the injected
+ *  tool is `client-tool`; else one whose `promptMeta` carries the schema is `turn-meta`; else the
+ *  schema is bound at session open (`session-meta`). */
+function structuredOutputChannel(backend) {
+    if (backend.injectStructuredOutputTool === true)
+        return "client-tool";
+    const turnMeta = backend.promptMeta(PROBE_SCHEMA);
+    if (turnMeta !== undefined && Object.keys(turnMeta).length > 0)
+        return "turn-meta";
+    return "session-meta";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automatalabs/acp-agents",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "license": "Apache-2.0",
   "engines": {
     "node": ">=22"
@@ -31,9 +31,9 @@
     "@agentclientprotocol/sdk": "^1.4.0",
     "@modelcontextprotocol/sdk": "^1.30",
     "typebox": "1.3.2",
-    "@automatalabs/codex-acp": "2.6.0",
-    "@automatalabs/pi-acp": "0.9.0",
-    "@automatalabs/shared-types": "3.0.0"
+    "@automatalabs/codex-acp": "2.7.0",
+    "@automatalabs/pi-acp": "0.9.1",
+    "@automatalabs/shared-types": "3.1.0"
   },
   "scripts": {
     "build": "tsc -b",