@automatalabs/acp-agents 1.3.0 → 3.0.0

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": "1.3.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.8.0",
-    "@automatalabs/shared-types": "2.3.0"
+    "@automatalabs/codex-acp": "2.7.0",
+    "@automatalabs/pi-acp": "0.9.1",
+    "@automatalabs/shared-types": "3.1.0"
   },
   "scripts": {
     "build": "tsc -b",