@hunterzhu/pulse-adapters 0.1.0

package/dist/providers/runtime-executor.js

@@ -0,0 +1,225 @@
+import { assignRuntimeToolCallIds, ModelFallbackController, OutputValidationError, estimateProjectionTokens, stableSerialize, validateAdapterResult, validateJsonSchema, modelFallbackError, runtimeErrorFromCause } from '@hunterzhu/pulse-runtime';
+class AsyncSlot {
+    limit;
+    active = 0;
+    pending = [];
+    constructor(limit) {
+        this.limit = limit;
+    }
+    async acquire(signal) {
+        if (this.limit === Number.POSITIVE_INFINITY || this.active < this.limit) {
+            this.active++;
+            return () => this.release();
+        }
+        if (signal?.aborted)
+            throw new Error('EFFECT_CANCELLED');
+        return new Promise((resolve, reject) => {
+            const request = { signal, resolve, reject };
+            const onAbort = () => { const index = this.pending.indexOf(request); if (index >= 0)
+                this.pending.splice(index, 1); reject(new Error('EFFECT_CANCELLED')); };
+            if (signal)
+                signal.addEventListener('abort', onAbort, { once: true });
+            this.pending.push(request);
+        });
+    }
+    release() {
+        const next = this.pending.shift();
+        if (!next) {
+            this.active = Math.max(0, this.active - 1);
+            return;
+        }
+        if (next.signal?.aborted) {
+            next.reject(new Error('EFFECT_CANCELLED'));
+            this.release();
+            return;
+        }
+        next.resolve(() => this.release());
+    }
+}
+class SlotPool {
+    limits;
+    slots = new Map();
+    constructor(limits = {}) {
+        this.limits = limits;
+    }
+    get(key) { let slot = this.slots.get(key); if (!slot) {
+        slot = new AsyncSlot(this.limits[key] ?? Number.POSITIVE_INFINITY);
+        this.slots.set(key, slot);
+    } ; return slot; }
+}
+function toJson(value, seen = new Set()) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new Error('LLM_OUTPUT_NOT_SERIALIZABLE');
+        return value;
+    }
+    if (Array.isArray(value)) {
+        if (seen.has(value))
+            throw new Error('LLM_OUTPUT_NOT_SERIALIZABLE');
+        seen.add(value);
+        try {
+            return value.map((item) => toJson(item, seen));
+        }
+        finally {
+            seen.delete(value);
+        }
+    }
+    if (typeof value === 'object') {
+        if (value instanceof Uint8Array || value instanceof ArrayBuffer || value instanceof Date || Object.getPrototypeOf(value) !== Object.prototype || seen.has(value))
+            throw new Error('LLM_OUTPUT_NOT_SERIALIZABLE');
+        seen.add(value);
+        try {
+            return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, toJson(item, seen)]));
+        }
+        finally {
+            seen.delete(value);
+        }
+    }
+    throw new Error('LLM_OUTPUT_NOT_SERIALIZABLE');
+}
+function candidateMetadata(candidate, attempts, usage, slotWaitMs, routes) {
+    return { selected: { id: candidate.id, providerId: candidate.providerId }, routes, attempts: attempts.map((attempt) => {
+            const recorded = usage.get(attempt.attemptId);
+            const usageJson = recorded === undefined ? undefined : { ...(recorded.inputTokens === undefined ? {} : { inputTokens: recorded.inputTokens }), ...(recorded.outputTokens === undefined ? {} : { outputTokens: recorded.outputTokens }), ...(recorded.cachedInputTokens === undefined ? {} : { cachedInputTokens: recorded.cachedInputTokens }), ...(recorded.uncachedInputTokens === undefined ? {} : { uncachedInputTokens: recorded.uncachedInputTokens }), ...(recorded.latencyMs === undefined ? {} : { latencyMs: recorded.latencyMs }), ...(recorded.cost === undefined ? {} : { cost: recorded.cost }) };
+            const waited = slotWaitMs.get(attempt.attemptId);
+            return { effectId: attempt.effectId, attemptId: attempt.attemptId, attemptNo: attempt.attemptNo, modelId: attempt.candidate.id, providerId: attempt.candidate.providerId, ...(waited === undefined ? {} : { slotWaitMs: waited }), ...(usageJson === undefined ? {} : { usage: usageJson }) };
+        }) };
+}
+export function createModelEffectExecutor(config) {
+    const fallback = new ModelFallbackController();
+    const providerSlots = new SlotPool(config.maxConcurrentByProvider);
+    const modelSlots = new SlotPool(config.maxConcurrentByModel);
+    return async (effect, signal, emitObservation) => {
+        if (effect.kind !== 'llm')
+            throw new Error(`UNSUPPORTED_EFFECT_KIND:${effect.kind}`);
+        const input = effect.input && typeof effect.input === 'object' && !Array.isArray(effect.input) ? effect.input : {};
+        const task = input.task;
+        const request = input.request;
+        if (typeof task !== 'string' || !request || typeof request !== 'object' || Array.isArray(request))
+            throw new Error('INVALID_LLM_EFFECT_INPUT');
+        const projection = request;
+        const observations = [];
+        const usage = new Map();
+        const slotWaitMs = new Map();
+        let lastSchemaViolation;
+        let failedForSchema = false;
+        const dynamicRequirements = input.requirements && typeof input.requirements === 'object' && !Array.isArray(input.requirements) ? input.requirements : {};
+        const structuredRequirement = dynamicRequirements.structuredOutput;
+        const structuredSchema = structuredRequirement && typeof structuredRequirement === 'object' && !Array.isArray(structuredRequirement) ? structuredRequirement.schema : undefined;
+        if (structuredSchema !== undefined && (input.outputSchema === undefined || stableSerialize(structuredSchema) !== stableSerialize(input.outputSchema)))
+            return { value: null, status: 'failed', executionState: 'failed', privacy: projection.privacy, error: { code: 'STRUCTURED_OUTPUT_CONTRACT_MISMATCH', message: 'requirements.structuredOutput.schema must equal outputSchema.' } };
+        const routeRequirements = { ...config.requirements, ...(typeof dynamicRequirements.toolCalling === 'boolean' ? { toolCalling: dynamicRequirements.toolCalling } : {}), ...(typeof dynamicRequirements.structuredOutput === 'boolean' ? { structuredOutput: dynamicRequirements.structuredOutput } : structuredSchema === undefined ? {} : { structuredOutput: true }), ...(dynamicRequirements.reasoning === 'low' || dynamicRequirements.reasoning === 'medium' || dynamicRequirements.reasoning === 'high' ? { reasoning: dynamicRequirements.reasoning } : {}), ...(typeof dynamicRequirements.maxOutputTokens === 'number' ? { maxOutputTokens: dynamicRequirements.maxOutputTokens } : {}), ...(typeof dynamicRequirements.contextSize === 'number' ? { contextSize: dynamicRequirements.contextSize } : {}) };
+        const routeDiagnostics = config.router.diagnostics(task, projection.privacy, routeRequirements, estimateProjectionTokens(projection) + (typeof routeRequirements.maxOutputTokens === 'number' ? routeRequirements.maxOutputTokens : 0));
+        const candidates = config.router.routeProjection(task, projection, routeRequirements);
+        const attemptNo = Math.max(1, effect.attemptNo);
+        const candidate = candidates[attemptNo - 1];
+        const maxAttempts = effect.retryPolicy?.maxAttempts ?? candidates.length;
+        const canFallback = candidate !== undefined && attemptNo < Math.max(0, maxAttempts) && candidates[attemptNo] !== undefined;
+        if (candidate === undefined)
+            return { value: null, status: 'failed', executionState: 'failed', privacy: projection.privacy, error: { code: candidates.length === 0 ? 'NO_ELIGIBLE_MODEL' : 'MODEL_ATTEMPT_LIMIT_REACHED', message: candidates.length === 0 ? 'No model candidate satisfies the task, privacy, capability, and context requirements.' : 'No additional routed model candidate is available for this Effect.' }, metadata: { routes: routeDiagnostics, attempts: [] } };
+        const result = await fallback.execute(effect.id, [candidate], async (attempt) => {
+            failedForSchema = false;
+            const provider = config.providers.get(attempt.candidate.providerId);
+            if (!provider)
+                throw modelFallbackError({ retryable: false, localClosed: true, sideEffectState: 'none', cause: new Error(`UNKNOWN_PROVIDER:${attempt.candidate.providerId}`) });
+            const slotStartedAt = Date.now();
+            let providerRelease;
+            try {
+                providerRelease = await providerSlots.get(attempt.candidate.providerId).acquire(signal);
+            }
+            catch (cause) {
+                if (signal.aborted)
+                    throw modelFallbackError({ retryable: false, localClosed: true, sideEffectState: 'none', cause });
+                throw cause;
+            }
+            let modelRelease;
+            try {
+                modelRelease = await modelSlots.get(attempt.candidate.id).acquire(signal);
+            }
+            catch (cause) {
+                providerRelease();
+                if (signal.aborted)
+                    throw modelFallbackError({ retryable: false, localClosed: true, sideEffectState: 'none', cause });
+                throw cause;
+            }
+            slotWaitMs.set(attempt.attemptId, Math.max(0, Date.now() - slotStartedAt));
+            const releases = [providerRelease, modelRelease];
+            let feedbackRecorded = false;
+            const recordFeedback = (outcome, quality) => {
+                if (feedbackRecorded)
+                    return;
+                feedbackRecorded = true;
+                config.router.recordFeedback({ modelId: attempt.candidate.id, providerId: attempt.candidate.providerId, outcome, quality, ...(usage.get(attempt.attemptId) === undefined ? {} : { usage: usage.get(attempt.attemptId) }) });
+            };
+            try {
+                const startedAt = Date.now();
+                const onObservation = (chunk) => {
+                    const observation = { type: 'chunk', data: chunk };
+                    if (emitObservation)
+                        emitObservation(observation);
+                    else
+                        observations.push(observation);
+                };
+                const output = assignRuntimeToolCallIds(validateAdapterResult(await provider.executeAttempt({ request: projection, signal, model: attempt.candidate.id, ...(input.outputSchema === undefined ? {} : { outputSchema: input.outputSchema }), ...(typeof routeRequirements.maxOutputTokens === 'number' ? { maxOutputTokens: routeRequirements.maxOutputTokens } : {}), onObservation })), effect.id);
+                const measuredUsage = output.usage === undefined ? { latencyMs: Math.max(0, Date.now() - startedAt) } : { ...output.usage, latencyMs: output.usage.latencyMs ?? Math.max(0, Date.now() - startedAt), ...(output.usage.uncachedInputTokens === undefined && output.usage.inputTokens !== undefined && output.usage.cachedInputTokens !== undefined ? { uncachedInputTokens: Math.max(0, output.usage.inputTokens - output.usage.cachedInputTokens) } : {}) };
+                usage.set(attempt.attemptId, measuredUsage);
+                if (output.finishReason === 'refusal') {
+                    recordFeedback('refused', 0);
+                    throw new OutputValidationError('adapter', 'MODEL_REFUSAL', output.refusal ?? 'Provider refused the request.');
+                }
+                if (input.outputSchema !== undefined) {
+                    const candidateValue = output.structured ?? output.text;
+                    if (!validateJsonSchema(candidateValue, input.outputSchema)) {
+                        lastSchemaViolation = toJson(candidateValue);
+                        failedForSchema = true;
+                        recordFeedback('schema_rejected', 0);
+                        throw new OutputValidationError('structured', 'OUTPUT_SCHEMA_VIOLATION', 'Provider output did not match the declared schema');
+                    }
+                }
+                failedForSchema = false;
+                recordFeedback('succeeded', 1);
+                return output;
+            }
+            catch (cause) {
+                recordFeedback('failed', 0);
+                if (signal.aborted)
+                    throw modelFallbackError({ retryable: false, localClosed: true, sideEffectState: 'none', cause });
+                const retryable = cause && typeof cause === 'object' && 'retryable' in cause && typeof cause.retryable === 'boolean' ? cause.retryable : true;
+                throw modelFallbackError({ retryable, localClosed: true, sideEffectState: 'none', cause });
+            }
+            finally {
+                for (const release of releases.reverse())
+                    release();
+            }
+        }, 1).then((value) => {
+            const providerAttempt = value.attempts.at(-1);
+            const measuredUsage = providerAttempt === undefined ? undefined : usage.get(providerAttempt.attemptId);
+            if (measuredUsage !== undefined)
+                usage.set(effect.attemptId, measuredUsage);
+            const waited = providerAttempt === undefined ? undefined : slotWaitMs.get(providerAttempt.attemptId);
+            if (waited !== undefined)
+                slotWaitMs.set(effect.attemptId, waited);
+            return { ...value, attempts: value.attempts.map(() => ({ effectId: effect.id, attemptId: effect.attemptId, attemptNo, candidate })) };
+        }).catch((cause) => {
+            if (failedForSchema && lastSchemaViolation !== undefined)
+                return { result: { text: '', toolCalls: [], finishReason: 'error' }, candidate, attempts: [{ effectId: effect.id, attemptId: effect.attemptId, attemptNo, candidate }], schemaRejected: lastSchemaViolation };
+            const inner = cause && typeof cause === 'object' && 'modelFallback' in cause ? cause.modelFallback?.cause : cause;
+            if (inner instanceof OutputValidationError && inner.code === 'MODEL_REFUSAL')
+                return { result: { text: '', refusal: inner.message, toolCalls: [], finishReason: 'refusal' }, candidate, attempts: [{ effectId: effect.id, attemptId: effect.attemptId, attemptNo, candidate }], refused: true, retryable: canFallback };
+            const fallbackError = cause && typeof cause === 'object' && 'modelFallback' in cause ? cause.modelFallback : undefined;
+            const error = runtimeErrorFromCause(fallbackError?.cause ?? cause, 'MODEL_EXECUTION_FAILED');
+            return { result: { text: '', toolCalls: [], finishReason: 'error' }, candidate, attempts: [{ effectId: effect.id, attemptId: effect.attemptId, attemptNo, candidate }], failed: { ...error, ...(canFallback && fallbackError?.retryable !== false && error.retryable !== false ? { retryable: true } : {}) } };
+        });
+        if ('schemaRejected' in result)
+            return { value: null, status: 'failed', executionState: 'failed', privacy: projection.privacy, error: { code: 'OUTPUT_SCHEMA_VIOLATION', message: 'Provider output did not match the declared schema.', ...(canFallback ? { retryable: true } : {}) }, metadata: candidateMetadata(result.candidate, result.attempts, usage, slotWaitMs, routeDiagnostics), rejectedOutput: { value: result.schemaRejected, privacy: projection.privacy, derivedFrom: [...(effect.derivedFrom ?? [])] } };
+        if ('refused' in result)
+            return { value: null, status: 'failed', executionState: 'failed', privacy: projection.privacy, error: { code: 'MODEL_REFUSAL', message: result.result.refusal ?? 'Provider refused the request.', ...(result.retryable ? { retryable: true } : {}) }, metadata: candidateMetadata(result.candidate, result.attempts, usage, slotWaitMs, routeDiagnostics) };
+        if ('failed' in result)
+            return { value: null, status: 'failed', executionState: 'failed', privacy: projection.privacy, error: result.failed, metadata: candidateMetadata(result.candidate, result.attempts, usage, slotWaitMs, routeDiagnostics) };
+        const modelValue = input.outputSchema !== undefined || typeof input.schema === 'string' ? (result.result.structured ?? result.result.text) : result.result;
+        const value = toJson(modelValue);
+        return { value, privacy: projection.privacy, sideEffectState: 'none', executionState: 'succeeded', metadata: candidateMetadata(result.candidate, result.attempts, usage, slotWaitMs, routeDiagnostics), ...(observations.length ? { observations } : {}) };
+    };
+}

