@hunterzhu/pulse-server 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,113 @@
+import { type JsonValue, type Outcome } from '@hunterzhu/pulse-runtime';
+import { type ProviderPresetConfig } from '@hunterzhu/pulse-adapters';
+export type ApprovalMode = 'read-only' | 'ask' | 'auto';
+export interface LocalHostOptions {
+    cwd?: string;
+    dataDir?: string;
+    provider?: ProviderPresetConfig;
+    mockResponse?: string;
+    mockToolCalls?: Array<{
+        name: string;
+        input?: JsonValue;
+        toolCallId?: string;
+    }>;
+    mockAfterToolResponse?: string;
+    approvalMode?: ApprovalMode;
+    allowNetwork?: boolean;
+    networkHosts?: string[];
+    maxRuntimeMs?: number;
+}
+export interface CreateConversationInput {
+    cwd?: string;
+    title?: string;
+}
+export interface ArtifactSummary {
+    path: string;
+    hash: string;
+    bytes: number;
+    mediaType?: string;
+    label?: string;
+    runId: string;
+}
+export interface ConversationSummary {
+    id: string;
+    title: string;
+    cwd: string;
+    createdAt: string;
+    updatedAt: string;
+    activeRunId?: string;
+    artifacts?: ArtifactSummary[];
+}
+export interface UserMessageInput {
+    text: string;
+    format?: 'text' | 'jsonl';
+}
+export interface AssistantEvent {
+    schemaVersion: 1;
+    type: 'text' | 'fact' | 'observation' | 'waiting' | 'complete' | 'error' | 'gap';
+    conversationId: string;
+    runId: string;
+    seq: number;
+    data?: JsonValue;
+}
+export interface RunHandle {
+    readonly id: string;
+    readonly conversationId: string;
+    readonly events: AsyncIterable<AssistantEvent>;
+    outcome(): Promise<Outcome & {
+        text?: string;
+    }>;
+    cancel(reason?: string): Promise<void>;
+    reply(effectId: string, value: JsonValue): Promise<void>;
+}
+export interface ConversationHandle {
+    readonly id: string;
+    readonly summary: ConversationSummary;
+}
+export declare class LocalHost {
+    private readonly root;
+    private readonly dataDir;
+    private readonly options;
+    private readonly approvedToolCalls;
+    private readonly active;
+    private readonly conversationLocks;
+    constructor(options?: LocalHostOptions);
+    init(): Promise<void>;
+    private conversationDir;
+    private manifestPath;
+    private messagesPath;
+    private runDir;
+    private lockPath;
+    private acquireConversationLock;
+    private releaseConversationLock;
+    private readManifest;
+    createConversation(input?: CreateConversationInput): Promise<ConversationHandle>;
+    listConversations(): Promise<ConversationSummary[]>;
+    getConversation(id: string): Promise<ConversationHandle>;
+    listArtifacts(id: string): Promise<ArtifactSummary[]>;
+    private appendMessage;
+    private runtimeFor;
+    private restoreRuntimeFor;
+    private makeRunHandle;
+    sendMessage(conversationId: string, input: UserMessageInput): Promise<RunHandle>;
+    resumeRun(conversationId: string): Promise<RunHandle>;
+    private resultText;
+    private projectEvents;
+    close(): Promise<void>;
+    doctor(options?: {
+        live?: boolean;
+    }): Promise<{
+        ok: boolean;
+        cwd: string;
+        dataDir: string;
+        node: string;
+        tools: string[];
+        provider: string;
+        errors: string[];
+        live?: {
+            ok: boolean;
+            message: string;
+        };
+    }>;
+}
+export declare function createLocalHost(options?: LocalHostOptions): LocalHost;

package/dist/index.js

