@aragon-agent/cli 0.6.38 → 0.6.39

package/dist/exec/bridge/protocol.d.ts

@@ -0,0 +1,346 @@
+/**
+ * The bridge wire protocol: frame types, one parser, and the outbound builders.
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * PURE. No I/O, no timers, no streams: every function here takes text or plain
+ * objects and returns text or plain objects. That is what makes the protocol
+ * testable at the level where the bugs actually live (a frame with a missing
+ * field, a `respondsTo` that points at nothing) without a subprocess in sight.
+ *
+ * TWO RULES DECIDE EVERYTHING BELOW, and they pull in opposite directions:
+ *
+ *   AN UNKNOWN `type` IS SILENTLY IGNORED (forward compatibility). A caller
+ *   written against a newer CLI must not be punished for a frame this build never
+ *   heard of; the same promise `stdin-stream.ts` already makes for `stream-json`.
+ *
+ *   AN UNKNOWN `respondsTo` IS AN ERROR (caller bug). There is no forward
+ *   compatibility to preserve - the caller answered a request that does not
+ *   exist - and silence would leave it waiting for an outcome forever.
+ */
+import type { NormalizedPlan, NormalizedQuestion, HumanRequest } from '../../tools/human-input.js';
+export declare const BRIDGE_PROTOCOL_VERSION = 2;
+/**
+ * What this build announces in `system/init.capabilities` when bridge is on.
+ *
+ * APPEND ONLY, NEVER REORDER, same discipline as `EXEC_CAPABILITIES`: the caller
+ * asks `includes('caller_tools')` and ignores what it does not recognise.
+ */
+export declare const BRIDGE_CAPABILITIES: readonly string[];
+/** The four things a caller can be asked to decide. */
+export type DecisionKind = 'tool' | 'questions' | 'plan' | 'skill_install';
+/**
+ * The two directions a pending request can travel.
+ *
+ * `decision` is the CLI asking (a tool approval, a question, a plan, an install);
+ * `caller_tool` is the CLI asking the caller to DO something. A `respondsTo`
+ * pointing at the wrong one is `bridge_kind_mismatch`, which is why the table has
+ * to know which kind each id belongs to.
+ */
+export type PendingKindValue = 'decision' | 'caller_tool';
+/**
+ * Where a tool call came from. `depth` 0 is the lead; subagents are 1 or more.
+ *
+ * SENT ON EVERY REQUEST, even the lead's, so a caller never has to infer it from
+ * the absence of a field - the same reason `sessionFile ?? null` is stamped
+ * unconditionally on `system/init`.
+ */
+export interface AgentScope {
+    id: string;
+    label: string;
+    depth: number;
+}
+export declare const LEAD_SCOPE: AgentScope;
+/** One caller-served tool, as `tool_register` declares it. */
+export interface CallerToolSpec {
+    name: string;
+    label?: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    timeoutMs?: number;
+}
+export interface BridgePromptFrame {
+    type: 'prompt';
+    id?: string;
+    text: string;
+    /**
+     * Thread mode only (headless-threads-and-lifecycle-hooks section 2.3.2). ABSENT
+     * MEANS THE DEFAULT THREAD `main`, which is what keeps a v1 caller working without
+     * a single change (AC-11).
+     */
+    threadId?: string;
+}
+export interface BridgeSteerFrame {
+    type: 'steer';
+    id?: string;
+    text: string;
+    threadId?: string;
+}
+export interface BridgeInterruptFrame {
+    type: 'interrupt';
+    id?: string;
+    /** Omitted means "the turn in flight". A queued turn is named explicitly. */
+    requestId?: string;
+    /**
+     * A THREAD ID HERE IS A REFUSAL, NOT A ROUTE (section 2.3.2 / AC-34).
+     *
+     * It is parsed so the router can answer
+     * `ack{accepted:false, code:'interrupt_is_process_level'}` instead of treating the
+     * frame as unknown. Degrading it to `cancel_request` would erase the difference
+     * between "the user pressed Ctrl-C" and "the backend withdrew one request".
+     */
+    threadId?: string;
+}
+/**
+ * Stop ONE request; keep the process serving (section 2.4.7).
+ *
+ * A SECOND FRAME RATHER THAN A FLAG ON `interrupt`, because the two answer different
+ * questions: `interrupt` means "stop this RUN" (process-level, `128 + signo`), and
+ * re-purposing it would make "the user pressed Ctrl-C" indistinguishable from "the
+ * backend withdrew one request" - after the fact there would be no way to tell.
+ *
+ * It is a CONTROL frame, so it continues to be routed after `end` (a caller that has
+ * sent its last prompt is still entitled to withdraw one), and it is ignored after
+ * `result` like every other frame.
+ */
+export interface BridgeCancelRequestFrame {
+    type: 'cancel_request';
+    /** This frame's own id, echoed on the `ack`. */
+    id?: string;
+    /** Omitted means "the request in flight"; named, it must match one exactly. */
+    requestId?: string;
+    threadId?: string;
+}
+/**
+ * The four decision shapes share one frame, discriminated by what it carries.
+ *
+ * A SINGLE FRAME RATHER THAN FOUR is the whole point of `kind` on the outbound
+ * side: the caller answers with the same envelope whatever it was asked, and the
+ * gate that asked is the one that knows how to read the answer.
+ */
+export interface BridgeDecisionFrame {
+    type: 'decision';
+    id?: string;
+    /**
+     * OPTIONAL ON PURPOSE (section 2.3.2). `respondsTo` is already globally unique, so a
+     * caller that lost its thread bookkeeping is still served correctly by the default
+     * thread's server - which is why the field is a convenience rather than a key.
+     */
+    threadId?: string;
+    respondsTo: string;
+    decision?: 'allow' | 'deny';
+    scope?: 'once' | 'session';
+    reason?: string;
+    /** Untrusted. `validateHumanResponse` is the only reader. */
+    answers?: unknown;
+    cancelled?: boolean;
+    planDecision?: unknown;
+    feedback?: string;
+}
+export interface BridgeToolResultFrame {
+    type: 'tool_result';
+    id?: string;
+    threadId?: string;
+    respondsTo: string;
+    /** A string is one text part; an array is a content-block list. */
+    content: unknown;
+    isError?: boolean;
+}
+export interface BridgeToolRegisterFrame {
+    type: 'tool_register';
+    id?: string;
+    threadId?: string;
+    /** Untrusted; `validateCallerTools` narrows it. */
+    tools: unknown[];
+}
+/**
+ * Open one more conversation (section 2.3.2).
+ *
+ * ACCEPTED ONLY IN THREAD MODE. Without `--threads` the answer is
+ * `ack{accepted:false, code:'threads_disabled'}` (AC-2), never silence: a wrapper that
+ * believes it opened a thread and gets nothing would send prompts into `main` and
+ * receive answers to a conversation it never asked for.
+ */
+export interface BridgeThreadOpenFrame {
+    type: 'thread_open';
+    id?: string;
+    /** `[a-z0-9][a-z0-9_-]{0,31}`; `resolveThreadIdentity` is the only validator. */
+    threadId: string;
+    /** Explicit session id; absent means `${base}-${threadId}`. */
+    sessionId?: string;
+}
+export interface BridgeThreadCloseFrame {
+    type: 'thread_close';
+    id?: string;
+    threadId: string;
+    /** `settle` (default) waits for the request in flight; `abort` cancels it. */
+    mode?: 'settle' | 'abort';
+}
+export interface BridgeThreadListFrame {
+    type: 'thread_list';
+    id?: string;
+}
+/**
+ * Register lifecycle hooks (section 2.4.2).
+ *
+ * `hooks` IS `unknown[]` ON PURPOSE: the frame comes off a pipe, and `validateHookSpecs`
+ * is the only reader. Typing it here would be a lie TypeScript happily propagates into
+ * a timeout table.
+ */
+export interface BridgeHookRegisterFrame {
+    type: 'hook_register';
+    id?: string;
+    threadId?: string;
+    hooks: unknown[];
+}
+/**
+ * The caller's answer to one `hook_request`.
+ *
+ * ONE FRAME FOR FOUR POINTS, discriminated by `action` - the same shape `decision`
+ * already uses for its four kinds. The point is not repeated because the CLI already
+ * knows which hook id it asked with.
+ */
+export interface BridgeHookAnswerFrame {
+    type: 'hook_answer';
+    id?: string;
+    threadId?: string;
+    respondsTo: string;
+    /** `allow` | `deny` | `rewrite` | `inject` | `keep` | `replace`; validated by point. */
+    action: string;
+    /** `prompt_pre` rewrite and `turn_start` inject. */
+    text?: string;
+    /** `tool_pre` rewrite. */
+    input?: unknown;
+    /** `tool_post` replace. */
+    content?: unknown;
+    isError?: boolean;
+    reason?: string;
+    message?: string;
+}
+export interface BridgePingFrame {
+    type: 'ping';
+    id?: string;
+}
+export interface BridgeEndFrame {
+    type: 'end';
+}
+/** A `type` this build does not know. Parsed successfully, then ignored. */
+export interface BridgeIgnoredFrame {
+    type: 'ignored';
+    rawType: string;
+}
+export type BridgeInputFrame = BridgePromptFrame | BridgeSteerFrame | BridgeInterruptFrame | BridgeCancelRequestFrame | BridgeDecisionFrame | BridgeToolResultFrame | BridgeToolRegisterFrame | BridgeThreadOpenFrame | BridgeThreadCloseFrame | BridgeThreadListFrame | BridgeHookRegisterFrame | BridgeHookAnswerFrame | BridgePingFrame | BridgeEndFrame | BridgeIgnoredFrame;
+export interface BridgeParseOk {
+    ok: true;
+    frame: BridgeInputFrame;
+}
+export interface BridgeParseFailure {
+    ok: false;
+    /** A stable `error.code` value; see the event contract in `events.ts`. */
+    code: string;
+    message: string;
+}
+export type BridgeParseResult = BridgeParseOk | BridgeParseFailure;
+export declare const BRIDGE_FRAME_INVALID = "bridge_frame_invalid";
+export declare const BRIDGE_FRAME_TOO_LARGE = "bridge_frame_too_large";
+/** The `tool` payload of a `decision_request{kind:'tool'}`. */
+export interface DecisionToolPayload {
+    name: string;
+    callId: string;
+    input: Record<string, unknown>;
+    /** One readable line, e.g. `Run: npm test`. Reuses `summarize()`. */
+    summary: string;
+    turn: number;
+}
+export interface DecisionInstallPayload {
+    tool: string;
+    summary: string;
+}
+/** What one `requestDecision` call is asking about. */
+export type DecisionAsk = {
+    kind: 'tool';
+    tool: DecisionToolPayload;
+    agent?: AgentScope;
+} | {
+    kind: 'questions';
+    questions: NormalizedQuestion[];
+    agent?: AgentScope;
+} | {
+    kind: 'plan';
+    plan: NormalizedPlan;
+    agent?: AgentScope;
+} | {
+    kind: 'skill_install';
+    install: DecisionInstallPayload;
+    agent?: AgentScope;
+};
+/**
+ * The caller's answer, unvalidated. `kind` on the request decides its shape.
+ *
+ * DELIBERATELY LOOSE. These fields come off a pipe, so they are `unknown` until a
+ * validator says otherwise; typing them as `Answer[]` here would be a lie that
+ * TypeScript happily propagates into model-visible text.
+ */
+export interface DecisionAnswer {
+    decision?: 'allow' | 'deny';
+    scope?: 'once' | 'session';
+    reason?: string;
+    answers?: unknown;
+    cancelled?: boolean;
+    planDecision?: unknown;
+    feedback?: string;
+}
+/**
+ * What `requestDecision` resolves with. IT NEVER REJECTS, AND EVERY NON-ANSWER IS
+ * ITS OWN MEMBER (review P1-6).
+ *
+ * A boolean would have collapsed four different situations - answered, timed out,
+ * the turn was aborted, the channel closed - into "not allowed", and the gate
+ * that has to write model-visible text cannot tell them apart afterwards. The
+ * three non-`answered` members also all map to `null` on the `HumanInputGate`
+ * path, because its contract is "resolves null on cancel" rather than "invent an
+ * empty answer".
+ */
+export type DecisionOutcome = {
+    outcome: 'answered';
+    answer: DecisionAnswer;
+} | {
+    outcome: 'timeout';
+    deadlineAt: number;
+} | {
+    outcome: 'aborted';
+} | {
+    outcome: 'closed';
+    reason: string;
+};
+/** A model-driven call into a caller tool. */
+export interface CallerToolCall {
+    callId: string;
+    turn: number;
+    tool: string;
+    input: Record<string, unknown>;
+    /** The EFFECTIVE ceiling, after `min(spec, --caller-tool-timeout)`. */
+    timeoutMs: number;
+    agent: AgentScope;
+}
+/** A caller tool's answer, before truncation and content checks. */
+export interface CallerToolAnswer {
+    content: unknown;
+    isError?: boolean;
+}
+/**
+ * Turn one stdin line into a frame, or into a stable failure code.
+ *
+ * THE OVER-LONG CHECK IS HERE AS WELL AS IN THE SPLITTER, on purpose: the
+ * splitter protects memory, this protects the contract, and a caller that raises
+ * `maxFrameBytes` for a test still gets the same refusal from the parser.
+ */
+export declare function parseBridgeInput(line: string): BridgeParseResult;
+/**
+ * Map a `HumanInputGate` request onto the frame that asks the caller.
+ *
+ * THE CLI IS THE AUTHORITY ON THE QUESTIONS, and this function is where that is
+ * visible: it copies the normalized question set the model produced, so the
+ * caller renders what was actually asked rather than inventing its own text.
+ */
+export declare function humanDecisionFrame(req: HumanRequest): DecisionAsk;