package/dist/providers/types.d.ts

@@ -0,0 +1,28 @@
+import type { JsonValue, LLMRequestProjection, LLMResult } from '@hunterzhu/pulse-runtime';
+export type ProviderToolChoice = 'auto' | 'required' | 'none' | {
+    type: 'function';
+    function: {
+        name: string;
+    };
+};
+export interface ProviderAdapter {
+    readonly id: string;
+    readonly name: string;
+    executeAttempt(params: {
+        request: LLMRequestProjection;
+        signal: AbortSignal;
+        onObservation?: (chunk: string) => void;
+        model?: string;
+        outputSchema?: JsonValue;
+        maxOutputTokens?: number;
+    }): Promise<LLMResult>;
+}
+export interface ProviderPresetConfig {
+    provider: string;
+    apiKey?: string;
+    baseURL?: string;
+    defaultModel?: string;
+    maxOutputTokens?: number;
+    toolChoice?: ProviderToolChoice;
+    extraHeaders?: Record<string, string>;
+}

package/dist/providers/types.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/filesystem.d.ts

@@ -0,0 +1,27 @@
+export interface FilesystemWriteResult {
+    hash: string;
+    bytes: number;
+}
+export interface FilesystemReadResult {
+    content: string;
+    truncated: boolean;
+}
+export declare class FilesystemTool {
+    readonly root: string;
+    private readonly lockTimeoutMs;
+    constructor(root: string, lockTimeoutMs?: number);
+    private safe;
+    private existing;
+    private writable;
+    read(path: string, signal?: AbortSignal): Promise<string>;
+    readLimited(path: string, maxBytes: number, signal?: AbortSignal): Promise<FilesystemReadResult>;
+    list(path?: string, signal?: AbortSignal): Promise<string[]>;
+    write(path: string, content: string, signal?: AbortSignal): Promise<void>;
+    move(source: string, destination: string, expectedHash?: string, signal?: AbortSignal): Promise<{
+        hash: string;
+        bytes: number;
+    }>;
+    hash(path: string, signal?: AbortSignal): Promise<string>;
+    writeIfUnchanged(path: string, content: string, expectedHash: string, signal?: AbortSignal): Promise<FilesystemWriteResult>;
+    private withLock;
+}

