@hunterzhu/pulse-runtime 0.1.0

package/dist/storage/policy.d.ts

@@ -0,0 +1,80 @@
+import type { JsonValue } from '../core/types.js';
+export type StorageKind = 'event' | 'result' | 'artifact' | 'snapshot';
+export type StorageState = 'memory' | 'persisted' | 'compacted';
+export interface StoragePolicyConfig {
+    maxEventLogBytes?: number;
+    maxResultBytes?: number;
+    maxArtifactBytes?: number;
+    maxSnapshotBytes?: number;
+    maxTotalMemoryBytes?: number;
+}
+export interface StoredRecord {
+    key: string;
+    kind: StorageKind;
+    storageState: StorageState;
+    pinCount: number;
+    bytes: number;
+    hash: string;
+    value?: JsonValue;
+}
+/** Record metadata without the body; safe to hand out without cloning the value. */
+export type StoredRecordInfo = Omit<StoredRecord, 'value'>;
+export interface StoragePolicySnapshot {
+    schemaVersion: 1;
+    limits: Required<StoragePolicyConfig>;
+    records: StoredRecord[];
+    pinSources: Array<[string, string[]]>;
+}
+/**
+ * Session-wide memory accounting for events, results, artifacts and snapshots.
+ *
+ * Records are treated as immutable values: every state change replaces the
+ * record object instead of mutating it. That makes `clone()` a shallow copy of
+ * the maps (copy-on-write), keeps per-kind byte totals as O(1) counters, and
+ * lets `put()` roll back by restoring the handful of records it touched instead
+ * of snapshotting the whole policy. Values are still cloned on the way in and
+ * out, so callers can never alias internal state.
+ */
+export declare class SessionStoragePolicy {
+    private records;
+    private pinSources;
+    /** Reverse index: record key -> number of pin sources holding it. */
+    private managedPins;
+    private readonly limits;
+    private memoryByKind;
+    private memoryTotal;
+    constructor(config?: StoragePolicyConfig);
+    put(kind: StorageKind, key: string, value: JsonValue, pin?: boolean): StoredRecord;
+    get(key: string): JsonValue | undefined;
+    has(key: string): boolean;
+    /** Metadata for one record without cloning its body. */
+    record(key: string): StoredRecordInfo | undefined;
+    pin(key: string): void;
+    unpin(key: string): void;
+    remove(key: string): boolean;
+    /** Replace one logical owner’s pins without double-counting repeated reconciliation. */
+    replacePinSource(source: string, keys: Iterable<string>): void;
+    /** Make a private copy suitable for validate-stage storage admission. Shallow: records are immutable and shared. */
+    clone(): SessionStoragePolicy;
+    /** Adopt the state of a clone produced by `clone()` after it has been mutated as a candidate. */
+    adopt(candidate: SessionStoragePolicy): void;
+    snapshot(): StoragePolicySnapshot;
+    /** Atomically replace this policy with a previously validated candidate snapshot. */
+    replaceSnapshot(snapshot: StoragePolicySnapshot): void;
+    static fromSnapshot(snapshot: StoragePolicySnapshot | JsonValue): SessionStoragePolicy;
+    compact(key: string): boolean;
+    /** Mark records durable only after the persistence backend has acknowledged the snapshot. */
+    markPersisted(keys?: Iterable<string>): void;
+    inspect(): StoredRecord[];
+    /** Keys of all records, without copying bodies. */
+    keys(): IterableIterator<string>;
+    get memoryBytesTotal(): number;
+    private compactToFit;
+    /** Install a record and keep the byte counters in sync with its residency. */
+    private set;
+    private unset;
+    private kindLimit;
+    private require;
+    private copyRecord;
+    private restore;
+}

package/dist/storage/policy.js

