@superjackfruitlabs/salaam 0.0.3 → 0.0.4

package/src/task-policy.ts

@@ -17,11 +17,41 @@ export interface TaskLimits {
   output_token_bound: number | null;
   verification_runs: number;
 }
+/** Item 8: checks required at completion, next to the acceptance checks. The critic is not yet
+ * admitted, so it is always null. */
+export interface CompletionGate {
+  /** The built-in reviewer judges the verified deliverables against this rubric. */
+  critic: { rubric: string } | null;
+  hooks: TaskCheck[];
+}
 export interface TaskPolicy {
   acceptance: TaskCheck[];
   deliverables: string[];
   limits: TaskLimits;
+  /** Present only when the plan declares one, so a plan without it keeps its exact shape. */
+  completion_gate?: CompletionGate;
+}
+/** Every check completion requires: the acceptance checks, then each hook as hook-<key>. */
+export function requiredChecks(
+  policy: Pick<TaskPolicy, 'acceptance' | 'completion_gate'>,
+): TaskCheck[] {
+  return [
+    ...policy.acceptance,
+    ...(policy.completion_gate?.hooks ?? []).map((h) => ({ ...h, key: 'hook-' + h.key })),
+  ];
 }
+const check = (v: unknown, keys: Set<string>, what: string): TaskCheck => {
+  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: TaskLimits = {
   requests: 64,
   runtime_ms: 900000,
@@ -36,18 +66,7 @@ export function taskPolicy(value: Record<string, unknown>): TaskPolicy {
   if (!Array.isArray(raw) || raw.length > 8)
     throw new ServiceError('invalid_plan', 'Supply at most eight acceptance checks', 400);
   const keys = new Set<string>();
-  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);
@@ -88,5 +107,38 @@ export function taskPolicy(value: Record<string, unknown>): TaskPolicy {
       throw new ServiceError('invalid_budget', 'Invocation limit must be 1–64', 400);
     limits.invocations = n;
   }
-  return { acceptance, deliverables, limits };
+  let completion_gate: CompletionGate | undefined;
+  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<string>();
+    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 } : {}) };
 }

package/src/task-verification.ts

@@ -1,3 +1,5 @@
+import type { TaskCritic, CriticVerdict } from './task-critic.js';
+import { requiredChecks } from './task-policy.js';
 import { StationTaskVerification, type StationCheckEvidence } from './station-task-verification.js';
 import type { StationWork } from './station-work.js';
 import { randomUUID } from 'node:crypto';