@@ -0,0 +1,362 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { z } from 'zod';
+import { assertPublicNetworkUrl, conversationDirectory, publicUrl, safeShellEnv, searchFiles, within } from './security.js';
+import { FileRuntimePersistenceBackend, ModelRouter, InMemoryModelRegistry, PulseRuntime, defineReActLane, } from '@hunterzhu/pulse-runtime';
+import { createModelEffectExecutor, createProviderAdapter, createToolEffectExecutor, createToolEffectSubmissionPreparer, MockAdapter, runShell, FilesystemTool, } from '@hunterzhu/pulse-adapters';
+import { defineTool, ToolRegistry } from '@hunterzhu/pulse-tool-sdk';
+const textLimit = 48_000;
+const json = (value) => {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (Array.isArray(value))
+        return value.map((item) => json(item));
+    if (typeof value === 'object' && value !== null)
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, json(item)]));
+    return String(value);
+};
+async function fetchText(raw, signal, allowHosts) {
+    const url = await assertPublicNetworkUrl(raw, allowHosts);
+    const response = await fetch(url, { signal, redirect: 'manual' });
+    if (response.status >= 300 && response.status < 400)
+        throw new Error('REDIRECT_REQUIRES_EXPLICIT_FETCH');
+    if (!response.ok)
+        throw new Error(`HTTP_${response.status}`);
+    const contentType = response.headers.get('content-type') ?? '';
+    if (!contentType.includes('text/') && !contentType.includes('json') && !contentType.includes('xml'))
+        throw new Error('UNSUPPORTED_WEB_CONTENT_TYPE');
+    const source = await response.text();
+    const text = source.replace(/<script[\s\S]*?<\/script>/gi, ' ').replace(/<style[\s\S]*?<\/style>/gi, ' ').replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim();
+    const title = source.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1]?.replace(/\s+/g, ' ').trim() ?? url.hostname;
+    const limit = 32_000;
+    return { url: url.toString(), title, text: text.slice(0, limit), truncated: text.length > limit, fetchedAt: new Date().toISOString() };
+}
+function registerBuiltIns(registry, root, approvalMode, allowNetwork = false, isApprovedToolCall = () => false, networkHosts) {
+    const fsTool = new FilesystemTool(root);
+    registry.register(defineTool({
+        name: 'fs.list', description: 'List files in the workspace.', tags: ['files', 'read'], input: z.object({ path: z.string().default('.') }), output: z.object({ path: z.string(), entries: z.array(z.string()) }), sideEffectPolicy: 'read', permissions: { workspaceRoots: [root] }, execute: async ({ path }) => { const safePath = path ?? '.'; return { path: safePath, entries: await fsTool.list(safePath) }; }, summarize: (output) => ({ path: output.path ?? '.', entries: output.entries.slice(0, 100) }),
+    }));
+    registry.register(defineTool({
+        name: 'fs.read', description: 'Read a UTF-8 text file from the workspace.', tags: ['files', 'read'], input: z.object({ path: z.string(), maxBytes: z.number().int().positive().max(200_000).optional() }), output: z.object({ path: z.string(), content: z.string(), truncated: z.boolean() }), sideEffectPolicy: 'read', permissions: { workspaceRoots: [root] }, execute: async ({ path, maxBytes }) => { const limit = maxBytes ?? 64_000; const read = await fsTool.readLimited(path, limit); return { path, content: read.content, truncated: read.truncated }; }, summarize: (output) => ({ path: output.path, content: output.content.slice(0, 1_000), truncated: output.truncated }),
+    }));
+    registry.register(defineTool({
+        name: 'fs.search', description: 'Search text files in the workspace.', tags: ['files', 'search'], input: z.object({ query: z.string().min(1), path: z.string().default('.') }), output: z.object({ matches: z.array(z.object({ path: z.string(), line: z.number(), text: z.string() })) }), sideEffectPolicy: 'read', permissions: { workspaceRoots: [root] }, execute: async ({ query, path }) => ({ matches: await searchFiles(root, query, path) }), summarize: (output) => ({ matches: output.matches.slice(0, 20) }),
+    }));
+    registry.register(defineTool({
+        name: 'fs.write', description: 'Write a UTF-8 text file after authorization.', tags: ['files', 'write'], input: z.object({ path: z.string(), content: z.string().max(500_000), expectedHash: z.string().regex(/^[a-f0-9]{64}$/).optional() }), output: z.object({ path: z.string(), bytes: z.number(), hash: z.string() }), sideEffectPolicy: 'write', retrySafety: 'unsafe', permissions: { workspaceRoots: [root] }, execute: async ({ path, content, expectedHash }, context) => { if (approvalMode === 'read-only')
+            throw new Error('WRITE_DISABLED_READ_ONLY'); if (approvalMode === 'ask' && !isApprovedToolCall(context.toolCallId))
+            throw new Error('APPROVAL_REQUIRED:fs.write'); if (expectedHash)
+            return { path, ...(await fsTool.writeIfUnchanged(path, content, expectedHash)) }; await fsTool.write(path, content); const bytes = Buffer.byteLength(content); return { path, bytes, hash: await fsTool.hash(path) }; }, summarize: (output) => output,
+    }));
+    registry.register(defineTool({
+        name: 'fs.apply_patch', description: 'Replace an exact text fragment in a UTF-8 file after authorization.', tags: ['files', 'write', 'patch'], input: z.object({ path: z.string(), find: z.string().min(1), replace: z.string(), all: z.boolean().default(false), expectedHash: z.string().regex(/^[a-f0-9]{64}$/).optional() }), output: z.object({ path: z.string(), replacements: z.number(), bytes: z.number(), hash: z.string() }), sideEffectPolicy: 'write', retrySafety: 'unsafe', permissions: { workspaceRoots: [root] }, execute: async ({ path, find, replace, all, expectedHash }, context) => { if (approvalMode === 'read-only')
+            throw new Error('WRITE_DISABLED_READ_ONLY'); if (approvalMode === 'ask' && !isApprovedToolCall(context.toolCallId))
+            throw new Error('APPROVAL_REQUIRED:fs.apply_patch'); const source = await fsTool.readLimited(path, 500_000); if (source.truncated)
+            throw new Error('FILE_TOO_LARGE'); const count = source.content.split(find).length - 1; if (count === 0)
+            throw new Error('PATCH_CONTEXT_NOT_FOUND'); if (!all && count !== 1)
+            throw new Error('PATCH_CONTEXT_AMBIGUOUS'); const content = all ? source.content.split(find).join(replace) : source.content.replace(find, replace); if (expectedHash)
+            await fsTool.writeIfUnchanged(path, content, expectedHash);
+        else
+            await fsTool.write(path, content); return { path, replacements: all ? count : 1, bytes: Buffer.byteLength(content), hash: await fsTool.hash(path) }; }, summarize: (output) => output,
+    }));
+    registry.register(defineTool({
+        name: 'fs.move', description: 'Move a file without overwriting an existing destination.', tags: ['files', 'write', 'organize'], input: z.object({ source: z.string(), destination: z.string(), expectedHash: z.string().regex(/^[a-f0-9]{64}$/).optional() }), output: z.object({ source: z.string(), destination: z.string(), bytes: z.number(), hash: z.string() }), sideEffectPolicy: 'write', retrySafety: 'unsafe', permissions: { workspaceRoots: [root] }, execute: async ({ source, destination, expectedHash }, context) => { if (approvalMode === 'read-only')
+            throw new Error('MOVE_DISABLED_READ_ONLY'); if (approvalMode === 'ask' && !isApprovedToolCall(context.toolCallId))
+            throw new Error('APPROVAL_REQUIRED:fs.move'); const moved = await fsTool.move(source, destination, expectedHash, context.signal); return { source, destination, ...moved }; }, summarize: (output) => output,
+    }));
+    registry.register(defineTool({
+        name: 'artifact.record', description: 'Record a bounded text file as a user-visible artifact.', tags: ['artifact', 'files', 'read'], input: z.object({ path: z.string(), mediaType: z.string().default('text/plain'), label: z.string().max(200).optional() }), output: z.object({ path: z.string(), mediaType: z.string(), label: z.string(), bytes: z.number(), hash: z.string() }), sideEffectPolicy: 'read', permissions: { workspaceRoots: [root] }, execute: async ({ path, mediaType, label }) => { const read = await fsTool.readLimited(path, 200_000); if (read.truncated)
+            throw new Error('FILE_TOO_LARGE'); return { path, mediaType: mediaType ?? 'text/plain', label: label ?? path, bytes: Buffer.byteLength(read.content), hash: await fsTool.hash(path) }; }, summarize: (output) => output,
+    }));
+    registry.register(defineTool({
+        name: 'shell.exec', description: 'Run an authorized local command with argv arguments.', tags: ['shell', 'system'], input: z.object({ command: z.string().min(1), args: z.array(z.string()).default([]), cwd: z.string().default('.'), timeoutMs: z.number().int().positive().max(300_000).optional() }), output: z.object({ code: z.number().nullable(), stdout: z.string(), stderr: z.string(), truncated: z.boolean(), timedOut: z.boolean(), aborted: z.boolean() }), sideEffectPolicy: 'external', retrySafety: 'unsafe', permissions: { workspaceRoots: [root] }, execute: async ({ command, args, cwd, timeoutMs }, context) => { if (approvalMode === 'read-only')
+            throw new Error('SHELL_DISABLED_READ_ONLY'); if (approvalMode === 'ask' && !isApprovedToolCall(context.toolCallId))
+            throw new Error('APPROVAL_REQUIRED:shell.exec'); const options = { cwd: await within(root, cwd ?? '.'), signal: context.signal, env: safeShellEnv(), maxOutputBytes: 64 * 1024, ...(timeoutMs === undefined ? {} : { timeoutMs }) }; return runShell(command, args, options); }, summarize: (output) => ({ code: output.code, stdout: output.stdout.slice(0, 2_000), stderr: output.stderr.slice(0, 2_000), truncated: output.truncated }),
+    }));
+    if (allowNetwork) {
+        registry.register(defineTool({
+            name: 'web.fetch', description: 'Fetch a public HTTP(S) page and return bounded text.', tags: ['web', 'research'], input: z.object({ url: z.string().url() }), output: z.object({ url: z.string(), title: z.string(), text: z.string(), truncated: z.boolean(), fetchedAt: z.string() }), sideEffectPolicy: 'external', retrySafety: 'read_only', permissions: { networkHosts: networkHosts ?? ['*'] }, execute: async ({ url }, context) => fetchText(url, context.signal, networkHosts), summarize: (output) => ({ url: output.url, title: output.title, text: output.text.slice(0, 2_000), truncated: output.truncated, fetchedAt: output.fetchedAt }),
+        }));
+        registry.register(defineTool({
+            name: 'web.search', description: 'Search public web pages using the configured DuckDuckGo HTML endpoint.', tags: ['web', 'research'], input: z.object({ query: z.string().min(1).max(500), limit: z.number().int().positive().max(10).default(5) }), output: z.object({ query: z.string(), results: z.array(z.object({ title: z.string(), url: z.string(), snippet: z.string() })), fetchedAt: z.string() }), sideEffectPolicy: 'external', retrySafety: 'read_only', permissions: { networkHosts: ['html.duckduckgo.com'] }, execute: async ({ query, limit }, context) => { const endpoint = await assertPublicNetworkUrl(process.env.PULSE_SEARCH_URL ?? 'https://html.duckduckgo.com/html/'); endpoint.searchParams.set('q', query); const response = await fetch(endpoint, { signal: context.signal }); if (!response.ok)
+                throw new Error(`HTTP_${response.status}`); const page = await response.text(); const results = []; const pattern = /result__a[^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>[\s\S]*?result__snippet[^>]*>([\s\S]*?)<\//g; for (const match of page.matchAll(pattern)) {
+                if (results.length >= (limit ?? 5))
+                    break;
+                const url = publicUrl(match[1] ?? '', networkHosts).toString();
+                results.push({ title: (match[2] ?? '').replace(/<[^>]+>/g, '').trim(), url, snippet: (match[3] ?? '').replace(/<[^>]+>/g, '').replace(/\s+/g, ' ').trim() });
+            } return { query, results, fetchedAt: new Date().toISOString() }; }, summarize: (output) => ({ query: output.query, results: output.results, fetchedAt: output.fetchedAt }),
+        }));
+    }
+}
+function buildProgram(toolNames) {
+    return (approvalMode = 'ask') => defineReActLane({ id: 'pulse.assistant', version: '1', system: 'You are Pulse, a careful general task assistant. Use available tools when they help. Explain what you did and cite workspace paths. Never claim an action succeeded unless its tool result confirms it.', toolSet: 'pulse.default', task: 'reason', instruction: ({ goal }) => goal, toolAllow: toolNames, maxTurns: 12, ...(approvalMode === 'ask' ? { toolApproval: { prompt: () => 'Reply with approved=true to continue or approved=false to deny.' } } : {}) });
+}
+function providerFromOptions(options) {
+    const config = options.provider ?? { provider: 'mock', defaultModel: 'mock' };
+    const adapter = createProviderAdapter(config);
+    if (config.provider === 'mock' && adapter instanceof MockAdapter) {
+        const toolCalls = options.mockToolCalls ?? [];
+        if (toolCalls.length)
+            adapter.enqueue({ text: '', toolCalls: toolCalls.map((call, index) => ({ toolCallId: call.toolCallId ?? `mock-call-${index + 1}`, name: call.name, input: call.input ?? {} })), finishReason: 'tool_calls' });
+        adapter.enqueue({ text: options.mockAfterToolResponse ?? options.mockResponse ?? process.env.PULSE_MOCK_RESPONSE ?? 'Mock provider is ready. Configure a real provider for model-generated answers.', toolCalls: [], finishReason: 'stop' });
+    }
+    const local = config.provider === 'mock' || config.provider === 'ollama';
+    return { adapter, model: { id: config.defaultModel ?? `${config.provider}-default`, providerId: adapter.id, tasks: ['reason', 'plan', 'merge'], priority: 10, capabilities: { toolCalling: true, structuredOutput: true, reasoning: 'medium', maxContextTokens: 32_000, maxOutputTokens: config.maxOutputTokens ?? 4_096, local }, adapter } };
+}
+export class LocalHost {
+    root;
+    dataDir;
+    options;
+    approvedToolCalls = new Map();
+    active = new Map();
+    conversationLocks = new Map();
+    constructor(options = {}) { this.root = resolve(options.cwd ?? process.cwd()); this.dataDir = resolve(options.dataDir ?? process.env.PULSE_DATA_DIR ?? join(homedir(), '.local', 'share', 'pulse')); this.options = options; }
+    async init() { await mkdir(this.dataDir, { recursive: true }); await stat(this.root); }
+    conversationDir(id) { return conversationDirectory(this.dataDir, id); }
+    manifestPath(id) { return join(this.conversationDir(id), 'manifest.json'); }
+    messagesPath(id) { return join(this.conversationDir(id), 'messages.jsonl'); }
+    runDir(conversationId, runId) { return join(this.conversationDir(conversationId), 'runs', runId); }
+    lockPath(conversationId) { return join(this.conversationDir(conversationId), 'conversation.lock'); }
+    async acquireConversationLock(conversationId, runId) {
+        const path = this.lockPath(conversationId);
+        await mkdir(this.conversationDir(conversationId), { recursive: true });
+        for (;;) {
+            try {
+                const handle = await open(path, 'wx', 0o600);
+                await handle.writeFile(JSON.stringify({ pid: process.pid, runId, acquiredAt: new Date().toISOString() }));
+                this.conversationLocks.set(conversationId, handle);
+                return;
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+                const body = await readFile(path, 'utf8').catch(() => undefined);
+                let owner;
+                try {
+                    owner = body ? JSON.parse(body) : undefined;
+                }
+                catch {
+                    owner = undefined;
+                }
+                if (typeof owner?.pid === 'number') {
+                    try {
+                        process.kill(owner.pid, 0);
+                        throw new Error('CONVERSATION_BUSY');
+                    }
+                    catch (probeError) {
+                        if (probeError.code !== 'ESRCH')
+                            throw probeError;
+                    }
+                    const current = await readFile(path, 'utf8').catch(() => undefined);
+                    if (current === body) {
+                        await rm(path, { force: true });
+                        continue;
+                    }
+                }
+                throw new Error('CONVERSATION_BUSY');
+            }
+        }
+    }
+    async releaseConversationLock(conversationId) { const handle = this.conversationLocks.get(conversationId); if (!handle)
+        return; this.conversationLocks.delete(conversationId); await handle.close().catch(() => undefined); await rm(this.lockPath(conversationId), { force: true }).catch(() => undefined); }
+    async readManifest(id) { return JSON.parse(await readFile(this.manifestPath(id), 'utf8')); }
+    async createConversation(input = {}) { const id = `conv-${randomUUID()}`; const now = new Date().toISOString(); const cwd = resolve(input.cwd ?? this.root); const manifest = { schemaVersion: 1, id, title: input.title ?? 'New conversation', cwd, createdAt: now, updatedAt: now, runs: [], artifacts: [] }; await mkdir(this.conversationDir(id), { recursive: true }); await writeFile(this.manifestPath(id), JSON.stringify(manifest, null, 2)); return { id, summary: manifest }; }
+    async listConversations() { await this.init(); const entries = await readdir(join(this.dataDir, 'conversations'), { withFileTypes: true }).catch(() => []); const summaries = []; for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        try {
+            const manifest = await this.readManifest(entry.name);
+            summaries.push(manifest);
+        }
+        catch { /* ignore incomplete directories */ }
+    } return summaries.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt)); }
+    async getConversation(id) { const manifest = await this.readManifest(id); return { id, summary: manifest }; }
+    async listArtifacts(id) { return [...((await this.readManifest(id)).artifacts ?? [])]; }
+    async appendMessage(id, message) { await writeFile(this.messagesPath(id), `${JSON.stringify(message)}\n`, { flag: 'a' }); }
+    runtimeFor(conversationId, runId, cwd) {
+        const registry = new ToolRegistry({ workspaceRoots: [cwd], allowNetwork: this.options.allowNetwork === true, ...(this.options.networkHosts === undefined ? {} : { networkHosts: this.options.networkHosts }) });
+        registerBuiltIns(registry, cwd, this.options.approvalMode ?? 'ask', this.options.allowNetwork === true, (toolCallId) => this.approvedToolCalls.get(runId)?.has(toolCallId) === true, this.options.networkHosts);
+        const provider = providerFromOptions(this.options);
+        const models = new InMemoryModelRegistry();
+        models.register(provider.model);
+        const router = new ModelRouter(models);
+        router.register({ task: 'reason', candidates: [provider.model.id] });
+        router.register({ task: 'plan', candidates: [provider.model.id] });
+        router.register({ task: 'merge', candidates: [provider.model.id] });
+        const backend = new FileRuntimePersistenceBackend(join(this.runDir(conversationId, runId), 'runtime.json'));
+        const toolVersions = Object.fromEntries(registry.list().map((tool) => [tool.name, tool.version]));
+        const runtime = new PulseRuntime({ sessionId: runId, maxRuntimeMs: this.options.maxRuntimeMs ?? 15 * 60_000, programs: [], models, modelRouter: router, toolVersions, builtinHumanEffects: true, effectExecutor: async (effect, signal, observe) => { if (effect.kind === 'llm')
+                return createModelEffectExecutor({ router, providers: new Map([[provider.adapter.id, provider.adapter]]) })(effect, signal, observe); if (effect.kind === 'tool')
+                return createToolEffectExecutor(registry)(effect, signal, observe); throw new Error(`UNSUPPORTED_EFFECT_KIND:${effect.kind}`); }, effectSubmissionPreparer: createToolEffectSubmissionPreparer(registry), persistenceBackend: backend });
+        return { runtime, registry };
+    }
+    async restoreRuntimeFor(conversationId, runId, cwd) {
+        const registry = new ToolRegistry({ workspaceRoots: [cwd], allowNetwork: this.options.allowNetwork === true, ...(this.options.networkHosts === undefined ? {} : { networkHosts: this.options.networkHosts }) });
+        registerBuiltIns(registry, cwd, this.options.approvalMode ?? 'ask', this.options.allowNetwork === true, (toolCallId) => this.approvedToolCalls.get(runId)?.has(toolCallId) === true, this.options.networkHosts);
+        const provider = providerFromOptions(this.options);
+        const models = new InMemoryModelRegistry();
+        models.register(provider.model);
+        const router = new ModelRouter(models);
+        router.register({ task: 'reason', candidates: [provider.model.id] });
+        router.register({ task: 'plan', candidates: [provider.model.id] });
+        router.register({ task: 'merge', candidates: [provider.model.id] });
+        const backend = new FileRuntimePersistenceBackend(join(this.runDir(conversationId, runId), 'runtime.json'));
+        const program = buildProgram(registry.list().map((tool) => tool.name))(this.options.approvalMode ?? 'ask');
+        const toolVersions = Object.fromEntries(registry.list().map((tool) => [tool.name, tool.version]));
+        const runtime = await PulseRuntime.restore(backend, { sessionId: runId, maxRuntimeMs: this.options.maxRuntimeMs ?? 15 * 60_000, programs: [program], models, modelRouter: router, toolVersions, builtinHumanEffects: true, effectExecutor: async (effect, signal, observe) => { if (effect.kind === 'llm')
+                return createModelEffectExecutor({ router, providers: new Map([[provider.adapter.id, provider.adapter]]) })(effect, signal, observe); if (effect.kind === 'tool')
+                return createToolEffectExecutor(registry)(effect, signal, observe); throw new Error(`UNSUPPORTED_EFFECT_KIND:${effect.kind}`); }, effectSubmissionPreparer: createToolEffectSubmissionPreparer(registry), persistenceBackend: backend });
+        return { runtime, registry };
+    }
+    makeRunHandle(conversationId, runId, runtime, session) {
+        let finalized;
+        const finish = () => finalized ??= (async () => { const outcome = await session.outcome(); const text = this.resultText(runtime, outcome.resultRef); await this.appendMessage(conversationId, { id: `msg-${randomUUID()}`, role: 'assistant', text: text ?? '', runId, createdAt: new Date().toISOString() }); const current = await this.readManifest(conversationId); const artifacts = [...runtime.state.results.values()].flatMap((result) => { const value = result.value; if (!value || typeof value !== 'object' || Array.isArray(value))
+            return []; const record = value; if (typeof record.path !== 'string' || typeof record.hash !== 'string' || typeof record.bytes !== 'number')
+            return []; return [{ path: record.path, hash: record.hash, bytes: record.bytes, ...(typeof record.mediaType === 'string' ? { mediaType: record.mediaType } : {}), ...(typeof record.label === 'string' ? { label: record.label } : {}), runId }]; }); current.artifacts = [...(current.artifacts ?? []).filter((item) => item.runId !== runId), ...artifacts]; if (current.activeRunId === runId)
+            delete current.activeRunId; current.updatedAt = new Date().toISOString(); await writeFile(this.manifestPath(conversationId), JSON.stringify(current, null, 2)); this.active.delete(runId); this.approvedToolCalls.delete(runId); await runtime.flushPersistence(); await writeFile(join(this.runDir(conversationId, runId), 'outcome.json'), JSON.stringify({ schemaVersion: 1, ...outcome, ...(text === undefined ? {} : { text }), completedAt: new Date().toISOString() }, null, 2)); return { ...outcome, ...(text === undefined ? {} : { text }) }; })().finally(async () => { await this.releaseConversationLock(conversationId); });
+        const events = this.projectEvents(conversationId, runId, session, finish);
+        return { id: runId, conversationId, events, outcome: finish, cancel: async (reason = 'USER_REQUESTED') => { await session.cancel(reason); }, reply: async (effectId, value) => { const effect = runtime.state.effects.get(effectId); const approved = value && typeof value === 'object' && !Array.isArray(value) && value.approved === true; if (approved && effect?.kind === 'human' && effect.input && typeof effect.input === 'object' && !Array.isArray(effect.input)) {
+                const calls = effect.input.tools;
+                if (Array.isArray(calls)) {
+                    const approvedIds = this.approvedToolCalls.get(runId) ?? new Set();
+                    this.approvedToolCalls.set(runId, approvedIds);
+                    for (const call of calls)
+                        if (call && typeof call === 'object' && !Array.isArray(call) && typeof call.toolCallId === 'string')
+                            approvedIds.add(call.toolCallId);
+                }
+            } await session.reply(effectId, value); } };
+    }
+    async sendMessage(conversationId, input) {
+        if (!input.text.trim())
+            throw new Error('MESSAGE_REQUIRED');
+        const runId = `run-${randomUUID()}`;
+        await this.acquireConversationLock(conversationId, runId);
+        try {
+            const manifest = await this.readManifest(conversationId);
+            if (manifest.activeRunId)
+                throw new Error('CONVERSATION_BUSY');
+            const previous = await readFile(this.messagesPath(conversationId), 'utf8').catch(() => '');
+            const context = previous.split('\n').filter(Boolean).slice(-8).map((line) => { try {
+                const message = JSON.parse(line);
+                return `${message.role}: ${message.text.slice(0, 4_000)}`;
+            }
+            catch {
+                return '';
+            } }).filter(Boolean).join('\n');
+            const goal = context ? `Conversation context:\n${context}\n\nuser: ${input.text}` : input.text;
+            const now = new Date().toISOString();
+            await this.appendMessage(conversationId, { id: `msg-${randomUUID()}`, role: 'user', text: input.text, runId, createdAt: now });
+            await mkdir(this.runDir(conversationId, runId), { recursive: true });
+            await writeFile(join(this.runDir(conversationId, runId), 'input.json'), JSON.stringify({ schemaVersion: 1, conversationId, runId, goal: input.text, cwd: manifest.cwd, provider: this.options.provider?.provider ?? 'mock', approvalMode: this.options.approvalMode ?? 'ask', createdAt: now }, null, 2));
+            const { runtime, registry } = this.runtimeFor(conversationId, runId, manifest.cwd);
+            const program = buildProgram(registry.list().map((tool) => tool.name))(this.options.approvalMode ?? 'ask');
+            runtime.register(program);
+            const { agentId } = runtime.createAgent({ goal, program });
+            const session = runtime.start(agentId);
+            this.active.set(runId, { runtime, session, conversationId, runId });
+            manifest.activeRunId = runId;
+            manifest.runs.push(runId);
+            manifest.updatedAt = now;
+            await writeFile(this.manifestPath(conversationId), JSON.stringify(manifest, null, 2));
+            return this.makeRunHandle(conversationId, runId, runtime, session);
+        }
+        catch (error) {
+            await this.releaseConversationLock(conversationId);
+            throw error;
+        }
+    }
+    async resumeRun(conversationId) {
+        const manifest = await this.readManifest(conversationId);
+        const runId = manifest.activeRunId;
+        if (!runId)
+            throw new Error('NO_ACTIVE_RUN');
+        const existing = this.active.get(runId);
+        if (existing)
+            return this.makeRunHandle(conversationId, runId, existing.runtime, existing.session);
+        await this.acquireConversationLock(conversationId, runId);
+        try {
+            const { runtime } = await this.restoreRuntimeFor(conversationId, runId, manifest.cwd);
+            const agent = [...runtime.state.agents.values()][0];
+            if (!agent)
+                throw new Error('RESTORED_AGENT_NOT_FOUND');
+            const session = runtime.start(agent.id);
+            this.active.set(runId, { runtime, session, conversationId, runId });
+            return this.makeRunHandle(conversationId, runId, runtime, session);
+        }
+        catch (error) {
+            await this.releaseConversationLock(conversationId);
+            throw error;
+        }
+    }
+    resultText(runtime, ref) { if (!ref)
+        return undefined; const first = runtime.state.results.get(ref)?.value; if (typeof first === 'string')
+        return first; if (!first || typeof first !== 'object' || Array.isArray(first))
+        return JSON.stringify(first); const firstRecord = first; const textRef = firstRecord.textRef; const value = typeof textRef === 'string' ? runtime.state.results.get(textRef)?.value : first; if (typeof value === 'string')
+        return value; if (value && typeof value === 'object' && !Array.isArray(value) && typeof value.text === 'string')
+        return value.text; return value === undefined ? undefined : JSON.stringify(value, null, 2); }
+    async *projectEvents(conversationId, runId, session, finish) { let seq = 0; for await (const event of session.stream()) {
+        seq++;
+        if (event.kind === 'observation') {
+            const observation = event.observation;
+            if (observation.type === 'chunk')
+                yield { schemaVersion: 1, type: 'text', conversationId, runId, seq, data: observation.data ?? '' };
+            else
+                yield { schemaVersion: 1, type: 'observation', conversationId, runId, seq, data: event.observation ?? null };
+            continue;
+        }
+        if (event.kind === 'gap') {
+            yield { schemaVersion: 1, type: 'gap', conversationId, runId, seq, data: { fromSeq: event.fromSeq ?? 0, toSeq: event.toSeq ?? 0 } };
+            continue;
+        }
+        if (event.event?.type === 'human.requested') {
+            const liveEffect = event.event.effectId === undefined ? undefined : this.active.get(runId)?.runtime.state.effects.get(event.event.effectId);
+            if (liveEffect?.state !== 'running' || liveEffect.outcome !== undefined)
+                continue;
+            yield { schemaVersion: 1, type: 'waiting', conversationId, runId, seq, data: { effectId: event.event.effectId ?? null, input: event.event.data ?? null } };
+            continue;
+        }
+        yield { schemaVersion: 1, type: 'fact', conversationId, runId, seq, data: event.event?.data ?? event.event?.type ?? null };
+    } try {
+        const outcome = await finish();
+        yield { schemaVersion: 1, type: 'complete', conversationId, runId, seq: seq + 1, data: { status: outcome.status } };
+    }
+    catch (error) {
+        yield { schemaVersion: 1, type: 'error', conversationId, runId, seq: seq + 1, data: String(error) };
+    } }
+    async close() { for (const active of this.active.values())
+        await active.runtime.shutdown(); this.active.clear(); this.approvedToolCalls.clear(); for (const conversationId of [...this.conversationLocks.keys()])
+        await this.releaseConversationLock(conversationId); }
+    async doctor(options = {}) {
+        const errors = [];
+        try {
+            await this.init();
+        }
+        catch (error) {
+            errors.push(error instanceof Error ? error.message : String(error));
+        }
+        const registry = new ToolRegistry({ allowNetwork: this.options.allowNetwork === true });
+        registerBuiltIns(registry, this.root, this.options.approvalMode ?? 'ask', this.options.allowNetwork === true);
+        let live;
+        if (options.live) {
+            const provider = providerFromOptions(this.options);
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), 10_000);
+            try {
+                await provider.adapter.executeAttempt({ model: provider.model.id, maxOutputTokens: 8, signal: controller.signal, request: { contextSpec: { globalSnapshotVersion: 0, laneSnapshotVersion: 0, resultRefs: [], eventIds: [], toolSetId: 'pulse.doctor', instruction: 'health check', privacy: 'cloud_allowed', privacyRefs: [] }, blocks: [{ kind: 'instruction', content: 'Reply with OK.' }], prefixHash: 'doctor', projectionHash: 'doctor', builderVersion: 'doctor', policyVersion: 'doctor', toolSetVersion: 'doctor', privacy: 'cloud_allowed', privacyRefs: [] } });
+                live = { ok: true, message: 'provider request succeeded' };
+            }
+            catch (error) {
+                live = { ok: false, message: error instanceof Error ? error.message : String(error) };
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+        return { ok: errors.length === 0 && (live?.ok ?? true), cwd: this.root, dataDir: this.dataDir, node: process.version, tools: registry.list().map((tool) => tool.name), provider: this.options.provider?.provider ?? 'mock', errors, ...(live === undefined ? {} : { live }) };
+    }
+}
+export function createLocalHost(options = {}) { return new LocalHost(options); }