package/dist/exec/bridge/protocol.js

@@ -0,0 +1,256 @@
+import { BRIDGE_LIMITS } from './limits.js';
+export const BRIDGE_PROTOCOL_VERSION = 2;
+/**
+ * What this build announces in `system/init.capabilities` when bridge is on.
+ *
+ * APPEND ONLY, NEVER REORDER, same discipline as `EXEC_CAPABILITIES`: the caller
+ * asks `includes('caller_tools')` and ignores what it does not recognise.
+ */
+export const BRIDGE_CAPABILITIES = [
+    'bridge',
+    'decision',
+    'caller_tools',
+    'steer',
+    'ping',
+    // Per-request budgets, accounting, cancellation and `request_end`
+    // (headless-request-scope-and-typed-result section 4.2). APPENDED, and the protocol
+    // version stays 2: `protocolVersion` only ever moves for an INCOMPATIBLE shape
+    // change, and every frame this capability promises is additive.
+    'request_scope',
+];
+export const LEAD_SCOPE = { id: 'lead', label: 'lead', depth: 0 };
+export const BRIDGE_FRAME_INVALID = 'bridge_frame_invalid';
+export const BRIDGE_FRAME_TOO_LARGE = 'bridge_frame_too_large';
+// ---------------------------------------------------------------------------
+// Parsing
+// ---------------------------------------------------------------------------
+function invalid(message) {
+    return { ok: false, code: BRIDGE_FRAME_INVALID, message };
+}
+function optionalString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value : undefined;
+}
+/**
+ * Turn one stdin line into a frame, or into a stable failure code.
+ *
+ * THE OVER-LONG CHECK IS HERE AS WELL AS IN THE SPLITTER, on purpose: the
+ * splitter protects memory, this protects the contract, and a caller that raises
+ * `maxFrameBytes` for a test still gets the same refusal from the parser.
+ */
+export function parseBridgeInput(line) {
+    const bytes = Buffer.byteLength(line, 'utf-8');
+    if (bytes > BRIDGE_LIMITS.maxFrameBytes) {
+        return {
+            ok: false,
+            code: BRIDGE_FRAME_TOO_LARGE,
+            message: `Skipped a bridge frame of ${bytes} bytes; the limit is ${BRIDGE_LIMITS.maxFrameBytes}.`,
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return invalid(`Skipped a bridge line that is not JSON: ${clip(line)}`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return invalid(`Skipped a bridge line that is not a JSON object: ${clip(line)}`);
+    }
+    const raw = parsed;
+    const type = typeof raw.type === 'string' ? raw.type : '';
+    if (type.length === 0)
+        return invalid('A bridge frame needs a string "type".');
+    // `user` is the v1 spelling of a prompt with no id. Kept because a caller
+    // migrated from `--input-format stream-json` should not have to rewrite.
+    if (type === 'user')
+        return parsePrompt({ ...raw, type: 'prompt' }, raw);
+    if (type === 'prompt')
+        return parsePrompt(raw, raw);
+    if (type === 'steer') {
+        const text = typeof raw.text === 'string' ? raw.text : '';
+        if (text.trim().length === 0)
+            return invalid('A "steer" frame needs a non-empty "text".');
+        return okFrame({ type: 'steer', text, ...idOf(raw), ...threadOf(raw) });
+    }
+    if (type === 'interrupt') {
+        const requestId = optionalString(raw.requestId);
+        return okFrame({
+            type: 'interrupt',
+            ...idOf(raw),
+            ...threadOf(raw),
+            ...(requestId ? { requestId } : {}),
+        });
+    }
+    if (type === 'cancel_request') {
+        // EVERY FIELD IS OPTIONAL, so there is nothing to reject: no `requestId` means "the
+        // request in flight", which is exactly what a caller that lost its own bookkeeping
+        // would send. Whether the target exists is a ROUTING question, answered by the
+        // runner with an `ack` - not a parse question.
+        const requestId = optionalString(raw.requestId);
+        return okFrame({
+            type: 'cancel_request',
+            ...idOf(raw),
+            ...threadOf(raw),
+            ...(requestId ? { requestId } : {}),
+        });
+    }
+    if (type === 'decision')
+        return parseDecision(raw);
+    if (type === 'tool_result')
+        return parseToolResult(raw);
+    if (type === 'tool_register') {
+        if (!Array.isArray(raw.tools))
+            return invalid('A "tool_register" frame needs a "tools" array.');
+        return okFrame({ type: 'tool_register', tools: raw.tools, ...idOf(raw), ...threadOf(raw) });
+    }
+    if (type === 'thread_open')
+        return parseThreadOpen(raw);
+    if (type === 'thread_close')
+        return parseThreadClose(raw);
+    if (type === 'thread_list')
+        return okFrame({ type: 'thread_list', ...idOf(raw) });
+    if (type === 'hook_register') {
+        if (!Array.isArray(raw.hooks))
+            return invalid('A "hook_register" frame needs a "hooks" array.');
+        return okFrame({ type: 'hook_register', hooks: raw.hooks, ...idOf(raw), ...threadOf(raw) });
+    }
+    if (type === 'hook_answer')
+        return parseHookAnswer(raw);
+    if (type === 'ping')
+        return okFrame({ type: 'ping', ...idOf(raw) });
+    if (type === 'end')
+        return okFrame({ type: 'end' });
+    // FORWARD COMPATIBILITY, the one case that is silent by design.
+    return okFrame({ type: 'ignored', rawType: type });
+}
+function okFrame(frame) {
+    return { ok: true, frame };
+}
+function idOf(raw) {
+    const id = optionalString(raw.id);
+    return id ? { id } : {};
+}
+/**
+ * `threadId` is only ever the ROUTE, never validated here.
+ *
+ * Whether an id names an open thread is a registry question with an `ack` for an
+ * answer; whether it is well FORMED is `resolveThreadIdentity`'s question, and it
+ * produces the `thread_id_invalid` refusal. A parser that also judged the shape would
+ * give the same input two different refusals depending on which layer saw it first.
+ */
+function threadOf(raw) {
+    const threadId = optionalString(raw.threadId);
+    return threadId ? { threadId } : {};
+}
+function parseThreadOpen(raw) {
+    const threadId = optionalString(raw.threadId);
+    if (!threadId)
+        return invalid('A "thread_open" frame needs a "threadId".');
+    const sessionId = optionalString(raw.sessionId);
+    return okFrame({
+        type: 'thread_open',
+        threadId,
+        ...idOf(raw),
+        ...(sessionId ? { sessionId } : {}),
+    });
+}
+function parseThreadClose(raw) {
+    const threadId = optionalString(raw.threadId);
+    if (!threadId)
+        return invalid('A "thread_close" frame needs a "threadId".');
+    // AN UNKNOWN MODE IS A PARSE ERROR, NOT A DEFAULT (AC-31 / AC-32). Coercing `"ABORT"` or
+    // a typo to `settle` would answer "wait for the request in flight" to a caller that asked
+    // to cancel it - the two behaviours differ in whether the work happens at all.
+    if (raw.mode !== undefined && raw.mode !== 'abort' && raw.mode !== 'settle') {
+        return invalid('A "thread_close" mode must be "settle" or "abort".');
+    }
+    return okFrame({
+        type: 'thread_close',
+        threadId,
+        ...idOf(raw),
+        ...(raw.mode === 'abort' || raw.mode === 'settle' ? { mode: raw.mode } : {}),
+    });
+}
+function parseHookAnswer(raw) {
+    const respondsTo = optionalString(raw.respondsTo);
+    if (!respondsTo)
+        return invalid('A "hook_answer" frame needs "respondsTo".');
+    const action = optionalString(raw.action);
+    if (!action)
+        return invalid('A "hook_answer" frame needs an "action".');
+    return okFrame({
+        type: 'hook_answer',
+        respondsTo,
+        action,
+        ...idOf(raw),
+        ...threadOf(raw),
+        ...(typeof raw.text === 'string' ? { text: raw.text } : {}),
+        ...(raw.input !== undefined ? { input: raw.input } : {}),
+        ...(raw.content !== undefined ? { content: raw.content } : {}),
+        ...(raw.isError === true ? { isError: true } : {}),
+        ...(typeof raw.reason === 'string' ? { reason: raw.reason } : {}),
+        ...(typeof raw.message === 'string' ? { message: raw.message } : {}),
+    });
+}
+function parsePrompt(raw, idSource) {
+    const text = typeof raw.text === 'string' ? raw.text : raw.content;
+    if (typeof text !== 'string' || text.trim().length === 0) {
+        return invalid('A "prompt" frame needs a non-empty "text".');
+    }
+    return okFrame({ type: 'prompt', text, ...idOf(idSource), ...threadOf(raw) });
+}
+function parseDecision(raw) {
+    const respondsTo = optionalString(raw.respondsTo);
+    if (!respondsTo)
+        return invalid('A "decision" frame needs "respondsTo".');
+    const frame = { type: 'decision', respondsTo, ...idOf(raw), ...threadOf(raw) };
+    if (raw.decision === 'allow' || raw.decision === 'deny')
+        frame.decision = raw.decision;
+    if (raw.scope === 'once' || raw.scope === 'session')
+        frame.scope = raw.scope;
+    if (typeof raw.reason === 'string')
+        frame.reason = raw.reason;
+    if (typeof raw.feedback === 'string')
+        frame.feedback = raw.feedback;
+    if (raw.cancelled === true)
+        frame.cancelled = true;
+    if (raw.answers !== undefined)
+        frame.answers = raw.answers;
+    if (raw.planDecision !== undefined)
+        frame.planDecision = raw.planDecision;
+    return okFrame(frame);
+}
+function parseToolResult(raw) {
+    const respondsTo = optionalString(raw.respondsTo);
+    if (!respondsTo)
+        return invalid('A "tool_result" frame needs "respondsTo".');
+    if (raw.content === undefined)
+        return invalid('A "tool_result" frame needs "content".');
+    return okFrame({
+        type: 'tool_result',
+        respondsTo,
+        content: raw.content,
+        ...(raw.isError === true ? { isError: true } : {}),
+        ...idOf(raw),
+        ...threadOf(raw),
+    });
+}
+/** Keep an error message readable without dumping a megabyte into the event. */
+function clip(text) {
+    return text.length <= 120 ? text : `${text.slice(0, 117)}...`;
+}
+// ---------------------------------------------------------------------------
+// Outbound builders
+// ---------------------------------------------------------------------------
+/**
+ * Map a `HumanInputGate` request onto the frame that asks the caller.
+ *
+ * THE CLI IS THE AUTHORITY ON THE QUESTIONS, and this function is where that is
+ * visible: it copies the normalized question set the model produced, so the
+ * caller renders what was actually asked rather than inventing its own text.
+ */
+export function humanDecisionFrame(req) {
+    return req.kind === 'questions'
+        ? { kind: 'questions', questions: req.questions }
+        : { kind: 'plan', plan: req.plan };
+}