@lensagent/core 0.1.0

package/dist/store/store.d.ts

@@ -0,0 +1,344 @@
+import { type EntityRef, type Json, type Page } from '../core/domain.js';
+import type { EventBus } from '../runtime/events.js';
+import type { Sqlite } from './database.js';
+import type { EventLog } from './event-log.js';
+export type Document = Readonly<Record<string, Json>>;
+interface PageOptions {
+    readonly cursor?: string;
+    readonly limit: number;
+}
+interface AgentCreate {
+    readonly taskId: string;
+    readonly sessionId: string;
+    readonly workspaceId: string;
+    readonly parentAgentId?: string;
+    readonly name: string;
+    readonly model: string;
+    readonly modelReasoningEffort: string;
+    readonly policyPreset: string;
+    readonly capabilities: Readonly<Record<string, string>>;
+    readonly loadedCapabilities: readonly string[];
+}
+export interface IngressCommand {
+    readonly clientId: string;
+    readonly key: string;
+    readonly operation: string;
+    readonly digest: string;
+}
+export declare class Store {
+    #private;
+    constructor(database: Sqlite, events: EventBus, eventLog?: EventLog);
+    close(): Promise<void>;
+    instance(): Document;
+    stateRevision(): number;
+    ingressReplay(input: IngressCommand): Document | null;
+    recover(): readonly EntityRef[];
+    /**
+     * 02A `ProjectPageQuery.archive`: `active` hides archived Projects, `archived` shows only those,
+     * `all` shows both. The Route previously read a differently spelled parameter, so the documented
+     * one silently had no effect and archived Projects were unreachable through the API.
+     */
+    listProjects(options: PageOptions, archive?: 'active' | 'archived' | 'all'): Page<Document>;
+    defaultProject(): Document | null;
+    getProject(projectId: string): Document;
+    createProject(name: string, paths: readonly string[]): Document;
+    updateProject(projectId: string, expectedRevision: number, name: string): Document;
+    archiveProject(projectId: string, expectedRevision: number, archived: boolean): Document;
+    listWorkspaces(projectId: string): readonly Document[];
+    /**
+     * The ordered folder set a Call may reach: every Workspace in the Project, with the Call's own
+     * Workspace first.
+     *
+     * The bound Workspace leads because the first path is the primary one that relative paths resolve
+     * against, so an Agent's own folder stays the default target while the rest of the Project becomes
+     * readable. Paths are deduplicated: the same folder may appear in more than one Workspace, and a
+     * repeated root would make the Executor walk it twice.
+     */
+    projectWorkspacePaths(projectId: string, workspaceId: string): readonly string[];
+    getWorkspace(projectId: string, workspaceId: string): Document;
+    createWorkspace(projectId: string, name: string, paths: readonly string[], makeDefault: boolean): Document;
+    updateWorkspace(projectId: string, workspaceId: string, expectedRevision: number, name: string, paths: readonly string[], makeDefault: boolean): Document;
+    deleteWorkspace(projectId: string, workspaceId: string, expectedRevision: number): void;
+    listTasks(projectId: string, options: PageOptions, archived?: boolean): Page<Document>;
+    listAllTasks(projectId: string, options: PageOptions, archived?: boolean): Page<Document>;
+    getTask(projectId: string, taskId: string): Document;
+    /**
+     * A Project's Task/Session totals. `Page` carries no total, so without this a client had to walk
+     * every page to show a count.
+     */
+    projectDetail(projectId: string): Document;
+    /**
+     * 02A `TaskDetail`. The Route returned a bare `TaskSummary`, so a client reading `task.title`
+     * dereferenced `undefined` and the view crashed. Counts are derived, not stored.
+     */
+    taskDetail(projectId: string, taskId: string): Document;
+    createTask(projectId: string, title: string): Document;
+    updateTask(projectId: string, taskId: string, expectedRevision: number, title: string): Document;
+    archiveTask(projectId: string, taskId: string, expectedRevision: number, archived: boolean): Document;
+    deleteTask(projectId: string, taskId: string, expectedRevision: number): Document;
+    listSessions(projectId: string, taskId: string, options: PageOptions, archived?: boolean): Page<Document>;
+    getSession(projectId: string, sessionId: string): Document;
+    /**
+     * 02A `SessionDetail`. The Route returned a bare `SessionSummary`, so `root_agent` was absent and
+     * a client reading the active Agent's Workspace dereferenced `undefined`.
+     */
+    sessionDetail(projectId: string, sessionId: string): Document;
+    /** 02A `AgentDetail`. */
+    agentDetail(projectId: string, agentId: string): Document;
+    createSession(projectId: string, taskId: string, title: string, ingress?: IngressCommand): Document;
+    createSessionWithAgent(projectId: string, input: {
+        readonly taskId: string;
+        readonly title: string;
+        readonly workspaceId: string;
+        readonly agentName: string;
+        readonly model: string;
+        readonly modelReasoningEffort: string;
+        readonly policyPreset: string;
+        readonly capabilities: Readonly<Record<string, string>>;
+        readonly loadedCapabilities: readonly string[];
+        readonly initialPrompt?: string;
+        readonly initialMessage?: string;
+        readonly ingress: IngressCommand;
+    }): Document;
+    updateSession(projectId: string, sessionId: string, expectedRevision: number, title: string): Document;
+    archiveSession(projectId: string, sessionId: string, expectedRevision: number, archived: boolean): Document;
+    /**
+     * 02A `SessionSnapshot`, bounded to the Session's live objects per 07 §163. It answered five fields
+     * of the thirteen and named the revision `revision` instead of `state_revision`, so the Trace tab
+     * read `snapshot.steps` and the Runs tab read `snapshot.agent_sessions` off `undefined` -- both threw
+     * during render, and with one boundary around the whole workbench that blanked the window.
+     *
+     * `messages` and `context_items` are still absent. 07 §163 bounds this to non-terminal run objects
+     * and names neither, and a Session's transcript is unbounded and already paged by its own Routes;
+     * sending it on every panel poll would be the opposite of a bounded read. Returning `[]` instead
+     * would be worse than omitting them -- it would assert there are none.
+     */
+    sessionSnapshot(projectId: string, sessionId: string): Document;
+    sessionTimeline(projectId: string, sessionId: string, options: PageOptions): Page<Document>;
+    listAgents(projectId: string, field: 'task_id' | 'session_id', ownerId: string): readonly Document[];
+    getAgent(projectId: string, agentId: string): Document;
+    createAgent(projectId: string, input: AgentCreate): Document;
+    createSubagent(projectId: string, parentAgentId: string, input: {
+        readonly name: string;
+        readonly model: string;
+        readonly modelReasoningEffort: string;
+        readonly policyPreset: string;
+        readonly capabilities: Readonly<Record<string, string>>;
+        readonly loadedCapabilities: readonly string[];
+        readonly forkContext: 'full' | 'compact' | 'none';
+        readonly compactSummary?: string;
+        readonly initialPrompt?: string;
+        readonly initialMessage?: string;
+        readonly ingress?: IngressCommand;
+    }): Document;
+    updateAgent(projectId: string, agentId: string, expectedRevision: number, input: {
+        readonly name: string;
+        readonly model: string;
+        readonly modelReasoningEffort: string;
+        readonly policyPreset: string;
+    }): Document;
+    setAgentState(projectId: string, agentId: string, state: string): Document;
+    getMessage(projectId: string, messageId: string): Document;
+    enqueueMessage(projectId: string, agentId: string, content: string, sourceAgentId?: string, ingress?: IngressCommand): {
+        readonly message: Document;
+        readonly pending: Document;
+        readonly run: Document;
+    };
+    enqueueSubagentMessage(projectId: string, parentAgentId: string, targetAgentId: string, content: string, ingress: IngressCommand): Document;
+    broadcastSubagentMessage(projectId: string, parentAgentId: string, content: string, ingress: IngressCommand): Document;
+    waitForSubagent(projectId: string, sourceAgentId: string, targetAgentId: string, timeoutMs: number, signal: AbortSignal): Promise<Document>;
+    listPending(projectId: string, agentId: string, options: PageOptions): Page<Document>;
+    getPending(projectId: string, pendingId: string): Document;
+    updatePending(projectId: string, pendingId: string, expectedRevision: number, content: string): Document;
+    deletePending(projectId: string, pendingId: string, expectedRevision: number): void;
+    reorderPending(projectId: string, agentId: string, ids: readonly string[]): readonly Document[];
+    listCapabilities(projectId: string, agentId: string): readonly Document[];
+    getCapabilityAssignment(projectId: string, agentId: string, capabilityId: string): Document;
+    replaceCapabilities(projectId: string, agentId: string, capabilities: Readonly<Record<string, string>>, loadedCapabilities: readonly string[]): readonly Document[];
+    setCapabilityLoaded(projectId: string, agentId: string, capabilityId: string, loaded: boolean): readonly Document[];
+    loadCapabilities(projectId: string, agentId: string, capabilities: Readonly<Record<string, string>>): readonly Document[];
+    listRuns(projectId: string, agentId: string, options: PageOptions): Page<Document>;
+    /** 02A `RunDetail`. */
+    runDetail(projectId: string, runId: string): Document;
+    getRun(projectId: string, runId: string): Document;
+    getRunGoal(projectId: string, runId: string): Document;
+    retryAgent(projectId: string, agentId: string): Document;
+    claimRun(projectId: string, agentId: string): {
+        readonly run: Document;
+        readonly step: Document;
+        readonly pending: readonly Document[];
+    } | null;
+    consumePending(projectId: string, pendingId: string): void;
+    restorePending(projectId: string, pending: Document): Document;
+    getStep(projectId: string, stepId: string): Document;
+    listSteps(projectId: string, runId: string, options: PageOptions): Page<Document>;
+    createAttempt(projectId: string, input: {
+        readonly agentId: string;
+        readonly stepId: string | null;
+        readonly kind: 'agent' | 'compaction';
+        readonly model: string;
+        readonly profileId: string;
+        readonly profileVersion: number;
+        readonly profileDigest: string;
+        readonly configDigest: string;
+        readonly contextRevision: number;
+        readonly request: Json;
+        readonly preparation: Json;
+        readonly capabilities: readonly {
+            readonly id: string;
+            readonly schema: Json;
+        }[];
+    }): Document;
+    getAttempt(projectId: string, attemptId: string): Document;
+    listAttempts(projectId: string, field: 'agent_id' | 'step_id', ownerId: string, options: PageOptions): Page<Document>;
+    transitionAttempt(projectId: string, attemptId: string, from: string, to: string, outcome?: string | null, usage?: Json | null, errorCode?: string | null): Document;
+    recordToolOrdinal(projectId: string, attemptId: string, ordinal: number, providerToolId: string | null, complete: boolean): void;
+    createPartition(projectId: string, stepId: string, mode: 'parallel' | 'serial'): Document;
+    listPartitions(projectId: string, stepId: string, options: PageOptions): Page<Document>;
+    createCall(projectId: string, input: {
+        readonly workspaceId: string;
+        readonly agentId?: string;
+        readonly stepId?: string;
+        readonly attemptId?: string;
+        readonly partitionId?: string;
+        readonly parentCallId?: string;
+        readonly source: 'user' | 'llm' | 'program';
+        readonly capabilityId: string;
+        readonly providerCallId?: string;
+        readonly callOrdinal?: number;
+        readonly arguments: Json;
+        readonly effect: string;
+        readonly policy?: string;
+        readonly state: 'WAITING' | 'QUEUED';
+        readonly waitReason?: string;
+        readonly autoReviewPassed?: boolean;
+        readonly ingress?: IngressCommand;
+    }): Document;
+    /**
+     * The stored Call row plus its Result, as the Runtime reads it: flat, physical column names,
+     * `state` and `outcome` separate. Every scheduling and dispatch path in `src/runtime` switches on
+     * this shape, so it is deliberately not the documented wire shape -- see `callDetail` and
+     * `callSummary` for those.
+     */
+    getCall(projectId: string, callId: string): Document;
+    /** 02A `CallSummary` for one Call. */
+    callSummary(projectId: string, callId: string): Document;
+    /**
+     * 02A `CallDetail`. `concurrency` is absent rather than invented: resource claims live only in the
+     * in-process scheduler (`runtime/scheduler.ts`) and are never persisted, so the Store cannot say
+     * whether a Call was judged concurrency-safe. Reporting `{ safe: true, claims: [] }` would be a
+     * claim no code made.
+     */
+    callDetail(projectId: string, callId: string): Document;
+    listCalls(projectId: string, options: PageOptions, filters?: {
+        readonly stepId?: string;
+        readonly state?: string;
+    }): Page<Document>;
+    activeCallIds(projectId: string, agentId: string): readonly string[];
+    queuedDirectCallIds(projectId: string): readonly string[];
+    hasActiveRuntimeObjects(projectId: string): boolean;
+    decideCall(projectId: string, callId: string, decision: 'approve' | 'reject' | 'cancel', expectedRevision?: number): {
+        readonly call: Document;
+        readonly result: Document | null;
+    };
+    answerCall(projectId: string, callId: string, expectedRevision: number, answer: Json): {
+        readonly call: Document;
+        readonly result: Document | null;
+    };
+    reviewCall(projectId: string, callId: string, approved: boolean): Document;
+    startCall(projectId: string, callId: string): Document;
+    waitCall(projectId: string, callId: string, prompt: Json): Document;
+    completeCall(projectId: string, callId: string, outcome: string, content: Json, errorCode?: string | null, errorMessage?: string | null, artifacts?: readonly string[], truncated?: boolean): {
+        readonly call: Document;
+        readonly result: Document;
+    };
+    /**
+     * The stored Result plus its full Artifact rows, as `includeResult` reads it when it copies a
+     * Result into a Context. Not the wire shape -- see `resultDocument`.
+     */
+    getResult(projectId: string, resultId: string): Document;
+    /**
+     * 02A `ResultDocument`. One `content_json` column becomes `text` or `structured` according to its
+     * JSON type, which is the same split `normalizeOutput` makes when it decides what to store: a
+     * Capability producing prose stores a string, one producing records stores an object or array, and
+     * either is `null` here when the payload was too large to inline and became an Artifact instead.
+     * That is why a client reading a large Result has to fall back to `artifact_ids` and ART-01.
+     *
+     * `error_code` stays off the wire here because the documented shape does not carry it; a failed
+     * Call reports its code on `CallSummary.error_code`.
+     */
+    resultDocument(projectId: string, resultId: string): Document;
+    includeResult(projectId: string, resultId: string, agentId: string, expectedContextRevision: number): Document;
+    createArtifact(projectId: string, input: {
+        readonly name: string;
+        readonly mediaType: string;
+        readonly relativePath: string;
+        readonly sha256: string;
+        readonly sizeBytes: number;
+    }): Document;
+    getArtifact(projectId: string, artifactId: string): Document;
+    listArtifacts(projectId: string, options: PageOptions): Page<Document>;
+    /**
+     * 02A `ContextPageQuery.direction`. `backward` walks from the newest item towards the oldest,
+     * which is what a transcript needs: the first page is the latest turn, and paging loads history.
+     * `forward` walks in ordinal order for an audit view. The parameter was ignored and every caller
+     * got ordinal order, so the chat rendered its newest turn first and, past one page, would have
+     * paged away from the conversation instead of into its history.
+     */
+    listContext(projectId: string, agentId: string, options: PageOptions, direction?: 'forward' | 'backward'): Page<Document>;
+    contextSource(projectId: string, agentId: string): {
+        readonly agent: Document;
+        readonly items: readonly Document[];
+        readonly overrides: readonly Document[];
+        readonly capabilities: readonly Document[];
+    };
+    getPlan(projectId: string, agentId: string): Document | null;
+    updatePlan(projectId: string, agentId: string, items: Json): Document;
+    getContextItem(projectId: string, contextItemId: string): Document;
+    updateContextItem(projectId: string, contextItemId: string, expectedRevision: number, content: string): Document;
+    setContextVisibility(projectId: string, agentId: string, turnGroupIds: readonly string[], visible: boolean, expectedContextRevision: number): readonly Document[];
+    reorderContext(projectId: string, agentId: string, turnGroupIds: readonly string[], expectedContextRevision: number): readonly Document[];
+    listOverrides(projectId: string, agentId: string, options: PageOptions): Page<Document>;
+    getOverride(projectId: string, overrideId: string): Document;
+    createOverride(projectId: string, agentId: string, targetKind: string, targetId: string, instructions: string): Document;
+    updateOverride(projectId: string, overrideId: string, expectedRevision: number, instructions: string): Document;
+    deleteOverride(projectId: string, overrideId: string, expectedRevision: number): void;
+    listTurnGroups(projectId: string, agentId: string, options: PageOptions): Page<Document>;
+    listProjectionDecisions(projectId: string, agentId: string, options: PageOptions): Page<Document>;
+    resetProjection(projectId: string, agentId: string, expectedContextRevision: number, stages?: readonly string[]): Document;
+    appendProjectionDecision(projectId: string, agentId: string, attemptId: string | null, stage: string, sourceTokens: number, projectedTokens: number, details: Json): Document;
+    compactContext(projectId: string, agentId: string, summary: string, preserveFromOrdinal: number): Document;
+    forkContext(projectId: string, sourceAgentId: string, targetAgentId: string, throughOrdinal: number): readonly Document[];
+    createContextFork(projectId: string, sourceAgentId: string, input: {
+        readonly throughTurnGroupId: string;
+        readonly expectedContextRevision: number;
+        readonly name: string;
+        readonly model: string;
+        readonly modelReasoningEffort: string;
+    }): Document;
+    appendAssistantMessage(projectId: string, agentId: string, stepId: string, content: string): Document;
+    appendToolCalls(projectId: string, agentId: string, stepId: string, calls: readonly {
+        readonly id: string;
+        readonly name: string;
+        readonly arguments: Json;
+    }[]): Document;
+    /**
+     * `errorMessage` is what the failure actually said. `error_code` alone made a Provider rejection, a TLS
+     * fault and a malformed Tool block all read as one `RUNTIME_FAILED` with nothing to act on.
+     */
+    finishStep(projectId: string, stepId: string, outcome: string, errorCode?: string | null, errorMessage?: string | null): {
+        readonly step: Document;
+        readonly run: Document;
+        readonly agent: Document;
+    };
+    continueRun(projectId: string, stepId: string): Document;
+    yieldResults(projectId: string, agentId: string, callIds: readonly string[]): readonly Document[];
+    cancelAgent(projectId: string, agentId: string): readonly Document[];
+    runTimeline(projectId: string, runId: string, options: PageOptions): Page<Document>;
+    stepOutput(projectId: string, stepId: string): Document;
+    storageStats(): Document;
+    exportState(): Json;
+    purgeArchived(projectId: string, before: string): Document;
+    snapshot(projectId: string, maxEntities: number): Document;
+}
+export {};