ctxfile 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,942 @@
+import { z } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+interface ConnectorStatus {
+    name: string;
+    status: "ok" | "skipped" | "error";
+    error?: string;
+    durationMs: number;
+}
+interface KeyFile {
+    path: string;
+    tokens: number;
+    truncated: boolean;
+    redactions: number;
+    content: string;
+}
+interface GitCommit {
+    hash: string;
+    date: string;
+    message: string;
+    author: string;
+}
+interface GitState {
+    branch: string;
+    staged: string[];
+    modified: string[];
+    untracked: string[];
+    ahead: number;
+    behind: number;
+    commits: GitCommit[];
+    diffSummary: string;
+}
+interface NotionPage {
+    id: string;
+    title: string;
+    lastEditedTime: string;
+    content: string;
+}
+interface SessionDigest {
+    /** Originating tool, e.g. "claude-code", "cursor", "codex", "opencode",
+        "gemini-cli", "aider", "openclaw". Open set: new session connectors
+        add sources without a core type change. */
+    source: string;
+    sessionId: string;
+    startedAt: string | null;
+    lastActiveAt: string | null;
+    turnCount: number;
+    /** Redacted, token-capped rolling summary of the conversation's text turns. */
+    digest: string;
+}
+interface ContextMeta {
+    name: "ctxfile";
+    version: string;
+    generatedAt: string;
+    root: string;
+    tokenBudget: number;
+    tokensUsed: number;
+    connectors: ConnectorStatus[];
+}
+interface ContextObject {
+    meta: ContextMeta;
+    plan: string | null;
+    keyFiles: KeyFile[];
+    gitState: GitState | null;
+    notionPages: NotionPage[];
+    /** Recent agent-session digests (populated by Pro session connectors). */
+    sessions?: SessionDigest[];
+    sessionSummary: string | null;
+}
+type ContextScope = "full" | "plan" | "files" | "git";
+/** Progress events emitted while a snapshot builds (consumed by the local UI's SSE stream). */
+type BuildEvent = {
+    type: "connector:start";
+    name: string;
+} | {
+    type: "connector:done";
+    connector: ConnectorStatus;
+} | {
+    type: "tokens";
+    tokensUsed: number;
+    tokenBudget: number;
+} | {
+    type: "done";
+    generatedAt: string;
+};
+
+/**
+ * `ctxfile export`: the ContextObject as a static, self-describing artifact
+ * (".ctxfile convention") that cloud agents read from the repo or a CI
+ * artifact. The envelope keys are snake_case and frozen by the public schema;
+ * the embedded context keeps the camelCase shape `get_context` already serves.
+ */
+declare const EXPORT_SCHEMA_VERSION = "1";
+declare const EXPORT_PROFILES: readonly ["repo-safe", "full", "custom"];
+type ExportProfile = (typeof EXPORT_PROFILES)[number];
+declare const EXPORT_SECTIONS: readonly ["plan", "gitState", "keyFiles", "keyFileContent", "notionPages", "sessions", "sessionSummary"];
+type ExportSection = (typeof EXPORT_SECTIONS)[number];
+interface ExportedKeyFile {
+    path: string;
+    tokens: number;
+    truncated: boolean;
+    redactions: number;
+    /** Present only when the "keyFileContent" section is included. */
+    content?: string;
+}
+interface ExportedContext {
+    meta: ContextMeta;
+    plan: string | null;
+    keyFiles: ExportedKeyFile[];
+    gitState: GitState | null;
+    notionPages: NotionPage[];
+    sessions?: SessionDigest[];
+    sessionSummary: string | null;
+}
+interface ExportEnvelope {
+    ctxfile_schema: typeof EXPORT_SCHEMA_VERSION;
+    ctxfile_version: string;
+    profile: ExportProfile;
+    /** When this artifact was written (drift detection, together with git_sha). */
+    generated_at: string;
+    /** When the underlying snapshot was built. */
+    snapshot_generated_at: string;
+    git_sha: string | null;
+    /** Basename only; the absolute local path never leaves the machine. */
+    root_name: string;
+    /** Sections actually present, so a found file explains itself. */
+    sections: ExportSection[];
+    context: ExportedContext;
+}
+interface BuildExportOptions {
+    profile: ExportProfile;
+    /** Section allowlist for the "custom" profile (falls back to repo-safe). */
+    customSections?: ExportSection[] | null;
+    /** Clock override for tests. */
+    now?: () => Date;
+}
+declare function buildExportEnvelope(ctx: ContextObject, options: BuildExportOptions): ExportEnvelope;
+/** Human/agent-readable render of the same artifact (context.md). */
+declare function renderExportMarkdown(envelope: ExportEnvelope): string;
+
+/** Scopes for the HTTP door: what a bearer token may do on a connection. */
+declare const SERVE_SCOPES: readonly ["read:context", "write:sessions"];
+type ServeScope = (typeof SERVE_SCOPES)[number];
+interface ConsultProviderSpec {
+    type: "anthropic" | "openai-compatible" | "ollama";
+    model?: string;
+    baseUrl?: string;
+    /** Name of the env var holding the API key — never the key itself. */
+    apiKeyEnv?: string;
+}
+interface ServeTokenSpec {
+    name: string;
+    /** Name of the env var holding the bearer token — never the token itself. */
+    tokenEnv: string;
+    scopes: ServeScope[];
+}
+interface ResolvedConfig {
+    root: string;
+    tokenBudget: number;
+    maxFileTokens: number;
+    cacheDir: string;
+    cacheMaxAgeMs: number;
+    include: string[];
+    exclude: string[];
+    notion: {
+        token: string | null;
+        pageIds: string[];
+    };
+    ollama: {
+        baseUrl: string;
+        model: string | null;
+        summarize: boolean;
+    };
+    voice: {
+        whisperPath: string | null;
+        modelPath: string | null;
+        audioDir: string | null;
+    };
+    consult: {
+        providers: ConsultProviderSpec[];
+    };
+    telemetry: {
+        enabled: boolean;
+        endpoint: string;
+    };
+    export: {
+        profile: ExportProfile;
+        include: ExportSection[] | null;
+    };
+    behavior: {
+        debounceMinutes: number;
+    };
+    /** The HTTP door (`ctxfile serve`): loopback default, bearer tokens by env var. */
+    serve: {
+        port: number;
+        host: string;
+        tokens: ServeTokenSpec[];
+    };
+}
+interface LoadConfigOptions {
+    root?: string;
+    configPath?: string;
+    env?: NodeJS.ProcessEnv;
+}
+declare function loadConfig(opts?: LoadConfigOptions): ResolvedConfig;
+
+declare function estimateTokens(text: string): number;
+declare function truncateToTokens(text: string, maxTokens: number): {
+    text: string;
+    truncated: boolean;
+};
+declare class TokenBudget {
+    private readonly total;
+    private consumed;
+    constructor(total: number);
+    used(): number;
+    remaining(): number;
+    take(tokens: number): boolean;
+}
+
+interface SnapshotInput {
+    config: ResolvedConfig;
+    budget: TokenBudget;
+}
+interface Connector {
+    name: string;
+    isEnabled(config: ResolvedConfig): boolean;
+    snapshot(input: SnapshotInput): Promise<Partial<ContextObject>>;
+}
+interface Summarizer {
+    name: string;
+    isEnabled(config: ResolvedConfig): boolean;
+    summarize(ctx: ContextObject, config: ResolvedConfig): Promise<string | null>;
+}
+
+declare const fileConnector: Connector;
+
+declare const gitConnector: Connector;
+
+type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+interface NotionConnectorOptions {
+    fetchImpl?: FetchLike;
+    /** Minimum ms between requests. Notion allows ~3 req/s per connection. */
+    minIntervalMs?: number;
+}
+declare function createNotionConnector(options?: NotionConnectorOptions): Connector;
+
+interface OllamaSummarizerOptions {
+    fetchImpl?: FetchLike;
+    healthTimeoutMs?: number;
+}
+declare function createOllamaSummarizer(options?: OllamaSummarizerOptions): Summarizer;
+
+declare function buildContext(config: ResolvedConfig, connectors: Connector[], summarizer: Summarizer | null, scope?: ContextScope, onEvent?: (event: BuildEvent) => void): Promise<ContextObject>;
+declare function filterScope(ctx: ContextObject, scope: ContextScope): ContextObject;
+
+declare class SnapshotCache {
+    private readonly db;
+    constructor(dbPath: string);
+    save(root: string, ctx: ContextObject, configFingerprint?: string, agentId?: string): void;
+    latest(root: string, maxAgeMs: number, configFingerprint?: string, agentId?: string): ContextObject | null;
+    /** Newest-first snapshot summaries for the UI freshness timeline. Corrupt rows are skipped. */
+    recent(root: string, limit?: number, agentId?: string): {
+        createdAt: number;
+        tokensUsed: number;
+    }[];
+    close(): void;
+}
+
+/**
+ * Agent-assisted session ingest: the inverse of the session parsers. Instead
+ * of ctxfile reverse-engineering a harness's storage, the client surface's
+ * own agent formats its session per this published schema and calls
+ * `ingest_context` (bulk/agent door) or `save_session` (conversational door).
+ * The prompt is the adapter. Parsers stay the invisible default (Pro); ingest
+ * is the universal floor for every harness, including ones not written yet.
+ *
+ * Schema v2 adds threads (durable identities that outlive any one provider's
+ * chat history), session lineage via `continues_from`, and the handoff
+ * package: when `handoff: true`, validation enforces everything a cold
+ * takeover needs, so any agent on any harness produces the same artifact.
+ *
+ * This is a write path fed by LLM output, so provenance is non-negotiable:
+ * every record is stamped `reported_by: "agent"` plus the door it came
+ * through, labeled as agent-reported wherever it surfaces, reviewable and
+ * deletable via `ctxfile ingest`.
+ */
+declare const INGEST_SCHEMA_VERSION = "2";
+declare const ingestSourceSchema: z.ZodObject<{
+    harness: z.ZodString;
+    harness_version: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const ingestSessionSchema: z.ZodObject<{
+    session_id: z.ZodOptional<z.ZodString>;
+    started_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    ended_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    summary: z.ZodString;
+    key_decisions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    files_touched: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    open_items: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    thread: z.ZodOptional<z.ZodString>;
+    continues_from: z.ZodOptional<z.ZodString>;
+    handoff: z.ZodOptional<z.ZodBoolean>;
+    state: z.ZodOptional<z.ZodString>;
+    gotchas: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    artifacts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        ref: z.ZodString;
+        role: z.ZodString;
+    }, z.core.$strict>>>;
+    suggested_first_prompt: z.ZodOptional<z.ZodString>;
+    trigger: z.ZodOptional<z.ZodEnum<{
+        auto: "auto";
+        manual: "manual";
+    }>>;
+}, z.core.$strict>;
+declare const ingestInputSchema: z.ZodObject<{
+    ctxfile_ingest_schema: z.ZodEnum<{
+        1: "1";
+        2: "2";
+    }>;
+    source: z.ZodObject<{
+        harness: z.ZodString;
+        harness_version: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    session: z.ZodObject<{
+        session_id: z.ZodOptional<z.ZodString>;
+        started_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        ended_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        summary: z.ZodString;
+        key_decisions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        files_touched: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        open_items: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        thread: z.ZodOptional<z.ZodString>;
+        continues_from: z.ZodOptional<z.ZodString>;
+        handoff: z.ZodOptional<z.ZodBoolean>;
+        state: z.ZodOptional<z.ZodString>;
+        gotchas: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        artifacts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            ref: z.ZodString;
+            role: z.ZodString;
+        }, z.core.$strict>>>;
+        suggested_first_prompt: z.ZodOptional<z.ZodString>;
+        trigger: z.ZodOptional<z.ZodEnum<{
+            auto: "auto";
+            manual: "manual";
+        }>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+type IngestInput = z.infer<typeof ingestInputSchema>;
+/** save_session takes the session fields directly (no envelope); the harness
+    is inferred from the connected client unless declared explicitly. */
+declare const saveSessionSchema: z.ZodObject<{
+    session_id: z.ZodOptional<z.ZodString>;
+    started_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    ended_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    summary: z.ZodString;
+    key_decisions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    files_touched: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    open_items: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    thread: z.ZodOptional<z.ZodString>;
+    continues_from: z.ZodOptional<z.ZodString>;
+    handoff: z.ZodOptional<z.ZodBoolean>;
+    state: z.ZodOptional<z.ZodString>;
+    gotchas: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    artifacts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        ref: z.ZodString;
+        role: z.ZodString;
+    }, z.core.$strict>>>;
+    suggested_first_prompt: z.ZodOptional<z.ZodString>;
+    trigger: z.ZodOptional<z.ZodEnum<{
+        auto: "auto";
+        manual: "manual";
+    }>>;
+    harness: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type SaveSessionInput = z.infer<typeof saveSessionSchema>;
+/** Which tool a record arrived through; part of its provenance. */
+type IngestDoor = "ingest_context" | "save_session";
+interface IngestArtifact {
+    ref: string;
+    role: string;
+}
+/** One stored, provenance-stamped ingest record. */
+interface IngestedSession {
+    id: number;
+    root: string;
+    harness: string;
+    harnessVersion: string | null;
+    sessionId: string;
+    reportedBy: "agent";
+    door: IngestDoor;
+    trigger: "auto" | "manual";
+    startedAt: string | null;
+    endedAt: string | null;
+    summary: string;
+    keyDecisions: string[];
+    filesTouched: string[];
+    openItems: string[];
+    threadId: number | null;
+    threadTitle: string | null;
+    continuesFrom: string | null;
+    handoff: boolean;
+    state: string | null;
+    gotchas: string[];
+    artifacts: IngestArtifact[];
+    suggestedFirstPrompt: string | null;
+    ingestedAt: string;
+    updatedAt: string;
+    revision: number;
+}
+/** Turns a validation failure into the actionable message agents self-correct from. */
+declare function formatIngestErrors(error: z.ZodError, toolName?: string): string;
+/** Stable identity when the harness has no native session id. */
+declare function ingestSessionId(input: IngestInput): string;
+/** Renders an ingest record as a SessionDigest so it rides the normal
+    sessions surface, loudly labeled as agent-reported. */
+declare function ingestToSessionDigest(record: IngestedSession, maxTokens?: number): SessionDigest;
+/** Parser wins: an ingest record whose sessionId matches a parser-provided
+    session is linked (dropped here), never duplicated. */
+declare function mergeIngestedSessions(parserSessions: SessionDigest[] | undefined, ingested: IngestedSession[]): SessionDigest[] | undefined;
+interface ThreadSummary {
+    id: number;
+    title: string;
+    status: string;
+    tags: string[];
+    /** Private threads are excluded from behavior-layer auto-capture (§4.1). */
+    private: boolean;
+    createdAt: string;
+    lastActiveAt: string;
+    sessionCount: number;
+    lastHarness: string | null;
+}
+type ThreadResolution = {
+    kind: "resolved";
+    thread: ThreadSummary;
+    assumed: boolean;
+} | {
+    kind: "ambiguous";
+    candidates: ThreadSummary[];
+} | {
+    kind: "none";
+};
+/** Deterministic fuzzy score in [0, 1]: exact 1, containment 0.85, tag hit
+    0.8, else token overlap scaled into (0.3, 0.8]. */
+declare function scoreThreadMatch(query: string, thread: Pick<ThreadSummary, "title" | "tags">): number;
+/** The "you know what I mean" rules: named thread fuzzy-matches; no name
+    defaults to the most recently active (and the caller says so); a genuine
+    tie returns the shortlist to ask with. */
+declare function resolveThread(query: string | undefined, threads: ThreadSummary[]): ThreadResolution;
+/** Renders continue_thread's merged history: chronological order, per-entry
+    provenance labels, newest-detailed/oldest-summarized token budgeting.
+    Shared by the local server and the relay's Standard-mode vault serving. */
+declare function renderThreadResume(thread: ThreadSummary, sessions: IngestedSession[], assumed: boolean): string;
+/** Maps an MCP client's advertised name to a harness id, so save_session
+    callers never have to know our enum. Unknown clients become custom:<name>. */
+declare function inferHarnessFromClientName(clientName: string | undefined): string;
+
+/**
+ * The Sync mailbox protocol, client side (M2). Push/pull of encrypted blobs
+ * with last-write-wins per blob and tombstones; no CRDTs, because a vault is
+ * single-user. The relay implements RelayStore (M3: Fly.io/R2; tests: an
+ * in-memory stub) and only ever sees opaque ids, version numbers, and
+ * ciphertext. Both sides converge because versions are the source records'
+ * own updated-at clocks and apply() is idempotent.
+ */
+/** What the relay sees per blob: opaque id, version, deletion flag. */
+interface SyncBlobMeta {
+    id: string;
+    version: number;
+    deleted: boolean;
+}
+/** The relay contract. M3 implements this over HTTP + R2; the same shape
+    self-hosts as the Team hub's storage. */
+interface RelayStore {
+    list(): Promise<SyncBlobMeta[]>;
+    get(id: string): Promise<{
+        meta: SyncBlobMeta;
+        data: Uint8Array;
+    } | null>;
+    put(id: string, meta: SyncBlobMeta, data: Uint8Array): Promise<void>;
+}
+/** One syncable record, plaintext side. The payload carries its own natural
+    identity, so tombstones and cross-device applies never depend on ids the
+    relay can read. */
+interface SyncEntry {
+    naturalId: string;
+    /** LWW clock: the record's own updated-at, in ms. */
+    version: number;
+    deleted: boolean;
+    payload: Uint8Array;
+}
+interface LocalBlobSource {
+    snapshot(): Promise<SyncEntry[]>;
+    /** Applies remote entries with its own LWW check; returns how many changed local state. */
+    apply(entries: SyncEntry[]): Promise<number>;
+}
+interface SyncResult {
+    pushed: number;
+    applied: number;
+}
+declare class SyncClient {
+    private readonly local;
+    private readonly relay;
+    private readonly key;
+    constructor(local: LocalBlobSource, relay: RelayStore, key: Uint8Array);
+    private opaqueIds;
+    /** Uploads every local blob that is newer than (or absent from) the relay. */
+    push(): Promise<number>;
+    /** Downloads and applies every remote blob newer than local state. */
+    pull(): Promise<number>;
+    /** Pull first (so local LWW sees the freshest remote), then push. */
+    sync(): Promise<SyncResult>;
+}
+
+interface IngestResult {
+    id: number;
+    sessionId: string;
+    revision: number;
+    action: "created" | "updated";
+    threadId: number | null;
+    threadTitle: string | null;
+}
+declare class IngestStore {
+    private readonly db;
+    constructor(dbPath: string);
+    /** Idempotent v2 migration: column-presence checks, never version guesses,
+        so a v1 database upgrades in place and a v2 one is untouched. */
+    private migrate;
+    /** Case-insensitive find-or-create; titles are redacted like all content.
+        Re-using a tombstoned (deleted) title resurrects that row — clearing
+        `deleted` — rather than bumping its clock while it stays deleted (which
+        would attach a session to an invisible thread and re-push a tombstone with
+        a newer clock). A unique (root, lower(title)) index makes one row per
+        title the only possibility, so resurrection is the correct move. */
+    ensureThread(root: string, title: string, now?: number): {
+        id: number;
+        title: string;
+        created: boolean;
+    };
+    /** The thread of a prior session, so `continues_from` carries lineage even
+        when the reporting agent never names the thread. */
+    private threadOfSession;
+    private threadTitle;
+    /** Upsert on (root, harness, session_id): re-ingest updates with history. */
+    ingest(root: string, input: IngestInput, now?: number, door?: IngestDoor): IngestResult;
+    /** Newest-first records for this project. */
+    list(root: string, limit?: number): IngestedSession[];
+    /** All threads for this project, most recently active first. */
+    listThreads(root: string): ThreadSummary[];
+    /** A thread's sessions in chronological (oldest-first) order. */
+    threadSessions(root: string, threadId: number): IngestedSession[];
+    /** The newest auto checkpoint on a thread, for the behavior-layer debounce
+        (§4.2: reject unchanged checkpoints inside the window). */
+    latestAutoForThread(root: string, threadTitle: string): IngestedSession | null;
+    /** Marks a thread private (excluded from auto-capture) or public again. */
+    setThreadPrivate(root: string, threadId: number, isPrivate: boolean, now?: number): boolean;
+    /** Whether the (case-insensitive) titled thread is private; false when the
+        thread does not exist yet. */
+    threadIsPrivate(root: string, title: string): boolean;
+    /** Deletes one record by numeric id (as shown by `ctxfile ingest list`).
+        A tombstone, not a hard delete, so the deletion syncs like any write. */
+    remove(root: string, id: number, now?: number): boolean;
+    /** Everything syncable for this root, tombstones included. */
+    exportSyncEntries(root: string): SyncEntry[];
+    /** Applies decrypted sync entries with per-record LWW; returns how many
+        changed local state. Content was redacted before it was first stored,
+        and blobs are AEAD-authenticated, so imports apply verbatim. */
+    importSyncEntries(root: string, entries: SyncEntry[]): number;
+    /** This store, adapted to the SyncClient contract for one root. */
+    syncSource(root: string): LocalBlobSource;
+    private applyThreadPayload;
+    private applySessionPayload;
+    close(): void;
+}
+
+interface SnapshotService {
+    getContext(scope?: ContextScope): Promise<ContextObject>;
+    rebuild(onEvent?: (event: BuildEvent) => void): Promise<ContextObject>;
+    /** Fresh cache hit only (cacheMaxAgeMs), scope-filtered; null means a rebuild is needed. */
+    getCached(scope?: ContextScope): ContextObject | null;
+    latestCached(): ContextObject | null;
+    recentSnapshots(limit?: number): {
+        createdAt: number;
+        tokensUsed: number;
+    }[];
+}
+declare function createSnapshotService(config: ResolvedConfig, deps: {
+    cache: SnapshotCache | null;
+    connectors: Connector[];
+    summarizer: Summarizer | null;
+    /** Agent-reported sessions merged into every snapshot (parser wins on id). */
+    ingest?: IngestStore | null;
+}): SnapshotService;
+
+/**
+ * The Behavior Layer (design doc 11): one canonical behavior spec, rendered
+ * into per-harness formats. MCP gives an agent tools; this gives it behavior:
+ * checkpoint at the right moments, announce every save, detect handoffs. The
+ * "software" is prose; this module is the renderer, the installer, and the
+ * consent/pause state the server's guardrails read.
+ */
+declare const BEHAVIOR_HARNESSES: readonly ["claude-code", "cursor", "agents-md", "codex", "generic"];
+type BehaviorHarness = (typeof BEHAVIOR_HARNESSES)[number];
+/** The canonical spec ships inside the npm package beside dist/. */
+declare function loadCanonicalBehaviors(): string;
+interface RenderedBehavior {
+    harness: BehaviorHarness;
+    /** Path relative to the render root (or the suggested install location). */
+    relativePath: string;
+    content: string;
+}
+/** Deterministic renders from the single source; the repo's committed
+    render/ folder is regenerated by scripts/render-behaviors.mjs and a test
+    fails if it drifts from this function's output. */
+declare function renderBehavior(harness: BehaviorHarness, canonical?: string): RenderedBehavior;
+declare function renderAllBehaviors(canonical?: string): RenderedBehavior[];
+interface DetectedHarness {
+    harness: BehaviorHarness;
+    reason: string;
+}
+/** Cheap, honest detection: directories the harnesses actually create. */
+declare function detectHarnesses(root: string, home: string): DetectedHarness[];
+interface InstallResult {
+    harness: BehaviorHarness;
+    target: string;
+    action: "created" | "updated" | "printed";
+}
+/** Writes the behavior file where the harness looks for it. Append-style
+    targets get the managed block (idempotent re-install); file-style targets
+    are whole files we own. */
+declare function installBehavior(harness: BehaviorHarness, root: string, canonical?: string): InstallResult;
+interface UninstallResult {
+    harness: BehaviorHarness;
+    target: string;
+    action: "removed" | "stripped" | "absent";
+}
+/** Reverses installBehavior for one harness. File-style targets we own (the
+    claude-code skill dir, the cursor rule) are deleted; the AGENTS.md managed
+    block is cut by its markers, leaving any surrounding content intact (and the
+    file removed only if our block was all it held). codex/generic were never
+    written, so there is nothing to remove. Never touches unrelated content. */
+declare function uninstallBehavior(harness: BehaviorHarness, root: string): UninstallResult;
+interface BehaviorState {
+    /** Explicit install-time consent (§4.1). Fail closed: an absent or unreadable
+        state file means no consent, so auto-captures are refused until `ctxfile
+        init` records it (or `--yes`). */
+    autoCapture: boolean;
+    paused: boolean;
+    consentAt?: string;
+    pausedAt?: string;
+}
+declare function readBehaviorState(cacheDir: string): BehaviorState;
+declare function writeBehaviorState(cacheDir: string, state: BehaviorState): void;
+/** Removes the consent/pause record, returning the install to a pre-`init`
+    state (fail-closed: auto-capture is then off until consent is recorded
+    again). Returns true if a state file was present. */
+declare function clearBehaviorState(cacheDir: string): boolean;
+/** True when automatic captures must be refused right now. */
+declare function autoCaptureBlocked(cacheDir: string): {
+    blocked: boolean;
+    reason: string | null;
+};
+
+declare function inspectLicenseKey(key: string, now?: Date): {
+    ok: boolean;
+    detail: string;
+};
+
+interface ProUiFeatures {
+    sessions: boolean;
+    memory: boolean;
+    consult: boolean;
+    voice: boolean;
+}
+interface ProMemoryEntry {
+    id: string;
+    agentId: string;
+    content: string;
+    createdAt: string;
+    /** Human-readable provenance: which tool/session wrote this entry. */
+    provenance: string;
+}
+interface ProLicenseInfo {
+    /** License tier from the verified payload; null when unlicensed. */
+    tier: string | null;
+    /** ISO expiry timestamp from the verified payload; null when unlicensed. */
+    expiresAt: string | null;
+    customerId?: string | null;
+}
+interface ProUiApi {
+    features(): ProUiFeatures;
+    /** Display metadata from the verified license payload — never the key itself. */
+    licenseInfo?(): ProLicenseInfo;
+    listMemory(): Promise<ProMemoryEntry[]>;
+    forgetMemory(id: string): Promise<boolean>;
+    /** Streams consult progress via onEvent; resolves when complete. */
+    consult?(question: string, onEvent: (event: {
+        type: string;
+        data: unknown;
+    }) => void): Promise<void>;
+}
+interface ProModule {
+    name: string;
+    connectors?: Connector[];
+    /**
+     * Handed the resolved config by createRuntime() before any tools or UI are
+     * used — the `ui` surface needs it on paths where registerTools never runs
+     * (the `ctxfile ui` command has no MCP server).
+     */
+    init?(config: ResolvedConfig): void;
+    registerTools?(server: McpServer, config: ResolvedConfig): void;
+    /** null when licensed and active; otherwise a human-readable reason Pro is inactive. */
+    licenseStatus(): string | null;
+    /** Optional UI delegation surface consumed by the local dashboard server. */
+    ui?: ProUiApi;
+}
+declare function loadProModule(): Promise<ProModule | null>;
+
+interface KdfParams {
+    /** Argon2id opsLimit; default interactive (client-side, per libsodium guidance). */
+    opsLimit?: number;
+    /** Argon2id memLimit in bytes; default interactive (64 MiB). */
+    memLimit?: number;
+}
+declare const MASTER_KEY_BYTES = 32;
+declare function generateSalt(): Promise<Uint8Array>;
+/** Passphrase -> 32-byte master key (Argon2id13). Store the salt and params
+    beside the vault metadata; they are not secret. */
+declare function deriveMasterKey(passphrase: string, salt: Uint8Array, params?: KdfParams): Promise<Uint8Array>;
+/** Encrypts one blob: MAGIC || 24-byte nonce || AEAD ciphertext.
+    `aad` binds the ciphertext to its slot (use the blob id). */
+declare function encryptBlob(key: Uint8Array, plaintext: Uint8Array, aad: string): Promise<Uint8Array>;
+/** Reverses encryptBlob. Throws on tampering, a wrong key, or a wrong aad. */
+declare function decryptBlob(key: Uint8Array, blob: Uint8Array, aad: string): Promise<Uint8Array>;
+declare function generateRecoveryCode(): Promise<string>;
+/** Canonical form of a recovery code for use as a wrapping secret, so a user
+    may retype it with any casing or dashing and still unwrap. Wrap and unwrap
+    MUST both pass the code through this. */
+declare function normalizeRecoveryCode(code: string): string;
+/** Wraps the master key under a secondary secret (the recovery code), so a
+    vault stays recoverable when the passphrase is lost. The wrapped copy is
+    safe to store beside the vault. */
+declare function wrapMasterKey(masterKey: Uint8Array, wrappingSecret: string, salt: Uint8Array, params?: KdfParams): Promise<Uint8Array>;
+declare function unwrapMasterKey(wrapped: Uint8Array, wrappingSecret: string, salt: Uint8Array, params?: KdfParams): Promise<Uint8Array>;
+/** Best-effort scrub of key material once done with it. */
+declare function zeroKey(key: Uint8Array): Promise<void>;
+/** Opaque, stable blob id: a keyed hash of the natural id, so the relay
+    learns nothing from ids (harness names, session ids stay private). */
+declare function deriveBlobId(key: Uint8Array, naturalId: string): Promise<string>;
+declare function toBase64(bytes: Uint8Array): Promise<string>;
+declare function fromBase64(text: string): Promise<Uint8Array>;
+
+/**
+ * RelayStore over HTTP: the client half of the relay's blob API. The wire
+ * carries only opaque ids, versions, and base64 ciphertext; the bearer token
+ * is the vault token minted at vault create/join.
+ */
+interface HttpRelayStoreOptions {
+    fetchImpl?: typeof fetch;
+}
+declare class HttpRelayStore implements RelayStore {
+    private readonly token;
+    private readonly base;
+    private readonly fetchImpl;
+    constructor(relayUrl: string, token: string, options?: HttpRelayStoreOptions);
+    private request;
+    list(): Promise<SyncBlobMeta[]>;
+    get(id: string): Promise<{
+        meta: SyncBlobMeta;
+        data: Uint8Array;
+    } | null>;
+    put(id: string, meta: SyncBlobMeta, data: Uint8Array): Promise<void>;
+}
+
+/**
+ * The plaintext shapes that travel inside encrypted sync blobs, shared by the
+ * local store (export/import) and the relay (which reconstructs a vault view
+ * from decrypted payloads to serve the five MCP tools in Standard mode).
+ * Every payload carries its own natural identity, so applies are
+ * order-independent and never depend on relay-visible ids.
+ */
+interface SessionSyncPayload {
+    kind: "session";
+    harness: string;
+    harness_version: string | null;
+    session_id: string;
+    door: string;
+    started_at: string | null;
+    ended_at: string | null;
+    summary: string;
+    key_decisions: string[];
+    files_touched: string[];
+    open_items: string[];
+    thread_title: string | null;
+    continues_from: string | null;
+    handoff: boolean;
+    state: string | null;
+    gotchas: string[];
+    artifacts: IngestArtifact[];
+    suggested_first_prompt: string | null;
+    /** Behavior-layer provenance; absent in pre-v1 payloads means manual. */
+    trigger?: "auto" | "manual";
+    ingested_at: number;
+    updated_at: number;
+    revision: number;
+    deleted: boolean;
+}
+interface ThreadSyncPayload {
+    kind: "thread";
+    title: string;
+    status: string;
+    tags: string[];
+    created_at: number;
+    last_active: number;
+    deleted: boolean;
+    /** Local auto-capture exclusion, synced so it holds across devices. Absent
+        in pre-v1 payloads means public. */
+    private?: boolean;
+}
+type SyncPayload = SessionSyncPayload | ThreadSyncPayload;
+declare function parseSyncPayload(payload: Uint8Array): SyncPayload | null;
+declare function sessionPayloadToIngestedSession(payload: SessionSyncPayload, id: number, root?: string): IngestedSession;
+interface VaultView {
+    threads: ThreadSummary[];
+    /** Live sessions, chronological (oldest first), threadTitle populated. */
+    sessions: IngestedSession[];
+}
+/** Rebuilds the queryable view a local IngestStore would give, from nothing
+    but decrypted payloads. Tombstoned records are dropped; a session whose
+    thread payload never arrived still yields a thread summary. */
+declare function buildVaultView(payloads: SyncPayload[]): VaultView;
+
+/**
+ * The vault client (M2/M3 seam): create or join a vault on a relay, unlock it
+ * with the passphrase, and sync the local store through it. Key design: the
+ * blob key is a random data key; the passphrase (and a printed recovery code)
+ * merely WRAP it, and the wraps live on the relay as vault metadata, so a new
+ * device needs only the vault token plus the passphrase, and a passphrase
+ * change is a re-wrap, never a re-encrypt of the world. In Standard mode the
+ * data key is additionally enrolled with the relay's keyring for serve-time
+ * decryption; in Strict mode it never leaves your devices.
+ */
+interface VaultConfig {
+    relayUrl: string;
+    vaultId: string;
+    name: string;
+    mode: "standard" | "strict";
+    /** Bearer token for this device; treat like a password. */
+    token: string;
+}
+interface VaultMeta {
+    vault_id: string;
+    name: string;
+    mode: "standard" | "strict";
+    salt_b64: string;
+    kdf: {
+        ops_limit: number;
+        mem_limit: number;
+    };
+    wrapped_passphrase_b64: string;
+    /** Present on device-token reads; used by 'ctxfile vault recover'. */
+    wrapped_recovery_b64?: string;
+}
+/** Minimum vault passphrase length. Raised past a throwaway value because the
+    KDF salt and parameters are stored as vault metadata: a weak passphrase is
+    offline-bruteforceable by anyone who obtains that metadata. */
+declare const MIN_PASSPHRASE_LENGTH = 12;
+declare function assertPassphraseStrength(passphrase: string): void;
+declare const DEFAULT_VAULT_CONFIG_PATH: string;
+declare function loadVaultConfig(configPath?: string): VaultConfig | null;
+declare function saveVaultConfig(config: VaultConfig, configPath?: string): void;
+interface CreateVaultOptions {
+    relayUrl: string;
+    name: string;
+    mode: "standard" | "strict";
+    passphrase: string;
+    kdf?: KdfParams;
+    configPath?: string;
+    fetchImpl?: typeof fetch;
+}
+declare function createVault(options: CreateVaultOptions): Promise<{
+    config: VaultConfig;
+    recoveryCode: string;
+}>;
+interface JoinVaultOptions {
+    relayUrl: string;
+    token: string;
+    passphrase: string;
+    configPath?: string;
+    fetchImpl?: typeof fetch;
+}
+/** Second device: vault token + passphrase is all it takes; the salt and the
+    wrapped key come down from the relay. */
+declare function joinVault(options: JoinVaultOptions): Promise<VaultConfig>;
+interface RecoverVaultOptions {
+    relayUrl: string;
+    token: string;
+    recoveryCode: string;
+    newPassphrase: string;
+    configPath?: string;
+    fetchImpl?: typeof fetch;
+}
+/** Reset a lost passphrase with the printed recovery code. The data key is
+    recovered from the recovery wrap, then re-wrapped under the new passphrase
+    and a freshly rotated recovery code — nothing is re-encrypted. Requires a
+    device token (the recovery code replaces the passphrase factor, not the
+    device factor). Returns the new recovery code; the old one stops working. */
+declare function recoverVault(options: RecoverVaultOptions): Promise<{
+    config: VaultConfig;
+    recoveryCode: string;
+}>;
+declare function fetchVaultMeta(fetchImpl: typeof fetch, relayUrl: string, token: string): Promise<VaultMeta>;
+declare function unlockVault(config: VaultConfig, passphrase: string, fetchImpl?: typeof fetch): Promise<Uint8Array>;
+/** Everything wired: unlock, point the local store at the relay, sync. */
+declare function openVaultSync(config: VaultConfig, passphrase: string, store: IngestStore, root: string, fetchImpl?: typeof fetch): Promise<SyncClient>;
+
+declare function isDeniedPath(relPath: string): boolean;
+declare function redactContent(text: string): {
+    text: string;
+    redactions: number;
+};
+
+interface RuntimeOptions {
+    /** Pass null to disable snapshot caching (e.g. in tests). */
+    cache?: SnapshotCache | null;
+    connectors?: Connector[];
+    summarizer?: Summarizer | null;
+    /** Commercial Pro module, loaded via loadProModule(). */
+    pro?: ProModule | null;
+    /** Store for agent-reported sessions; pass null to disable (tests). */
+    ingest?: IngestStore | null;
+}
+
+interface ServerOptions extends RuntimeOptions {
+    /** Scope allowlist for this connection; undefined (stdio) means everything. */
+    scopes?: ServeScope[];
+}
+declare function createServer(config: ResolvedConfig, options?: ServerOptions): McpServer;
+
+declare const VERSION = "0.1.0";
+
+export { BEHAVIOR_HARNESSES, type BehaviorHarness, type BehaviorState, type BuildEvent, type BuildExportOptions, type Connector, type ConnectorStatus, type ConsultProviderSpec, type ContextMeta, type ContextObject, type ContextScope, type CreateVaultOptions, DEFAULT_VAULT_CONFIG_PATH, EXPORT_PROFILES, EXPORT_SCHEMA_VERSION, EXPORT_SECTIONS, type ExportEnvelope, type ExportProfile, type ExportSection, type ExportedContext, type ExportedKeyFile, type FetchLike, type GitCommit, type GitState, HttpRelayStore, type HttpRelayStoreOptions, INGEST_SCHEMA_VERSION, type IngestArtifact, type IngestDoor, type IngestInput, type IngestResult, IngestStore, type IngestedSession, type JoinVaultOptions, type KdfParams, type KeyFile, type LoadConfigOptions, type LocalBlobSource, MASTER_KEY_BYTES, MIN_PASSPHRASE_LENGTH, type NotionConnectorOptions, type NotionPage, type OllamaSummarizerOptions, type ProLicenseInfo, type ProMemoryEntry, type ProModule, type ProUiApi, type ProUiFeatures, type RecoverVaultOptions, type RelayStore, type RenderedBehavior, type ResolvedConfig, type SaveSessionInput, type ServeTokenSpec, type ServerOptions, type SessionDigest, type SessionSyncPayload, SnapshotCache, type SnapshotInput, type SnapshotService, type Summarizer, type SyncBlobMeta, SyncClient, type SyncEntry, type SyncPayload, type SyncResult, type ThreadResolution, type ThreadSummary, type ThreadSyncPayload, TokenBudget, type UninstallResult, VERSION, type VaultConfig, type VaultMeta, type VaultView, assertPassphraseStrength, autoCaptureBlocked, buildContext, buildExportEnvelope, buildVaultView, clearBehaviorState, createNotionConnector, createOllamaSummarizer, createServer, createSnapshotService, createVault, decryptBlob, deriveBlobId, deriveMasterKey, detectHarnesses, encryptBlob, estimateTokens, fetchVaultMeta, fileConnector, filterScope, formatIngestErrors, fromBase64, generateRecoveryCode, generateSalt, gitConnector, inferHarnessFromClientName, ingestInputSchema, ingestSessionId, ingestSessionSchema, ingestSourceSchema, ingestToSessionDigest, inspectLicenseKey, installBehavior, isDeniedPath, joinVault, loadCanonicalBehaviors, loadConfig, loadProModule, loadVaultConfig, mergeIngestedSessions, normalizeRecoveryCode, openVaultSync, parseSyncPayload, readBehaviorState, recoverVault, redactContent, renderAllBehaviors, renderBehavior, renderExportMarkdown, renderThreadResume, resolveThread, saveSessionSchema, saveVaultConfig, scoreThreadMatch, sessionPayloadToIngestedSession, toBase64, truncateToTokens, uninstallBehavior, unlockVault, unwrapMasterKey, wrapMasterKey, writeBehaviorState, zeroKey };