@superjackfruitlabs/salaam 0.0.2 → 0.0.4

package/dist/src/task-budget.js

@@ -6,6 +6,12 @@ export class TaskBudgetError extends ServiceError {
         this.session_id = session_id;
     }
 }
+/** Tools a critic review child may hold and still be left out of the verification busy check. */
+export const READ_ONLY_REVIEW_TOOLS = [
+    'salaam_findings',
+    'salaam_probe',
+    'salaam_repository',
+];
 export class TaskBudget {
     store;
     tasks;
@@ -23,6 +29,8 @@ export class TaskBudget {
         store.taskChildFinished = (attempt) => this.releaseChild(attempt);
         store.taskCommandAdmission = (session) => this.command(session);
         store.taskRemainingRuntime = (session) => this.remaining(session);
+        // Only the task's own session: a child's attempt keeps the budget its reservation set.
+        store.taskAttemptRequestLimit = (session) => this.tasks.forSession(session)?.limits.requests;
     }
     task(session) {
         const direct = this.tasks.forSession(session);
@@ -39,19 +47,49 @@ export class TaskBudget {
             .n);
         return { ...runtime, invocations_spent: n, external_model_usage: n ? 'unknown' : 'none' };
     }
-    active(task) {
+    /** The child attempt of each running critic review of this task revision whose recorded
+     * tools are all read-only (operator ruling 2026-10-30, option A). Only verification reads may
+     * leave these out of the busy count: the reviewer reads a digest-bound snapshot and cannot
+     * write the workspace, run a command or reach the station (staging card_019a647a169744ff). */
+    readOnlyReviews(task) {
+        if (!this.store.db
+            .prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='task_critics'")
+            .get())
+            return [];
+        const rows = this.store.db
+            .prepare("SELECT c.child_attempt, c.authority FROM task_critics r JOIN child_tasks c ON c.id=r.child_id WHERE r.task_id=? AND r.plan_revision=? AND r.state='running' AND c.parent_session=?")
+            .all(task.id, task.plan_revision, task.session_id);
+        return rows
+            .filter((r) => {
+            try {
+                const tools = JSON.parse(r.authority);
+                return (Array.isArray(tools) &&
+                    tools.every((t) => READ_ONLY_REVIEW_TOOLS.includes(t)));
+            }
+            catch {
+                return false;
+            }
+        })
+            .map((r) => r.child_attempt);
+    }
+    /** Live work in the task's session tree. `verification` leaves out a running read-only review's
+     * child attempt, for verification reads only; admission and concurrency count everything. */
+    active(task, opts = {}) {
+        const excluded = JSON.stringify(opts.verification ? this.readOnlyReviews(task) : []);
         const row = this.store.db
             .prepare(`WITH tree(id) AS (SELECT ? UNION ALL SELECT child_session FROM child_tasks WHERE parent_session=?) SELECT
-      (SELECT count(*) FROM attempts WHERE session_id IN (SELECT id FROM tree) AND state IN ('accepted','dispatching','running')) +
+      (SELECT count(*) FROM attempts WHERE session_id IN (SELECT id FROM tree) AND state IN ('accepted','dispatching','running') AND id NOT IN (SELECT value FROM json_each(?))) +
+      (SELECT count(*) FROM station_calls WHERE session_id IN (SELECT id FROM tree) AND kind='check' AND attempt_id IS NULL AND state IN ('prepared','dispatching')) +
       (SELECT count(*) FROM command_runs WHERE session_id IN (SELECT id FROM tree) AND state NOT IN ('succeeded','failed','cancelled','timed_out','output_limited','interrupted')) +
       (SELECT count(*) FROM external_runs e JOIN child_tasks c ON c.id=e.child_id JOIN attempts a ON a.id=c.child_attempt WHERE c.parent_session=? AND e.stopped=0 AND a.state NOT IN ('accepted','dispatching','running')) AS n`)
-            .get(task.session_id, task.session_id, task.session_id);
+            .get(task.session_id, task.session_id, excluded, task.session_id);
         return Number(row.n);
     }
     deny(session, message) {
         throw new TaskBudgetError(session, message);
     }
     check(session) {
+        this.store.execution.assert(session);
         const task = this.task(session);
         if (!task)
             return;

package/dist/src/task-context.js

@@ -13,6 +13,7 @@ export class TaskContext {
     store;
     artifacts;
     work;
+    admitted;
     constructor(store, artifacts) {
         this.store = store;
         this.artifacts = artifacts;
@@ -56,14 +57,21 @@ export class TaskContext {
                 session_id: id,
                 binding,
                 version: state.version,
-                instructions: 'Use active facts. Superseded facts are historical. Do not repeat completed steps. Retrieve evidence with salaam_history.',
+                instructions: 'Runtime bookkeeping, not a user message or a new task. Answer the latest actual user request. Empty facts mean no saved notes, not an empty workspace or missing objective. Inspect workspace tools for filesystem questions; history is only for prior conversation. Use active facts; superseded facts are historical. Do not repeat completed steps.',
                 facts: state.facts,
                 ...(admitted.length ? { admitted_agents: admitted } : {}),
                 ...(this.work?.forSession(id) ? { work_task: this.work.frame(id) } : {}),
             });
         if (Buffer.byteLength(frame) > TASK_FRAME_BYTES)
             throw new ServiceError('context_capacity', 'Mandatory task state exceeds the context budget');
-        return frame;
+        const admittedContext = this.admitted?.frame(id);
+        return admittedContext
+            ? 'SALAAM_TASK_STATE ' +
+                canonical({
+                    ...JSON.parse(frame.slice('SALAAM_TASK_STATE '.length)),
+                    admitted_context: admittedContext,
+                })
+            : frame;
     }
     update(id, request, expected, input, authorize) {
         const kind = string(input.kind, 'kind', 32);

package/dist/src/task-critic.js

@@ -0,0 +1,115 @@
+import { randomUUID } from 'node:crypto';
+/**
+ * The completion critic (item 8). When the admitted plan declares a critic, the built-in reviewer
+ * reads an immutable snapshot of the verified deliverables against the plan's rubric before the
+ * task may complete. Its verdict is bound to the exact verified evidence (checks and tree): any
+ * later change makes it stale. A critical or high finding means changes are needed; a reviewer
+ * that reports nothing at all is a failure, never a pass.
+ */
+export const CRITIC_BUDGET = 4;
+export const CRITIC_REOPENS = 2;
+export class TaskCritic {
+    store;
+    artifacts;
+    deps;
+    constructor(store, artifacts, deps) {
+        this.store = store;
+        this.artifacts = artifacts;
+        this.deps = deps;
+        store.db.exec(`CREATE TABLE IF NOT EXISTS task_critics(
+      id TEXT PRIMARY KEY NOT NULL,
+      task_id TEXT NOT NULL,
+      plan_revision INTEGER NOT NULL,
+      evidence_digest TEXT NOT NULL,
+      round INTEGER NOT NULL,
+      child_id TEXT NOT NULL,
+      state TEXT NOT NULL,
+      findings TEXT,
+      reason TEXT,
+      UNIQUE(task_id, plan_revision, evidence_digest))`);
+    }
+    /** Whether this exact verified evidence has a passing critic verdict. */
+    passed(task, evidenceDigest) {
+        return (this.store.db
+            .prepare("SELECT 1 FROM task_critics WHERE task_id=? AND plan_revision=? AND evidence_digest=? AND state='pass'")
+            .get(task.id, task.plan_revision, evidenceDigest) !== undefined);
+    }
+    /** How many times the critic has sent this plan revision back for changes. */
+    reopens(task) {
+        return Number(this.store.db
+            .prepare("SELECT count(*) AS n FROM task_critics WHERE task_id=? AND plan_revision=? AND state='changes_needed'")
+            .get(task.id, task.plan_revision).n);
+    }
+    /** The verdict for this verified evidence, starting the reviewer the first time it is asked. */
+    async gate(task, evidenceDigest, deliverables) {
+        const critic = task.completion_gate?.critic;
+        if (!critic)
+            return { state: 'pass' };
+        const row = this.store.db
+            .prepare('SELECT * FROM task_critics WHERE task_id=? AND plan_revision=? AND evidence_digest=?')
+            .get(task.id, task.plan_revision, evidenceDigest);
+        if (row)
+            return this.settle(row);
+        const last = this.store.db
+            .prepare('SELECT b.attempt_id FROM task_step_attempts b JOIN task_steps s ON s.id=b.step_id WHERE s.task_id=? ORDER BY b.rowid DESC LIMIT 1')
+            .get(task.id);
+        if (!last)
+            return { state: 'failed', reason: 'No step attempt for the critic to follow' };
+        if (!deliverables.length)
+            return { state: 'failed', reason: 'No verified deliverables to review' };
+        const round = Number(this.store.db
+            .prepare('SELECT count(*) AS n FROM task_critics WHERE task_id=? AND plan_revision=?')
+            .get(task.id, task.plan_revision).n) + 1;
+        const snapshot = Object.fromEntries(deliverables.map((d) => [
+            d.path,
+            { content: Buffer.from(d.content, 'utf8').toString('base64'), executable: false },
+        ]));
+        const grant = await this.deps.admit(task, `critic:${task.id}:${task.plan_revision}`);
+        const child = this.deps.spawn(task, String(last.attempt_id), `critic-${task.plan_revision}-${round}`, [
+            'Judge the delivered work against this rubric before it is accepted:',
+            critic.rubric,
+            '',
+            'Objective: ' + task.objective,
+            'Deliverables (the snapshot): ' + deliverables.map((d) => d.path).join(', '),
+            '',
+            'Report findings with salaam_findings, citing the file and line. Use critical or high only',
+            'for what must change before the work is accepted; medium or low for suggestions. If the',
+            'work meets the rubric, report an empty list.',
+        ].join('\n'), CRITIC_BUDGET, grant, snapshot);
+        this.store.db
+            .prepare("INSERT INTO task_critics VALUES (?,?,?,?,?,?,'running',NULL,NULL)")
+            .run(randomUUID(), task.id, task.plan_revision, evidenceDigest, round, child.id);
+        return { state: 'pending' };
+    }
+    settle(row) {
+        if (row.state === 'pass')
+            return { state: 'pass' };
+        if (row.state === 'changes_needed')
+            return { state: 'changes_needed', findings: JSON.parse(String(row.findings)) };
+        if (row.state === 'failed')
+            return { state: 'failed', reason: String(row.reason) };
+        const child = this.store.db
+            .prepare('SELECT state FROM child_tasks WHERE id=?')
+            .get(String(row.child_id));
+        if (!child || child.state === 'accepted')
+            return { state: 'pending' };
+        const report = this.store.db
+            .prepare('SELECT artifact_id FROM specialist_reports WHERE worker_id=?')
+            .get(this.deps.workerId(String(row.child_id)));
+        const set = (state, findings, reason) => this.store.db
+            .prepare('UPDATE task_critics SET state=?,findings=?,reason=? WHERE id=?')
+            .run(state, findings ? JSON.stringify(findings) : null, reason, String(row.id));
+        if (!report) {
+            const reason = 'The critic returned no findings report';
+            set('failed', null, reason);
+            return { state: 'failed', reason };
+        }
+        const findings = JSON.parse(this.artifacts.read(String(report.artifact_id))).findings.map(({ path, line, severity, message }) => ({ path, line, severity, message }));
+        if (findings.some((f) => f.severity === 'critical' || f.severity === 'high')) {
+            set('changes_needed', findings, null);
+            return { state: 'changes_needed', findings };
+        }
+        set('pass', findings, null);
+        return { state: 'pass' };
+    }
+}

package/dist/src/task-driver.js

@@ -1,3 +1,6 @@
+import { CRITIC_REOPENS } from './task-critic.js';
+import { requiredChecks } from './task-policy.js';
+import { RATE_LIMIT_STOP, RateLimitRetries } from './rate-limit-retries.js';
 import { randomUUID } from 'node:crypto';
 import { commandTerminal } from './coding.js';
 import { canonical, ServiceError } from './protocol.js';
@@ -11,8 +14,10 @@ export class TaskDriver {
     children;
     coding;
     timer;
+    awaitingAuthorityRenewal;
     active;
     stopped = true;
+    rateLimits;
     constructor(store, tasks, budget, verification, supervisor, children, coding) {
         this.store = store;
         this.tasks = tasks;
@@ -21,6 +26,7 @@ export class TaskDriver {
         this.supervisor = supervisor;
         this.children = children;
         this.coding = coding;
+        this.rateLimits = new RateLimitRetries(store);
         tasks.assertProgressionBinding = (task, binding) => {
             if (canonical(this.verification.binding(task)) !== binding)
                 throw new ServiceError('task_progression_stale', 'Workspace or execution environment changed since the bounded grant');
@@ -146,6 +152,7 @@ export class TaskDriver {
             await this.supervisor.cancelAttempt(attempt.id);
         }
         await this.children.external?.cancelRoot(task.session_id);
+        await this.verification.station?.station.stopSession(task.session_id);
         const compactions = this.store.db
             .prepare("SELECT id FROM compactions WHERE session_id=? AND state='running'")
             .all(task.session_id);
@@ -265,7 +272,7 @@ export class TaskDriver {
             this.stop(task, 'Managed compaction ' + work.state + '; inspect before continuing');
         return false;
     }
-    check(task, key, step) {
+    async check(task, key, step) {
         const receipt = this.verification.latest(task, key, step);
         if (!receipt) {
             this.verification.start(task.id, key, step, 'auto-check:' + task.id + ':' + task.plan_revision + ':' + (step ?? 'final') + ':' + key, task.revision, () => {
@@ -278,7 +285,7 @@ export class TaskDriver {
         }
         if (receipt.state === 'accepted' || receipt.state === 'running')
             return false;
-        if (!this.verification.fresh(receipt)) {
+        if (!(await this.verification.freshAsync(receipt))) {
             this.stop(task, 'Verification failed or became stale: ' + key);
             return false;
         }
@@ -293,6 +300,22 @@ export class TaskDriver {
             return;
         }
         if (task.steps.some((s) => ['interrupted', 'failed', 'cancelled'].includes(s.state))) {
+            // A provider 429 is retried as a fresh attempt of the step after a backoff; past the limit,
+            // or with no progression step left, the task stops with a block recovery can settle.
+            const retry = this.rateLimits.decide(task);
+            if (retry.action === 'wait')
+                return;
+            if (retry.action === 'retry' && Number(r.remaining_steps) >= 1) {
+                if (!(await this.worker(task)) || this.stopped)
+                    return;
+                this.tasks.retryStep(task.id, retry.step, retry.n, Number(r.auto_epoch));
+                return;
+            }
+            if (retry.action !== 'none') {
+                this.budget.block(task.session_id, RATE_LIMIT_STOP);
+                this.stop(task, RATE_LIMIT_STOP);
+                return;
+            }
             this.stop(task, 'An interrupted or failed step requires explicit operator review');
             return;
         }
@@ -319,9 +342,9 @@ export class TaskDriver {
                 return;
             }
             for (const key of reviewing.checks)
-                if (!this.check(task, key, reviewing.id))
+                if (!(await this.check(task, key, reviewing.id)))
                     return;
-            this.verification.verifiedStep(task, reviewing.id);
+            await this.verification.verifiedStepAsync(task, reviewing.id);
             return;
         }
         if (task.steps.every((s) => s.state === 'completed')) {
@@ -329,10 +352,41 @@ export class TaskDriver {
                 this.stop(task, 'Configure acceptance checks and deliverable evidence before completion');
                 return;
             }
-            for (const check of task.acceptance)
-                if (!this.check(task, check.key, null))
+            // A passed receipt cannot be re-observed while another final check owns
+            // the native workspace. Wait for the whole set before testing freshness;
+            // finishAsync still performs the final transactional evidence validation.
+            if (requiredChecks(task).some((check) => {
+                const receipt = this.verification.latest(task, check.key, null);
+                return receipt?.state === 'accepted' || receipt?.state === 'running';
+            }))
+                return;
+            for (const check of requiredChecks(task))
+                if (!(await this.check(task, check.key, null)))
+                    return;
+            // Item 8: a declared critic reviews the verified deliverables before completion.
+            if (task.completion_gate?.critic) {
+                const verdict = await this.verification.criticGateAsync(task);
+                if (verdict.state === 'pending')
+                    return;
+                if (verdict.state === 'failed') {
+                    this.stop(task, 'Critic review failed: ' + verdict.reason);
                     return;
-            this.verification.finish(task.id, 'auto-finish:' + task.id + ':' + task.plan_revision, task.revision, null, () => {
+                }
+                if (verdict.state === 'changes_needed') {
+                    const round = this.verification.critic.reopens(task);
+                    if (round > CRITIC_REOPENS || Number(r.remaining_steps) < 1) {
+                        this.stop(task, 'Critic requested changes');
+                        return;
+                    }
+                    if (!(await this.worker(task)) || this.stopped)
+                        return;
+                    this.tasks.reopenForCritic(task.id, task.steps.at(-1).id, round, Number(r.auto_epoch), verdict.findings
+                        .map((f) => `- ${f.path}:${f.line} (${f.severity}) ${f.message}`)
+                        .join('\n'));
+                    return;
+                }
+            }
+            await this.verification.finishAsync(task.id, 'auto-finish:' + task.id + ':' + task.plan_revision, task.revision, null, () => {
                 if (!this.budget.state(task.id).auto_enabled)
                     throw new ServiceError('task_authority', 'Progression paused before completion');
             });
@@ -383,7 +437,7 @@ export class TaskDriver {
         this.tasks.advance(grant.id);
     }
     async tick() {
-        this.verification.reconcile();
+        await this.verification.reconcileAsync();
         for (const row of this.store.db
             .prepare('SELECT id FROM durable_tasks ORDER BY rowid')
             .all()) {
@@ -393,6 +447,8 @@ export class TaskDriver {
             const r = this.budget.state(task.id);
             if (['succeeded', 'succeeded_with_exception', 'cancelled'].includes(task.state))
                 continue;
+            if (this.awaitingAuthorityRenewal?.(task.session_id))
+                continue;
             if (r.started_at !== null && Date.now() - Number(r.started_at) >= task.limits.runtime_ms) {
                 this.budget.block(task.session_id, 'Task runtime limit reached');
                 await this.stopActive(task);
@@ -434,6 +490,19 @@ export class TaskDriver {
             }
         }
     }
+    async viewAsync(id) {
+        const result = this.view(id);
+        if (!this.verification.station)
+            return result;
+        result.verification = await this.verification.viewAsync(this.tasks.get(id));
+        const current = this.tasks.get(id);
+        if (result.verification.completion?.fresh &&
+            ['succeeded', 'succeeded_with_exception'].includes(current.state)) {
+            result.state = current.state;
+            result.reason = current.reason;
+        }
+        return result;
+    }
     view(id) {
         const task = this.tasks.get(id), runtime = this.budget.state(id), verification = this.verification.view(task);
         let state = task.state, reason = task.reason;

package/dist/src/task-policy.js

@@ -1,5 +1,23 @@
 import { integer, object, ServiceError, string } from './protocol.js';
 import { filePath } from './workspaces.js';
+/** Every check completion requires: the acceptance checks, then each hook as hook-<key>. */
+export function requiredChecks(policy) {
+    return [
+        ...policy.acceptance,
+        ...(policy.completion_gate?.hooks ?? []).map((h) => ({ ...h, key: 'hook-' + h.key })),
+    ];
+}
+const check = (v, keys, what) => {
+    const c = object(v), key = string(c.key, what + ' key', 64);
+    if (!/^[a-zA-Z0-9_-]+$/.test(key) || keys.has(key))
+        throw new ServiceError('invalid_plan', what + ' keys must be unique identifiers', 400);
+    keys.add(key);
+    return {
+        key,
+        command: string(c.command, what + ' command', 4096),
+        cwd: c.cwd === undefined || c.cwd === '.' ? '.' : filePath(c.cwd),
+    };
+};
 export const DEFAULT_TASK_LIMITS = {
     requests: 64,
     runtime_ms: 900000,
@@ -14,17 +32,7 @@ export function taskPolicy(value) {
     if (!Array.isArray(raw) || raw.length > 8)
         throw new ServiceError('invalid_plan', 'Supply at most eight acceptance checks', 400);
     const keys = new Set();
-    const acceptance = raw.map((v) => {
-        const c = object(v), key = string(c.key, 'check key', 64);
-        if (!/^[a-zA-Z0-9_-]+$/.test(key) || keys.has(key))
-            throw new ServiceError('invalid_plan', 'Acceptance keys must be unique identifiers', 400);
-        keys.add(key);
-        return {
-            key,
-            command: string(c.command, 'check command', 4096),
-            cwd: c.cwd === undefined || c.cwd === '.' ? '.' : filePath(c.cwd),
-        };
-    });
+    const acceptance = raw.map((v) => check(v, keys, 'Acceptance'));
     const paths = value.deliverables ?? [];
     if (!Array.isArray(paths) || paths.length > 32)
         throw new ServiceError('invalid_plan', 'Supply at most 32 deliverable paths', 400);
@@ -66,5 +74,29 @@ export function taskPolicy(value) {
             throw new ServiceError('invalid_budget', 'Invocation limit must be 1–64', 400);
         limits.invocations = n;
     }
-    return { acceptance, deliverables, limits };
+    let completion_gate;
+    if (value.completion_gate !== undefined) {
+        const g = object(value.completion_gate);
+        const hooks = g.hooks;
+        const c = g.critic;
+        const critic = c === null
+            ? null
+            : (() => {
+                const v = object(c);
+                if (Object.keys(v).join(',') !== 'rubric')
+                    throw new ServiceError('invalid_plan', 'A critic names only its rubric', 400);
+                return { rubric: string(v.rubric, 'critic rubric', 4096) };
+            })();
+        if (Object.keys(g).sort().join(',') !== 'critic,hooks' ||
+            !Array.isArray(hooks) ||
+            hooks.length > 8 ||
+            (!critic && hooks.length < 1))
+            throw new ServiceError('invalid_plan', 'A completion gate has a critic or 1–8 hooks, and at most 8 hooks', 400);
+        const hookKeys = new Set();
+        completion_gate = { critic, hooks: hooks.map((v) => check(v, hookKeys, 'Hook')) };
+        if (requiredChecks({ acceptance, completion_gate }).length !==
+            new Set(requiredChecks({ acceptance, completion_gate }).map((c) => c.key)).size)
+            throw new ServiceError('invalid_plan', 'A hook collides with an acceptance check', 400);
+    }
+    return { acceptance, deliverables, limits, ...(completion_gate ? { completion_gate } : {}) };
 }