@sayknow-cli/coding-agent 0.3.13 → 0.3.16

package/dist/types/modes/rpc/rpc-types.d.ts

@@ -0,0 +1,810 @@
+/**
+ * RPC protocol types for headless operation.
+ *
+ * Commands are sent as JSON lines on stdin.
+ * Responses and events are emitted as JSON lines on stdout.
+ */
+import type { AgentMessage, AgentToolResult, ResolvedThinkingLevel, ThinkingLevel } from "@sayknow-cli/agent-core";
+import type { CompactionResult } from "@sayknow-cli/agent-core/compaction";
+import type { Effort, ImageContent, Model } from "@sayknow-cli/ai";
+import type { BashResult } from "../../exec/bash-executor";
+import type { ContextUsage } from "../../extensibility/extensions/types";
+import type { SessionStats } from "../../session/agent-session";
+import type { TodoPhase } from "../../tools/todo-write";
+export type RpcGetStateInclude = "tools" | "dumpTools" | "systemPrompt";
+export type RpcCapability = "compact_message_update";
+export type RpcCommand = {
+    id?: string;
+    type: "prompt";
+    message: string;
+    images?: ImageContent[];
+    streamingBehavior?: "steer" | "followUp";
+} | {
+    id?: string;
+    type: "steer";
+    message: string;
+    images?: ImageContent[];
+} | {
+    id?: string;
+    type: "follow_up";
+    message: string;
+    images?: ImageContent[];
+} | {
+    id?: string;
+    type: "abort";
+} | {
+    id?: string;
+    type: "abort_and_prompt";
+    message: string;
+    images?: ImageContent[];
+} | {
+    id?: string;
+    type: "new_session";
+    parentSession?: string;
+} | {
+    id?: string;
+    type: "get_state";
+    include?: RpcGetStateInclude[];
+} | {
+    id?: string;
+    type: "set_todos";
+    phases: TodoPhase[];
+} | {
+    id?: string;
+    type: "set_host_tools";
+    tools: RpcHostToolDefinition[];
+} | {
+    id?: string;
+    type: "set_host_uri_schemes";
+    schemes: RpcHostUriSchemeDefinition[];
+} | {
+    id?: string;
+    type: "get_pending_workflow_gates";
+} | {
+    id?: string;
+    type: "set_capabilities";
+    capabilities: RpcCapability[];
+} | {
+    id?: string;
+    type: "set_model";
+    provider: string;
+    modelId: string;
+} | {
+    id?: string;
+    type: "set_default_model_selection";
+    provider: string;
+    modelId: string;
+    thinkingLevel?: ResolvedThinkingLevel;
+} | {
+    id?: string;
+    type: "cycle_model";
+} | {
+    id?: string;
+    type: "get_available_models";
+} | {
+    id?: string;
+    type: "set_thinking_level";
+    level: ThinkingLevel;
+} | {
+    id?: string;
+    type: "cycle_thinking_level";
+} | {
+    id?: string;
+    type: "set_steering_mode";
+    mode: "all" | "one-at-a-time";
+} | {
+    id?: string;
+    type: "set_follow_up_mode";
+    mode: "all" | "one-at-a-time";
+} | {
+    id?: string;
+    type: "set_interrupt_mode";
+    mode: "immediate" | "wait";
+} | {
+    id?: string;
+    type: "compact";
+    customInstructions?: string;
+} | {
+    id?: string;
+    type: "set_auto_compaction";
+    enabled: boolean;
+} | {
+    id?: string;
+    type: "set_auto_retry";
+    enabled: boolean;
+} | {
+    id?: string;
+    type: "abort_retry";
+} | {
+    id?: string;
+    type: "bash";
+    command: string;
+} | {
+    id?: string;
+    type: "abort_bash";
+} | {
+    id?: string;
+    type: "get_session_stats";
+} | {
+    id?: string;
+    type: "export_html";
+    outputPath?: string;
+} | {
+    id?: string;
+    type: "switch_session";
+    sessionPath: string;
+} | {
+    id?: string;
+    type: "branch";
+    entryId: string;
+} | {
+    id?: string;
+    type: "get_branch_messages";
+} | {
+    id?: string;
+    type: "get_last_assistant_text";
+} | {
+    id?: string;
+    type: "set_session_name";
+    name: string;
+} | {
+    id?: string;
+    type: "handoff";
+    customInstructions?: string;
+} | {
+    id?: string;
+    type: "get_messages";
+} | {
+    id?: string;
+    type: "get_login_providers";
+} | {
+    id?: string;
+    type: "login";
+    providerId: string;
+} | {
+    id?: string;
+    type: "negotiate_unattended";
+    declaration: RpcUnattendedDeclaration;
+} | ({
+    id?: string;
+    type: "workflow_gate_response";
+} & RpcWorkflowGateResponse);
+export interface RpcSessionState {
+    model?: Model;
+    thinkingLevel: ThinkingLevel | undefined;
+    isStreaming: boolean;
+    isCompacting: boolean;
+    steeringMode: "all" | "one-at-a-time";
+    followUpMode: "all" | "one-at-a-time";
+    interruptMode: "immediate" | "wait";
+    sessionFile?: string;
+    sessionId: string;
+    sessionName?: string;
+    autoCompactionEnabled: boolean;
+    messageCount: number;
+    queuedMessageCount: number;
+    todoPhases: TodoPhase[];
+    /** Optional static system prompt blocks. Omitted by default; request with get_state include ["systemPrompt"]. */
+    systemPrompt?: string[];
+    /** Optional static tool schemas. Omitted by default; request with get_state include ["tools"]. */
+    dumpTools?: Array<{
+        name: string;
+        description: string;
+        parameters: unknown;
+    }>;
+    /** Current context window usage. Null tokens/percent when unknown (e.g. right after compaction). */
+    contextUsage?: ContextUsage;
+}
+export interface RpcHandoffResult {
+    savedPath?: string;
+}
+export type RpcResponse = {
+    id?: string;
+    type: "response";
+    command: "prompt";
+    success: true;
+} | {
+    id?: string;
+    type: "response";
+    command: "steer";
+    success: true;
+} | {
+    id?: string;
+    type: "response";
+    command: "follow_up";
+    success: true;
+} | {
+    id?: string;
+    type: "response";
+    command: "abort";
+    success: true;
+} | {
+    id?: string;
+    type: "response";
+    command: "abort_and_prompt";
+    success: true;
+} | {
+    id?: string;
+    type: "response";
+    command: "new_session";
+    success: true;
+    data: {
+        cancelled: boolean;
+    };
+} | {
+    id?: string;
+    type: "response";
+    command: "get_state";
+    success: true;
+    data: RpcSessionState;
+} | {
+    id?: string;
+    type: "response";
+    command: "set_todos";
+    success: true;
+    data: {
+        todoPhases: TodoPhase[];
+    };
+} | {
+    id?: string;
+    type: "response";
+    command: "set_host_tools";
+    success: true;
+    data: {
+        toolNames: string[];
+    };
+} | {
+    id?: string;
+    type: "response";
+    command: "set_host_uri_schemes";
+    success: true;
+    data: {
+        schemes: string[];
+    };
+} | {
+    id?: string;
+    type: "response";
+    command: "get_pending_workflow_gates";
+    success: true;
+    data: {
+        gates: RpcWorkflowGate[];
+    };
+} | {
+    id?: string;
+    type: "response";
+    command: "set_capabilities";
+    success: true;
+    data: {
+        acceptedCapabilities: RpcCapability[];
+        unsupported: string[];
+    };
+} | {
+    id?: string;
+    type: "response";
+    command: "set_model";
+    success: true;
+    data: Model;
+} | {
+    id?: string;
+    type: "response";
+    command: "set_default_model_selection";
+    success: true;
+    data: {
+        provider: string;
+        modelId: string;
+        thinkingLevel: ResolvedThinkingLevel;
+    };
+} | {
+    id?: string;
+    type: "response";
+    command: "cycle_model";
+    success: true;
+    data: {
+        model: Model;
+        thinkingLevel: ThinkingLevel | undefined;
+        isScoped: boolean;
+    } | null;
+} | {
+    id?: string;
+    type: "response";
+    command: "get_available_models";
+    success: true;
+    data: {
+        models: Model[];
+    };
+} | {
+    id?: string;
+    type: "response";
+    command: "set_thinking_level";
+    success: true;
+} | {
+    id?: string;
+    type: "response";
+    command: "cycle_thinking_level";
+    success: true;
+    data: {
+        level: Effort;
+    } | null;
+} | {
+    id?: string;
+    type: "response";
+    command: "set_steering_mode";
+    success: true;
+} | {
+    id?: string;
+    type: "response";
+    command: "set_follow_up_mode";
+    success: true;
+} | {
+    id?: string;
+    type: "response";
+    command: "set_interrupt_mode";
+    success: true;
+} | {
+    id?: string;
+    type: "response";
+    command: "compact";
+    success: true;
+    data: CompactionResult;
+} | {
+    id?: string;
+    type: "response";
+    command: "set_auto_compaction";
+    success: true;
+} | {
+    id?: string;
+    type: "response";
+    command: "set_auto_retry";
+    success: true;
+} | {
+    id?: string;
+    type: "response";
+    command: "abort_retry";
+    success: true;
+} | {
+    id?: string;
+    type: "response";
+    command: "bash";
+    success: true;
+    data: BashResult;
+} | {
+    id?: string;
+    type: "response";
+    command: "abort_bash";
+    success: true;
+} | {
+    id?: string;
+    type: "response";
+    command: "get_session_stats";
+    success: true;
+    data: SessionStats;
+} | {
+    id?: string;
+    type: "response";
+    command: "export_html";
+    success: true;
+    data: {
+        path: string;
+    };
+} | {
+    id?: string;
+    type: "response";
+    command: "switch_session";
+    success: true;
+    data: {
+        cancelled: boolean;
+    };
+} | {
+    id?: string;
+    type: "response";
+    command: "branch";
+    success: true;
+    data: {
+        text: string;
+        cancelled: boolean;
+    };
+} | {
+    id?: string;
+    type: "response";
+    command: "get_branch_messages";
+    success: true;
+    data: {
+        messages: Array<{
+            entryId: string;
+            text: string;
+        }>;
+    };
+} | {
+    id?: string;
+    type: "response";
+    command: "get_last_assistant_text";
+    success: true;
+    data: {
+        text: string | null;
+    };
+} | {
+    id?: string;
+    type: "response";
+    command: "set_session_name";
+    success: true;
+} | {
+    id?: string;
+    type: "response";
+    command: "handoff";
+    success: true;
+    data: RpcHandoffResult | null;
+} | {
+    id?: string;
+    type: "response";
+    command: "get_messages";
+    success: true;
+    data: {
+        messages: AgentMessage[];
+    };
+} | {
+    id?: string;
+    type: "response";
+    command: "get_login_providers";
+    success: true;
+    data: {
+        providers: Array<{
+            id: string;
+            name: string;
+            available: boolean;
+            authenticated: boolean;
+        }>;
+    };
+} | {
+    id?: string;
+    type: "response";
+    command: "login";
+    success: true;
+    data: {
+        providerId: string;
+    };
+} | {
+    id?: string;
+    type: "response";
+    command: "negotiate_unattended";
+    success: true;
+    data: RpcUnattendedAccepted;
+} | {
+    id?: string;
+    type: "response";
+    command: "workflow_gate_response";
+    success: true;
+    data: RpcWorkflowGateResolution;
+} | {
+    id?: string;
+    type: "response";
+    command: string;
+    success: false;
+    error: string | object;
+};
+/** Emitted when an extension needs user input */
+export type RpcExtensionUIRequest = {
+    type: "extension_ui_request";
+    id: string;
+    method: "select";
+    title: string;
+    options: string[];
+    timeout?: number;
+} | {
+    type: "extension_ui_request";
+    id: string;
+    method: "confirm";
+    title: string;
+    message: string;
+    timeout?: number;
+} | {
+    type: "extension_ui_request";
+    id: string;
+    method: "input";
+    title: string;
+    placeholder?: string;
+    timeout?: number;
+} | {
+    type: "extension_ui_request";
+    id: string;
+    method: "editor";
+    title: string;
+    prefill?: string;
+    promptStyle?: boolean;
+} | {
+    type: "extension_ui_request";
+    id: string;
+    method: "cancel";
+    targetId: string;
+} | {
+    type: "extension_ui_request";
+    id: string;
+    method: "notify";
+    message: string;
+    notifyType?: "info" | "warning" | "error";
+} | {
+    type: "extension_ui_request";
+    id: string;
+    method: "setStatus";
+    statusKey: string;
+    statusText: string | undefined;
+} | {
+    type: "extension_ui_request";
+    id: string;
+    method: "setWidget";
+    widgetKey: string;
+    widgetLines: string[] | undefined;
+    widgetPlacement?: "aboveEditor" | "belowEditor";
+} | {
+    type: "extension_ui_request";
+    id: string;
+    method: "setTitle";
+    title: string;
+} | {
+    type: "extension_ui_request";
+    id: string;
+    method: "set_editor_text";
+    text: string;
+} | {
+    type: "extension_ui_request";
+    id: string;
+    method: "open_url";
+    url: string;
+    instructions?: string;
+};
+export interface RpcHostToolDefinition {
+    name: string;
+    label?: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    hidden?: boolean;
+}
+/** Emitted by the RPC server when it needs the host to execute a registered tool. */
+export interface RpcHostToolCallRequest {
+    type: "host_tool_call";
+    id: string;
+    toolCallId: string;
+    toolName: string;
+    arguments: Record<string, unknown>;
+}
+/** Emitted by the RPC server when a pending host tool call should be aborted. */
+export interface RpcHostToolCancelRequest {
+    type: "host_tool_cancel";
+    id: string;
+    targetId: string;
+}
+/** Sent by the host to stream partial tool updates back to the RPC server. */
+export interface RpcHostToolUpdate {
+    type: "host_tool_update";
+    id: string;
+    partialResult: AgentToolResult<unknown>;
+}
+/** Sent by the host to complete a pending tool call. */
+export interface RpcHostToolResult {
+    type: "host_tool_result";
+    id: string;
+    result: AgentToolResult<unknown>;
+    isError?: boolean;
+}
+export interface RpcHostUriSchemeDefinition {
+    /** URL scheme without trailing `://` (e.g. `db`, `notion`). */
+    scheme: string;
+    /** Optional human-readable description for logs/diagnostics. */
+    description?: string;
+    /** When true, the write tool is allowed to dispatch writes to this scheme. */
+    writable?: boolean;
+    /** When true, downstream callers suppress hashline anchors for resolved content. */
+    immutable?: boolean;
+}
+export type RpcHostUriOperation = "read" | "write";
+/** Emitted by the RPC server when it needs the host to satisfy a URI operation. */
+export interface RpcHostUriRequest {
+    type: "host_uri_request";
+    id: string;
+    operation: RpcHostUriOperation;
+    url: string;
+    /** Present for write operations. */
+    content?: string;
+}
+/** Emitted by the RPC server when a pending URI request should be aborted. */
+export interface RpcHostUriCancelRequest {
+    type: "host_uri_cancel";
+    id: string;
+    targetId: string;
+}
+/** Sent by the host to complete a pending URI request. */
+export interface RpcHostUriResult {
+    type: "host_uri_result";
+    id: string;
+    /**
+     * Required for successful `read` results. Ignored for `write` success.
+     * Set on errors when a textual explanation accompanies `isError`.
+     */
+    content?: string;
+    /** Defaults to `text/plain` when omitted. */
+    contentType?: "text/markdown" | "application/json" | "text/plain";
+    /** Optional resolution notes propagated to the read tool. */
+    notes?: string[];
+    /** Overrides the scheme-level `immutable` flag for this single resolution. */
+    immutable?: boolean;
+    /** When true, surface the result content as an error to the caller. */
+    isError?: boolean;
+    /** Optional error message; preferred over `content` for error surfacing. */
+    error?: string;
+}
+/** Response to an extension UI request */
+export type RpcExtensionUIResponse = {
+    type: "extension_ui_response";
+    id: string;
+    value: string;
+} | {
+    type: "extension_ui_response";
+    id: string;
+    confirmed: boolean;
+} | {
+    type: "extension_ui_response";
+    id: string;
+    cancelled: true;
+    timedOut?: boolean;
+};
+export type RpcCommandType = RpcCommand["type"];
+/**
+ * Lifecycle stages that emit machine-addressable gates. v1 is single-agent;
+ * `team` parallel execution over RPC is deferred, so it is intentionally absent
+ * from this union. Gate construction rejects any other stage value.
+ */
+export type RpcWorkflowStage = "deep-interview" | "ralplan" | "ultragoal";
+/** Reserved stage names that are explicitly not part of the v1 contract. */
+export declare const RESERVED_WORKFLOW_STAGES: readonly string[];
+export type RpcWorkflowGateKind = "question" | "approval" | "execution";
+/**
+ * The documented JSON Schema 2020-12 subset supported by the gate validator.
+ * Schemas containing any keyword outside this shape are rejected at gate
+ * construction time so the server never advertises a schema it cannot validate.
+ */
+export interface RpcJsonSchema {
+    type?: "string" | "number" | "integer" | "boolean" | "object" | "array" | "null";
+    enum?: unknown[];
+    const?: unknown;
+    properties?: Record<string, RpcJsonSchema>;
+    required?: string[];
+    additionalProperties?: boolean | RpcJsonSchema;
+    items?: RpcJsonSchema;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+    minimum?: number;
+    maximum?: number;
+    title?: string;
+    description?: string;
+    oneOf?: RpcJsonSchema[];
+    anyOf?: RpcJsonSchema[];
+}
+export interface RpcWorkflowGateOption {
+    value: unknown;
+    label: string;
+    description?: string;
+}
+export interface RpcWorkflowGateContext {
+    title?: string;
+    plan?: string;
+    source?: string;
+    prompt?: string;
+    summary?: string;
+    stage_state?: Record<string, unknown>;
+    artifact_refs?: Array<{
+        kind: string;
+        path?: string;
+        sha256?: string;
+    }>;
+    language?: string;
+}
+/** Outbound event: a machine-addressable workflow gate awaiting an answer. */
+export interface RpcWorkflowGate {
+    type: "workflow_gate";
+    /** Run-scoped, monotonic, stable id (e.g. `wg_<run>_<stage>_000001`). */
+    gate_id: string;
+    stage: RpcWorkflowStage;
+    kind: RpcWorkflowGateKind;
+    schema: RpcJsonSchema;
+    /** Canonical hash of `schema`; advertised hash must equal server validation hash. */
+    schema_hash: string;
+    options?: RpcWorkflowGateOption[];
+    context: RpcWorkflowGateContext;
+    created_at: string;
+    required: true;
+}
+/** Inbound: the agent's answer to a workflow gate. */
+export interface RpcWorkflowGateResponse {
+    gate_id: string;
+    answer: unknown;
+    /** Optional idempotency key; same key + body returns the cached resolution. */
+    idempotency_key?: string;
+}
+/** Outcome of resolving a gate, surfaced back to the answering client. */
+export interface RpcWorkflowGateResolution {
+    gate_id: string;
+    status: "accepted" | "rejected";
+    answer_hash: string;
+    resolved_at: string;
+    /** Present only when `status === "rejected"`. */
+    error?: RpcWorkflowGateValidationError;
+}
+/** Typed error shape for schema validation failures (#315 acceptance). */
+export interface RpcWorkflowGateValidationError {
+    code: "invalid_workflow_gate_answer";
+    gate_id: string;
+    schema_hash: string;
+    errors: Array<{
+        path: string;
+        keyword: string;
+        message: string;
+        expected?: unknown;
+    }>;
+}
+export interface RpcUnattendedBudget {
+    max_tokens: number;
+    max_tool_calls: number;
+    max_wall_time_ms: number;
+    max_cost_usd: number;
+}
+export interface RpcUnattendedDeclaration {
+    /** Identity of the operating external agent, recorded in the audit trail. */
+    actor: string;
+    budget: RpcUnattendedBudget;
+    /** Coarse command scopes the agent may use (maps to BridgeCommandScope). */
+    scopes: string[];
+    /** Action classes the agent is allowed to perform (default-deny otherwise). */
+    action_allowlist: string[];
+}
+export interface RpcUnattendedAccepted {
+    run_id: string;
+    actor: string;
+    budget: RpcUnattendedBudget;
+    scopes: string[];
+    action_allowlist: string[];
+    accepted_at: string;
+}
+export type RpcBudgetMetric = "tokens" | "tool_calls" | "wall_time" | "cost";
+/** Typed payload emitted when a declared budget cap is breached (#318). */
+export interface RpcBudgetExceeded {
+    code: "budget_exceeded";
+    metric: RpcBudgetMetric;
+    limit: number;
+    observed: number;
+    /** The accounting phase that detected the breach. */
+    phase: string;
+    run_id: string;
+    session_id?: string;
+    /** `aborting` = breach detected, async abort initiated; settled status follows in audit. */
+    abort_status: "aborting" | "aborted" | "abort_failed";
+}
+export type RpcUnattendedRefusalCode = "unattended_not_negotiated" | "incomplete_budget" | "unsupported_budget_metric" | "invalid_unattended_declaration" | "unattended_aborted";
+/** Typed refusal emitted when unattended mode cannot start or continue (fail-closed). */
+export interface RpcUnattendedRefused {
+    code: RpcUnattendedRefusalCode;
+    message: string;
+}
+/** v1 action taxonomy: every authorized operation maps to one of these classes. */
+export type RpcUnattendedActionClass = "command.prompt" | "command.control" | "command.bash" | "command.export" | "command.session" | "command.model" | "command.message_read" | "command.host_tools" | "command.host_uri" | "command.admin" | "bash.readonly" | "bash.mutating" | "bash.destructive" | "git.force_push" | "file.delete" | "file.write" | "host_tool.invoke" | "host_uri.read" | "host_uri.write" | "auth.login";
+/** Typed error when a command's coarse scope is not in the declared allowlist. */
+export interface RpcScopeDenied {
+    code: "scope_denied";
+    scope: string;
+    command?: string;
+    run_id: string;
+    session_id?: string;
+    /** Always true: enforcement happens before the side effect runs. */
+    pre_side_effect: true;
+}
+/** Typed error when an action class is not in the declared allowlist (default-deny). */
+export interface RpcActionDenied {
+    code: "action_denied";
+    action: string;
+    command?: string;
+    run_id: string;
+    session_id?: string;
+    pre_side_effect: true;
+}