@zq-silk/yui 0.15.7 → 0.15.8

package/dist/runtime/acpProtocol.js

@@ -0,0 +1,425 @@
+/**
+ * Agent Client Protocol (ACP) v1 codec.
+ *
+ * This module owns the protocol only. It knows nothing about which product is
+ * on the other end of the pipe: every product-specific fact (executable,
+ * arguments, version, authentication context) belongs to a product descriptor.
+ * A second ACP product must be reachable by adding a descriptor alone.
+ *
+ * Field names and semantics follow the published v1 specification
+ * (agentclientprotocol.com/protocol/v1). Where the specification leaves a
+ * behavior optional, this codec reports the negotiated fact rather than
+ * assuming the capability exists.
+ */
+export const ACP_PROTOCOL_VERSION = 1;
+/** JSON-RPC "Request Cancelled", used by ACP for `$/cancel_request`. */
+export const ACP_REQUEST_CANCELLED_CODE = -32800;
+export const ACP_METHOD_NOT_FOUND_CODE = -32601;
+/**
+ * Capabilities Yui advertises as an ACP client. The filesystem and terminal
+ * entries are deliberately false: Yui does not expose either to the Agent
+ * through this transport, so the Agent must not call `fs/*` or `terminal/*`.
+ * Declaring a capability Yui does not implement would invite calls it must then
+ * refuse.
+ *
+ * `session.configOptions.boolean` is likewise absent. ACP gates boolean config
+ * options behind that capability, and Yui's Role configuration expresses model,
+ * effort and permission mode as named values rather than flags. Advertising it
+ * would invite boolean options Yui has nothing to bind them to; staying silent
+ * means the Agent sends only the `select` options this client can actually act
+ * on, which the specification requires it to support unconditionally.
+ */
+export const YUI_CLIENT_CAPABILITIES = Object.freeze({
+    fs: Object.freeze({ readTextFile: false, writeTextFile: false }),
+    terminal: false
+});
+export function acpInitializeRequest(clientVersion) {
+    return {
+        protocolVersion: ACP_PROTOCOL_VERSION,
+        clientCapabilities: YUI_CLIENT_CAPABILITIES,
+        clientInfo: { name: "yui", title: "Yui", version: clientVersion }
+    };
+}
+/**
+ * Read an `initialize` result. The specification allows the Agent to answer
+ * with the newest version it supports; a client that cannot use that version
+ * must stop rather than continue on a guessed dialect.
+ */
+export function readAcpInitializeResult(value) {
+    const result = asObject(value);
+    if (result === null)
+        throw new Error("ACP initialize result is not an object.");
+    const negotiated = result.protocolVersion;
+    if (typeof negotiated !== "number" || !Number.isSafeInteger(negotiated)) {
+        throw new Error("ACP initialize result is missing an integer protocolVersion.");
+    }
+    if (negotiated !== ACP_PROTOCOL_VERSION) {
+        throw new Error(`ACP Agent negotiated protocol version ${negotiated}; Yui implements version `
+            + `${ACP_PROTOCOL_VERSION}. Select an Agent build that speaks this version.`);
+    }
+    const capabilities = asObject(result.agentCapabilities) ?? {};
+    const prompt = asObject(capabilities.promptCapabilities) ?? {};
+    const session = asObject(capabilities.sessionCapabilities) ?? {};
+    const info = asObject(result.agentInfo) ?? {};
+    return Object.freeze({
+        protocolVersion: negotiated,
+        capabilities: Object.freeze({
+            loadSession: capabilities.loadSession === true,
+            // A capability object being present (even empty) is how ACP signals
+            // support for these; absence or false means unsupported.
+            resumeSession: isCapabilityPresent(session.resume),
+            closeSession: isCapabilityPresent(session.close),
+            additionalDirectories: isCapabilityPresent(session.additionalDirectories),
+            promptImage: prompt.image === true,
+            promptAudio: prompt.audio === true,
+            promptEmbeddedContext: prompt.embeddedContext === true
+        }),
+        authMethods: Object.freeze(readAuthMethods(result.authMethods)),
+        ...(optionalText(info.name) === undefined ? {} : { agentName: optionalText(info.name) }),
+        ...(optionalText(info.version) === undefined
+            ? {}
+            : { agentVersion: optionalText(info.version) })
+    });
+}
+function isCapabilityPresent(value) {
+    return value === true || (value !== null && typeof value === "object" && !Array.isArray(value));
+}
+function readAuthMethods(value) {
+    if (!Array.isArray(value))
+        return [];
+    const methods = [];
+    for (const entry of value) {
+        const method = asObject(entry);
+        const id = method === null ? undefined : optionalText(method.id);
+        if (method === null || id === undefined)
+            continue;
+        methods.push(Object.freeze({
+            id,
+            ...(optionalText(method.name) === undefined ? {} : { name: optionalText(method.name) }),
+            ...(optionalText(method.description) === undefined
+                ? {}
+                : { description: optionalText(method.description) })
+        }));
+    }
+    return methods;
+}
+export function acpNewSessionRequest(cwd, additionalDirectories = []) {
+    // `mcpServers` is required by the specification; Yui exposes none over ACP.
+    return {
+        cwd,
+        mcpServers: [],
+        // Clients MUST only send `additionalDirectories` when the Agent advertised
+        // `sessionCapabilities.additionalDirectories`, so the caller gates this and
+        // passes an empty list for an Agent that never offered the field. Omitting
+        // the key entirely — rather than sending `[]` — keeps the request byte-wise
+        // identical to what an Agent without the capability expects.
+        ...(additionalDirectories.length === 0
+            ? {}
+            : { additionalDirectories: [...additionalDirectories] })
+    };
+}
+export function acpPromptRequest(sessionId, text) {
+    // Text is the baseline ContentBlock every ACP Agent must accept, so a prompt
+    // never depends on a negotiated prompt capability.
+    return { sessionId, prompt: [{ type: "text", text }] };
+}
+/**
+ * Read a `configOptions` array from a session setup or set-option result.
+ *
+ * Returns undefined when the field is absent, which is how an Agent that
+ * predates config options answers; that is a different fact from an Agent
+ * answering with an empty list, which offers nothing configurable. Callers must
+ * be able to tell those apart, so the absence is not flattened to `[]`.
+ */
+export function readAcpConfigOptions(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const options = [];
+    for (const entry of value) {
+        const option = asObject(entry);
+        if (option === null)
+            continue;
+        const id = optionalText(option.id);
+        // A select option's current value and choices are what make it settable.
+        // An entry missing either cannot be acted on, and inventing a default here
+        // would let Yui report a selection the Agent never offered.
+        const currentValue = optionalText(option.currentValue);
+        if (id === undefined || currentValue === undefined)
+            continue;
+        if (option.type !== undefined && option.type !== "select")
+            continue;
+        if (!Array.isArray(option.options))
+            continue;
+        const values = [];
+        for (const candidate of option.options) {
+            const choice = asObject(candidate);
+            const choiceValue = choice === null ? undefined : optionalText(choice.value);
+            if (choice === null || choiceValue === undefined)
+                continue;
+            values.push(Object.freeze({
+                value: choiceValue,
+                name: optionalText(choice.name) ?? choiceValue,
+                ...(optionalText(choice.description) === undefined
+                    ? {}
+                    : { description: optionalText(choice.description) })
+            }));
+        }
+        options.push(Object.freeze({
+            id,
+            name: optionalText(option.name) ?? id,
+            ...(optionalText(option.description) === undefined
+                ? {}
+                : { description: optionalText(option.description) }),
+            ...(optionalText(option.category) === undefined
+                ? {}
+                : { category: optionalText(option.category) }),
+            currentValue,
+            options: Object.freeze(values)
+        }));
+    }
+    return Object.freeze(options);
+}
+/** The config option id ACP uses for a session's permission mode. */
+export const ACP_MODE_CONFIG_ID = "mode";
+export function readAcpSessionConfiguration(value) {
+    const result = asObject(value);
+    const modern = readAcpConfigOptions(result?.configOptions);
+    if (modern !== undefined) {
+        return Object.freeze({ options: modern, legacyModes: false });
+    }
+    const legacy = readAcpSessionModes(result?.modes);
+    return Object.freeze({
+        options: legacy === undefined ? Object.freeze([]) : Object.freeze([legacy]),
+        legacyModes: legacy !== undefined
+    });
+}
+/**
+ * Convert the legacy `modes` field into the one config option it describes.
+ *
+ * The shape is fixed by ACP: `currentModeId` plus `availableModes`. Presenting
+ * it as a config option keeps mode selection in one vocabulary without
+ * pretending the Agent supports the newer method.
+ */
+function readAcpSessionModes(value) {
+    const modes = asObject(value);
+    const currentValue = modes === null ? undefined : optionalText(modes.currentModeId);
+    if (modes === null || currentValue === undefined)
+        return undefined;
+    const values = [];
+    if (Array.isArray(modes.availableModes)) {
+        for (const entry of modes.availableModes) {
+            const mode = asObject(entry);
+            const id = mode === null ? undefined : optionalText(mode.id);
+            if (mode === null || id === undefined)
+                continue;
+            values.push(Object.freeze({
+                value: id,
+                name: optionalText(mode.name) ?? id,
+                ...(optionalText(mode.description) === undefined
+                    ? {}
+                    : { description: optionalText(mode.description) })
+            }));
+        }
+    }
+    return Object.freeze({
+        id: ACP_MODE_CONFIG_ID,
+        name: "Mode",
+        category: "mode",
+        currentValue,
+        options: Object.freeze(values)
+    });
+}
+export function acpSetConfigOptionRequest(sessionId, configId, value) {
+    return { sessionId, configId, value };
+}
+export function acpSetModeRequest(sessionId, modeId) {
+    return { sessionId, modeId };
+}
+export function acpCancelNotification(sessionId) {
+    return { sessionId };
+}
+const STOP_REASONS = [
+    "end_turn",
+    "max_tokens",
+    "max_turn_requests",
+    "refusal",
+    "cancelled"
+];
+export function readAcpStopReason(value) {
+    const result = asObject(value);
+    const reason = result?.stopReason;
+    return STOP_REASONS.find((candidate) => candidate === reason);
+}
+/**
+ * Map a stop reason onto Yui's terminal vocabulary. Only `end_turn` is a
+ * completed Turn: a token or request ceiling and a refusal each ended the Turn
+ * without delivering the requested work, and reporting them as success would
+ * hide a real outcome from the Task record.
+ */
+export function acpTerminalStatus(reason) {
+    switch (reason) {
+        case "end_turn":
+            return "completed";
+        case "cancelled":
+            return "cancelled";
+        default:
+            return "failed";
+    }
+}
+export function acpStopReasonDetail(reason) {
+    switch (reason) {
+        case "max_tokens":
+            return "ACP Agent stopped at its token limit (stopReason=max_tokens).";
+        case "max_turn_requests":
+            return "ACP Agent stopped at its per-Turn model request limit "
+                + "(stopReason=max_turn_requests).";
+        case "refusal":
+            return "ACP Agent refused to continue the Turn (stopReason=refusal).";
+        case "cancelled":
+            return "ACP Agent reported the Turn as cancelled (stopReason=cancelled).";
+        case "end_turn":
+            return "ACP Agent completed the Turn (stopReason=end_turn).";
+    }
+}
+/** Decode a `session/update` notification payload for the given session. */
+export function readAcpSessionUpdate(params, sessionId) {
+    const value = asObject(params);
+    if (value === null || optionalText(value.sessionId) !== sessionId)
+        return undefined;
+    const update = asObject(value.update);
+    const kind = update === null ? undefined : optionalText(update.sessionUpdate);
+    if (update === null || kind === undefined)
+        return undefined;
+    switch (kind) {
+        case "agent_message_chunk": {
+            const text = readContentText(update.content);
+            return text === undefined ? undefined : Object.freeze({ kind: "agent-message", text });
+        }
+        case "tool_call": {
+            const toolCallId = optionalText(update.toolCallId);
+            if (toolCallId === undefined)
+                return undefined;
+            return Object.freeze({
+                kind: "tool-call",
+                toolCallId,
+                ...(optionalText(update.title) === undefined
+                    ? {}
+                    : { title: optionalText(update.title) }),
+                ...(optionalText(update.status) === undefined
+                    ? {}
+                    : { status: optionalText(update.status) })
+            });
+        }
+        case "tool_call_update": {
+            const toolCallId = optionalText(update.toolCallId);
+            if (toolCallId === undefined)
+                return undefined;
+            return Object.freeze({
+                kind: "tool-call-update",
+                toolCallId,
+                ...(optionalText(update.status) === undefined
+                    ? {}
+                    : { status: optionalText(update.status) })
+            });
+        }
+        case "plan":
+            return Object.freeze({ kind: "plan" });
+        case "config_option_update": {
+            const options = readAcpConfigOptions(update.configOptions);
+            return options === undefined
+                ? undefined
+                : Object.freeze({ kind: "config-options", options });
+        }
+        case "current_mode_update": {
+            const modeId = optionalText(update.currentModeId);
+            return modeId === undefined ? undefined : Object.freeze({ kind: "mode", modeId });
+        }
+        case "usage_update":
+            return Object.freeze({
+                kind: "usage",
+                ...(safeCount(update.used) === undefined ? {} : { used: safeCount(update.used) }),
+                ...(safeCount(update.size) === undefined ? {} : { size: safeCount(update.size) })
+            });
+        default:
+            return Object.freeze({ kind: "other", sessionUpdate: kind });
+    }
+}
+function readContentText(value) {
+    const content = asObject(value);
+    if (content === null || content.type !== "text")
+        return undefined;
+    return typeof content.text === "string" ? content.text : undefined;
+}
+export function readAcpPermissionRequest(params) {
+    const value = asObject(params);
+    const sessionId = value === null ? undefined : optionalText(value.sessionId);
+    if (value === null || sessionId === undefined)
+        return undefined;
+    const toolCall = asObject(value.toolCall);
+    const options = [];
+    if (Array.isArray(value.options)) {
+        for (const entry of value.options) {
+            const option = asObject(entry);
+            const optionId = option === null ? undefined : optionalText(option.optionId);
+            const kind = option === null ? undefined : optionalText(option.kind);
+            if (option === null || optionId === undefined || !isPermissionOptionKind(kind))
+                continue;
+            options.push(Object.freeze({
+                optionId,
+                name: optionalText(option.name) ?? optionId,
+                kind
+            }));
+        }
+    }
+    const toolCallId = toolCall === null ? undefined : optionalText(toolCall.toolCallId);
+    return Object.freeze({
+        sessionId,
+        ...(toolCallId === undefined ? {} : { toolCallId }),
+        options: Object.freeze(options)
+    });
+}
+function isPermissionOptionKind(value) {
+    return value === "allow_once" || value === "allow_always"
+        || value === "reject_once" || value === "reject_always";
+}
+/**
+ * Choose a permission response without ever granting authority on the user's
+ * behalf. Yui holds no interactive consent on this transport, so an Agent's
+ * request to act is declined: an explicit reject option when the Agent offered
+ * one, otherwise the `cancelled` outcome the specification always permits.
+ * Escalating to an allow option here would silently convert an absent user
+ * decision into a granted one.
+ */
+export function acpDeclinePermission(request) {
+    const reject = request.options.find((option) => option.kind === "reject_once")
+        ?? request.options.find((option) => option.kind === "reject_always");
+    return reject === undefined
+        ? Object.freeze({ outcome: "cancelled" })
+        : Object.freeze({ outcome: "selected", optionId: reject.optionId, kind: reject.kind });
+}
+export function acpPermissionResult(decision) {
+    return decision.outcome === "selected"
+        ? { outcome: { outcome: "selected", optionId: decision.optionId } }
+        : { outcome: { outcome: "cancelled" } };
+}
+export function acpPermissionSummary(request, decision) {
+    const target = request.toolCallId === undefined
+        ? "an operation"
+        : `tool call ${request.toolCallId}`;
+    return decision.outcome === "selected"
+        ? `Yui declined ACP permission for ${target} using option ${decision.optionId}.`
+        : `Yui returned the cancelled outcome for an ACP permission request covering ${target}.`;
+}
+export function asObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+export function optionalText(value) {
+    return typeof value === "string" && value.trim().length > 0 && !value.includes("\0")
+        ? value.trim()
+        : undefined;
+}
+function safeCount(value) {
+    return Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}