@tomradex/agent 0.0.0-stage → 0.15.0

package/dist/service.d.ts

@@ -0,0 +1,445 @@
+import { Context, Service } from "cordis";
+import { z } from "zod";
+import { type UndoRunResult } from "@tomradex/domain";
+import type { SettingsSection } from "@tomradex/settings";
+import { AgentStore } from "./store.js";
+import { type MediaRef, type MediaUpload, type MediaContent } from "./media.js";
+import { type AgentEvent, type AgentPolicy, type CardView, type Engine, type CliCheck, type McpLinkView, type EngineTry, type EngineView, type FocusRef, type GeneralExecution, type ParkView, type PendingView, type Playbook, type PlaybookIndexEntry, type PlaybookSource, type RunView, type ThreadMessage, type ThreadSummary, type TurnFollowUp, type UserInput, type WorkflowSpec, type ThreadSurface } from "./types.js";
+import { type TokenBreakdown } from "./tokens.js";
+/** Where a thread's engine would run, or the one reason it cannot yet. `code` is stable for the renderer to translate. */
+/** Which of these threads a plugin opened, and what to call that: thread id → label. */
+export type ThreadOrigins = (projectId: string, threads: ThreadSummary[]) => Iterable<[string, string]>;
+export interface WorkdirStatus {
+    cwd: string | null;
+    remote: string | null;
+    branch: string | null;
+    worktree: string | null;
+    problem: string | null;
+    /**
+     * Why there is no folder. no-board, no-board-repo and unknown-repo come with no `problem`: a conversation
+     * on a workstream without a repository runs fine without one, and only a Start needs to say so.
+     */
+    code: "no-checkout" | "no-repos" | "no-board" | "no-board-repo" | "unknown-repo" | "no-hub" | "branch-in-use" | "finished" | "error" | null;
+    /** branch-in-use: the other worktree that has the branch. */
+    heldAt?: string;
+}
+export interface PlaybookRecommendation {
+    workType: "coding" | "general";
+    playbookId: string | null;
+    confidence: number;
+    reason: string;
+    source: "llm" | "fallback";
+    requires: string[];
+}
+/** What one engine's finished runs added up to over a stretch of time, across every open project. */
+export interface EngineUsage extends TokenBreakdown {
+    engine: string;
+    title: string;
+    runs: number;
+    /** Null when none of the runs said what it cost (Codex, the loop): tokens are all there is. */
+    costUsd: number | null;
+}
+export interface UsageSummary {
+    /** Since local midnight. */
+    today: EngineUsage[];
+    /** The last seven days, today included. */
+    week: EngineUsage[];
+}
+export interface ThreadDetail {
+    thread: ThreadSummary;
+    messages: ThreadMessage[];
+    runs: RunView[];
+    cards: CardView[];
+    pending: PendingView | null;
+    activePermissionMode?: string;
+}
+/** How a General ticket is to be run: which engine, which method, and the engine knobs for this delivery. */
+export interface GeneralStartOptions {
+    engine?: string;
+    playbook?: string;
+    /** Engine option overrides for the thread (model, effort…); replaces earlier overrides when given. */
+    options?: Record<string, unknown>;
+    /** The UI that owns the thread; a terminal session is a `code` surface thread the panel does not list. */
+    surface?: ThreadSurface;
+    /** The engine is a CLI the user runs themselves: no engine plugin is checked and none is required. */
+    external?: boolean;
+    /** Start although tickets this one waits on are still open; the agent is told which. */
+    allowBlocked?: boolean;
+}
+/** A General delivery ready to run: the thread is bound to the delivery and the playbook, nothing has been sent yet. */
+export interface GeneralPreparation {
+    threadId: string;
+    continued: boolean;
+    engine: string;
+    cwd: string;
+    playbook: GeneralExecution["playbook"];
+    /** The first user message of a headless run; the engine's system prompt carries the rest. */
+    opener: string;
+    /** The whole brief for a CLI agent the user runs in a terminal, which gets no system prompt from Tomrade. */
+    prompt: string;
+}
+/** What a new thread may be about beyond its workstream: the ticket it implements and the branch it works on. */
+export interface NewThreadOptions {
+    itemId?: string | null;
+    branch?: string | null;
+    title?: string;
+    /** The UI that owns this thread. Defaults to the Assistant panel. */
+    surface?: ThreadSurface;
+    /** The engine knobs the thread opens with — what the thread it was opened from was using. */
+    options?: Record<string, unknown> | null;
+}
+/** Current in-memory work plus durable questions, for main-process observers that load mid-run. */
+export interface AgentActivity {
+    projectId: string;
+    threadId: string;
+    run: RunView | null;
+    pending: PendingView | null;
+}
+declare module "cordis" {
+    interface Context {
+        agent: Agent;
+    }
+    interface Events {
+        /** Main-process lifecycle stream for feature plugins; renderer IPC is only one consumer. */
+        "agent/event"(threadId: string, event: AgentEvent): void;
+        /** The assistant panel switched to this thread, for observers that follow the conversation on screen. */
+        "agent/showing"(threadId: string): void;
+    }
+}
+declare module "@tomradex/ipc" {
+    interface Channels {
+        "agent.recommendPlaybook": (projectId: string, input: {
+            title: string;
+            body?: string | null;
+            workType?: "coding" | "general";
+        }) => PlaybookRecommendation;
+        "agent.startGeneral": (projectId: string, itemId: string, opts?: GeneralStartOptions) => {
+            threadId: string;
+            runId: string;
+            continued: boolean;
+        };
+        "agent.takeoverGeneral": (projectId: string, itemId: string) => {
+            stopped: number;
+        };
+        "agent.threads": (projectId: string) => ThreadSummary[];
+        "agent.thread": (projectId: string, threadId: string) => ThreadDetail;
+        "agent.usage": () => UsageSummary;
+        /** The project's rules for every agent, as the person wrote them; empty when there are none. */
+        "agent.rules": (projectId: string) => {
+            body: string;
+            file: string | null;
+        };
+        "agent.setRules": (projectId: string, body: string) => {
+            body: string;
+            file: string | null;
+        };
+        "agent.newThread": (projectId: string, engine?: string, boardId?: string | null, opts?: NewThreadOptions) => ThreadSummary;
+        /** Put the thread on a workstream (its repository is where a code engine runs), or back on the whole project. */
+        "agent.setWorkstream": (projectId: string, threadId: string, boardId: string | null) => ThreadSummary;
+        "agent.archiveThread": (projectId: string, threadId: string) => boolean;
+        "agent.archivedThreads": (projectId: string) => ThreadSummary[];
+        "agent.unarchiveThread": (projectId: string, threadId: string) => boolean;
+        "agent.deleteThread": (projectId: string, threadId: string) => boolean;
+        /** Where the thread's engine would run: ready, or why not yet (no checkout on this machine). */
+        "agent.workdir": (projectId: string, threadId: string) => WorkdirStatus;
+        "agent.send": (projectId: string, threadId: string, text: string, focus?: FocusRef[], attachments?: MediaRef[]) => {
+            runId: string;
+        };
+        "agent.media.upload": (projectId: string, threadId: string, upload: MediaUpload) => MediaRef;
+        "agent.media.read": (projectId: string, threadId: string, id: string) => MediaContent;
+        "agent.mediaCapabilities": (engineId: string, options?: unknown) => {
+            input: string[];
+            output: string[];
+        };
+        "agent.answer": (projectId: string, threadId: string, questionId: string, value: string | string[]) => {
+            runId: string;
+        };
+        "agent.cancel": (runId: string) => boolean;
+        /** Into the running turn, when its engine steers; false means it was not taken (queue it instead). */
+        "agent.steer": (projectId: string, threadId: string, steerId: string, text: string) => Promise<boolean>;
+        "agent.showing": (threadId: string) => void;
+        "agent.revert": (projectId: string, runId: string) => UndoRunResult;
+        /** `fresh` looks for each engine's CLI again instead of answering from a recent probe. */
+        "agent.engines": (opts?: {
+            fresh?: boolean;
+        }) => EngineView[];
+        /** Runs a file the person picked as an engine's CLI, before it is saved. */
+        "agent.checkCli": (engineId: string, file: string) => CliCheck;
+        /** Whether the engine's own user-level configuration reaches this Tomrade's MCP server. */
+        "agent.mcpLink": (engineId: string) => McpLinkView;
+        "agent.linkMcp": (engineId: string, profile?: string) => McpLinkView;
+        "agent.unlinkMcp": (engineId: string, profile?: string) => McpLinkView;
+        /** One real turn on the engine in a hidden thread of this project: does it answer? */
+        "agent.tryEngine": (projectId: string | null, engineId: string) => EngineTry;
+        "agent.setPermissionMode": (projectId: string, threadId: string, mode: string) => ThreadSummary;
+        "agent.setEngine": (projectId: string, threadId: string, engineId: string) => ThreadSummary;
+        /** Engine option overrides for one thread; null clears them so the engine's settings apply again. */
+        "agent.setOptions": (projectId: string, threadId: string, options: Record<string, unknown> | null) => ThreadSummary;
+        "agent.playbooks": (projectId?: string) => PlaybookIndexEntry[];
+    }
+    interface Broadcasts {
+        "agent.event": (threadId: string, event: AgentEvent) => void;
+    }
+}
+export declare const AgentConfig: z.ZodPreprocess<z.ZodObject<{
+    mediaDir: z.ZodOptional<z.ZodString>;
+    playbooksDir: z.ZodOptional<z.ZodString>;
+    codeMaxWallMs: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>>;
+export type AgentConfig = z.infer<typeof AgentConfig>;
+export interface AgentSettings {
+    defaultEngine: string;
+    /** No longer read: a plan always waits for the person before it is written. */
+    confirmWritesOver: number;
+    /** A run stopped by a usage limit is continued once the limit lifts. */
+    resumeAfterLimit: boolean;
+    /** Wall-clock ceiling of one run in a conversation without a ticket; it pauses while a question waits. */
+    maxRunMinutes: number;
+    engines: Record<string, unknown>;
+    /** Per-playbook-id: which source wins when several carry the same id. Absent = most specific wins. */
+    playbookChoices: Record<string, PlaybookSource>;
+}
+export declare const AGENT_SECTION: SettingsSection<AgentSettings>;
+export declare class Agent extends Service {
+    readonly config: AgentConfig;
+    static provide: string;
+    static inject: string[];
+    static Config: z.ZodPreprocess<z.ZodObject<{
+        mediaDir: z.ZodOptional<z.ZodString>;
+        playbooksDir: z.ZodOptional<z.ZodString>;
+        codeMaxWallMs: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    store: AgentStore;
+    private engines;
+    private trying;
+    private tries;
+    private workflows;
+    private followUps;
+    private playbooks;
+    private readonly origins;
+    /** Playbooks read from each project's shared copy; refreshed when a run starts. */
+    private projectPlaybooks;
+    private permissions;
+    private permissionQueues;
+    private activeByThread;
+    private shownThread;
+    private activeById;
+    private mediaStore?;
+    private parkTimers;
+    /** A run Tomrade started because a limit lifted, and how many limited runs came before it. */
+    private limitTries;
+    private resuming;
+    constructor(ctx: Context, config: AgentConfig);
+    [Service.init](): () => void;
+    /** A registered engine, for a plugin that reads the contract (the troubleshooter). */
+    engineOf(id: string): Engine | undefined;
+    /** The registered engine that answers for an id: the id itself, or the engine that includes it. */
+    answering(id: string): string;
+    /** The engines a person chooses between: none that another engine took in. */
+    allEngines(): Engine[];
+    engine(engine: Engine): () => void;
+    /** A plugin names the conversations it opened (thread id → a short label in the person's language). */
+    threadOrigins(provider: ThreadOrigins): () => void;
+    /** The threads with what each plugin says opened them. */
+    withOrigins(projectId: string, threads: ThreadSummary[]): ThreadSummary[];
+    playbook(playbook: Omit<Playbook, "tools"> & {
+        tools?: string[];
+    }): () => void;
+    policy(policy: AgentPolicy): () => void;
+    /** Registers the spec and exposes it as a tool named `spec.id` on every surface. */
+    workflow<I, S>(spec: WorkflowSpec<I, S>): () => void;
+    /** Registers a check that runs after every turn; see TurnFollowUp. */
+    followUp(followUp: TurnFollowUp): () => void;
+    thread(projectId: string, threadId: string): ThreadDetail;
+    /** The thread the assistant panel last showed; it outlives the panel, so leaving a project keeps it. */
+    showing(): string | null;
+    show(threadId: string): void;
+    activities(): AgentActivity[];
+    private pendingView;
+    engineViews(fresh?: boolean): Promise<EngineView[]>;
+    playbookIndex(projectId?: string): PlaybookIndexEntry[];
+    /**
+     * `withinMs` is for callers that must not wait on the worker model (an agent creating a ticket):
+     * past it, or on any failure, the keyword fallback answers instead.
+     */
+    recommendPlaybook(projectId: string, input: {
+        title: string;
+        body?: string | null;
+        workType?: "coding" | "general";
+    }, opts?: {
+        withinMs?: number;
+        signal?: AbortSignal;
+    }): Promise<PlaybookRecommendation>;
+    openPlaybook(id: string, projectId?: string): string | null;
+    /**
+     * Re-read `.tomrade/playbooks/` from the project's shared copy, when the
+     * project has one. Called when a run starts and when the panel asks for the
+     * index — never fatal: a project without storage simply has none.
+     */
+    refreshProjectPlaybooks(projectId: string): Promise<void>;
+    /** Runs and their tokens and spend, per engine, today and over the last week — what Tomrade itself recorded, nothing asked of a provider. */
+    usage(now?: number): UsageSummary;
+    /** `<project folder>/.tomrade/rules.md`: text beside the project's playbooks and decisions, travelling with it. */
+    rulesFile(projectId: string): string | null;
+    /** The project's rules for every agent, as the person wrote them; null when there are none. */
+    rules(projectId: string): string | null;
+    /** Empty removes the file. Rules are the person's: only their edit, or a rule they confirmed, lands here. */
+    setRules(projectId: string, body: string): void;
+    settingsOf(): AgentSettings;
+    /** Read when a run starts, so a changed setting reaches the next run. */
+    private wallLimit;
+    /** The old global "conversation" model role becomes the loop engine's own profile override, so a multi-profile pick survives. */
+    private migrateConversationRole;
+    /** A removed model profile stops being an engine's pick, so the engine is back on its default rather than a dead id. */
+    private forgetRemovedProfiles;
+    newThread(projectId: string, engine?: string, boardId?: string | null, opts?: NewThreadOptions): ThreadSummary;
+    /** Options the engine's own schema accepts; ones it rejects are dropped rather than leaving a thread that cannot run. */
+    private acceptedOptions;
+    /** The engines that may take a code turn — a local coding agent, never the in-app model. */
+    codeEngines(): Engine[];
+    private generalStarts;
+    private generalTakeovers;
+    private generalScratch;
+    private executionCapabilities;
+    takeoverGeneral(projectId: string, itemId: string): Promise<{
+        stopped: number;
+    }>;
+    /** A plugin advertises an available capability; this never grants tool permissions. */
+    capability(name: string): () => void;
+    private withGeneralLock;
+    /** Everything Start does for a General ticket short of sending the first message — what a terminal session needs before the user's own CLI takes over. */
+    prepareGeneral(projectId: string, itemId: string, opts?: GeneralStartOptions): Promise<GeneralPreparation>;
+    /**
+     * The engine a General ticket runs on: the one named, else the first that can take one right now.
+     * Available is not enough: Tomrade with no model is available, but only to chat.
+     */
+    private generalEngine;
+    startGeneral(projectId: string, itemId: string, opts?: GeneralStartOptions): Promise<{
+        threadId: string;
+        runId: string;
+        continued: boolean;
+    }>;
+    private prepare;
+    /** Runs in flight right now, across projects — what a quit would interrupt. */
+    activeRuns(): {
+        run: RunView;
+        thread: ThreadSummary;
+    }[];
+    setWorkstream(projectId: string, threadId: string, boardId: string | null): ThreadSummary;
+    archiveThread(projectId: string, threadId: string): boolean;
+    /** `restored`: a person brought it back by hand, so automatic archiving leaves it alone from now on. */
+    unarchiveThread(projectId: string, threadId: string, opts?: {
+        restored?: boolean;
+    }): boolean;
+    /**
+     * One real turn on the engine, in a thread nobody sees, deleted after: does it answer now? Never part
+     * of readiness — it costs the person's quota and a flaky network would lock out an engine that works.
+     */
+    tryEngine(projectId: string, engineId: string, signal?: AbortSignal): Promise<EngineTry>;
+    /** The last try, while the engine's settings are the ones it ran with. */
+    private triedWith;
+    private runTry;
+    deleteThread(projectId: string, threadId: string): boolean;
+    /**
+     * Where the thread's engine works, resolved through the workstream's repository and this machine's checkout of it.
+     * Only a run or a Start may `create` a missing worktree; looking never does. A finished thread
+     * (archived, or its ticket done) gets its worktree back only through `revive` — a fresh Start.
+     */
+    workdir(projectId: string, threadId: string, opts?: {
+        create?: boolean;
+        revive?: boolean;
+    }): Promise<WorkdirStatus>;
+    setPermissionMode(projectId: string, threadId: string, mode: string): ThreadSummary;
+    setEngine(projectId: string, threadId: string, asked: string): ThreadSummary;
+    /** Engine knobs for this thread alone — what the Start dialog and the panel's quick picks write. Null puts the engine's settings back in charge. */
+    setOptions(projectId: string, threadId: string, options: Record<string, unknown> | null): ThreadSummary;
+    /** The session to resume: the engine's own, else one an engine it took in left on the thread. */
+    private resumeOf;
+    /** The engine's settings with the thread's overrides on top — what a turn runs with. */
+    optionsOf(thread: Pick<ThreadSummary, "options">, engineId: string): object;
+    private media;
+    uploadMedia(projectId: string, threadId: string, upload: MediaUpload): MediaRef;
+    readMedia(projectId: string, threadId: string, id: string): MediaContent;
+    /** Providers publish through the platform so MCP and the in-app loop share output. */
+    runSignal(runId: string): AbortSignal;
+    publishMedia(runId: string, upload: MediaUpload, caption?: string, source?: MediaRef): MediaRef;
+    /** A transport retries the same request id without starting a second run, even after restart. */
+    send(projectId: string, threadId: string, input: UserInput, delivery?: {
+        requestId: string;
+        source?: Record<string, string>;
+    }): {
+        runId: string;
+    };
+    /** A message for the running turn: held until the engine reaches a point where the model reads it. */
+    steer(projectId: string, threadId: string, steerId: string, text: string): Promise<boolean>;
+    /** Stop a suspended question without starting an engine just to clear it. */
+    cancelWaiting(projectId: string, threadId: string): boolean;
+    cancel(runId: string): boolean;
+    revert(projectId: string, runId: string): UndoRunResult;
+    /** Set or update a card (the dossier is one). Emits both the live card and a block in the stream the first time. */
+    setCard(runId: string, card: {
+        id: string;
+        schema: string;
+        title: string;
+        data: unknown;
+    }): CardView;
+    brief(projectId: string): string | null;
+    /** The words the platform writes into a conversation, in the person's language now. */
+    private words;
+    private makeRunCtx;
+    private itemOf;
+    /** The ticket a code thread implements, as the engine should hear about it. */
+    private ticketOf;
+    /** Open dependencies are the human's call at Start; once work is under way they are what the agent is told, not a reason to stop it. */
+    private waitsOn;
+    private drive;
+    /** The turn is over but the run is not: follow-ups may still write into it, or end it on a question. */
+    private runFollowUps;
+    /** Writes a workflow makes outside a tool call still belong to the run, so they count and revert with it. */
+    private asRun;
+    /**
+     * On-script input goes straight back into the thing that asked: a suspended
+     * workflow resumes deterministically, an engine's own question is simply
+     * cleared so the engine reads the answer. Off-script input leaves the
+     * question standing and hands the turn to the engine, which sees it in
+     * `TurnInput.pending` and holds resume_workflow / cancel_workflow.
+     */
+    private routePending;
+    private startWorkflow;
+    /** Control is code while a workflow runs: steps transition, ask, or finish; asks persist and suspend. */
+    private driveWorkflow;
+    private finish;
+    /** The thread waiting for a usage limit to lift, if it is. */
+    parked(projectId: string, threadId: string): ParkView | null;
+    /**
+     * Holds a thread until a usage limit lifts: the conversation says so, and at
+     * `until` Tomrade continues it — or, when it cannot (a terminal session, the
+     * setting off, too many limited runs in a row), says the person can.
+     */
+    park(projectId: string, threadId: string, limit: {
+        until: number | null;
+        runId?: string | null;
+        attempt?: number;
+        resume?: boolean; /** A terminal session's thread holds no conversation to write into. */
+        note?: boolean;
+    }): ParkView;
+    /** Someone continued the thread another way — a terminal session resumed by hand. */
+    unpark(projectId: string, threadId: string): void;
+    private clearPark;
+    private armParked;
+    private armPark;
+    private liftPark;
+    private appendAndBroadcast;
+    private broadcast;
+    private registerPlatformTools;
+    /** `<playbooksDir>/<name>/SKILL.md` — the user slot; a plugin's id may coexist. */
+    /**
+     * The user's playbooks live in the Hub folder (`<Hub>/playbooks/`) and travel
+     * with it; the configured `playbooksDir` is where they lived before the Hub
+     * existed, and is moved into the Hub the first time one is chosen.
+     */
+    private userPlaybooksDir;
+    private migratePlaybooksIntoHub;
+    loadUserPlaybooks(): void;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/steps.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Words for the steps an engine takes with its own tools (a shell command, a
+ * file edit), so the panel shows what each one did, not just that it ran.
+ */
+/** The argument that says most about a call: the command, the file, the pattern. */
+export declare function stepHint(args: unknown, max?: number): string;
+/** The first line of a result that says something. */
+export declare function resultLine(output: unknown, max?: number): string;
+/** The one line under a step: what it was asked to do, and why it failed when it did. */
+export declare function stepSummary(args: unknown, output: unknown, ok: boolean): string;
+//# sourceMappingURL=steps.d.ts.map

package/dist/store.d.ts

@@ -0,0 +1,188 @@
+import type { Db } from "@tomradex/db";
+import type { Author } from "@tomradex/domain";
+import type { Block, CardView, GeneralExecution, ParkView, PendingView, RunStatus, RunView, ThreadMessage, ThreadSummary, ThreadSurface } from "./types.js";
+export declare const MIGRATIONS: {
+    version: number;
+    up: string;
+}[];
+export interface PendingRecord extends PendingView {
+    step: string | null;
+    state: unknown;
+    waiveRule: string | null;
+    waiveOn: string[];
+}
+/**
+ * Table declarations for `ctx.db.migrate`: how each table's rows belong to a
+ * project (deletion, the legacy split and export all read this), and whether
+ * they travel in the project's folder. Cards and pending questions are one
+ * machine's working state and never leave it. Conversations are `private`:
+ * they never travel to a public repository.
+ */
+export declare const TABLES: {
+    readonly plugin_agent_threads: {
+        readonly project: "project_id";
+        readonly export: {
+            readonly order: "id";
+            readonly private: true;
+        };
+    };
+    readonly plugin_agent_messages: {
+        readonly project: {
+            readonly via: "thread_id";
+            readonly table: "plugin_agent_threads";
+        };
+        readonly export: {
+            readonly order: "thread_id, seq";
+            readonly appendOnly: true;
+            readonly private: true;
+        };
+    };
+    readonly plugin_agent_runs: {
+        readonly project: {
+            readonly via: "thread_id";
+            readonly table: "plugin_agent_threads";
+        };
+        readonly export: {
+            readonly order: "thread_id, started_at";
+            readonly private: true;
+        };
+    };
+    readonly plugin_agent_ledger: {
+        readonly project: {
+            readonly via: "run_id";
+            readonly table: "plugin_agent_runs";
+        };
+        readonly export: {
+            readonly order: "run_id, seq";
+            readonly appendOnly: true;
+            readonly private: true;
+        };
+    };
+    readonly plugin_agent_cards: {
+        readonly project: {
+            readonly via: "thread_id";
+            readonly table: "plugin_agent_threads";
+        };
+        readonly export: false;
+    };
+    readonly plugin_agent_pending: {
+        readonly project: {
+            readonly via: "thread_id";
+            readonly table: "plugin_agent_threads";
+        };
+        readonly export: false;
+    };
+    readonly plugin_agent_briefs: {
+        readonly project: "project_id";
+        readonly export: {
+            readonly order: "project_id";
+        };
+    };
+    readonly plugin_agent_inputs: {
+        readonly project: {
+            readonly via: "thread_id";
+            readonly table: "plugin_agent_threads";
+        };
+        readonly export: false;
+    };
+    readonly plugin_agent_parked: {
+        readonly project: {
+            readonly via: "thread_id";
+            readonly table: "plugin_agent_threads";
+        };
+        readonly export: false;
+    };
+};
+/** Threads live in their project's file, so every read and write names the project first. */
+export declare class AgentStore {
+    private readonly pool;
+    /** The engine that answers for a stored engine id — another engine may have taken it in. */
+    private readonly engineOf;
+    constructor(pool: Db, 
+    /** The engine that answers for a stored engine id — another engine may have taken it in. */
+    engineOf?: (id: string) => string);
+    private toThread;
+    private db;
+    transaction<T>(projectId: string, work: () => T): T;
+    inputReceipt(projectId: string, requestId: string): {
+        thread_id: string;
+        fingerprint: string;
+        run_id: string;
+    } | undefined;
+    recordInput(projectId: string, requestId: string, threadId: string, fingerprint: string, runId: string, source?: Record<string, string>): void;
+    threads(projectId: string, surface?: ThreadSurface | ThreadSurface[] | null): ThreadSummary[];
+    /** Put away, newest first — so a conversation archived by mistake can be found and brought back. */
+    archivedThreads(projectId: string, surface?: ThreadSurface | ThreadSurface[]): ThreadSummary[];
+    setArchived(projectId: string, id: string, archived: boolean, opts?: {
+        restored?: boolean;
+    }): void;
+    deleteThread(projectId: string, id: string): void;
+    thread(projectId: string, id: string): ThreadSummary | null;
+    setExecution(projectId: string, threadId: string, execution: GeneralExecution): void;
+    recordPlaybook(projectId: string, runId: string, playbook: GeneralExecution["playbook"]): void;
+    createThread(projectId: string, engine: string, title?: string, boardId?: string | null, itemId?: string | null, branch?: string | null, surface?: ThreadSurface): ThreadSummary;
+    touchThread(projectId: string, id: string, fields?: {
+        title?: string;
+        engine?: string;
+        boardId?: string | null;
+        itemId?: string | null;
+        branch?: string | null;
+        surface?: ThreadSurface;
+        permissionMode?: string | null;
+        options?: Record<string, unknown> | null;
+    }): void;
+    /** Threads started from a ticket, newest first. */
+    threadsForItem(projectId: string, itemId: string): ThreadSummary[];
+    external(projectId: string, threadId: string): Record<string, string>;
+    /** Null forgets the engine's session. */
+    setExternal(projectId: string, threadId: string, engine: string, sessionId: string | null): void;
+    waivers(projectId: string, threadId: string): Set<string>;
+    addWaiver(projectId: string, threadId: string, rule: string): void;
+    messages(projectId: string, threadId: string): ThreadMessage[];
+    appendMessage(projectId: string, threadId: string, role: ThreadMessage["role"], block: Block, runId: string | null): ThreadMessage;
+    runs(projectId: string, threadId: string): RunView[];
+    run(projectId: string, id: string): RunView | null;
+    /** The project a run belongs to, searched across open files — for a caller that only holds the run id. */
+    projectOfRun(runId: string): string | null;
+    /** Runs left mid-flight by a killed process — no in-memory controller will ever cancel them. */
+    reconcileInterrupted(projectId: string, note?: string): void;
+    beginRun(projectId: string, threadId: string, engine: string): RunView;
+    endRun(projectId: string, id: string, fields: {
+        status: RunStatus;
+        stop?: string;
+        error?: string;
+        usage?: {
+            inputTokens?: number;
+            outputTokens?: number;
+        };
+        metrics?: RunView["metrics"];
+        costUsd?: number;
+        changes: number;
+    }): RunView;
+    markReverted(projectId: string, id: string, kept: number): RunView;
+    appendLedger(projectId: string, runId: string, seq: number, tool: string, args: unknown, ok: boolean, summary: string, ms: number): void;
+    cards(projectId: string, threadId: string): CardView[];
+    setCard(projectId: string, threadId: string, card: {
+        id: string;
+        schema: string;
+        title: string;
+        data: unknown;
+    }, by: Author | "human"): CardView;
+    pending(projectId: string, threadId: string): PendingRecord | null;
+    setPending(projectId: string, threadId: string, record: Omit<PendingRecord, "threadId">): void;
+    clearPending(projectId: string, threadId: string): void;
+    parked(projectId: string, threadId: string): ParkView | null;
+    allParked(projectId: string): ParkView[];
+    park(projectId: string, park: ParkView): void;
+    unpark(projectId: string, threadId: string): boolean;
+    brief(projectId: string): string | null;
+    setBrief(projectId: string, body: string): void;
+    changesOf(projectId: string, runId: string): number;
+    /** What the run netted out to, per entity — the facts behind "Changed N". */
+    changedEntities(projectId: string, runId: string): {
+        key: string;
+        label: string;
+        op: "created" | "updated" | "deleted";
+    }[];
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/tokens.d.ts

@@ -0,0 +1,21 @@
+import type { TurnMetrics } from "./evaluation.js";
+/**
+ * A run's tokens the one way a ticket's conversation and the Usage pane both
+ * show them. Input is every prompt token the model read: new (uncached) +
+ * cache read + cache write, so the three parts always add up to it. Engines
+ * that report no cache counters count all their input as new.
+ */
+export interface TokenBreakdown {
+    inputTokens: number;
+    uncachedInputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    outputTokens: number;
+}
+export declare const NO_TOKENS: TokenBreakdown;
+export declare function runTokens(usage: {
+    inputTokens?: number;
+    outputTokens?: number;
+} | null | undefined, metrics?: Pick<TurnMetrics, "cacheReadTokens" | "cacheWriteTokens"> | null): TokenBreakdown | null;
+export declare const addTokens: (a: TokenBreakdown, b: TokenBreakdown | null) => TokenBreakdown;
+//# sourceMappingURL=tokens.d.ts.map