@farmslot/protocol 0.73.2 → 0.74.1

package/dist/client-cache/keys.d.ts

@@ -0,0 +1,126 @@
+/** Experimental ADR-071 keys. IDs identify resources; keys never contain filesystem paths. */
+export type ResourceKey = {
+    family: 'sources';
+    scope: 'farm';
+} | {
+    family: 'runs';
+    scope: 'farm';
+    project?: string;
+} | {
+    family: 'run';
+    runId: string;
+} | {
+    family: 'family';
+    familyId: string;
+} | {
+    family: 'decisions';
+    scope: 'farm';
+} | {
+    family: 'decision';
+    decisionId: string;
+} | {
+    family: 'gate' | 'package';
+    runId: string;
+    decisionId?: string;
+} | {
+    family: 'slots';
+    scope: 'farm';
+    project?: string;
+    nodeId?: string;
+} | {
+    family: 'slot';
+    slotId: string;
+} | {
+    family: 'node' | 'workers';
+    scope: 'farm';
+} | {
+    family: 'node' | 'pressure' | 'workers';
+    nodeId: string;
+} | {
+    family: 'review';
+    runId: string;
+    reviewId?: string;
+} | {
+    family: 'artifacts';
+    runId: string;
+    invocationId?: string;
+} | {
+    family: 'progress';
+    runId: string;
+    contextId?: string;
+} | {
+    family: 'capabilities';
+    nodeId?: string;
+    slotId?: string;
+} | {
+    family: 'capability';
+    capabilityId: string;
+} | {
+    family: 'workspace';
+    slotId: string;
+    runId?: string;
+} | {
+    family: 'workspace';
+    nodeId: string;
+    ownerId: string;
+    sessionId: string;
+    contextId?: string;
+} | {
+    family: 'workspace';
+    nodeId: string;
+    ownerId: string;
+    workspaceId: string;
+} | {
+    family: 'native-session';
+    nodeId: string;
+    ownerId: string;
+    sessionId?: string;
+    workerId?: string;
+} | {
+    family: 'profiles';
+    nodeId: string;
+    ownerId: string;
+} | {
+    family: 'native-session' | 'profiles';
+    scope: 'owner';
+    ownerId: string;
+} | {
+    family: 'configuration' | 'pr-automation' | 'analytics';
+    scope: 'farm';
+    project?: string;
+} | {
+    family: 'planning';
+    collection: 'backlog' | 'roadmap' | 'work-graphs' | 'dispatch-queue';
+    project?: string;
+    itemId?: string;
+} | {
+    family: 'assessment';
+    scope: 'farm';
+    assessmentId?: string;
+} | {
+    family: 'copilot';
+    ownerId: string;
+    sessionId?: string;
+} | {
+    family: 'gateway-update';
+    scope: 'gateway';
+} | {
+    family: 'upstream';
+    integration: 'github' | 'packages' | 'providers';
+    queryId: string;
+};
+export type ResourceRevision = number;
+export interface ResourceDependency {
+    key: ResourceKey;
+    revision: ResourceRevision;
+}
+export interface ResourceReadStamp {
+    epoch: string;
+    dependencies: ResourceDependency[];
+}
+/** Canonical JSON for query parameters and typed resource keys. Arrays retain their order. */
+export declare function canonicalResourceJson(value: unknown): string;
+export declare function resourceKeyId(key: ResourceKey): string;
+/** Busy observations have one gateway publication cadence, shared by all readers. */
+export declare const RESOURCE_PUBLISH_INTERVAL_MS: Partial<Record<ResourceKey['family'], number>>;
+//# sourceMappingURL=keys.d.ts.map

package/dist/client-cache/keys.d.ts.map

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

package/dist/client-cache/keys.js

