@hyperdrive.bot/fleet-server 0.3.99

package/dist/server/server/agent/agent-stream-coalescer.js

@@ -0,0 +1,166 @@
+export const AGENT_STREAM_COALESCE_DEFAULT_WINDOW_MS = 60;
+function isCoalescableTimelineEvent(event) {
+    return (event.type === "timeline" &&
+        (event.item.type === "assistant_message" ||
+            event.item.type === "reasoning" ||
+            event.item.type === "tool_call"));
+}
+function isTextTimelineItem(item) {
+    return item.type === "assistant_message" || item.type === "reasoning";
+}
+function isTerminalToolCall(item) {
+    return (item.type === "tool_call" &&
+        (item.status === "completed" || item.status === "failed" || item.status === "canceled"));
+}
+export class AgentStreamCoalescer {
+    constructor(options) {
+        this.buffers = new Map();
+        this.windowMs = options.windowMs ?? AGENT_STREAM_COALESCE_DEFAULT_WINDOW_MS;
+        this.timers = options.timers;
+        this.onFlush = options.onFlush;
+    }
+    handle(agentId, event) {
+        if (!isCoalescableTimelineEvent(event)) {
+            return false;
+        }
+        if (isTextTimelineItem(event.item) && event.item.text === "") {
+            return true;
+        }
+        const buffer = this.getOrCreateBuffer(agentId);
+        this.appendToBuffer(buffer, event);
+        if (isTerminalToolCall(event.item)) {
+            this.flushBuffer(agentId);
+            return true;
+        }
+        if (!buffer.timer) {
+            this.scheduleFlush(buffer);
+        }
+        return true;
+    }
+    flushFor(agentId) {
+        this.flushBuffer(agentId);
+    }
+    flushAll() {
+        for (const agentId of Array.from(this.buffers.keys())) {
+            this.flushBuffer(agentId);
+        }
+    }
+    flushAndDiscard(agentId) {
+        this.flushBuffer(agentId);
+        const buffer = this.buffers.get(agentId);
+        if (buffer) {
+            this.clearTimer(buffer);
+            this.buffers.delete(agentId);
+        }
+    }
+    getOrCreateBuffer(agentId) {
+        const existing = this.buffers.get(agentId);
+        if (existing) {
+            return existing;
+        }
+        const buffer = {
+            agentId,
+            entries: [],
+            toolCallEntryIndexes: new Map(),
+            timer: null,
+            flushing: false,
+        };
+        this.buffers.set(agentId, buffer);
+        return buffer;
+    }
+    appendToBuffer(buffer, event) {
+        if (isTextTimelineItem(event.item)) {
+            buffer.entries.push({
+                kind: "text",
+                item: event.item,
+                text: event.item.text,
+                provider: event.provider,
+                ...(event.turnId !== undefined ? { turnId: event.turnId } : {}),
+            });
+            return;
+        }
+        const existingIndex = buffer.toolCallEntryIndexes.get(event.item.callId);
+        const entry = {
+            kind: "tool_call",
+            item: event.item,
+            provider: event.provider,
+            ...(event.turnId !== undefined ? { turnId: event.turnId } : {}),
+        };
+        if (existingIndex !== undefined) {
+            buffer.entries[existingIndex] = entry;
+            return;
+        }
+        buffer.toolCallEntryIndexes.set(event.item.callId, buffer.entries.length);
+        buffer.entries.push(entry);
+    }
+    scheduleFlush(buffer) {
+        const timer = this.timers.setTimeout(() => {
+            this.flushBuffer(buffer.agentId, buffer);
+        }, this.windowMs);
+        timer.unref?.();
+        buffer.timer = timer;
+    }
+    clearTimer(buffer) {
+        if (!buffer.timer) {
+            return;
+        }
+        this.timers.clearTimeout(buffer.timer);
+        buffer.timer = null;
+    }
+    flushBuffer(agentId, expectedBuffer) {
+        const buffer = this.buffers.get(agentId);
+        if (!buffer) {
+            return;
+        }
+        if (expectedBuffer && buffer !== expectedBuffer) {
+            return;
+        }
+        if (buffer.flushing) {
+            return;
+        }
+        this.clearTimer(buffer);
+        if (buffer.entries.length === 0) {
+            return;
+        }
+        const entries = buffer.entries;
+        buffer.entries = [];
+        buffer.toolCallEntryIndexes.clear();
+        buffer.flushing = true;
+        try {
+            for (const entry of this.collapseEntries(entries)) {
+                this.onFlush({
+                    agentId,
+                    item: entry.kind === "text"
+                        ? {
+                            ...entry.item,
+                            text: entry.text,
+                        }
+                        : entry.item,
+                    provider: entry.provider,
+                    ...(entry.turnId !== undefined ? { turnId: entry.turnId } : {}),
+                });
+            }
+        }
+        finally {
+            buffer.flushing = false;
+        }
+    }
+    collapseEntries(entries) {
+        const collapsed = [];
+        for (const entry of entries) {
+            const previous = collapsed.at(-1);
+            if (previous &&
+                previous.kind === "text" &&
+                entry.kind === "text" &&
+                previous.item.type === entry.item.type &&
+                previous.provider === entry.provider &&
+                previous.turnId === entry.turnId) {
+                previous.text += entry.text;
+                continue;
+            }
+            collapsed.push({ ...entry });
+        }
+        return collapsed;
+    }
+}
+//# sourceMappingURL=agent-stream-coalescer.js.map

