ferrycat 0.3.2 → 0.4.0

package/dist/daemon.js

@@ -0,0 +1,372 @@
+/**
+ * FerryCat Controlled Daemon (Phase 3 Step 1, ADR-0005 Hardened).
+ *
+ * Provides a production-grade, background-ready execution orchestrator:
+ *   - Short-transaction CAS leases on `daemon_locks` table.
+ *   - Cryptographically random per-process owner token (prevents split-brain on identical configs).
+ *   - Automatic process tree termination on lease loss (CK-04/05).
+ *   - Safe heartbeat intervals clamped to <= lease_ttl_sec / 2.
+ *   - Robust heartbeat exception recovery.
+ *   - Declarative handler execution with args and environment forwarding.
+ *   - Graceful shutdown on SIGINT/SIGTERM.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { FerryCatEngine, expandTilde } from './engine.js';
+import { FerryCatConfigFileSchema, } from './schemas.js';
+import { executeTaskAndFulfill, terminateActiveChildrenSync } from './supervisor.js';
+export function loadFerryCatConfig(customConfigPath) {
+    const candidatePaths = [];
+    if (customConfigPath) {
+        candidatePaths.push(path.resolve(expandTilde(customConfigPath)));
+    }
+    if (process.env.FERRYCAT_CONFIG) {
+        candidatePaths.push(path.resolve(expandTilde(process.env.FERRYCAT_CONFIG)));
+    }
+    candidatePaths.push(path.resolve(process.cwd(), 'ferrycat.config.json'));
+    candidatePaths.push(path.join(os.homedir(), '.ferrycat', 'config.json'));
+    for (const candidate of candidatePaths) {
+        if (fs.existsSync(candidate)) {
+            try {
+                const raw = fs.readFileSync(candidate, 'utf8');
+                const parsed = JSON.parse(raw);
+                const validated = FerryCatConfigFileSchema.parse(parsed);
+                return { config: validated, resolvedPath: candidate };
+            }
+            catch (err) {
+                throw new Error(`Failed to parse FerryCat configuration file at '${candidate}': ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    // Return empty valid default configuration if no file exists
+    return {
+        config: FerryCatConfigFileSchema.parse({}),
+        resolvedPath: null,
+    };
+}
+export function notifyOperator(title, message) {
+    try {
+        const timestamp = new Date().toISOString();
+        // Always emit structured line to stderr/stdout
+        process.stderr.write(`[FerryCat Daemon Notice] ${timestamp} | ${title}: ${message}\n`);
+    }
+    catch (err) {
+        if (err && typeof err === 'object' && 'code' in err && err.code === 'EPIPE') {
+            // EPIPE indicates downstream logger closed its pipe early; safe to swallow silently
+            return;
+        }
+    }
+}
+export class FerryCatDaemon {
+    engine;
+    config;
+    configPath;
+    lockId;
+    leaseTtlSec;
+    heartbeatIntervalMs;
+    pollIntervalMs;
+    ownerToken;
+    targetAgentFilter;
+    notifyEnabled;
+    isRunning = false;
+    isLeader = false;
+    heartbeatTimer = null;
+    pollTimer = null;
+    signalCleanupRegistered = false;
+    activeInFlightContract = null;
+    constructor(options = {}) {
+        const { config, resolvedPath } = loadFerryCatConfig(options.configPath);
+        this.config = config;
+        this.configPath = resolvedPath;
+        this.engine = new FerryCatEngine({ dbPath: options.dbPath });
+        this.lockId = options.lockId ?? config.daemon.lock_id ?? 'global';
+        // Ensure lease TTL is at least 5 seconds
+        const reqTtl = options.leaseTtlSec ?? config.daemon.lease_ttl_sec ?? 30;
+        this.leaseTtlSec = Math.max(5, reqTtl);
+        // Enforce heartbeat interval <= leaseTtl / 2 to prevent false expirations
+        const reqHeartbeat = options.heartbeatIntervalMs ?? config.daemon.heartbeat_interval_ms ?? 5000;
+        const maxHeartbeat = Math.floor((this.leaseTtlSec * 1000) / 2);
+        this.heartbeatIntervalMs = Math.min(reqHeartbeat, maxHeartbeat);
+        this.pollIntervalMs = options.pollIntervalMs ?? config.daemon.poll_interval_ms ?? 1000;
+        // Critical Finding 1: Never accept a static shared owner_token across daemon processes.
+        // Always generate a unique cryptographic token per runtime instance.
+        this.ownerToken = `daemon-${process.pid}-${crypto.randomBytes(8).toString('hex')}`;
+        this.targetAgentFilter = options.targetAgent;
+        this.notifyEnabled = options.notify ?? config.daemon.notify ?? true;
+    }
+    registerSignalHandlers() {
+        if (this.signalCleanupRegistered)
+            return;
+        this.signalCleanupRegistered = true;
+        const cleanup = (sig) => {
+            if (this.notifyEnabled) {
+                notifyOperator('Shutdown', `Received ${sig}, terminating children and releasing lease...`);
+            }
+            this.stop();
+            terminateActiveChildrenSync();
+            this.engine.releaseDaemonLease({ lock_id: this.lockId, owner_token: this.ownerToken });
+            this.engine.close();
+            process.exit(0);
+        };
+        process.once('SIGINT', () => cleanup('SIGINT'));
+        process.once('SIGTERM', () => cleanup('SIGTERM'));
+    }
+    acquireLease() {
+        try {
+            const res = this.engine.acquireDaemonLease({
+                lock_id: this.lockId,
+                owner_token: this.ownerToken,
+                ttl_sec: this.leaseTtlSec,
+                metadata: {
+                    pid: process.pid,
+                    hostname: os.hostname(),
+                    platform: process.platform,
+                    config_path: this.configPath,
+                },
+            });
+            if (res.ok) {
+                this.isLeader = true;
+                return true;
+            }
+            this.isLeader = false;
+            return false;
+        }
+        catch (err) {
+            this.isLeader = false;
+            if (this.notifyEnabled) {
+                notifyOperator('Lease Error', `Acquire lease error: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            return false;
+        }
+    }
+    renewLease() {
+        if (!this.isLeader)
+            return false;
+        try {
+            const res = this.engine.renewDaemonLease({
+                lock_id: this.lockId,
+                owner_token: this.ownerToken,
+                ttl_sec: this.leaseTtlSec,
+            });
+            if (!res.ok) {
+                // Critical WorkBuddy P1 Fix: When lease is lost, don't kill active contract to FAILED.
+                // First voluntarily release in-flight contract back to queue tail so new leader can claim it!
+                this.isLeader = false;
+                if (this.activeInFlightContract) {
+                    try {
+                        this.engine.releaseContract({
+                            contract_id: this.activeInFlightContract.contract_id,
+                            agent_id: this.activeInFlightContract.target_agent,
+                            claim_token: this.activeInFlightContract.claim_token,
+                            reason: 'DAEMON_LEASE_LOST',
+                        });
+                    }
+                    catch {
+                        // best-effort release
+                    }
+                    this.activeInFlightContract = null;
+                }
+                terminateActiveChildrenSync();
+                if (this.notifyEnabled) {
+                    notifyOperator('Lease Lost', `Failed to renew lease '${this.lockId}': ${res.message}. In-flight contract released and children terminated.`);
+                }
+                return false;
+            }
+            return true;
+        }
+        catch (err) {
+            // WorkBuddy Finding: On SQLite/IO exception, demote to non-leader, backoff, and release in-flight contract
+            this.isLeader = false;
+            if (this.activeInFlightContract) {
+                try {
+                    this.engine.releaseContract({
+                        contract_id: this.activeInFlightContract.contract_id,
+                        agent_id: this.activeInFlightContract.target_agent,
+                        claim_token: this.activeInFlightContract.claim_token,
+                        reason: 'DAEMON_HEARTBEAT_EXCEPTION',
+                    });
+                }
+                catch {
+                    // best-effort release
+                }
+                this.activeInFlightContract = null;
+            }
+            terminateActiveChildrenSync();
+            if (this.notifyEnabled) {
+                notifyOperator('Lease Error', `Heartbeat exception: ${err instanceof Error ? err.message : String(err)}. Contract released and children terminated.`);
+            }
+            return false;
+        }
+    }
+    releaseLease() {
+        if (this.isLeader) {
+            try {
+                this.engine.releaseDaemonLease({
+                    lock_id: this.lockId,
+                    owner_token: this.ownerToken,
+                });
+            }
+            catch {
+                // best-effort cleanup on shutdown
+            }
+            this.isLeader = false;
+        }
+    }
+    resolveHandler(targetAgent, taskType) {
+        const agentConfig = this.config.agents[targetAgent];
+        if (!agentConfig)
+            return null;
+        const typedTask = taskType;
+        if (agentConfig.handlers && agentConfig.handlers[typedTask]) {
+            return agentConfig.handlers[typedTask];
+        }
+        if (agentConfig.default_handler) {
+            return agentConfig.default_handler;
+        }
+        return null;
+    }
+    /**
+     * Process a single cycle: check lease, poll task, execute configured handler if matched.
+     */
+    async pollAndDispatchOnce() {
+        if (!this.isLeader) {
+            const acquired = this.acquireLease();
+            if (!acquired) {
+                return { processed: false, reason: 'LEASE_NOT_HELD' };
+            }
+        }
+        // Determine target agent(s) to poll
+        const targetAgentsToPoll = this.targetAgentFilter
+            ? [this.targetAgentFilter]
+            : Object.keys(this.config.agents);
+        if (targetAgentsToPoll.length === 0) {
+            // If no configured agents, poll without target agent filter
+            return this.pollAgentQueue(undefined);
+        }
+        for (const agent of targetAgentsToPoll) {
+            const res = await this.pollAgentQueue(agent);
+            if (res.processed) {
+                return res;
+            }
+        }
+        return { processed: false, reason: 'NO_TASK_AVAILABLE' };
+    }
+    async pollAgentQueue(agentId) {
+        // Determine configured task types for this agent to avoid claiming unhandled tasks (WorkBuddy P1)
+        let eligibleTaskTypes;
+        if (agentId && this.config.agents[agentId]) {
+            const agentCfg = this.config.agents[agentId];
+            if (!agentCfg.default_handler && agentCfg.handlers) {
+                eligibleTaskTypes = Object.keys(agentCfg.handlers);
+                if (eligibleTaskTypes.length === 0) {
+                    // If agent has no handlers and no default_handler, skip polling this agent completely
+                    return { processed: false, reason: 'NO_HANDLERS_CONFIGURED' };
+                }
+            }
+        }
+        const pollResult = this.engine.pollNextTask({
+            agent_id: agentId,
+            task_types: eligibleTaskTypes,
+        });
+        if (!pollResult.has_task || !pollResult.contract || pollResult.status !== 'CLAIMED') {
+            return { processed: false, reason: 'NO_TASK_AVAILABLE' };
+        }
+        const contract = pollResult.contract;
+        const handler = this.resolveHandler(contract.target_agent, contract.task_type);
+        if (!handler) {
+            // Fallback: If somehow claimed without handler (e.g. default_handler was missing), release back to queue cleanly
+            const warningMsg = `No handler configured in ferrycat.config.json for agent '${contract.target_agent}' task '${contract.task_type}'. Releasing contract back to queue.`;
+            if (this.notifyEnabled) {
+                notifyOperator('Unhandled Task', warningMsg);
+            }
+            this.engine.releaseContract({
+                contract_id: contract.contract_id,
+                agent_id: contract.target_agent,
+                claim_token: contract.claim_token,
+                reason: `NO_HANDLER_CONFIGURED: Task type '${contract.task_type}' not handled by this node.`,
+            });
+            return {
+                processed: false,
+                contract_id: contract.contract_id,
+                reason: 'NO_HANDLER_CONFIGURED',
+            };
+        }
+        if (this.notifyEnabled) {
+            notifyOperator('Task Claimed', `Agent '${contract.target_agent}' executing contract ${contract.contract_id} (${contract.task_type}: "${contract.title}") via ${handler.exec_file}`);
+        }
+        // Track active in-flight contract for graceful lease loss failover
+        this.activeInFlightContract = {
+            contract_id: contract.contract_id,
+            target_agent: contract.target_agent,
+            claim_token: contract.claim_token,
+        };
+        try {
+            // Forward configured args and pass_env (contract's own exec_ttl_sec is authoritative)
+            const execResult = await executeTaskAndFulfill(this.engine, contract, {
+                execFile: handler.exec_file,
+                passEnv: handler.pass_env,
+                args: handler.args,
+            });
+            if (this.notifyEnabled) {
+                notifyOperator('Task Finished', `Contract ${contract.contract_id} concluded with status '${execResult.status}' (ok=${execResult.ok})`);
+            }
+            return {
+                processed: true,
+                contract_id: contract.contract_id,
+                status: execResult.status,
+            };
+        }
+        finally {
+            this.activeInFlightContract = null;
+        }
+    }
+    async start() {
+        this.registerSignalHandlers();
+        this.isRunning = true;
+        // Heartbeat ticker loop for lease renewal
+        this.heartbeatTimer = setInterval(() => {
+            try {
+                if (this.isRunning && this.isLeader) {
+                    this.renewLease();
+                }
+            }
+            catch (err) {
+                if (this.notifyEnabled) {
+                    notifyOperator('Heartbeat Ticker Error', err instanceof Error ? err.message : String(err));
+                }
+            }
+        }, this.heartbeatIntervalMs);
+        // Main polling loop
+        const tick = async () => {
+            if (!this.isRunning)
+                return;
+            try {
+                await this.pollAndDispatchOnce();
+            }
+            catch (err) {
+                if (this.notifyEnabled) {
+                    notifyOperator('Daemon Loop Error', err instanceof Error ? err.message : String(err));
+                }
+            }
+            if (this.isRunning) {
+                this.pollTimer = setTimeout(tick, this.pollIntervalMs);
+            }
+        };
+        tick();
+    }
+    stop() {
+        this.isRunning = false;
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        if (this.pollTimer) {
+            clearTimeout(this.pollTimer);
+            this.pollTimer = null;
+        }
+        this.releaseLease();
+    }
+}
+//# sourceMappingURL=daemon.js.map

