@pasko70/pibo 1.10.0 → 1.11.0

package/dist/loops/store.js

@@ -75,13 +75,37 @@ function resourceMetadataJson(resources) {
     const normalized = normalizeLoopResourceMetadata(resources);
     return normalized ? JSON.stringify(normalized) : null;
 }
+function parseRunAccounting(json) {
+    if (!json)
+        return undefined;
+    try {
+        const value = JSON.parse(json);
+        return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function runAccountingJson(accounting) { return accounting ? JSON.stringify(accounting) : null; }
+function normalizeJobState(state, mode, enabled, createdAt) {
+    if (mode !== 'goal')
+        return state;
+    const activeTimeSeconds = Math.max(0, Math.floor(state.activeTimeSeconds ?? state.timeUsedSeconds ?? 0));
+    const goalStartedAt = state.goalStartedAt ?? (enabled || (state.completedIterations ?? 0) > 0 || (state.tokensUsed ?? 0) > 0 || (state.goalStatus !== undefined && state.goalStatus !== 'paused') ? createdAt : undefined);
+    const normalized = { ...state, activeTimeSeconds, ...(goalStartedAt ? { goalStartedAt } : {}) };
+    delete normalized.timeUsedSeconds;
+    return normalized;
+}
 function jobFromRow(row) {
     const resources = parseResourceMetadata(row.resource_json);
-    return { id: row.id, mode: normalizeLoopMode(row.loop_mode, 'ralph'), name: row.name, description: row.description ?? undefined, enabled: row.enabled === 1, target: parseLoopTarget(row.target_json), profile: row.profile, prompt: row.prompt, maxIterations: row.max_iterations ?? undefined, tokenBudget: row.token_budget ?? 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 };
+    const mode = normalizeLoopMode(row.loop_mode, 'ralph');
+    const enabled = row.enabled === 1;
+    return { id: row.id, mode, name: row.name, description: row.description ?? undefined, enabled, target: parseLoopTarget(row.target_json), profile: row.profile, prompt: row.prompt, maxIterations: row.max_iterations ?? undefined, tokenBudget: row.token_budget ?? undefined, tokenReserve: row.token_reserve ?? undefined, stopPolicy: parseStopPolicy(row.stop_policy_json), ...parseRuntimeOptions(row.runtime_options_json), ...(resources ? { resources } : {}), state: normalizeJobState(parseJson(row.state_json), mode, enabled, row.created_at), 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 };
+    const accounting = parseRunAccounting(row.accounting_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, ...(accounting ? { accounting } : {}), ...(resources ? { resources } : {}), createdAt: row.created_at, updatedAt: row.updated_at };
 }
 function mergeResourceMetadata(jobResources, runResources) {
     if (!jobResources && !runResources)
@@ -106,6 +130,13 @@ function normalizeTokenBudget(value) {
         throw new Error('tokenBudget must be a positive integer');
     return value;
 }
+function normalizeTokenReserve(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isInteger(value) || value < 0)
+        throw new Error('tokenReserve must be a non-negative integer');
+    return value;
+}
 function goalStatus(job) {
     if (job.mode !== 'goal')
         return undefined;
@@ -213,10 +244,15 @@ function validateJobInput(input) {
         throw new Error('prompt is required');
     if (input.target.kind === 'room' && !input.target.roomId.trim())
         throw new Error('target.roomId is required');
-    if (input.mode === 'ralph' && input.tokenBudget !== undefined)
-        throw new Error('tokenBudget is only available for goal mode');
+    if (input.mode === 'ralph' && (input.tokenBudget !== undefined || input.tokenReserve !== undefined))
+        throw new Error('tokenBudget and tokenReserve are only available for goal mode');
     normalizeMaxIterations(input.maxIterations);
     normalizeTokenBudget(input.tokenBudget);
+    normalizeTokenReserve(input.tokenReserve);
+    if (input.tokenReserve !== undefined && input.tokenBudget === undefined)
+        throw new Error('tokenReserve requires tokenBudget');
+    if (input.tokenReserve !== undefined && input.tokenBudget !== undefined && input.tokenReserve >= input.tokenBudget)
+        throw new Error('tokenReserve must be smaller than tokenBudget');
     normalizeRuntimeOptions(input);
     normalizeLoopStopPolicy(input.stopPolicy);
     normalizeLoopResourceMetadata(input.resources);
@@ -246,10 +282,10 @@ export class PiboLoopStore {
         const enabled = input.enabled === true;
         const state = {
             completedIterations: 0,
-            ...(mode === 'goal' ? { goalStatus: enabled ? 'active' : 'paused', tokensUsed: 0, timeUsedSeconds: 0 } : {}),
+            ...(mode === 'goal' ? { goalStatus: enabled ? 'active' : 'paused', tokensUsed: 0, activeTimeSeconds: 0, ...(enabled ? { goalStartedAt: timestamp } : {}) } : {}),
             ...(input.initialPiboSessionId?.trim() ? { lastPiboSessionId: input.initialPiboSessionId.trim() } : {}),
         };
-        const job = { id: mode === 'ralph' ? `ralph_${randomUUID()}` : `loop_${randomUUID()}`, mode, name: (input.name ?? defaultName(input.prompt)).trim(), description: input.description?.trim() || undefined, enabled, target, profile: input.profile, prompt: input.prompt, maxIterations: normalizeMaxIterations(input.maxIterations), tokenBudget: normalizeTokenBudget(input.tokenBudget), stopPolicy: normalizeLoopStopPolicy(input.stopPolicy), ...runtimeOptions, ...(resources ? { resources } : {}), state, createdAt: timestamp, updatedAt: timestamp };
+        const job = { id: mode === 'ralph' ? `ralph_${randomUUID()}` : `loop_${randomUUID()}`, mode, name: (input.name ?? defaultName(input.prompt)).trim(), description: input.description?.trim() || undefined, enabled, target, profile: input.profile, prompt: input.prompt, maxIterations: normalizeMaxIterations(input.maxIterations), tokenBudget: normalizeTokenBudget(input.tokenBudget), tokenReserve: normalizeTokenReserve(input.tokenReserve), stopPolicy: normalizeLoopStopPolicy(input.stopPolicy), ...runtimeOptions, ...(resources ? { resources } : {}), state, createdAt: timestamp, updatedAt: timestamp };
         this.insertJob(job);
         return this.getJob(job.id);
     }
@@ -264,6 +300,10 @@ export class PiboLoopStore {
             return undefined;
         const timestamp = nowIso(now);
         const state = { ...job.state, goalStatus: status, runningAt: job.state.runningAt };
+        if (job.state.runningAt)
+            delete state.goalEndedAt;
+        else
+            state.goalEndedAt = timestamp;
         this.db.prepare('UPDATE pibo_ralph_jobs SET enabled = 0, state_json = ?, updated_at = ? WHERE id = ?').run(JSON.stringify(state), timestamp, id);
         return this.getJob(id);
     }
@@ -272,20 +312,65 @@ export class PiboLoopStore {
         if (!job || job.mode !== 'goal')
             return job;
         const tokens = Math.max(0, Math.floor(input.tokens ?? 0));
-        const timeUsedSeconds = Math.max(0, Math.floor(input.timeUsedSeconds ?? 0));
+        const activeTimeSeconds = Math.max(0, Math.floor(input.activeTimeSeconds ?? 0));
         const nextTokens = (job.state.tokensUsed ?? 0) + tokens;
         const currentStatus = goalStatus(job) ?? 'active';
         const budgetLimited = currentStatus === 'active' && job.tokenBudget !== undefined && nextTokens >= job.tokenBudget;
         const state = {
             ...job.state,
             tokensUsed: nextTokens,
-            timeUsedSeconds: (job.state.timeUsedSeconds ?? 0) + timeUsedSeconds,
+            activeTimeSeconds: (job.state.activeTimeSeconds ?? 0) + activeTimeSeconds,
             goalStatus: budgetLimited ? 'budget_limited' : currentStatus,
         };
         const timestamp = nowIso(now);
+        if (budgetLimited && !job.state.runningAt)
+            state.goalEndedAt = timestamp;
         this.db.prepare('UPDATE pibo_ralph_jobs SET enabled = ?, state_json = ?, updated_at = ? WHERE id = ?').run(budgetLimited ? 0 : job.enabled ? 1 : 0, JSON.stringify(state), timestamp, id);
         return this.getJob(id);
     }
+    recordGoalTurnUsage(id, runId, tokens, now = new Date()) {
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const job = this.recordGoalProgress(id, { tokens }, now);
+            if (job?.mode === 'goal') {
+                const row = this.db.prepare('SELECT * FROM pibo_ralph_runs WHERE id = ? AND job_id = ?').get(runId, id);
+                if (row) {
+                    const accounting = parseRunAccounting(row.accounting_json) ?? {};
+                    const turnTokens = (accounting.tokensUsed ?? 0) + Math.max(0, Math.floor(tokens));
+                    const budget = accounting.tokenBudget;
+                    const before = accounting.tokensUsedBefore ?? 0;
+                    const nextAccounting = { ...accounting, tokensUsed: turnTokens, ...(budget !== undefined ? { overshootTokens: Math.max(0, before + turnTokens - budget) } : {}) };
+                    this.db.prepare('UPDATE pibo_ralph_runs SET accounting_json = ?, updated_at = ? WHERE id = ?').run(runAccountingJson(nextAccounting), nowIso(now), runId);
+                }
+            }
+            this.db.exec('COMMIT');
+            return job;
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    recordGoalRunTime(id, runId, activeTimeSeconds, now = new Date()) {
+        const seconds = Math.max(0, Math.floor(activeTimeSeconds));
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const job = this.recordGoalProgress(id, { activeTimeSeconds: seconds }, now);
+            if (job?.mode === 'goal') {
+                const row = this.db.prepare('SELECT * FROM pibo_ralph_runs WHERE id = ? AND job_id = ?').get(runId, id);
+                if (row) {
+                    const accounting = { ...(parseRunAccounting(row.accounting_json) ?? {}), activeTimeSeconds: seconds };
+                    this.db.prepare('UPDATE pibo_ralph_runs SET accounting_json = ?, updated_at = ? WHERE id = ?').run(runAccountingJson(accounting), nowIso(now), runId);
+                }
+            }
+            this.db.exec('COMMIT');
+            return job;
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+    }
     listJobs(input = {}) {
         const clauses = [];
         const values = [];
@@ -309,16 +394,19 @@ export class PiboLoopStore {
         const enabled = patch.enabled ?? existing.enabled;
         let state = mode === existing.mode
             ? { ...existing.state }
-            : { completedIterations: existing.state.completedIterations ?? 0, ...(mode === 'goal' ? { goalStatus: enabled ? 'active' : 'paused', tokensUsed: 0, timeUsedSeconds: 0 } : {}) };
+            : { completedIterations: existing.state.completedIterations ?? 0, ...(mode === 'goal' ? { goalStatus: enabled ? 'active' : 'paused', tokensUsed: 0, activeTimeSeconds: 0, ...(enabled ? { goalStartedAt: nowIso(now) } : {}) } : {}) };
         if (mode === 'goal' && patch.enabled !== undefined) {
             const currentGoalStatus = goalStatus({ mode, enabled: existing.enabled, state: existing.state }) ?? 'paused';
             if (patch.enabled) {
                 if (currentGoalStatus === 'complete')
                     throw new Error('Completed goals cannot be restarted; create a new goal');
                 const nextBudget = hasOwn(patch, 'tokenBudget') ? normalizeTokenBudget(patch.tokenBudget ?? undefined) : existing.tokenBudget;
-                if (currentGoalStatus === 'budget_limited' && nextBudget !== undefined && (existing.state.tokensUsed ?? 0) >= nextBudget)
-                    throw new Error('Increase or clear the token budget before resuming this goal');
+                const nextReserve = hasOwn(patch, 'tokenReserve') ? normalizeTokenReserve(patch.tokenReserve ?? undefined) : existing.tokenReserve;
+                if (currentGoalStatus === 'budget_limited' && nextBudget !== undefined && (existing.state.tokensUsed ?? 0) + (nextReserve ?? 0) >= nextBudget)
+                    throw new Error('Increase or clear the token budget, or lower the token reserve, before resuming this goal');
                 state.goalStatus = 'active';
+                state.goalStartedAt ??= nowIso(now);
+                delete state.goalEndedAt;
                 state.stopRequestedAt = undefined;
                 state.cancelRequestedAt = undefined;
             }
@@ -326,7 +414,7 @@ export class PiboLoopStore {
                 state.goalStatus = currentGoalStatus === 'active' ? 'paused' : currentGoalStatus;
             }
         }
-        const next = { ...existing, mode, state, name: patch.name !== undefined ? patch.name.trim() : existing.name, description: patch.description !== undefined ? patch.description?.trim() || undefined : existing.description, enabled, target, profile: patch.profile ?? existing.profile, prompt: patch.prompt ?? existing.prompt, maxIterations: hasOwn(patch, 'maxIterations') ? normalizeMaxIterations(patch.maxIterations ?? undefined) : existing.maxIterations, tokenBudget: mode === 'ralph' ? undefined : hasOwn(patch, 'tokenBudget') ? normalizeTokenBudget(patch.tokenBudget ?? undefined) : existing.tokenBudget, stopPolicy, modelOverride: runtimeOptions.modelOverride, thinkingLevel: runtimeOptions.thinkingLevel, fastMode: runtimeOptions.fastMode, updatedAt: nowIso(now) };
+        const next = { ...existing, mode, state, name: patch.name !== undefined ? patch.name.trim() : existing.name, description: patch.description !== undefined ? patch.description?.trim() || undefined : existing.description, enabled, target, profile: patch.profile ?? existing.profile, prompt: patch.prompt ?? existing.prompt, maxIterations: hasOwn(patch, 'maxIterations') ? normalizeMaxIterations(patch.maxIterations ?? undefined) : existing.maxIterations, tokenBudget: mode === 'ralph' ? undefined : hasOwn(patch, 'tokenBudget') ? normalizeTokenBudget(patch.tokenBudget ?? undefined) : existing.tokenBudget, tokenReserve: mode === 'ralph' || (hasOwn(patch, 'tokenBudget') && patch.tokenBudget === null && !hasOwn(patch, 'tokenReserve')) ? undefined : hasOwn(patch, 'tokenReserve') ? normalizeTokenReserve(patch.tokenReserve ?? undefined) : existing.tokenReserve, stopPolicy, modelOverride: runtimeOptions.modelOverride, thinkingLevel: runtimeOptions.thinkingLevel, fastMode: runtimeOptions.fastMode, updatedAt: nowIso(now) };
         validateJobInput(next);
         this.writeJob(next);
         return this.getJob(id);
@@ -418,7 +506,7 @@ export class PiboLoopStore {
         const reachedMaxIterations = job.maxIterations !== undefined && completedIterations >= job.maxIterations;
         const terminalGoalStatus = job.mode === 'goal' && ['complete', 'blocked', 'budget_limited'].includes(goalStatus(job) ?? '');
         const shouldDisable = terminalGoalStatus || 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 };
+        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, ...(terminalGoalStatus ? { goalEndedAt: job.state.goalEndedAt ?? timestamp } : {}) };
         this.db.prepare('UPDATE pibo_ralph_runs SET status = ?, pibo_session_id = COALESCE(?, 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);
     }
@@ -486,6 +574,15 @@ export class PiboLoopStore {
                 this.db.exec('COMMIT');
                 return undefined;
             }
+            if (job.mode === 'goal' && job.tokenBudget !== undefined) {
+                const remaining = Math.max(0, job.tokenBudget - (job.state.tokensUsed ?? 0));
+                if (remaining <= (job.tokenReserve ?? 0)) {
+                    const state = { ...job.state, goalStatus: 'budget_limited', goalEndedAt: timestamp };
+                    this.db.prepare('UPDATE pibo_ralph_jobs SET enabled = 0, state_json = ?, updated_at = ? WHERE id = ?').run(JSON.stringify(state), timestamp, job.id);
+                    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);
@@ -502,13 +599,15 @@ export class PiboLoopStore {
         this.ensureJobColumn('loop_mode', "TEXT NOT NULL DEFAULT 'ralph'");
         this.ensureJobColumn('max_iterations', 'INTEGER');
         this.ensureJobColumn('token_budget', 'INTEGER');
+        this.ensureJobColumn('token_reserve', 'INTEGER');
         this.ensureJobColumn('runtime_options_json', 'TEXT');
         this.ensureJobColumn('stop_policy_json', 'TEXT');
         this.ensureJobColumn('resource_json', 'TEXT');
         this.ensureRunColumn('resource_json', 'TEXT');
+        this.ensureRunColumn('accounting_json', 'TEXT');
     }
     createFreshSchema() {
-        this.db.exec(`CREATE TABLE IF NOT EXISTS pibo_ralph_jobs (id TEXT PRIMARY KEY, loop_mode TEXT NOT NULL DEFAULT 'goal', 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, token_budget 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);`);
+        this.db.exec(`CREATE TABLE IF NOT EXISTS pibo_ralph_jobs (id TEXT PRIMARY KEY, loop_mode TEXT NOT NULL DEFAULT 'goal', 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, token_budget INTEGER, token_reserve 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, accounting_json 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');
@@ -523,9 +622,21 @@ export class PiboLoopStore {
     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, loop_mode, name, description, enabled, target_json, profile, prompt, max_iterations, token_budget, runtime_options_json, stop_policy_json, resource_json, state_json, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)').run(job.id, job.mode, job.name, job.description ?? null, job.enabled ? 1 : 0, targetJson(job.target), job.profile, job.prompt, job.maxIterations ?? null, job.tokenBudget ?? 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 loop_mode = ?, name = ?, description = ?, enabled = ?, target_json = ?, profile = ?, prompt = ?, max_iterations = ?, token_budget = ?, runtime_options_json = ?, stop_policy_json = ?, resource_json = ?, state_json = ?, updated_at = ? WHERE id = ?').run(job.mode, job.name, job.description ?? null, job.enabled ? 1 : 0, targetJson(job.target), job.profile, job.prompt, job.maxIterations ?? null, job.tokenBudget ?? null, runtimeOptionsJson(job), stopPolicyJson(job.stopPolicy), resourceMetadataJson(job.resources), JSON.stringify(job.state), job.updatedAt, job.id); }
+    insertJob(job) { this.db.prepare('INSERT INTO pibo_ralph_jobs (id, loop_mode, name, description, enabled, target_json, profile, prompt, max_iterations, token_budget, token_reserve, runtime_options_json, stop_policy_json, resource_json, state_json, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)').run(job.id, job.mode, job.name, job.description ?? null, job.enabled ? 1 : 0, targetJson(job.target), job.profile, job.prompt, job.maxIterations ?? null, job.tokenBudget ?? null, job.tokenReserve ?? 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 loop_mode = ?, name = ?, description = ?, enabled = ?, target_json = ?, profile = ?, prompt = ?, max_iterations = ?, token_budget = ?, token_reserve = ?, runtime_options_json = ?, stop_policy_json = ?, resource_json = ?, state_json = ?, updated_at = ? WHERE id = ?').run(job.mode, job.name, job.description ?? null, job.enabled ? 1 : 0, targetJson(job.target), job.profile, job.prompt, job.maxIterations ?? null, job.tokenBudget ?? null, job.tokenReserve ?? 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: job.mode === 'ralph' ? `rrun_${randomUUID()}` : `lrun_${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; }
+    createRunLocked(job, timestamp) {
+        const tokensUsedBefore = job.state.tokensUsed ?? 0;
+        const accounting = job.mode === 'goal' ? {
+            ...(job.tokenBudget !== undefined ? { tokenBudget: job.tokenBudget, remainingTokensBefore: Math.max(0, job.tokenBudget - tokensUsedBefore) } : {}),
+            ...(job.tokenReserve !== undefined ? { tokenReserve: job.tokenReserve } : {}),
+            tokensUsedBefore,
+            tokensUsed: 0,
+            overshootTokens: 0,
+        } : undefined;
+        const run = { id: job.mode === 'ralph' ? `rrun_${randomUUID()}` : `lrun_${randomUUID()}`, jobId: job.id, status: 'running', startedAt: timestamp, ...(accounting ? { accounting } : {}), ...(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, accounting_json, resource_json, started_at, completed_at, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)').run(run.id, run.jobId, null, run.status, null, null, runAccountingJson(run.accounting), resourceMetadataJson(run.resources), run.startedAt ?? null, null, run.createdAt, run.updatedAt);
+        return run;
+    }
 }
 export function createDefaultPiboLoopStore(options = {}) { return new PiboLoopStore(options); }

package/dist/loops/tools.js

@@ -1,5 +1,6 @@
 import { StringEnum, Type } from '@earendil-works/pi-ai';
 import { defineTool } from '@earendil-works/pi-coding-agent';
+import { goalActiveTimeSeconds, goalCanStartNextTurn, goalElapsedWallClockSeconds, goalRemainingTokens } from './accounting.js';
 import { createDefaultPiboLoopStore } from './store.js';
 export const PIBO_GOAL_TOOL_NAMES = ['get_goal', 'create_goal', 'update_goal'];
 let configuredStorePath;
@@ -33,17 +34,30 @@ function positiveInteger(value, field) {
         throw new Error(`${field} must be a positive integer`);
     return value;
 }
+function nonNegativeInteger(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (!Number.isInteger(value) || value < 0)
+        throw new Error(`${field} must be a non-negative integer`);
+    return value;
+}
 function goalPayload(job) {
-    const tokensUsed = job.state.tokensUsed ?? 0;
     const tokenBudget = job.tokenBudget;
     return {
         goalId: job.id,
         objective: job.prompt,
         status: effectiveGoalStatus(job),
+        budgetType: tokenBudget === undefined ? 'unbounded' : 'soft',
         tokenBudget: tokenBudget ?? null,
-        tokensUsed,
-        remainingTokens: tokenBudget === undefined ? null : Math.max(0, tokenBudget - tokensUsed),
-        timeUsedSeconds: job.state.timeUsedSeconds ?? 0,
+        tokenReserve: job.tokenReserve ?? 0,
+        tokensUsed: job.state.tokensUsed ?? 0,
+        remainingTokens: goalRemainingTokens(job) ?? null,
+        canStartNextTurn: goalCanStartNextTurn(job),
+        activeAgentTimeSeconds: goalActiveTimeSeconds(job),
+        elapsedWallClockSeconds: goalElapsedWallClockSeconds(job),
+        goalStartedAt: job.state.goalStartedAt ?? null,
+        goalEndedAt: job.state.goalEndedAt ?? null,
+        wallClockIncludesPausedTime: true,
     };
 }
 function effectiveGoalStatus(job) {
@@ -64,7 +78,7 @@ function createGetGoalTool(context, options) {
     return defineTool({
         name: 'get_goal',
         label: 'Get Goal',
-        description: 'Get the current goal for this Pibo Session, including status, token budget, consumed tokens, remaining tokens, and elapsed active time.',
+        description: 'Get the current goal for this Pibo Session, including soft-budget risk, per-turn reserve, active agent time, and wall-clock elapsed time.',
         promptSnippet: 'Use get_goal when you need the authoritative persisted status or accounting for the current Pibo Session goal.',
         parameters: Type.Object({}),
         async execute() {
@@ -89,7 +103,8 @@ function createCreateGoalTool(context, options) {
         promptSnippet: 'Call create_goal only when the user or system explicitly requests a persistent goal. Do not infer a goal from an ordinary task.',
         parameters: Type.Object({
             objective: Type.String({ description: 'Concrete objective to pursue across automatic continuations.' }),
-            token_budget: Type.Optional(Type.Number({ description: 'Optional positive token budget. Omit unless explicitly requested.' })),
+            token_budget: Type.Optional(Type.Number({ description: 'Optional soft token budget. Usage arrives after each model response, so the final turn can overshoot.' })),
+            token_reserve: Type.Optional(Type.Number({ description: 'Optional non-negative minimum remaining tokens required before Pibo starts another turn.' })),
         }),
         async execute(_toolCallId, params) {
             try {
@@ -98,6 +113,7 @@ function createCreateGoalTool(context, options) {
                 if (!objective)
                     throw new Error('objective is required');
                 const tokenBudget = positiveInteger(params.token_budget, 'token_budget');
+                const tokenReserve = nonNegativeInteger(params.token_reserve, 'token_reserve');
                 return await withStore(options, (store) => {
                     const existing = store.getLatestGoalForSession(session.piboSessionId);
                     if (existing && effectiveGoalStatus(existing) !== 'complete') {
@@ -110,6 +126,7 @@ function createCreateGoalTool(context, options) {
                         profile: session.profileName,
                         prompt: objective,
                         tokenBudget,
+                        tokenReserve,
                         initialPiboSessionId: session.piboSessionId,
                     });
                     return toolResult({ ok: true, goal: goalPayload(job) });
@@ -147,7 +164,7 @@ function createUpdateGoalTool(context, options) {
                         ok: true,
                         goal: goalPayload(job),
                         ...(status === 'complete' && job.tokenBudget !== undefined
-                            ? { completionBudgetReport: `${job.state.tokensUsed ?? 0}/${job.tokenBudget} reported tokens consumed before the current model turn finishes` }
+                            ? { completionBudgetReport: `${job.state.tokensUsed ?? 0}/${job.tokenBudget} reported tokens consumed against a soft budget before the current model turn finishes` }
                             : {}),
                     });
                 });

package/dist/reliability/store.js

@@ -30,6 +30,11 @@ function migratePiboRunControllerColumn(db) {
     db.exec("DROP INDEX IF EXISTS idx_pibo_runs_" + ["o", "wner_updated"].join(""));
     db.exec(`ALTER TABLE pibo_runs RENAME COLUMN ${legacyColumn} TO controller_pibo_session_id`);
 }
+function ensurePiboRunColumn(db, name, definition) {
+    const columns = sqliteTableColumns(db, "pibo_runs");
+    if (!columns.has(name))
+        db.exec(`ALTER TABLE pibo_runs ADD COLUMN ${name} ${definition}`);
+}
 export class PiboReliabilityStore {
     db;
     appendEventStatement;
@@ -135,13 +140,21 @@ export class PiboReliabilityStore {
 				completed_at TEXT,
 				job_id TEXT,
 				retryable INTEGER NOT NULL DEFAULT 0,
-				max_attempts INTEGER NOT NULL DEFAULT 1
+				max_attempts INTEGER NOT NULL DEFAULT 1,
+				timeout_ms INTEGER,
+				timeout_at TEXT,
+				timeout_phase TEXT,
+				service_warning TEXT
 			);
 			CREATE INDEX IF NOT EXISTS idx_pibo_runs_controller_updated
 				ON pibo_runs(controller_pibo_session_id, updated_at);
 			CREATE INDEX IF NOT EXISTS idx_pibo_runs_status
 				ON pibo_runs(status);
 		`);
+        ensurePiboRunColumn(this.db, "timeout_ms", "INTEGER");
+        ensurePiboRunColumn(this.db, "timeout_at", "TEXT");
+        ensurePiboRunColumn(this.db, "timeout_phase", "TEXT");
+        ensurePiboRunColumn(this.db, "service_warning", "TEXT");
         this.appendEventStatement = this.db.prepare(`
 			INSERT INTO pibo_event_stream (topic, key, event_id, idempotency_key, created_at, retention_class, payload_json)
 			VALUES (?, ?, ?, ?, ?, ?, ?)
@@ -466,6 +479,7 @@ export class PiboReliabilityStore {
         const timestamp = now();
         const runId = input.runId ?? `run_${randomUUID()}`;
         const maxAttempts = Math.max(1, input.maxAttempts ?? 1);
+        const timeoutAt = input.timeoutMs === undefined ? undefined : new Date(Date.parse(timestamp) + input.timeoutMs).toISOString();
         const job = this.enqueue({
             queue: "runs",
             payload: {
@@ -473,6 +487,7 @@ export class PiboReliabilityStore {
                 controllerPiboSessionId: input.controllerPiboSessionId,
                 toolName: input.toolName,
                 params: input.params,
+                timeoutMs: input.timeoutMs,
             },
             maxAttempts,
         });
@@ -481,10 +496,10 @@ export class PiboReliabilityStore {
 				INSERT INTO pibo_runs (
 					run_id, kind, controller_pibo_session_id, status, completion_policy, consumed, tool_name,
 					summary, result_json, error, notified_status, acknowledged_status, created_at, updated_at,
-					completed_at, job_id, retryable, max_attempts
-				) VALUES (?, 'tool', ?, 'running', ?, 0, ?, ?, NULL, NULL, NULL, NULL, ?, ?, NULL, ?, ?, ?)
+					completed_at, job_id, retryable, max_attempts, timeout_ms, timeout_at, timeout_phase, service_warning
+				) VALUES (?, 'tool', ?, 'running', ?, 0, ?, ?, NULL, NULL, NULL, NULL, ?, ?, NULL, ?, ?, ?, ?, ?, NULL, ?)
 			`)
-            .run(runId, input.controllerPiboSessionId, input.completionPolicy, input.toolName, `${input.toolName} run is running.`, timestamp, timestamp, job.jobId, input.retryable ? 1 : 0, maxAttempts);
+            .run(runId, input.controllerPiboSessionId, input.completionPolicy, input.toolName, `${input.toolName} run is running.`, timestamp, timestamp, job.jobId, input.retryable ? 1 : 0, maxAttempts, input.timeoutMs ?? null, timeoutAt ?? null, input.serviceWarning ?? null);
         this.claimJob(job.jobId, `run-registry:${process.pid}`, 24 * 60 * 60 * 1000);
         return this.requireRun(runId);
     }
@@ -508,10 +523,14 @@ export class PiboReliabilityStore {
 					completed_at = ?,
 					job_id = ?,
 					retryable = ?,
-					max_attempts = ?
+					max_attempts = ?,
+					timeout_ms = ?,
+					timeout_at = ?,
+					timeout_phase = ?,
+					service_warning = ?
 				WHERE run_id = ?
 			`)
-            .run(next.status, next.completionPolicy, next.consumed ? 1 : 0, next.summary ?? null, next.result ? JSON.stringify(next.result) : null, next.error ?? null, next.notifiedStatus ?? null, next.acknowledgedStatus ?? null, next.updatedAt, next.completedAt ?? null, next.jobId ?? null, next.retryable ? 1 : 0, next.maxAttempts, runId);
+            .run(next.status, next.completionPolicy, next.consumed ? 1 : 0, next.summary ?? null, next.result ? JSON.stringify(next.result) : null, next.error ?? null, next.notifiedStatus ?? null, next.acknowledgedStatus ?? null, next.updatedAt, next.completedAt ?? null, next.jobId ?? null, next.retryable ? 1 : 0, next.maxAttempts, next.timeoutMs ?? null, next.timeoutAt ?? null, next.timeoutPhase ?? null, next.serviceWarning ?? null, runId);
         return this.requireRun(runId);
     }
     getRun(runId) {
@@ -535,7 +554,7 @@ export class PiboReliabilityStore {
     }
     pruneRuns(input) {
         const rows = this.db
-            .prepare("SELECT * FROM pibo_runs WHERE status IN ('completed', 'failed', 'cancelled') AND completed_at IS NOT NULL")
+            .prepare("SELECT * FROM pibo_runs WHERE status IN ('completed', 'failed', 'timed_out', 'cancelled') AND completed_at IS NOT NULL")
             .all();
         const ids = rows
             .map(runFromRow)
@@ -760,6 +779,14 @@ function runFromRow(row) {
         output.completedAt = row.completed_at;
     if (row.job_id)
         output.jobId = row.job_id;
+    if (row.timeout_ms !== null)
+        output.timeoutMs = row.timeout_ms;
+    if (row.timeout_at)
+        output.timeoutAt = row.timeout_at;
+    if (row.timeout_phase === "startup" || row.timeout_phase === "lifetime")
+        output.timeoutPhase = row.timeout_phase;
+    if (row.service_warning)
+        output.serviceWarning = row.service_warning;
     return output;
 }
 function retryDelayMs(attempts, input) {

package/dist/resources/cli.js

@@ -1,3 +1,4 @@
+import { isAbsolute, resolve } from "node:path";
 import { Command } from "commander";
 import { getComputeResourceHealth } from "../compute/resource-health.js";
 import { renderComputeResourceHealthText } from "../compute/cli.js";
@@ -17,6 +18,15 @@ function parsePidList(value) {
         throw new Error("PIDs must be positive integers separated by commas");
     return [...new Set(pids)];
 }
+function parseAbsolutePathList(value) {
+    const paths = value.split(",").map((item) => item.trim());
+    if (paths.some((path) => !path || !isAbsolute(path)))
+        throw new Error("Browser user-data directories must be absolute paths separated by commas");
+    return [...new Set(paths.map((path) => resolve(path)))];
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
 export function renderResourceLeasesText(leases) {
     if (leases.length === 0)
         return "No active managed browser-pool leases.\nNext: pibo resources status";
@@ -53,6 +63,10 @@ export function renderResourceReapText(value) {
         ];
         if (plan.options.includeDev)
             args.push("--include-dev");
+        if (plan.options.exemptBrowserPids.length > 0)
+            args.push(`--exempt-browser-pids ${plan.options.exemptBrowserPids.join(",")}`);
+        if (plan.options.exemptBrowserUserDataDirs.length > 0)
+            args.push(`--exempt-browser-user-data-dirs ${shellQuote(plan.options.exemptBrowserUserDataDirs.join(","))}`);
         if (plan.options.browserPoolRoot)
             args.push(`--browser-pool-root ${plan.options.browserPoolRoot}`);
         if (plan.options.browserUseHome)
@@ -118,6 +132,7 @@ export async function runResourcesCli(argv) {
         .option("--idle-timeout-minutes <n>", "Select browser pools idle for this many minutes", parseNonNegativeNumber, 10)
         .option("--unmanaged-browser-grace-minutes <n>", "Select unmanaged Chromium older than this many minutes", parseNonNegativeNumber, 10)
         .option("--exempt-browser-pids <list>", "Comma-separated browser PIDs or process groups to preserve", parsePidList)
+        .option("--exempt-browser-user-data-dirs <list>", "Comma-separated absolute browser profile directories to preserve", parseAbsolutePathList)
         .option("--browser-pool-root <path>", "Browser pool root directory to scan")
         .option("--browser-use-home <path>", "Browser-use home directory to scan for stale CDP files")
         .option("--json", "Print machine-readable cleanup plan or result")

package/dist/resources/lifecycle.js

@@ -1,7 +1,7 @@
 import { execFile } from "node:child_process";
 import { existsSync } from "node:fs";
 import { readdir, readFile, rm } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { promisify } from "node:util";
 import { applyComputeWorkerReapPlan, buildComputeWorkerReapPlan, planReapWorkers, } from "../compute/docker.js";
 import { defaultBrowserPoolRoot, defaultBrowserUseHome, getComputeResourceHealth, parseProcessList, } from "../compute/resource-health.js";
@@ -60,9 +60,14 @@ export async function planResourceReap(options = {}) {
         collectManagedBrowserPools(resolved.browserPoolRoot),
         planStaleCdpFiles(resolved.browserUseHome),
         planComputeReapSafely({ includeDev: resolved.includeDev, maxAgeMinutes: resolved.maxAgeMinutes, now }),
-        getComputeResourceHealth({ now, browserPoolRoot: resolved.browserPoolRoot, browserUseHome: resolved.browserUseHome }),
+        getComputeResourceHealth({
+            now,
+            browserPoolRoot: resolved.browserPoolRoot,
+            browserUseHome: resolved.browserUseHome,
+            exemptBrowserUserDataDirs: [],
+        }),
     ]);
-    const unmanagedBrowsers = buildUnmanagedBrowserPlanItems(health.browserProcesses.unassignedMainProcessDetails, resolved.unmanagedBrowserGraceMinutes, new Set(resolved.exemptBrowserPids));
+    const unmanagedBrowsers = buildUnmanagedBrowserPlanItems(health.browserProcesses.unassignedMainProcessDetails, resolved.unmanagedBrowserGraceMinutes, new Set(resolved.exemptBrowserPids), new Set(resolved.exemptBrowserUserDataDirs));
     return buildResourceReapPlan({ now, options: resolved, records, staleFiles, unmanagedBrowsers, compute });
 }
 export function buildResourceReapPlan(input) {
@@ -126,9 +131,10 @@ function resolveReapOptions(options) {
         browserPoolRoot: options.browserPoolRoot ?? defaultBrowserPoolRoot(),
         browserUseHome: options.browserUseHome ?? defaultBrowserUseHome(),
         exemptBrowserPids: options.exemptBrowserPids ?? readExemptBrowserPids(),
+        exemptBrowserUserDataDirs: normalizeBrowserUserDataDirs(options.exemptBrowserUserDataDirs ?? readExemptBrowserUserDataDirs()),
     };
 }
-export function buildUnmanagedBrowserPlanItems(processes, graceMinutes, exemptPids = new Set()) {
+export function buildUnmanagedBrowserPlanItems(processes, graceMinutes, exemptPids = new Set(), exemptUserDataDirs = new Set()) {
     const graceSeconds = graceMinutes * 60;
     return processes.map((process) => {
         let action = "terminate";
@@ -141,6 +147,10 @@ export function buildUnmanagedBrowserPlanItems(processes, graceMinutes, exemptPi
             action = "skip";
             reason = "explicitly exempted pid or process group";
         }
+        else if (browserUserDataDirIsExempt(process.userDataDir, exemptUserDataDirs)) {
+            action = "skip";
+            reason = "explicitly exempted browser user-data-dir";
+        }
         else if (process.elapsedSeconds !== undefined && process.elapsedSeconds < graceSeconds) {
             action = "skip";
             reason = `process age ${process.elapsedSeconds}s is within ${graceSeconds}s grace period`;
@@ -211,6 +221,20 @@ function readExemptBrowserPids() {
         .map((value) => Number.parseInt(value.trim(), 10))
         .filter((value) => Number.isInteger(value) && value > 0);
 }
+function readExemptBrowserUserDataDirs() {
+    return (process.env.PIBO_RESOURCE_REAPER_EXEMPT_BROWSER_USER_DATA_DIRS ?? "").split(",");
+}
+function normalizeBrowserUserDataDirs(values) {
+    return [...new Set([...values]
+            .map((value) => value.trim())
+            .filter((value) => value.length > 0 && isAbsolute(value))
+            .map((value) => resolve(value)))];
+}
+function browserUserDataDirIsExempt(userDataDir, exemptions) {
+    if (!userDataDir || !isAbsolute(userDataDir))
+        return false;
+    return exemptions.has(resolve(userDataDir));
+}
 function buildBrowserReapPlanItem(record, now, idleTimeoutMinutes) {
     const { state } = record;
     let action = "skip";

package/dist/resources/reaper.js

@@ -76,6 +76,7 @@ export class ResourceReaperService {
                 browserPoolRoot: this.options.browserPoolRoot,
                 browserUseHome: this.options.browserUseHome,
                 exemptBrowserPids: this.options.exemptBrowserPids,
+                exemptBrowserUserDataDirs: this.options.exemptBrowserUserDataDirs,
                 now: runAt,
             });
             result = await this.apply(plan);