package/dist/server/server/agent/agent-timeline-store-types.d.ts

@@ -0,0 +1,50 @@
+import type { AgentTimelineItem } from "./agent-sdk-types.js";
+export interface AgentTimelineRow {
+    seq: number;
+    timestamp: string;
+    item: AgentTimelineItem;
+}
+export interface AgentTimelineCursor {
+    epoch: string;
+    seq: number;
+}
+export type AgentTimelineFetchDirection = "tail" | "before" | "after";
+export interface AgentTimelineFetchOptions {
+    direction?: AgentTimelineFetchDirection;
+    cursor?: AgentTimelineCursor;
+    /**
+     * Number of canonical rows to return.
+     * - undefined: store default
+     * - 0: all rows in the selected window
+     */
+    limit?: number;
+}
+export interface AgentTimelineWindow {
+    minSeq: number;
+    maxSeq: number;
+    nextSeq: number;
+}
+export interface AgentTimelineFetchResult {
+    epoch: string;
+    direction: AgentTimelineFetchDirection;
+    reset: boolean;
+    staleCursor: boolean;
+    gap: boolean;
+    window: AgentTimelineWindow;
+    hasOlder: boolean;
+    hasNewer: boolean;
+    rows: AgentTimelineRow[];
+}
+export interface AgentTimelineStore {
+    appendCommitted(agentId: string, item: AgentTimelineItem, options?: {
+        timestamp?: string;
+    }): Promise<AgentTimelineRow>;
+    fetchCommitted(agentId: string, options?: AgentTimelineFetchOptions): Promise<AgentTimelineFetchResult>;
+    getLatestCommittedSeq(agentId: string): Promise<number>;
+    getCommittedRows(agentId: string): Promise<AgentTimelineRow[]>;
+    getLastItem(agentId: string): Promise<AgentTimelineItem | null>;
+    getLastAssistantMessage(agentId: string): Promise<string | null>;
+    deleteAgent(agentId: string): Promise<void>;
+    bulkInsert(agentId: string, rows: readonly AgentTimelineRow[]): Promise<void>;
+}
+//# sourceMappingURL=agent-timeline-store-types.d.ts.map

package/dist/server/server/agent/agent-timeline-store-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=agent-timeline-store-types.js.map