@@ -63,7 +65,7 @@ export class TaskVerification {
   }
   assertIdle(task: WorkTask, stationInspection?: string): void {
     if (
-      this.budget.active(task) > 0 ||
+      this.budget.active(task, { verification: true }) > 0 ||
       this.store.db
         .prepare("SELECT 1 FROM compactions WHERE session_id=? AND state='running'")
         .get(task.session_id)
@@ -156,7 +158,7 @@ export class TaskVerification {
           throw new ServiceError('task_settled', 'Revise a cancelled task before completing it');
         this.assertIdle(task);
         if (!this.station) this.coding.assertSafe(task.session_id);
-        if (!task.acceptance.some((c) => c.key === key))
+        if (!requiredChecks(task).some((c) => c.key === key))
           throw new ServiceError('invalid_check', 'Check is not in this task plan');
         if (
           step &&
@@ -215,7 +217,7 @@ export class TaskVerification {
       return;
     }
     const task = this.tasks.get(receipt.task_id),
-      check = task.acceptance.find((c) => c.key === receipt.check_key);
+      check = requiredChecks(task).find((c) => c.key === receipt.check_key);
     try {
       const existing = this.store.db
         .prepare('SELECT id FROM command_runs WHERE session_id=? AND step_key=?')
@@ -485,6 +487,32 @@ export class TaskVerification {
       );
     return this.finishRecorded(id, request, expected, exception, authorize);
   }
+  /** Item 8: the completion critic, when the service has one. */
+  critic?: TaskCritic;
+  /** The critic's verdict on the current fresh verified evidence, starting it the first time.
+   * Reads the evidence outside the finishing transaction, so starting the reviewer can never be
+   * rolled back with a refused finish; the finish itself re-checks the verdict against its own
+   * evidence. */
+  async criticGateAsync(task: WorkTask): Promise<CriticVerdict> {
+    if (!task.completion_gate?.critic) return { state: 'pass' };
+    if (!this.critic || !this.station)
+      return { state: 'failed', reason: 'A critic needs the station verification boundary' };
+    const checks = requiredChecks(task).map((c) => this.latest(task, c.key, null));
+    if (checks.some((c) => !c || c.state !== 'passed')) return { state: 'pending' };
+    const fresh = await this.station.withFreshMany(
+      checks.map((c) => c!.id),
+      task.deliverables,
+      (evidence, deliverables) => ({ evidence, deliverables }),
+    );
+    return this.critic.gate(
+      task,
+      digest(fresh.evidence),
+      (fresh.deliverables as { path: string; content: string }[]).map(({ path, content }) => ({
+        path,
+        content,
+      })),
+    );
+  }
   async finishAsync(
     id: string,
     request: string,
@@ -521,7 +549,7 @@ export class TaskVerification {
         'verification_required',
         'Configured checks and deliverables required',
       );
-    const checks = task.acceptance.map((c) => this.latest(task, c.key, null));
+    const checks = requiredChecks(task).map((c) => this.latest(task, c.key, null));
     if (checks.some((c) => !c || c.state !== 'passed'))
       throw new ServiceError('verification_required', 'Passed configured checks required');
     return this.station.withFreshMany(
@@ -541,7 +569,7 @@ export class TaskVerification {
     if (view.completion?.state === 'succeeded') {
       try {
         const evidence = JSON.parse(this.artifacts.read(String(view.completion.artifact_id)));
-        const checks = task.acceptance.map((c) => this.latest(task, c.key, null));
+        const checks = requiredChecks(task).map((c) => this.latest(task, c.key, null));
         if (checks.some((c) => !c || c.state !== 'passed' || !evidence.checks.includes(c.id)))
           throw Error('Changed checks');
         view.completion.fresh = await this.station.withFreshMany(
@@ -578,7 +606,7 @@ export class TaskVerification {
       this.assertIdle(task);
       if (task.steps.some((s) => s.state !== 'completed'))
         throw new ServiceError('verification_required', 'Every step must be reviewed or verified');
-      const checks = task.acceptance.map((c) => this.latest(task, c.key, null));
+      const checks = requiredChecks(task).map((c) => this.latest(task, c.key, null));
       const missing: string[] = [];
       if (!task.acceptance.length) missing.push('No configured acceptance checks');
       if (!task.deliverables.length) missing.push('No configured deliverable paths');
@@ -589,7 +617,7 @@ export class TaskVerification {
             ? !protectedResult.evidence.some((e) => e.check_id === checks[n]!.id)
             : !this.fresh(checks[n]!))
         )
-          missing.push('Fresh check required: ' + task.acceptance[n]!.key);
+          missing.push('Fresh check required: ' + requiredChecks(task)[n]!.key);
       let workspace: { id: string; revision: number; digest: string } | null = null,
         deliverables: unknown[] = [],
         diff: unknown = null;
@@ -597,7 +625,17 @@ export class TaskVerification {
         if (protectedResult) {
           const e = protectedResult.evidence[0]!;
           workspace = { id: 'station:' + e.root_digest, revision: 0, digest: e.tree_digest };
-          deliverables = protectedResult.deliverables;
+          // Keep each deliverable's verified bytes as a session artifact, committed with the
+          // completion, so publication reads the verified revision and never the live workspace.
+          deliverables = (
+            protectedResult.deliverables as { path: string; sha256: string; content: string }[]
+          ).map(({ path, sha256, content }) => {
+            if (typeof content !== 'string')
+              throw new ServiceError('verification_required', 'Deliverable bytes unavailable');
+            const artifact = this.artifacts.prepare(task.session_id, content);
+            artifact.commit();
+            return { path, sha256, artifact_id: artifact.id };
+          });
           diff = {
             backend: 'linux-systemd-station-v1',
             root_digest: e.root_digest,
@@ -617,6 +655,12 @@ export class TaskVerification {
       } catch (error) {
         missing.push('Workspace verification unavailable: ' + (error as Error).message);
       }
+      // Item 8: a declared critic must have passed this exact verified evidence.
+      if (
+        task.completion_gate?.critic &&
+        !(protectedResult && this.critic?.passed(task, digest(protectedResult.evidence)))
+      )
+        missing.push('Critic review required');
       if (missing.length && !exception)
         throw new ServiceError('verification_required', missing.join('; '));
       if (exception) {
@@ -702,7 +746,7 @@ export class TaskVerification {
           if (completion.state === 'succeeded')
             fresh =
               fresh &&
-              task.acceptance.every((check) => {
+              requiredChecks(task).every((check) => {
                 const latest = this.latest(task, check.key, null);
                 return !!latest && evidence.checks.includes(latest.id) && this.fresh(latest);
               });

package/src/task-work.ts

@@ -98,6 +98,80 @@ export class TaskWork {
       .prepare('UPDATE task_runtime SET remaining_steps=remaining_steps-1 WHERE task_id=?')
       .run(task.id);
   }
+  /** Item 8: re-run the last completed step with the critic's findings added to its instruction,
+   * under its own re-prepared progression grant and a request of its own. */
+  reopenForCritic(
+    taskId: string,
+    stepId: string,
+    round: number,
+    epoch: number,
+    findings: string,
+  ): unknown {
+    const task = this.get(taskId);
+    const step = task.steps.find((s) => s.id === stepId);
+    const grant = this.store.db
+      .prepare(
+        "SELECT id FROM task_grants WHERE task_id=? AND step_id=? AND plan_revision=? AND epoch=? AND state='accepted'",
+      )
+      .get(task.id, stepId, task.plan_revision, epoch) as { id: string } | undefined;
+    if (!grant || !step || step.state !== 'completed' || task.steps.at(-1)?.id !== stepId)
+      throw new ServiceError('task_authority', 'Only the completed last step can be reopened');
+    this.store.transaction(() => {
+      this.store.db.prepare("UPDATE task_steps SET state='pending' WHERE id=?").run(stepId);
+      this.store.db.prepare("UPDATE task_grants SET state='prepared' WHERE id=?").run(grant.id);
+      this.store.event(task.session_id, 'work_task.step_reopened', {
+        task_id: task.id,
+        step_id: stepId,
+        grant_id: grant.id,
+        round,
+        reason: 'Critic requested changes',
+      });
+    });
+    return this.run(
+      task.id,
+      stepId,
+      'task-grant:' + grant.id + ':critic-reopen:' + round,
+      this.get(task.id).revision,
+      step.instruction +
+        '\n\nBefore this work is accepted, a reviewer asked for these changes:\n' +
+        findings,
+      null,
+      null,
+      grant.id,
+    );
+  }
+  /** Re-run a step the provider rate-limited, as a fresh attempt under its own progression grant
+   * (re-prepared, with a request of its own, so it is never a replay of the refused attempt). */
+  retryStep(taskId: string, stepId: string, n: number, epoch: number): unknown {
+    const task = this.get(taskId);
+    const grant = this.store.db
+      .prepare(
+        "SELECT id FROM task_grants WHERE task_id=? AND step_id=? AND plan_revision=? AND epoch=? AND state='accepted'",
+      )
+      .get(task.id, stepId, task.plan_revision, epoch) as { id: string } | undefined;
+    if (!grant || task.steps.find((s) => s.id === stepId)?.state !== 'failed')
+      throw new ServiceError('task_authority', 'No settled grant for this rate-limited step');
+    this.store.transaction(() => {
+      this.store.db.prepare("UPDATE task_grants SET state='prepared' WHERE id=?").run(grant.id);
+      this.store.event(task.session_id, 'work_task.step_retried', {
+        task_id: task.id,
+        step_id: stepId,
+        grant_id: grant.id,
+        retry: n,
+        reason: 'Provider rate limit',
+      });
+    });
+    return this.run(
+      task.id,
+      stepId,
+      'task-grant:' + grant.id + ':rate-limit-retry:' + n,
+      task.revision,
+      null,
+      null,
+      null,
+      grant.id,
+    );
+  }
   advance(grantId: string): unknown {
     const grant = this.store.db.prepare('SELECT * FROM task_grants WHERE id=?').get(grantId) as
       { task_id: string; step_id: string; expected_revision: number } | undefined;
@@ -693,6 +767,7 @@ export class TaskWork {
           objective: task.objective,
           constraints: task.constraints,
           acceptance: task.acceptance,
+          ...(task.completion_gate ? { completion_gate: task.completion_gate } : {}),
           deliverables: task.deliverables,
           limits: task.limits,
           active_step_id: task.steps.find((s) => s.state === 'running')?.id ?? null,

package/src/tool-identity.ts

@@ -0,0 +1,110 @@
+import { spawnSync } from 'node:child_process';
+import { userInfo } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { ServiceError } from './protocol.js';
+import type { LocalEdit } from './local-edits.js';
+
+/**
+ * The OS identity that agent-initiated local commands and file effects run as.
+ * `service-user` is the single-user default; `tools-user` switches through a
+ * runas-restricted `sudo -n -u <user>` rule so the daemon needs no capability.
+ */
+export interface ToolIdentity {
+  mode: 'service-user' | 'tools-user';
+  user: string;
+  uid: number;
+  /** argv prefix that runs a program as the tool identity; empty for service-user. */
+  prefix: string[];
+  warning: string | null;
+}
+export const sharedUserWarning = (user: string) =>
+  `Tool execution runs as ${user}, the same OS user that holds the provider credential. Set --tools-user to separate them.`;
+
+export function serviceToolIdentity(): ToolIdentity {
+  const user = userInfo().username;
+  return {
+    mode: 'service-user',
+    user,
+    uid: process.getuid?.() ?? -1,
+    prefix: [],
+    warning: sharedUserWarning(user),
+  };
+}
+
+const run = (argv: string[], input?: string) =>
+  spawnSync(argv[0]!, argv.slice(1), {
+    env: { PATH: '/usr/local/bin:/usr/bin:/bin', LANG: 'C' },
+    input,
+    encoding: 'utf8',
+    timeout: 10000,
+    killSignal: 'SIGKILL',
+    maxBuffer: 1 << 20,
+  });
+
+/** Fail closed unless the tools user exists, is reachable without a password, and cannot read state. */
+export function probeToolsUser(
+  user: string,
+  stateDir: string,
+  prefix = ['sudo', '-n', '-u', user, '--'],
+): ToolIdentity {
+  if (!/^[a-z_][a-z0-9_-]{0,31}$/.test(user))
+    throw new Error('--tools-user must be a plain Unix user name');
+  if (process.platform !== 'linux' && prefix[0] === 'sudo')
+    throw new Error('--tools-user is supported on Linux hosts only');
+  const id = run([...prefix, '/usr/bin/id', '-u']);
+  const uid = Number(String(id.stdout).trim());
+  if (id.status !== 0 || !Number.isSafeInteger(uid))
+    throw new Error(
+      `Cannot run as tools user ${user} (sudo -n -u ${user} failed); see docs/security.md host setup`,
+    );
+  if (uid === 0 || uid === process.getuid?.())
+    throw new Error('The tools user must be an unprivileged user distinct from the service user');
+  if (run([...prefix, '/usr/bin/test', '-r', stateDir]).status === 0)
+    throw new Error(`Tools user ${user} can read the Salaam state directory; restrict it to 0700`);
+  return { mode: 'tools-user', user, uid, prefix, warning: null };
+}
+
+export function toolArgv(identity: ToolIdentity, argv: string[]): string[] {
+  return [...identity.prefix, ...argv];
+}
+
+/** Kill a tool process group owned by the tools user; the daemon cannot signal another uid. */
+export function killToolGroup(identity: ToolIdentity, pgid: number): void {
+  if (identity.mode !== 'tools-user' || !Number.isSafeInteger(pgid) || pgid < 2) return;
+  run(toolArgv(identity, ['/bin/kill', '-KILL', '--', '-' + pgid]));
+}
+
+const here = fileURLToPath(import.meta.url);
+/** Source runs (tests) use the built helper; packages ship it beside this file. */
+export const EDIT_HELPER = here.endsWith('.ts')
+  ? join(dirname(here), '..', 'dist/src/local-edit-helper.js')
+  : join(dirname(here), 'local-edit-helper.js');
+
+export interface ToolEdit extends LocalEdit {
+  remove?: boolean;
+}
+/** Apply reviewed edits as the tools user. Reports each applied path; any failure throws. */
+export function applyEditsAsTools(
+  identity: ToolIdentity,
+  root: string,
+  edits: ToolEdit[],
+  applied: (path: string) => void,
+): void {
+  if (!existsSync(EDIT_HELPER)) throw new ServiceError('tool_identity', 'Edit helper is missing');
+  const result = run(
+    toolArgv(identity, [process.execPath, EDIT_HELPER, root]),
+    JSON.stringify(edits),
+  );
+  for (const line of String(result.stdout ?? '').split('\n')) {
+    if (line.startsWith('applied ')) applied(JSON.parse(line.slice(8)) as string);
+  }
+  if (result.status !== 0)
+    throw new ServiceError(
+      'tool_identity',
+      `Edit as ${identity.user} failed: ${String(result.stderr ?? '')
+        .trim()
+        .slice(0, 400)}`,
+    );
+}

package/src/usage.ts

@@ -31,7 +31,7 @@ export class UsageLedger {
         this.store.execution.assert(session);
         this.store.taskModelAdmission?.(session, attempt, bounds?.input ?? 0, bounds?.output ?? 0);
         if (attempt) {
-          this.budget(attempt);
+          this.budget(attempt, this.store.taskAttemptRequestLimit?.(session) ?? 16);
           const changed = this.store.db
             .prepare(
               'UPDATE attempt_budgets SET spent_requests=spent_requests+1 WHERE attempt_id=? AND spent_requests+reserved_requests<limit_requests',