package/dist/security.d.ts

@@ -0,0 +1,19 @@
+export declare const CONVERSATION_ID: RegExp;
+export declare function isConversationId(id: string): boolean;
+export declare function conversationDirectory(dataDir: string, id: string): string;
+export declare function within(root: string, path: string): Promise<string>;
+export declare function ipv4FromDottedOrInteger(host: string): string | undefined;
+export declare function mappedIpv4(host: string): string | undefined;
+export declare function isPrivateIp(address: string): boolean;
+export declare function isBlockedHostname(host: string): boolean;
+export declare function hostAllowed(host: string, allowHosts: string[] | undefined): boolean;
+export declare function publicUrl(raw: string, allowHosts?: string[]): URL;
+export declare function assertPublicNetworkUrl(raw: string, allowHosts?: string[]): Promise<URL>;
+export declare function searchFiles(root: string, query: string, directory?: string, depth?: number, visited?: {
+    count: number;
+}): Promise<Array<{
+    path: string;
+    line: number;
+    text: string;
+}>>;
+export declare function safeShellEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;

package/dist/security.js

@@ -0,0 +1,181 @@
+import { lstat, readdir, readFile, realpath } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { isIP } from 'node:net';
+import { promises as dns } from 'node:dns';
+export const CONVERSATION_ID = /^conv-[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const SEARCH_MAX_DEPTH = 8;
+const SEARCH_MAX_VISITED = 2_000;
+const SEARCH_MAX_RESULTS = 100;
+export function isConversationId(id) {
+    return CONVERSATION_ID.test(id);
+}
+export function conversationDirectory(dataDir, id) {
+    if (!isConversationId(id))
+        throw new Error('INVALID_CONVERSATION_ID');
+    const root = resolve(dataDir, 'conversations');
+    const target = resolve(root, id);
+    const rel = relative(root, target);
+    if (rel.startsWith('..') || isAbsolute(rel))
+        throw new Error('INVALID_CONVERSATION_ID');
+    return target;
+}
+function lexicalWithin(root, path) {
+    if (isAbsolute(path))
+        throw new Error('PATH_OUTSIDE_WORKSPACE');
+    const base = resolve(root);
+    const absolute = resolve(base, path);
+    const rel = relative(base, absolute);
+    if (rel === '..' || rel.startsWith(`..${sep}`))
+        throw new Error('PATH_OUTSIDE_WORKSPACE');
+    return absolute;
+}
+export async function within(root, path) {
+    const target = lexicalWithin(root, path);
+    const resolvedRoot = await realpath(root);
+    try {
+        const resolved = await realpath(target);
+        const rel = relative(resolvedRoot, resolved);
+        if (rel.startsWith('..') || isAbsolute(rel))
+            throw new Error('PATH_OUTSIDE_WORKSPACE');
+        return resolved;
+    }
+    catch (cause) {
+        if (cause.code !== 'ENOENT')
+            throw cause;
+        const parent = await realpath(resolve(target, '..'));
+        const rel = relative(resolvedRoot, parent);
+        if (rel.startsWith('..') || isAbsolute(rel))
+            throw new Error('PATH_OUTSIDE_WORKSPACE');
+        return target;
+    }
+}
+export function ipv4FromDottedOrInteger(host) {
+    if (/^\d+$/.test(host)) {
+        const value = Number(host);
+        if (!Number.isInteger(value) || value < 0 || value > 0xffffffff)
+            return undefined;
+        return [24, 16, 8, 0].map((shift) => (value >>> shift) & 255).join('.');
+    }
+    if (/^\d{1,3}(\.\d{1,3}){0,3}$/.test(host)) {
+        const parts = host.split('.').map(Number);
+        if (parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255))
+            return undefined;
+        if (parts.length === 1)
+            return undefined;
+        if (parts.length === 2)
+            return `${parts[0]}.0.0.${parts[1]}`;
+        if (parts.length === 3)
+            return `${parts[0]}.${parts[1]}.0.${parts[2]}`;
+        return parts.join('.');
+    }
+    return undefined;
+}
+export function mappedIpv4(host) {
+    const unwrapped = host.replace(/^\[|\]$/g, '');
+    const match = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(unwrapped) ?? /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i.exec(unwrapped);
+    if (!match)
+        return undefined;
+    if (match[1]?.includes('.'))
+        return match[1];
+    const high = Number.parseInt(match[1] ?? '0', 16);
+    const low = Number.parseInt(match[2] ?? '0', 16);
+    return `${high >> 8}.${high & 255}.${low >> 8}.${low & 255}`;
+}
+export function isPrivateIp(address) {
+    const mapped = mappedIpv4(address);
+    if (mapped)
+        return isPrivateIp(mapped);
+    const ipv4 = ipv4FromDottedOrInteger(address) ?? (isIP(address) === 4 ? address : undefined);
+    if (ipv4) {
+        const [a = 0, b = 0] = ipv4.split('.').map(Number);
+        return a === 0 || a === 10 || a === 127 || (a === 169 && b === 254) || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || a === 255;
+    }
+    const host = address.replace(/^\[|\]$/g, '').toLocaleLowerCase();
+    if (isIP(host) !== 6)
+        return false;
+    if (host === '::' || host === '::1')
+        return true;
+    if (host.startsWith('fe80:') || host.startsWith('fc') || host.startsWith('fd'))
+        return true;
+    return false;
+}
+export function isBlockedHostname(host) {
+    const normalized = host.toLocaleLowerCase().replace(/^\[|\]$/g, '');
+    if (normalized === 'localhost' || normalized.endsWith('.localhost') || normalized === 'metadata.google.internal' || normalized === 'metadata.internal')
+        return true;
+    if (isPrivateIp(normalized))
+        return true;
+    const dotted = ipv4FromDottedOrInteger(normalized);
+    return dotted !== undefined && isPrivateIp(dotted);
+}
+export function hostAllowed(host, allowHosts) {
+    if (!allowHosts || allowHosts.includes('*'))
+        return true;
+    const normalized = host.toLocaleLowerCase().replace(/^\[|\]$/g, '');
+    return allowHosts.some((allowed) => {
+        const rule = allowed.toLocaleLowerCase();
+        return rule === normalized || (rule.startsWith('*.') && (normalized === rule.slice(2) || normalized.endsWith(`.${rule.slice(2)}`)));
+    });
+}
+export function publicUrl(raw, allowHosts) {
+    const url = new URL(raw);
+    if (!['http:', 'https:'].includes(url.protocol))
+        throw new Error('URL_SCHEME_NOT_ALLOWED');
+    const host = url.hostname;
+    if (isBlockedHostname(host))
+        throw new Error('PRIVATE_NETWORK_URL_NOT_ALLOWED');
+    if (!hostAllowed(host, allowHosts))
+        throw new Error('NETWORK_HOST_NOT_ALLOWED');
+    return url;
+}
+export async function assertPublicNetworkUrl(raw, allowHosts) {
+    const url = publicUrl(raw, allowHosts);
+    if (isIP(url.hostname.replace(/^\[|\]$/g, '')) || ipv4FromDottedOrInteger(url.hostname) !== undefined)
+        return url;
+    const lookup = await dns.lookup(url.hostname, { all: true, verbatim: true }).catch(() => {
+        throw new Error('NETWORK_HOST_UNRESOLVABLE');
+    });
+    if (lookup.length === 0 || lookup.some((entry) => isPrivateIp(entry.address)))
+        throw new Error('PRIVATE_NETWORK_URL_NOT_ALLOWED');
+    return url;
+}
+export async function searchFiles(root, query, directory = '.', depth = 0, visited = { count: 0 }) {
+    if (depth > SEARCH_MAX_DEPTH || visited.count >= SEARCH_MAX_VISITED)
+        return [];
+    const base = await within(root, directory);
+    const baseStat = await lstat(base).catch(() => undefined);
+    if (!baseStat || baseStat.isSymbolicLink() || !baseStat.isDirectory())
+        return [];
+    const entries = await readdir(base, { withFileTypes: true });
+    const result = [];
+    const needle = query.toLocaleLowerCase();
+    for (const entry of entries) {
+        if (entry.name.startsWith('.') || entry.name === 'node_modules' || result.length >= SEARCH_MAX_RESULTS || visited.count >= SEARCH_MAX_VISITED)
+            break;
+        visited.count++;
+        const relativePath = directory === '.' ? entry.name : join(directory, entry.name);
+        if (entry.isSymbolicLink())
+            continue;
+        if (entry.isDirectory()) {
+            result.push(...await searchFiles(root, query, relativePath, depth + 1, visited));
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        const filePath = await within(root, relativePath).catch(() => undefined);
+        if (!filePath)
+            continue;
+        const file = await readFile(filePath).catch(() => undefined);
+        if (!file || file.includes('\u0000') || file.byteLength > 1_000_000)
+            continue;
+        const lines = file.toString('utf8').split(/\r?\n/);
+        lines.forEach((line, index) => {
+            if (line.toLocaleLowerCase().includes(needle) && result.length < SEARCH_MAX_RESULTS)
+                result.push({ path: relativePath, line: index + 1, text: line.slice(0, 500) });
+        });
+    }
+    return result.slice(0, SEARCH_MAX_RESULTS);
+}
+export function safeShellEnv(env = process.env) {
+    return Object.fromEntries(Object.entries(env).filter(([key]) => !/(API_KEY|TOKEN|SECRET|PASSWORD|PRIVATE_KEY|AUTHORIZATION|BEARER|CREDENTIAL|COOKIE)/i.test(key) && key !== 'NODE_OPTIONS'));
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@hunterzhu/pulse-server",
+  "version": "0.1.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zhuhengtan/Pulse"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "@hunterzhu/pulse-adapters": "0.1.0",
+    "@hunterzhu/pulse-runtime": "0.1.0",
+    "@hunterzhu/pulse-tool-sdk": "0.1.0",
+    "zod": "^3.24.1"
+  }
+}