package/dist/server/server/agent/agent-timeline-store.d.ts

@@ -0,0 +1,27 @@
+import type { AgentTimelineItem } from "./agent-sdk-types.js";
+import type { AgentTimelineFetchOptions, AgentTimelineFetchResult, AgentTimelineRow } from "./agent-timeline-store-types.js";
+export interface SeedAgentTimelineOptions {
+    items?: readonly AgentTimelineItem[];
+    rows?: readonly AgentTimelineRow[];
+    epoch?: string;
+    nextSeq?: number;
+    timestamp?: string;
+}
+export declare class InMemoryAgentTimelineStore {
+    private readonly states;
+    has(agentId: string): boolean;
+    initialize(agentId: string, options?: SeedAgentTimelineOptions): void;
+    delete(agentId: string): void;
+    getItems(agentId: string): AgentTimelineItem[];
+    getRows(agentId: string): AgentTimelineRow[];
+    getEpoch(agentId: string): string;
+    fetch(agentId: string, options?: AgentTimelineFetchOptions): AgentTimelineFetchResult;
+    append(agentId: string, item: AgentTimelineItem, options?: {
+        timestamp?: string;
+    }): AgentTimelineRow;
+    getLastItem(agentId: string): AgentTimelineItem | null;
+    getLastAssistantMessage(agentId: string): string | null;
+    private requireState;
+    private buildRowsFromItems;
+}
+//# sourceMappingURL=agent-timeline-store.d.ts.map

package/dist/server/server/agent/agent-timeline-store.js

