@myagentroam/node 0.1.0

package/dist/database.d.ts

@@ -0,0 +1,282 @@
+import { DatabaseSync } from 'node:sqlite';
+import { type AgentRunStatus, type RunnerDefaultConfiguration, type RunnerName } from '@myagentroam/protocol';
+import type { NativeSessionHistory } from './native-session-history.js';
+export type RunRecoveryState = 'ACTIVE' | 'SUSPECT' | 'LOST';
+export type ApprovalStatus = 'PENDING' | 'APPROVED' | 'REJECTED' | 'EXPIRED';
+/** Whether a native session ID was created by this Node or merely discovered. */
+export type NativeSessionControl = 'MAR_MANAGED' | 'EXTERNAL';
+export interface NodeWorkspace {
+    readonly id: string;
+    readonly path: string;
+    readonly kind: 'DIRECTORY' | 'GIT_WORKSPACE';
+    readonly gitSummary: unknown | null;
+}
+export interface NodeAgentSession {
+    readonly id: string;
+    readonly nodeId: string;
+    readonly workspaceId: string;
+    readonly runner: RunnerName;
+    readonly externalSessionId: string | null;
+    readonly nativeControl: NativeSessionControl;
+    readonly channelToken: string | null;
+    readonly cwd: string;
+    /** Runner preferences chosen when this managed session was created. */
+    readonly model: string | null;
+    readonly effort: string | null;
+    readonly access: string | null;
+    readonly customTitle: string | null;
+    readonly runnerTitle: string | null;
+    readonly pinnedAt: number | null;
+    readonly titleSource: 'AUTO' | 'RUNNER' | 'CUSTOM';
+    readonly lastActivityAt: number;
+    readonly createdAt: number;
+}
+export interface NativeSessionMetadata {
+    readonly customTitle: string | null;
+    readonly runnerTitle: string | null;
+    readonly runnerTitlePending: boolean;
+    readonly pinnedAt: number | null;
+    readonly model: string | null;
+    readonly effort: string | null;
+    readonly access: string | null;
+}
+export interface NodeAgentRun {
+    readonly id: string;
+    readonly sessionId: string;
+    readonly nodeId: string;
+    readonly workspaceId: string;
+    readonly runner: RunnerName;
+    readonly status: AgentRunStatus;
+    readonly recoveryState: RunRecoveryState;
+    readonly version: number;
+    readonly clientMessageId: string;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+}
+export interface NodeRunEvent {
+    readonly id: number;
+    readonly runId: string;
+    readonly sequence: number;
+    readonly eventType: string;
+    readonly payload: unknown;
+    /** The authoritative lifecycle state carried by a Runner terminal event. */
+    readonly status?: AgentRunStatus;
+    readonly createdAt: number;
+}
+export interface WorkspaceActivityEvent {
+    readonly id: number;
+    readonly workspaceId: string;
+    readonly eventType: string;
+    readonly payload: unknown;
+    readonly createdAt: number;
+}
+export interface ConversationPage {
+    readonly turns: readonly NodeConversationTurn[];
+    readonly nextCursor: string | null;
+}
+export interface ConversationItemPage {
+    readonly items: readonly NodeConversationItem[];
+    readonly nextCursor: string | null;
+}
+/** Local structural projection; protocol validation remains at the boundary. */
+export interface NodeConversationItem {
+    readonly id: string;
+    readonly sessionId: string;
+    readonly turnId: string;
+    readonly runId: string | null;
+    readonly parentItemId: string | null;
+    readonly sourceSequence: number | null;
+    readonly revision: number;
+    readonly kind: string;
+    readonly status: string;
+    readonly payload: unknown;
+    readonly startedAt: number | null;
+    readonly completedAt: number | null;
+}
+export interface NodeConversationTurn {
+    readonly id: string;
+    readonly sessionId: string;
+    readonly runId: string | null;
+    readonly userItemId: string | null;
+    readonly status: string;
+    readonly model: string | null;
+    readonly effort: string | null;
+    readonly access: string | null;
+    readonly items: readonly NodeConversationItem[];
+    readonly startedAt: number | null;
+    readonly completedAt: number | null;
+}
+export interface NodeMessageAttachmentInput {
+    readonly name: string;
+    readonly mime: string;
+    readonly dataBase64: string;
+}
+export interface WorkspaceActivityPage {
+    readonly events: readonly WorkspaceActivityEvent[];
+    readonly nextCursor: string | null;
+}
+export interface NodeApproval {
+    readonly id: string;
+    readonly runId: string;
+    readonly status: ApprovalStatus;
+    readonly payload: unknown;
+    readonly expiresAt: number;
+    readonly createdAt: number;
+    readonly decidedAt: number | null;
+}
+/** Terminal output and input are deliberately never part of this projection. */
+export interface NodeTerminalSession {
+    readonly id: string;
+    readonly workspaceId: string | null;
+    readonly profileId: string;
+    readonly state: 'RUNNING' | 'EXITED' | 'CLOSED';
+    readonly exitCode: number | null;
+    readonly rows: number;
+    readonly cols: number;
+    readonly latestSequence: number;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+}
+export declare class NodeDatabase {
+    private readonly now;
+    activeWorkspaceLeaseCount(): number;
+    readonly raw: DatabaseSync;
+    constructor(path: string, nodeId: string | (() => string), now?: () => number);
+    close(): void;
+    getRunnerDefaults(): readonly RunnerDefaultConfiguration[];
+    saveRunnerDefaults(input: RunnerDefaultConfiguration): RunnerDefaultConfiguration;
+    /**
+     * Stores only terminal lifecycle metadata. PTY input/output must remain in
+     * the Node-local bounded replay buffer and must never be passed here.
+     */
+    saveTerminalSession(input: NodeTerminalSession): NodeTerminalSession;
+    getTerminalSession(id: string): NodeTerminalSession | undefined;
+    listTerminalSessions(): readonly NodeTerminalSession[];
+    /** A restart cannot safely reattach an orphaned PTY, so record it as closed. */
+    closeRunningTerminalSessions(): void;
+    saveWorkspace(input: Omit<NodeWorkspace, 'id'> & {
+        readonly id?: string;
+    }): NodeWorkspace;
+    listWorkspaces(): readonly NodeWorkspace[];
+    getWorkspace(id: string): NodeWorkspace | undefined;
+    /** Unregisters a Workspace registration without deleting its local directory. */
+    removeWorkspace(id: string): NodeWorkspace;
+    createAgentSession(input: {
+        readonly workspaceId: string;
+        readonly runner: RunnerName;
+        readonly externalSessionId?: string;
+        /** A caller-supplied native ID is always treated as an unverified external session. */
+        readonly nativeControl?: NativeSessionControl;
+        readonly cwd: string;
+        /** Runner/native history title; never treated as a user override. */
+        readonly title?: string;
+        readonly model?: string;
+        readonly effort?: string;
+        readonly access?: string;
+    }): NodeAgentSession;
+    getAgentSession(id: string): NodeAgentSession | undefined;
+    updateAgentSessionConfiguration(input: {
+        readonly sessionId: string;
+        readonly model: string;
+        readonly effort: string;
+        readonly access: string;
+    }): NodeAgentSession;
+    listAgentSessions(): readonly NodeAgentSession[];
+    findAgentSessionByExternalSession(runner: RunnerName, externalSessionId: string): NodeAgentSession | undefined;
+    setNativeControl(sessionId: string, nativeControl: NativeSessionControl): void;
+    setExternalSessionId(sessionId: string, externalSessionId: string): void;
+    setChannelToken(sessionId: string, token: string): void;
+    updateSessionMetadata(input: {
+        readonly sessionId: string;
+        readonly customTitle?: string | null;
+        readonly pinned?: boolean;
+    }): NodeAgentSession;
+    getNativeSessionMetadata(runner: RunnerName, externalSessionId: string, workspaceId: string): NativeSessionMetadata | undefined;
+    saveNativeSessionMetadata(input: {
+        readonly runner: RunnerName;
+        readonly externalSessionId: string;
+        readonly workspaceId: string;
+        readonly customTitle?: string | null;
+        readonly runnerTitle?: string | null;
+        readonly runnerTitlePending?: boolean;
+        readonly pinned?: boolean;
+        readonly model?: string | null;
+        readonly effort?: string | null;
+        readonly access?: string | null;
+    }): NativeSessionMetadata;
+    /**
+     * Replaces only transcript-derived, run-less history. Managed Run turns are
+     * never touched by a vendor file scan.
+     */
+    syncNativeTranscript(sessionId: string, history: NativeSessionHistory): boolean;
+    createMessageRun(input: {
+        readonly sessionId: string;
+        readonly clientMessageId: string;
+        readonly content: string;
+        readonly attachments?: readonly NodeMessageAttachmentInput[];
+    }): {
+        readonly run: NodeAgentRun;
+        readonly created: boolean;
+    };
+    getRun(id: string): NodeAgentRun | undefined;
+    listRunsForSession(sessionId: string): readonly NodeAgentRun[];
+    getRunInput(id: string): string | undefined;
+    transitionRun(runId: string, next: AgentRunStatus): NodeAgentRun;
+    appendRunEvent(input: {
+        readonly runId: string;
+        readonly sequence: number;
+        readonly eventType: string;
+        readonly payload: unknown;
+        readonly status?: AgentRunStatus;
+    }): NodeRunEvent | undefined;
+    listRunEvents(runId: string, after?: number): readonly NodeRunEvent[];
+    /**
+     * Returns durable final item snapshots. Run events stay internal to the
+     * replay path; callers never need to reconstruct native runner payloads.
+     */
+    listConversationTurns(input: {
+        readonly sessionId: string;
+        readonly cursor?: string;
+        readonly limit?: number;
+        /** File transcript history takes precedence when it is available and no managed Run is live. */
+        readonly nativeOnly?: boolean;
+    }): ConversationPage;
+    hasNativeTranscript(sessionId: string): boolean;
+    /** Session detail cursor is intentionally distinct from history paging. */
+    listConversationItems(input: {
+        readonly sessionId: string;
+        readonly cursor?: string;
+        readonly limit?: number;
+    }): ConversationItemPage;
+    listWorkspaceActivity(input: {
+        readonly workspaceId: string;
+        readonly cursor?: string;
+        readonly limit?: number;
+    }): WorkspaceActivityPage;
+    createApproval(input: {
+        readonly runId: string;
+        readonly approvalId: string;
+        readonly payload: unknown;
+        readonly expiresAt: number;
+    }): NodeApproval;
+    getApproval(id: string): NodeApproval | undefined;
+    listApprovals(runId: string): readonly NodeApproval[];
+    /** Persists an expiry so a later decision cannot resurrect an old prompt. */
+    expireApproval(id: string): NodeApproval;
+    expireDueApprovals(): readonly NodeApproval[];
+    decideApproval(id: string, decision: 'APPROVED' | 'REJECTED'): NodeApproval;
+    listNonterminalRuns(): readonly NodeAgentRun[];
+    lastRunSequence(runId: string): number;
+    saveSnapshot(runId: string, snapshot: unknown): void;
+    getSnapshot(runId: string): unknown | undefined;
+    markActiveRunsSuspect(): void;
+    hasActiveWorkspaceLease(workspaceId: string): boolean;
+    reconcileRun(runId: string, active: boolean): void;
+    private releaseLease;
+    private recordWorkspaceActivity;
+    private recordConversationItemChange;
+    private projectApproval;
+    private readConversationTurn;
+    private projectRunEvent;
+    private readonly nodeIdProvider;
+}