@hunterzhu/pulse-runtime 0.1.0

package/dist/storage/session.js

@@ -0,0 +1,447 @@
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { mkdir, open } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname } from 'node:path';
+import { privacyRank } from '../core/types.js';
+import { createRuntimeState } from '../core/types.js';
+import { normalizeRuntimeEvent } from '../core/events.js';
+export class InMemoryRuntimeSessionStore {
+    snapshots = new Map();
+    get(sessionId) { return this.getWithRevision(sessionId)?.snapshot; }
+    put(snapshot) { this.putIfRevision(snapshot); }
+    getWithRevision(sessionId) {
+        const entry = this.snapshots.get(sessionId);
+        return entry === undefined ? undefined : { revision: entry.revision, snapshot: structuredClone(entry.snapshot) };
+    }
+    putIfRevision(snapshot, expectedRevision) {
+        validateWarmStartSnapshot(snapshot);
+        const current = this.snapshots.get(snapshot.sessionId);
+        if (expectedRevision !== undefined && current?.revision !== expectedRevision)
+            throw new Error('RUNTIME_SESSION_STORE_CONFLICT');
+        const revision = (current?.revision ?? 0) + 1;
+        this.snapshots.set(snapshot.sessionId, { revision, snapshot: structuredClone(snapshot) });
+        return revision;
+    }
+}
+function validProvenance(value) {
+    if (typeof value === 'string')
+        return value.length > 0;
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const ref = value;
+    return (ref.kind === 'result' || ref.kind === 'artifact') && typeof ref.ref === 'string' && ref.ref.length > 0;
+}
+function validPrivacyMetadata(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const metadata = value;
+    if (!['public', 'cloud_allowed', 'local_only'].includes(String(metadata.privacy)))
+        return false;
+    const taints = metadata.privacyTaints;
+    return taints === undefined || (Array.isArray(taints) && taints.every((taint) => taint && typeof taint === 'object' && Array.isArray(taint.path) && taint.path.length > 0 && taint.path.every((part) => typeof part === 'string' && part.length > 0) && ['public', 'cloud_allowed', 'local_only'].includes(String(taint.privacy))));
+}
+function validateWarmStartSnapshot(snapshot) {
+    if (!snapshot || snapshot.schemaVersion !== 1 || typeof snapshot.sessionId !== 'string' || snapshot.sessionId.length === 0 || !snapshot.agent || typeof snapshot.agent.rootLaneId !== 'string' || snapshot.agent.rootLaneId.length === 0 || !Number.isInteger(snapshot.agent.latestGlobalVersion) || snapshot.agent.latestGlobalVersion < 0 || !Array.isArray(snapshot.agent.globalVersions) || !Array.isArray(snapshot.visibleResultRefs) || !Array.isArray(snapshot.results))
+        throw new Error('INVALID_RUNTIME_SESSION_SNAPSHOT');
+    const versions = new Set();
+    for (const entry of snapshot.agent.globalVersions) {
+        if (!Array.isArray(entry) || entry.length !== 2 || !Number.isInteger(entry[0]) || entry[0] < 0 || versions.has(entry[0]) || entry[1] === undefined)
+            throw new Error('INVALID_RUNTIME_SESSION_SNAPSHOT');
+        versions.add(entry[0]);
+    }
+    if (!versions.has(snapshot.agent.latestGlobalVersion))
+        throw new Error('INVALID_RUNTIME_SESSION_SNAPSHOT');
+    if (snapshot.agent.globalPrivacy !== undefined) {
+        const privacyVersions = new Set();
+        for (const entry of snapshot.agent.globalPrivacy) {
+            if (!Array.isArray(entry) || entry.length !== 2 || !Number.isInteger(entry[0]) || entry[0] < 0 || privacyVersions.has(entry[0]) || !versions.has(entry[0]) || !validPrivacyMetadata(entry[1]))
+                throw new Error('INVALID_RUNTIME_SESSION_SNAPSHOT');
+            privacyVersions.add(entry[0]);
+        }
+    }
+    if (new Set(snapshot.visibleResultRefs).size !== snapshot.visibleResultRefs.length || snapshot.visibleResultRefs.some((ref) => typeof ref !== 'string' || ref.length === 0))
+        throw new Error('INVALID_RUNTIME_SESSION_SNAPSHOT');
+    const resultRefs = new Set();
+    for (const entry of snapshot.results) {
+        if (!Array.isArray(entry) || entry.length !== 2 || typeof entry[0] !== 'string' || entry[0].length === 0 || resultRefs.has(entry[0]))
+            throw new Error('INVALID_RUNTIME_SESSION_SNAPSHOT');
+        const result = entry[1];
+        if (!result || result.id !== entry[0] || !validPrivacyMetadata(result) || !Array.isArray(result.derivedFrom) || result.derivedFrom.some((ref) => !validProvenance(ref)) || (result.pinCount !== undefined && (!Number.isInteger(result.pinCount) || result.pinCount < 0)) || (result.sizeBytes !== undefined && (!Number.isInteger(result.sizeBytes) || result.sizeBytes < 0)) || (result.storageState !== undefined && !['memory', 'persisted'].includes(result.storageState)))
+            throw new Error('INVALID_RUNTIME_SESSION_SNAPSHOT');
+        resultRefs.add(entry[0]);
+    }
+    if (snapshot.visibleResultRefs.some((ref) => !resultRefs.has(ref)))
+        throw new Error('INVALID_RUNTIME_SESSION_SNAPSHOT');
+}
+function emptyRuntimeSessionEnvelope() { return { schemaVersion: 1, sessions: [] }; }
+/** Durable synchronous Session Store for hosts that need createAgent() to remain synchronous. */
+export class FileRuntimeSessionStore {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    get(sessionId) { return this.getWithRevision(sessionId)?.snapshot; }
+    getWithRevision(sessionId) {
+        const entry = this.readEnvelope().sessions.find((candidate) => candidate.sessionId === sessionId);
+        return entry === undefined ? undefined : { revision: entry.revision, snapshot: structuredClone(entry.snapshot) };
+    }
+    put(snapshot) { this.putIfRevision(snapshot); }
+    putIfRevision(snapshot, expectedRevision) {
+        validateWarmStartSnapshot(snapshot);
+        return this.withLock(() => {
+            const envelope = this.readEnvelope();
+            const current = envelope.sessions.find((candidate) => candidate.sessionId === snapshot.sessionId);
+            if (expectedRevision !== undefined && current?.revision !== expectedRevision)
+                throw new Error('RUNTIME_SESSION_STORE_CONFLICT');
+            const revision = (current?.revision ?? 0) + 1;
+            const next = { sessionId: snapshot.sessionId, revision, snapshot: structuredClone(snapshot) };
+            envelope.sessions = current === undefined ? [...envelope.sessions, next] : envelope.sessions.map((candidate) => candidate.sessionId === snapshot.sessionId ? next : candidate);
+            this.writeEnvelope(envelope);
+            return revision;
+        });
+    }
+    readEnvelope() {
+        try {
+            const parsed = JSON.parse(readFileSync(this.filePath, 'utf8'));
+            if (!parsed || parsed.schemaVersion !== 1 || !Array.isArray(parsed.sessions))
+                throw new Error('INVALID_RUNTIME_SESSION_STORE');
+            for (const entry of parsed.sessions) {
+                if (!entry || typeof entry.sessionId !== 'string' || !Number.isInteger(entry.revision) || entry.revision < 1)
+                    throw new Error('INVALID_RUNTIME_SESSION_STORE');
+                validateWarmStartSnapshot(entry.snapshot);
+            }
+            return parsed;
+        }
+        catch (cause) {
+            if (cause.code === 'ENOENT')
+                return emptyRuntimeSessionEnvelope();
+            if (cause instanceof Error && (cause.message === 'INVALID_RUNTIME_SESSION_STORE' || cause.message === 'INVALID_RUNTIME_SESSION_SNAPSHOT'))
+                throw cause;
+            throw new Error('INVALID_RUNTIME_SESSION_STORE');
+        }
+    }
+    writeEnvelope(envelope) {
+        mkdirSync(dirname(this.filePath), { recursive: true });
+        const temporaryPath = `${this.filePath}.tmp-${process.pid}-${Date.now()}-${process.hrtime.bigint().toString()}`;
+        let handle;
+        try {
+            handle = openSync(temporaryPath, 'wx', 0o600);
+            writeFileSync(handle, JSON.stringify(envelope), 'utf8');
+            fsyncSync(handle);
+            closeSync(handle);
+            handle = undefined;
+            renameSync(temporaryPath, this.filePath);
+        }
+        finally {
+            if (handle !== undefined)
+                closeSync(handle);
+            rmSync(temporaryPath, { force: true });
+        }
+    }
+    withLock(work) {
+        mkdirSync(dirname(this.filePath), { recursive: true });
+        const lockPath = `${this.filePath}.lock`;
+        const deadline = Date.now() + 30_000;
+        const sleeper = new Int32Array(new SharedArrayBuffer(4));
+        let lock;
+        while (lock === undefined) {
+            try {
+                lock = openSync(lockPath, 'wx', 0o600);
+            }
+            catch (cause) {
+                if (cause.code !== 'EEXIST')
+                    throw cause;
+                const lockStat = statSync(lockPath, { throwIfNoEntry: false });
+                if (lockStat && Date.now() - lockStat.mtimeMs > 30_000) {
+                    rmSync(lockPath, { force: true });
+                    continue;
+                }
+                if (Date.now() >= deadline)
+                    throw new Error('RUNTIME_SESSION_STORE_LOCK_TIMEOUT');
+                Atomics.wait(sleeper, 0, 0, 5);
+            }
+        }
+        try {
+            return work();
+        }
+        finally {
+            closeSync(lock);
+            rmSync(lockPath, { force: true });
+        }
+    }
+}
+/** Durable SQLite Session Store with transaction-scoped revision CAS. */
+export class SqliteRuntimeSessionStore {
+    filePath;
+    database;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    get(sessionId) { return this.getWithRevision(sessionId)?.snapshot; }
+    getWithRevision(sessionId) {
+        const row = this.open().prepare('SELECT revision, snapshot FROM runtime_sessions WHERE session_id = ?').get(sessionId);
+        if (!row || typeof row.revision !== 'number' || typeof row.snapshot !== 'string')
+            return undefined;
+        const snapshot = JSON.parse(row.snapshot);
+        validateWarmStartSnapshot(snapshot);
+        return { revision: row.revision, snapshot: structuredClone(snapshot) };
+    }
+    put(snapshot) { this.putIfRevision(snapshot); }
+    putIfRevision(snapshot, expectedRevision) {
+        validateWarmStartSnapshot(snapshot);
+        const database = this.open();
+        database.exec('BEGIN IMMEDIATE');
+        try {
+            const current = database.prepare('SELECT revision FROM runtime_sessions WHERE session_id = ?').get(snapshot.sessionId);
+            const currentRevision = current && typeof current.revision === 'number' ? current.revision : undefined;
+            if (expectedRevision !== undefined && currentRevision !== expectedRevision)
+                throw new Error('RUNTIME_SESSION_STORE_CONFLICT');
+            const revision = (currentRevision ?? 0) + 1;
+            database.prepare('INSERT INTO runtime_sessions (session_id, revision, snapshot) VALUES (?, ?, ?) ON CONFLICT(session_id) DO UPDATE SET revision = excluded.revision, snapshot = excluded.snapshot').run(snapshot.sessionId, revision, JSON.stringify(snapshot));
+            database.exec('COMMIT');
+            return revision;
+        }
+        catch (cause) {
+            try {
+                database.exec('ROLLBACK');
+            }
+            catch { /* transaction already closed */ }
+            throw cause;
+        }
+    }
+    close() { this.database?.close(); this.database = undefined; }
+    open() {
+        if (this.database)
+            return this.database;
+        mkdirSync(dirname(this.filePath), { recursive: true });
+        const require = createRequire(import.meta.url);
+        const { DatabaseSync } = require('node:sqlite');
+        this.database = new DatabaseSync(this.filePath);
+        this.database.exec('PRAGMA journal_mode = WAL; PRAGMA synchronous = FULL; PRAGMA busy_timeout = 30000; CREATE TABLE IF NOT EXISTS runtime_sessions (session_id TEXT PRIMARY KEY, revision INTEGER NOT NULL, snapshot TEXT NOT NULL)');
+        return this.database;
+    }
+}
+/** A durable JSONL audit sink. Each successfully returned append is fsync'd. */
+export class FileRuntimeLogSink {
+    filePath;
+    pending = Promise.resolve();
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    async append(log) {
+        const operation = this.pending.then(async () => {
+            await mkdir(dirname(this.filePath), { recursive: true });
+            const handle = await open(this.filePath, 'a', 0o600);
+            try {
+                await handle.writeFile(`${JSON.stringify(log)}\n`, 'utf8');
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+        });
+        this.pending = operation.catch(() => undefined);
+        await operation;
+    }
+}
+/** Sends privacy-filtered audit exports to a host-owned collector. */
+export class HttpRuntimeLogSink {
+    endpoint;
+    headers;
+    timeoutMs;
+    fetcher;
+    constructor(options) {
+        if (!options.endpoint)
+            throw new Error('RUNTIME_LOG_ENDPOINT_REQUIRED');
+        this.endpoint = options.endpoint;
+        this.headers = { 'content-type': 'application/json', ...(options.headers ?? {}) };
+        this.timeoutMs = options.timeoutMs ?? 10_000;
+        if (!Number.isFinite(this.timeoutMs) || this.timeoutMs <= 0)
+            throw new Error('INVALID_RUNTIME_LOG_TIMEOUT');
+        this.fetcher = options.fetch ?? globalThis.fetch;
+    }
+    async append(log) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const response = await this.fetcher(this.endpoint, { method: 'POST', headers: this.headers, body: JSON.stringify(log), signal: controller.signal });
+            if (!response.ok)
+                throw new Error(`RUNTIME_LOG_HTTP_${response.status}`);
+        }
+        catch (cause) {
+            if (controller.signal.aborted)
+                throw new Error('RUNTIME_LOG_HTTP_TIMEOUT');
+            throw cause;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+function encodeNumber(value) { return Number.isFinite(value) ? value : 'Infinity'; }
+function decodeNumber(value) {
+    if (value === 'Infinity')
+        return Number.POSITIVE_INFINITY;
+    if (typeof value !== 'number' || Number.isNaN(value))
+        throw new Error('INVALID_SESSION_SNAPSHOT');
+    return value;
+}
+function validateStateConfiguration(value) {
+    const nonNegativeInteger = (candidate) => Number.isInteger(candidate) && candidate >= 0;
+    if (typeof value.now !== 'number' || !Number.isFinite(value.now) || !nonNegativeInteger(value.maxTotalLanes) || !nonNegativeInteger(value.maxQueuedEffects) || !nonNegativeInteger(value.historySoftTokens ?? 0) || !nonNegativeInteger(value.historyHardTokens ?? 0) || !nonNegativeInteger(value.maxResultSummaryBytes ?? 0))
+        throw new Error('INVALID_SESSION_SNAPSHOT');
+    if (value.historyHardTokens !== undefined && value.historySoftTokens !== undefined && value.historyHardTokens < value.historySoftTokens)
+        throw new Error('INVALID_SESSION_SNAPSHOT');
+    if (value.forkAffinity !== undefined && !['off', 'advise', 'coalesce'].includes(value.forkAffinity))
+        throw new Error('INVALID_SESSION_SNAPSHOT');
+    for (const key of ['llm', 'tool', 'agent'])
+        if (!nonNegativeInteger(decodeNumber(value.maxRunning?.[key])))
+            throw new Error('INVALID_SESSION_SNAPSHOT');
+    if (value.maxRunning?.none !== 'Infinity' && !nonNegativeInteger(decodeNumber(value.maxRunning?.none)))
+        throw new Error('INVALID_SESSION_SNAPSHOT');
+    const ids = ['agent', 'lane', 'effect', 'wait', 'result', 'artifact', 'proposal', 'event'];
+    if (!value.nextIds || ids.some((key) => !Number.isInteger(value.nextIds[key]) || value.nextIds[key] < 1))
+        throw new Error('INVALID_SESSION_SNAPSHOT');
+    if (value.trustedSanitizerIds !== undefined && (!Array.isArray(value.trustedSanitizerIds) || new Set(value.trustedSanitizerIds).size !== value.trustedSanitizerIds.length || value.trustedSanitizerIds.some((id) => typeof id !== 'string' || id.length === 0)))
+        throw new Error('INVALID_SESSION_SNAPSHOT');
+}
+export function exportRuntimeState(state) {
+    return {
+        schemaVersion: 1,
+        state: {
+            now: state.now,
+            agents: [...state.agents.entries()].map(([id, agent]) => [id, { ...agent, globalVersions: [...agent.globalVersions.entries()].map(([version, value]) => [version, structuredClone(value)]), ...(agent.globalPrivacy === undefined ? {} : { globalPrivacy: [...agent.globalPrivacy.entries()].map(([version, metadata]) => [version, structuredClone(metadata)]) }) }]),
+            lanes: [...state.lanes.entries()].map(([id, lane]) => [id, { ...structuredClone(lane), children: [...lane.children], ownedEffectIds: [...lane.ownedEffectIds], ...(lane.visibleResultRefs === undefined ? {} : { visibleResultRefs: [...lane.visibleResultRefs] }) }]),
+            effects: [...state.effects.entries()].map(([id, effect]) => [id, structuredClone(effect)]),
+            waits: [...state.waits.entries()].map(([id, wait]) => [id, structuredClone(wait)]),
+            results: [...state.results.entries()].map(([id, result]) => [id, structuredClone(result)]),
+            artifacts: [...state.artifacts.entries()].map(([ref, artifact]) => [ref, structuredClone(artifact)]),
+            toolCallCorrelations: [...state.toolCallCorrelations.entries()].map(([id, correlation]) => [id, structuredClone(correlation)]),
+            mergeProposals: [...state.mergeProposals.entries()].map(([id, proposal]) => [id, structuredClone(proposal)]),
+            events: state.events.map((event) => normalizeRuntimeEvent(event, event.seq, { sessionId: event.sessionId, timestamp: event.timestamp })),
+            ...(state.eventsCompactedThrough === undefined ? {} : { eventsCompactedThrough: state.eventsCompactedThrough }),
+            nextIds: { ...state.nextIds },
+            maxTotalLanes: state.maxTotalLanes,
+            maxQueuedEffects: state.maxQueuedEffects,
+            maxRunning: { llm: encodeNumber(state.maxRunning.llm), tool: encodeNumber(state.maxRunning.tool), agent: encodeNumber(state.maxRunning.agent), none: encodeNumber(state.maxRunning.none) },
+            forkAffinity: state.forkAffinity,
+            historySoftTokens: state.historySoftTokens,
+            historyHardTokens: state.historyHardTokens,
+            maxResultSummaryBytes: state.maxResultSummaryBytes,
+            trustedSanitizerIds: [...state.trustedSanitizerIds].sort(),
+        },
+    };
+}
+export function exportWarmStartSession(state, sessionId) {
+    const agent = state.agents.get(sessionId);
+    if (!agent)
+        throw new Error(`WARM_START_SOURCE_NOT_FOUND:${sessionId}`);
+    const root = state.lanes.get(agent.rootLaneId);
+    const laneIds = new Set([...state.lanes.values()].filter((lane) => lane.agentId === sessionId).map((lane) => lane.id));
+    const effectIds = new Set([...state.effects.values()].filter((effect) => effect.agentId === sessionId).map((effect) => effect.id));
+    const results = [...state.results.entries()].filter(([ref, result]) => (root?.visibleResultRefs?.has(ref) ?? false) || (result.effectId !== undefined && effectIds.has(result.effectId)) || (result.producer?.kind === 'lane' && laneIds.has(result.producer.id)) || (result.producer?.kind === 'effect' && effectIds.has(result.producer.id))).map(([ref, result]) => [ref, structuredClone(result)]);
+    return {
+        schemaVersion: 1,
+        sessionId,
+        agent: {
+            rootLaneId: agent.rootLaneId,
+            latestGlobalVersion: agent.latestGlobalVersion,
+            globalVersions: [...agent.globalVersions.entries()].map(([version, value]) => [version, structuredClone(value)]),
+            ...(agent.globalPrivacy === undefined ? {} : { globalPrivacy: [...agent.globalPrivacy.entries()].map(([version, value]) => [version, structuredClone(value)]) }),
+        },
+        visibleResultRefs: [...(root?.visibleResultRefs ?? [])],
+        results,
+    };
+}
+function relatedEventPrivacy(state, event) {
+    const labels = [];
+    const effect = event.effectId === undefined ? undefined : state.effects.get(event.effectId);
+    if (effect?.input && typeof effect.input === 'object' && !Array.isArray(effect.input)) {
+        const inputPrivacy = effect.input.privacy;
+        if (inputPrivacy === 'public' || inputPrivacy === 'cloud_allowed' || inputPrivacy === 'local_only')
+            labels.push(inputPrivacy);
+    }
+    const resultRefs = [];
+    if (effect?.outcome?.resultRef !== undefined)
+        resultRefs.push(effect.outcome.resultRef);
+    if (event.type === 'lane.succeeded' && typeof event.data === 'string')
+        resultRefs.push(event.data);
+    if (event.type === 'privacy.downgraded' && event.data && typeof event.data === 'object' && !Array.isArray(event.data)) {
+        const outputRef = event.data.outputRef;
+        if (typeof outputRef === 'string')
+            resultRefs.push(outputRef);
+    }
+    for (const ref of resultRefs) {
+        const result = state.results.get(ref);
+        if (result)
+            labels.push(result.privacy);
+    }
+    return labels.length === 0 ? 'local_only' : labels.reduce((current, next) => privacyRank(next) > privacyRank(current) ? next : current, 'public');
+}
+function redactEvent(event, privacy) {
+    return { ...structuredClone(event), payload: { redacted: true, privacy }, data: { redacted: true, privacy } };
+}
+/** Export audit/log data with an explicit privacy ceiling; this is not a recovery snapshot. */
+export function exportRuntimeLog(state, options = {}) {
+    const maxPrivacy = options.maxPrivacy ?? 'public';
+    const allowed = (privacy) => privacyRank(privacy) <= privacyRank(maxPrivacy);
+    const results = [...state.results.values()].map((result) => {
+        const copy = structuredClone(result);
+        if (allowed(copy.privacy))
+            return copy;
+        const { value: _value, summary: _summary, ...metadata } = copy;
+        return { ...metadata, redacted: true };
+    });
+    const artifacts = [...state.artifacts.values()].map((artifact) => {
+        const copy = structuredClone(artifact);
+        if (allowed(copy.privacy))
+            return copy;
+        const { contentBase64: _content, ...metadata } = copy;
+        return { ...metadata, redacted: true };
+    });
+    const events = state.events.map((event) => {
+        const privacy = relatedEventPrivacy(state, event);
+        return allowed(privacy) ? structuredClone(event) : redactEvent(event, privacy);
+    });
+    return { schemaVersion: 1, maxPrivacy, events, results, artifacts };
+}
+/** Applies the privacy ceiling before handing an audit export to its sink. */
+export async function exportRuntimeLogTo(state, sink, options = {}) {
+    const log = exportRuntimeLog(state, options);
+    await sink.append(log);
+    return log;
+}
+export function serializeRuntimeState(state) { return exportRuntimeState(state); }
+export function importRuntimeState(snapshot) {
+    const value = snapshot;
+    if (!value || value.schemaVersion !== 1 || !value.state || !Array.isArray(value.state.agents) || !Array.isArray(value.state.lanes) || !Array.isArray(value.state.effects) || !Array.isArray(value.state.waits) || !Array.isArray(value.state.results) || !Array.isArray(value.state.events) || (value.state.eventsCompactedThrough !== undefined && (!Number.isInteger(value.state.eventsCompactedThrough) || value.state.eventsCompactedThrough < 0)))
+        throw new Error('INVALID_SESSION_SNAPSHOT');
+    validateStateConfiguration(value.state);
+    const state = createRuntimeState(value.state.maxTotalLanes, { maxQueuedEffects: value.state.maxQueuedEffects, maxRunning: { llm: decodeNumber(value.state.maxRunning.llm), tool: decodeNumber(value.state.maxRunning.tool), agent: decodeNumber(value.state.maxRunning.agent), none: decodeNumber(value.state.maxRunning.none) }, forkAffinity: value.state.forkAffinity ?? 'advise', ...(value.state.historySoftTokens === undefined ? {} : { historySoftTokens: value.state.historySoftTokens }), ...(value.state.historyHardTokens === undefined ? {} : { historyHardTokens: value.state.historyHardTokens }), ...(value.state.maxResultSummaryBytes === undefined ? {} : { maxResultSummaryBytes: value.state.maxResultSummaryBytes }), ...(value.state.trustedSanitizerIds === undefined ? {} : { trustedSanitizerIds: value.state.trustedSanitizerIds }) });
+    state.now = value.state.now;
+    state.nextIds = { ...value.state.nextIds, artifact: value.state.nextIds.artifact ?? 1, proposal: value.state.nextIds.proposal ?? 1 };
+    for (const [id, agent] of value.state.agents) {
+        const { globalVersions, globalPrivacy, ...agentValue } = agent;
+        state.agents.set(id, { ...agentValue, globalVersions: new Map(globalVersions.map(([version, context]) => [version, structuredClone(context)])), ...(globalPrivacy === undefined ? {} : { globalPrivacy: new Map(globalPrivacy.map(([version, metadata]) => [version, structuredClone(metadata)])) }) });
+    }
+    for (const [id, lane] of value.state.lanes) {
+        const { visibleResultRefs, ...laneValue } = lane;
+        state.lanes.set(id, { ...laneValue, children: new Set(lane.children), ownedEffectIds: new Set(lane.ownedEffectIds), ...(visibleResultRefs === undefined ? {} : { visibleResultRefs: new Set(visibleResultRefs) }) });
+    }
+    for (const [id, effect] of value.state.effects)
+        state.effects.set(id, structuredClone(effect));
+    for (const [id, wait] of value.state.waits)
+        state.waits.set(id, structuredClone(wait));
+    for (const [id, result] of value.state.results)
+        state.results.set(id, { ...structuredClone(result), storageState: result.storageState ?? 'memory', pinCount: result.pinCount ?? 0 });
+    for (const [ref, artifact] of value.state.artifacts ?? [])
+        state.artifacts.set(ref, structuredClone(artifact));
+    for (const [id, correlation] of value.state.toolCallCorrelations ?? [])
+        state.toolCallCorrelations.set(id, structuredClone(correlation));
+    for (const [id, proposal] of value.state.mergeProposals ?? [])
+        state.mergeProposals.set(id, structuredClone(proposal));
+    state.events = value.state.events.map((event) => normalizeRuntimeEvent(event, event.seq, { sessionId: event.sessionId, timestamp: event.timestamp }));
+    if (value.state.eventsCompactedThrough !== undefined)
+        state.eventsCompactedThrough = value.state.eventsCompactedThrough;
+    return state;
+}

package/dist/tools/registry.d.ts

@@ -0,0 +1,125 @@
+import type { JsonValue, ResourceLockSpec, SideEffectPolicy } from '../core/types.js';
+export interface RuntimeToolPermissions {
+    workspaceRoots?: string[];
+    networkHosts?: string[];
+}
+export interface RuntimeToolManifest {
+    name: string;
+    version: string;
+    description: string;
+    tags?: string[];
+    inputSchema: Record<string, unknown>;
+    outputSchema: Record<string, unknown>;
+    concurrencyClass: 'llm' | 'tool' | 'agent' | 'none';
+    locks: ResourceLockSpec[];
+    resources?: ResourceLockSpec[];
+    supportsAbortSignal: boolean;
+    sideEffectPolicy: SideEffectPolicy;
+    retrySafety: 'read_only' | 'idempotent' | 'unsafe';
+    defaultTimeoutMs: number;
+    maxResultSummaryBytes?: number;
+    permissions?: RuntimeToolPermissions;
+}
+export interface RuntimeToolContext {
+    toolCallId: string;
+    effectId: string;
+    attemptId: string;
+    idempotencyKey?: string;
+    agentId: string;
+    laneId: string;
+    signal: AbortSignal;
+    emit(event: {
+        type: 'progress' | 'warning' | 'diagnostic';
+        data: JsonValue;
+    }): void;
+}
+export interface RuntimeReconcileContext {
+    toolCallId: string;
+    effectId: string;
+    attemptId: string;
+    agentId: string;
+    laneId: string;
+    signal: AbortSignal;
+}
+export interface RuntimeReconcileResult {
+    status: 'succeeded' | 'failed' | 'cancelled' | 'unknown';
+    output?: unknown;
+    error?: {
+        code: string;
+        message: string;
+        retryable?: boolean;
+        details?: JsonValue;
+    };
+}
+export interface RuntimeToolDefinition {
+    manifest: RuntimeToolManifest;
+    resourceAdmissionMode?: 'explicit' | 'default';
+    validateInput?(input: unknown): unknown;
+    execute(input: unknown, context: RuntimeToolContext): Promise<unknown> | unknown;
+    executionRef?(input: unknown, context: RuntimeToolContext): JsonValue;
+    resolveResources?(input: unknown): ResourceLockSpec[];
+    reconcile?(executionRef: JsonValue, context: RuntimeReconcileContext): Promise<RuntimeReconcileResult>;
+    normalize?(output: unknown): JsonValue;
+    summarize?(output: unknown): JsonValue;
+}
+export interface RuntimeToolDiscoveryQuery {
+    text?: string;
+    tags?: string[];
+    sideEffectPolicy?: RuntimeToolManifest['sideEffectPolicy'];
+    concurrencyClass?: RuntimeToolManifest['concurrencyClass'];
+    limit?: number;
+}
+export interface RuntimeToolDiscoveryResult {
+    manifest: RuntimeToolManifest;
+    score: number;
+}
+export interface RuntimeToolSetSnapshot {
+    id: string;
+    version: string;
+    tools: RuntimeToolManifest[];
+}
+export interface RuntimeToolRegistryPolicy {
+    allow?: string[];
+    deny?: string[];
+    workspaceRoots?: string[];
+    networkHosts?: string[];
+    allowNetwork?: boolean;
+}
+export interface RuntimeToolAdmission {
+    locks: ResourceLockSpec[];
+    sideEffectPolicy: RuntimeToolManifest['sideEffectPolicy'];
+    defaultTimeoutMs: number;
+    retrySafety: RuntimeToolManifest['retrySafety'];
+    version: string;
+}
+/**
+ * Core tool catalog used by PulseRuntime. Tool SDK definitions are structurally
+ * compatible, so an application may register them directly and still choose a
+ * separate executor or adapter.
+ */
+export declare class RuntimeToolRegistry {
+    private readonly definitions;
+    private readonly policy;
+    constructor(policy?: RuntimeToolRegistryPolicy);
+    register(definition: RuntimeToolDefinition | unknown): void;
+    get(name: string): RuntimeToolDefinition | undefined;
+    isAllowed(name: string): boolean;
+    permissionReasons(name: string): string[];
+    list(): RuntimeToolManifest[];
+    validateInput(name: string, input: unknown): unknown;
+    discover(query?: RuntimeToolDiscoveryQuery): RuntimeToolDiscoveryResult[];
+    compileToolSet(id: string, query?: RuntimeToolDiscoveryQuery, version?: string): RuntimeToolSetSnapshot;
+    execute(name: string, input: unknown, context: RuntimeToolContext | AbortSignal): Promise<unknown>;
+    executeDetailed(name: string, input: unknown, context: RuntimeToolContext | AbortSignal): Promise<{
+        output: unknown;
+        normalized?: JsonValue;
+        summary?: JsonValue;
+        manifest: RuntimeToolManifest;
+    }>;
+    reconcileDetailed(name: string, executionRef: JsonValue, context: RuntimeReconcileContext): Promise<RuntimeReconcileResult>;
+    executionRef(name: string, input: unknown, context: RuntimeToolContext): JsonValue | undefined;
+    resolveResources(name: string, input: unknown): ResourceLockSpec[];
+    admission(name: string, input: unknown): RuntimeToolAdmission;
+    private require;
+    private permissionsAllowed;
+}