@@ -0,0 +1,268 @@
+import { contentHash, stableSerialize } from '../context/builder.js';
+const storageLimitKeys = ['maxEventLogBytes', 'maxResultBytes', 'maxArtifactBytes', 'maxSnapshotBytes', 'maxTotalMemoryBytes'];
+function validStorageLimits(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const limits = value;
+    return storageLimitKeys.every((key) => Number.isInteger(limits[key]) && limits[key] >= 0);
+}
+function validStoragePolicySnapshot(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const snapshot = value;
+    if (snapshot.schemaVersion !== 1 || !validStorageLimits(snapshot.limits) || !Array.isArray(snapshot.records) || !Array.isArray(snapshot.pinSources))
+        return false;
+    const keys = new Set();
+    for (const record of snapshot.records) {
+        if (!record || typeof record.key !== 'string' || record.key.length === 0 || keys.has(record.key) || !['event', 'result', 'artifact', 'snapshot'].includes(record.kind) || !['memory', 'persisted', 'compacted'].includes(record.storageState) || !Number.isInteger(record.pinCount) || record.pinCount < 0 || !Number.isInteger(record.bytes) || record.bytes < 0 || !/^[a-f0-9]{64}$/.test(record.hash) || (record.kind === 'event' && record.storageState === 'compacted') || (record.storageState === 'memory' && record.value === undefined) || (record.storageState !== 'memory' && record.value !== undefined))
+            return false;
+        if (record.value !== undefined) {
+            try {
+                if (Buffer.byteLength(stableSerialize(record.value), 'utf8') !== record.bytes || contentHash(record.value) !== record.hash)
+                    return false;
+            }
+            catch {
+                return false;
+            }
+        }
+        keys.add(record.key);
+    }
+    const sources = new Set();
+    const managedPins = new Map();
+    for (const entry of snapshot.pinSources) {
+        if (!Array.isArray(entry) || entry.length !== 2 || typeof entry[0] !== 'string' || entry[0].length === 0 || sources.has(entry[0]) || !Array.isArray(entry[1]) || new Set(entry[1]).size !== entry[1].length || entry[1].some((key) => typeof key !== 'string' || key.length === 0))
+            return false;
+        sources.add(entry[0]);
+        for (const key of entry[1])
+            managedPins.set(key, (managedPins.get(key) ?? 0) + 1);
+    }
+    for (const record of snapshot.records)
+        if (record.pinCount < (managedPins.get(record.key) ?? 0))
+            return false;
+    return true;
+}
+/**
+ * Session-wide memory accounting for events, results, artifacts and snapshots.
+ *
+ * Records are treated as immutable values: every state change replaces the
+ * record object instead of mutating it. That makes `clone()` a shallow copy of
+ * the maps (copy-on-write), keeps per-kind byte totals as O(1) counters, and
+ * lets `put()` roll back by restoring the handful of records it touched instead
+ * of snapshotting the whole policy. Values are still cloned on the way in and
+ * out, so callers can never alias internal state.
+ */
+export class SessionStoragePolicy {
+    records = new Map();
+    pinSources = new Map();
+    /** Reverse index: record key -> number of pin sources holding it. */
+    managedPins = new Map();
+    limits;
+    memoryByKind = { event: 0, result: 0, artifact: 0, snapshot: 0 };
+    memoryTotal = 0;
+    constructor(config = {}) {
+        const limits = { maxEventLogBytes: config.maxEventLogBytes ?? 1_000_000, maxResultBytes: config.maxResultBytes ?? 1_000_000, maxArtifactBytes: config.maxArtifactBytes ?? 4_000_000, maxSnapshotBytes: config.maxSnapshotBytes ?? 1_000_000, maxTotalMemoryBytes: config.maxTotalMemoryBytes ?? 4_000_000 };
+        if (!validStorageLimits(limits))
+            throw new Error('INVALID_STORAGE_POLICY_LIMITS');
+        this.limits = limits;
+    }
+    put(kind, key, value, pin = false) {
+        const bytes = Buffer.byteLength(stableSerialize(value));
+        const hash = contentHash(value);
+        const previous = this.records.get(key);
+        if (previous && previous.kind !== kind)
+            throw new Error('STORAGE_KEY_KIND_CONFLICT');
+        const managedPin = previous === undefined ? this.managedPins.get(key) ?? 0 : 0;
+        const unchanged = previous !== undefined && previous.bytes === bytes && previous.hash === hash;
+        const storageState = unchanged ? previous.storageState : 'memory';
+        const record = { key, kind, storageState, pinCount: (previous?.pinCount ?? 0) + (pin ? 1 : 0) + managedPin, bytes, hash, ...(storageState === 'memory' ? { value: unchanged && previous.value !== undefined ? previous.value : structuredClone(value) } : {}) };
+        const touched = new Map([[key, previous]]);
+        this.set(record);
+        this.compactToFit(kind, key, touched);
+        if (this.memoryByKind[kind] > this.kindLimit(kind) || this.memoryTotal > this.limits.maxTotalMemoryBytes) {
+            for (const [touchedKey, original] of touched)
+                if (original === undefined)
+                    this.unset(touchedKey);
+                else
+                    this.set(original);
+            throw new Error('SESSION_STORAGE_LIMIT_EXCEEDED');
+        }
+        return this.copyRecord(record);
+    }
+    get(key) {
+        const record = this.records.get(key);
+        return record?.storageState === 'memory' && record.value !== undefined ? structuredClone(record.value) : undefined;
+    }
+    has(key) { return this.records.has(key); }
+    /** Metadata for one record without cloning its body. */
+    record(key) {
+        const record = this.records.get(key);
+        if (!record)
+            return undefined;
+        const { value: _value, ...info } = record;
+        return info;
+    }
+    pin(key) { const record = this.require(key); this.set({ ...record, pinCount: record.pinCount + 1 }); }
+    unpin(key) { const record = this.require(key); this.set({ ...record, pinCount: Math.max(0, record.pinCount - 1) }); }
+    remove(key) {
+        const record = this.records.get(key);
+        if (!record || record.pinCount > 0 || record.kind === 'event')
+            return false;
+        this.unset(key);
+        if (this.managedPins.has(key)) {
+            for (const [source, keys] of this.pinSources) {
+                if (!keys.has(key))
+                    continue;
+                const next = new Set(keys);
+                next.delete(key);
+                if (next.size === 0)
+                    this.pinSources.delete(source);
+                else
+                    this.pinSources.set(source, next);
+            }
+            this.managedPins.delete(key);
+        }
+        return true;
+    }
+    /** Replace one logical owner’s pins without double-counting repeated reconciliation. */
+    replacePinSource(source, keys) {
+        const next = new Set(keys);
+        const previous = this.pinSources.get(source) ?? new Set();
+        for (const key of previous)
+            if (!next.has(key)) {
+                const count = (this.managedPins.get(key) ?? 1) - 1;
+                if (count <= 0)
+                    this.managedPins.delete(key);
+                else
+                    this.managedPins.set(key, count);
+                if (this.records.has(key))
+                    this.unpin(key);
+            }
+        for (const key of next)
+            if (!previous.has(key)) {
+                this.managedPins.set(key, (this.managedPins.get(key) ?? 0) + 1);
+                if (this.records.has(key))
+                    this.pin(key);
+            }
+        if (next.size)
+            this.pinSources.set(source, next);
+        else
+            this.pinSources.delete(source);
+    }
+    /** Make a private copy suitable for validate-stage storage admission. Shallow: records are immutable and shared. */
+    clone() {
+        const copy = new SessionStoragePolicy(this.limits);
+        copy.records = new Map(this.records);
+        copy.pinSources = new Map(this.pinSources);
+        copy.managedPins = new Map(this.managedPins);
+        copy.memoryByKind = { ...this.memoryByKind };
+        copy.memoryTotal = this.memoryTotal;
+        return copy;
+    }
+    /** Adopt the state of a clone produced by `clone()` after it has been mutated as a candidate. */
+    adopt(candidate) {
+        if (storageLimitKeys.some((key) => candidate.limits[key] !== this.limits[key]))
+            throw new Error('STORAGE_POLICY_LIMITS_MISMATCH');
+        this.records = new Map(candidate.records);
+        this.pinSources = new Map(candidate.pinSources);
+        this.managedPins = new Map(candidate.managedPins);
+        this.memoryByKind = { ...candidate.memoryByKind };
+        this.memoryTotal = candidate.memoryTotal;
+    }
+    snapshot() { return { schemaVersion: 1, limits: { ...this.limits }, records: [...this.records.values()].map((record) => this.copyRecord(record)), pinSources: [...this.pinSources.entries()].map(([source, keys]) => [source, [...keys]]) }; }
+    /** Atomically replace this policy with a previously validated candidate snapshot. */
+    replaceSnapshot(snapshot) {
+        if (!validStoragePolicySnapshot(snapshot))
+            throw new Error('INVALID_STORAGE_POLICY_SNAPSHOT');
+        this.restore(snapshot);
+    }
+    static fromSnapshot(snapshot) {
+        const value = snapshot;
+        if (!validStoragePolicySnapshot(value))
+            throw new Error('INVALID_STORAGE_POLICY_SNAPSHOT');
+        const policy = new SessionStoragePolicy(value.limits);
+        policy.restore(value);
+        return policy;
+    }
+    compact(key) {
+        const record = this.require(key);
+        if (record.kind === 'event')
+            throw new Error('FACT_EVENT_REQUIRES_PERSISTENCE');
+        if (record.pinCount > 0 || record.storageState === 'compacted')
+            return false;
+        const { value: _value, ...rest } = record;
+        this.set({ ...rest, storageState: 'compacted' });
+        return true;
+    }
+    /** Mark records durable only after the persistence backend has acknowledged the snapshot. */
+    markPersisted(keys) {
+        const selected = keys === undefined ? [...this.records.keys()] : [...keys];
+        for (const key of selected) {
+            const record = this.require(key);
+            if (record.storageState === 'compacted')
+                continue;
+            const { value: _value, ...rest } = record;
+            this.set({ ...rest, storageState: 'persisted' });
+        }
+    }
+    inspect() { return [...this.records.values()].map((record) => this.copyRecord(record)); }
+    /** Keys of all records, without copying bodies. */
+    keys() { return this.records.keys(); }
+    get memoryBytesTotal() { return this.memoryTotal; }
+    compactToFit(kind, protectedKey, touched) {
+        while (this.memoryByKind[kind] > this.kindLimit(kind) || this.memoryTotal > this.limits.maxTotalMemoryBytes) {
+            let candidate;
+            for (const record of this.records.values())
+                if (record.key !== protectedKey && record.storageState === 'memory' && record.pinCount === 0 && record.kind !== 'event') {
+                    candidate = record;
+                    break;
+                }
+            if (!candidate)
+                break;
+            if (!touched.has(candidate.key))
+                touched.set(candidate.key, candidate);
+            if (!this.compact(candidate.key))
+                break;
+        }
+    }
+    /** Install a record and keep the byte counters in sync with its residency. */
+    set(record) {
+        const previous = this.records.get(record.key);
+        if (previous?.storageState === 'memory') {
+            this.memoryByKind[previous.kind] -= previous.bytes;
+            this.memoryTotal -= previous.bytes;
+        }
+        if (record.storageState === 'memory') {
+            this.memoryByKind[record.kind] += record.bytes;
+            this.memoryTotal += record.bytes;
+        }
+        this.records.set(record.key, record);
+    }
+    unset(key) {
+        const previous = this.records.get(key);
+        if (!previous)
+            return;
+        if (previous.storageState === 'memory') {
+            this.memoryByKind[previous.kind] -= previous.bytes;
+            this.memoryTotal -= previous.bytes;
+        }
+        this.records.delete(key);
+    }
+    kindLimit(kind) { return kind === 'event' ? this.limits.maxEventLogBytes : kind === 'result' ? this.limits.maxResultBytes : kind === 'artifact' ? this.limits.maxArtifactBytes : this.limits.maxSnapshotBytes; }
+    require(key) { const record = this.records.get(key); if (!record)
+        throw new Error(`UNKNOWN_STORAGE_KEY:${key}`); return record; }
+    copyRecord(record) { return { ...record, ...(record.value === undefined ? {} : { value: structuredClone(record.value) }) }; }
+    restore(snapshot) {
+        this.records = new Map();
+        this.memoryByKind = { event: 0, result: 0, artifact: 0, snapshot: 0 };
+        this.memoryTotal = 0;
+        for (const record of snapshot.records)
+            this.set(this.copyRecord(record));
+        this.pinSources = new Map();
+        this.managedPins = new Map();
+        for (const [source, keys] of snapshot.pinSources) {
+            this.pinSources.set(source, new Set(keys));
+            for (const key of keys)
+                this.managedPins.set(key, (this.managedPins.get(key) ?? 0) + 1);
+        }
+    }
+}

