@cjhyy/code-shell-core 0.7.1 → 0.8.0

package/dist/protocol/client.d.ts

@@ -11,8 +11,10 @@
  *   const result = await client.run("fix the bug");
  */
 import type { Transport } from "./transport.js";
-import { type RunParams, type RunResult, type ForkSessionParams, type ForkSessionResult, type AgentStreamEventNotification, type ConfigureParams, type QueryParams, type QueryResult, type ApprovalRequestNotification, type ApprovalResolvedNotification } from "./types.js";
-import type { ApprovalRequest, ApprovalResult, PermissionMode, BackgroundAgentCompletedEvent } from "../types.js";
+import { type RunParams, type RunResult, type ForkSessionParams, type ForkSessionResult, type AgentStreamEventNotification, type ConfigureParams, type QueryParams, type QueryResult, type PluginCommandsListResult, type PluginCommandExpandResult, type ApprovalRequestNotification, type ApprovalResolvedNotification } from "./types.js";
+import type { ApprovalRequest, ApprovalResult, PermissionMode, BackgroundAgentCompletedEvent, SessionKind } from "../types.js";
+import type { RunBehaviorMode } from "../engine/run-types.js";
+import type { GoalConfig } from "../goal/lifecycle.js";
 export type ApprovalRequestMeta = Pick<ApprovalRequestNotification, "connectionId" | "sessionId" | "generation">;
 export type ApprovalResolvedEvent = ApprovalResolvedNotification;
 export interface AgentClientEvents {
@@ -28,6 +30,8 @@ export interface AgentRunOptions {
     permissionMode?: PermissionMode;
     model?: string;
     planMode?: boolean;
+    behaviorMode?: RunBehaviorMode;
+    kind?: SessionKind;
 }
 export type BackgroundAgentCompletedHandler = (sessionId: string, event: BackgroundAgentCompletedEvent) => void;
 export declare class AgentClient {
@@ -54,7 +58,7 @@ export declare class AgentClient {
      * for multi-session servers) or the legacy string form `(task, sessionId?)`
      * for backward compatibility with createInProcessClient callers.
      */
-    run(taskOrParams: string | RunParams, sessionIdOrOptions?: string | AgentRunOptions): Promise<RunResult>;
+    run(taskOrParams: string | RunParams, sessionIdOrOptions?: string | AgentRunOptions, onTransportResponse?: () => void): Promise<RunResult>;
     /**
      * Respond to an approval request from the server.
      *
@@ -76,6 +80,20 @@ export declare class AgentClient {
      * a goal was actually cleared (false = there was none).
      */
     goalClear(sessionId?: string): Promise<boolean>;
+    /** Delete a persisted goal. Kept separate from goalClear for UI semantics. */
+    goalDelete(sessionId: string, expected: {
+        goalId: string;
+        revision: number;
+    }): Promise<boolean>;
+    /** Edit or pause/resume a goal while preserving its goalId. */
+    goalUpdate(sessionId: string, patch: {
+        objective?: string;
+        paused?: boolean;
+        expectedGoalId: string;
+        expectedRevision: number;
+    }): Promise<GoalConfig | null>;
+    /** Read the full persisted goal control state. */
+    goalGetState(sessionId: string): Promise<GoalConfig | null>;
     /**
      * Read a session's persisted active goal objective, or null when there's
      * none. The host calls this on session load to re-surface the goal block +
@@ -109,6 +127,13 @@ export declare class AgentClient {
      * Query server state.
      */
     query(type: QueryParams["type"], arg?: string | Record<string, unknown>, ...extra: unknown[]): Promise<QueryResult>;
+    /** Discover enabled installed plugin commands for one workspace. */
+    listPluginCommands(cwd: string): Promise<PluginCommandsListResult>;
+    /**
+     * Expand one plugin command inside the trusted server. The command source
+     * body and install path never cross the protocol boundary.
+     */
+    expandPluginCommand(cwd: string, name: string, rawArguments?: string): Promise<PluginCommandExpandResult>;
     /**
      * Inject context into the session transcript without triggering a LLM turn.
      * Used to make arena results, tool outputs, etc. visible to subsequent LLM calls.
@@ -139,5 +164,10 @@ export declare class AgentClient {
     private request;
     private handleResponse;
     private handleNotification;
+    /** Subscribe to an extension-owned server notification method. */
+    onExtensionNotification(method: string, handler: (params: Record<string, unknown>) => void): void;
+    offExtensionNotification(method: string, handler: (params: Record<string, unknown>) => void): void;
+    /** Issue a request to an extension-registered protocol method. */
+    requestExtension(method: string, params?: Record<string, unknown>): Promise<unknown>;
     close(): void;
 }

package/dist/protocol/client.js

@@ -10,7 +10,7 @@
  *   client.onApprovalRequest((reqId, request) => { ... });
  *   const result = await client.run("fix the bug");
  */
-import { Methods, createRequest, isResponse, isNotification, } from "./types.js";
+import { Methods, createRequest, isResponse, isNotification, ErrorCodes, } from "./types.js";
 import { EventEmitter } from "node:events";
 import { logger } from "../logging/logger.js";
 export class AgentClient {
@@ -46,7 +46,7 @@ export class AgentClient {
      * for multi-session servers) or the legacy string form `(task, sessionId?)`
      * for backward compatibility with createInProcessClient callers.
      */
-    async run(taskOrParams, sessionIdOrOptions) {
+    async run(taskOrParams, sessionIdOrOptions, onTransportResponse) {
         let params;
         if (typeof taskOrParams === "string") {
             // Form: run(task, sessionId | options?)
@@ -72,7 +72,7 @@ export class AgentClient {
         // first call of a brand-new session, when sessionId is undefined.
         if (params.sessionId)
             logger.setSid(params.sessionId);
-        const result = (await this.request(Methods.Run, params));
+        const result = (await this.request(Methods.Run, params, onTransportResponse));
         if (result.sessionId)
             logger.setSid(result.sessionId);
         return result;
@@ -120,6 +120,51 @@ export class AgentClient {
         const res = (await this.request(Methods.GoalClear, { sessionId }));
         return res?.cleared === true;
     }
+    /** Delete a persisted goal. Kept separate from goalClear for UI semantics. */
+    async goalDelete(sessionId, expected) {
+        try {
+            const res = (await this.request(Methods.GoalDelete, {
+                sessionId,
+                expectedGoalId: expected.goalId,
+                expectedRevision: expected.revision,
+            }));
+            return res?.deleted === true;
+        }
+        catch (err) {
+            // Compatibility only: old servers do not know GoalDelete and expose the
+            // unfenced GoalClear method. Never downgrade on a stale/validation error.
+            if (err.code !== ErrorCodes.MethodNotFound)
+                throw err;
+            return this.goalClear(sessionId);
+        }
+    }
+    /** Edit or pause/resume a goal while preserving its goalId. */
+    async goalUpdate(sessionId, patch) {
+        const res = (await this.request(Methods.GoalUpdate, {
+            sessionId,
+            ...patch,
+        }));
+        if (res?.updated !== true || !res.goal)
+            return null;
+        return {
+            objective: res.goal,
+            ...(res.goalId ? { goalId: res.goalId } : {}),
+            ...(res.revision ? { revision: res.revision } : {}),
+            ...(res.paused === true ? { paused: true } : {}),
+        };
+    }
+    /** Read the full persisted goal control state. */
+    async goalGetState(sessionId) {
+        const res = (await this.request(Methods.GoalGet, { sessionId }));
+        if (!res?.goal)
+            return null;
+        return {
+            objective: res.goal,
+            ...(res.goalId ? { goalId: res.goalId } : {}),
+            ...(res.revision ? { revision: res.revision } : {}),
+            ...(res.paused === true ? { paused: true } : {}),
+        };
+    }
     /**
      * Read a session's persisted active goal objective, or null when there's
      * none. The host calls this on session load to re-surface the goal block +
@@ -199,6 +244,21 @@ export class AgentClient {
         }
         return this.request(Methods.Query, params);
     }
+    /** Discover enabled installed plugin commands for one workspace. */
+    async listPluginCommands(cwd) {
+        return this.request(Methods.PluginCommandsList, { cwd });
+    }
+    /**
+     * Expand one plugin command inside the trusted server. The command source
+     * body and install path never cross the protocol boundary.
+     */
+    async expandPluginCommand(cwd, name, rawArguments = "") {
+        return this.request(Methods.PluginCommandExpand, {
+            cwd,
+            name,
+            rawArguments,
+        });
+    }
     /**
      * Inject context into the session transcript without triggering a LLM turn.
      * Used to make arena results, tool outputs, etc. visible to subsequent LLM calls.
@@ -260,10 +320,10 @@ export class AgentClient {
         this.emitter.off("stream", wrapper);
     }
     // ─── Internals ──────────────────────────────────────────────────
-    request(method, params) {
+    request(method, params, onResponse) {
         return new Promise((resolve, reject) => {
             const req = createRequest(method, params);
-            this.pendingRequests.set(req.id, { resolve, reject });
+            this.pendingRequests.set(req.id, { onResponse, resolve, reject });
             this.transport.send(req);
         });
     }
@@ -272,6 +332,19 @@ export class AgentClient {
         if (!pending)
             return;
         this.pendingRequests.delete(res.id);
+        // Emit before resolving/rejecting: Promise continuations run in a later
+        // microtask, while the transport may synchronously parse the next queued
+        // session_started notification in the same chunk.
+        if (pending.onResponse) {
+            try {
+                pending.onResponse();
+            }
+            catch (error) {
+                logger.warn("client.run_response_handler_failed", {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
         if (res.error) {
             // Attach both message and code so callers can do toMatchObject({ code }).
             const err = new Error(`[${res.error.code}] ${res.error.message}`);
@@ -327,8 +400,26 @@ export class AgentClient {
                 this.emitter.emit("status", status, message);
                 break;
             }
+            default: {
+                // Extension-owned notification methods (e.g. projection deltas pushed
+                // by a ProtocolObserver via host.notify) surface through a generic
+                // per-method channel; core knows nothing about their payloads.
+                this.emitter.emit(`notification:${notif.method}`, params);
+                break;
+            }
         }
     }
+    /** Subscribe to an extension-owned server notification method. */
+    onExtensionNotification(method, handler) {
+        this.emitter.on(`notification:${method}`, handler);
+    }
+    offExtensionNotification(method, handler) {
+        this.emitter.off(`notification:${method}`, handler);
+    }
+    /** Issue a request to an extension-registered protocol method. */
+    async requestExtension(method, params) {
+        return this.request(method, params);
+    }
     close() {
         // Reject all pending requests
         for (const [, pending] of this.pendingRequests) {

package/dist/protocol/index.d.ts

@@ -1,4 +1,4 @@
 export { AgentServer, type AgentServerOptions } from "./server.js";
 export { AgentClient } from "./client.js";
-export { createInProcessTransport, StdioTransport, type Transport, } from "./transport.js";
-export { Methods, ErrorCodes, type RpcMessage, type RunResult } from "./types.js";
+export { createInProcessTransport, StdioTransport, type Transport } from "./transport.js";
+export { Methods, ErrorCodes, type RpcMessage, type RunResult, type PluginCommandsListParams, type PluginCommandsListResult, type ProtocolPluginCommandDescriptor, type PluginCommandExpandParams, type PluginCommandExpandResult, } from "./types.js";

package/dist/protocol/index.js

@@ -1,4 +1,4 @@
 export { AgentServer } from "./server.js";
 export { AgentClient } from "./client.js";
-export { createInProcessTransport, StdioTransport, } from "./transport.js";
-export { Methods, ErrorCodes } from "./types.js";
+export { createInProcessTransport, StdioTransport } from "./transport.js";
+export { Methods, ErrorCodes, } from "./types.js";

package/dist/protocol/mobile-remote-types.d.ts

@@ -0,0 +1,406 @@
+/**
+ * Mobile remote wire-protocol DTOs (pairing / rooms / attachments / CC rooms).
+ * Moved here from @cjhyy/code-shell-server so that client packages (web) can
+ * consume the protocol contract without depending on the server implementation
+ * package — this file must stay pure types (no runtime code).
+ */
+import type { PermissionMode as CorePermissionMode } from "../types.js";
+/** Permission modes supported by the mobile remote wire protocol. */
+export type MobileRemotePermissionMode = Extract<CorePermissionMode, "default" | "acceptEdits" | "bypassPermissions">;
+type PermissionMode = MobileRemotePermissionMode;
+export interface TrustedDevice {
+    id: string;
+    name: string;
+    secretHash: string;
+    createdAt: number;
+    lastSeenAt?: number;
+    revokedAt?: number;
+}
+export interface TrustedDevicePublic {
+    id: string;
+    name: string;
+    createdAt: number;
+    lastSeenAt?: number;
+    revokedAt?: number;
+}
+export interface PairingToken {
+    value: string;
+    expiresAt: number;
+}
+/** Where a remembered permission grant applies (mirrors desktop approve). */
+export type ApprovalScope = "once" | "session" | "project";
+/** Path breadth for a remembered grant (path-scoped tools only). */
+export type ApprovalPathScope = "file" | "dir" | "tool";
+/** Mirror of core DiscoveredSession (mobile-remote can't import core). */
+export interface CcDiscoveredSession {
+    sessionId: string;
+    /** External CLI's authoritative cwd. Older hosts may omit it. */
+    cwd?: string;
+    firstMessage: string;
+    lastModified: number;
+    messageCount: number;
+}
+/** Mirror of core HistoryMessage. */
+export interface CcHistoryMessage {
+    role: "user" | "assistant";
+    text: string;
+    tools?: {
+        name: string;
+        summary: string;
+        args?: Record<string, unknown>;
+    }[];
+    ts?: number;
+}
+/** Mirror of cc-room ApprovalDecision. `answer` carries the user's
+ *  AskUserQuestion choice (string; multiSelect joins labels with ", "). */
+export type CcApprovalDecision = {
+    behavior: "allow";
+    updatedInput?: unknown;
+    answer?: string;
+} | {
+    behavior: "deny";
+    message: string;
+};
+export interface MobilePermissionModeSnapshotEntry {
+    sessionId: string;
+    mode: PermissionMode;
+}
+export interface MobileProjectMeta {
+    path: string;
+    name: string;
+    addedAt?: number;
+    pinned?: boolean;
+}
+export type MobileImageMime = "image/png" | "image/jpeg" | "image/webp" | "image/gif";
+export interface MobileImageBase {
+    clientId: string;
+    name: string;
+    mime: MobileImageMime;
+    size: number;
+}
+export type MobileImageAttachment = (MobileImageBase & {
+    transport: "inline";
+    dataUrl: string;
+}) | (MobileImageBase & {
+    transport: "upload";
+    uploadId: string;
+});
+export type MobileAttachmentSummary = MobileImageBase;
+export type MobileClientEvent = {
+    type: "auth.device";
+    deviceId: string;
+    secretHash: string;
+} | {
+    type: "pair.complete";
+    token: string;
+    name: string;
+    secretHash: string;
+} | {
+    type: "chat.send";
+    text: string;
+    sessionId?: string;
+    clientMessageId?: string;
+    attachments?: MobileImageAttachment[];
+} | {
+    type: "attachment.upload.begin";
+    clientId: string;
+    name: string;
+    mime: string;
+    size: number;
+} | {
+    type: "session.select";
+    sessionId: string;
+} | {
+    type: "session.create";
+    cwd?: string | null;
+    name?: string;
+} | {
+    type: "run.stop";
+    sessionId?: string;
+} | {
+    type: "approval.respond";
+    approvalId: string;
+    decision: "approve" | "reject";
+    sessionId?: string;
+    reason?: string;
+    answer?: string;
+    scope?: ApprovalScope;
+    pathScope?: ApprovalPathScope;
+} | {
+    type: "session.list";
+} | {
+    type: "session.history";
+    sessionId: string;
+} | {
+    type: "session.sync";
+    sessionId: string;
+    sinceSeq?: number;
+} | {
+    type: "permission.setMode";
+    sessionId?: string;
+    mode: PermissionMode;
+} | {
+    type: "model.set";
+    model: string;
+} | {
+    type: "goal.extend";
+    sessionId: string;
+    addTurns?: number;
+    addTokenBudget?: number;
+    addTimeBudgetMs?: number;
+    addStopBlocks?: number;
+} | {
+    type: "goal.clear";
+    sessionId: string;
+} | {
+    type: "room.list";
+} | {
+    type: "room.projects";
+} | {
+    type: "room.create";
+    name?: string;
+    cwd: string;
+    kind?: "claude-code" | "codex";
+    permissionMode?: "default" | "acceptEdits" | "bypassPermissions";
+} | {
+    type: "room.open";
+    roomId: string;
+} | {
+    type: "room.close";
+    roomId: string;
+} | {
+    type: "room.send";
+    roomId: string;
+    text: string;
+    clientMessageId?: string;
+    attachments?: MobileImageAttachment[];
+} | {
+    type: "room.history";
+    roomId: string;
+    sinceSeq?: number;
+} | {
+    type: "ccRoom.probe";
+    force?: boolean;
+    kind?: "claude-code" | "codex";
+} | {
+    type: "ccRoom.listSessions";
+    cwd: string;
+    kind?: "claude-code" | "codex";
+} | {
+    type: "ccRoom.openSession";
+    sessionId: string;
+    cwd: string;
+    mode: PermissionMode;
+    kind?: "claude-code" | "codex";
+} | {
+    type: "ccRoom.subscribeTranscript";
+    roomId: string;
+    sessionId: string;
+    cwd: string;
+    limit: number;
+    kind?: "claude-code" | "codex";
+} | {
+    type: "ccRoom.unsubscribeTranscript";
+    roomId: string;
+} | {
+    type: "ccRoom.readHistory";
+    cwd: string;
+    sessionId: string;
+    limit: number;
+    kind?: "claude-code" | "codex";
+} | {
+    type: "ccRoom.respondApproval";
+    roomId: string;
+    requestId: string;
+    decision: CcApprovalDecision;
+};
+export type MobileServerEvent = {
+    type: "auth.ok";
+    device: TrustedDevicePublic;
+} | {
+    type: "auth.failed";
+    message: string;
+} | {
+    type: "pair.ok";
+    device: TrustedDevicePublic;
+} | {
+    type: "pair.failed";
+    message: string;
+} | {
+    type: "chat.accepted";
+    sessionId?: string;
+    cwd?: string | null;
+    clientMessageId?: string;
+    attachments?: MobileAttachmentSummary[];
+} | {
+    type: "room.accepted";
+    roomId: string;
+    clientMessageId: string;
+} | {
+    type: "attachment.upload.ready";
+    clientId: string;
+    uploadId: string;
+    putUrl: string;
+    expiresAt: number;
+} | {
+    type: "attachment.upload.failed";
+    clientId: string;
+    message: string;
+} | {
+    type: "approval.request";
+    approvalId: string;
+    title: string;
+    risk: "low" | "medium" | "high";
+    body: string;
+} | {
+    type: "approval.resolved";
+    approvalId: string;
+    sessionId?: string;
+    approved?: boolean;
+} | {
+    type: "error";
+    message: string;
+    clientMessageId?: string;
+} | {
+    type: "session.list.ok";
+    sessions: MobileSessionMeta[];
+    activeSessionId?: string;
+} | {
+    type: "session.history.ok";
+    sessionId: string;
+    events: unknown[];
+} | {
+    type: "session.snapshot";
+    sessionId: string;
+    entries: Array<{
+        seq: number;
+        event: unknown;
+    }>;
+    nextSeq: number;
+} | {
+    type: "session.stream";
+    sessionId: string;
+    seq: number;
+    event: unknown;
+} | {
+    type: "permission.mode";
+    sessionId?: string;
+    mode: PermissionMode;
+} | {
+    type: "model.current";
+    model: string;
+    available?: string[];
+} | {
+    type: "goal.extended";
+    sessionId: string;
+    ok: boolean;
+    message?: string;
+} | {
+    type: "goal.cleared";
+    sessionId: string;
+    ok: boolean;
+    cleared?: boolean;
+    message?: string;
+} | {
+    type: "room.list.ok";
+    rooms: RoomPublic[];
+} | {
+    type: "room.projects.ok";
+    projects: MobileProjectMeta[];
+} | {
+    type: "room.opened";
+    roomId: string;
+    status: "running" | "missing" | "observing";
+} | {
+    type: "room.message";
+    roomId: string;
+    msg: unknown;
+} | {
+    type: "room.history.ok";
+    roomId: string;
+    messages: unknown[];
+    latestSeq: number;
+} | {
+    type: "room.closed";
+    roomId: string;
+} | {
+    type: "room.error";
+    roomId?: string;
+    message: string;
+    clientMessageId?: string;
+} | {
+    type: "ccRoom.approvalRequest";
+    roomId: string;
+    req: {
+        requestId: string;
+        toolName: string;
+        displayName?: string;
+        input: unknown;
+        description?: string;
+        /** AskUserQuestion only: parsed prompt + option labels for a choice card. */
+        askUser?: {
+            question: string;
+            header?: string;
+            options: string[];
+            multiSelect: boolean;
+        };
+    };
+} | {
+    type: "ccRoom.probe.ok";
+    available: boolean;
+    command?: string;
+    version?: string;
+    reason?: "not-found" | "not-executable";
+    kind: "claude-code" | "codex";
+} | {
+    type: "ccRoom.listSessions.ok";
+    cwd: string;
+    sessions: CcDiscoveredSession[];
+    kind: "claude-code" | "codex";
+} | {
+    type: "ccRoom.opened";
+    roomId: string;
+    sessionId: string;
+    status: "running" | "missing" | "observing";
+} | {
+    type: "ccRoom.transcriptSubscribed";
+    roomId: string;
+    sessionId: string;
+    active: boolean;
+    messages: CcHistoryMessage[];
+    hasMore: boolean;
+    totalCount: number;
+    roomCursor: number;
+} | {
+    type: "ccRoom.readHistory.ok";
+    sessionId: string;
+    messages: CcHistoryMessage[];
+    hasMore: boolean;
+    totalCount: number;
+} | {
+    type: "ccRoom.approvalResolved";
+    roomId: string;
+    requestId: string;
+    decision: CcApprovalDecision;
+};
+export interface RoomPublic {
+    id: string;
+    name: string;
+    cwd: string;
+    kind: "claude-code" | "codex";
+    permissionMode: "default" | "acceptEdits" | "bypassPermissions";
+    createdAt: number;
+    lastActiveAt: number;
+    open: boolean;
+    /** True when the room is bound for transcript observation and cannot send. */
+    observing: boolean;
+}
+/** A desktop session the phone can see + drive (from listDiskSessions). */
+export interface MobileSessionMeta {
+    id: string;
+    title: string;
+    cwd: string;
+    updatedAt: number;
+    origin: "desktop" | "automation";
+}
+export {};

package/dist/protocol/mobile-remote-types.js

@@ -0,0 +1 @@
+export {};