@@ -0,0 +1,25 @@
+/** Canonical JSON for query parameters and typed resource keys. Arrays retain their order. */
+export function canonicalResourceJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map(canonicalResourceJson).join(',')}]`;
+    const object = value;
+    return `{${Object.keys(object)
+        .sort()
+        .filter((key) => object[key] !== undefined)
+        .map((key) => `${JSON.stringify(key)}:${canonicalResourceJson(object[key])}`)
+        .join(',')}}`;
+}
+export function resourceKeyId(key) {
+    return canonicalResourceJson(key);
+}
+/** Busy observations have one gateway publication cadence, shared by all readers. */
+export const RESOURCE_PUBLISH_INTERVAL_MS = {
+    workspace: 200,
+    workers: 200,
+    copilot: 200,
+    progress: 200,
+    'native-session': 200,
+};
+//# sourceMappingURL=keys.js.map

package/dist/client-cache/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../../src/client-cache/keys.ts"],"names":[],"mappings":"AAsDA,8FAA8F;AAC9F,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC;IACxF,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IACnF,MAAM,MAAM,GAAG,KAAgC,CAAC;IAChD,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;SAC3B,IAAI,EAAE;SACN,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC;SAC1C,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,qBAAqB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;SAC5E,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,GAAgB;IAC5C,OAAO,qBAAqB,CAAC,GAAG,CAAC,CAAC;AACpC,CAAC;AAED,qFAAqF;AACrF,MAAM,CAAC,MAAM,4BAA4B,GAAmD;IAC1F,SAAS,EAAE,GAAG;IACd,OAAO,EAAE,GAAG;IACZ,OAAO,EAAE,GAAG;IACZ,QAAQ,EAAE,GAAG;IACb,gBAAgB,EAAE,GAAG;CACtB,CAAC"}

package/dist/client-cache/native-history.d.ts

@@ -0,0 +1,64 @@
+import type { NativeSessionEvent, NativeSessionReadResult, NativeSessionTargetParams } from '../rpc/native-session.js';
+import { type ResourceQuery } from './registry.js';
+import type { ResourceReadResult } from './types.js';
+export interface NativeTimelineEntry {
+    key: number;
+    kind: 'user' | 'assistant' | 'tool' | 'status';
+    event: NativeSessionEvent;
+    text: string;
+}
+export declare function nativeTimeline(events: NativeSessionEvent[]): NativeTimelineEntry[];
+/** Client projection metadata. Never sent as a native RPC parameter. */
+export interface NativeHistorySnapshot extends NativeSessionReadResult {
+    historyRead: {
+        pageReadCount: number;
+        pageAfters: number[];
+    };
+}
+export declare const NATIVE_HISTORY_MESSAGES = 200;
+export declare const NATIVE_HISTORY_SESSIONS = 10;
+/** One durable observation per opened session/binding, never per cursor page. */
+export declare function nativeHistoryQuery(target: NativeSessionTargetParams, ownerId: string): ResourceQuery<NativeHistorySnapshot>;
+export declare function nativeObservationQuery<T>(method: string, params: unknown, ownerId: string): ResourceQuery<T>;
+/** Merge fragments before bounding logical timeline entries. Never slice the raw event tail. */
+export declare function retainNativeMessages(events: NativeSessionEvent[]): NativeSessionEvent[];
+export declare function sameNativeHistoryIdentity(a: NativeSessionReadResult, b: NativeSessionReadResult): boolean;
+export interface NativeHistoryReader {
+    (params: NativeSessionTargetParams & {
+        after?: number;
+        limit: number;
+    }, signal: AbortSignal): Promise<ResourceReadResult<NativeSessionReadResult>>;
+}
+/** Called inside the existing cache's single in-flight read and authority/store fences.
+ * Cursor drains remain read-only. Neither receipts nor pending intents are dispatched here.
+ */
+export declare function readNativeHistory(target: NativeSessionTargetParams, previous: NativeSessionReadResult | undefined, request: NativeHistoryReader, signal: AbortSignal): Promise<ResourceReadResult<NativeHistorySnapshot>>;
+/** Dependencies are scoped to the authenticated reader's authorized native view.
+ * The gateway stamps and invalidates these aliases only after handler-level authorization.
+ * Cross-node inventories use an explicit owner collection, never a wildcard node.
+ */
+export declare function nativeObservationDependencies(method: string, params: unknown, ownerId: string): {
+    family: "profiles" | "native-session";
+    scope: "owner";
+    ownerId: string;
+}[] | {
+    family: "profiles";
+    nodeId: string;
+    ownerId: string;
+}[] | {
+    workerId?: string | undefined;
+    sessionId?: string | undefined;
+    family: "native-session";
+    nodeId: string;
+    ownerId: string;
+}[];
+/** Reject cursor/limit variants at registration. They belong only to readNativeHistory. */
+export declare function nativeHistoryParams(value: unknown): NativeSessionTargetParams;
+/** Durable retention counts sessions, while in-memory observation identity keeps the lease pin. */
+export declare function nativeHistoryStorageId(query: Pick<ResourceQuery, 'id' | 'method' | 'params'>): string;
+export declare function storedNativeHistoryMatches(target: NativeSessionTargetParams, value: unknown): value is NativeSessionReadResult;
+export declare function nativeHistoryCanAct(observation: {
+    status: string;
+    data?: NativeSessionReadResult;
+} | undefined, rendered: NativeSessionReadResult | undefined, connected: boolean): boolean;
+//# sourceMappingURL=native-history.d.ts.map

package/dist/client-cache/native-history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-history.d.ts","sourceRoot":"","sources":["../../src/client-cache/native-history.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,uBAAuB,EACvB,yBAAyB,EAC1B,MAAM,0BAA0B,CAAC;AAIlC,OAAO,EAAE,KAAK,aAAa,EAA0C,MAAM,eAAe,CAAC;AAC3F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM,GAAG,QAAQ,CAAC;IAC/C,KAAK,EAAE,kBAAkB,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,kBAAkB,EAAE,GAAG,mBAAmB,EAAE,CAyElF;AAED,wEAAwE;AACxE,MAAM,WAAW,qBAAsB,SAAQ,uBAAuB;IACpE,WAAW,EAAE;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CAC9D;AAED,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAC3C,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C,iFAAiF;AACjF,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,yBAAyB,EACjC,OAAO,EAAE,MAAM,GACd,aAAa,CAAC,qBAAqB,CAAC,CAMtC;AAED,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,MAAM,GACd,aAAa,CAAC,CAAC,CAAC,CAElB;AAED,gGAAgG;AAChG,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,kBAAkB,EAAE,GAAG,kBAAkB,EAAE,CAkBvF;AAED,wBAAgB,yBAAyB,CACvC,CAAC,EAAE,uBAAuB,EAC1B,CAAC,EAAE,uBAAuB,GACzB,OAAO,CAcT;AAmBD,MAAM,WAAW,mBAAmB;IAClC,CACE,MAAM,EAAE,yBAAyB,GAAG;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EACrE,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,kBAAkB,CAAC,uBAAuB,CAAC,CAAC,CAAC;CACzD;AASD;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,yBAAyB,EACjC,QAAQ,EAAE,uBAAuB,GAAG,SAAS,EAC7C,OAAO,EAAE,mBAAmB,EAC5B,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,kBAAkB,CAAC,qBAAqB,CAAC,CAAC,CAyEpD;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM;;;;;;;;;;;;;;IA4B7F;AAED,2FAA2F;AAC3F,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,yBAAyB,CAqB7E;AAED,mGAAmG;AACnG,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,IAAI,CAAC,aAAa,EAAE,IAAI,GAAG,QAAQ,GAAG,QAAQ,CAAC,GACrD,MAAM,CAIR;AAED,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,yBAAyB,EACjC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,uBAAuB,CAalC;AAED,wBAAgB,mBAAmB,CACjC,WAAW,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,uBAAuB,CAAA;CAAE,GAAG,SAAS,EAC3E,QAAQ,EAAE,uBAAuB,GAAG,SAAS,EAC7C,SAAS,EAAE,OAAO,GACjB,OAAO,CAQT"}

package/dist/client-cache/native-history.js

@@ -0,0 +1,285 @@
+import { Methods } from '../rpc/registry.js';
+import { resourceQuery } from './registry.js';
+export function nativeTimeline(events) {
+    const entries = [];
+    const userCommands = new Set();
+    const tools = new Map();
+    const prompts = new Map();
+    for (const event of events) {
+        if ((event.type === 'command.submitted' || event.type === 'command.accepted') &&
+            event.commandId &&
+            event.text !== undefined &&
+            !prompts.has(event.commandId))
+            prompts.set(event.commandId, event);
+    }
+    for (const event of events) {
+        if (event.commandId && !userCommands.has(event.commandId)) {
+            const prompt = prompts.get(event.commandId);
+            if (prompt) {
+                userCommands.add(event.commandId);
+                entries.push({ key: prompt.sequence, kind: 'user', event: prompt, text: prompt.text });
+            }
+        }
+        if (event.type === 'text.delta') {
+            const last = entries.at(-1);
+            if (last?.kind === 'assistant' &&
+                last.event.commandId === event.commandId &&
+                last.event.generation === event.generation) {
+                last.text += event.text ?? '';
+            }
+            else
+                entries.push({ key: event.sequence, kind: 'assistant', event, text: event.text ?? '' });
+        }
+        else if (event.type === 'tool.started' || event.type === 'tool.completed') {
+            const identity = event.nativeId && JSON.stringify([event.generation, event.commandId, event.nativeId]);
+            const previous = identity ? tools.get(identity) : undefined;
+            if (previous) {
+                const completed = previous.event.type === 'tool.completed' ? previous.event : event;
+                const started = event.type === 'tool.started' ? event : previous.event;
+                previous.event = {
+                    ...completed,
+                    tool: {
+                        ...started.tool,
+                        ...completed.tool,
+                        name: started.tool?.name ?? completed.tool?.name ?? 'Tool',
+                    },
+                };
+            }
+            else {
+                const entry = {
+                    key: event.sequence,
+                    kind: 'tool',
+                    event,
+                    text: event.tool?.name ?? 'Tool',
+                };
+                entries.push(entry);
+                if (identity)
+                    tools.set(identity, entry);
+            }
+        }
+        else if (['turn.completed', 'session.closed', 'error'].includes(event.type)) {
+            entries.push({
+                key: event.sequence,
+                kind: 'status',
+                event,
+                text: event.text ??
+                    (event.type === 'session.closed'
+                        ? `Session ${event.status ?? 'closed'}`
+                        : event.type === 'error'
+                            ? 'Runner error'
+                            : `Turn ${event.status ?? 'completed'}`),
+            });
+        }
+    }
+    return entries;
+}
+export const NATIVE_HISTORY_MESSAGES = 200;
+export const NATIVE_HISTORY_SESSIONS = 10;
+/** One durable observation per opened session/binding, never per cursor page. */
+export function nativeHistoryQuery(target, ownerId) {
+    return nativeObservationQuery(Methods.NATIVE_SESSION_READ, nativeHistoryParams(target), ownerId);
+}
+export function nativeObservationQuery(method, params, ownerId) {
+    return resourceQuery(method, params, ownerId);
+}
+/** Merge fragments before bounding logical timeline entries. Never slice the raw event tail. */
+export function retainNativeMessages(events) {
+    const timeline = nativeTimeline(events);
+    let messages = 0;
+    let start = timeline.length;
+    while (start > 0 && messages < NATIVE_HISTORY_MESSAGES) {
+        start--;
+        if (timeline[start].kind === 'user' || timeline[start].kind === 'assistant')
+            messages++;
+    }
+    let statuses = 0;
+    const retained = timeline
+        .slice(start)
+        .reverse()
+        .filter((entry) => entry.kind !== 'status' || ++statuses <= NATIVE_HISTORY_MESSAGES)
+        .reverse();
+    return retained.map((entry) => ({
+        ...entry.event,
+        ...(entry.kind === 'assistant' || entry.kind === 'user' ? { text: entry.text } : {}),
+    }));
+}
+export function sameNativeHistoryIdentity(a, b) {
+    const identity = (page) => JSON.stringify([
+        page.session.id,
+        page.session.executionNodeId,
+        page.session.ownerPrincipalId,
+        page.session.profileId,
+        page.session.accountContextId,
+        page.session.nativeSessionId,
+        page.session.generation,
+        page.session.workerLeaseId,
+        page.scope?.leaseId,
+    ]);
+    return identity(a) === identity(b);
+}
+/** A paged observation can claim only the minimum revision sampled across its pages. */
+function intersectStamps(a, b) {
+    if (!a || !b || a.epoch !== b.epoch)
+        return undefined;
+    return {
+        epoch: a.epoch,
+        dependencies: a.dependencies.flatMap((left) => {
+            const right = b.dependencies.find((item) => JSON.stringify(item.key) === JSON.stringify(left.key));
+            return right ? [{ key: left.key, revision: Math.min(left.revision, right.revision) }] : [];
+        }),
+    };
+}
+function assertHistoryNotAborted(signal) {
+    if (!signal.aborted)
+        return;
+    // Mobile signals support aborted but can lack the newer method and reason.
+    if (signal.reason !== undefined)
+        throw signal.reason;
+    throw Object.assign(new Error('Native history read aborted.'), { name: 'AbortError' });
+}
+/** Called inside the existing cache's single in-flight read and authority/store fences.
+ * Cursor drains remain read-only. Neither receipts nor pending intents are dispatched here.
+ */
+export async function readNativeHistory(target, previous, request, signal) {
+    let retained = previous;
+    let cursor = previous?.cursor;
+    let stamp;
+    let first = true;
+    const previousRead = previous?.historyRead;
+    let pageReadCount = previousRead?.pageReadCount ?? 0;
+    let pageAfters = previousRead?.pageAfters ?? [];
+    for (let pages = 0; pages < 1000; pages++) {
+        assertHistoryNotAborted(signal);
+        const reply = await request({ ...target, ...(cursor === undefined ? {} : { after: cursor }), limit: 200 }, signal);
+        assertHistoryNotAborted(signal);
+        pageReadCount++;
+        pageAfters = [...pageAfters.slice(-19), cursor ?? reply.data.scope?.startAfter ?? 0];
+        const page = reply.data;
+        if (page.session.id !== target.sessionId ||
+            page.session.executionNodeId !== (target.executionNodeId ?? 'local'))
+            throw Object.assign(new Error('Native history returned another session or node.'), {
+                code: 'NOT_FOUND',
+            });
+        if (target.worker &&
+            (page.scope?.leaseId !== target.worker.leaseId ||
+                page.session.workerLeaseId !== target.worker.leaseId ||
+                page.session.generation !== target.worker.generation))
+            throw Object.assign(new Error('Native worker history binding changed.'), {
+                code: 'NOT_FOUND',
+            });
+        if (retained && !sameNativeHistoryIdentity(retained, page)) {
+            throw Object.assign(new Error('Native session identity changed. Reopen it explicitly.'), {
+                code: 'NOT_FOUND',
+            });
+        }
+        if (retained?.scope &&
+            page.scope &&
+            (retained.scope.startAfter !== page.scope.startAfter ||
+                page.scope.endAt < retained.scope.endAt ||
+                (retained.scope.released &&
+                    (!page.scope.released || page.scope.endAt !== retained.scope.endAt))))
+            throw Object.assign(new Error('Native task history boundaries changed.'), {
+                code: 'NOT_FOUND',
+            });
+        let next = cursor ?? page.scope?.startAfter ?? 0;
+        const fresh = [];
+        for (const event of page.events) {
+            if (event.sessionId !== target.sessionId)
+                throw new Error('Native event belongs to another session.');
+            if (event.sequence <= next)
+                continue;
+            if (event.sequence !== next + 1)
+                throw new Error('Native history has a gap.');
+            next = event.sequence;
+            fresh.push(event);
+        }
+        if (page.cursor !== next || (page.hasMore && next === (cursor ?? page.scope?.startAfter ?? 0)))
+            throw new Error('Native history cursor did not advance consistently.');
+        stamp = first ? reply.resourceState : intersectStamps(stamp, reply.resourceState);
+        first = false;
+        retained = { ...page, events: retainNativeMessages([...(retained?.events ?? []), ...fresh]) };
+        cursor = page.cursor;
+        if (!page.hasMore)
+            return {
+                data: { ...retained, historyRead: { pageReadCount, pageAfters } },
+                resourceState: stamp,
+            };
+    }
+    throw new Error('Native history exceeded the bounded page drain. Retry the read explicitly.');
+}
+/** Dependencies are scoped to the authenticated reader's authorized native view.
+ * The gateway stamps and invalidates these aliases only after handler-level authorization.
+ * Cross-node inventories use an explicit owner collection, never a wildcard node.
+ */
+export function nativeObservationDependencies(method, params, ownerId) {
+    const target = (params ?? {});
+    if (!ownerId)
+        throw new Error('Native observations require the saved authenticated owner.');
+    const profiles = method === Methods.NATIVE_PROFILE_LIST || method === Methods.NATIVE_PROFILE_STATUS;
+    if (!target.executionNodeId && method !== Methods.NATIVE_SESSION_READ)
+        return [
+            {
+                family: profiles ? 'profiles' : 'native-session',
+                scope: 'owner',
+                ownerId,
+            },
+        ];
+    const nodeId = target.executionNodeId ?? 'local';
+    if (profiles)
+        return [{ family: 'profiles', nodeId, ownerId }];
+    return [
+        {
+            family: 'native-session',
+            nodeId,
+            ownerId,
+            ...(target.sessionId ? { sessionId: target.sessionId } : {}),
+            ...(target.worker ? { workerId: target.worker.runId } : {}),
+        },
+    ];
+}
+/** Reject cursor/limit variants at registration. They belong only to readNativeHistory. */
+export function nativeHistoryParams(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Native history requires a target.');
+    const target = value;
+    if (Object.keys(value).some((key) => !['sessionId', 'executionNodeId', 'worker'].includes(key)))
+        throw new Error('Native history observations cannot contain cursors or page limits.');
+    if (!target.sessionId || typeof target.sessionId !== 'string')
+        throw new Error('Native history requires sessionId.');
+    if (target.worker &&
+        ['runId', 'contextId', 'generation', 'leaseId'].some((key) => typeof Reflect.get(target.worker, key) !== 'string' || !Reflect.get(target.worker, key)))
+        throw new Error('Native worker history requires the complete pinned binding.');
+    return {
+        sessionId: target.sessionId,
+        executionNodeId: target.executionNodeId ?? 'local',
+        ...(target.worker ? { worker: target.worker } : {}),
+    };
+}
+/** Durable retention counts sessions, while in-memory observation identity keeps the lease pin. */
+export function nativeHistoryStorageId(query) {
+    if (query.method !== Methods.NATIVE_SESSION_READ)
+        return query.id;
+    const target = nativeHistoryParams(query.params);
+    return `${Methods.NATIVE_SESSION_READ}:${JSON.stringify({ executionNodeId: target.executionNodeId, sessionId: target.sessionId })}`;
+}
+export function storedNativeHistoryMatches(target, value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const page = value;
+    return (page.session?.id === target.sessionId &&
+        page.session.executionNodeId === (target.executionNodeId ?? 'local') &&
+        Array.isArray(page.events) &&
+        Number.isSafeInteger(page.cursor) &&
+        (!target.worker ||
+            (page.scope?.leaseId === target.worker.leaseId &&
+                page.session.workerLeaseId === target.worker.leaseId &&
+                page.session.generation === target.worker.generation)));
+}
+export function nativeHistoryCanAct(observation, rendered, connected) {
+    return (connected &&
+        observation?.status === 'ready' &&
+        !!rendered &&
+        observation.data === rendered &&
+        !rendered.hasMore);
+}
+//# sourceMappingURL=native-history.js.map

package/dist/client-cache/native-history.js.map

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

package/dist/client-cache/prefetch.d.ts

@@ -0,0 +1,50 @@
+import type { Run } from '../contracts/runs.js';
+import type { GitDiffResult } from '../rpc/git.js';
+import { type ResourceQuery } from './registry.js';
+import type { GatewayResourceCache, ResourceCacheTransport } from './types.js';
+/** A pending gate or an active run the client lists. */
+export interface ContentPrefetchTarget {
+    runId: string;
+    gate: boolean;
+    /** Orders runs of the same kind, most recent first. */
+    updatedAt?: string | number;
+}
+/** A retained run artifact, read from `/api/run-artifact` with its bundle digest. */
+export interface ContentPrefetchArtifact {
+    runId: string;
+    path: string;
+    bundleDigest?: string;
+}
+export interface ContentPrefetchOptions {
+    /** The cache's transport: connection, capabilities and resource changes. */
+    transport: Pick<ResourceCacheTransport, 'getConnection' | 'onConnectionChange' | 'onResourceChanged'>;
+    cache: Pick<GatewayResourceCache, 'retry' | 'readContent' | 'storeContent' | 'retainContent' | 'contentWriteToken'>;
+    /** Plain RPC for reads that are not stored queries: `git.show`, `git.log` and frozen `git.diff`. */
+    request<T>(method: string, params: unknown, signal: AbortSignal): Promise<T>;
+    /** Raw bytes. An authorization refusal rejects with `code: 'AUTH_FORBIDDEN'`. */
+    readArtifact(artifact: ContentPrefetchArtifact, signal: AbortSignal): Promise<Uint8Array>;
+    /** The run's project default branch, for an active run without a stack base (`activeRunDiffBase`). */
+    defaultBranch?(run: Run): string | undefined;
+}
+export interface ContentPrefetcher {
+    /** Replaces the listed runs; a run no longer listed stops. */
+    setTargets(targets: readonly ContentPrefetchTarget[]): void;
+    dispose(): void;
+}
+/**
+ * The base an active run's diff compares with, in the gateway's `publicationBaseForRun` order:
+ * the stack base, then the run's project default branch, then `main`.
+ */
+export declare function activeRunDiffBase<R extends Pick<Run, 'stack'>>(run: R, defaultBranch?: (run: R) => string | undefined): string;
+/** The active-run diff prefetch keeps: merge-base to worktree, with untracked files. */
+export declare function activeRunDiffQuery(params: {
+    slotId: string;
+    runId: string;
+    base: string;
+}): ResourceQuery<GitDiffResult>;
+/**
+ * Experimental Prefetch rules 1 to 6: fills the content cache for pending gates and active runs.
+ * It reads only while the connection advertises `capabilities.batchedContent`, and never on a timer.
+ */
+export declare function createContentPrefetcher(options: ContentPrefetchOptions): ContentPrefetcher;
+//# sourceMappingURL=prefetch.d.ts.map

package/dist/client-cache/prefetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefetch.d.ts","sourceRoot":"","sources":["../../src/client-cache/prefetch.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAA0C,GAAG,EAAE,MAAM,sBAAsB,CAAC;AACxF,OAAO,KAAK,EAAE,aAAa,EAAoC,MAAM,eAAe,CAAC;AAUrF,OAAO,EAAE,KAAK,aAAa,EAAiB,MAAM,eAAe,CAAC;AAElE,OAAO,KAAK,EACV,oBAAoB,EAEpB,sBAAsB,EAIvB,MAAM,YAAY,CAAC;AAEpB,wDAAwD;AACxD,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;IACd,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC7B;AAED,qFAAqF;AACrF,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,SAAS,EAAE,IAAI,CACb,sBAAsB,EACtB,eAAe,GAAG,oBAAoB,GAAG,mBAAmB,CAC7D,CAAC;IACF,KAAK,EAAE,IAAI,CACT,oBAAoB,EACpB,OAAO,GAAG,aAAa,GAAG,cAAc,GAAG,eAAe,GAAG,mBAAmB,CACjF,CAAC;IACF,oGAAoG;IACpG,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAC7E,iFAAiF;IACjF,YAAY,CAAC,QAAQ,EAAE,uBAAuB,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC1F,sGAAsG;IACtG,aAAa,CAAC,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,GAAG,SAAS,CAAC;CAC9C;AAED,MAAM,WAAW,iBAAiB;IAChC,8DAA8D;IAC9D,UAAU,CAAC,OAAO,EAAE,SAAS,qBAAqB,EAAE,GAAG,IAAI,CAAC;IAC5D,OAAO,IAAI,IAAI,CAAC;CACjB;AAkED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,EAC5D,GAAG,EAAE,CAAC,EACN,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,MAAM,GAAG,SAAS,GAC7C,MAAM,CAER;AAED,wFAAwF;AACxF,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,aAAa,CAAC,aAAa,CAAC,CAM/B;AAsBD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,sBAAsB,GAAG,iBAAiB,CA+d1F"}