@cjhyy/code-shell-core 0.7.0 → 0.8.0

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 {};

package/dist/protocol/server.d.ts

@@ -16,7 +16,18 @@
 import type { Transport } from "./transport.js";
 import type { Engine } from "../engine/engine.js";
 import type { ValidatedSettings } from "../settings/schema.js";
+import { type ApprovalRouter } from "../tool-system/permission.js";
 import type { ChatSessionManager } from "./chat-session-manager.js";
+import type { ExtensionModule } from "../tool-system/capability-module.js";
+/**
+ * Why a host-loopback request (Panel / Browser / workspace / credential) ended
+ * without a result. These four used to collapse into one string — "declined or
+ * unavailable" — so a Stop, a closed session, and an actual user denial were
+ * indistinguishable to the calling tool and therefore to the model.
+ */
+export type HostLoopbackFailure = "denied" | "cancelled" | "session_closed" | "owner_lost" | "timed_out"
+/** The host replied, but with something that wasn't parseable JSON. */
+ | "malformed";
 export interface AgentServerOptions {
     /**
      * Multi-session manager. Required for the new multi-session protocol.
@@ -49,16 +60,69 @@ export interface AgentServerOptions {
      * mode already reads disk via the engine, and tests that don't exercise the
      * reopened-session path can omit it.
      */
-    readActiveGoalFromDisk?: (sessionId: string) => import("../engine/goal.js").GoalConfig | undefined;
+    readActiveGoalFromDisk?: (sessionId: string) => import("../goal/lifecycle.js").GoalConfig | undefined;
+    /** Disk controls for a persisted goal whose ChatSession is not live. */
+    updateActiveGoalOnDisk?: (sessionId: string, patch: {
+        objective?: string;
+        paused?: boolean;
+        expectedGoalId?: string;
+        expectedRevision?: number;
+    }) => import("../goal/lifecycle.js").GoalConfig | undefined;
+    clearActiveGoalOnDisk?: (sessionId: string, expected?: {
+        goalId?: string;
+        revision?: number;
+    }) => boolean;
     /**
      * Enable the desktop workspace bridge channel. Off by default so generic
      * protocol hosts do not emit hidden workspace approval requests they cannot
      * service.
      */
     workspaceBridge?: boolean;
+    /** Enable model-driven panel discovery/focus for interactive Desktop sessions. */
+    panelBridge?: boolean;
+    /** Stable transport connection identity. Supplying it enables strict
+     * connection+session+generation+requestId approval response matching. */
+    connectionId?: string;
+    /**
+     * Resolve the user identity this connection acts as (identity dimension
+     * foundations, Task 2). Absent → today's behavior byte-for-byte: every
+     * request routes through the single host-supplied chatManager. Present →
+     * the server resolves the identity per request and routes getOrCreate/get
+     * (and session lists/streams) through a lazily-created per-identity
+     * manager (`chatManager.forIdentity(id)`), whose sessions persist under
+     * `<dataRoot>/identities/<id>/sessions`. Returning the base manager's own
+     * identity ("local" unless the host injected one) selects the base manager
+     * unchanged. The returned identity is validated as a safe path segment;
+     * an invalid identity fails the request (fail closed).
+     */
+    resolveIdentity?: (ctx: {
+        connectionId: string;
+    }) => string;
+    /**
+     * Sessions dir for the server's lazy disk reader (background-wakeup
+     * rehydrate). Defaults to the standard sessions root; a host that relocates
+     * its data root (CODE_SHELL_DATA_ROOT worker) points this at
+     * `<dataRoot>/sessions` so cold wakeups read the same store its engines
+     * write.
+     */
+    sessionDiskRoot?: string;
+    /** Shared owner router; injectable for hosts/tests, process singleton by default. */
+    approvalRouter?: ApprovalRouter;
+    /**
+     * Extension modules whose protocol observers / run-param validators /
+     * hidden session kinds this server applies. Defaults to core's built-in
+     * pet extension so existing hosts keep the Pet projection channel.
+     * TODO(pet-out-of-core): drop the default once hosts register it explicitly.
+     */
+    extensionModules?: readonly ExtensionModule[];
 }
 export declare class AgentServer {
-    private readonly chatManager;
+    /** Host-supplied manager; requests route through the `chatManager` getter. */
+    private readonly baseChatManager;
+    /** Identity resolution hook; null → single-manager behavior (today's path). */
+    private readonly resolveIdentity;
+    /** Lazily-derived managers keyed by identity (non-base identities only). */
+    private readonly identityManagers;
     private readonly legacyEngine;
     private globalQueryEngine;
     private transport;
@@ -66,15 +130,35 @@ export declare class AgentServer {
     private readonly settingsReader;
     /** Disk-only active-goal reader for agent/goalGet on a non-live session. */
     private readonly readActiveGoalFromDisk;
+    private readonly updateActiveGoalOnDisk;
+    private readonly clearActiveGoalOnDisk;
     private readonly workspaceBridgeEnabled;
+    private readonly panelBridgeEnabled;
+    private readonly connectionId;
+    private readonly strictApprovalRouting;
+    private readonly approvalRouter;
+    private approvalConnectionUnregister;
+    private disconnected;
+    private readonly pendingApprovalTargets;
+    /** Extension modules this server consults for protocol-level hooks. */
+    private readonly extensionModules;
+    /** Protocol lifecycle observers created by extension modules (registration order). */
+    private readonly protocolObservers;
+    /** Extension-registered protocol method/query aliases (compat channel). */
+    private readonly protocolQueryHandlers;
+    /** Union of extension hiddenSessionKinds, excluded from generic session lists. */
+    private readonly hiddenSessionKinds;
     /**
      * Last per-session EngineConfigSlice supplied by agent/run. Kept even after
      * idle eviction so background-completion wakeups can rebuild the ChatSession
-     * with the same cwd/permission/trust inputs before draining the queue.
+     * with the same cwd/trust inputs before draining the queue. Per-turn
+     * permission/plan overrides deliberately do not survive into wakeup turns.
      */
     private readonly lastSliceBySession;
     /** Lazy disk reader for cold wakeup rehydrate when this process lacks a slice. */
     private diskSessionReader;
+    /** Sessions dir for diskSessionReader; undefined → default sessions root. */
+    private readonly sessionDiskRoot;
     /**
      * Monotonic config-reload version, bumped per reloadSettings request so each
      * Engine.refreshRuntimeConfig can drop out-of-order (stale) deliveries (Q5).
@@ -114,6 +198,16 @@ export declare class AgentServer {
      * itself outlives the server (it's a process-local singleton).
      */
     private bgAgentBusUnsubscribe;
+    private readonly wakeupsInFlight;
+    /**
+     * Effective session manager for the connection this server serves. Without
+     * a resolveIdentity hook this is exactly the host-supplied manager —
+     * today's single-manager behavior, byte-for-byte. With the hook, requests
+     * route through a lazily-created per-identity manager, so the same
+     * sessionId under two identities resolves to two isolated ChatSessions and
+     * a connection can only list/stream sessions of its own identity.
+     */
+    private get chatManager();
     constructor(options: AgentServerOptions);
     /**
      * Wake an IDLE chatManager session that has pending background-completion
@@ -133,23 +227,36 @@ export declare class AgentServer {
      *   the first drains all currently-pending items; subsequent bus events for
      *   the same session find it busy (or find an empty queue) and no-op.
      *
-     * INVARIANT (the burst-merge correctness depends on it): the merge only
-     * holds because (a) the bus fans out to subscribers SYNCHRONOUSLY, and (b)
-     * `enqueueTurn` sets the session's `active` (→ isBusy()===true) SYNCHRONOUSLY
-     * before its first await. So when bus events #2..N arrive — still on the same
-     * synchronous fan-out as #1 — they already see the session as busy and no-op.
-     * If either path is ever made async (e.g. an await is added inside
-     * enqueueTurn before `active` is set, or the bus starts deferring delivery),
-     * this degrades into N concurrent wakeups for N completions. Keep both
-     * synchronous, or replace this comment's assumption with an explicit
-     * "wakeup in flight" guard flag.
+     * `wakeupsInFlight` serializes the now-async rehydrate path, so a burst of
+     * completion events cannot create duplicate sessions or enqueue duplicate
+     * wakeup turns while getOrCreate waits for a closing generation to settle.
      */
     private maybeWakeIdleSession;
+    private wakeIdleSession;
     private rehydrateSessionForWake;
     private sliceForWakeRehydrate;
     private rememberSessionSlice;
     private wireInteractiveSession;
+    /** Queue a model-sent message as an ordinary user turn in another Session. */
+    private routeSessionMessage;
     private handleRequest;
+    private pluginCommandContext;
+    private handlePluginCommandsList;
+    private handlePluginCommandExpand;
+    /** Route a protocol method to its extension-registered handler, if any. */
+    private handleExtensionProtocolMethod;
+    private forEachObserver;
+    private observeSessionAttached;
+    private observeSessionStream;
+    private observeRunBoundary;
+    /** Observers may replace approval metadata (e.g. surfaceable overrides). */
+    private observeApprovalCreated;
+    private observeApprovalTransition;
+    private observeSessionClosed;
+    private observeServerClose;
+    /** Generic run-param shape checks plus each extension's domain validation. */
+    private validateRunInput;
+    private handleForkSession;
     private handleRun;
     private handleRunMulti;
     private handleRunLegacy;
@@ -161,6 +268,13 @@ export declare class AgentServer {
      * limits, or an error if no session / no active run.
      */
     private handleGoalExtend;
+    /** Reject destructive Goal controls owned by a different TCP connection. */
+    private authorizeGoalControl;
+    /** Start a fully rebuilt Goal run for an idle or goal-less in-flight session. */
+    private queueGoalResumeTurn;
+    private reconcileFailedGoalResume;
+    /** Edit or pause/resume a persisted goal without replacing its identity. */
+    private handleGoalUpdate;
     /**
      * Clear a session's persisted active goal (CC /goal clear). Routes to the
      * named session, falling back to the legacy single engine (mirrors
@@ -170,7 +284,7 @@ export declare class AgentServer {
     /**
      * Read a session's persisted active goal so the host can re-surface the goal
      * block + Cancel button on session load. A persistent goal lives only in
-     * state.activeGoal and is never replayed from the transcript, so a reloaded
+     * state.goalLifecycle and is never replayed from the transcript, so a reloaded
      * (or disk-rebuilt) session has no other way to learn it. Prefers a live
      * chatManager session, else falls through to a disk read (readActiveGoalFromDisk
      * in worker mode, or the legacy engine's disk read in single-engine mode) — the
@@ -198,7 +312,17 @@ export declare class AgentServer {
     private handleBackgroundWork;
     private handleCloseSession;
     private handleReleaseWorkspace;
+    private handleSetWorkspace;
     private handleConfigure;
+    /**
+     * Resolve the Engine that owns a session-scoped query (compact, archive_range,
+     * …). With a chatManager: materialize a persisted-but-not-live session on
+     * demand, or borrow any live engine when no sessionId is given. Sends the
+     * appropriate error response and returns null when the session is
+     * closing/closed, unknown, or no engine is available; `label` names the query
+     * in the "no engine" message. Domain-neutral — no query-specific literals.
+     */
+    private resolveEngineForSessionQuery;
     private handleQuery;
     private handleInject;
     private handleSteer;
@@ -207,6 +331,7 @@ export declare class AgentServer {
      * Ask the client to approve a tool operation (legacy single-engine path).
      */
     private requestApprovalFromClient;
+    private approvalRouteEnvelope;
     /**
      * Per-session AskUserQuestion for the chatManager path. Resolves via the
      * SESSION's pendingApprovals (the chatManager approve handler looks there,
@@ -232,6 +357,8 @@ export declare class AgentServer {
      */
     private requestCredentialInjectForSession;
     private makeWorkspaceBridge;
+    private makePanelBridge;
+    private requestPanelActionForSession;
     private requestWorkspaceSwitchForSession;
     /**
      * Ask the client to answer a question from the agent (legacy single-engine
@@ -249,6 +376,16 @@ export declare class AgentServer {
      */
     private anyEngine;
     close(): void;
+    /** Release only this transport's approval ownership. Safe on socket close
+     * even when the ChatSessionManager is shared by other TCP connections. */
+    disconnect(reason?: string): void;
+    /** Resolver-free metadata view for extension projections and protocol snapshots. */
+    getPendingDecisionSnapshot(): readonly unknown[];
+    /** Host lifecycle generation stamped onto pending-approval metadata. */
+    private workerGeneration;
+    private registerSessionApproval;
+    private takeSessionApproval;
+    private internalPendingMetadata;
     private clearApprovalTimer;
     /**
      * Resolve all of a chat session's pending approvals as cancelled and clear
@@ -258,5 +395,6 @@ export declare class AgentServer {
      * AskUserQuestion does not.
      */
     private cancelSessionApprovals;
+    private failClosedApprovalTargets;
     private clearAllApprovalTimers;
 }