@pasko70/pibo 1.1.0 → 1.3.0

package/dist/ralph/store.js

@@ -0,0 +1,450 @@
+import { randomUUID } from 'node:crypto';
+import { mkdirSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { piboHomePath } from '../core/pibo-home.js';
+import { isPiboThinkingLevel } from '../core/thinking.js';
+function nowIso(now = new Date()) { return now.toISOString(); }
+function parseJson(json) { return JSON.parse(json); }
+function defaultName(prompt) { const normalized = prompt.replace(/\s+/g, ' ').trim(); return normalized ? normalized.slice(0, 80) : 'Ralph job'; }
+function isJsonObject(value) { return !!value && typeof value === 'object' && !Array.isArray(value); }
+const cleanupStates = new Set(['none', 'active', 'released', 'retained', 'dirty']);
+function normalizeRalphTarget(target) {
+    if (target.kind === 'room')
+        return { kind: 'room', roomId: String(target.roomId ?? '').trim() };
+    return { kind: 'default-chat' };
+}
+function parseRalphTarget(json) { return normalizeRalphTarget(parseJson(json)); }
+function targetJson(target) { return JSON.stringify(normalizeRalphTarget(target)); }
+function optionalString(value, field) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string')
+        throw new Error(`${field} must be a string`);
+    const trimmed = value.trim();
+    return trimmed || undefined;
+}
+function normalizeBrowserLeaseIds(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (!Array.isArray(value))
+        throw new Error('resources.browserLeaseIds must be an array');
+    const ids = [...new Set(value.map((item) => optionalString(item, 'resources.browserLeaseIds[]')).filter((item) => !!item))];
+    return ids.length ? ids : undefined;
+}
+export function normalizeRalphResourceMetadata(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('resources must be an object');
+    const cleanupState = optionalString(value.cleanupState, 'resources.cleanupState');
+    if (cleanupState && !cleanupStates.has(cleanupState))
+        throw new Error('resources.cleanupState must be one of none, active, released, retained, dirty');
+    const resources = {};
+    const workerId = optionalString(value.workerId, 'resources.workerId');
+    const browserLeaseIds = normalizeBrowserLeaseIds(value.browserLeaseIds);
+    const retainedUntil = optionalString(value.retainedUntil, 'resources.retainedUntil');
+    const dirtyReason = optionalString(value.dirtyReason, 'resources.dirtyReason');
+    const updatedAt = optionalString(value.updatedAt, 'resources.updatedAt');
+    if (workerId)
+        resources.workerId = workerId;
+    if (browserLeaseIds)
+        resources.browserLeaseIds = browserLeaseIds;
+    if (cleanupState)
+        resources.cleanupState = cleanupState;
+    if (retainedUntil)
+        resources.retainedUntil = retainedUntil;
+    if (dirtyReason)
+        resources.dirtyReason = dirtyReason;
+    if (updatedAt)
+        resources.updatedAt = updatedAt;
+    return Object.keys(resources).length ? resources : undefined;
+}
+function parseResourceMetadata(json) {
+    if (!json)
+        return undefined;
+    try {
+        return normalizeRalphResourceMetadata(JSON.parse(json));
+    }
+    catch {
+        return undefined;
+    }
+}
+function resourceMetadataJson(resources) {
+    const normalized = normalizeRalphResourceMetadata(resources);
+    return normalized ? JSON.stringify(normalized) : null;
+}
+function jobFromRow(row) {
+    const resources = parseResourceMetadata(row.resource_json);
+    return { id: row.id, name: row.name, description: row.description ?? undefined, enabled: row.enabled === 1, target: parseRalphTarget(row.target_json), profile: row.profile, prompt: row.prompt, maxIterations: row.max_iterations ?? undefined, stopPolicy: parseStopPolicy(row.stop_policy_json), ...parseRuntimeOptions(row.runtime_options_json), ...(resources ? { resources } : {}), state: parseJson(row.state_json), createdAt: row.created_at, updatedAt: row.updated_at };
+}
+function runFromRow(row) {
+    const resources = parseResourceMetadata(row.resource_json);
+    return { id: row.id, jobId: row.job_id, piboSessionId: row.pibo_session_id ?? undefined, status: row.status, reason: row.reason ?? undefined, error: row.error ?? undefined, startedAt: row.started_at ?? undefined, completedAt: row.completed_at ?? undefined, ...(resources ? { resources } : {}), createdAt: row.created_at, updatedAt: row.updated_at };
+}
+function mergeResourceMetadata(jobResources, runResources) {
+    if (!jobResources && !runResources)
+        return undefined;
+    const browserLeaseIds = [...new Set([...(jobResources?.browserLeaseIds ?? []), ...(runResources?.browserLeaseIds ?? [])])];
+    return { ...(jobResources ?? {}), ...(runResources ?? {}), ...(browserLeaseIds.length ? { browserLeaseIds } : {}) };
+}
+function factFromRow(row) {
+    return { id: row.id, jobId: row.job_id, runId: row.run_id ?? undefined, piboSessionId: row.pibo_session_id ?? undefined, type: row.type, source: row.source, payload: parseJson(row.payload_json), createdAt: row.created_at };
+}
+function normalizeMaxIterations(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isInteger(value) || value < 1)
+        throw new Error('maxIterations must be a positive integer');
+    return value;
+}
+function normalizeModelOverride(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const provider = value.provider.trim();
+    const id = value.id.trim();
+    if (!provider || !id)
+        throw new Error('modelOverride must include provider and id');
+    return { provider, id };
+}
+function normalizeThinkingLevel(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (!isPiboThinkingLevel(value))
+        throw new Error('thinkingLevel must be one of off, minimal, low, medium, high, xhigh');
+    return value;
+}
+function normalizeFastMode(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'boolean')
+        throw new Error('fastMode must be a boolean');
+    return value;
+}
+function normalizeRuntimeOptions(input) {
+    return { modelOverride: normalizeModelOverride(input.modelOverride), thinkingLevel: normalizeThinkingLevel(input.thinkingLevel), fastMode: normalizeFastMode(input.fastMode) };
+}
+function parseRuntimeOptions(json) {
+    if (!json)
+        return {};
+    try {
+        const parsed = JSON.parse(json);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return {};
+        return normalizeRuntimeOptions(parsed);
+    }
+    catch {
+        return {};
+    }
+}
+function runtimeOptionsJson(job) {
+    const options = normalizeRuntimeOptions(job);
+    const json = {};
+    if (options.modelOverride)
+        json.modelOverride = options.modelOverride;
+    if (options.thinkingLevel)
+        json.thinkingLevel = options.thinkingLevel;
+    if (options.fastMode !== undefined)
+        json.fastMode = options.fastMode;
+    return Object.keys(json).length ? JSON.stringify(json) : null;
+}
+function hasOwn(object, key) { return Object.prototype.hasOwnProperty.call(object, key); }
+export function normalizeRalphStopPolicy(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('stopPolicy must be an object');
+    if (value.mode !== 'any' && value.mode !== 'all')
+        throw new Error('stopPolicy.mode must be any or all');
+    if (!Array.isArray(value.conditions))
+        throw new Error('stopPolicy.conditions must be an array');
+    const ids = new Set();
+    return { mode: value.mode, conditions: value.conditions.map((condition, index) => {
+            if (!condition || typeof condition !== 'object' || Array.isArray(condition))
+                throw new Error(`stopPolicy.conditions[${index}] must be an object`);
+            const id = typeof condition.id === 'string' && condition.id.trim() ? condition.id.trim() : `condition-${index + 1}`;
+            const type = typeof condition.type === 'string' ? condition.type.trim() : '';
+            if (!type)
+                throw new Error(`stopPolicy.conditions[${index}].type is required`);
+            if (ids.has(id))
+                throw new Error(`Duplicate Ralph stop condition id: ${id}`);
+            ids.add(id);
+            if (condition.options !== undefined && !isJsonObject(condition.options))
+                throw new Error(`stopPolicy.conditions[${index}].options must be an object`);
+            if (condition.enabled !== undefined && typeof condition.enabled !== 'boolean')
+                throw new Error(`stopPolicy.conditions[${index}].enabled must be a boolean`);
+            if (condition.failClosed !== undefined && typeof condition.failClosed !== 'boolean')
+                throw new Error(`stopPolicy.conditions[${index}].failClosed must be a boolean`);
+            if (condition.timeoutMs !== undefined && (!Number.isInteger(condition.timeoutMs) || condition.timeoutMs < 1))
+                throw new Error(`stopPolicy.conditions[${index}].timeoutMs must be a positive integer`);
+            return { id, type, ...(condition.enabled !== undefined ? { enabled: condition.enabled } : {}), ...(condition.options ? { options: condition.options } : {}), ...(condition.failClosed !== undefined ? { failClosed: condition.failClosed } : {}), ...(condition.timeoutMs !== undefined ? { timeoutMs: condition.timeoutMs } : {}) };
+        }) };
+}
+function parseStopPolicy(json) {
+    if (!json)
+        return undefined;
+    try {
+        return normalizeRalphStopPolicy(JSON.parse(json));
+    }
+    catch {
+        return undefined;
+    }
+}
+function stopPolicyJson(policy) { return policy ? JSON.stringify(normalizeRalphStopPolicy(policy)) : null; }
+function validateJobInput(input) {
+    if (!input.profile.trim())
+        throw new Error('profile is required');
+    if (!input.prompt.trim())
+        throw new Error('prompt is required');
+    if (input.target.kind === 'room' && !input.target.roomId.trim())
+        throw new Error('target.roomId is required');
+    normalizeMaxIterations(input.maxIterations);
+    normalizeRuntimeOptions(input);
+    normalizeRalphStopPolicy(input.stopPolicy);
+    normalizeRalphResourceMetadata(input.resources);
+}
+export class PiboRalphStore {
+    db;
+    constructor(options = {}) {
+        const dbPath = options.path ?? piboHomePath('pibo-ralph.sqlite');
+        const resolved = dbPath === ':memory:' ? dbPath : resolve(dbPath);
+        if (resolved !== ':memory:')
+            mkdirSync(dirname(resolved), { recursive: true });
+        this.db = new DatabaseSync(resolved);
+        this.db.exec('PRAGMA busy_timeout = 5000');
+        this.db.exec('PRAGMA foreign_keys = ON');
+        if (resolved !== ':memory:')
+            this.db.exec('PRAGMA journal_mode = WAL');
+        this.applySchema();
+    }
+    close() { this.db.close(); }
+    createJob(input, now = new Date()) {
+        const target = normalizeRalphTarget(input.target);
+        validateJobInput({ ...input, target });
+        const timestamp = nowIso(now);
+        const runtimeOptions = normalizeRuntimeOptions(input);
+        const resources = normalizeRalphResourceMetadata(input.resources);
+        const job = { id: `ralph_${randomUUID()}`, name: (input.name ?? defaultName(input.prompt)).trim(), description: input.description?.trim() || undefined, enabled: input.enabled === true, target, profile: input.profile, prompt: input.prompt, maxIterations: normalizeMaxIterations(input.maxIterations), stopPolicy: normalizeRalphStopPolicy(input.stopPolicy), ...runtimeOptions, ...(resources ? { resources } : {}), state: { completedIterations: 0 }, createdAt: timestamp, updatedAt: timestamp };
+        this.insertJob(job);
+        return this.getJob(job.id);
+    }
+    getJob(id) { const row = this.db.prepare('SELECT * FROM pibo_ralph_jobs WHERE id = ?').get(id); return row ? jobFromRow(row) : undefined; }
+    listJobs(input = {}) {
+        const clauses = [];
+        const values = [];
+        if (!input.includeDisabled)
+            clauses.push('enabled = 1');
+        const where = clauses.length ? `WHERE ${clauses.join(' AND ')}` : '';
+        return this.db.prepare(`SELECT * FROM pibo_ralph_jobs ${where} ORDER BY updated_at DESC, id ASC`).all(...values).map(jobFromRow);
+    }
+    updateJob(id, patch, now = new Date()) {
+        const existing = this.getJob(id);
+        if (!existing)
+            return undefined;
+        const runtimeOptions = normalizeRuntimeOptions({
+            modelOverride: hasOwn(patch, 'modelOverride') ? patch.modelOverride : existing.modelOverride,
+            thinkingLevel: hasOwn(patch, 'thinkingLevel') ? patch.thinkingLevel : existing.thinkingLevel,
+            fastMode: hasOwn(patch, 'fastMode') ? patch.fastMode : existing.fastMode,
+        });
+        const stopPolicy = hasOwn(patch, 'stopPolicy') ? normalizeRalphStopPolicy(patch.stopPolicy ?? undefined) : existing.stopPolicy;
+        const target = patch.target ? normalizeRalphTarget(patch.target) : existing.target;
+        const next = { ...existing, name: patch.name !== undefined ? patch.name.trim() : existing.name, description: patch.description !== undefined ? patch.description?.trim() || undefined : existing.description, enabled: patch.enabled ?? existing.enabled, target, profile: patch.profile ?? existing.profile, prompt: patch.prompt ?? existing.prompt, maxIterations: hasOwn(patch, 'maxIterations') ? normalizeMaxIterations(patch.maxIterations ?? undefined) : existing.maxIterations, stopPolicy, modelOverride: runtimeOptions.modelOverride, thinkingLevel: runtimeOptions.thinkingLevel, fastMode: runtimeOptions.fastMode, updatedAt: nowIso(now) };
+        validateJobInput(next);
+        this.writeJob(next);
+        return this.getJob(id);
+    }
+    updateJobResources(id, resources, now = new Date()) {
+        const existing = this.getJob(id);
+        if (!existing)
+            return undefined;
+        const timestamp = nowIso(now);
+        this.db.prepare('UPDATE pibo_ralph_jobs SET resource_json = ?, updated_at = ? WHERE id = ?').run(resourceMetadataJson(resources), timestamp, id);
+        return this.getJob(id);
+    }
+    updateRunResources(input, now = new Date()) {
+        const clauses = ['id = ?'];
+        const values = [input.runId];
+        if (input.jobId) {
+            clauses.push('job_id = ?');
+            values.push(input.jobId);
+        }
+        const timestamp = nowIso(now);
+        const result = this.db.prepare(`UPDATE pibo_ralph_runs SET resource_json = ?, updated_at = ? WHERE ${clauses.join(' AND ')}`).run(resourceMetadataJson(input.resources), timestamp, ...values);
+        if (Number(result.changes ?? 0) === 0)
+            return undefined;
+        const row = this.db.prepare('SELECT * FROM pibo_ralph_runs WHERE id = ?').get(input.runId);
+        return row ? runFromRow(row) : undefined;
+    }
+    removeJob(id) { const result = this.db.prepare('DELETE FROM pibo_ralph_jobs WHERE id = ?').run(id); return Number(result.changes ?? 0) > 0; }
+    listRuns(input = {}) {
+        const clauses = [];
+        const values = [];
+        if (input.jobId) {
+            clauses.push('job_id = ?');
+            values.push(input.jobId);
+        }
+        const where = clauses.length ? `WHERE ${clauses.join(' AND ')}` : '';
+        return this.db.prepare(`SELECT * FROM pibo_ralph_runs ${where} ORDER BY created_at DESC LIMIT ?`).all(...values, Math.max(1, Math.min(input.limit ?? 100, 500))).map(runFromRow);
+    }
+    reserveRun(id, now = new Date()) { this.updateJob(id, { enabled: true }, now); return this.reserveJob(id, now); }
+    reserveDueRuns(limit, now = new Date()) {
+        const rows = this.db.prepare('SELECT * FROM pibo_ralph_jobs WHERE enabled = 1 ORDER BY updated_at ASC').all();
+        const result = [];
+        for (const row of rows) {
+            if (result.length >= limit)
+                break;
+            const reserved = this.reserveJob(row.id, now);
+            if (reserved)
+                result.push(reserved);
+        }
+        return result;
+    }
+    attachRunSession(jobId, runId, piboSessionId, now = new Date()) {
+        const timestamp = nowIso(now);
+        const job = this.getJob(jobId);
+        if (!job)
+            return;
+        this.db.prepare('UPDATE pibo_ralph_runs SET pibo_session_id = ?, updated_at = ? WHERE id = ?').run(piboSessionId, timestamp, runId);
+        this.updateJobStateLocked(jobId, { ...job.state, lastPiboSessionId: piboSessionId }, timestamp);
+    }
+    requestStop(id, now = new Date()) {
+        const job = this.getJob(id);
+        if (!job)
+            return undefined;
+        const state = { ...job.state, stopRequestedAt: nowIso(now) };
+        this.writeJob({ ...job, enabled: false, state, updatedAt: nowIso(now) });
+        return this.getJob(id);
+    }
+    requestCancel(id, now = new Date()) {
+        const job = this.getJob(id);
+        if (!job)
+            return undefined;
+        const state = { ...job.state, stopRequestedAt: nowIso(now), cancelRequestedAt: nowIso(now) };
+        this.writeJob({ ...job, enabled: false, state, updatedAt: nowIso(now) });
+        return this.getJob(id);
+    }
+    applyStopEvaluation(input, now = new Date()) {
+        const job = this.getJob(input.jobId);
+        if (!job)
+            return;
+        const timestamp = nowIso(now);
+        const state = { ...job.state, runningAt: undefined, conditionStates: input.conditionStates ?? job.state.conditionStates, lastStopEvaluation: input.evaluation };
+        this.db.prepare('UPDATE pibo_ralph_jobs SET enabled = ?, state_json = ?, updated_at = ? WHERE id = ?').run(input.disable ? 0 : job.enabled ? 1 : 0, JSON.stringify(state), timestamp, job.id);
+    }
+    completeRun(input, now = new Date()) {
+        const timestamp = nowIso(now);
+        const job = this.getJob(input.jobId);
+        if (!job)
+            return;
+        const completedIterations = (job.state.completedIterations ?? 0) + 1;
+        const reachedMaxIterations = job.maxIterations !== undefined && completedIterations >= job.maxIterations;
+        const shouldDisable = reachedMaxIterations || input.stopAfterRun === true || input.stopEvaluation?.finalAction === 'stop-after-run' || input.stopEvaluation?.finalAction === 'cancel-current-run';
+        const state = { ...job.state, runningAt: undefined, completedIterations, lastRunAt: timestamp, lastRunId: input.runId, lastStatus: input.status === 'error' ? 'error' : input.status === 'cancelled' ? 'cancelled' : 'ok', lastError: input.error, lastPiboSessionId: input.piboSessionId ?? job.state.lastPiboSessionId, consecutiveErrors: input.status === 'error' ? (job.state.consecutiveErrors ?? 0) + 1 : 0, conditionStates: input.conditionStates ?? job.state.conditionStates, lastStopEvaluation: input.stopEvaluation ?? job.state.lastStopEvaluation };
+        this.db.prepare('UPDATE pibo_ralph_runs SET status = ?, pibo_session_id = ?, reason = ?, error = ?, completed_at = ?, updated_at = ? WHERE id = ?').run(input.status, input.piboSessionId ?? null, input.reason ?? input.stopEvaluation?.reason ?? null, input.error ?? null, timestamp, timestamp, input.runId);
+        this.db.prepare('UPDATE pibo_ralph_jobs SET enabled = ?, state_json = ?, updated_at = ? WHERE id = ?').run(shouldDisable ? 0 : job.enabled ? 1 : 0, JSON.stringify(state), timestamp, job.id);
+    }
+    appendRunFact(input) {
+        if (!input.jobId.trim())
+            throw new Error('fact jobId is required');
+        if (!input.type.trim())
+            throw new Error('fact type is required');
+        if (!isJsonObject(input.payload))
+            throw new Error('fact payload must be an object');
+        const payloadJson = JSON.stringify(input.payload);
+        if (payloadJson.length > 16_384)
+            throw new Error('fact payload is too large');
+        const fact = { id: input.id ?? `rfact_${randomUUID()}`, jobId: input.jobId, runId: input.runId, piboSessionId: input.piboSessionId, type: input.type.trim(), source: input.source, payload: input.payload, createdAt: input.createdAt ?? nowIso() };
+        this.db.prepare('INSERT INTO pibo_ralph_run_facts (id, job_id, run_id, pibo_session_id, type, source, payload_json, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)').run(fact.id, fact.jobId, fact.runId ?? null, fact.piboSessionId ?? null, fact.type, fact.source, payloadJson, fact.createdAt);
+        return fact;
+    }
+    listRunFacts(input = {}) {
+        const clauses = [];
+        const values = [];
+        if (input.jobId) {
+            clauses.push('job_id = ?');
+            values.push(input.jobId);
+        }
+        if (input.runId) {
+            clauses.push('run_id = ?');
+            values.push(input.runId);
+        }
+        if (input.type) {
+            clauses.push('type = ?');
+            values.push(input.type);
+        }
+        const where = clauses.length ? `WHERE ${clauses.join(' AND ')}` : '';
+        return this.db.prepare(`SELECT * FROM pibo_ralph_run_facts ${where} ORDER BY created_at DESC LIMIT ?`).all(...values, Math.max(1, Math.min(input.limit ?? 100, 500))).map(factFromRow);
+    }
+    createFactReader(job) {
+        return { list: (input = {}) => this.listRunFacts({ jobId: job.id, type: input.type, runId: input.runId, limit: input.limit }), count: (input = {}) => this.listRunFacts({ jobId: job.id, type: input.type, runId: input.runId, limit: 500 }).length };
+    }
+    recoverInterruptedRuns(cutoff = new Date(Date.now() - 5 * 60_000)) { const cutoffIso = nowIso(cutoff); const rows = this.db.prepare("SELECT * FROM pibo_ralph_jobs WHERE json_extract(state_json, '$.runningAt') IS NOT NULL").all(); let recovered = 0; for (const row of rows) {
+        const job = jobFromRow(row);
+        if (!job.state.runningAt || job.state.runningAt > cutoffIso)
+            continue;
+        if (job.state.lastRunId) {
+            this.completeRun({ jobId: job.id, runId: job.state.lastRunId, status: 'error', error: 'Ralph run was interrupted by gateway restart', reason: 'interrupted' });
+            this.markInterruptedRunResourcesDirty(job, job.state.lastRunId);
+        }
+        recovered += 1;
+    } return recovered; }
+    status() { const jobs = this.listJobs({ includeDisabled: false }); return { jobs: jobs.length, running: jobs.filter((job) => job.state.runningAt).length }; }
+    markInterruptedRunResourcesDirty(job, runId) {
+        const runRow = this.db.prepare('SELECT * FROM pibo_ralph_runs WHERE id = ? AND job_id = ?').get(runId, job.id);
+        const resources = mergeResourceMetadata(job.resources, runRow ? runFromRow(runRow).resources : undefined);
+        if (!resources || (!resources.workerId && (resources.browserLeaseIds ?? []).length === 0))
+            return;
+        const nextResources = { ...resources, cleanupState: 'dirty', dirtyReason: 'Ralph run was interrupted before browser resource cleanup could be confirmed', updatedAt: nowIso() };
+        this.updateRunResources({ jobId: job.id, runId, resources: nextResources });
+        this.updateJobResources(job.id, nextResources);
+    }
+    reserveJob(id, now = new Date()) {
+        const timestamp = nowIso(now);
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const job = this.getJob(id);
+            if (!job || !job.enabled || job.state.runningAt) {
+                this.db.exec('COMMIT');
+                return undefined;
+            }
+            const run = this.createRunLocked(job, timestamp);
+            const state = { ...job.state, runningAt: timestamp, lastRunAt: timestamp, lastRunId: run.id };
+            this.updateJobStateLocked(job.id, state, timestamp);
+            this.db.exec('COMMIT');
+            return { job: { ...job, state, updatedAt: timestamp }, run };
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    applySchema() {
+        this.createFreshSchema();
+        this.ensureJobColumn('max_iterations', 'INTEGER');
+        this.ensureJobColumn('runtime_options_json', 'TEXT');
+        this.ensureJobColumn('stop_policy_json', 'TEXT');
+        this.ensureJobColumn('resource_json', 'TEXT');
+        this.ensureRunColumn('resource_json', 'TEXT');
+    }
+    createFreshSchema() {
+        this.db.exec(`CREATE TABLE IF NOT EXISTS pibo_ralph_jobs (id TEXT PRIMARY KEY, name TEXT NOT NULL, description TEXT, enabled INTEGER NOT NULL, target_json TEXT NOT NULL, profile TEXT NOT NULL, prompt TEXT NOT NULL, max_iterations INTEGER, runtime_options_json TEXT, stop_policy_json TEXT, resource_json TEXT, state_json TEXT NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL); CREATE INDEX IF NOT EXISTS idx_pibo_ralph_jobs_enabled ON pibo_ralph_jobs(enabled, updated_at DESC); CREATE TABLE IF NOT EXISTS pibo_ralph_runs (id TEXT PRIMARY KEY, job_id TEXT NOT NULL, pibo_session_id TEXT, status TEXT NOT NULL, reason TEXT, error TEXT, resource_json TEXT, started_at TEXT, completed_at TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL); CREATE INDEX IF NOT EXISTS idx_pibo_ralph_runs_job_created ON pibo_ralph_runs(job_id, created_at DESC); CREATE TABLE IF NOT EXISTS pibo_ralph_run_facts (id TEXT PRIMARY KEY, job_id TEXT NOT NULL, run_id TEXT, pibo_session_id TEXT, type TEXT NOT NULL, source TEXT NOT NULL, payload_json TEXT NOT NULL, created_at TEXT NOT NULL); CREATE INDEX IF NOT EXISTS idx_pibo_ralph_facts_job_created ON pibo_ralph_run_facts(job_id, created_at DESC); CREATE INDEX IF NOT EXISTS idx_pibo_ralph_facts_run_type ON pibo_ralph_run_facts(run_id, type, created_at DESC);`);
+    }
+    ensureJobColumn(name, definition) {
+        const columns = this.tableColumns('pibo_ralph_jobs');
+        if (!columns.has(name))
+            this.db.exec(`ALTER TABLE pibo_ralph_jobs ADD COLUMN ${name} ${definition}`);
+    }
+    ensureRunColumn(name, definition) {
+        const columns = this.tableColumns('pibo_ralph_runs');
+        if (!columns.has(name))
+            this.db.exec(`ALTER TABLE pibo_ralph_runs ADD COLUMN ${name} ${definition}`);
+    }
+    tableColumns(tableName) {
+        return new Set(this.db.prepare(`PRAGMA table_info(${tableName})`).all().map((column) => column.name));
+    }
+    insertJob(job) { this.db.prepare('INSERT INTO pibo_ralph_jobs (id, name, description, enabled, target_json, profile, prompt, max_iterations, runtime_options_json, stop_policy_json, resource_json, state_json, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)').run(job.id, job.name, job.description ?? null, job.enabled ? 1 : 0, targetJson(job.target), job.profile, job.prompt, job.maxIterations ?? null, runtimeOptionsJson(job), stopPolicyJson(job.stopPolicy), resourceMetadataJson(job.resources), JSON.stringify(job.state), job.createdAt, job.updatedAt); }
+    writeJob(job) { this.db.prepare('UPDATE pibo_ralph_jobs SET name = ?, description = ?, enabled = ?, target_json = ?, profile = ?, prompt = ?, max_iterations = ?, runtime_options_json = ?, stop_policy_json = ?, resource_json = ?, state_json = ?, updated_at = ? WHERE id = ?').run(job.name, job.description ?? null, job.enabled ? 1 : 0, targetJson(job.target), job.profile, job.prompt, job.maxIterations ?? null, runtimeOptionsJson(job), stopPolicyJson(job.stopPolicy), resourceMetadataJson(job.resources), JSON.stringify(job.state), job.updatedAt, job.id); }
+    updateJobStateLocked(id, state, updatedAt) { this.db.prepare('UPDATE pibo_ralph_jobs SET state_json = ?, updated_at = ? WHERE id = ?').run(JSON.stringify(state), updatedAt, id); }
+    createRunLocked(job, timestamp) { const run = { id: `rrun_${randomUUID()}`, jobId: job.id, status: 'running', startedAt: timestamp, ...(job.resources ? { resources: job.resources } : {}), createdAt: timestamp, updatedAt: timestamp }; this.db.prepare('INSERT INTO pibo_ralph_runs (id, job_id, pibo_session_id, status, reason, error, resource_json, started_at, completed_at, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)').run(run.id, run.jobId, null, run.status, null, null, resourceMetadataJson(run.resources), run.startedAt ?? null, null, run.createdAt, run.updatedAt); return run; }
+}
+export function createDefaultPiboRalphStore(options = {}) { return new PiboRalphStore(options); }

package/dist/ralph/templates.js

@@ -0,0 +1,200 @@
+const promiseCompletePolicy = {
+    mode: 'any',
+    conditions: [{ id: 'promise-complete', type: 'pibo.ralph.promise-complete' }],
+};
+const singleRunPolicy = {
+    mode: 'any',
+    conditions: [{ id: 'max-iterations', type: 'pibo.ralph.max-iterations' }],
+};
+function markdown(strings) {
+    return String.raw(strings).replaceAll('\\`', '`');
+}
+export const BUILT_IN_RALPH_JOB_TEMPLATES = [
+    {
+        id: 'prd-single-story-standard',
+        name: 'PRD single story standard',
+        description: 'Default Ralph loop: pick the highest-priority failing PRD user story, implement exactly one story, test, commit, update progress, then stop or continue on the next run.',
+        category: 'prd',
+        job: {
+            name: 'Ralph PRD single story',
+            description: 'One PRD user story per Ralph iteration.',
+            prompt: markdown `# Ralph Auftrag: <Project / Change Name>
+
+## Worktree
+
+Work from the host worktree, not from a container copy:
+
+\`\`\`bash
+cd <host-worktree>
+\`\`\`
+
+Branch: \`<branch-name>\`  
+Base: \`<base-branch-or-commit>\`  
+PRDs: \`<path-to-prds>/prd_*.json\`  
+Progress log: \`<path-to-prds>/progress.txt\`
+
+If a container is required for build, gateway, or browser checks, use it only for running commands. Edit files and run git commands in the host worktree. Do not edit \`/app\` inside a container.
+
+## Ralph Agent Instructions
+
+You are an autonomous coding agent working on a software project.
+
+### Your Task
+
+1. Work from the host worktree above.
+2. Read all PRD JSON files matching \`<path-to-prds>/prd_*.json\`.
+3. Read the progress log. If it does not exist, create it.
+4. Read the \`## Codebase Patterns\` section at the top of the progress log if present.
+5. Pick the highest-priority user story where \`passes: false\`.
+6. Implement that single user story only.
+7. Run quality checks:
+   - Always run \`npm run typecheck\`.
+   - Run relevant tests for touched areas.
+   - For UI stories, run browser verification in the configured dev container/browser environment.
+8. If checks pass, update the PRD JSON to set \`passes: true\` for the completed story.
+9. Commit all changes from the host worktree with message:
+   \`feat: [Story ID] - [Story Title]\`
+10. Append your progress to the progress log.
+
+### Progress Report Format
+
+Append to the progress log. Never replace; always append.
+
+\`\`\`md
+## [Date/Time] - [Story ID]
+- What was implemented
+- Files changed
+- Quality checks run
+- Browser verification, if UI changed
+- **Learnings for future iterations:**
+  - Patterns discovered
+  - Gotchas encountered
+  - Useful context
+---
+\`\`\`
+
+### Consolidate Patterns
+
+If you discover a reusable pattern, add it to the \`## Codebase Patterns\` section at the top of the progress log. Only add general reusable patterns, not story-specific notes.
+
+## Quality Requirements
+
+- All commits must pass quality checks.
+- Do not commit broken code.
+- Keep changes focused and minimal.
+- Follow existing code patterns.
+- For UI stories, browser verification is mandatory.
+
+## Stop Condition
+
+After completing one user story, check whether all stories in all PRD JSON files have \`passes: true\`.
+
+If all stories are complete and passing, reply with the XML completion marker on its own line. Compose it from the opening tag \`<promise>\`, the word \`COMPLETE\`, and the closing tag \`</promise>\`.
+
+Do not quote, negate, explain, or mention that literal marker unless all stories are complete and you intend to stop the job. If any story remains with \`passes: false\`, end normally so another iteration can pick up the next story and say only that the completion marker was omitted.`,
+            stopPolicy: promiseCompletePolicy,
+        },
+    },
+    {
+        id: 'prd-batch-stories',
+        name: 'PRD batch stories',
+        description: 'Batch loop: implement several failing PRD user stories in priority order in one Ralph run, committing after each completed story.',
+        category: 'prd',
+        job: {
+            name: 'Ralph PRD batch',
+            description: 'Multiple PRD user stories per Ralph run.',
+            prompt: markdown `# Ralph Auftrag: <Project / Change Name> Batch
+
+## Worktree
+
+Work from the host worktree:
+
+\`\`\`bash
+cd <host-worktree>
+\`\`\`
+
+PRDs: \`<path-to-prds>/prd_*.json\`  
+Progress log: \`<path-to-prds>/progress.txt\`  
+Batch limit: \`<max-stories-this-run>\`
+
+## Task
+
+1. Read the PRD JSON files and progress log.
+2. Work through failing user stories in priority order.
+3. Complete up to \`<max-stories-this-run>\` stories in this run.
+4. Keep each story isolated:
+   - implement one story;
+   - run relevant checks;
+   - set that story's \`passes\` to \`true\` only after checks pass;
+   - commit with \`feat: [Story ID] - [Story Title]\`;
+   - append a progress-log entry.
+5. Stop early if a story is blocked, ambiguous, or tests fail. Do not continue with later stories after a failed story.
+
+## Quality Requirements
+
+- Always run \`npm run typecheck\` before each story commit unless the repository has a documented narrower check for this batch.
+- Run relevant tests for touched areas.
+- Browser verification is mandatory for UI changes.
+- Keep changes focused; do not bundle unrelated refactors.
+
+## Stop Condition
+
+If all stories in all PRD JSON files are complete and passing, reply with the XML completion marker on its own line. Compose it from the opening tag \`<promise>\`, the word \`COMPLETE\`, and the closing tag \`</promise>\`.
+
+Do not quote, negate, explain, or mention that literal marker unless all stories are complete and you intend to stop the job. Otherwise report the stories completed and the next remaining failing story, and say only that the completion marker was omitted.`,
+            stopPolicy: promiseCompletePolicy,
+        },
+    },
+    {
+        id: 'single-run-objective',
+        name: 'Single-run objective',
+        description: 'Non-PRD template for one focused objective with explicit done criteria. Stops after one completed run attempt by max-iterations.',
+        category: 'general',
+        job: {
+            name: 'Ralph single-run objective',
+            description: 'One focused non-PRD objective.',
+            maxIterations: 1,
+            stopPolicy: singleRunPolicy,
+            prompt: markdown `# Ralph Auftrag: <Objective>
+
+## Worktree
+
+\`\`\`bash
+cd <host-worktree>
+\`\`\`
+
+Branch: \`<branch-name>\`
+
+## Objective
+
+<Describe the concrete outcome.>
+
+## Done Criteria
+
+- <Pass/fail criterion 1>
+- <Pass/fail criterion 2>
+- <Required verification command or manual check>
+
+## Instructions
+
+1. Inspect the relevant code and docs before editing.
+2. State assumptions in code comments or docs only when they matter for maintainers.
+3. Implement the smallest focused change that satisfies the done criteria.
+4. Run \`npm run typecheck\` and relevant tests.
+5. Commit with a concise message if checks pass.
+6. End with a short report listing files changed and verification run.
+
+This is not a PRD loop. Do not edit PRD JSON progress unless the objective explicitly asks for it.`,
+        },
+    },
+];
+export function listRalphJobTemplates() {
+    return BUILT_IN_RALPH_JOB_TEMPLATES.map((template) => cloneTemplate(template));
+}
+export function getRalphJobTemplate(id) {
+    const template = BUILT_IN_RALPH_JOB_TEMPLATES.find((item) => item.id === id);
+    return template ? cloneTemplate(template) : undefined;
+}
+function cloneTemplate(template) {
+    return JSON.parse(JSON.stringify(template));
+}

package/dist/ralph/types.js

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