package/dist/daemon.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon.js","sourceRoot":"","sources":["../src/daemon.ts"],"names":[],"mappings":"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"}

package/dist/demo.d.ts

@@ -0,0 +1,36 @@
+export interface DemoOptions {
+    /** Keep the sandbox directory on disk and report its path instead of deleting it. */
+    keep?: boolean;
+    /** Suppress all human-readable output; the caller receives only the structured result. */
+    json?: boolean;
+    /** Sink for human-readable lines. Defaults to process.stdout. Ignored when `json` is true. */
+    write?: (line: string) => void;
+    /** Force ANSI colors on/off. Defaults to auto-detection (TTY and no NO_COLOR). */
+    color?: boolean;
+    /** Lifetime of the demo child process in ms (0 = finish immediately). */
+    execDelayMs?: number;
+    /** Execution TTL granted to the demo contract, in seconds. */
+    execTtlSec?: number;
+}
+export interface DemoStepRecord {
+    index: number;
+    total: number;
+    title: string;
+    fields: Record<string, string>;
+}
+export interface DemoResult {
+    ok: boolean;
+    sandbox: string;
+    sandbox_kept: boolean;
+    contract_id: string;
+    claim_token: string;
+    status: string;
+    verdict: 'PASSED' | 'CHANGES_REQUESTED';
+    issues: string[];
+    dirty_files: number;
+    heartbeat_renewals: number;
+    elapsed_ms: number;
+    steps: DemoStepRecord[];
+    warnings: string[];
+}
+export declare function runDemo(options?: DemoOptions): Promise<DemoResult>;