@fabric-harness/sdk 1.13.0 → 2.0.0

package/dist/attachment-store.js

@@ -0,0 +1,164 @@
+/**
+ * Durable, content-addressed attachment storage (v2 migration, phase A7).
+ *
+ * Inline base64 attachments on a {@link DeliveredMessage} are materialized at
+ * admission into content-addressed refs: bytes live in an
+ * {@link AttachmentStore} keyed by `(scope, sha-256 digest)` and the persisted
+ * submission payload carries only the ref. `scope` is the storage partition —
+ * the harness passes the instance's store session id
+ * (`agent:<name>:<id>:<session>`), so attachments are isolated per instance
+ * session and content-deduplicated within it.
+ *
+ * Materialization is deterministic (ids derive from the submission/dispatch
+ * id + attachment index, digests from content), so an exact redelivery of the
+ * same message produces an identical payload and admission idempotency is
+ * preserved. Verify an implementation with
+ * `defineAttachmentStoreContractTests` from `attachment-store-contract.ts`.
+ */
+/**
+ * Build an {@link AttachmentRef} for the given bytes, computing the SHA-256
+ * digest via WebCrypto (`crypto.subtle`) so the SDK stays runtime-agnostic.
+ */
+export async function createAttachmentRef(input) {
+    return {
+        id: input.id,
+        mimeType: input.mimeType,
+        sizeBytes: input.bytes.byteLength,
+        digest: await attachmentDigest(input.bytes),
+        ...(input.filename !== undefined ? { filename: input.filename } : {}),
+    };
+}
+/** Lowercase hex SHA-256 of the bytes (WebCrypto). */
+export async function attachmentDigest(bytes) {
+    const digest = await crypto.subtle.digest('SHA-256', viewToBuffer(bytes));
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * Verify that `bytes` match the ref's digest (and declared size), throwing
+ * `AttachmentStoreError('DIGEST_MISMATCH')` otherwise. Every store's `put`
+ * MUST run this check before persisting.
+ */
+export async function verifyAttachmentBytes(ref, bytes) {
+    if (ref.sizeBytes !== bytes.byteLength || ref.digest !== (await attachmentDigest(bytes))) {
+        throw new AttachmentStoreError('DIGEST_MISMATCH', `Attachment ${ref.id} bytes do not match the declared digest/size.`);
+    }
+}
+export class AttachmentStoreError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'AttachmentStoreError';
+        this.code = code;
+    }
+}
+// ─── In-memory store ────────────────────────────────────────────────────────
+/** In-memory attachment store (dev / `runtime: 'stateless'` / tests). */
+export class InMemoryAttachmentStore {
+    records = new Map();
+    async put(input) {
+        await verifyAttachmentBytes(input.ref, input.bytes);
+        const key = attachmentKey(input.scope, input.ref.digest);
+        // Idempotent by (scope, digest): the first stored copy wins.
+        if (this.records.has(key))
+            return;
+        this.records.set(key, { ref: { ...input.ref }, bytes: Uint8Array.from(input.bytes) });
+    }
+    async get(scope, digest) {
+        const record = this.records.get(attachmentKey(scope, digest));
+        if (!record)
+            return null;
+        return { ref: { ...record.ref }, bytes: Uint8Array.from(record.bytes) };
+    }
+    async getByAttachmentId(scope, attachmentId) {
+        for (const [key, record] of this.records) {
+            if (scopeOfKey(key) === scope && record.ref.id === attachmentId) {
+                return { ref: { ...record.ref }, bytes: Uint8Array.from(record.bytes) };
+            }
+        }
+        return null;
+    }
+    async list(scope) {
+        const refs = [];
+        for (const [key, record] of this.records) {
+            if (scopeOfKey(key) === scope)
+                refs.push({ ...record.ref });
+        }
+        return refs;
+    }
+    async delete(scope, digest) {
+        if (!this.records.delete(attachmentKey(scope, digest))) {
+            throw new AttachmentStoreError('NOT_FOUND', `Attachment not found: ${scope}/${digest}`);
+        }
+    }
+}
+function attachmentKey(scope, digest) {
+    return JSON.stringify([scope, digest]);
+}
+function scopeOfKey(key) {
+    const [scope] = JSON.parse(key);
+    return scope;
+}
+// ─── Message materialization ────────────────────────────────────────────────
+/** True when the message carries at least one inline (base64) attachment. */
+export function messageHasDataAttachments(message) {
+    return (message.kind === 'user' &&
+        (message.attachments ?? []).some((attachment) => attachment.data !== undefined));
+}
+/**
+ * Materialize a message's inline attachments into durable refs: decode the
+ * base64 data, store the bytes under `scope`, and return a NEW message whose
+ * attachments carry `{ type, mimeType, filename?, ref }` and no `data`.
+ *
+ * Deterministic by construction — attachment ids are `${idPrefix}_${index}`
+ * and digests derive from content — so an exact redelivery of the same
+ * message produces an identical materialized payload (admission idempotency).
+ * Messages without inline attachments are returned unchanged (same
+ * reference).
+ */
+export async function materializeMessageAttachments(message, store, options) {
+    if (!messageHasDataAttachments(message) || message.kind !== 'user')
+        return message;
+    const attachments = [];
+    const source = message.attachments ?? [];
+    for (let index = 0; index < source.length; index += 1) {
+        const attachment = source[index];
+        if (!attachment || attachment.data === undefined) {
+            if (attachment)
+                attachments.push(attachment);
+            continue;
+        }
+        const bytes = decodeAttachmentBase64(attachment.data);
+        const ref = await createAttachmentRef({
+            id: `${options.idPrefix}_${index}`,
+            mimeType: attachment.mimeType,
+            bytes,
+            ...(attachment.filename !== undefined ? { filename: attachment.filename } : {}),
+        });
+        await store.put({ scope: options.scope, ref, bytes });
+        attachments.push({
+            type: attachment.type,
+            mimeType: attachment.mimeType,
+            ...(attachment.filename !== undefined ? { filename: attachment.filename } : {}),
+            ref: { id: ref.id, digest: ref.digest, sizeBytes: ref.sizeBytes },
+        });
+    }
+    return { kind: 'user', body: message.body, attachments };
+}
+function decodeAttachmentBase64(value) {
+    try {
+        if (typeof Buffer !== 'undefined')
+            return new Uint8Array(Buffer.from(value, 'base64'));
+        const bin = atob(value);
+        const out = new Uint8Array(bin.length);
+        for (let i = 0; i < bin.length; i += 1)
+            out[i] = bin.charCodeAt(i);
+        return out;
+    }
+    catch {
+        throw new Error('[fabric-harness] Attachment "data" is not valid base64.');
+    }
+}
+function viewToBuffer(bytes) {
+    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}
+//# sourceMappingURL=attachment-store.js.map

