@zq-silk/yui 0.15.7 → 0.15.9

package/dist/runtime/agentRunConfiguration.js

@@ -0,0 +1,258 @@
+/**
+ * What a live Agent Session can be asked about the run configuration it is
+ * actually operating under.
+ *
+ * Yui already records what a launch *requested*: a Role's model, reasoning
+ * effort and permission strategy resolve into an effective launch snapshot that
+ * every `show` surface prints. That snapshot is an expectation, and it is
+ * complete on its own terms. What it cannot answer is whether the Agent agreed:
+ * a requested model the Agent does not offer, a permission mode it silently
+ * substituted, or an axis it reset when a later call landed are all invisible to
+ * a record written before the process started.
+ *
+ * This is the read path for that second question, and it is deliberately
+ * separate from the first. Presenting configuration expectation as execution
+ * fact is the specific failure this vocabulary exists to prevent, so every
+ * value here carries how it was learned, and the three ways of not knowing stay
+ * distinct instead of collapsing into one blank:
+ *
+ * - `unknown` means nobody could be asked. There is no live Session, or the
+ *   Session exists but could not be reached. It says nothing about the Agent.
+ * - `unsupported` means this Session implementation has no observation reader.
+ *   It does not claim the underlying product can never report these facts.
+ * - `observed` carries what the Agent itself reported, and only that.
+ *
+ * Nothing here performs I/O or holds a product name. A Session that can answer
+ * projects its own protocol's report into this shape; a Session that cannot
+ * returns the `unsupported` branch. Reading it never sends a protocol message,
+ * because a query that configured or prompted the Agent would change the thing
+ * it claims to describe.
+ */
+/**
+ * The answer when there is no live Session to ask, or it could not be reached.
+ *
+ * Kept apart from `unsupported` because the two would otherwise both render as
+ * "no data" while meaning opposite things: this one says Yui did not get an
+ * answer, the other says the Agent has none to give.
+ */
+export function unknownAgentRunConfiguration(reason) {
+    return Object.freeze({ status: "unknown", reason });
+}
+/**
+ * The answer for a Session implementation without a run-configuration reader.
+ *
+ * Stated once so the two implementations that share this position cannot drift
+ * into describing it differently, and so the reason travels with the status
+ * instead of being reconstructed by whoever renders it.
+ */
+export function unsupportedAgentRunConfiguration(protocolDescription) {
+    return Object.freeze({
+        status: "unsupported",
+        reason: `${protocolDescription}: this Yui Session implementation exposes no run configuration observation, so Yui cannot `
+            + `confirm which model, reasoning effort or permission mode this Session is `
+            + `operating under. See the Session's pinned launch request; current Role settings may differ.`
+    });
+}
+/**
+ * Project a negotiated capability exchange into the shared handshake shape.
+ *
+ * The parameter is described structurally rather than by naming a protocol type,
+ * so this module stays free of any one protocol while still being the single
+ * place the projection happens. That matters because the two callers learn the
+ * same facts at different moments — a capability probe before any Session
+ * exists, and a live Session at launch — and a second copy of this mapping would
+ * let `yui config agent capabilities` and a Session inspect disagree about the
+ * same Agent's advertised capabilities.
+ *
+ * Only enabled capabilities are listed, and a silent Agent stays `unknown`
+ * rather than being resolved into a product by anything Yui knows about the
+ * command it ran.
+ */
+export function handshakeObservationFrom(negotiated) {
+    return Object.freeze({
+        status: "observed",
+        protocolVersion: negotiated.protocolVersion,
+        agentName: negotiated.agentName ?? "unknown",
+        agentVersion: negotiated.agentVersion ?? "unknown",
+        capabilities: Object.freeze(Object.entries(negotiated.capabilities)
+            .filter(([, enabled]) => enabled)
+            .map(([name]) => name)
+            .sort()),
+        authMethods: Object.freeze(negotiated.authMethods.map((method) => method.id).sort())
+    });
+}
+/**
+ * Read an observation back from a parsed control response.
+ *
+ * This value is produced inside the Agent Host and read by a CLI process, so it
+ * arrives as untyped JSON from another program. A malformed one must not
+ * degrade into a confident-looking partial reading: an entry missing its
+ * confirmation would render as a blank cell that looks like agreement. So
+ * anything that does not parse becomes `unknown` with the reason saying so,
+ * which is the same answer as a Session that could not be reached — because
+ * that is exactly what it is.
+ */
+export function readAgentRunConfigurationObservation(value) {
+    const malformed = unknownAgentRunConfiguration("The Agent Host reported run configuration in a shape this build does not "
+        + "recognize, so nothing about the live Session's configuration can be shown.");
+    const observation = asRecord(value);
+    if (observation === undefined)
+        return malformed;
+    if (observation.status === "unknown" || observation.status === "unsupported") {
+        const reason = text(observation.reason);
+        if (reason === undefined)
+            return malformed;
+        return Object.freeze({ status: observation.status, reason });
+    }
+    if (observation.status !== "observed")
+        return malformed;
+    const observedAt = text(observation.observedAt);
+    const handshake = readHandshake(observation.handshake);
+    if (observedAt === undefined || !Number.isFinite(Date.parse(observedAt))
+        || handshake === undefined)
+        return malformed;
+    if (!Array.isArray(observation.requested) || !Array.isArray(observation.axes))
+        return malformed;
+    const requested = [];
+    for (const entry of observation.requested) {
+        const request = readRequest(entry);
+        // One unreadable entry cannot be skipped: the list would then look complete
+        // while silently omitting a requested value, which is the difference between
+        // "not requested" and "requested, outcome lost".
+        if (request === undefined)
+            return malformed;
+        requested.push(request);
+    }
+    const axes = [];
+    for (const entry of observation.axes) {
+        const axis = readAxis(entry);
+        if (axis === undefined)
+            return malformed;
+        axes.push(axis);
+    }
+    return Object.freeze({
+        status: "observed",
+        observedAt,
+        handshake,
+        requested: Object.freeze(requested),
+        axes: Object.freeze(axes)
+    });
+}
+function readRequest(value) {
+    const entry = asRecord(value);
+    if (entry === undefined)
+        return undefined;
+    const field = entry.field;
+    const key = text(entry.key);
+    const requestedValue = text(entry.value);
+    const confirmation = entry.confirmation;
+    if (field !== "model" && field !== "effort" && field !== "permission")
+        return undefined;
+    if (key === undefined || requestedValue === undefined)
+        return undefined;
+    if (confirmation !== "already" && confirmation !== "observed" && confirmation !== "acknowledged") {
+        return undefined;
+    }
+    const current = readCurrentValue(entry.current);
+    if (current === undefined)
+        return undefined;
+    return Object.freeze({ field, key, value: requestedValue, confirmation, current });
+}
+/**
+ * Read the current value and its evidence, shared by both tables.
+ *
+ * One reader because one shape: an axis and a requested value answer the same
+ * question about evidence, and a second implementation is where the two would
+ * eventually come to disagree about what counts as observed.
+ */
+function readCurrentValue(value) {
+    const current = asRecord(value);
+    if (current === undefined)
+        return undefined;
+    if (current.status === "observed") {
+        const observed = text(current.value);
+        return observed === undefined
+            ? undefined
+            : Object.freeze({ status: "observed", value: observed });
+    }
+    if (current.status !== "unobserved")
+        return undefined;
+    const reason = text(current.reason);
+    return reason === undefined ? undefined : Object.freeze({ status: "unobserved", reason });
+}
+function readAxis(value) {
+    const entry = asRecord(value);
+    if (entry === undefined)
+        return undefined;
+    const key = text(entry.key);
+    const current = readCurrentValue(entry.current);
+    if (key === undefined || current === undefined)
+        return undefined;
+    if (!Array.isArray(entry.offered))
+        return undefined;
+    const offered = [];
+    for (const candidate of entry.offered) {
+        const offer = text(candidate);
+        if (offer === undefined)
+            return undefined;
+        offered.push(offer);
+    }
+    const category = text(entry.category);
+    return Object.freeze({
+        key,
+        ...(category === undefined ? {} : { category }),
+        current,
+        offered: Object.freeze(offered)
+    });
+}
+function readHandshake(value) {
+    const handshake = asRecord(value);
+    if (handshake === undefined)
+        return undefined;
+    if (handshake.status === "unsupported") {
+        const reason = text(handshake.reason);
+        return reason === undefined ? undefined : Object.freeze({ status: "unsupported", reason });
+    }
+    if (handshake.status !== "observed")
+        return undefined;
+    const protocolVersion = handshake.protocolVersion;
+    const agentName = text(handshake.agentName);
+    const agentVersion = text(handshake.agentVersion);
+    if (typeof protocolVersion !== "number" || !Number.isSafeInteger(protocolVersion))
+        return undefined;
+    if (agentName === undefined || agentVersion === undefined)
+        return undefined;
+    if (!Array.isArray(handshake.capabilities) || !Array.isArray(handshake.authMethods)) {
+        return undefined;
+    }
+    const capabilities = [];
+    for (const candidate of handshake.capabilities) {
+        const capability = text(candidate);
+        if (capability === undefined)
+            return undefined;
+        capabilities.push(capability);
+    }
+    const authMethods = [];
+    for (const candidate of handshake.authMethods) {
+        const method = text(candidate);
+        if (method === undefined)
+            return undefined;
+        authMethods.push(method);
+    }
+    return Object.freeze({
+        status: "observed",
+        protocolVersion,
+        agentName,
+        agentVersion,
+        capabilities: Object.freeze(capabilities),
+        authMethods: Object.freeze(authMethods)
+    });
+}
+function asRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function text(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}

