@pasko70/pibo 1.1.0 → 1.3.0

package/dist/ralph/cli.js

@@ -0,0 +1,152 @@
+import { readFileSync } from 'node:fs';
+import { Command } from 'commander';
+import { createDefaultPiboRalphStore } from './store.js';
+import { createBuiltInRalphStopConditions } from './stopping.js';
+import { getRalphJobTemplate, listRalphJobTemplates } from './templates.js';
+function printDiscovery() {
+    console.log(`pibo ralph
+
+Manage continuous Ralph Pibo agent jobs.
+
+Commands:
+  status    Show Ralph status
+  list      List Ralph jobs
+  add       Create a Ralph job
+  edit      Update a Ralph job
+  conditions List registered built-in stop conditions
+  templates List built-in Ralph job templates
+  policy    Show, set, or clear a job stop policy
+  start     Start a Ralph job now
+  stop      Stop after the current session finishes
+  cancel    Abort the current session and stop
+  remove    Delete a Ralph job
+  runs      List Ralph runs
+
+Next: pibo ralph add --help`);
+}
+function targetFromOptions(options) { if (options.room)
+    return { kind: 'room', roomId: options.room }; if (options.defaultChat)
+    return { kind: 'default-chat' }; throw new Error('Choose a target: --room <room-id> or --default-chat'); }
+function maybeTargetFromOptions(options) { if (options.room || options.defaultChat)
+    return targetFromOptions(options); return undefined; }
+function printJson(value) { console.log(JSON.stringify(value, null, 2)); }
+function maxIterations(value) { if (value === undefined)
+    return undefined; const parsed = Number(value); if (!Number.isInteger(parsed) || parsed < 1)
+    throw new Error('--max-iterations must be a positive integer'); return parsed; }
+function templatePatch(id) {
+    if (!id)
+        return {};
+    const template = getRalphJobTemplate(id);
+    if (!template)
+        throw new Error(`Unknown Ralph template: ${id}`);
+    return { name: template.job.name, description: template.job.description, prompt: template.job.prompt, maxIterations: template.job.maxIterations ?? null, stopPolicy: template.job.stopPolicy ?? null };
+}
+function compactResourceText(value, max = 80) { return value.length <= max ? value : `${value.slice(0, max - 1)}…`; }
+function shellToken(value) { return /^[A-Za-z0-9._:@/-]+$/.test(value) ? value : `'${value.replace(/'/g, `'"'"'`)}'`; }
+export function formatRalphResourceSummary(resources) {
+    if (!resources)
+        return '-';
+    const parts = [
+        resources.workerId ? `worker=${resources.workerId}` : undefined,
+        resources.cleanupState ? `state=${resources.cleanupState}` : undefined,
+        resources.browserLeaseIds?.length ? `leases=${resources.browserLeaseIds.length}` : undefined,
+        resources.retainedUntil ? `retainedUntil=${resources.retainedUntil}` : undefined,
+        resources.dirtyReason ? `dirty=${compactResourceText(resources.dirtyReason)}` : undefined,
+    ].filter((part) => !!part);
+    if (resources.cleanupState === 'dirty')
+        parts.push(`next=${resources.workerId ? `pibo tools browser-use pool reap --worker-id ${shellToken(resources.workerId)} --json` : 'pibo compute reap --dry-run'}`);
+    else if (resources.cleanupState === 'retained')
+        parts.push('next=pibo compute reap --dry-run --include-dev');
+    return parts.length ? parts.join(';') : '-';
+}
+function formatRalphJobLine(job) { return `${job.id}\t${job.enabled ? 'running' : 'stopped'}\t${job.state.runningAt ? 'active' : '-'}\tresources=${formatRalphResourceSummary(job.resources)}\t${job.name}`; }
+function formatRalphRunLine(run) { return `${run.id}\t${run.jobId}\t${run.status}\t${run.piboSessionId ?? '-'}\t${run.completedAt ?? '-'}\tresources=${formatRalphResourceSummary(run.resources)}`; }
+export async function runRalphCli(argv = process.argv) {
+    const program = new Command();
+    program.name('pibo ralph').description('Manage continuous Ralph Pibo jobs').helpOption('-h, --help');
+    program.option('--store <path>', 'Ralph store path');
+    program.command('status').description('Show Ralph store status').option('--json', 'Print JSON').action((options) => { const store = createDefaultPiboRalphStore({ path: program.opts().store }); const status = store.status(); if (options.json)
+        printJson(status);
+    else {
+        console.log(`jobs\t${status.jobs}`);
+        console.log(`running\t${status.running}`);
+    } store.close(); });
+    program.command('list').description('List Ralph jobs').option('--all', 'Include stopped jobs').option('--json', 'Print JSON').action((options) => { const store = createDefaultPiboRalphStore({ path: program.opts().store }); const jobs = store.listJobs({ includeDisabled: options.all }); if (options.json)
+        printJson(jobs);
+    else
+        for (const job of jobs)
+            console.log(formatRalphJobLine(job)); store.close(); });
+    program.command('add').description('Create a Ralph job').option('--template <id>', 'Built-in job template id').option('--prompt <text>', 'Task prompt').option('--name <name>', 'Job name').option('--description <text>', 'Job description').option('--profile <profile>', 'Agent profile', 'default').option('--room <room-id>', 'Target room id').option('--default-chat', 'Target the shared default chat').option('--max-iterations <n>', 'Stop after n completed run attempts')
+        .option('--start', 'Start immediately').option('--json', 'Print JSON').action((options) => { const base = templatePatch(options.template); const prompt = options.prompt ?? base.prompt; if (typeof prompt !== 'string' || !prompt.trim())
+        throw new Error('Choose --template <id> or provide --prompt <text>'); const store = createDefaultPiboRalphStore({ path: program.opts().store }); const job = store.createJob({ name: options.name ?? base.name, description: options.description ?? base.description, enabled: options.start === true, target: targetFromOptions(options), profile: options.profile, prompt, maxIterations: options.maxIterations !== undefined ? maxIterations(options.maxIterations) : typeof base.maxIterations === 'number' ? base.maxIterations : undefined, stopPolicy: base.stopPolicy ?? undefined }); if (options.json)
+        printJson(job);
+    else
+        console.log(`${job.id}\t${job.enabled ? 'running' : 'stopped'}\t${job.name}`); store.close(); });
+    program.command('edit').argument('<id>', 'Ralph job id').description('Update a Ralph job').option('--template <id>', 'Apply a built-in job template before explicit overrides').option('--prompt <text>', 'Task prompt').option('--name <name>', 'Job name').option('--description <text>', 'Job description').option('--profile <profile>', 'Agent profile').option('--room <room-id>', 'Target room id').option('--default-chat', 'Target the shared default chat').option('--max-iterations <n>', 'Stop after n completed run attempts').option('--json', 'Print JSON').action((id, options) => { const store = createDefaultPiboRalphStore({ path: program.opts().store }); const patch = { ...templatePatch(options.template) }; if (options.name !== undefined)
+        patch.name = options.name; if (options.description !== undefined)
+        patch.description = options.description; if (options.profile !== undefined)
+        patch.profile = options.profile; if (options.prompt !== undefined)
+        patch.prompt = options.prompt; if (options.maxIterations !== undefined)
+        patch.maxIterations = maxIterations(options.maxIterations); const target = maybeTargetFromOptions(options); if (target)
+        patch.target = target; if (Object.keys(patch).length === 0)
+        throw new Error('No Ralph job update fields provided'); const job = store.updateJob(id, patch); if (!job)
+        throw new Error('Ralph job not found'); if (options.json)
+        printJson(job);
+    else
+        console.log(`${job.id}\tupdated\t${job.name}`); store.close(); });
+    program.command('conditions').description('List built-in Ralph stop-condition types').option('--json', 'Print JSON').action((options) => { const conditions = createBuiltInRalphStopConditions().map((condition) => ({ type: condition.type, name: condition.name, description: condition.description, phases: condition.phases, defaultOptions: condition.defaultOptions, optionsSchema: condition.optionsSchema })); if (options.json)
+        printJson(conditions);
+    else
+        for (const condition of conditions)
+            console.log(`${condition.type}	${condition.phases.join(',')}	${condition.name}`); });
+    program.command('templates').description('List built-in Ralph job templates').option('--json', 'Print JSON').action((options) => { const templates = listRalphJobTemplates(); if (options.json)
+        printJson(templates);
+    else
+        for (const template of templates)
+            console.log(`${template.id}\t${template.category}\t${template.name}\t${template.description}`); });
+    const policy = program.command('policy').description('Manage a Ralph job stop policy');
+    policy.command('show').argument('<id>').option('--json', 'Print JSON').action((id, options) => { const store = createDefaultPiboRalphStore({ path: program.opts().store }); const job = store.getJob(id); if (!job)
+        throw new Error('Ralph job not found'); const value = job.stopPolicy ?? null; if (options.json)
+        printJson(value);
+    else
+        console.log(value ? JSON.stringify(value, null, 2) : 'default'); store.close(); });
+    policy.command('set').argument('<id>').requiredOption('--file <path>', 'JSON stop policy file').option('--json', 'Print JSON').action((id, options) => { const store = createDefaultPiboRalphStore({ path: program.opts().store }); const stopPolicy = JSON.parse(readFileSync(options.file, 'utf8')); const job = store.updateJob(id, { stopPolicy }); if (!job)
+        throw new Error('Ralph job not found'); if (options.json)
+        printJson(job);
+    else
+        console.log(`${job.id}	policy-updated	${job.name}`); store.close(); });
+    policy.command('clear').argument('<id>').option('--json', 'Print JSON').action((id, options) => { const store = createDefaultPiboRalphStore({ path: program.opts().store }); const job = store.updateJob(id, { stopPolicy: null }); if (!job)
+        throw new Error('Ralph job not found'); if (options.json)
+        printJson(job);
+    else
+        console.log(`${job.id}	policy-cleared	${job.name}`); store.close(); });
+    program.command('start').argument('<id>').description('Mark a Ralph job running; the gateway service starts the next session').option('--json', 'Print JSON').action((id, options) => { const store = createDefaultPiboRalphStore({ path: program.opts().store }); const job = store.updateJob(id, { enabled: true }); if (!job)
+        throw new Error('Ralph job not found'); if (options.json)
+        printJson(job);
+    else
+        console.log(`${job.id}\trunning\t${job.name}`); store.close(); });
+    program.command('stop').argument('<id>').description('Stop after the current session finishes').option('--json', 'Print JSON').action((id, options) => { const store = createDefaultPiboRalphStore({ path: program.opts().store }); const job = store.requestStop(id); if (!job)
+        throw new Error('Ralph job not found'); if (options.json)
+        printJson(job);
+    else
+        console.log(`${job.id}\tstopping\t${job.name}`); store.close(); });
+    program.command('cancel').argument('<id>').description('Abort the current session and stop').option('--json', 'Print JSON').action((id, options) => { const store = createDefaultPiboRalphStore({ path: program.opts().store }); const job = store.requestCancel(id); if (!job)
+        throw new Error('Ralph job not found'); if (options.json)
+        printJson(job);
+    else
+        console.log(`${job.id}\tcancel-requested\t${job.name}`); store.close(); });
+    program.command('remove').argument('<id>').description('Delete a Ralph job').option('--json', 'Print JSON').action((id, options) => { const store = createDefaultPiboRalphStore({ path: program.opts().store }); const removed = store.removeJob(id); if (options.json)
+        printJson({ removed });
+    else
+        console.log(removed ? 'removed' : 'not found'); store.close(); });
+    program.command('runs').description('List Ralph runs').option('--job <id>', 'Filter by job').option('--json', 'Print JSON').action((options) => { const store = createDefaultPiboRalphStore({ path: program.opts().store }); const runs = store.listRuns({ jobId: options.job }); if (options.json)
+        printJson(runs);
+    else
+        for (const run of runs)
+            console.log(formatRalphRunLine(run)); store.close(); });
+    if (argv.length <= 2 || argv.includes('--help') || argv.includes('-h')) {
+        printDiscovery();
+        return;
+    }
+    await program.parseAsync(argv);
+}

package/dist/ralph/plugin.js

@@ -0,0 +1,14 @@
+import { definePiboPlugin } from '../plugins/registry.js';
+import { createPiboRalphChannel } from './channel.js';
+import { createBuiltInRalphStopConditions } from './stopping.js';
+export function createPiboRalphPlugin(options = {}) {
+    return definePiboPlugin({
+        id: 'pibo.ralph',
+        name: 'Pibo Ralph',
+        register(api) {
+            for (const condition of createBuiltInRalphStopConditions())
+                api.registerRalphStopCondition(condition);
+            api.registerChannel(createPiboRalphChannel(options));
+        },
+    });
+}

package/dist/ralph/service.js

@@ -0,0 +1,271 @@
+import { randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { getDefaultPiboWorkspace } from '../core/workspace.js';
+import { PiboDataStore } from '../data/pibo-store.js';
+import { ChatRoomService } from '../apps/chat/data/room-service.js';
+import { isPiboRoomArchived } from '../apps/chat/types/rooms.js';
+import { browserPoolPaths, releaseBrowserPoolLease } from '../tools/browser-pool.js';
+import { createDefaultPiboRalphStore } from './store.js';
+import { createBuiltInRalphStopConditions, evaluateRalphStopPolicy } from './stopping.js';
+const CHAT_WEB_CHANNEL = 'pibo.chat-web';
+function errorMessage(error) { return error instanceof Error ? error.message : String(error); }
+function buildRalphPrompt(job) { return ['You are running a continuous Pibo Ralph job.', `Job: ${job.name}`, `Target: ${job.target.kind}`, '', 'Complete the task below. Return the result in this session. When this session finishes, Ralph may start a fresh session with the same task unless a configured stop condition is satisfied.', 'Important: if this job uses a promise-complete stop condition, do not quote, negate, explain, or mention its literal completion marker unless the task is fully complete and you intend to stop the job.', '', 'Task:', job.prompt].join('\n'); }
+function isJsonObject(value) { return !!value && typeof value === 'object' && !Array.isArray(value); }
+function mergeRunResources(jobResources, runResources) {
+    if (!jobResources && !runResources)
+        return undefined;
+    const browserLeaseIds = [...new Set([...(jobResources?.browserLeaseIds ?? []), ...(runResources?.browserLeaseIds ?? [])])];
+    return {
+        ...(jobResources ?? {}),
+        ...(runResources ?? {}),
+        ...(browserLeaseIds.length ? { browserLeaseIds } : {}),
+    };
+}
+function clearDirtyReason(resources) {
+    const clean = { ...resources };
+    delete clean.dirtyReason;
+    return clean;
+}
+export class PiboRalphService {
+    options;
+    store;
+    dataStore;
+    roomService;
+    intervalMs;
+    maxConcurrentRuns;
+    runTimeoutMs;
+    timer;
+    activeRuns = 0;
+    stopped = true;
+    cancelledRuns = new Set();
+    unsubscribeProductEvents;
+    constructor(options) {
+        this.options = options;
+        this.store = options.store ?? createDefaultPiboRalphStore();
+        this.dataStore = new PiboDataStore(options.dataStorePath, { payloadRootDir: options.dataPayloadRootDir });
+        this.roomService = new ChatRoomService(this.dataStore);
+        this.intervalMs = options.intervalMs ?? 5_000;
+        this.maxConcurrentRuns = Math.max(1, options.maxConcurrentRuns ?? 2);
+        this.runTimeoutMs = options.runTimeoutMs ?? 30 * 60_000;
+    }
+    start() { if (!this.stopped)
+        return; this.stopped = false; this.store.recoverInterruptedRuns(); this.unsubscribeProductEvents = this.options.context.subscribeProductEvents?.((event) => this.handleProductEvent(event)); this.arm(250); }
+    stop() { this.stopped = true; if (this.timer)
+        clearTimeout(this.timer); this.timer = undefined; this.unsubscribeProductEvents?.(); this.unsubscribeProductEvents = undefined; this.dataStore.close(); this.store.close(); }
+    status() { return { enabled: !this.stopped, ...this.store.status() }; }
+    async startJob(id) { const job = this.store.updateJob(id, { enabled: true }); if (!job)
+        return undefined; const reserved = await this.reserveAfterBeforeRunEvaluation(job); if (!reserved)
+        return undefined; void this.executeReserved(reserved.job, reserved.run).finally(() => this.armSoon()); return reserved.run; }
+    stopJob(id) { const job = this.store.requestStop(id); this.armSoon(); return job; }
+    async cancelJob(id) {
+        const job = this.store.requestCancel(id);
+        if (!job)
+            return undefined;
+        await this.abortJobIfRunning(job);
+        this.armSoon();
+        return this.store.getJob(id);
+    }
+    arm(delayMs) { if (this.stopped)
+        return; if (this.timer)
+        clearTimeout(this.timer); this.timer = setTimeout(() => void this.tick(), delayMs ?? this.intervalMs); }
+    armSoon() { this.arm(250); }
+    async tick() { if (this.stopped)
+        return; try {
+        await this.abortCancelRequestedJobs();
+        const capacity = this.maxConcurrentRuns - this.activeRuns;
+        if (capacity > 0) {
+            const jobs = this.store.listJobs({ includeDisabled: false }).filter((job) => !job.state.runningAt).slice(0, capacity);
+            for (const job of jobs) {
+                const reserved = await this.reserveAfterBeforeRunEvaluation(job);
+                if (reserved)
+                    void this.executeReserved(reserved.job, reserved.run).finally(() => this.armSoon());
+            }
+        }
+    }
+    catch (error) {
+        console.error('[ralph] scheduler tick failed', error);
+    }
+    finally {
+        this.arm();
+    } }
+    async reserveAfterBeforeRunEvaluation(job) {
+        const fresh = this.store.getJob(job.id) ?? job;
+        if (!fresh.enabled || fresh.state.runningAt)
+            return undefined;
+        const { evaluation, conditionStates } = await this.evaluateStopPolicy(fresh, 'before-run');
+        if (evaluation.finalAction !== 'continue') {
+            this.store.applyStopEvaluation({ jobId: fresh.id, evaluation, conditionStates, disable: true });
+            return undefined;
+        }
+        this.store.applyStopEvaluation({ jobId: fresh.id, evaluation, conditionStates, disable: false });
+        return this.store.reserveRun(fresh.id);
+    }
+    async abortCancelRequestedJobs() { for (const job of this.store.listJobs({ includeDisabled: true })) {
+        if (job.state.cancelRequestedAt)
+            await this.abortJobIfRunning(job);
+    } }
+    async abortJobIfRunning(job) {
+        if (!job.state.runningAt || !job.state.lastRunId)
+            return;
+        const sessionId = job.state.lastPiboSessionId;
+        if (!sessionId) {
+            this.markRunResourcesDirty(job, 'Cancel requested but active session is unavailable; browser lease may still exist');
+            return;
+        }
+        this.cancelledRuns.add(job.state.lastRunId);
+        try {
+            await this.options.context.emit({ type: 'execution', piboSessionId: sessionId, action: 'abort', id: `ralph_cancel_${randomUUID()}` });
+        }
+        catch (error) {
+            this.cancelledRuns.delete(job.state.lastRunId);
+            this.markRunResourcesDirty(job, `Cancel requested but abort failed: ${errorMessage(error)}`);
+        }
+    }
+    async executeReserved(job, run) {
+        this.activeRuns += 1;
+        try {
+            const result = await this.executeJob(job, run);
+            const cancelled = this.cancelledRuns.delete(run.id);
+            const outcome = { status: cancelled ? 'cancelled' : 'ok', piboSessionId: result.piboSessionId, finalAnswer: result.finalAnswer };
+            const { evaluation, conditionStates } = await this.evaluateStopPolicy(this.store.getJob(job.id) ?? job, 'after-run', run, outcome);
+            this.store.completeRun({ jobId: job.id, runId: run.id, status: outcome.status, piboSessionId: result.piboSessionId, reason: cancelled ? 'cancelled' : evaluation.reason, stopAfterRun: evaluation.finalAction !== 'continue', stopEvaluation: evaluation, conditionStates });
+            await this.cleanupRunResources(job, run);
+        }
+        catch (error) {
+            const cancelled = this.cancelledRuns.delete(run.id);
+            const outcome = { status: cancelled ? 'cancelled' : 'error', error: cancelled ? undefined : errorMessage(error) };
+            const { evaluation, conditionStates } = await this.evaluateStopPolicy(this.store.getJob(job.id) ?? job, 'after-run', run, outcome);
+            this.store.completeRun({ jobId: job.id, runId: run.id, status: outcome.status, error: outcome.error, reason: cancelled ? 'cancelled' : evaluation.reason, stopAfterRun: evaluation.finalAction !== 'continue', stopEvaluation: evaluation, conditionStates });
+            await this.cleanupRunResources(job, run);
+            if (!cancelled)
+                console.error(`[ralph] job ${job.id} failed`, error);
+        }
+        finally {
+            this.activeRuns -= 1;
+        }
+    }
+    markRunResourcesDirty(job, dirtyReason) {
+        const latestJob = this.store.getJob(job.id) ?? job;
+        const runId = latestJob.state.lastRunId ?? job.state.lastRunId;
+        const latestRun = runId ? this.store.listRuns({ jobId: latestJob.id, limit: 100 }).find((candidate) => candidate.id === runId) : undefined;
+        const resources = mergeRunResources(latestJob.resources, latestRun?.resources);
+        if (!resources || (!resources.workerId && (resources.browserLeaseIds ?? []).length === 0))
+            return;
+        const nextResources = { ...resources, cleanupState: 'dirty', dirtyReason, updatedAt: new Date().toISOString() };
+        try {
+            if (latestRun)
+                this.store.updateRunResources({ jobId: latestJob.id, runId: latestRun.id, resources: nextResources });
+            this.store.updateJobResources(latestJob.id, nextResources);
+        }
+        catch (error) {
+            console.error(`[ralph] failed to mark resource cleanup dirty for job ${latestJob.id}`, error);
+        }
+    }
+    async cleanupRunResources(job, run) {
+        const latestJob = this.store.getJob(job.id) ?? job;
+        const latestRun = this.store.listRuns({ jobId: job.id, limit: 100 }).find((candidate) => candidate.id === run.id) ?? run;
+        const resources = mergeRunResources(latestJob.resources, latestRun.resources);
+        const leaseIds = resources?.browserLeaseIds ?? [];
+        if (!resources || leaseIds.length === 0)
+            return;
+        const workerId = resources.workerId || process.env.PIBO_BROWSER_POOL_WORKER_ID || process.env.PIBO_COMPUTE_WORKER_ID || process.env.HOSTNAME || 'local';
+        const poolId = this.options.resourceCleanup?.browserPoolId || process.env.PIBO_BROWSER_POOL_ID || 'default';
+        const rootDir = this.options.resourceCleanup?.browserPoolRootDir || process.env.PIBO_BROWSER_POOL_ROOT || join(process.env.BROWSER_USE_HOME || join(homedir(), '.browser-use'), 'pibo-browser-pool');
+        const identity = { workerId, poolId };
+        const paths = browserPoolPaths(rootDir, identity);
+        const release = this.options.resourceCleanup?.releaseBrowserPoolLease ?? releaseBrowserPoolLease;
+        let dirtyReason;
+        for (const leaseId of leaseIds) {
+            try {
+                const result = await release(paths, identity, { leaseId, lockOptions: { holder: `ralph:${run.id}` } });
+                if (result.cleanupStatus === 'failed' || result.state.state === 'dirty' || (!result.released && !!result.state.activeLeaseId))
+                    dirtyReason = result.lastError || `Browser lease ${leaseId} cleanup failed`;
+            }
+            catch (error) {
+                dirtyReason = `Browser lease ${leaseId} cleanup failed: ${errorMessage(error)}`;
+            }
+            if (dirtyReason)
+                break;
+        }
+        const updatedAt = new Date().toISOString();
+        const nextResources = dirtyReason
+            ? { ...resources, workerId, cleanupState: 'dirty', dirtyReason, updatedAt }
+            : clearDirtyReason({ ...resources, workerId, cleanupState: 'released', updatedAt });
+        try {
+            this.store.updateRunResources({ jobId: job.id, runId: run.id, resources: nextResources });
+            this.store.updateJobResources(job.id, nextResources);
+        }
+        catch (error) {
+            console.error(`[ralph] failed to record resource cleanup for run ${run.id}`, error);
+        }
+    }
+    async evaluateStopPolicy(job, phase, run, outcome) {
+        return await evaluateRalphStopPolicy({ job, phase, definitions: this.getStopConditionDefinitions(), facts: this.store.createFactReader(job), run, outcome });
+    }
+    getStopConditionDefinitions() { return this.options.context.getRalphStopConditionDefinitions?.() ?? createBuiltInRalphStopConditions(); }
+    handleProductEvent(event) {
+        if (event.type !== 'pibo.ralph.fact' && event.type !== 'ralph.fact')
+            return;
+        const payload = event.payload;
+        if (!isJsonObject(payload.payload))
+            return;
+        if (typeof payload.jobId !== 'string' || typeof payload.type !== 'string')
+            return;
+        const source = payload.source === 'pi-extension' || payload.source === 'tool' || payload.source === 'plugin' || payload.source === 'pibo' ? payload.source : 'plugin';
+        try {
+            this.store.appendRunFact({ jobId: payload.jobId, runId: typeof payload.runId === 'string' ? payload.runId : undefined, piboSessionId: typeof payload.piboSessionId === 'string' ? payload.piboSessionId : undefined, type: payload.type, source: source, payload: payload.payload });
+        }
+        catch (error) {
+            console.error('[ralph] failed to append run fact', error);
+        }
+    }
+    async executeJob(job, run) {
+        const target = this.resolveTarget(job);
+        const session = this.options.context.createSession({
+            channel: CHAT_WEB_CHANNEL,
+            kind: 'ralph',
+            profile: job.profile,
+            workspace: target.workspace ?? getDefaultPiboWorkspace(),
+            title: job.name,
+            activeModel: job.modelOverride ? { ...job.modelOverride } : undefined,
+            metadata: {
+                ...(target.metadata ?? {}),
+                chatRoomId: target.roomId,
+                ralphJobId: job.id,
+                ralphRunId: run.id,
+                ralphTargetKind: job.target.kind,
+                ...(job.thinkingLevel ? { initialThinkingLevel: job.thinkingLevel } : {}),
+                ...(job.fastMode !== undefined ? { initialFastMode: job.fastMode } : {}),
+            },
+        });
+        this.store.attachRunSession(job.id, run.id, session.id);
+        const finalAnswer = await this.emitMessageAndWait(session.id, buildRalphPrompt(job), { isCancelled: () => this.cancelledRuns.has(run.id) });
+        return { piboSessionId: session.id, finalAnswer };
+    }
+    resolveTarget(job) { if (job.target.kind === 'room') {
+        const room = this.roomService.getRoom(job.target.roomId);
+        if (!room)
+            throw new Error('Target room no longer exists');
+        if (isPiboRoomArchived(room))
+            throw new Error('Target room is archived');
+        return { roomId: room.id, workspace: room.workspace ?? getDefaultPiboWorkspace() };
+    } const room = this.roomService.ensureDefaultRoom({ name: 'Shared Chat' }); return { roomId: room.id, workspace: room.workspace ?? getDefaultPiboWorkspace() }; }
+    async emitMessageAndWait(piboSessionId, text, options = {}) {
+        const eventId = `ralph_msg_${randomUUID()}`;
+        return await new Promise((resolve, reject) => { let settled = false; let deltaAnswer = ''; let finalAnswer = ''; let lastSessionError; let unsubscribe; const timeout = setTimeout(() => finish(new Error(lastSessionError ? `Ralph run timed out after session error: ${lastSessionError}` : 'Ralph run timed out')), this.runTimeoutMs); const finish = (error) => { if (settled)
+            return; settled = true; clearTimeout(timeout); unsubscribe?.(); if (error)
+            reject(error);
+        else
+            resolve(finalAnswer || deltaAnswer); }; unsubscribe = this.options.context.subscribe((event) => { if (event.piboSessionId !== piboSessionId)
+            return; if ('eventId' in event && event.eventId !== eventId)
+            return; if (event.type === 'assistant_delta')
+            deltaAnswer += event.text; if (event.type === 'assistant_message')
+            finalAnswer = event.text; if (event.type === 'message_finished')
+            finish(); if (event.type === 'session_error') {
+            lastSessionError = event.error;
+            if (options.isCancelled?.())
+                finish(new Error(event.error));
+        } }); this.options.context.emit({ type: 'message', piboSessionId, id: eventId, source: 'service', text }).catch((error) => finish(error instanceof Error ? error : new Error(String(error)))); });
+    }
+}

package/dist/ralph/stopping.js

@@ -0,0 +1,151 @@
+import { randomUUID } from 'node:crypto';
+export const PROMISE_COMPLETE_STOP_TOKEN = '<promise>COMPLETE</promise>';
+export const MAX_ITERATIONS_STOP_CONDITION = 'pibo.ralph.max-iterations';
+export const PROMISE_COMPLETE_STOP_CONDITION = 'pibo.ralph.promise-complete';
+export const FACT_COUNT_STOP_CONDITION = 'pibo.ralph.fact-count';
+function hasPromiseCompleteMarker(finalAnswer) { return finalAnswer.split(/\r?\n/).some((line) => line.trim() === PROMISE_COMPLETE_STOP_TOKEN); }
+function isObject(value) { return !!value && typeof value === 'object' && !Array.isArray(value); }
+function stringOption(options, key) { const value = options?.[key]; return typeof value === 'string' && value.trim() ? value.trim() : undefined; }
+function numberOption(options, key) { const value = options?.[key]; return typeof value === 'number' && Number.isFinite(value) ? value : undefined; }
+function boolOption(options, key) { const value = options?.[key]; return typeof value === 'boolean' ? value : undefined; }
+export function getDefaultRalphStopPolicy(job) {
+    const conditions = [];
+    if (job.maxIterations !== undefined)
+        conditions.push({ id: 'max-iterations', type: MAX_ITERATIONS_STOP_CONDITION });
+    conditions.push({ id: 'promise-complete', type: PROMISE_COMPLETE_STOP_CONDITION });
+    return { mode: 'any', conditions };
+}
+export function getEffectiveRalphStopPolicy(job) {
+    return job.stopPolicy ?? getDefaultRalphStopPolicy(job);
+}
+export function createBuiltInRalphStopConditions() {
+    return [
+        {
+            type: MAX_ITERATIONS_STOP_CONDITION,
+            name: 'Max iterations',
+            description: 'Stops a Ralph job after its configured number of completed run attempts, regardless of outcome.',
+            phases: ['before-run', 'after-run'],
+            evaluate(context) {
+                const maxIterations = context.job.maxIterations;
+                if (maxIterations === undefined)
+                    return { action: 'continue' };
+                const current = context.job.state.completedIterations ?? 0;
+                const completed = context.phase === 'after-run' && context.outcome ? current + 1 : current;
+                if (completed >= maxIterations)
+                    return { action: 'stop-after-run', reason: 'max-iterations', details: { maxIterations, completedIterations: completed } };
+                return { action: 'continue', details: { maxIterations, completedIterations: completed } };
+            },
+        },
+        {
+            type: PROMISE_COMPLETE_STOP_CONDITION,
+            name: 'Promise complete token',
+            description: 'Stops after a successful run whose final answer contains the promise-complete marker on its own line.',
+            phases: ['after-run'],
+            evaluate(context) {
+                const finalAnswer = context.outcome?.finalAnswer ?? '';
+                if (context.outcome?.status === 'ok' && hasPromiseCompleteMarker(finalAnswer))
+                    return { action: 'stop-after-run', reason: 'promise-complete', details: { token: PROMISE_COMPLETE_STOP_TOKEN } };
+                return { action: 'continue' };
+            },
+        },
+        {
+            type: FACT_COUNT_STOP_CONDITION,
+            name: 'Run fact count',
+            description: 'Stops when the current run or job history contains at least a configured number of matching Ralph run facts.',
+            phases: ['after-run'],
+            defaultOptions: { factType: 'example.fact', threshold: 1, currentRunOnly: true },
+            optionsSchema: {
+                type: 'object',
+                properties: {
+                    factType: { type: 'string', description: 'Fact type to count.' },
+                    threshold: { type: 'number', description: 'Stop after at least this many facts.' },
+                    currentRunOnly: { type: 'boolean', description: 'Only count facts for the current run.' },
+                    reason: { type: 'string', description: 'Optional stop reason.' },
+                },
+            },
+            evaluate(context) {
+                const factType = stringOption(context.instance.options, 'factType');
+                if (!factType)
+                    return { action: 'continue', details: { missingOption: 'factType' } };
+                const threshold = Math.max(1, Math.floor(numberOption(context.instance.options, 'threshold') ?? 1));
+                const currentRunOnly = boolOption(context.instance.options, 'currentRunOnly') ?? true;
+                const runId = currentRunOnly ? context.run?.id : undefined;
+                const count = context.facts.count({ type: factType, runId });
+                if (count >= threshold)
+                    return { action: 'stop-after-run', reason: stringOption(context.instance.options, 'reason') ?? `fact:${factType}`, details: { factType, threshold, count, currentRunOnly } };
+                return { action: 'continue', details: { factType, threshold, count, currentRunOnly } };
+            },
+        },
+    ];
+}
+function severity(action) {
+    if (action === 'cancel-current-run')
+        return 2;
+    if (action === 'stop-after-run')
+        return 1;
+    return 0;
+}
+function highest(left, right) { return severity(right) > severity(left) ? right : left; }
+function sanitizeDecision(value) {
+    if (!isObject(value))
+        throw new Error('condition returned a non-object decision');
+    if (value.action !== 'continue' && value.action !== 'stop-after-run' && value.action !== 'cancel-current-run')
+        throw new Error('condition returned an invalid action');
+    return { action: value.action, reason: typeof value.reason === 'string' ? value.reason : undefined, details: isObject(value.details) ? value.details : undefined, nextState: isObject(value.nextState) ? value.nextState : undefined };
+}
+async function withTimeout(promise, timeoutMs, signal) {
+    if (!timeoutMs || timeoutMs <= 0)
+        return await promise;
+    return await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => reject(new Error(`condition timed out after ${timeoutMs}ms`)), timeoutMs);
+        if (signal)
+            signal.addEventListener('abort', () => reject(new Error('condition aborted')), { once: true });
+        promise.then((value) => { clearTimeout(timeout); resolve(value); }, (error) => { clearTimeout(timeout); reject(error); });
+    });
+}
+export async function evaluateRalphStopPolicy(input) {
+    const now = (input.now ?? new Date()).toISOString();
+    const policy = getEffectiveRalphStopPolicy(input.job);
+    const definitions = new Map(input.definitions.map((definition) => [definition.type, definition]));
+    const decisions = [];
+    const conditionStates = { ...(input.job.state.conditionStates ?? {}) };
+    let finalAction = 'continue';
+    for (const instance of policy.conditions) {
+        const base = { id: instance.id, type: instance.type, phase: input.phase };
+        if (instance.enabled === false) {
+            decisions.push({ ...base, action: 'continue', skipped: true, reason: 'disabled' });
+            continue;
+        }
+        const definition = definitions.get(instance.type);
+        if (!definition) {
+            decisions.push({ ...base, action: 'continue', skipped: true, error: `Unknown Ralph stop condition type: ${instance.type}` });
+            continue;
+        }
+        if (!definition.phases.includes(input.phase)) {
+            decisions.push({ ...base, action: 'continue', skipped: true, reason: 'unsupported-phase' });
+            continue;
+        }
+        try {
+            const state = conditionStates[instance.id] ?? {};
+            const decision = sanitizeDecision(await withTimeout(Promise.resolve(definition.evaluate({ phase: input.phase, job: input.job, policy, instance, state, now, run: input.run, outcome: input.outcome, facts: input.facts, signal: input.signal })), instance.timeoutMs ?? definition.timeoutMs, input.signal));
+            if (decision.nextState)
+                conditionStates[instance.id] = decision.nextState;
+            decisions.push({ ...base, action: decision.action, reason: decision.reason, details: decision.details });
+        }
+        catch (error) {
+            const failClosed = instance.failClosed ?? definition.failClosedDefault ?? false;
+            const action = failClosed ? 'stop-after-run' : 'continue';
+            decisions.push({ ...base, action, reason: failClosed ? 'condition-error-fail-closed' : 'condition-error', error: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    const active = decisions.filter((decision) => !decision.skipped);
+    if (policy.mode === 'all' && active.length > 0) {
+        const allStop = active.every((decision) => severity(decision.action) >= severity('stop-after-run'));
+        finalAction = allStop ? active.reduce((action, decision) => highest(action, decision.action), 'stop-after-run') : 'continue';
+    }
+    else {
+        finalAction = active.reduce((action, decision) => highest(action, decision.action), 'continue');
+    }
+    const contributing = finalAction === 'continue' ? active.find((decision) => decision.error || decision.reason) : active.find((decision) => decision.action === finalAction) ?? active.find((decision) => severity(decision.action) > 0);
+    return { evaluation: { id: `rse_${randomUUID()}`, phase: input.phase, at: now, mode: policy.mode, finalAction, reason: contributing?.reason ?? (contributing?.error ? 'condition-error' : undefined), decisions }, conditionStates };
+}