@@ -0,0 +1,277 @@
+import { randomUUID } from "node:crypto";
+const DEFAULT_TIMELINE_FETCH_LIMIT = 200;
+/**
+ * Byte ceiling for one timeline page, enforced ALONGSIDE the item-count limit.
+ *
+ * The count limit alone does not bound a page: a single tool result in a real
+ * transcript reaches 6.2 MB, so a "safe" 200-item page can still be tens of
+ * megabytes. A phone holds that whole payload before it renders a pixel, which
+ * is how the iOS client reached 65 MiB free and got watchdog-terminated
+ * (2026-07-30, Sentry devsquad-04/react-native REACT-NATIVE-2).
+ *
+ * 2 MiB is comfortably above a normal page (measured p50 message 1.4 KB, p99
+ * 42 KB, so a typical 200-item page is a few hundred KB) and bounds the tail.
+ */
+const MAX_TIMELINE_FETCH_BYTES = 2 * 1024 * 1024;
+function cloneRow(row) {
+    return { ...row };
+}
+function rowBytes(row) {
+    try {
+        return JSON.stringify(row.item)?.length ?? 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Trim a selected page to {@link MAX_TIMELINE_FETCH_BYTES}, dropping rows from
+ * the side FURTHEST from the cursor so the caller's `hasOlder` / `hasNewer`
+ * computation (which reads the first and last row of the returned array) stays
+ * correct without any extra bookkeeping.
+ *
+ * Always keeps at least one row: a single over-budget item must still make
+ * forward progress, otherwise pagination deadlocks on it forever.
+ *
+ * Sizing stops as soon as the budget is exceeded, so the pathological case
+ * serializes one oversized item rather than the whole page.
+ */
+function applyByteBudget(rows, keep, maxBytes = MAX_TIMELINE_FETCH_BYTES) {
+    if (rows.length <= 1)
+        return rows;
+    const ordered = keep === "newest" ? rows.toReversed() : rows;
+    const kept = [];
+    let total = 0;
+    for (const row of ordered) {
+        total += rowBytes(row);
+        if (kept.length > 0 && total > maxBytes)
+            break;
+        kept.push(row);
+    }
+    if (kept.length === rows.length)
+        return rows;
+    return keep === "newest" ? kept.toReversed() : kept;
+}
+function fetchTail(ctx) {
+    const { state, direction, limit, selectAll, minSeq, window } = ctx;
+    const selected = applyByteBudget(selectAll || limit >= state.rows.length
+        ? state.rows
+        : state.rows.slice(state.rows.length - limit), "newest");
+    return {
+        epoch: state.epoch,
+        direction,
+        reset: false,
+        staleCursor: false,
+        gap: false,
+        window,
+        hasOlder: selected.length > 0 && selected[0].seq > minSeq,
+        hasNewer: false,
+        rows: selected.map(cloneRow),
+    };
+}
+function fetchAfter(ctx) {
+    const { state, direction, limit, selectAll, cursor, minSeq, maxSeq, window } = ctx;
+    const baseSeq = cursor?.seq ?? 0;
+    const startIdx = state.rows.findIndex((row) => row.seq > baseSeq);
+    if (startIdx < 0) {
+        return {
+            epoch: state.epoch,
+            direction,
+            reset: false,
+            staleCursor: false,
+            gap: false,
+            window,
+            hasOlder: baseSeq >= minSeq,
+            hasNewer: false,
+            rows: [],
+        };
+    }
+    const selected = applyByteBudget(selectAll ? state.rows.slice(startIdx) : state.rows.slice(startIdx, startIdx + limit), "oldest");
+    const lastSelected = selected[selected.length - 1];
+    return {
+        epoch: state.epoch,
+        direction,
+        reset: false,
+        staleCursor: false,
+        gap: false,
+        window,
+        hasOlder: selected[0].seq > minSeq,
+        hasNewer: lastSelected !== null && lastSelected !== undefined && lastSelected.seq < maxSeq,
+        rows: selected.map(cloneRow),
+    };
+}
+function fetchBefore(ctx) {
+    const { state, direction, limit, selectAll, cursor, minSeq, window } = ctx;
+    const beforeSeq = cursor?.seq ?? state.nextSeq;
+    const endExclusive = state.rows.findIndex((row) => row.seq >= beforeSeq);
+    const boundedRows = endExclusive < 0 ? state.rows : state.rows.slice(0, endExclusive);
+    const selected = applyByteBudget(selectAll || limit >= boundedRows.length
+        ? boundedRows
+        : boundedRows.slice(boundedRows.length - limit), "newest");
+    return {
+        epoch: state.epoch,
+        direction,
+        reset: false,
+        staleCursor: false,
+        gap: false,
+        window,
+        hasOlder: selected.length > 0 && selected[0].seq > minSeq,
+        hasNewer: endExclusive >= 0,
+        rows: selected.map(cloneRow),
+    };
+}
+function fetchReset(ctx, flags) {
+    const { state, direction, limit, selectAll, minSeq, window } = ctx;
+    const rows = selectAll || limit >= state.rows.length
+        ? state.rows.map(cloneRow)
+        : state.rows.slice(state.rows.length - limit).map(cloneRow);
+    return {
+        epoch: state.epoch,
+        direction,
+        reset: true,
+        staleCursor: flags.staleCursor,
+        gap: flags.gap,
+        window,
+        hasOlder: rows.length > 0 && rows[0].seq > minSeq,
+        hasNewer: false,
+        rows,
+    };
+}
+export class InMemoryAgentTimelineStore {
+    constructor() {
+        this.states = new Map();
+    }
+    has(agentId) {
+        return this.states.has(agentId);
+    }
+    initialize(agentId, options) {
+        const timestamp = options?.timestamp ?? new Date().toISOString();
+        const rows = options?.rows?.length
+            ? options.rows.map(cloneRow)
+            : this.buildRowsFromItems(options?.items ?? [], options?.nextSeq ?? 1, timestamp);
+        const nextSeq = options?.nextSeq ?? (rows.length ? rows[rows.length - 1].seq + 1 : 1);
+        this.states.set(agentId, {
+            epoch: options?.epoch ?? randomUUID(),
+            rows,
+            nextSeq,
+        });
+    }
+    delete(agentId) {
+        this.states.delete(agentId);
+    }
+    getItems(agentId) {
+        return this.requireState(agentId).rows.map((row) => row.item);
+    }
+    getRows(agentId) {
+        return this.requireState(agentId).rows.map(cloneRow);
+    }
+    getEpoch(agentId) {
+        return this.requireState(agentId).epoch;
+    }
+    fetch(agentId, options) {
+        const state = this.requireState(agentId);
+        const direction = options?.direction ?? "tail";
+        const requestedLimit = options?.limit;
+        const limit = requestedLimit === undefined
+            ? DEFAULT_TIMELINE_FETCH_LIMIT
+            : Math.max(0, Math.floor(requestedLimit));
+        const cursor = options?.cursor;
+        const minSeq = state.rows.length ? state.rows[0].seq : 0;
+        const maxSeq = state.rows.length ? state.rows[state.rows.length - 1].seq : 0;
+        const selectAll = limit === 0;
+        const window = {
+            minSeq,
+            maxSeq,
+            nextSeq: state.nextSeq,
+        };
+        const ctx = {
+            state,
+            direction,
+            limit,
+            selectAll,
+            cursor,
+            minSeq,
+            maxSeq,
+            window,
+        };
+        if (cursor && typeof cursor.epoch === "string" && cursor.epoch !== state.epoch) {
+            return fetchReset(ctx, { staleCursor: true, gap: false });
+        }
+        if (direction === "after" && cursor && state.rows.length > 0 && cursor.seq < minSeq - 1) {
+            return fetchReset(ctx, { staleCursor: false, gap: true });
+        }
+        if (state.rows.length === 0) {
+            return {
+                epoch: state.epoch,
+                direction,
+                reset: false,
+                staleCursor: false,
+                gap: false,
+                window,
+                hasOlder: false,
+                hasNewer: false,
+                rows: [],
+            };
+        }
+        if (direction === "tail") {
+            return fetchTail(ctx);
+        }
+        if (direction === "after") {
+            return fetchAfter(ctx);
+        }
+        return fetchBefore(ctx);
+    }
+    append(agentId, item, options) {
+        const state = this.requireState(agentId);
+        const row = {
+            seq: state.nextSeq,
+            timestamp: options?.timestamp ?? new Date().toISOString(),
+            item,
+        };
+        state.nextSeq += 1;
+        state.rows.push(row);
+        return cloneRow(row);
+    }
+    getLastItem(agentId) {
+        const state = this.requireState(agentId);
+        return state.rows[state.rows.length - 1]?.item ?? null;
+    }
+    getLastAssistantMessage(agentId) {
+        const rows = this.requireState(agentId).rows;
+        const chunks = [];
+        for (let i = rows.length - 1; i >= 0; i -= 1) {
+            const item = rows[i].item;
+            if (item.type !== "assistant_message") {
+                if (chunks.length > 0) {
+                    break;
+                }
+                continue;
+            }
+            chunks.push(item.text);
+        }
+        if (chunks.length === 0) {
+            return null;
+        }
+        return chunks.toReversed().join("");
+    }
+    requireState(agentId) {
+        const state = this.states.get(agentId);
+        if (!state) {
+            throw new Error(`Unknown agent '${agentId}'`);
+        }
+        return state;
+    }
+    buildRowsFromItems(items, startSeq, timestamp) {
+        let nextSeq = startSeq;
+        return items.map((item) => {
+            const row = {
+                seq: nextSeq,
+                timestamp,
+                item,
+            };
+            nextSeq += 1;
+            return row;
+        });
+    }
+}
+//# sourceMappingURL=agent-timeline-store.js.map

package/dist/server/server/agent/audio-utils.d.ts

@@ -0,0 +1,3 @@
+export declare function inferAudioExtension(format: string | undefined): string;
+export declare function sanitizeForFilename(segment: string | undefined, fallback: string): string;
+//# sourceMappingURL=audio-utils.d.ts.map

package/dist/server/server/agent/audio-utils.js

@@ -0,0 +1,19 @@
+const AUDIO_EXTENSIONS = [
+    { match: (format) => format.includes("webm"), ext: "webm" },
+    { match: (format) => format.includes("ogg"), ext: "ogg" },
+    { match: (format) => format.includes("mp3"), ext: "mp3" },
+    { match: (format) => format.includes("wav"), ext: "wav" },
+    { match: (format) => format.includes("m4a") || format.includes("aac"), ext: "m4a" },
+    { match: (format) => format.includes("mp4"), ext: "mp4" },
+    { match: (format) => format.includes("flac"), ext: "flac" },
+];
+export function inferAudioExtension(format) {
+    const normalized = (format || "webm").toLowerCase();
+    const candidate = AUDIO_EXTENSIONS.find((entry) => entry.match(normalized));
+    return candidate?.ext ?? "webm";
+}
+export function sanitizeForFilename(segment, fallback) {
+    const value = segment && segment.length > 0 ? segment : fallback;
+    return value.replace(/[^a-zA-Z0-9-_]/g, "_").slice(0, 64);
+}
+//# sourceMappingURL=audio-utils.js.map

package/dist/server/server/agent/authorship-ledger.d.ts

@@ -0,0 +1,139 @@
+import type { Logger } from "pino";
+/**
+ * Append-only human-authorship ledger.
+ *
+ * Why this exists: paseo stores session METADATA only. Conversation text lives
+ * in the provider's store, joined through `runtimeInfo.sessionId`. A provider
+ * transcript record knows a message came from `human`; it has no idea WHICH
+ * human, because until now there has only ever been one principal per daemon.
+ *
+ * Paseo is therefore the only component that observes the human and the message
+ * in the same instant. If it does not stamp authorship there, the fact is
+ * destroyed and no later migration recovers it.
+ *
+ * It is PROSPECTIVE ONLY, which is why it ships ahead of the authorization work
+ * it eventually feeds: authorization can land later and lose nothing, whereas
+ * every day without this ledger is a day of permanently unattributable history.
+ *
+ * Today `principalId` resolves to this daemon's single local principal, because
+ * daemon-side identity does not exist yet (`packages/server`, `packages/relay`
+ * and `packages/protocol` carry no `principal` concept). That is deliberate:
+ * the key is STABLE and OPAQUE, never a display name, so mapping it to a real
+ * per-user identity later is a JOIN rather than a break in history.
+ *
+ * Durability model: newline-delimited JSON appended to a single file under
+ * $PASEO_HOME, mirroring {@link CardMoveLog}. Append is atomic enough here
+ * (single writer process, one `appendFileSync` per row, rows far below
+ * PIPE_BUF), and a torn final line is tolerated by the reader rather than being
+ * allowed to poison a read.
+ *
+ * Full design: super-repo `docs/architecture/paseo-multiplayer/ARCHITECTURE.md` §4.
+ */
+/** Current row schema version. Bump when the shape changes; readers must tolerate older rows. */
+export declare const AUTHORSHIP_ROW_VERSION = 1;
+export interface AuthorshipRow {
+    /** Row schema version, so rows written today stay readable after the shape evolves. */
+    v: number;
+    /** Paseo agent id the turn belongs to. */
+    agentId: string;
+    /**
+     * Paseo turn id. This is the ordinal: it is the real, stable identity of a
+     * human turn in paseo's own model, which a synthetic counter would only
+     * approximate.
+     */
+    turnId: string;
+    /**
+     * Provider session id (`persistence.sessionId`), the join key out to the
+     * transcript text. Null when the turn starts before the session is persisted.
+     */
+    sessionId: string | null;
+    /** Stable opaque principal key. NEVER a display name. */
+    principalId: string;
+    /** ISO timestamp of submission. */
+    at: string;
+}
+export interface AuthorshipLedgerOptions {
+    /** Directory to write into, normally $PASEO_HOME. */
+    dir: string;
+    logger: Logger;
+    /** Stable opaque principal key for this daemon. See {@link resolveLocalPrincipal}. */
+    principalId: string;
+    /** Test seam. Defaults to `() => new Date()`. */
+    now?: () => Date;
+}
+export declare class AuthorshipLedger {
+    private readonly filePath;
+    private readonly logger;
+    private readonly principalId;
+    private readonly now;
+    private ensured;
+    constructor(options: AuthorshipLedgerOptions);
+    /**
+     * Record that a human started a turn.
+     *
+     * NEVER throws. A user's turn must not fail because bookkeeping failed. The
+     * reason is always written to the logger, so a silently-dead ledger is
+     * greppable instead of indistinguishable from a legitimate no-op.
+     */
+    record(params: {
+        agentId: string;
+        turnId: string;
+        sessionId?: string | null;
+    }): void;
+    /** All rows, oldest first. Returns [] when the ledger does not exist yet. */
+    readAll(): AuthorshipRow[];
+    /** Rows for one agent, oldest first. */
+    history(agentId: string): AuthorshipRow[];
+    /**
+     * Distinct principals that have taken a turn on this agent, in first-seen
+     * order. This is what a "filter sessions by participant" facet reads.
+     */
+    participants(agentId: string): string[];
+    private ensureDir;
+}
+/**
+ * Environment variable that turns authorship recording on.
+ *
+ * The feature is OFF BY DEFAULT and only the exact string "true" enables it.
+ * Deliberately strict: "1", "yes" and "TRUE" all leave it off, because a
+ * recording feature that switches itself on from a near-miss value is a
+ * privacy surprise, and every other paseo opt-in uses this same `=== "true"`
+ * shape (see MULTI_TENANT_ENABLED in the app).
+ */
+export declare const AUTHORSHIP_ENV_FLAG = "PASEO_AUTHORSHIP_ENABLED";
+export interface CreateAuthorshipLedgerOptions {
+    /** Directory to write into, normally $PASEO_HOME. */
+    dir: string;
+    logger: Logger;
+    /** Raw env value, normally `process.env.PASEO_AUTHORSHIP_ENABLED`. */
+    flag: string | undefined;
+    /** Test seam. Defaults to `() => new Date()`. */
+    now?: () => Date;
+}
+/**
+ * Build the ledger, or return undefined when the feature is off.
+ *
+ * Returning undefined IS the kill switch: `AgentManager` holds the ledger
+ * optionally and calls it as `this.authorshipLedger?.record(...)`, so a
+ * disabled build allocates nothing, touches no disk, and adds no branch to the
+ * turn path.
+ *
+ * Also returns undefined when the flag is on but no stable principal key can be
+ * persisted. Rows attributed to an identity that changes every restart look
+ * like history and are not, which is worse than having no rows.
+ */
+export declare function createAuthorshipLedger(options: CreateAuthorshipLedgerOptions): AuthorshipLedger | undefined;
+/**
+ * Read or create this daemon's stable principal key at `$PASEO_HOME/principal-id`.
+ *
+ * The value is an opaque UUID and is NEVER a display name: a rename must not
+ * fork a person's history, and the eventual per-user identity mapping has to be
+ * a join onto this key. Written 0600 because it will become identity-bearing.
+ *
+ * Returns null if the key can neither be read nor created, which disables
+ * recording rather than inventing an unstable per-boot identity. A ledger of
+ * rows attributed to a principal that changes every restart is worse than no
+ * ledger, because it looks like history and is not.
+ */
+export declare function resolveLocalPrincipal(dir: string, logger: Logger): string | null;
+//# sourceMappingURL=authorship-ledger.d.ts.map