package/dist/attachment-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-store.js","sourceRoot":"","sources":["../src/attachment-store.ts"],"names":[],"mappings":"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"}

package/dist/channel.d.ts

@@ -0,0 +1,84 @@
+import type { DeliveredMessage } from './delivered-message.js';
+import type { DispatchReceipt } from './dispatch.js';
+import type { FabricActor } from './types.js';
+/**
+ * Channels turn platform webhooks (Slack, GitHub, …) into agent dispatches. Handlers are written
+ * against the Web `Request`/`Response` API and `crypto.subtle`, so the same channel runs on Node and
+ * Cloudflare. A channel is a stateless route container plus a conversation-id (de)serializer —
+ * session continuity falls out of the key (same thread → same key → same session).
+ */
+export interface ChannelRoute {
+    /** HTTP method, uppercase (e.g. "POST"). */
+    method: string;
+    /** Absolute path suffix mounted under `/channels/:name` (e.g. "/events"). */
+    path: string;
+    handler: (request: Request, context: ChannelContext) => Promise<Response> | Response;
+}
+export interface Channel {
+    /** Optional stable name; the mount name usually comes from the file/registration. */
+    readonly name?: string;
+    readonly routes: readonly ChannelRoute[];
+    /** Serialize a platform reference (e.g. a Slack thread) into a stable instance id. */
+    conversationKey(ref: unknown): string;
+    /** Parse an instance id back into the platform reference. */
+    parseConversationKey(id: string): unknown;
+}
+export interface ChannelDispatchRequest {
+    /** Target persistent-agent instance id — typically `channel.conversationKey(ref)`. */
+    instanceId: string;
+    session?: string;
+    /**
+     * The message delivered to the session. Channels should construct signals
+     * (`kind: 'signal'`) for platform activity; preferred over `input`.
+     */
+    message?: DeliveredMessage;
+    /** Legacy JSON payload. Normalized into a user-kind message at admission. */
+    input?: unknown;
+    /** Stable key (e.g. the platform event id) → `dispatchId` for exactly-once delivery. */
+    dedupeKey?: string;
+    tenantId?: string;
+    actor?: FabricActor;
+}
+export type ChannelDispatch = (agent: string, request: ChannelDispatchRequest) => Promise<DispatchReceipt>;
+export interface ChannelContext {
+    /** Dispatch to a persistent agent. Provided by the runtime mounting the channel. */
+    dispatch: ChannelDispatch;
+    env: Record<string, string | undefined>;
+}
+/** Validates and brands a channel's routes. */
+export declare function defineChannel(channel: Channel): Channel;
+export declare function hmacSha256(secret: string | Uint8Array, message: Uint8Array): Promise<Uint8Array>;
+/** Constant-time HMAC-SHA256 verification (via `crypto.subtle.verify`). */
+export declare function verifyHmacSha256(secret: string | Uint8Array, message: Uint8Array, signature: Uint8Array): Promise<boolean>;
+export declare function bytesToHex(bytes: Uint8Array): string;
+export declare function hexToBytes(hex: string): Uint8Array;
+export declare function conversationKey(provider: string, version: string, ...segments: string[]): string;
+export interface ParsedConversationKey {
+    provider: string;
+    version: string;
+    segments: string[];
+}
+export declare function parseConversationKey(key: string): ParsedConversationKey;
+/**
+ * Reads the full request body as bytes, or returns undefined if it exceeds `limitBytes`.
+ *
+ * NOTE: this consumes the request stream (single read). Signature-verifying channels need the *exact*
+ * bytes for HMAC and the parsed JSON afterward — don't call `request.json()` as well. Use
+ * {@link readJsonBody} to get both from one read.
+ */
+export declare function readRequestBody(request: Request, limitBytes?: number): Promise<Uint8Array | undefined>;
+export interface RequestBody {
+    /** Exact bytes — use these (or `text`) for signature verification. */
+    raw: Uint8Array;
+    /** UTF-8 decode of `raw`. */
+    text: string;
+    /** Parsed JSON, or `undefined` if the body isn't valid JSON. */
+    json: unknown;
+}
+/**
+ * Reads the body once and returns the raw bytes, the decoded text, and the parsed JSON together — so a
+ * channel can HMAC-verify the exact bytes and use the JSON without re-reading the (already consumed)
+ * stream. Returns undefined only when the body exceeds `limitBytes`.
+ */
+export declare function readJsonBody(request: Request, limitBytes?: number): Promise<RequestBody | undefined>;
+//# sourceMappingURL=channel.d.ts.map

