@sayknow-cli/coding-agent 0.4.2 → 0.4.4

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

@@ -0,0 +1,299 @@
+/**
+ * RPC Client for programmatic access to the coding agent.
+ *
+ * Spawns the agent in RPC mode and provides a typed API for all operations.
+ */
+import { type AgentEvent, type AgentMessage, type AgentToolResult, type ResolvedThinkingLevel, ThinkingLevel } from "@sayknow-cli/agent-core";
+import type { CompactionResult } from "@sayknow-cli/agent-core/compaction";
+import type { ImageContent, Model } from "@sayknow-cli/ai";
+import type { BashResult } from "../../exec/bash-executor";
+import type { AgentSessionEvent, SessionStats } from "../../session/agent-session";
+import type { RpcExtensionUIRequest, RpcGetStateInclude, RpcHandoffResult, RpcHostToolDefinition, RpcSessionState, RpcUnattendedAccepted, RpcUnattendedDeclaration, RpcWorkflowGate, RpcWorkflowGateResolution } from "./rpc-types";
+export interface RpcClientOptions {
+    /** Dial an existing Unix-domain socket instead of spawning a stdio child. */
+    socketPath?: string;
+    /** Explicit transport selector; defaults to uds when socketPath is set, otherwise stdio. */
+    transport?: "stdio" | "uds";
+    /** Observe transport close/error state. */
+    onTransportClose?: (error?: Error) => void;
+    /** Alias for transport close/error observation. */
+    onTransportError?: (error: Error) => void;
+    /** Path to the CLI entry point (default: searches for dist/cli.js) */
+    cliPath?: string;
+    /** Working directory for the agent */
+    cwd?: string;
+    /** Environment variables */
+    env?: Record<string, string>;
+    /** Provider to use */
+    provider?: string;
+    /** Model ID to use */
+    model?: string;
+    /** Session directory for the agent */
+    sessionDir?: string;
+    /** Additional CLI arguments */
+    args?: string[];
+    /** Custom tools owned by the embedding host and exposed over the RPC transport */
+    customTools?: RpcClientCustomTool[];
+}
+export type ModelInfo = Pick<Model, "provider" | "id" | "contextWindow" | "reasoning" | "thinking">;
+export type RpcDefaultModelSelection = {
+    readonly provider: string;
+    readonly modelId: string;
+    readonly thinkingLevel: ResolvedThinkingLevel;
+};
+export type RpcEventListener = (event: AgentEvent) => void;
+export type RpcSessionEventListener = (event: AgentSessionEvent) => void;
+export interface RpcClientToolContext<TDetails = unknown> {
+    toolCallId: string;
+    signal: AbortSignal;
+    sendUpdate(partialResult: RpcClientToolResult<TDetails>): void;
+}
+export type RpcClientToolResult<TDetails = unknown> = AgentToolResult<TDetails> | string;
+export interface RpcClientCustomTool<TParams extends Record<string, unknown> = Record<string, unknown>, TDetails = unknown> extends Omit<RpcHostToolDefinition, "parameters"> {
+    parameters: Record<string, unknown>;
+    execute(params: TParams, context: RpcClientToolContext<TDetails>): Promise<RpcClientToolResult<TDetails>> | RpcClientToolResult<TDetails>;
+}
+export declare function defineRpcClientTool<TParams extends Record<string, unknown> = Record<string, unknown>, TDetails = unknown>(tool: RpcClientCustomTool<TParams, TDetails>): RpcClientCustomTool<TParams, TDetails>;
+export interface RpcTransport {
+    readonly kind: "stdio" | "uds";
+    start(onFrame: (frame: unknown) => void, onClose: (error?: Error) => void): Promise<void>;
+    write(frame: unknown): void;
+    stop(): void;
+    getStderr(): string;
+}
+export declare class RpcClient {
+    #private;
+    private options;
+    constructor(options?: RpcClientOptions);
+    /**
+     * Start the RPC agent process.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the RPC agent process.
+     */
+    stop(): void;
+    /**
+     * Stop the RPC agent process and clean up resources.
+     */
+    [Symbol.dispose](): void;
+    /**
+     * Subscribe to the legacy core AgentEvent subset.
+     */
+    onEvent(listener: RpcEventListener): () => void;
+    /**
+     * Subscribe to all renderer-facing agent session events.
+     */
+    onSessionEvent(listener: RpcSessionEventListener): () => void;
+    /**
+     * Subscribe to workflow lifecycle gates emitted by RPC mode.
+     */
+    onWorkflowGate(listener: (gate: RpcWorkflowGate) => void): () => void;
+    /**
+     * Answer a workflow lifecycle gate and wait for the server resolution envelope.
+     */
+    respondGate(gateId: string, answer: unknown, idempotencyKey?: string): Promise<RpcWorkflowGateResolution>;
+    /**
+     * Subscribe to extension UI requests emitted by the server (e.g. select /
+     * input / editor / confirm). Returns an unsubscribe function.
+     */
+    onExtensionUiRequest(listener: (req: RpcExtensionUIRequest) => void): () => void;
+    /** Respond to an extension UI request over the live transport. */
+    respondExtensionUi(response: import("./rpc-types").RpcExtensionUIResponse): void;
+    /** Observe transport close/error notifications. */
+    onTransportError(listener: (error: Error) => void): () => void;
+    /**
+     * Enter unattended mode by declaring budget + scopes + action allowlist.
+     * Returns the accepted declaration, or rejects (fail-closed) on refusal.
+     */
+    negotiateUnattended(declaration: RpcUnattendedDeclaration): Promise<RpcUnattendedAccepted>;
+    /**
+     * Get collected stderr output (useful for debugging).
+     */
+    getStderr(): string;
+    /**
+     * Send a prompt to the agent.
+     * Returns immediately after sending; use onEvent() to receive streaming events.
+     * Use waitForIdle() to wait for completion.
+     */
+    prompt(message: string, images?: ImageContent[]): Promise<void>;
+    /**
+     * Queue a steering message to interrupt the agent mid-run.
+     */
+    steer(message: string, images?: ImageContent[]): Promise<void>;
+    /**
+     * Queue a follow-up message to be processed after the agent finishes.
+     */
+    followUp(message: string, images?: ImageContent[]): Promise<void>;
+    /**
+     * Abort current operation.
+     */
+    abort(): Promise<void>;
+    /**
+     * Abort current operation and immediately start a new turn with the given message.
+     */
+    abortAndPrompt(message: string, images?: ImageContent[]): Promise<void>;
+    /**
+     * Start a new session, optionally with parent tracking.
+     * @param parentSession - Optional parent session path for lineage tracking
+     * @returns Object with `cancelled: true` if an extension cancelled the new session
+     */
+    newSession(parentSession?: string): Promise<{
+        cancelled: boolean;
+    }>;
+    /**
+     * Get current session state.
+     */
+    getState(include?: RpcGetStateInclude[]): Promise<RpcSessionState>;
+    /** Return unresolved workflow gates persisted by the RPC session. */
+    getPendingWorkflowGates(): Promise<RpcWorkflowGate[]>;
+    /**
+     * Set model by provider and ID.
+     */
+    setModel(provider: string, modelId: string): Promise<{
+        provider: string;
+        id: string;
+    }>;
+    setDefaultModelSelection(provider: string, modelId: string, thinkingLevel: ResolvedThinkingLevel): Promise<RpcDefaultModelSelection>;
+    /**
+     * Cycle to next model.
+     */
+    cycleModel(): Promise<{
+        model: {
+            provider: string;
+            id: string;
+        };
+        thinkingLevel: ThinkingLevel | undefined;
+        isScoped: boolean;
+    } | null>;
+    /**
+     * Get list of available models.
+     */
+    getAvailableModels(): Promise<ModelInfo[]>;
+    /**
+     * Set thinking level.
+     */
+    setThinkingLevel(level: ThinkingLevel): Promise<void>;
+    /**
+     * Cycle thinking level.
+     */
+    cycleThinkingLevel(): Promise<{
+        level: ThinkingLevel;
+    } | null>;
+    /**
+     * Set steering mode.
+     */
+    setSteeringMode(mode: "all" | "one-at-a-time"): Promise<void>;
+    /**
+     * Set follow-up mode.
+     */
+    setFollowUpMode(mode: "all" | "one-at-a-time"): Promise<void>;
+    /**
+     * Compact session context.
+     */
+    compact(customInstructions?: string): Promise<CompactionResult>;
+    /**
+     * Set auto-compaction enabled/disabled.
+     */
+    setAutoCompaction(enabled: boolean): Promise<void>;
+    /**
+     * Set auto-retry enabled/disabled.
+     */
+    setAutoRetry(enabled: boolean): Promise<void>;
+    /**
+     * Abort in-progress retry.
+     */
+    abortRetry(): Promise<void>;
+    /**
+     * Execute a bash command.
+     */
+    bash(command: string): Promise<BashResult>;
+    /**
+     * Abort running bash command.
+     */
+    abortBash(): Promise<void>;
+    /**
+     * Get session statistics.
+     */
+    getSessionStats(): Promise<SessionStats>;
+    /**
+     * Hand off session context to a new session.
+     */
+    handoff(customInstructions?: string): Promise<RpcHandoffResult | null>;
+    /**
+     * Export session to HTML.
+     */
+    exportHtml(outputPath?: string): Promise<{
+        path: string;
+    }>;
+    /**
+     * Switch to a different session file.
+     * @returns Object with `cancelled: true` if an extension cancelled the switch
+     */
+    switchSession(sessionPath: string): Promise<{
+        cancelled: boolean;
+    }>;
+    /**
+     * Branch from a specific message.
+     * @returns Object with `text` (the message text) and `cancelled` (if extension cancelled)
+     */
+    branch(entryId: string): Promise<{
+        text: string;
+        cancelled: boolean;
+    }>;
+    /**
+     * Get messages available for branching.
+     */
+    getBranchMessages(): Promise<Array<{
+        entryId: string;
+        text: string;
+    }>>;
+    /**
+     * Get text of last assistant message.
+     */
+    getLastAssistantText(): Promise<string | null>;
+    /**
+     * Get all messages in the session.
+     */
+    getMessages(): Promise<AgentMessage[]>;
+    /**
+     * Get list of OAuth providers available for login, with their current authentication status.
+     */
+    getLoginProviders(): Promise<Array<{
+        id: string;
+        name: string;
+        available: boolean;
+        authenticated: boolean;
+    }>>;
+    /**
+     * Trigger OAuth login for the given provider.
+     * The server will emit an `open_url` extension_ui_request for the auth URL.
+     * Resolves when login completes or rejects on failure.
+     *
+     * @param onOpenUrl Called when the server emits the auth URL. The host must open
+     *   it in a browser for the callback-server OAuth flow to complete.
+     */
+    login(providerId: string, options?: {
+        onOpenUrl?: (url: string, instructions?: string) => void;
+    }): Promise<{
+        providerId: string;
+    }>;
+    /**
+     * Replace the host-owned custom tools exposed to the RPC session.
+     * Changes take effect before the next model call.
+     */
+    setCustomTools(tools: RpcClientCustomTool[]): Promise<string[]>;
+    /**
+     * Wait for agent to become idle (no streaming).
+     * Resolves when agent_end event is received.
+     */
+    waitForIdle(timeout?: number): Promise<void>;
+    /**
+     * Collect events until agent becomes idle.
+     */
+    collectEvents(timeout?: number): Promise<AgentEvent[]>;
+    /**
+     * Send prompt and wait for completion, returning all events.
+     */
+    promptAndWait(message: string, images?: ImageContent[], timeout?: number): Promise<AgentEvent[]>;
+}

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