package/dist/runtime/builtinAgentDrivers.js

@@ -1,10 +1,16 @@
 import { AgentDriverRegistry } from "./agentDriver.js";
 import { claudeTranscriptObserver, codexTranscriptObserver, transcriptObserverSource } from "./builtinTranscriptObserver.js";
-import { mapClaudeAgentError, mapCodexAgentError } from "./builtinAgentErrorMappers.js";
+import { mapAcpAgentError, mapClaudeAgentError, mapCodexAgentError } from "./builtinAgentErrorMappers.js";
 import { serializeAgentErrorRaw, standardAgentError } from "./agentError.js";
 import { transportAgentResult } from "../domain/agentResultTransport.js";
 export const CODEX_DRIVER_ID = "openai/codex";
 export const CLAUDE_CODE_DRIVER_ID = "anthropic/claude-code";
+/**
+ * The Agent Client Protocol Driver is named after the protocol, not a product:
+ * every ACP Agent is observed through this one entry, so adding a second ACP
+ * CLI needs a launch descriptor and no new Driver.
+ */
+export const ACP_DRIVER_ID = "acp/agent-client-protocol";
 export function builtinDriverIdForAdapter(adapterId) {
     return builtinAgentDriverRegistry().requireByAdapterId(adapterId).id;
 }