package/dist/tools/filesystem.js

@@ -0,0 +1,183 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { lstat, mkdir, open, readFile, readdir, realpath, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+function filesystemError(code, retryable = false, cause) {
+    return Object.assign(new Error(code), { code, retryable, ...(cause === undefined ? {} : { cause }) });
+}
+function filesystemCause(cause) {
+    if (cause instanceof Error && typeof cause.code === 'string' && typeof cause.retryable === 'boolean')
+        return cause;
+    const code = cause && typeof cause === 'object' && typeof cause.code === 'string' ? String(cause.code) : 'FILESYSTEM_OPERATION_FAILED';
+    const retryable = code === 'EAGAIN' || code === 'EBUSY' || code === 'EMFILE' || code === 'ENFILE' || code === 'ETIMEDOUT';
+    return filesystemError(code, retryable, cause);
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (cause) {
+        if (cause.code === 'ESRCH')
+            return false;
+        throw cause;
+    }
+}
+export class FilesystemTool {
+    root;
+    lockTimeoutMs;
+    constructor(root, lockTimeoutMs = 30_000) {
+        this.root = root;
+        this.lockTimeoutMs = lockTimeoutMs;
+    }
+    safe(path) { const target = resolve(this.root, path); if (isAbsolute(path) || relative(resolve(this.root), target).startsWith('..'))
+        throw filesystemError('PATH_OUTSIDE_SANDBOX'); return target; }
+    async existing(path) {
+        const target = this.safe(path);
+        const [root, resolved] = await Promise.all([realpath(this.root), realpath(target)]);
+        const within = relative(root, resolved);
+        if (within.startsWith('..') || isAbsolute(within))
+            throw filesystemError('PATH_OUTSIDE_SANDBOX');
+        return resolved;
+    }
+    async writable(path) {
+        const target = this.safe(path);
+        await mkdir(dirname(target), { recursive: true });
+        const [root, parent] = await Promise.all([realpath(this.root), realpath(dirname(target))]);
+        const within = relative(root, parent);
+        if (within.startsWith('..') || isAbsolute(within))
+            throw filesystemError('PATH_OUTSIDE_SANDBOX');
+        const existing = await lstat(target).catch((cause) => cause.code === 'ENOENT' ? undefined : Promise.reject(cause));
+        if (existing?.isSymbolicLink())
+            throw filesystemError('PATH_OUTSIDE_SANDBOX');
+        return target;
+    }
+    async read(path, signal) { if (signal?.aborted)
+        throw filesystemError('ABORTED'); return readFile(await this.existing(path), 'utf8'); }
+    async readLimited(path, maxBytes, signal) {
+        if (signal?.aborted)
+            throw filesystemError('ABORTED');
+        const handle = await open(await this.existing(path), 'r');
+        try {
+            const buffer = Buffer.alloc(maxBytes + 1);
+            const { bytesRead } = await handle.read(buffer, 0, maxBytes + 1, 0);
+            return { content: buffer.subarray(0, Math.min(bytesRead, maxBytes)).toString('utf8'), truncated: bytesRead > maxBytes };
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    async list(path = '.', signal) { if (signal?.aborted)
+        throw filesystemError('ABORTED'); return readdir(await this.existing(path)); }
+    async write(path, content, signal) { if (signal?.aborted)
+        throw filesystemError('ABORTED'); await writeFile(await this.writable(path), content, 'utf8'); }
+    async move(source, destination, expectedHash, signal) {
+        if (signal?.aborted)
+            throw filesystemError('ABORTED');
+        const sourcePath = this.safe(source);
+        const sourceEntry = await lstat(sourcePath).catch((cause) => cause.code === 'ENOENT' ? undefined : Promise.reject(cause));
+        if (!sourceEntry)
+            throw filesystemError('ENOENT');
+        if (sourceEntry.isSymbolicLink())
+            throw filesystemError('PATH_OUTSIDE_SANDBOX');
+        const sourceTarget = await this.existing(source);
+        const destinationTarget = await this.writable(destination);
+        const destinationExists = await lstat(destinationTarget).catch((cause) => cause.code === 'ENOENT' ? undefined : Promise.reject(cause));
+        if (destinationExists)
+            throw filesystemError('MOVE_DESTINATION_EXISTS');
+        const currentHash = await this.hash(source, signal);
+        if (expectedHash !== undefined && currentHash !== expectedHash)
+            throw filesystemError('FILE_BASELINE_CONFLICT');
+        await this.withLock(sourceTarget, async () => { await rename(sourceTarget, destinationTarget); });
+        return { hash: currentHash, bytes: sourceEntry.size };
+    }
+    async hash(path, signal) {
+        if (signal?.aborted)
+            throw filesystemError('ABORTED');
+        const digest = createHash('sha256');
+        await pipeline(createReadStream(await this.existing(path)), digest, signal === undefined ? {} : { signal });
+        return digest.digest('hex');
+    }
+    async writeIfUnchanged(path, content, expectedHash, signal) {
+        if (signal?.aborted)
+            throw filesystemError('ABORTED');
+        if (!/^[a-f0-9]{64}$/.test(expectedHash))
+            throw filesystemError('INVALID_FILE_BASELINE_HASH');
+        const target = await this.writable(path);
+        return this.withLock(target, async () => {
+            if (signal?.aborted)
+                throw filesystemError('ABORTED');
+            let current;
+            try {
+                current = await readFile(target);
+            }
+            catch (cause) {
+                if (cause.code === 'ENOENT')
+                    throw filesystemError('FILE_BASELINE_MISSING');
+                throw filesystemCause(cause);
+            }
+            const currentHash = createHash('sha256').update(current).digest('hex');
+            if (currentHash !== expectedHash)
+                throw filesystemError('FILE_BASELINE_CONFLICT');
+            const bytes = Buffer.byteLength(content, 'utf8');
+            const temporary = `${target}.tmp-${process.pid}-${process.hrtime.bigint().toString()}`;
+            let handle;
+            try {
+                handle = await open(temporary, 'wx', 0o600);
+                await handle.writeFile(content, 'utf8');
+                await handle.sync();
+                await handle.close();
+                handle = undefined;
+                await rename(temporary, target);
+            }
+            finally {
+                if (handle)
+                    await handle.close().catch(() => undefined);
+                await rm(temporary, { force: true }).catch(() => undefined);
+            }
+            return { hash: createHash('sha256').update(content).digest('hex'), bytes };
+        });
+    }
+    async withLock(target, work) {
+        const lockPath = `${target}.pulse.lock`;
+        const deadline = Date.now() + this.lockTimeoutMs;
+        const payload = JSON.stringify({ pid: process.pid, token: `${process.pid}:${process.hrtime.bigint()}` });
+        let lock;
+        while (lock === undefined) {
+            try {
+                lock = await open(lockPath, 'wx', 0o600);
+                await lock.writeFile(payload);
+            }
+            catch (cause) {
+                if (cause.code !== 'EEXIST')
+                    throw filesystemCause(cause);
+                const body = await readFile(lockPath, 'utf8').catch(() => undefined);
+                let owner;
+                try {
+                    owner = body ? JSON.parse(body) : undefined;
+                }
+                catch {
+                    owner = undefined;
+                }
+                if (typeof owner?.pid === 'number' && !pidAlive(owner.pid) && body !== undefined) {
+                    const current = await readFile(lockPath, 'utf8').catch(() => undefined);
+                    if (current === body) {
+                        await rm(lockPath, { force: true });
+                        continue;
+                    }
+                }
+                if (Date.now() >= deadline)
+                    throw filesystemError('FILESYSTEM_LOCK_TIMEOUT', true);
+                await new Promise((resolve) => setTimeout(resolve, 5));
+            }
+        }
+        try {
+            return await work();
+        }
+        finally {
+            await lock.close().catch(() => undefined);
+            await rm(lockPath, { force: true }).catch(() => undefined);
+        }
+    }
+}

package/dist/tools/registry.d.ts

@@ -0,0 +1,5 @@
+import { type EffectExecutor, type EffectRecord, type EffectSubmission, type JsonValue } from '@hunterzhu/pulse-runtime';
+import { ToolRegistry, type ReconcileResult } from '@hunterzhu/pulse-tool-sdk';
+export declare function createToolEffectExecutor(registry: ToolRegistry): EffectExecutor;
+export declare function reconcileToolEffect(registry: ToolRegistry, effect: Readonly<EffectRecord>, signal: AbortSignal): Promise<ReconcileResult<JsonValue>>;
+export declare function createToolEffectSubmissionPreparer(registry: ToolRegistry): (submission: EffectSubmission) => EffectSubmission;

package/dist/tools/registry.js

@@ -0,0 +1,141 @@
+import { isSideEffectful } from '@hunterzhu/pulse-runtime';
+function toJson(value, seen = new Set()) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean' || typeof value === 'number')
+        return value;
+    if (Array.isArray(value)) {
+        if (seen.has(value))
+            throw new Error('TOOL_OUTPUT_NOT_SERIALIZABLE');
+        seen.add(value);
+        try {
+            return value.map((item) => toJson(item, seen));
+        }
+        finally {
+            seen.delete(value);
+        }
+    }
+    if (typeof value === 'object') {
+        if (value instanceof Uint8Array || value instanceof ArrayBuffer || value instanceof Date || Object.getPrototypeOf(value) !== Object.prototype)
+            throw new Error('TOOL_OUTPUT_NOT_SERIALIZABLE');
+        if (seen.has(value))
+            throw new Error('TOOL_OUTPUT_NOT_SERIALIZABLE');
+        seen.add(value);
+        try {
+            return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, toJson(item, seen)]));
+        }
+        finally {
+            seen.delete(value);
+        }
+    }
+    throw new Error('TOOL_OUTPUT_NOT_SERIALIZABLE');
+}
+function artifactOutput(value) {
+    if (value instanceof Uint8Array)
+        return { mediaType: 'application/octet-stream', content: new Uint8Array(value) };
+    if (value instanceof ArrayBuffer)
+        return { mediaType: 'application/octet-stream', content: new Uint8Array(value) };
+    try {
+        const serialized = JSON.stringify(value);
+        if (serialized !== undefined)
+            return { mediaType: 'application/json', content: serialized };
+    }
+    catch { /* fall through to a bounded textual representation */ }
+    return { mediaType: 'text/plain', content: String(value) };
+}
+export function createToolEffectExecutor(registry) {
+    return async (effect, signal, emitObservation) => {
+        if (effect.kind !== 'tool')
+            throw new Error(`UNSUPPORTED_EFFECT_KIND:${effect.kind}`);
+        const input = effect.input && typeof effect.input === 'object' && !Array.isArray(effect.input) ? effect.input : {};
+        const name = input.name;
+        if (typeof name !== 'string')
+            throw new Error('INVALID_TOOL_EFFECT_INPUT');
+        if (!registry.isAllowed(name))
+            throw new Error(`TOOL_NOT_ALLOWED:${name}`);
+        const definition = registry.get(name);
+        if (!definition)
+            throw new Error(`UNKNOWN_TOOL:${name}`);
+        const observations = [];
+        const emit = (event) => {
+            if (signal.aborted)
+                return;
+            if (emitObservation)
+                emitObservation(event);
+            else
+                observations.push(event);
+        };
+        const toolContext = {
+            toolCallId: effect.toolCallId ?? '',
+            effectId: effect.id,
+            attemptId: effect.attemptId,
+            ...(effect.idempotencyKey === undefined ? {} : { idempotencyKey: effect.idempotencyKey }),
+            agentId: effect.agentId,
+            laneId: effect.ownerLaneId,
+            signal,
+            emit,
+        };
+        const executionRef = registry.executionRef(name, input.arguments ?? {}, toolContext);
+        let detailed;
+        try {
+            detailed = await registry.executeDetailed(name, input.arguments ?? {}, {
+                toolCallId: effect.toolCallId ?? '',
+                effectId: effect.id,
+                attemptId: effect.attemptId,
+                ...(effect.idempotencyKey === undefined ? {} : { idempotencyKey: effect.idempotencyKey }),
+                agentId: effect.agentId,
+                laneId: effect.ownerLaneId,
+                signal,
+                emit,
+            });
+        }
+        catch (error) {
+            if (signal.aborted && isSideEffectful(definition.manifest.sideEffectPolicy))
+                return { value: null, executionState: 'remote_unknown', sideEffectState: 'unknown', ...(executionRef === undefined ? {} : { executionRef }), metadata: { toolVersion: definition.manifest.version, reconcileRequired: true }, ...(error instanceof Error ? { error: { code: 'TOOL_CANCELLED_UNKNOWN', message: error.message } } : {}) };
+            throw error;
+        }
+        const summary = detailed.summary === undefined ? undefined : toJson(detailed.summary);
+        let value;
+        let artifact;
+        try {
+            value = toJson(detailed.output);
+        }
+        catch {
+            value = null;
+            artifact = artifactOutput(detailed.output);
+        }
+        return { value, ...(detailed.normalized === undefined ? {} : { normalized: toJson(detailed.normalized) }), ...(artifact === undefined ? {} : { artifact }), ...(summary === undefined ? {} : { summary }), sideEffectState: isSideEffectful(definition.manifest.sideEffectPolicy) ? 'applied' : 'none', executionState: 'succeeded', ...(executionRef === undefined ? {} : { executionRef }), metadata: { toolVersion: detailed.manifest.version, retrySafety: detailed.manifest.retrySafety, defaultTimeoutMs: detailed.manifest.defaultTimeoutMs, observationCount: observations.length, ...(artifact === undefined ? {} : { artifactMediaType: artifact.mediaType }) }, ...(observations.length ? { observations } : {}) };
+    };
+}
+export async function reconcileToolEffect(registry, effect, signal) {
+    if (effect.kind !== 'tool')
+        throw new Error(`UNSUPPORTED_EFFECT_KIND:${effect.kind}`);
+    if (effect.executionRef === undefined)
+        throw new Error('MISSING_TOOL_EXECUTION_REF');
+    const input = effect.input && typeof effect.input === 'object' && !Array.isArray(effect.input) ? effect.input : {};
+    if (typeof input.name !== 'string')
+        throw new Error('INVALID_TOOL_EFFECT_INPUT');
+    const result = await registry.reconcileDetailed(input.name, effect.executionRef, { toolCallId: effect.toolCallId ?? '', effectId: effect.id, attemptId: effect.attemptId, agentId: effect.agentId, laneId: effect.ownerLaneId, signal });
+    return { status: result.status, ...(result.error === undefined ? {} : { error: result.error }), ...(result.output === undefined ? {} : { output: toJson(result.output) }) };
+}
+export function createToolEffectSubmissionPreparer(registry) {
+    return (submission) => {
+        if (submission.kind === 'llm') {
+            const input = submission.input && typeof submission.input === 'object' && !Array.isArray(submission.input) ? submission.input : {};
+            const rawQuery = input.toolDiscovery;
+            if (rawQuery && typeof rawQuery === 'object' && !Array.isArray(rawQuery)) {
+                const query = rawQuery;
+                const requestedId = typeof input.toolSetId === 'string' ? input.toolSetId : 'dynamic';
+                const toolSet = registry.compileToolSet(requestedId, query);
+                const tools = toolSet.tools.map((manifest) => ({ name: manifest.name, description: manifest.description, inputSchema: manifest.inputSchema }));
+                return { ...submission, input: { ...input, toolSetId: `${toolSet.id}@${toolSet.version}`, tools: { tools } } };
+            }
+            return submission;
+        }
+        if (submission.kind !== 'tool')
+            return submission;
+        const input = submission.input && typeof submission.input === 'object' && !Array.isArray(submission.input) ? submission.input : {};
+        if (typeof input.name !== 'string')
+            throw new Error('INVALID_TOOL_EFFECT_INPUT');
+        const admission = registry.admission(input.name, input.arguments ?? {});
+        return { ...submission, ...(submission.locks === undefined ? { locks: admission.locks } : {}), ...(submission.sideEffectPolicy === undefined ? { sideEffectPolicy: admission.sideEffectPolicy } : {}), ...(submission.attemptTimeoutMs === undefined ? { attemptTimeoutMs: admission.defaultTimeoutMs } : {}), ...(submission.toolVersion === undefined ? { toolVersion: admission.version } : {}) };
+    };
+}

package/dist/tools/shell.d.ts

@@ -0,0 +1,15 @@
+export interface ShellResult {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    truncated: boolean;
+    timedOut: boolean;
+    aborted: boolean;
+}
+export declare function runShell(command: string, args?: string[], options?: {
+    cwd?: string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+    env?: NodeJS.ProcessEnv;
+}): Promise<ShellResult>;