package/dist/storage/session.d.ts

@@ -0,0 +1,140 @@
+import type { AgentRecord, ArtifactRecord, EffectRecord, JsonValue, LaneRecord, MergeProposal, PrivacyLabel, PrivacyMetadata, ResultRecord, RuntimeEvent, RuntimeState, WaitRecord, ToolCallCorrelation } from '../core/types.js';
+export interface SessionSnapshot {
+    schemaVersion: 1;
+    state: {
+        now: number;
+        agents: Array<[string, Omit<AgentRecord, 'globalVersions' | 'globalPrivacy'> & {
+            globalVersions: Array<[number, JsonValue]>;
+            globalPrivacy?: Array<[number, PrivacyMetadata]>;
+        }]>;
+        lanes: Array<[string, Omit<LaneRecord, 'children' | 'ownedEffectIds' | 'visibleResultRefs'> & {
+            children: string[];
+            ownedEffectIds: string[];
+            visibleResultRefs?: string[];
+        }]>;
+        effects: Array<[string, EffectRecord]>;
+        waits: Array<[string, WaitRecord]>;
+        results: Array<[string, ResultRecord]>;
+        artifacts?: Array<[string, ArtifactRecord]>;
+        toolCallCorrelations?: Array<[string, ToolCallCorrelation]>;
+        mergeProposals: Array<[string, MergeProposal]>;
+        events: RuntimeEvent[];
+        eventsCompactedThrough?: number;
+        nextIds: RuntimeState['nextIds'];
+        maxTotalLanes: number;
+        maxQueuedEffects: number;
+        maxRunning: Record<'llm' | 'tool' | 'agent' | 'none', number | 'Infinity'>;
+        forkAffinity?: 'off' | 'advise' | 'coalesce';
+        historySoftTokens?: number;
+        historyHardTokens?: number;
+        maxResultSummaryBytes?: number;
+        trustedSanitizerIds?: string[];
+    };
+}
+export interface RuntimeWarmStartSnapshot {
+    schemaVersion: 1;
+    sessionId: string;
+    agent: {
+        rootLaneId: string;
+        latestGlobalVersion: number;
+        globalVersions: Array<[number, JsonValue]>;
+        globalPrivacy?: Array<[number, PrivacyMetadata]>;
+    };
+    visibleResultRefs: string[];
+    results: Array<[string, ResultRecord]>;
+}
+export interface RuntimeSessionStore {
+    get(sessionId: string): RuntimeWarmStartSnapshot | undefined;
+    put(snapshot: RuntimeWarmStartSnapshot): void;
+}
+export interface RuntimeSessionRevision {
+    snapshot: RuntimeWarmStartSnapshot;
+    revision: number;
+}
+export interface VersionedRuntimeSessionStore extends RuntimeSessionStore {
+    getWithRevision(sessionId: string): RuntimeSessionRevision | undefined;
+    putIfRevision(snapshot: RuntimeWarmStartSnapshot, expectedRevision?: number): number;
+}
+export declare class InMemoryRuntimeSessionStore implements RuntimeSessionStore {
+    private readonly snapshots;
+    get(sessionId: string): RuntimeWarmStartSnapshot | undefined;
+    put(snapshot: RuntimeWarmStartSnapshot): void;
+    getWithRevision(sessionId: string): RuntimeSessionRevision | undefined;
+    putIfRevision(snapshot: RuntimeWarmStartSnapshot, expectedRevision?: number): number;
+}
+/** Durable synchronous Session Store for hosts that need createAgent() to remain synchronous. */
+export declare class FileRuntimeSessionStore implements VersionedRuntimeSessionStore {
+    readonly filePath: string;
+    constructor(filePath: string);
+    get(sessionId: string): RuntimeWarmStartSnapshot | undefined;
+    getWithRevision(sessionId: string): RuntimeSessionRevision | undefined;
+    put(snapshot: RuntimeWarmStartSnapshot): void;
+    putIfRevision(snapshot: RuntimeWarmStartSnapshot, expectedRevision?: number): number;
+    private readEnvelope;
+    private writeEnvelope;
+    private withLock;
+}
+/** Durable SQLite Session Store with transaction-scoped revision CAS. */
+export declare class SqliteRuntimeSessionStore implements VersionedRuntimeSessionStore {
+    readonly filePath: string;
+    private database;
+    constructor(filePath: string);
+    get(sessionId: string): RuntimeWarmStartSnapshot | undefined;
+    getWithRevision(sessionId: string): RuntimeSessionRevision | undefined;
+    put(snapshot: RuntimeWarmStartSnapshot): void;
+    putIfRevision(snapshot: RuntimeWarmStartSnapshot, expectedRevision?: number): number;
+    close(): void;
+    private open;
+}
+export interface SessionLogExportOptions {
+    maxPrivacy?: PrivacyLabel;
+}
+export type SessionLogResult = Omit<ResultRecord, 'value' | 'summary'> & {
+    value?: JsonValue;
+    summary?: JsonValue;
+    redacted?: boolean;
+};
+export type SessionLogArtifact = Omit<ArtifactRecord, 'contentBase64'> & {
+    contentBase64?: string;
+    redacted?: boolean;
+};
+export interface SessionLogExport {
+    schemaVersion: 1;
+    maxPrivacy: PrivacyLabel;
+    events: RuntimeEvent[];
+    results: SessionLogResult[];
+    artifacts: SessionLogArtifact[];
+}
+export interface RuntimeLogSink {
+    append(log: SessionLogExport): Promise<void> | void;
+}
+/** A durable JSONL audit sink. Each successfully returned append is fsync'd. */
+export declare class FileRuntimeLogSink implements RuntimeLogSink {
+    readonly filePath: string;
+    private pending;
+    constructor(filePath: string);
+    append(log: SessionLogExport): Promise<void>;
+}
+export interface HttpRuntimeLogSinkOptions {
+    endpoint: string;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+    fetch?: typeof globalThis.fetch;
+}
+/** Sends privacy-filtered audit exports to a host-owned collector. */
+export declare class HttpRuntimeLogSink implements RuntimeLogSink {
+    private readonly endpoint;
+    private readonly headers;
+    private readonly timeoutMs;
+    private readonly fetcher;
+    constructor(options: HttpRuntimeLogSinkOptions);
+    append(log: SessionLogExport): Promise<void>;
+}
+export declare function exportRuntimeState(state: RuntimeState): SessionSnapshot;
+export declare function exportWarmStartSession(state: RuntimeState, sessionId: string): RuntimeWarmStartSnapshot;
+/** Export audit/log data with an explicit privacy ceiling; this is not a recovery snapshot. */
+export declare function exportRuntimeLog(state: RuntimeState, options?: SessionLogExportOptions): SessionLogExport;
+/** Applies the privacy ceiling before handing an audit export to its sink. */
+export declare function exportRuntimeLogTo(state: RuntimeState, sink: RuntimeLogSink, options?: SessionLogExportOptions): Promise<SessionLogExport>;
+export declare function serializeRuntimeState(state: RuntimeState): JsonValue;
+export declare function importRuntimeState(snapshot: SessionSnapshot | JsonValue): RuntimeState;