@myagentroam/node 0.1.0

package/dist/connector.d.ts

@@ -0,0 +1,343 @@
+import { type NodeCapabilities } from '@myagentroam/protocol';
+import { type NodeConfig } from './config.js';
+import { FakeRunner, type FakeRunnerStep } from './fake-runner.js';
+import { CodexAppServerClient } from './codex-app-server.js';
+import { ClaudeAgentSdkAdapter } from './claude-agent-sdk.js';
+import { NodeDatabase } from './database.js';
+import { TerminalManager } from './terminal.js';
+import { RunnerUsageReader } from './runner-usage.js';
+export declare function nextReconnectDelay(attempt: number): number;
+export interface NodeConnectorOptions {
+    readonly configPath?: string;
+    readonly config?: NodeConfig;
+    readonly capabilities?: NodeCapabilities;
+    readonly reconnect?: boolean;
+    /** Test injection only; production capability reporting remains unchanged. */
+    readonly fakeRunner?: FakeRunner;
+    readonly fakeScript?: (input: unknown, runId: string) => readonly FakeRunnerStep[];
+    readonly codexClient?: CodexAppServerClient;
+    /** Test injection only; the default uses the official Claude Agent SDK. */
+    readonly claudeClient?: ClaudeAgentSdkAdapter;
+    /** Test injection; production opens the SQLite path from NodeConfig. */
+    readonly database?: NodeDatabase;
+    /** Test-only override. Production approvals always have a ten-minute expiry. */
+    readonly claudeApprovalTimeoutMs?: number;
+    /** Test injection; production uses node-pty/ConPTY through TerminalManager. */
+    readonly terminalManager?: TerminalManager;
+    /** Test injection; production reads OAuth credentials only on the local Node. */
+    readonly runnerUsageReader?: RunnerUsageReader;
+}
+export declare class NodeConnector {
+    private socket;
+    private terminalSocket;
+    private heartbeat;
+    private reconnectTimer;
+    private terminalReconnectTimer;
+    private attempts;
+    private stopped;
+    private config;
+    private readonly capabilities;
+    private readonly configPath;
+    private readonly reconnect;
+    private readonly claudeApprovalTimeoutMs;
+    private readonly eventBuffer;
+    /** A global sequence lets one Admin page merge every business callback. */
+    private workbenchEventSequence;
+    /** Bounded process-local history used only to bridge a browser reconnect. */
+    private readonly workbenchEvents;
+    private readonly fakeRunner;
+    private readonly fakeScript;
+    private readonly runSequences;
+    /** Coalesce token-sized assistant deltas before persisting and relaying them. */
+    private readonly pendingTextDeltas;
+    private readonly activeRuns;
+    private readonly interruptRequestedRuns;
+    /** Pending turn inputs are memory-only, as are the queue records themselves. */
+    private readonly queuedRunStarts;
+    /** Bootstrap IDs never cross HTTP or Workbench event boundaries. */
+    private readonly bootstrapSessionIds;
+    private readonly nativeSessionIdentityWaiters;
+    private readonly nativeSessionStarts;
+    /** One background Claude control probe per native session; never persisted. */
+    private readonly pendingClaudeContextReads;
+    /** A completed probe is kept briefly so the next polling request can render it. */
+    private readonly completedClaudeContextReads;
+    /** Session-scoped second-stop windows; sessions in one Workspace are independent. */
+    private readonly queuePauseWindows;
+    /** Ephemeral Codex localImage files; never persisted with a Session or Workspace. */
+    private readonly runAttachmentDirectories;
+    private readonly codexClient;
+    private readonly codexRuns;
+    /** App Server turn ID → current-process managed Run; never persisted. */
+    private readonly managedCodexTurns;
+    private readonly codexApprovals;
+    private readonly codexUserInputs;
+    private readonly claudeClient;
+    private readonly claudeRuns;
+    /** Native IDs currently associated with a process-local managed Claude session. */
+    private readonly managedClaudeSessions;
+    /** Native IDs observed from an SDK-resumed Claude stream, kept process-local. */
+    private readonly managedClaudeSessionByNativeId;
+    /** Read-only native discovery cache; never persisted to SQLite. */
+    private readonly directNativeSessions;
+    /** Official Codex thread status, refreshed only in process and never persisted. */
+    private readonly codexExternalActivity;
+    /** Browser-renewed read-only native-session watches; never persisted. */
+    private readonly sessionWatches;
+    /** Maps a direct external projection to its process-local resumed session for message retries. */
+    private readonly resumedSessionByDirectId;
+    /** Last rejected explicit takeover reason for an external direct projection. */
+    private readonly externalResumeFailures;
+    /** Bounded Runner diagnostic paired with a fixed external resume reason code. */
+    private readonly externalResumeFailureDetails;
+    private readonly claudeApprovals;
+    private readonly commandStates;
+    private readonly runnerUsageReader;
+    private codexFastEnabled;
+    private readonly terminalManager;
+    private readonly terminalAttachments;
+    /** Uploads are process-local like runs; Node restart intentionally cancels them. */
+    private readonly workspaceUploads;
+    /** Completed Composer files are process-local references, never SQLite state. */
+    private readonly composerAttachments;
+    /** Identical refreshes share one Git scan; separate Workspaces use bounded parallelism. */
+    private readonly workspaceChangesReads;
+    private readonly workspaceChangesLimiter;
+    private database;
+    /** Runtime/session state is intentionally not persisted to Node SQLite. */
+    private readonly runtime;
+    private readonly metrics;
+    constructor(options?: NodeConnectorOptions);
+    start(): Promise<void>;
+    stop(): void;
+    private connect;
+    private scheduleReconnect;
+    /**
+     * Terminal bytes never share the control socket.  This connection has a
+     * deliberately tiny local envelope and can only authenticate, bind an
+     * attachment already authorized on the control channel, or carry terminal
+     * frames for that binding.
+     */
+    private connectTerminal;
+    private scheduleTerminalReconnect;
+    private handleTerminalMessage;
+    private publishTerminalFrame;
+    private sendTerminalFrame;
+    private sendTerminal;
+    private handleMessage;
+    private connected;
+    /** Executes only the closed Admin-facing operation set forwarded by Server. */
+    private handleNodeRequest;
+    private executeNodeOperation;
+    private requireWorkspace;
+    private fileAccessOptions;
+    private listFilesForWorkspace;
+    private readFileForWorkspace;
+    private searchFilesForWorkspace;
+    private preflightWorkspaceUploads;
+    private createWorkspaceUpload;
+    private writeWorkspaceUploadChunk;
+    private workspaceUploadStatus;
+    private completeWorkspaceUpload;
+    private cancelWorkspaceUpload;
+    private requireWorkspaceUpload;
+    private removeWorkspaceUpload;
+    private composerAttachmentTarget;
+    private resolveComposerAttachments;
+    private currentChangesForWorkspace;
+    private persistTerminalSession;
+    /**
+     * Discovers only the Codex sources that App Server itself identifies as CLI
+     * or VS Code. Discovery reads native history but never copies it into MAR's
+     * message table and never grants write control.
+     */
+    private discoverCodexSessions;
+    private directClaudeSessions;
+    private listDirectNativeSessions;
+    private resolveDirectNativeSession;
+    /**
+     * A rename is Node-local metadata, so an external transcript receives a
+     * process-local projection without resuming or taking control of its Runner.
+     */
+    private createMetadataProjection;
+    /**
+     * Native Runner history does not reliably expose the Composer settings that
+     * should govern MAR's next Turn.  A resumed projection therefore keeps an
+     * already-valid local choice, otherwise takes this Runner's saved Node
+     * default.  Defaults never cross Runner boundaries.
+     */
+    private resumedSessionConfiguration;
+    private ensureResumedSessionConfiguration;
+    private rememberDirectNativeSessions;
+    /** Returns exact native IDs of a managed Session, including verified Claude aliases only. */
+    private nativeSessionIdsForProjection;
+    /** Clears only projections proven to represent the just-deleted native transcripts. */
+    private forgetNativeSessionProjection;
+    private readDirectNativeHistory;
+    private readConversationHistoryPage;
+    private conversationHistoryPage;
+    private readOfficialCodexConversation;
+    private managedCodexTurn;
+    private refreshCodexExternalActivity;
+    private watchNativeSession;
+    private stopNativeSessionWatch;
+    private refreshWatchedSession;
+    private performWatchedSessionRefresh;
+    /**
+     * Resumes only an externally idle Codex thread.  The final official read is
+     * intentionally adjacent to resume so an external active turn can never be
+     * raced into a MAR-controlled message.
+     */
+    private resumeExternalCodexSession;
+    /**
+     * Claude's SDK has no cross-process activity status.  A visible CLI history
+     * is therefore resumable on first message, but only after `sessionInfo`
+     * verifies the exact native ID and cwd.  The map makes retries idempotently
+     * target the same process-local managed projection.
+     */
+    private resumeExternalClaudeSession;
+    private clearExternalResumeFailure;
+    private setExternalResumeFailure;
+    private externalResumeFailure;
+    private resolveSessionForMessage;
+    private directNativeSession;
+    /** DB caches confirmed Codex names and shields a pending rename from stale discovery results. */
+    private nativeSessionRunnerTitle;
+    /** Runner-specific title persistence: Codex owns its thread name; Claude metadata is Node-local. */
+    private renameRunnerSession;
+    /**
+     * External sessions are followed from their append-only local transcript.
+     * A managed active Run is intentionally excluded: its durable projection is
+     * fed by the Runner event stream and is therefore the live authority.
+     */
+    private hasManagedActiveRun;
+    private syncExternalTranscript;
+    private startFakeRun;
+    private startCodexRun;
+    private startClaudeRun;
+    private deliverClaudeChannelMessage;
+    /**
+     * `STEERED` means that the SDK AsyncIterable consumed the message, rather
+     * than merely accepting it into a Node-side queue. Reusing a client message
+     * ID is idempotent and never writes a second input to Claude.
+     */
+    private deliverClaudeChannel;
+    private cancelCodexTurn;
+    private respondCodexUserInput;
+    /** Returns true when cancellation already made this Run terminal. */
+    private completeCancelledRun;
+    private presentSession;
+    /**
+     * Discovery always keeps the native record in the local cache so a stale
+     * direct ID remains readable, but the response must not reintroduce it in
+     * the Workbench once this process has already resumed that native session.
+     */
+    private presentDiscoveredSessions;
+    /**
+     * Claude can report a native session ID distinct from the ID used to start
+     * a verified resume.  Keep that observed ID as a process-local alias of the
+     * same managed projection, without treating a `conversation_reset` ID as
+     * an alias.
+     */
+    private rememberManagedClaudeNativeSession;
+    /**
+     * Refresh the title once this Claude Session's own turn has flushed its
+     * native transcript. `externalSessionId` originates from that managed
+     * stream, never from a title-based discovery match.
+     */
+    private syncManagedClaudeRunnerTitle;
+    /**
+     * Resolves a native discovery record only to its exact managed projection:
+     * same runner, same Workspace and same native Session ID. Claude's only
+     * exception is a Session ID observed from that managed SDK resume stream.
+     * A title is never an identity or matching input.
+     */
+    private managedSessionForNativeRecord;
+    /**
+     * A custom-title projection can be external, but must still match the same
+     * native identity so session polling neither restores the old title nor
+     * inserts a duplicate direct record.
+     */
+    private sessionProjectionForNativeRecord;
+    private isManagedProjectionForNativeRecord;
+    /**
+     * Context occupancy is an observed Runner fact. Codex persists its latest
+     * prompt/window pair in the native transcript; Claude exposes it through
+     * the official SDK control channel. Neither path estimates tokens in MAR.
+     */
+    private readSessionContextUsage;
+    private probeClaudeContextUsage;
+    /** Executes only Node-declared interactions; the browser never supplies behavior. */
+    private executeRunnerCommand;
+    /** Claude `/compact` is a native SDK command, represented as a Run but never as a user bubble. */
+    private startClaudeCompaction;
+    /** Compaction is an App Server Turn, so keep a normal Run lifecycle for the Web spinner. */
+    private startCodexCompaction;
+    private runnerProfiles;
+    private workbenchManifest;
+    private resumeDelivery;
+    private requestClaudeApproval;
+    /**
+     * An approval is an individual Runner callback. Keep its exact payload in
+     * the process-local snapshot and emit a Run event so an already open
+     * Workbench refreshes immediately instead of waiting for a page reload.
+     */
+    private publishApprovalRequest;
+    private emitRunEvent;
+    private enqueueTextDelta;
+    private flushTextDelta;
+    private emitRunEventNow;
+    /**
+     * Browser callbacks are multiplexed on one Admin Workbench connection.  The
+     * Server adds the Node identity and never interprets this business payload.
+     */
+    private emitWorkbenchEvent;
+    private workbenchPayloadSessionId;
+    private emitWorkspaceQueue;
+    /** Promote every Connector-owned Session key together with Runtime state. */
+    private promoteManagedSessionIdentity;
+    private waitForNativeSessionIdentity;
+    private rejectBootstrapSessionIdentity;
+    /**
+     * Shared replacement primitive for Ctrl+Enter and queue "execute now".
+     * The queued Run remains authoritative until the interrupted Run emits its
+     * terminal event and releases the Session lease.
+     */
+    private replaceCurrentRunWithQueued;
+    private dispatchSessionQueue;
+    /** Let the operation response leave the Node before Runner callbacks can close or flood the socket. */
+    private scheduleSessionQueueDispatch;
+    private presentWorkspaceQueue;
+    private openQueuePauseWindow;
+    private clearQueuePauseWindow;
+    private materializeCodexAttachments;
+    /**
+     * Non-image Composer files are intentionally Workspace-visible so both
+     * runners can read the exact bytes with their normal file tools.  Unlike
+     * Codex localImage files, these are not deleted on Run completion.
+     */
+    private persistNonImageAttachments;
+    private cleanupRunAttachments;
+    /** Image bytes never enter conversation history. Keep them Node-local for one hour after Run end. */
+    private readonly runImageCache;
+    private cacheRunImages;
+    private readRunImage;
+    private expireRunImageCacheAfterTtl;
+    private clearRunImageCache;
+    /**
+     * Only send a bounded, user-readable projection. Raw SDK/JSON-RPC records
+     * and hidden reasoning must never cross this boundary into the Workbench.
+     */
+    private emitConversationItem;
+    private handleCodexNotification;
+    private reconcileRuns;
+    /** A process restart cannot safely reattach a native in-flight SDK stream. */
+    private reconcilePersistedRuns;
+    private inspectWorkspace;
+    private captureRunSnapshot;
+    private send;
+    private sendEnvelope;
+}
+export declare function validatedCapabilities(value: unknown): NodeCapabilities;
+export declare function nodeConnectEndpoint(serverUrl: string): string;
+export declare function nodeTerminalConnectEndpoint(serverUrl: string): string;