@yanlinglabs/winter-agent-runtime 0.0.27

package/dist/store/dialect.d.ts

@@ -0,0 +1,526 @@
+import type { RuntimeConfig } from "@yanlinglabs/winter-agent-sdk";
+import { type SessionKey, type SessionStore, type SessionStoreEntry } from "@yanlinglabs/winter-agent-sdk";
+import type { ContentBlock, ProviderMessage, SessionPersistence } from "../engine.js";
+import type { CompactBoundaryRecord, CompactBoundaryWriteResult } from "../compaction/seam.js";
+import { type DurableApprovalStore } from "../permissions/approvals.js";
+import { type AutoCounterStore } from "../permissions/auto/caches.js";
+import { type ProviderStateRecord, type ProviderStateRecordInput } from "./provider-state.js";
+export interface ProviderStateSink {
+    append(input: ProviderStateRecordInput): Promise<ProviderStateRecord>;
+    load(): Promise<ProviderStateRecord[]>;
+}
+/** The neighbour-file sink: `<sessionId>.provider-state.jsonl`, 0600, append-only, fsync per record. */
+export declare function createFileProviderStateSink(sidecarPath: string): ProviderStateSink;
+/**
+ * The external-store sink. Records ride the `provider-state` subkey as ordinary `SessionStoreEntry`s.
+ *
+ * `load()` reads THAT KEY DIRECTLY and never calls `listSubkeys`: the method is optional on the
+ * pinned `SessionStore` and, when a host's adapter omits it, resume materialises only the main
+ * transcript -- so a chain discovered by enumeration is a chain that silently vanishes for half the
+ * hosts that could implement this interface.
+ */
+export declare function createStoreProviderStateSink(store: SessionStore, key: {
+    projectKey: string;
+    sessionId: string;
+}): ProviderStateSink;
+/**
+ * R6-9 / WS-16 §4: the resolved provider identity a dialect record carries, so a resumed session can
+ * be told WHICH provider produced it without re-resolving.
+ *
+ * `authRefKind` is the credential ref's KIND and nothing else. R6-10 makes credential material a host
+ * responsibility that the SDK never persists, and this record is durable session state -- the kind is
+ * what a later reader needs ("this session authenticated from the keychain"), the material is what it
+ * must never find.
+ */
+export interface DialectProviderIdentity {
+    providerId: string;
+    modelKey: string;
+    /**
+     * WIDENED in review round 1 (I1): the four catalog/credential fields are OPTIONAL.
+     *
+     * The engine must be able to write an identity block from whatever it has -- and what it has is
+     * whatever its caller resolved. Requiring all four forced the alternative of fabricating
+     * `"unknown"` strings, which would put a claim in durable session state that nothing verified.
+     * `providerId`/`modelKey` stay required because they are what makes the block an IDENTITY at all,
+     * and they are what the resume side reads to tell "this session had provider state" from "this
+     * session predates the concept".
+     */
+    adapterId?: string;
+    adapterVersion?: string;
+    catalogVersion?: string;
+    authRefKind?: string;
+    /** R6-14: the classifier identity PINNED by the session's first successful classification. */
+    classifierPin?: string;
+}
+/** One entry of the dialect record's `providerHistory` (R6-C: a swap is recorded, not only framed). */
+export interface DialectProviderSwitch {
+    from: string;
+    to: string;
+    reason: "fallback" | "set_model" | "interrupt";
+}
+export type Block = ContentBlock;
+export interface Chain {
+    parentUuid: string | null;
+}
+export interface SessionCtx {
+    sessionId: string;
+    cwd: string;
+    version: string;
+    projectDirName?: string;
+}
+export interface DialectEntryBase {
+    type: string;
+    uuid: string;
+    parentUuid: string | null;
+    sessionId: string;
+    timestamp: string;
+    cwd: string;
+    version: string;
+    isSidechain: boolean;
+    [k: string]: unknown;
+}
+export interface SidechainStamp {
+    agentId: string;
+    parentToolUseId: string;
+}
+export type UserEntryOpts = {
+    chain: Chain;
+    ctx: SessionCtx;
+    sidechain?: SidechainStamp;
+    meta?: {
+        isMeta?: boolean;
+        origin?: {
+            kind: string;
+            [k: string]: unknown;
+        };
+    };
+} & ({
+    text: string;
+} | {
+    content: Block[];
+});
+export declare function userEntry(opts: UserEntryOpts): DialectEntryBase & {
+    type: "user";
+    message: {
+        role: "user";
+        content: string | Block[];
+    };
+};
+export declare function winterMessageIdFor(uuid: string): string;
+export declare function assistantEntry(opts: {
+    content: Block[];
+    chain: Chain;
+    ctx: SessionCtx;
+    sidechain?: SidechainStamp;
+    /**
+     * Phase 6 Task 3 (R6-7): the PRE-ALLOCATED entry uuid.
+     *
+     * `baseFields` mints one unconditionally, which is exactly what write-ahead ordering cannot live
+     * with: the sidecar record has to name the entry's uuid BEFORE the entry exists, so the engine
+     * mints it and passes it down. Omitted by every pre-P6 caller -- the entry is then byte-identical
+     * to before this task.
+     */
+    uuid?: string;
+    /**
+     * WS-23: claude's own assistant-entry fields, verbatim names -- `effort` is the top-level effort the
+     * request sent, `perTurnEffort` the level in force for the turn (they differ only under per-message
+     * effort). TOP-LEVEL entry fields, exactly where claude 2.1.282 writes them; spread conditionally so
+     * an entry written without them stays byte-identical (the goldens compare whole entries).
+     */
+    effort?: string;
+    perTurnEffort?: string;
+}): DialectEntryBase & {
+    type: "assistant";
+    message: {
+        id: string;
+        type: "message";
+        role: "assistant";
+        content: Block[];
+    };
+};
+export declare const COMPACT_SUMMARY_ENTRY_TYPE = "compact_summary";
+export declare const COMPACT_BOUNDARY_ENTRY_TYPE = "compact_boundary";
+export interface CompactMetadata {
+    trigger: "manual" | "auto";
+    pre_tokens: number;
+    post_tokens?: number;
+    duration_ms?: number;
+    preserved_messages?: {
+        anchor_uuid: string;
+        uuids: string[];
+    };
+}
+export declare function compactSummaryEntry(opts: {
+    summary: string;
+    chain: Chain;
+    ctx: SessionCtx;
+    sidechain?: SidechainStamp;
+}): DialectEntryBase & {
+    type: "compact_summary";
+    message: {
+        role: "user";
+        content: string;
+    };
+};
+export declare function compactBoundaryEntry(opts: {
+    metadata: CompactMetadata;
+    chain: Chain;
+    ctx: SessionCtx;
+    sidechain?: SidechainStamp;
+}): DialectEntryBase & {
+    type: "compact_boundary";
+    compact_metadata: CompactMetadata;
+};
+export declare const CLAUDE_COMPACT_SUMMARY_PREAMBLE = "This session is being continued from a previous conversation that ran out of context. The summary below covers the earlier portion of the conversation.";
+/**
+ * Fix round 1 (controller ruling, LOAD-BEARING): the live engine's in-memory history and a cold
+ * resume's rebuilt history must never diverge after a compaction. `recordCompactBoundary` below
+ * computes exactly which conversational uuids the live run retained (`preserved`) -- omitting them
+ * from the persisted boundary (as the original P10b-7 comment here did) meant the LIVE session kept
+ * seeing its retained tail for the rest of that run while a COLD RESUME rebuilt only the summary,
+ * silently losing that tail forever the instant the process restarted. `anchorUuid`/`uuids` and their
+ * ordering are byte-exact to the real capture (`conformance/goldens/claude-2.1.250/compaction.jsonl`)
+ * -- `anchorUuid` names the summary (the entries in `uuids` relink AFTER it, never before), which is
+ * also exactly the retained set's own natural anchor: the summary IS the first surviving entry.
+ */
+export interface ClaudeCompactPreservedMessages {
+    anchorUuid: string;
+    uuids: string[];
+}
+export interface ClaudeCompactMetadata {
+    trigger: "manual" | "auto";
+    preTokens: number;
+    postTokens?: number;
+    durationMs?: number;
+    preservedMessages?: ClaudeCompactPreservedMessages;
+}
+/**
+ * The boundary half of Claude's native compaction shape (W18-12). A SECOND `parentUuid: null` root
+ * BY DESIGN (I-5 is worded to allow exactly this) -- `logicalParentUuid` is the backward-looking link
+ * to the pre-compaction leaf, which is what lets a transcript reader (and claude itself) find where
+ * the cut happened without the boundary sitting IN the chain it cuts.
+ */
+export declare function claudeCompactBoundaryEntry(opts: {
+    trigger: "manual" | "auto";
+    preTokens: number;
+    postTokens?: number;
+    durationMs?: number;
+    /** The pre-compaction chain's own leaf uuid -- never this entry's OWN chain parent (that is always `null`). */
+    logicalParentUuid: string;
+    /**
+     * Fix round 1: OMITTED entirely (never an empty `{uuids: []}`) when nothing was retained --
+     * absence stays semantic ("compaction summarized everything"), matching the golden and the reader
+     * (`resume.ts`) both.
+     */
+    preservedMessages?: ClaudeCompactPreservedMessages;
+    ctx: SessionCtx;
+}): DialectEntryBase & {
+    type: "system";
+    subtype: "compact_boundary";
+    content: "Conversation compacted";
+    level: "info";
+    logicalParentUuid: string;
+    compactMetadata: ClaudeCompactMetadata;
+};
+/**
+ * The summary half: a CONVERSATIONAL `user` entry (it carries a `message`, unlike the boundary),
+ * parented ON the boundary -- `resume.ts`'s ancestry walk stops at the boundary's own `null` parent,
+ * so this is the first entry a resumed lineage actually rebuilds into provider history.
+ */
+export declare function claudeCompactSummaryEntry(opts: {
+    summary: string;
+    boundaryUuid: string;
+    ctx: SessionCtx;
+    /**
+     * Fix round 1: a PRE-ALLOCATED entry uuid, mirroring `assistantEntry`'s own write-ahead pattern
+     * (R6-7). `recordCompactBoundary` needs the summary's uuid to name it as the boundary's OWN
+     * `compactMetadata.preservedMessages.anchorUuid` -- but the boundary is written FIRST (W18-12's
+     * order) -- so it mints this uuid before either entry exists and passes it to both. Omitted ->
+     * a fresh uuid is minted here, byte-identical to every pre-fix-round-1 caller.
+     */
+    uuid?: string;
+}): DialectEntryBase & {
+    type: "user";
+    message: {
+        role: "user";
+        content: string;
+    };
+    isCompactSummary: true;
+    isVisibleInTranscriptOnly: true;
+};
+/** Lane S's `invoked_skills` (skills/attachment.ts) -- the one authority on the payload shape. */
+export declare const INVOKED_SKILLS_ENTRY_TYPE = "invoked_skills";
+/**
+ * Lane K's checkpoint records (checkpoint/file-history.ts's `CheckpointRecord`), one entry per
+ * intercepted mutation.
+ *
+ * WHAT THIS DOES AND DOES NOT CHANGE, stated plainly because rider 16 asks for more than this
+ * lands. Lane K's concern 1 named ONE cost of the private sidecar: "a transcript reader cannot see
+ * that a rewind is possible". That cost is what this closes -- the record is now visible to anyone
+ * reading the session's own transcript. `<home>/backups/<session>/index.jsonl` REMAINS the rewind's
+ * read authority, and rider 16's "retire the sidecar" half is NOT done. Two concrete blockers, both
+ * behavioural rather than cosmetic:
+ *
+ *   1. SCOPING -- CORRECTED IN THE FIX WAVE (B-M2). This used to say the seam's `req.sessionUuid`
+ *      is "how a child engine's edits land in the CHILD's subtree", and that routing records through
+ *      the sink's single parent `SessionPersistence` would move them into the parent's. Both halves
+ *      were wrong, and checking beats reasoning here:
+ *
+ *        * A CHILD HAS NO SINK AT ALL. `fileCheckpointSink` is in `production-wiring.ts`'s
+ *          `engineOptions` and NOT in its `childFactoryOptions`, so in a child engine it is
+ *          `undefined` and the `beforeMutation` call site never runs. There are no child records to
+ *          misroute.
+ *        * AND IF THERE WERE, `sessionUuid` WOULD NOT SEPARATE THEM. The engine stamps
+ *          `sessionUuid: config.sessionId`, and a child's `config.sessionId` IS the owning parent's
+ *          (`runCtx.parentSessionId` -- Phase 4's I1, deliberate, and every session-keyed registry
+ *          downstream reads it that way). The seam field the old text called the scoping mechanism
+ *          carries the parent's identity in both engines.
+ *
+ *      So the real blocker is the inverse of the one recorded: giving children a sink needs a
+ *      scoping key that DOES distinguish them (the `agentId`, which `childTranscriptSubpath` already
+ *      uses for the child's own transcript) before any routing question arises at all.
+ *   2. THE READ PATH. `rewindToCheckpoint` is synchronous and reads `index.jsonl` next to the blobs
+ *      it names; `SessionPersistence` is an append-only write sink with no read surface at all, and
+ *      the store's own reader is async.
+ *
+ * So the two are deliberately asymmetric and each says what it is: the transcript entry is the
+ * READABLE record, the sidecar is the OPERATIONAL index co-located with the blobs. Nothing reads the
+ * transcript entry for behaviour, which is what keeps this from being a second producer of a
+ * consumed value -- it is the same shape `recordHookAudit` already has.
+ */
+export declare const FILE_HISTORY_ENTRY_TYPE_BY_KIND: {
+    readonly snapshot: "file-history-snapshot";
+    readonly delta: "file-history-delta";
+};
+/** Lane K's `CheckpointRecord`, verbatim -- this module never reshapes it. */
+export interface FileHistoryEntryPayload {
+    kind: "snapshot" | "delta";
+    userMessageUuid: string;
+    path: string;
+    pathHash: string;
+    tool: string;
+    at: string;
+    version: number;
+    absent?: boolean;
+    parentRealPath?: string;
+    anchorPath?: string;
+    anchorRealPath?: string;
+}
+export declare function invokedSkillsEntry(opts: {
+    attachment: {
+        type: string;
+        skills: unknown[];
+    };
+    chain: Chain;
+    ctx: SessionCtx;
+    sidechain?: SidechainStamp;
+}): DialectEntryBase & {
+    type: "invoked_skills";
+    skills: unknown[];
+};
+/**
+ * SDK 0.0.16 (P16-5/P16-6): claude 0.3.250's persisted ATTACHMENT entry --
+ * `{type: "attachment", attachment: {type, ...payload}, uuid, parentUuid, ...}`, captured from the
+ * pinned binary's own transcript. No `message` field: the model-facing text is rendered from the
+ * payload on resume (store/resume.ts, through context/attachments.ts), exactly as claude does.
+ */
+export declare const ATTACHMENT_ENTRY_TYPE = "attachment";
+export declare function attachmentEntry(opts: {
+    attachment: {
+        type: string;
+        [key: string]: unknown;
+    };
+    chain: Chain;
+    ctx: SessionCtx;
+    sidechain?: SidechainStamp;
+}): DialectEntryBase & {
+    type: "attachment";
+    attachment: {
+        type: string;
+        [key: string]: unknown;
+    };
+};
+export declare function fileHistoryEntry(opts: {
+    record: FileHistoryEntryPayload;
+    chain: Chain;
+    ctx: SessionCtx;
+    sidechain?: SidechainStamp;
+}): DialectEntryBase & {
+    type: string;
+    file_history: FileHistoryEntryPayload;
+};
+export declare class TranscriptWriterError extends Error {
+    constructor(message: string);
+}
+export interface TranscriptWriterOptions {
+    store: SessionStore;
+    key: SessionKey;
+    ctx: SessionCtx;
+    initialParentUuid?: string | null;
+    sidechain?: SidechainStamp;
+    initialConversationalUuids?: readonly string[];
+    /**
+     * Phase 6 Task 3 (R6-7): where this session's provider-state records go. Omitted -> the session
+     * keeps an IN-MEMORY chain only, which is the honest state for a writer with no durable home for
+     * one (and byte-identical to every pre-P6 writer).
+     */
+    providerStateSink?: ProviderStateSink;
+}
+export declare class TranscriptWriter implements SessionPersistence {
+    private readonly store;
+    private readonly key;
+    private readonly ctx;
+    private readonly sidechain;
+    private parentUuid;
+    private readonly conversationalUuids;
+    private readonly providerStateSink;
+    private providerIdentity;
+    private readonly providerHistory;
+    constructor(opts: TranscriptWriterOptions);
+    recordUserEntry(content: string | Block[], opts?: {
+        isMeta?: boolean;
+        origin?: {
+            kind: string;
+            [k: string]: unknown;
+        };
+    }): Promise<void>;
+    recordAssistantEntry(content: Block[], opts?: {
+        uuid?: string;
+        effort?: string;
+        perTurnEffort?: string;
+    }): Promise<void>;
+    /**
+     * SDK 0.0.16: one persisted attachment. It is CONVERSATIONAL -- it is a message in the engine's
+     * history -- so it is tracked with the user/assistant entries, which keeps a compaction boundary's
+     * preserved-message uuids aligned with the retained history.
+     */
+    recordAttachmentEntry(attachment: {
+        type: string;
+        [key: string]: unknown;
+    }): Promise<void>;
+    /**
+     * Appends one sidecar record. Called BEFORE `recordAssistantEntry` for the same `anchorUuid`.
+     *
+     * A writer with no sink (a bare test fixture, a store shape with nowhere to put it) records
+     * nothing and says so by returning `undefined` -- never an error, matching the whole seam's
+     * "entirely optional" contract. The chain is then in-memory only for that run.
+     */
+    recordProviderState(record: ProviderStateRecordInput): Promise<void>;
+    loadProviderState(): Promise<ProviderStateRecord[]>;
+    /**
+     * Review round 1 (I1): did THIS session ever record a provider identity?
+     *
+     * The one question that separates R6-7's two indistinguishable-looking resumes. A session with no
+     * records could be pre-P6 (nothing to degrade from, resume silently) or one whose sidecar was
+     * DELETED (every message degraded, and the user deserves to be told). The identity block is the
+     * marker that tells them apart, and it lives in the summary sidecar because that is where the
+     * store folds every dialect record.
+     *
+     * Read through the store's OWN per-session reader rather than by re-deriving the summary path here:
+     * this writer already holds the key the store resolves paths from, and a second path derivation is
+     * the drift `providerStateSidecarPath` exists to avoid.
+     *
+     * `readSessionSummary` is a Winter-only capability on the concrete store, reached through a LOCAL
+     * intersection type so the pinned six-member `SessionStore` surface stays untouched (the same
+     * pattern `resume.ts` uses for `listProjectKeys`). It replaces a `listSessionSummaries` scan that
+     * read and parsed EVERY summary in the project directory -- O(#sessions) on every resume, paid by
+     * the busiest projects (review round 2, M2). A store without it degrades to `undefined`, which
+     * reads as "unknown" and keeps the resume silent rather than guessing.
+     */
+    loadProviderIdentity(): Promise<{
+        providerId: string;
+        modelKey: string;
+    } | undefined>;
+    /**
+     * R6-9: the resolved provider identity every subsequent dialect record carries.
+     *
+     * SET, not appended: the identity is the session's CURRENT one, and `appendWithDialectRecord`'s
+     * own stateless/self-healing contract means the freshest value simply wins on the next append.
+     * A model swap is recorded separately, in `providerHistory`, because that is a HISTORY and
+     * overwriting it would erase the very thing it exists to preserve.
+     */
+    setProviderIdentity(identity: DialectProviderIdentity): void;
+    /** R6-C: records a model swap in the dialect record's `providerHistory`, alongside the Winter-only `system/model_switch` frame the engine emits. */
+    recordProviderSwitch(entry: DialectProviderSwitch): void;
+    /**
+     * Appends the dialect record ALONE -- no transcript entry beside it.
+     *
+     * The store partitions `DIALECT_RECORD_ENTRY_TYPE` out of the jsonl by construction and folds its
+     * fields into the summary sidecar, and `append()` explicitly allows a batch with zero native
+     * entries. So this writes the identity block and nothing else, which is exactly what a FORK needs:
+     * its transcript is already a byte-for-byte copy of the source's, and re-appending an entry to
+     * carry the block would corrupt the chain it just copied (review round 2, M3).
+     */
+    stampDialectRecord(): Promise<void>;
+    private trackConversational;
+    recordCompactBoundary(record: CompactBoundaryRecord): Promise<CompactBoundaryWriteResult>;
+    /**
+     * Phase 5 Task 8 (rider 16): Lane S's `invoked_skills` attachment, as a real transcript entry.
+     *
+     * Lane S's NEEDS_CONTEXT 1: the payload went to `SkillSessionRuntime.onInvoked`, a HOST sink, and
+     * with no entry the record existed only for as long as the host chose to keep it. Nothing else
+     * about the payload changes -- `skills/attachment.ts` is still its one producer.
+     */
+    recordInvokedSkills(attachment: {
+        type: string;
+        skills: unknown[];
+    }): Promise<void>;
+    /**
+     * Phase 5 Task 8 (riders 9/16): one checkpoint record, as a transcript entry. See
+     * `FILE_HISTORY_ENTRY_TYPE_BY_KIND`'s own header for exactly what this closes and what it does
+     * NOT (the sidecar remains the rewind's read authority).
+     */
+    recordFileHistory(record: FileHistoryEntryPayload): Promise<void>;
+    writeMetadata(metadata: Record<string, unknown>): Promise<void>;
+    flush(): Promise<void>;
+    private appendWithDialectRecord;
+    /** The dialect record this writer stamps beside every append. Factored out so the fork path can write it ALONE (`stampDialectRecord`). */
+    private dialectRecord;
+    static readBack(store: SessionStore, key: SessionKey): Promise<SessionStoreEntry[]>;
+}
+export declare const RUNTIME_ENGINE_VERSION = "0.0.27";
+export interface ResolvedEngineSession {
+    config: RuntimeConfig;
+    store: SessionPersistence | undefined;
+    initialMessages: ProviderMessage[];
+    approvalStore?: DurableApprovalStore;
+    autoStateStore?: AutoCounterStore;
+}
+export declare function childTranscriptSubpath(agentId: string): string;
+export interface ChildTranscriptWriterOptions {
+    store: SessionStore;
+    projectKey: string;
+    parentSessionId: string;
+    agentId: string;
+    parentToolUseId: string;
+    cwd: string;
+    /** Phase 6 Task 3 (R6-7): the resolved winter root, so the child's provider-state sidecar can be located beside the child's own transcript. Omitted -> that child keeps an in-memory chain only. */
+    winterHome?: string;
+}
+export declare function buildChildTranscriptWriter(opts: ChildTranscriptWriterOptions): TranscriptWriter;
+export declare function listChildAgentIds(store: SessionStore, key: {
+    projectKey: string;
+    sessionId: string;
+}): Promise<string[]>;
+export declare function resolveEngineSession(opts: {
+    config: RuntimeConfig;
+    resolveWinterHome: () => string;
+    /**
+     * WS-21 §3.7/§6.3 item 3 (durable-write audit, fix round 2): the shared STORE home, when this
+     * incarnation has one -- called ONLY when persistence is active, same discipline as
+     * `resolveWinterHome`'s own thunk (a caller that wants "never touch the real environment unless a
+     * session actually persists" must be able to defer this too). Every durable write this function
+     * makes (the transcript store, the provider-state sidecar, the permission journal, the approval
+     * store, the auto-counter store) anchors on THIS value, never on `resolveWinterHome`'s own return
+     * -- `winterHome` is the per-run folder (WS-21 §2.1: deleted after the run), and a durable write
+     * rooted there is durable in name only. Omitted, or returning `undefined`, degrades to
+     * `winterHome` itself: byte-identical to every pre-WS-21 caller (`testing.ts`'s in-memory leg,
+     * deliberately -- its own hermetic root is already the single source of truth for a virtual
+     * session, and splitting it further would buy that leg nothing while adding a second root a test
+     * could disagree with itself about).
+     */
+    resolveStoreHome?: () => string | undefined;
+    env: Record<string, string | undefined>;
+}): Promise<ResolvedEngineSession>;
+export declare function resolveProductionWinterHome(config: RuntimeConfig, env: Record<string, string | undefined>): string;
+export declare function resolveProductionStoreHome(config: RuntimeConfig, env: Record<string, string | undefined>): string | undefined;