@@ -0,0 +1,86 @@
+/**
+ * RPC mode: Headless operation with JSON stdin/stdout protocol.
+ *
+ * Used for embedding the agent in other applications.
+ * Receives commands as JSON on stdin, outputs events and responses as JSON on stdout.
+ *
+ * Protocol:
+ * - Commands: JSON objects with `type` field, optional `id` for correlation
+ * - Responses: JSON objects with `type: "response"`, `command`, `success`, and optional `data`/`error`
+ * - Events: AgentSessionEvent objects streamed as they occur
+ * - Extension UI: Extension UI requests are emitted, client responds with extension_ui_response
+ */
+import type { ExtensionUIContext, ExtensionUIDialogOptions } from "../../extensibility/extensions";
+import type { AgentSession } from "../../session/agent-session";
+import type { RpcCommand, RpcExtensionUIRequest, RpcExtensionUIResponse, RpcHostToolCallRequest, RpcHostToolCancelRequest, RpcHostUriCancelRequest, RpcHostUriRequest, RpcResponse } from "./rpc-types";
+export type * from "./rpc-types";
+export type PendingExtensionRequest = {
+    resolve: (response: RpcExtensionUIResponse) => void;
+    reject: (error: Error) => void;
+};
+type RpcOutput = (obj: RpcResponse | RpcExtensionUIRequest | RpcHostToolCallRequest | RpcHostToolCancelRequest | RpcHostUriRequest | RpcHostUriCancelRequest | object) => Promise<void>;
+export declare function shouldEmitRpcTitlesForTest(): boolean;
+/**
+ * Cancellation commands bypass the ordered serial chain because they must
+ * interrupt in-flight work — they cannot wait behind the very command they are
+ * meant to abort.
+ */
+export declare const RPC_CANCELLATION_COMMANDS: ReadonlySet<RpcCommand["type"]>;
+/**
+ * Safe read-only commands that bypass the ordered serial chain so they never
+ * head-of-line-block behind a long-running ordered command like
+ * `bash`/`compact`/`handoff`/`login` (#606, issue 13 — the partial fix only
+ * fast-laned cancellation).
+ *
+ * Every command listed here has a dispatch handler that is **fully synchronous
+ * and side-effect-free**: on the single-threaded event loop it runs to
+ * completion between the await points of any in-flight ordered command, reading
+ * live state without mutating it. Because such a read performs no causal write,
+ * jumping ahead of an earlier *queued* ordered command is observably harmless —
+ * there is no state change to reorder. Read payloads are additionally
+ * snapshotted inside the handler (e.g. `get_messages` returns a shallow copy of
+ * `session.messages`) so a fast-lane read can never serialize a half-mutated
+ * array that an ordered turn/compaction is rewriting in place.
+ *
+ * Deliberately excluded (kept ordered): every async/long command and every
+ * mutating command. In particular the control-flag setters (`set_thinking_level`,
+ * `cycle_thinking_level`, `set_steering_mode`, `set_follow_up_mode`,
+ * `set_interrupt_mode`, `set_auto_compaction`, `set_auto_retry`) stay ordered.
+ * Their handlers are synchronous, so fast-laning one ahead of an already-queued
+ * `prompt`/`bash` would apply the new mode *before* that earlier command runs —
+ * the earlier command would then observe the later setter's value, a
+ * causal-order (arrival-order) regression. Mutations therefore stay on the
+ * chain, and new command types default to ordered (fail-safe).
+ */
+export declare const RPC_SAFE_READ_CONTROL_COMMANDS: ReadonlySet<RpcCommand["type"]>;
+/** True when a command may bypass the ordered serial chain and run immediately. */
+export declare function isFastLaneRpcCommand(type: RpcCommand["type"]): boolean;
+/**
+ * Schedules inbound RPC commands: fast-lane commands run immediately while
+ * everything else runs through a serial chain so causal order is preserved. The
+ * read loop never blocks, which is what lets a fast-lane command reach a
+ * long-running ordered command instead of being head-of-line-blocked behind it.
+ */
+export declare function createRpcCommandScheduler(run: (command: RpcCommand) => Promise<void>, track: (task: Promise<void>) => void): {
+    dispatch: (command: RpcCommand) => void;
+    close: () => void;
+};
+export { RpcListenRefusedError } from "./rpc-socket-security";
+/**
+ * Probe whether a unix-domain socket path has a live server accepting
+ * connections. Returns `true` when a connection succeeds (a previous owner is
+ * still alive), and returns `false` only for known missing/stale endpoints
+ * (ENOENT / ECONNREFUSED). Unexpected probe failures fail closed as "alive" so
+ * `--listen` startup refuses to unlink a path it could not safely classify.
+ */
+export declare function isUnixSocketAlive(socketPath: string): Promise<boolean>;
+export declare function requestRpcEditor(pendingRequests: Map<string, PendingExtensionRequest>, output: RpcOutput, title: string, prefill?: string, dialogOptions?: ExtensionUIDialogOptions, editorOptions?: {
+    promptStyle?: boolean;
+}): Promise<string | undefined>;
+/**
+ * Run in RPC mode.
+ * Listens for JSON commands on stdin, outputs events and responses on stdout.
+ */
+export declare function runRpcMode(session: AgentSession, setToolUIContext?: (uiContext: ExtensionUIContext, hasUI: boolean) => void, options?: {
+    listen?: string;
+}): Promise<never>;

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

@@ -0,0 +1,10 @@
+export declare class RpcSocketSecurityError extends Error {
+    constructor(message: string);
+}
+export declare class RpcListenRefusedError extends Error {
+    constructor(socketPath: string);
+}
+export declare function prepareRpcSocketPath(socketPath: string): Promise<void>;
+export declare function assertSafeClientSocket(socketPath: string): Promise<void>;
+export declare function verifyRpcSocketAfterListen(socketPath: string): Promise<void>;
+export declare function probeUnixSocketAlive(socketPath: string): Promise<boolean>;