@cjhyy/code-shell-core 0.7.1 → 0.8.0

package/dist/protocol/server.d.ts

@@ -18,6 +18,16 @@ 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.
@@ -50,21 +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;
@@ -72,13 +130,24 @@ 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
@@ -88,6 +157,8 @@ export declare class AgentServer {
     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).
@@ -128,6 +199,15 @@ export declare class AgentServer {
      */
     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
@@ -157,7 +237,25 @@ export declare class AgentServer {
     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;
@@ -170,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
@@ -179,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
@@ -207,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;
@@ -242,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
@@ -262,6 +379,13 @@ export declare class AgentServer {
     /** 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