package/dist/channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;GAKG;AAEH,MAAM,WAAW,YAAY;IAC3B,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,QAAQ,CAAC;CACtF;AAED,MAAM,WAAW,OAAO;IACtB,qFAAqF;IACrF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;IACzC,sFAAsF;IACtF,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAAC;IACtC,6DAA6D;IAC7D,oBAAoB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3C;AAED,MAAM,WAAW,sBAAsB;IACrC,sFAAsF;IACtF,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,6EAA6E;IAC7E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,wFAAwF;IACxF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,sBAAsB,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;AAE3G,MAAM,WAAW,cAAc;IAC7B,oFAAoF;IACpF,QAAQ,EAAE,eAAe,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;CACzC;AAID,+CAA+C;AAC/C,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAevD;AAgBD,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAItG;AAED,2EAA2E;AAC3E,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAOhI;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAIpD;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAMlD;AAMD,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,CAGhG;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,qBAAqB,CAKvE;AAQD;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,SAAqB,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAMxH;AAED,MAAM,WAAW,WAAW;IAC1B,sEAAsE;IACtE,GAAG,EAAE,UAAU,CAAC;IAChB,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,SAAqB,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAWtH"}

package/dist/channel.js

@@ -0,0 +1,115 @@
+const METHOD_RE = /^[A-Z]+$/;
+/** Validates and brands a channel's routes. */
+export function defineChannel(channel) {
+    if (!Array.isArray(channel.routes) || channel.routes.length === 0) {
+        throw new Error('defineChannel: a channel must declare at least one route.');
+    }
+    const seen = new Set();
+    for (const route of channel.routes) {
+        if (!METHOD_RE.test(route.method))
+            throw new Error(`defineChannel: route method "${route.method}" must be uppercase letters.`);
+        if (!route.path.startsWith('/') || route.path.startsWith('//') || route.path.includes('?') || route.path.includes('#')) {
+            throw new Error(`defineChannel: route path "${route.path}" must be an absolute suffix without query or fragment.`);
+        }
+        const key = `${route.method} ${route.path}`;
+        if (seen.has(key))
+            throw new Error(`defineChannel: duplicate route "${key}".`);
+        seen.add(key);
+    }
+    return channel;
+}
+// ---------------------------------------------------------------------------
+// Web-standard crypto helpers (HMAC-SHA256) — run identically on Node and edge.
+// ---------------------------------------------------------------------------
+const encoder = new TextEncoder();
+function toBytes(value) {
+    return typeof value === 'string' ? encoder.encode(value) : value;
+}
+function viewToBuffer(bytes) {
+    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}
+export async function hmacSha256(secret, message) {
+    const key = await crypto.subtle.importKey('raw', viewToBuffer(toBytes(secret)), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const signature = await crypto.subtle.sign('HMAC', key, viewToBuffer(message));
+    return new Uint8Array(signature);
+}
+/** Constant-time HMAC-SHA256 verification (via `crypto.subtle.verify`). */
+export async function verifyHmacSha256(secret, message, signature) {
+    try {
+        const key = await crypto.subtle.importKey('raw', viewToBuffer(toBytes(secret)), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
+        return await crypto.subtle.verify('HMAC', key, viewToBuffer(signature), viewToBuffer(message));
+    }
+    catch {
+        return false;
+    }
+}
+export function bytesToHex(bytes) {
+    let hex = '';
+    for (const byte of bytes)
+        hex += byte.toString(16).padStart(2, '0');
+    return hex;
+}
+export function hexToBytes(hex) {
+    const clean = hex.startsWith('0x') ? hex.slice(2) : hex;
+    if (clean.length % 2 !== 0)
+        throw new Error('hexToBytes: odd-length hex string.');
+    const bytes = new Uint8Array(clean.length / 2);
+    for (let i = 0; i < bytes.length; i += 1)
+        bytes[i] = Number.parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+    return bytes;
+}
+// ---------------------------------------------------------------------------
+// Conversation key encoding — `provider:version:seg1:seg2:...` with url-safe segments.
+// ---------------------------------------------------------------------------
+export function conversationKey(provider, version, ...segments) {
+    if (provider.includes(':') || version.includes(':'))
+        throw new Error('conversationKey: provider/version must not contain ":".');
+    return [provider, version, ...segments.map(encodeURIComponent)].join(':');
+}
+export function parseConversationKey(key) {
+    const parts = key.split(':');
+    if (parts.length < 2)
+        throw new Error(`parseConversationKey: invalid key "${key}".`);
+    const [provider, version, ...rest] = parts;
+    return { provider, version, segments: rest.map(decodeURIComponent) };
+}
+// ---------------------------------------------------------------------------
+// Request body — read with a size guard (signature verification needs exact bytes).
+// ---------------------------------------------------------------------------
+const DEFAULT_BODY_LIMIT = 1_000_000;
+/**
+ * Reads the full request body as bytes, or returns undefined if it exceeds `limitBytes`.
+ *
+ * NOTE: this consumes the request stream (single read). Signature-verifying channels need the *exact*
+ * bytes for HMAC and the parsed JSON afterward — don't call `request.json()` as well. Use
+ * {@link readJsonBody} to get both from one read.
+ */
+export async function readRequestBody(request, limitBytes = DEFAULT_BODY_LIMIT) {
+    const contentLength = request.headers.get('content-length');
+    if (contentLength && Number(contentLength) > limitBytes)
+        return undefined;
+    const buffer = new Uint8Array(await request.arrayBuffer());
+    if (buffer.byteLength > limitBytes)
+        return undefined;
+    return buffer;
+}
+/**
+ * Reads the body once and returns the raw bytes, the decoded text, and the parsed JSON together — so a
+ * channel can HMAC-verify the exact bytes and use the JSON without re-reading the (already consumed)
+ * stream. Returns undefined only when the body exceeds `limitBytes`.
+ */
+export async function readJsonBody(request, limitBytes = DEFAULT_BODY_LIMIT) {
+    const raw = await readRequestBody(request, limitBytes);
+    if (!raw)
+        return undefined;
+    const text = new TextDecoder().decode(raw);
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch {
+        json = undefined;
+    }
+    return { raw, text, json };
+}
+//# sourceMappingURL=channel.js.map

package/dist/channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.js","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"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"}

package/dist/context-budget.d.ts

@@ -6,15 +6,31 @@ export interface ContextBudget {
     reserveTokens: number;
     compactAtTokens?: number;
     shouldCompact: boolean;
+    keepRecentTokens?: number;
 }
 export interface ContextBudgetOptions {
     contextWindowTokens?: number;
     compactAtTokens?: number;
     reserveTokens?: number;
+    keepRecentTokens?: number;
 }
 export declare function estimateTextTokens(text: string): number;
 export declare function estimateModelMessagesTokens(messages: ModelMessage[]): number;
+export declare function estimateSessionEntryTokens(entry: SessionEntry): number;
 export declare function estimateSessionEntriesTokens(entries: SessionEntry[]): number;
+/**
+ * Compute model-aware compaction defaults. Reserve is capped at the model's
+ * max output because reserving more than the model can emit in one turn
+ * wastes context; the preserved tail stays flat because recent-context
+ * fidelity depends on the active work, not on the model's total window size.
+ */
+export declare function deriveCompactionDefaults(input: {
+    contextWindowTokens: number;
+    maxOutputTokens?: number;
+}): {
+    reserveTokens: number;
+    keepRecentTokens: number;
+};
 export declare function evaluateContextBudget(messages: ModelMessage[], options?: ContextBudgetOptions): ContextBudget;
 export declare function isContextOverflowError(error: unknown): boolean;
 //# sourceMappingURL=context-budget.d.ts.map

package/dist/context-budget.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-budget.d.ts","sourceRoot":"","sources":["../src/context-budget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,MAAM,WAAW,aAAa;IAC5B,eAAe,EAAE,MAAM,CAAC;IACxB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAID,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,MAAM,CAE5E;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,MAAM,CAE5E;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,YAAY,EAAE,EAAE,OAAO,GAAE,oBAAyB,GAAG,aAAa,CAWjH;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAG9D"}
+{"version":3,"file":"context-budget.d.ts","sourceRoot":"","sources":["../src/context-budget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,MAAM,WAAW,aAAa;IAC5B,eAAe,EAAE,MAAM,CAAC;IACxB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,OAAO,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,oBAAoB;IACnC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAKD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,MAAM,CAE5E;AAED,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAEtE;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,MAAM,CAE5E;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,mBAAmB,EAAE,MAAM,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAE,CAatD;AAED,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,YAAY,EAAE,EAAE,OAAO,GAAE,oBAAyB,GAAG,aAAa,CAuBjH;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAG9D"}

package/dist/context-budget.js

@@ -1,16 +1,50 @@
-const DEFAULT_RESERVE_TOKENS = 4096;
+const DEFAULT_RESERVE_TOKENS = 20_000;
+const DEFAULT_KEEP_RECENT_TOKENS = 8_000;
 export function estimateTextTokens(text) {
     return Math.ceil(text.length / 4);
 }
 export function estimateModelMessagesTokens(messages) {
     return messages.reduce((sum, message) => sum + estimateTextTokens(message.content) + 8, 0);
 }
+export function estimateSessionEntryTokens(entry) {
+    return estimateTextTokens(JSON.stringify({ type: entry.type, data: entry.data ?? {} })) + 8;
+}
 export function estimateSessionEntriesTokens(entries) {
-    return entries.reduce((sum, entry) => sum + estimateTextTokens(JSON.stringify({ type: entry.type, data: entry.data ?? {} })) + 8, 0);
+    return entries.reduce((sum, entry) => sum + estimateSessionEntryTokens(entry), 0);
+}
+/**
+ * Compute model-aware compaction defaults. Reserve is capped at the model's
+ * max output because reserving more than the model can emit in one turn
+ * wastes context; the preserved tail stays flat because recent-context
+ * fidelity depends on the active work, not on the model's total window size.
+ */
+export function deriveCompactionDefaults(input) {
+    const reserveCap = input.maxOutputTokens !== undefined && input.maxOutputTokens > 0
+        ? input.maxOutputTokens
+        : DEFAULT_RESERVE_TOKENS;
+    let reserveTokens = Math.min(DEFAULT_RESERVE_TOKENS, reserveCap);
+    if (input.contextWindowTokens > 0 && reserveTokens * 2 >= input.contextWindowTokens) {
+        reserveTokens = Math.max(1024, Math.floor(input.contextWindowTokens / 3));
+    }
+    return {
+        reserveTokens,
+        keepRecentTokens: DEFAULT_KEEP_RECENT_TOKENS,
+    };
 }
 export function evaluateContextBudget(messages, options = {}) {
     const estimatedTokens = estimateModelMessagesTokens(messages);
-    const reserveTokens = options.reserveTokens ?? DEFAULT_RESERVE_TOKENS;
+    let reserveTokens;
+    if (options.reserveTokens !== undefined) {
+        reserveTokens = options.reserveTokens;
+    }
+    else if (options.contextWindowTokens !== undefined) {
+        const defaults = deriveCompactionDefaults({ contextWindowTokens: options.contextWindowTokens });
+        reserveTokens = defaults.reserveTokens;
+    }
+    else {
+        reserveTokens = DEFAULT_RESERVE_TOKENS;
+    }
+    const keepRecentTokens = options.keepRecentTokens ?? DEFAULT_KEEP_RECENT_TOKENS;
     const compactAtTokens = options.compactAtTokens ?? (options.contextWindowTokens ? Math.max(0, options.contextWindowTokens - reserveTokens) : undefined);
     return {
         estimatedTokens,
@@ -18,6 +52,7 @@ export function evaluateContextBudget(messages, options = {}) {
         ...(options.contextWindowTokens !== undefined ? { contextWindowTokens: options.contextWindowTokens } : {}),
         ...(compactAtTokens !== undefined ? { compactAtTokens } : {}),
         shouldCompact: compactAtTokens !== undefined && estimatedTokens >= compactAtTokens,
+        keepRecentTokens,
     };
 }
 export function isContextOverflowError(error) {

package/dist/context-budget.js.map

@@ -1 +1 @@
-{"version":3,"file":"context-budget.js","sourceRoot":"","sources":["../src/context-budget.ts"],"names":[],"mappings":"AAiBA,MAAM,sBAAsB,GAAG,IAAI,CAAC;AAEpC,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,2BAA2B,CAAC,QAAwB;IAClE,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,CAAC,GAAG,GAAG,kBAAkB,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;AAC7F,CAAC;AAED,MAAM,UAAU,4BAA4B,CAAC,OAAuB;IAClE,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,GAAG,GAAG,kBAAkB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;AACvI,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,QAAwB,EAAE,UAAgC,EAAE;IAChG,MAAM,eAAe,GAAG,2BAA2B,CAAC,QAAQ,CAAC,CAAC;IAC9D,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,sBAAsB,CAAC;IACtE,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,mBAAmB,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACxJ,OAAO;QACL,eAAe;QACf,aAAa;QACb,GAAG,CAAC,OAAO,CAAC,mBAAmB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,mBAAmB,EAAE,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1G,GAAG,CAAC,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7D,aAAa,EAAE,eAAe,KAAK,SAAS,IAAI,eAAe,IAAI,eAAe;KACnF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,KAAc;IACnD,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACvE,OAAO,yGAAyG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AACjI,CAAC"}
+{"version":3,"file":"context-budget.js","sourceRoot":"","sources":["../src/context-budget.ts"],"names":[],"mappings":"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"}

package/dist/conversation-projection.d.ts

@@ -0,0 +1,52 @@
+import type { ConversationStreamStore } from './conversation-stream.js';
+import type { SessionData, SessionEntry, SessionStore } from './types.js';
+/**
+ * Wrap a {@link SessionStore} so active-path appends are mirrored into an
+ * append-only {@link ConversationStreamStore} projection (v2 A4).
+ *
+ * The SessionEntry DAG stays the single source of truth; the stream gives
+ * clients offset-based catch-up + live tail. Two rules keep them coherent:
+ *
+ * 1. **Idempotent by entryId** — a crash between the DAG write and the
+ *    stream write is repaired on the next append: the projector diffs the
+ *    stream tail against the active path and re-emits anything missing.
+ * 2. **Truncation is explicit** — the DAG can branch (fork/replay/
+ *    checkpoint-restore rewrite `leafId`); the stream cannot. When `save()`
+ *    rewinds the active path, the projector appends a `truncated` record
+ *    and re-acquires the producer (epoch bump), so tailing clients see the
+ *    branch switch instead of silently reading a stale path.
+ *
+ * Projection failures are logged and swallowed — the conversation stream is
+ * an observability surface and must never fail the session write itself;
+ * the diff-repair on the next append restores consistency.
+ */
+export declare function withConversationProjection(store: SessionStore, streams: ConversationStreamStore, options?: {
+    producerId?: string;
+    onError?: (error: unknown) => void;
+}): SessionStore;
+export declare class ConversationProjector {
+    private readonly streams;
+    private readonly producerId;
+    private readonly onError;
+    private readonly producers;
+    constructor(streams: ConversationStreamStore, options?: {
+        producerId?: string;
+        onError?: (error: unknown) => void;
+    });
+    /** Mirror one appended entry, repairing any missed backlog first. */
+    projectAppend(store: SessionStore, sessionId: string, entry: SessionEntry): Promise<void>;
+    /** Handle whole-document saves (fork/replay/truncation rewrite the path). */
+    projectSave(data: SessionData): Promise<void>;
+    deleteStream(sessionId: string): Promise<void>;
+    private ensureProducer;
+    /** Fold the stream into the currently-projected entry ids (truncations rewind). */
+    private readProjectedEntryIds;
+    /**
+     * Diff the projected tail against the current active path. A pure
+     * extension appends the missing suffix; a divergence appends a
+     * `truncated` record (with a fresh producer epoch) then the new suffix.
+     */
+    private reproject;
+    private appendRecords;
+}
+//# sourceMappingURL=conversation-projection.d.ts.map

package/dist/conversation-projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-projection.d.ts","sourceRoot":"","sources":["../src/conversation-projection.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAEV,uBAAuB,EACxB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,YAAY,EACnB,OAAO,EAAE,uBAAuB,EAChC,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;CAAO,GACxE,YAAY,CAyBd;AAUD,qBAAa,qBAAqB;IAM9B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAL1B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;IACnD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoC;gBAG3C,OAAO,EAAE,uBAAuB,EACjD,OAAO,GAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;KAAO;IAQ3E,qEAAqE;IAC/D,aAAa,CAAC,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB/F,6EAA6E;IACvE,WAAW,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAS7C,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAStC,cAAc;IAmB5B,mFAAmF;YACrE,qBAAqB;IAoBnC;;;;OAIG;YACW,SAAS;YAgCT,aAAa;CA6B5B"}