@hunterzhu/pulse-cli 0.1.11 → 0.2.1

package/README.md

@@ -0,0 +1,55 @@
+# @hunterzhu/pulse-cli
+
+**A local-first AI assistant for coding, research, and everyday file tasks.**
+
+Pulse runs in your project folder, keeps conversations on your machine, and can resume unfinished work. Requires Node.js 22+.
+
+## Install
+
+Install the CLI globally so the `pulse` command is on your `PATH`:
+
+```bash
+npm install -g @hunterzhu/pulse-cli
+pulse --version
+```
+
+For a one-off run, use `npx @hunterzhu/pulse-cli`. Commands below assume a global installation.
+
+## Configure a model and API key
+
+Create a starter configuration:
+
+```bash
+pulse setup
+```
+
+The configuration lives at `~/.pulse/config.json` (Windows:
+`%USERPROFILE%\.pulse\config.json`). A fresh configuration includes the DeepSeek
+provider and `deepseek-chat` model. Set `activeModel` to `deepseek-chat`, or use
+`--model deepseek-chat` as below. The default `mock` model makes no API calls.
+
+Set the API key in your shell; the DeepSeek provider uses
+`apiKeyEnv: "DEEPSEEK_API_KEY"` to read it:
+
+```bash
+export DEEPSEEK_API_KEY="your-key"
+# Windows PowerShell: $env:DEEPSEEK_API_KEY="your-key"
+```
+
+## Usage
+
+```bash
+pulse --model deepseek-chat                        # interactive session
+pulse run "Summarize this project" --model deepseek-chat
+pulse sessions
+pulse resume <conversation-id> "Continue" --model deepseek-chat
+pulse doctor
+pulse --read-only
+```
+
+See `pulse --help` for all options.
+
+## Links
+
+- [Full CLI configuration guide](https://github.com/zhuhengtan/Pulse/blob/main/docs/cli-config.md)
+- [Source code and documentation](https://github.com/zhuhengtan/Pulse)

package/dist/bin.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import type { LocalHostOptions } from '@hunterzhu/pulse-server';
+import { type LocalHostOptions } from '@hunterzhu/pulse-server';
 export declare const version: string;
 export interface Parsed {
     command: string;

package/dist/bin.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 import { readFile } from 'node:fs/promises';
 import { createRequire } from 'node:module';
-import { resolve } from 'node:path';
+import { isAbsolute, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { createMcpCapabilityPack, createPdfCapabilityPack, createSkillCapabilityPack, createSpreadsheetCapabilityPack } from '@hunterzhu/pulse-server';
 import { ensurePulseUserConfig, expandHome, loadPulseConfig } from './config.js';
 import { runInteractive } from './commands/interactive.js';
 import { runOneShot } from './commands/run.js';
@@ -10,6 +11,10 @@ import { runDoctor } from './commands/doctor.js';
 import { runSessions } from './commands/sessions.js';
 import { runResume } from './commands/resume.js';
 import { runSetup } from './commands/setup.js';
+import { runScheduledCommand } from './commands/scheduled.js';
+import { runServiceCommand } from './commands/service.js';
+import { runTemplateCommand } from './commands/template.js';
+import { runMcpDoctor } from './commands/mcp.js';
 import { isSameModulePath } from './utils/is-main-module.js';
 const packageManifest = createRequire(import.meta.url)('../package.json');
 export const version = packageManifest.version;
@@ -26,6 +31,11 @@ Usage:
   pulse sessions [options]                list saved conversations
   pulse resume <conversation-id> [task]    continue or recover a conversation
   pulse doctor [options]                  check local configuration
+  pulse schedule <add|list|pause|resume|remove|daemon> [options]
+                                          manage recurring tasks (daemon requires read-only or auto approval)
+  pulse service <install|status|start|stop|uninstall>
+  pulse template <list|show|run> [name] [values...]
+  pulse mcp doctor [server-id]
 
 Options:
   --cwd <path>              workspace directory
@@ -36,6 +46,7 @@ Options:
   --max-output-tokens <n>   maximum generated tokens (default 4096)
   --reasoning-effort <x>    low, medium, or high
   --max-turns <n>           maximum ReAct model/tool turns (default 32)
+  --execution-mode <mode>   serial (default) or parallel-read (up to three read-only lanes)
   --auto-compact-percent <n> compact automatically at this percent of the context window (1-90, default 90)
   --format <text|jsonl>     output format
   --resume                  enter the latest saved session
@@ -43,10 +54,12 @@ Options:
   --auto-approve             approve local writes and shell execution on your behalf
   --approval-mode <mode>     read-only, ask, or auto
   --allow-network           enable public web search and fetch tools
+  --no-network              disable network tools even when user config enables them
   --trust-workspace         treat workspace .pulse/config.json as user-trusted
   --system-prompt <text>    custom system instructions
   --system-prompt-file <path> load custom system instructions from file
   --mock-response <text>    deterministic response for local debugging
+  --mock-task-assessment <json> deterministic verifier result for local debugging
   --live                    doctor: make one real provider request
   --no-color                disable terminal styling
   --help, -h                show this help
@@ -91,7 +104,7 @@ export function parse(argv) {
             options[key] = true;
             continue;
         }
-        if (!command && ['run', 'sessions', 'resume', 'doctor', 'setup'].includes(arg)) {
+        if (!command && ['run', 'sessions', 'resume', 'doctor', 'setup', 'schedule', 'service', 'template', 'mcp'].includes(arg)) {
             command = arg;
         }
         else {
@@ -124,6 +137,8 @@ export async function hostOptions(parsed) {
     if (!profile)
         throw new Error(`MODEL_PROVIDER_NOT_FOUND:${providerName}`);
     const model = modelSelection.modelCode;
+    if (modelSelection.pricing && (!/^[A-Z]{3}$/.test(modelSelection.pricing.currency) || !Number.isFinite(modelSelection.pricing.inputPerMillion) || modelSelection.pricing.inputPerMillion < 0 || !Number.isFinite(modelSelection.pricing.outputPerMillion) || modelSelection.pricing.outputPerMillion < 0 || !modelSelection.pricing.version.trim()))
+        throw new Error(`INVALID_MODEL_PRICING:${activeModelName}`);
     const baseURL = profile.baseURL;
     const contextTokens = option(parsed.options, 'context-tokens') ?? process.env.PULSE_CONTEXT_TOKENS;
     const maxOutputTokens = option(parsed.options, 'max-output-tokens') ?? process.env.PULSE_MAX_OUTPUT_TOKENS;
@@ -180,18 +195,86 @@ export async function hostOptions(parsed) {
         if (modelDisplayNames.has(displayName))
             throw new Error(`DUPLICATE_MODEL_DISPLAY_NAME:${displayName}`);
         modelDisplayNames.add(displayName);
-        return [[displayName, { provider: item.provider, model: item.modelCode }]];
+        return [[displayName, {
+                    provider: item.provider,
+                    model: item.modelCode,
+                    ...(item.maxContextTokens === undefined ? {} : { maxContextTokens: item.maxContextTokens }),
+                    ...(item.maxOutputTokens === undefined ? {} : { maxOutputTokens: item.maxOutputTokens }),
+                    ...(item.reasoningEffort === undefined ? {} : { reasoningEffort: item.reasoningEffort }),
+                }]];
     }));
+    const taskRouting = config.taskRouting;
+    for (const [task, models] of Object.entries(taskRouting ?? {})) {
+        if (!Array.isArray(models) || models.length === 0 || models.some((model) => typeof model !== 'string' || !providerModels[model])) {
+            throw new Error(`INVALID_TASK_MODEL_ROUTE:${task}`);
+        }
+        if (new Set(models).size !== models.length)
+            throw new Error(`DUPLICATE_TASK_MODEL_ROUTE_CANDIDATE:${task}`);
+    }
     const cwd = requestedCwd ?? expandHome(config.cwd);
     const dataDir = expandHome(option(parsed.options, 'data-dir') ?? process.env.PULSE_DATA_DIR ?? config.dataDir);
     const mockResponse = option(parsed.options, 'mock-response');
+    const mockTaskAssessment = option(parsed.options, 'mock-task-assessment');
+    let mockTaskAssessments;
+    if (mockTaskAssessment !== undefined) {
+        try {
+            const value = JSON.parse(mockTaskAssessment);
+            if (!Array.isArray(value) || value.length === 0 || value.some((item) => !item || typeof item !== 'object' || Array.isArray(item)))
+                throw new Error('INVALID');
+            mockTaskAssessments = value;
+        }
+        catch {
+            throw new Error('INVALID_MOCK_TASK_ASSESSMENT: expected a non-empty JSON array of assessment objects');
+        }
+    }
     const requestedApprovalMode = option(parsed.options, 'approval-mode') ?? process.env.PULSE_APPROVAL_MODE;
     const approvalMode = requestedApprovalMode === 'read-only' || parsed.options['read-only'] === true
         ? 'read-only'
         : requestedApprovalMode === 'auto' || parsed.options['auto-approve'] === true || process.env.PULSE_AUTO_APPROVE === '1'
             ? 'auto'
             : requestedApprovalMode === 'ask' ? 'ask' : config.approvalMode;
-    const allowNetwork = parsed.options['allow-network'] === true || process.env.PULSE_ALLOW_NETWORK === '1' ? true : config.allowNetwork;
+    const allowNetwork = parsed.options['no-network'] === true ? false : parsed.options['allow-network'] === true || process.env.PULSE_ALLOW_NETWORK === '1' ? true : config.allowNetwork;
+    const executionMode = option(parsed.options, 'execution-mode') ?? process.env.PULSE_EXECUTION_MODE ?? config.executionMode ?? 'serial';
+    if (executionMode !== 'serial' && executionMode !== 'parallel-read')
+        throw new Error('INVALID_EXECUTION_MODE: expected serial or parallel-read');
+    const capabilitySettings = config.capabilities ?? {};
+    const skillRoots = capabilitySettings.trustedSkillRoots ?? [];
+    if (!Array.isArray(skillRoots) || skillRoots.some((root) => typeof root !== 'string' || !isAbsolute(expandHome(root) ?? root)))
+        throw new Error('SKILL_TRUSTED_ROOT_MUST_BE_ABSOLUTE');
+    const enabledCapabilityPacks = capabilitySettings.enabled ?? [];
+    if (!Array.isArray(enabledCapabilityPacks) || enabledCapabilityPacks.some((id) => typeof id !== 'string') || new Set(enabledCapabilityPacks).size !== enabledCapabilityPacks.length)
+        throw new Error('INVALID_ENABLED_CAPABILITY_LIST');
+    const skillNames = capabilitySettings.skills ?? [];
+    if (!Array.isArray(skillNames) || skillNames.some((name) => typeof name !== 'string'))
+        throw new Error('INVALID_SKILL_SELECTION');
+    const capabilityPacks = [createPdfCapabilityPack(), createSpreadsheetCapabilityPack(), createSkillCapabilityPack({ trustedRoots: skillRoots.map((root) => resolve(expandHome(root) ?? root)) })];
+    for (const [id, server] of Object.entries(capabilitySettings.mcpServers ?? {})) {
+        if (!server || typeof server.command !== 'string' || server.command.trim().length === 0 || (server.args !== undefined && (!Array.isArray(server.args) || server.args.some((arg) => typeof arg !== 'string'))))
+            throw new Error(`INVALID_MCP_SERVER_CONFIG:${id}`);
+        if (server.toolPolicies && Object.entries(server.toolPolicies).some(([name, policy]) => !name || !['read', 'write', 'external'].includes(policy)))
+            throw new Error(`INVALID_MCP_TOOL_POLICY:${id}`);
+        const resolvedEnv = { ...(server.env ?? {}) };
+        for (const [childName, sourceName] of Object.entries(server.envFrom ?? {})) {
+            if (!/^[A-Z_][A-Z0-9_]*$/i.test(childName) || !/^[A-Z_][A-Z0-9_]*$/i.test(sourceName))
+                throw new Error(`INVALID_MCP_ENV_REFERENCE:${id}`);
+            const value = process.env[sourceName];
+            if (value === undefined)
+                throw new Error(`MCP_ENVIRONMENT_REQUIRED:${id}:${sourceName}`);
+            resolvedEnv[childName] = value;
+        }
+        capabilityPacks.push(createMcpCapabilityPack(id, {
+            command: server.command,
+            args: server.args ?? [],
+            ...(server.cwd === undefined ? {} : { cwd: resolve(expandHome(server.cwd) ?? server.cwd) }),
+            ...(Object.keys(resolvedEnv).length === 0 ? {} : { env: resolvedEnv }),
+            ...(server.timeoutMs === undefined ? {} : { timeoutMs: server.timeoutMs }),
+            ...(server.toolPolicies === undefined ? {} : { toolPolicies: server.toolPolicies }),
+        }));
+    }
+    for (const id of enabledCapabilityPacks) {
+        if (!capabilityPacks.some((pack) => pack.manifest.id === id))
+            throw new Error(`UNKNOWN_ENABLED_CAPABILITY:${id}`);
+    }
     const rawSystemPrompt = option(parsed.options, 'system-prompt') ?? process.env.PULSE_SYSTEM_PROMPT ?? config.systemPrompt;
     const rawSystemPromptFile = option(parsed.options, 'system-prompt-file') ?? process.env.PULSE_SYSTEM_PROMPT_FILE ?? config.systemPromptFile;
     let systemPrompt = rawSystemPrompt;
@@ -218,13 +301,21 @@ export async function hostOptions(parsed) {
         provider,
         providerProfiles,
         providerModels,
+        modelPricing: Object.fromEntries(Object.values(config.models ?? {}).flatMap((item) => item.pricing ? [[item.displayName, item.pricing]] : [])),
+        ...(taskRouting === undefined ? {} : { taskRouting }),
+        capabilityPacks,
+        enabledCapabilityPacks,
+        capabilityConfig: { skills: skillNames },
         activeProviderCode: providerName,
         activeModel: activeModelName,
         ...(mockResponse === undefined ? {} : { mockResponse }),
+        ...(mockTaskAssessments === undefined ? {} : { mockTaskAssessments }),
         ...(approvalMode === undefined ? {} : { approvalMode }),
         ...(configuredMaxTurns === undefined ? {} : { maxTurns: configuredMaxTurns }),
         ...(configuredAutoCompactPercent === undefined ? {} : { autoCompactPercent: Math.min(90, configuredAutoCompactPercent) }),
         ...(allowNetwork === undefined ? {} : { allowNetwork }),
+        ...(config.networkHosts === undefined ? {} : { networkHosts: config.networkHosts }),
+        executionMode,
     };
 }
 export async function main() {
@@ -247,6 +338,15 @@ export async function main() {
     if (parsed.command === 'sessions') {
         return runSessions(options, option(parsed.options, 'format') ?? 'text', version);
     }
+    if (parsed.command === 'schedule') {
+        return runScheduledCommand(options, parsed.positionals, parsed.options);
+    }
+    if (parsed.command === 'service')
+        return runServiceCommand(options, parsed.positionals);
+    if (parsed.command === 'mcp' && parsed.positionals[0] === 'doctor')
+        return runMcpDoctor(options, parsed.positionals.slice(1));
+    if (parsed.command === 'template')
+        return runTemplateCommand(options, parsed.positionals, option(parsed.options, 'format') ?? 'text', version);
     if (parsed.command === 'run') {
         const task = parsed.positionals.join(' ').trim();
         if (!task)

package/dist/commands/mcp.d.ts

@@ -0,0 +1,2 @@
+import type { LocalHostOptions } from '@hunterzhu/pulse-server';
+export declare function runMcpDoctor(options: LocalHostOptions, ids: string[]): Promise<number>;

package/dist/commands/mcp.js

@@ -0,0 +1,29 @@
+export async function runMcpDoctor(options, ids) {
+    const selected = options.enabledCapabilityPacks ?? [];
+    const requested = ids[0] ? selected.filter(id => id === ids[0]) : selected.filter(id => options.capabilityPacks?.some(pack => pack.manifest.id === id && pack.manifest.kind === 'mcp'));
+    if (ids[0] && !requested.includes(ids[0]))
+        throw new Error(`MCP_SERVER_NOT_ENABLED:${ids[0]}`);
+    const rows = [];
+    for (const id of requested) {
+        const pack = options.capabilityPacks?.find(item => item.manifest.id === id && item.manifest.kind === 'mcp');
+        if (!pack)
+            continue;
+        let activation;
+        try {
+            activation = await pack.activate({ workspaceRoot: options.cwd ?? process.cwd(), config: options.capabilityConfig ?? {}, signal: new AbortController().signal });
+            rows.push({ id, status: 'connected', tools: activation.tools.map(tool => tool.manifest.name) });
+        }
+        catch (error) {
+            rows.push({ id, status: 'failed', error: error instanceof Error ? error.message.replace(/(API[_-]?KEY|TOKEN|SECRET|PASSWORD)\s*[:=]\s*[^\s,;]+/gi, '$1=[REDACTED]') : 'MCP_CONNECTION_FAILED' });
+        }
+        finally {
+            await activation?.dispose?.();
+        }
+    }
+    if (!rows.length) {
+        process.stdout.write('No enabled MCP servers. Configure capabilities.mcpServers and capabilities.enabled.\n');
+        return 1;
+    }
+    process.stdout.write(`${JSON.stringify({ servers: rows }, null, 2)}\n`);
+    return rows.some(row => row.status !== 'connected') ? 1 : 0;
+}

package/dist/commands/resume.js

@@ -47,12 +47,14 @@ export async function runResume(options, conversationId, task, format = 'text',
             }
         }
         const outcome = await run.outcome();
+        const taskOutcome = await run.taskOutcome();
         if (format === 'jsonl') {
             process.stdout.write(`${JSON.stringify({
                 schemaVersion: 1,
                 type: 'result',
                 runId: run.id,
                 status: outcome.status,
+                taskOutcome: taskOutcome ?? null,
                 text: outcome.text ?? null,
                 error: outcome.error ?? null,
             })}\n`);
@@ -66,7 +68,9 @@ export async function runResume(options, conversationId, task, format = 'text',
         else {
             process.stdout.write(`\n[${outcome.status}]\n`);
         }
-        return outcome.status === 'succeeded' ? 0 : outcome.status === 'cancelled' ? 3 : 1;
+        if (outcome.status === 'cancelled')
+            return 3;
+        return outcome.status === 'succeeded' && (!taskOutcome || taskOutcome.status === 'accepted') ? 0 : 1;
     }
     catch (error) {
         process.stderr.write(`[错误] ${error instanceof Error ? error.message : String(error)}\n`);

package/dist/commands/run.js

@@ -49,12 +49,16 @@ export async function runOneShot(options, task, format = 'text', version = '0.1.
             }
         }
         const outcome = await run.outcome();
+        const taskOutcome = await run.taskOutcome();
+        const usage = await run.usage();
         if (format === 'jsonl') {
             process.stdout.write(`${JSON.stringify({
                 schemaVersion: 1,
                 type: 'result',
                 runId: run.id,
                 status: outcome.status,
+                taskOutcome: taskOutcome ?? null,
+                usage,
                 text: outcome.text ?? null,
                 error: outcome.error ?? null,
             })}\n`);
@@ -68,7 +72,9 @@ export async function runOneShot(options, task, format = 'text', version = '0.1.
         else {
             process.stdout.write(`\n[${outcome.status}]\n`);
         }
-        return outcome.status === 'succeeded' ? 0 : outcome.status === 'cancelled' ? 3 : 1;
+        if (outcome.status === 'cancelled')
+            return 3;
+        return outcome.status === 'succeeded' && (!taskOutcome || taskOutcome.status === 'accepted') ? 0 : 1;
     }
     finally {
         unbindSignals();

package/dist/commands/scheduled.d.ts

@@ -0,0 +1,2 @@
+import { type LocalHostOptions } from '@hunterzhu/pulse-server';
+export declare function runScheduledCommand(options: LocalHostOptions, args: string[], flags: Record<string, string | boolean>): Promise<number>;

package/dist/commands/scheduled.js

@@ -0,0 +1,131 @@
+import { realpath } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import { createLocalHost, MAX_SCHEDULED_TASK_INTERVAL_MS, MIN_SCHEDULED_TASK_INTERVAL_MS, ScheduledTaskStore, ScheduledTaskWorker, pulseDataPath } from '@hunterzhu/pulse-server';
+function parseInterval(raw) {
+    if (!raw)
+        throw new Error('SCHEDULE_EVERY_REQUIRED');
+    const match = /^(\d+)(ms|s|m|h|d)$/.exec(raw.trim());
+    if (!match)
+        throw new Error('INVALID_SCHEDULE_INTERVAL: use 30s, 15m, 2h, or 1d');
+    const value = Number(match[1]);
+    const multiplier = match[2] === 'ms' ? 1 : match[2] === 's' ? 1_000 : match[2] === 'm' ? 60_000 : match[2] === 'h' ? 3_600_000 : 86_400_000;
+    const intervalMs = value * multiplier;
+    if (!Number.isSafeInteger(intervalMs) || intervalMs < MIN_SCHEDULED_TASK_INTERVAL_MS || intervalMs > MAX_SCHEDULED_TASK_INTERVAL_MS)
+        throw new Error('SCHEDULE_INTERVAL_OUT_OF_RANGE');
+    return intervalMs;
+}
+function storeFor(options) {
+    return new ScheduledTaskStore(join(resolve(options.dataDir ?? pulseDataPath()), 'scheduled-tasks.json'));
+}
+function output(value, format) {
+    process.stdout.write(format === 'jsonl' ? `${JSON.stringify(value)}\n` : `${JSON.stringify(value, null, 2)}\n`);
+}
+export async function runScheduledCommand(options, args, flags) {
+    const [action, id] = args;
+    if (!action)
+        throw new Error('SCHEDULE_ACTION_REQUIRED');
+    const store = storeFor(options);
+    if (action === 'add') {
+        const name = typeof flags.name === 'string' ? flags.name : undefined;
+        const instruction = args.slice(1).join(' ').trim();
+        if (!instruction)
+            throw new Error('SCHEDULE_TASK_REQUIRED');
+        const task = await store.create({ workspace: await realpath(resolve(options.cwd ?? process.cwd())), name: name ?? instruction.slice(0, 120), instruction, intervalMs: parseInterval(typeof flags.every === 'string' ? flags.every : undefined) });
+        output(task, typeof flags.format === 'string' ? flags.format : 'text');
+        return 0;
+    }
+    if (action === 'list') {
+        output(await store.list(), typeof flags.format === 'string' ? flags.format : 'text');
+        return 0;
+    }
+    if (action === 'recover') {
+        if (!id)
+            throw new Error('SCHEDULE_RECOVER_REQUIRES_ID');
+        if (flags['confirm-stopped'] !== true)
+            throw new Error('SCHEDULE_RECOVER_REQUIRES_CONFIRMATION: stop the worker and child processes, then pass --confirm-stopped');
+        const task = await store.get(id);
+        if (!task?.run?.quarantined)
+            throw new Error(`SCHEDULED_TASK_NOT_QUARANTINED:${id}`);
+        const recovered = await store.recoverQuarantined(id, task.run.id);
+        if (!recovered)
+            throw new Error('SCHEDULED_TASK_RECOVERY_RACE');
+        output(recovered, typeof flags.format === 'string' ? flags.format : 'text');
+        return 0;
+    }
+    if (action === 'pause' || action === 'resume' || action === 'remove') {
+        if (!id)
+            throw new Error(`SCHEDULE_${action.toUpperCase()}_REQUIRES_ID`);
+        const result = action === 'remove' ? await store.remove(id) : await store.pause(id, action === 'pause');
+        if (!result)
+            throw new Error(`SCHEDULED_TASK_NOT_FOUND:${id}`);
+        output(result, typeof flags.format === 'string' ? flags.format : 'text');
+        return 0;
+    }
+    if (action !== 'daemon' && action !== 'run-once')
+        throw new Error(`UNKNOWN_SCHEDULE_ACTION:${action}`);
+    if (options.approvalMode !== 'read-only' && options.approvalMode !== 'auto')
+        throw new Error('SCHEDULED_EXECUTION_REQUIRES_READ_ONLY_OR_AUTO_APPROVAL');
+    const host = createLocalHost(options);
+    await host.init();
+    let currentRun;
+    const worker = new ScheduledTaskWorker(store, async (task, signal) => {
+        if (signal.aborted)
+            throw Object.assign(new Error('SCHEDULED_RUN_ABORTED'), { code: 'SCHEDULED_RUN_ABORTED' });
+        if (!task.workspace)
+            throw new Error('SCHEDULED_TASK_WORKSPACE_REQUIRED: recreate this legacy task');
+        const conversation = await host.createConversation({ cwd: task.workspace, title: `Scheduled: ${task.name}` });
+        const run = await host.sendMessage(conversation.id, { text: task.instruction });
+        currentRun = run;
+        const abort = () => { void run.cancel('SCHEDULED_WORKER_STOPPING').catch(() => { }); };
+        signal.addEventListener('abort', abort, { once: true });
+        if (signal.aborted)
+            abort();
+        try {
+            for await (const _event of run.events) {
+                if (signal.aborted) {
+                    await run.cancel('SCHEDULED_WORKER_STOPPING');
+                    throw Object.assign(new Error('SCHEDULED_RUN_ABORTED'), { code: 'SCHEDULED_RUN_ABORTED' });
+                }
+            }
+            const outcome = await run.outcome();
+            const taskOutcome = await run.taskOutcome();
+            if (signal.aborted)
+                throw new Error('SCHEDULED_RUN_ABORTED');
+            if (outcome.status !== 'succeeded')
+                throw Object.assign(new Error(`RUNTIME_${outcome.status.toUpperCase()}`), { code: `RUNTIME_${outcome.status.toUpperCase()}` });
+            if (taskOutcome?.status !== 'accepted')
+                throw Object.assign(new Error(`TASK_${(taskOutcome?.status ?? 'unverified').toUpperCase()}`), { code: `TASK_${(taskOutcome?.status ?? 'unverified').toUpperCase()}` });
+        }
+        catch (error) {
+            // Runtime cancellation may settle before an uncooperative tool stops.
+            // Keep the durable claim until this worker process has exited.
+            if (signal.aborted)
+                throw Object.assign(new Error('SCHEDULED_TASK_CANCELLATION_UNCONFIRMED'), { code: 'SCHEDULED_TASK_CANCELLATION_UNCONFIRMED', cause: error });
+            throw error;
+        }
+        finally {
+            signal.removeEventListener('abort', abort);
+            if (currentRun === run)
+                currentRun = undefined;
+        }
+    });
+    const controller = new AbortController();
+    const stop = () => { controller.abort(); void currentRun?.cancel('SCHEDULED_WORKER_STOPPING'); };
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+    let runOnceSummary;
+    try {
+        if (action === 'run-once') {
+            runOnceSummary = await worker.runOnce(controller.signal);
+            output(runOnceSummary, typeof flags.format === 'string' ? flags.format : 'text');
+        }
+        else
+            await worker.start(controller.signal);
+    }
+    finally {
+        process.removeListener('SIGINT', stop);
+        process.removeListener('SIGTERM', stop);
+        await host.close();
+    }
+    return runOnceSummary && runOnceSummary.failed > 0 ? 1 : 0;
+}

package/dist/commands/service.d.ts

@@ -0,0 +1,2 @@
+import type { LocalHostOptions } from '@hunterzhu/pulse-server';
+export declare function runServiceCommand(options: LocalHostOptions, args: string[]): Promise<number>;

package/dist/commands/service.js

@@ -0,0 +1,81 @@
+import { access, mkdir, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+const serviceId = 'com.hunterzhu.pulse.scheduler';
+function checked(file, args) { const result = spawnSync(file, args, { encoding: 'utf8' }); if (result.status !== 0)
+    throw new Error(`${file} ${args[0]} failed: ${(result.stderr || result.stdout || '').trim()}`); }
+function xml(value) { return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&apos;'); }
+function quoteSystemd(value) { return `"${value.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('%', '%%')}"`; }
+export async function runServiceCommand(options, args) {
+    const [action] = args;
+    if (!['install', 'status', 'start', 'stop', 'uninstall'].includes(action ?? ''))
+        throw new Error('SERVICE_ACTION_REQUIRED');
+    const platform = process.platform;
+    const home = process.env.PULSE_HOME ?? homedir();
+    const executable = process.execPath;
+    const entry = fileURLToPath(new URL('../bin.js', import.meta.url));
+    const config = process.env.PULSE_CONFIG ?? join(home, '.pulse', 'config.json');
+    const data = options.dataDir ?? process.env.PULSE_DATA_DIR ?? join(home, '.pulse', 'data');
+    const cwd = options.cwd ?? process.cwd();
+    if (action === 'install') {
+        if (!['darwin', 'linux', 'win32'].includes(platform))
+            throw new Error(`SERVICE_PLATFORM_UNSUPPORTED:${platform}`);
+        if (platform === 'darwin') {
+            const directory = join(home, 'Library', 'LaunchAgents');
+            const file = join(directory, `${serviceId}.plist`);
+            await mkdir(directory, { recursive: true });
+            await writeFile(file, `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict><key>Label</key><string>${serviceId}</string><key>ProgramArguments</key><array>${[executable, entry, 'schedule', 'daemon', '--approval-mode', options.approvalMode === 'auto' ? 'auto' : 'read-only'].map(v => `<string>${xml(v)}</string>`).join('')}</array><key>WorkingDirectory</key><string>${xml(cwd)}</string><key>EnvironmentVariables</key><dict><key>PULSE_HOME</key><string>${xml(home)}</string><key>PULSE_CONFIG</key><string>${xml(config)}</string><key>PULSE_DATA_DIR</key><string>${xml(data)}</string></dict><key>RunAtLoad</key><true/><key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict><key>ThrottleInterval</key><integer>30</integer><key>StandardOutPath</key><string>${xml(join(data, 'service.log'))}</string><key>StandardErrorPath</key><string>${xml(join(data, 'service.error.log'))}</string></dict></plist>\n`, { mode: 0o600 });
+            await mkdir(data, { recursive: true });
+            checked('launchctl', ['bootstrap', `gui/${process.getuid?.() ?? 0}`, file]);
+        }
+        else if (platform === 'linux') {
+            const directory = join(home, '.config', 'systemd', 'user');
+            const file = join(directory, 'pulse-scheduler.service');
+            await mkdir(directory, { recursive: true });
+            await writeFile(file, `[Unit]\nDescription=Pulse scheduled task worker\n\n[Service]\nType=simple\nWorkingDirectory=${quoteSystemd(cwd)}\nEnvironment=${quoteSystemd(`PULSE_HOME=${home}`)}\nEnvironment=${quoteSystemd(`PULSE_CONFIG=${config}`)}\nEnvironment=${quoteSystemd(`PULSE_DATA_DIR=${data}`)}\nExecStart=${quoteSystemd(executable)} ${quoteSystemd(entry)} schedule daemon --approval-mode ${options.approvalMode === 'auto' ? 'auto' : 'read-only'}\nRestart=on-failure\nRestartSec=30s\n\n[Install]\nWantedBy=default.target\n`, { mode: 0o600 });
+            checked('systemctl', ['--user', 'daemon-reload']);
+            checked('systemctl', ['--user', 'enable', '--now', 'pulse-scheduler.service']);
+        }
+        else {
+            const task = 'Pulse Scheduler';
+            const command = `"${executable}" "${entry}" schedule daemon --approval-mode ${options.approvalMode === 'auto' ? 'auto' : 'read-only'}`;
+            checked('schtasks.exe', ['/Create', '/F', '/SC', 'ONLOGON', '/TN', task, '/TR', command]);
+        }
+        process.stdout.write(`Installed user scheduler service (${platform}); status: pulse service status\n`);
+        return 0;
+    }
+    if (platform === 'darwin') {
+        const file = join(home, 'Library', 'LaunchAgents', `${serviceId}.plist`);
+        if (action === 'status' && await access(file).then(() => false, () => true)) {
+            process.stdout.write('Scheduler service is not installed.\n');
+            return 0;
+        }
+        if (action === 'uninstall') {
+            spawnSync('launchctl', ['bootout', `gui/${process.getuid?.() ?? 0}`, file], { stdio: 'ignore' });
+            await rm(file, { force: true });
+            return 0;
+        }
+        const result = spawnSync('launchctl', [action === 'status' ? 'print' : action === 'start' ? 'kickstart' : 'kill', ...(action === 'start' ? ['-k'] : action === 'stop' ? ['SIGTERM'] : []), `gui/${process.getuid?.() ?? 0}/${serviceId}`], { encoding: 'utf8' });
+        process.stdout.write(result.stdout || result.stderr || `${action}: ${result.status === 0 ? 'ok' : 'not running'}\n`);
+        return result.status === 0 ? 0 : 1;
+    }
+    if (platform === 'linux') {
+        if (action === 'status' && await access(join(home, '.config', 'systemd', 'user', 'pulse-scheduler.service')).then(() => false, () => true)) {
+            process.stdout.write('Scheduler service is not installed.\n');
+            return 0;
+        }
+        const verb = action === 'status' ? 'status' : action === 'start' ? 'start' : action === 'stop' ? 'stop' : 'disable';
+        const result = spawnSync('systemctl', ['--user', verb, ...(action === 'uninstall' ? ['--now'] : []), 'pulse-scheduler.service'], { encoding: 'utf8' });
+        if (action === 'uninstall')
+            await rm(join(home, '.config', 'systemd', 'user', 'pulse-scheduler.service'), { force: true });
+        process.stdout.write(result.stdout || result.stderr || '');
+        return result.status === 0 ? 0 : 1;
+    }
+    const task = 'Pulse Scheduler';
+    const verb = action === 'status' ? '/Query' : action === 'start' ? '/Run' : action === 'stop' ? '/End' : '/Delete';
+    const result = spawnSync('schtasks.exe', [verb, '/TN', task, ...(action === 'uninstall' ? ['/F'] : [])], { encoding: 'utf8' });
+    process.stdout.write(result.stdout || result.stderr || '');
+    return result.status === 0 ? 0 : 1;
+}

package/dist/commands/template.d.ts

@@ -0,0 +1,2 @@
+import type { LocalHostOptions } from '@hunterzhu/pulse-server';
+export declare function runTemplateCommand(options: LocalHostOptions, args: string[], format: string, version: string): Promise<number>;

package/dist/commands/template.js

@@ -0,0 +1,31 @@
+import { runOneShot } from './run.js';
+const templates = [
+    { version: 1, name: 'code-review', description: '审查当前工作区中的代码变更并给出有证据的问题清单。', parameters: ['focus'], deliverables: ['按严重程度排序的 findings', '文件路径与行号'], acceptance: ['每条问题有可复核代码证据', '不把风格偏好列作缺陷'], prompt: '审查当前工作区代码变更。重点：{{focus}}。只报告能从源码证明的问题，按严重度排序，给出路径和行号；若没有发现，说明审查范围和未覆盖部分。' },
+    { version: 1, name: 'research', description: '围绕问题检索资料并整理可追溯结论。', parameters: ['question', 'sources'], deliverables: ['结论摘要', '来源及支持的主张'], acceptance: ['区分事实与推断', '每项关键结论附来源'], prompt: '研究问题：{{question}}。优先使用这些来源范围：{{sources}}。给出结论、证据链接、更新时间和不确定性；无法核验的内容标明未知。' },
+    { version: 1, name: 'file-organization', description: '按规则整理工作区文件，先规划并遵守工具审批。', parameters: ['rules'], deliverables: ['整理后的文件', '移动清单'], acceptance: ['不覆盖已有目标', '总结每次移动'], prompt: '按以下规则整理当前工作区文件：{{rules}}。先检查现状并制定计划，再执行获批的移动；遇到目标冲突时跳过并报告。' },
+    { version: 1, name: 'project-health', description: '检查项目入口、构建、测试和近期变更，报告健康状态。', parameters: ['scope'], deliverables: ['检查结果', '风险与建议'], acceptance: ['运行检查前说明具体命令', '区分已验证和推测'], prompt: '检查项目健康状态，范围：{{scope}}。阅读项目脚本与文档，运行适用的本地只读检查，汇报证据、失败和未覆盖项；不得安装、发布或修改文件。' },
+];
+function render(template, values) {
+    if (values.length !== template.parameters.length)
+        throw new Error(`TEMPLATE_ARGUMENTS_REQUIRED:${template.name}:${template.parameters.join(',')}`);
+    let prompt = template.prompt;
+    template.parameters.forEach((name, index) => { prompt = prompt.replaceAll(`{{${name}}}`, values[index] ?? ''); });
+    return prompt;
+}
+export async function runTemplateCommand(options, args, format, version) {
+    const [action, name, ...values] = args;
+    if (action === 'list') {
+        process.stdout.write(templates.map(item => `${item.name}\t${item.description}`).join('\n') + '\n');
+        return 0;
+    }
+    const template = templates.find(item => item.name === name);
+    if (!template)
+        throw new Error(action === 'run' || action === 'show' ? `TEMPLATE_NOT_FOUND:${name ?? ''}` : 'TEMPLATE_ACTION_REQUIRED');
+    if (action === 'show') {
+        process.stdout.write(`${JSON.stringify(template, null, 2)}\n`);
+        return 0;
+    }
+    if (action !== 'run')
+        throw new Error('TEMPLATE_ACTION_REQUIRED');
+    return runOneShot(options, render(template, values), format, version);
+}