@@ -27,6 +33,9 @@ const STRUCTURED_CLI_CAPABILITIES = Object.freeze({
         resume: true,
         sendTurn: true,
         interrupt: true,
+        // Conservative default: a Driver that has not stated otherwise is assumed
+        // to cancel by stopping the process Yui owns.
+        interruptDelivery: "owned-process",
         stop: true
     }),
     conversation: Object.freeze({
@@ -94,7 +103,6 @@ export const BUILTIN_AGENT_DRIVERS = Object.freeze([
                 terminal: isTerminalHook(hookEventName),
                 ...(hookEventName !== "SubagentStop" ? {} : {
                     continuationId: subagentId(payload),
-                    continuationGeneration: continuationGeneration(payload)
                 })
             }),
             observer: Object.freeze({
@@ -123,6 +131,12 @@ export const BUILTIN_AGENT_DRIVERS = Object.freeze([
                 acceptance: "exact",
                 idempotency: "unavailable"
             }),
+            control: Object.freeze({
+                ...STRUCTURED_CLI_CAPABILITIES.control,
+                // Managed Codex interrupts its Turn through the App Server, which
+                // leaves the Session (and its process) alive.
+                interruptDelivery: "native"
+            }),
             descendants: Object.freeze({
                 lineage: "partial",
                 detachedQuery: "partial",
@@ -152,7 +166,6 @@ export const BUILTIN_AGENT_DRIVERS = Object.freeze([
                 terminal: isTerminalHook(hookEventName),
                 ...(hookEventName !== "SubagentStop" ? {} : {
                     continuationId: subagentId(payload),
-                    continuationGeneration: continuationGeneration(payload)
                 })
             }),
             observer: Object.freeze({
@@ -160,6 +173,119 @@ export const BUILTIN_AGENT_DRIVERS = Object.freeze([
                 sample: codexTranscriptObserver
             })
         })
+    }),
+    Object.freeze({
+        id: ACP_DRIVER_ID,
+        label: "Agent Client Protocol",
+        protocolVersion: 1,
+        adapterId: "acp",
+        /**
+         * Declared from ACP v1 itself, not from any product's abilities.
+         *
+         * ACP is a client-driven JSON-RPC protocol: Yui owns the pipe and learns
+         * everything from request/response pairs, so there is no Hook ingress and
+         * no transcript file to sample. Several capabilities are therefore
+         * genuinely unavailable rather than merely unimplemented, and saying so is
+         * what keeps managed admission fail-closed.
+         */
+        capabilities: Object.freeze({
+            // No interactive surface: `acp` mode is a machine protocol on stdio.
+            surfaces: Object.freeze(["managed-protocol"]),
+            lifecycle: Object.freeze({
+                host: "persistent",
+                providerProcess: "persistent",
+                // `session/load` is ACP's exact Conversation resume, so the protocol
+                // does define one and managed admission — which runs adapter-wide,
+                // before any connection exists — is right to see it here. What a
+                // *given* Agent implements is negotiated per connection via
+                // `agentCapabilities.loadSession`, and that answer cannot be predicted
+                // by a static table. The live Session therefore reports its own
+                // recoverability after the handshake, and that value, not this one, is
+                // what gets published and stored. An Agent that never advertised
+                // `loadSession` also fails loudly inside `session/load` rather than
+                // silently degrading a running Turn.
+                nativeConversationResume: "exact",
+                compaction: "unknown",
+                compactionEvents: "unavailable",
+                contextUsage: "unavailable",
+                inSessionContinuation: true,
+                deliveryDeduplication: "unsupported"
+            }),
+            control: Object.freeze({
+                start: true,
+                resume: true,
+                sendTurn: true,
+                // `session/cancel` is a notification the Agent MUST answer with the
+                // `cancelled` stop reason, but halting the work is only a SHOULD.
+                interrupt: true,
+                interruptDelivery: "native",
+                stop: true
+            }),
+            conversation: Object.freeze({
+                // `session/new` returns the Agent's own Session id.
+                persistentIdentity: "exact",
+                // Same as `nativeConversationResume`: `session/load` is how ACP carries
+                // a Conversation across processes, so the capability exists. Whether
+                // this Agent honours it is the live Session's answer, not this table's.
+                crossProcessResume: true,
+                // `session/load` replays the Conversation, but ACP exposes no way to
+                // read back a Session's history without reloading it.
+                readback: "unavailable"
+            }),
+            input: Object.freeze({
+                startTurn: true,
+                // One Turn is one `session/prompt` request; ACP defines no way to add
+                // input to a Turn already in flight.
+                steer: "unavailable",
+                inject: "unavailable",
+                // The prompt response IS the terminal, so ACP defines no separate
+                // acceptance message. This is a permanent protocol fact, not a
+                // per-Agent gap: a completed pipe write is all that can be observed
+                // before the Turn's own result arrives.
+                acceptance: "unavailable",
+                idempotency: "unavailable"
+            }),
+            descendants: Object.freeze({
+                lineage: "unavailable",
+                detachedQuery: "unavailable",
+                resultRouting: "unavailable"
+            }),
+            // The prompt response carries an explicit stopReason, which is an exact
+            // structured terminal for the Turn that requested it.
+            bounded: Object.freeze({ structuredTerminal: true }),
+            observation: Object.freeze({
+                sessionIdentity: "exact",
+                sessionBootstrap: "discovered",
+                // ACP has no "ready" signal beyond `initialize` answering.
+                preInputReadiness: "unavailable",
+                promptAcceptance: "unavailable",
+                // The terminal status and its correlation to the exact request are
+                // both exact. What ACP lacks is intermediate progress, which is
+                // recorded as absent operations and usage rather than by understating
+                // the lifecycle Yui does observe.
+                turnLifecycle: "exact",
+                goalLifecycle: "unavailable",
+                operations: Object.freeze([]),
+                waiting: Object.freeze([]),
+                usage: "unavailable",
+                delivery: "host-only"
+            })
+        }),
+        runtime: Object.freeze({
+            // ACP delivers no Hooks. Identity comes from the protocol Session the
+            // managed Endpoint already holds, so there is no payload to mine here —
+            // and inventing a Turn id from a JSON-RPC request id would present a
+            // Yui-owned value as a Provider identity.
+            nativeSessionId: ({ payload }) => (optionalIdentityFrom(payload, ["sessionId"])),
+            nativeTurnId: () => undefined,
+            mapError: mapAcpAgentError,
+            mapHook: ({ hookEventName }) => {
+                throw new Error(`ACP Driver receives no native Hooks: ${hookEventName}.`);
+            },
+            classifyHook: ({ hookEventName }) => {
+                throw new Error(`ACP Driver receives no native Hooks: ${hookEventName}.`);
+            }
+        })
     })
 ]);
 export function builtinAgentDriverRegistry() {
@@ -185,8 +311,7 @@ function mapClaudeLifecycleHook(name, payload, occurrenceId) {
                 payload.source === "startup"
                     ? mapped("session.ready")
                     : mapped("session.started"),
-                mapped("conversation.observed", { recoverability: "recoverable" }),
-                mapped("activation.started")
+                mapped("conversation.observed", { recoverability: "recoverable" })
             ];
         case "UserPromptSubmit":
             return mapped("turn.accepted");
@@ -261,7 +386,7 @@ function mapClaudeLifecycleHook(name, payload, occurrenceId) {
             // Native CLI exit ends this local Provider attachment, not the
             // resumable Conversation. Durable Session end is an explicit Yui
             // mutation or a Provider fact that the Conversation is unrecoverable.
-            return mapped("activation.ended");
+            return [];
         default:
             throw new Error(`Claude Code Driver does not support Hook event: ${name}.`);
     }
@@ -336,8 +461,7 @@ function mapCodexHook(name, payload, occurrenceId) {
         case "SessionStart":
             return [
                 mapped("session.started"),
-                mapped("conversation.observed", { recoverability: "recoverable" }),
-                mapped("activation.started")
+                mapped("conversation.observed", { recoverability: "recoverable" })
             ];
         case "UserPromptSubmit":
             return mapped("turn.accepted");
@@ -380,7 +504,7 @@ function mapCodexHook(name, payload, occurrenceId) {
         case "Stop":
             return mapped("turn.completed", optionalResultOutput(payload));
         case "SessionEnd":
-            return mapped("activation.ended");
+            return [];
         default:
             throw new Error(`Codex Driver does not support Hook event: ${name}.`);
     }
@@ -394,10 +518,8 @@ function mapped(kind, payload = {}, fence) {
 }
 function continuationObservation(kind, native, payload) {
     const continuationId = subagentId(native);
-    const generation = continuationGeneration(native);
     return mapped(kind, payload, {
         continuationId,
-        continuationGeneration: generation,
         ...(optionalIdentityFrom(native, ["parent_agent_id", "parent_subagent_id"]) === undefined
             ? {}
             : {
@@ -405,12 +527,6 @@ function continuationObservation(kind, native, payload) {
             })
     });
 }
-function continuationGeneration(native) {
-    return typeof native.generation === "number"
-        && Number.isSafeInteger(native.generation) && native.generation >= 1
-        ? native.generation
-        : 1;
-}
 function reportId(payload) {
     return optionalIdentityFrom(payload, ["report_id", "message_id", "agent_id", "subagent_id"])
         ?? subagentId(payload);
@@ -491,7 +607,7 @@ function claudeFailure(payload) {
             }),
             ...(lastOutput === undefined ? {} : { lastOutput }),
             ...(payload.run_terminal === true || payload.unrecoverable === true
-                ? { turnTerminal: true }
+                ? { runTerminal: true }
                 : {})
         },
         summary: [

package/dist/runtime/builtinAgentErrorMappers.js

@@ -1,6 +1,9 @@
 /** Provider-specific Claude Code failure recognition. */
 export function mapClaudeAgentError(input) {
     const text = `${input.message}\n${input.raw}`;
+    if (/^No conversation found with session ID: [A-Za-z0-9-]+\.?$/imu.test(input.message)) {
+        return sessionUnavailable("provider.session-not-found");
+    }
     if (/^server_error$/iu.test(input.message) || /\bapi_error\b/iu.test(text)) {
         return recoverable("availability", "provider.server-error");
     }
@@ -44,6 +47,49 @@ export function mapCodexAgentError(input) {
     }
     return mapSharedAgentError(text, "codex");
 }
+/**
+ * Agent Client Protocol failure recognition.
+ *
+ * ACP rides on JSON-RPC 2.0, so its failures arrive as numeric codes rather
+ * than provider prose. The codes are recognized first because they are the
+ * protocol's own exact vocabulary; only then does the shared text matcher run,
+ * which is what catches the transport failures underneath the protocol.
+ */
+export function mapAcpAgentError(input) {
+    const text = `${input.message}\n${input.raw}`;
+    // -32800 is ACP's own "request cancelled". It is the expected answer to
+    // `session/cancel`, not a fault.
+    if (/-32800/u.test(text) || /request[\s_-]?cancell?ed/iu.test(text)) {
+        return Object.freeze({
+            category: "cancelled",
+            code: "acp.request-cancelled",
+            sessionDisposition: "recoverable"
+        });
+    }
+    // -32601 method not found / -32602 invalid params: Yui asked for something
+    // this Agent does not implement, or asked for it wrongly. Either way the
+    // request is at fault, and retrying it unchanged cannot help.
+    if (/-32601/u.test(text)) {
+        return classification("invalid-request", "acp.method-not-found");
+    }
+    if (/-32602/u.test(text)) {
+        return classification("invalid-request", "acp.invalid-params");
+    }
+    if (/-3270[01]/u.test(text)) {
+        return classification("invalid-request", "acp.invalid-request");
+    }
+    // -32603 is the catch-all internal error: the Agent failed, but the protocol
+    // says nothing about whether this Session survived.
+    if (/-32603/u.test(text)) {
+        return recoverable("runtime", "acp.internal-error");
+    }
+    // ACP's authentication path: the Agent requires `authenticate` first. Yui
+    // never performs it on the user's behalf, so this is a genuine access fact.
+    if (/auth[\s_-]?required|requires? authentication|-32000/iu.test(text)) {
+        return classification("access", "acp.authentication-required");
+    }
+    return mapSharedAgentError(text, "acp");
+}
 function mapSharedAgentError(text, namespace) {
     if (/stream error:.*INTERNAL_ERROR/iu.test(text)) {
         return recoverable("transport", "transport.stream-internal-error");
@@ -124,13 +170,19 @@ function mapSharedAgentError(text, namespace) {
         return recoverable("runtime", "runtime.process-exited");
     }
     if (/invalid[\s_-]?request|validation[\s_-]?error|bad[\s_-]?request|unknown[\s_-]?(?:flag|tool|argument)|unexpected argument|invalid schema/iu.test(text)
-        || (namespace === "codex"
-            ? /\[codex:(?:unrecognized_model|invalid_model|model_not_found)\]/iu.test(text)
-            : /\[claude-code:(?:unrecognized_model|invalid_model|model_not_found)\]/iu.test(text))) {
+        || namespacedModelError(namespace).test(text)) {
         return classification("invalid-request", "provider.invalid-request");
     }
     return classification("unknown", "unknown");
 }
+/**
+ * The `[<namespace>:<code>]` model-error tag, built from the caller's own
+ * namespace. Enumerating the namespaces here instead would silently test one
+ * provider's tag against another provider's text.
+ */
+function namespacedModelError(namespace) {
+    return new RegExp(String.raw `\[${namespace}:(?:unrecognized_model|invalid_model|model_not_found)\]`, "iu");
+}
 function classification(category, code) {
     return Object.freeze({ category, code });
 }

package/dist/runtime/builtinTranscriptUsage.js

@@ -14,7 +14,7 @@ export function codexTranscriptUsage(transcript) {
 export function codexTranscriptUsageReport(transcript) {
     // Codex token_count events are cumulative Session snapshots. Per-request
     // input is the non-negative delta between consecutive snapshots; the first
-    // snapshot only establishes the generation baseline.
+    // snapshot only establishes the Session baseline.
     let latestInput = 0;
     let latestCached = 0;
     let latestOutput = 0;