@superjackfruitlabs/salaam 0.0.3 → 0.0.4

package/src/station-checkpoints.ts

@@ -0,0 +1,183 @@
+import type { Store } from './store.js';
+import type { WorkTask } from './task-work.js';
+import { digest, ServiceError } from './protocol.js';
+
+/**
+ * Checkpoints of a station task, derived from its own recorded writes (item 11). Each completed
+ * step ends at a checkpoint: the tree after that step's last returned station patch. A file's
+ * content at a checkpoint is known only from the run's own patches; a file that existed before
+ * the run and was first written after the checkpoint has no recorded earlier bytes, so it is
+ * "unknown" there and cannot be restored. Read-only: nothing here changes the workspace.
+ */
+export interface StationCheckpoint {
+  id: string;
+  step_id: string;
+  step_key: string;
+  tree_digest: string;
+  at: number; // the last patch call rowid at the checkpoint (0: before any write)
+  files_changed: string[];
+}
+type Patch = {
+  rowid: number;
+  path: string;
+  content: string | null;
+  expected_hash: string | null;
+  before_tree: string;
+  tree: string;
+  sha256: string | null;
+};
+export type FileAtCheckpoint =
+  { state: 'content'; content: string } | { state: 'absent' } | { state: 'unknown' };
+/** A file as the workspace holds it now, read through the protected helper's closed verbs. */
+export type FileNow =
+  | { state: 'content'; content: string; sha256: string }
+  | { state: 'absent' }
+  | { state: 'unreadable' };
+/** The live workspace: its tree digest now, and each file's bytes now. */
+export interface LiveTree {
+  tree: string;
+  file(path: string): Promise<FileNow>;
+}
+
+export class StationCheckpoints {
+  constructor(private readonly store: Store) {}
+  private patches(session: string): Patch[] {
+    return this.store.db
+      .prepare(
+        "SELECT rowid,args_json,result_json,attempt_id FROM station_calls WHERE session_id=? AND kind='patch' AND state='returned' ORDER BY rowid",
+      )
+      .all(session)
+      .map((r) => {
+        const args = JSON.parse(String(r.args_json)),
+          result = JSON.parse(String(r.result_json));
+        return {
+          rowid: Number(r.rowid),
+          path: String(args.path),
+          content: typeof args.content === 'string' ? args.content : null,
+          expected_hash: typeof args.expected_hash === 'string' ? args.expected_hash : null,
+          before_tree: String(result.before_tree_digest),
+          tree: String(result.tree_digest),
+          sha256: typeof result.sha256 === 'string' ? result.sha256 : null,
+          attempt: String(r.attempt_id),
+        } as Patch & { attempt: string };
+      });
+  }
+  list(task: WorkTask): StationCheckpoint[] {
+    const patches = this.patches(task.session_id) as (Patch & { attempt: string })[];
+    const attemptsOf = (step: string) =>
+      new Set(
+        this.store.db
+          .prepare('SELECT attempt_id FROM task_step_attempts WHERE step_id=?')
+          .all(step)
+          .map((r) => String(r.attempt_id)),
+      );
+    const out: StationCheckpoint[] = [];
+    let at = 0,
+      tree = patches[0]?.before_tree ?? '';
+    for (const step of task.steps.filter((s) => s.state === 'completed')) {
+      const mine = patches.filter((p) => attemptsOf(step.id).has(p.attempt));
+      if (mine.length) {
+        at = Math.max(at, ...mine.map((p) => p.rowid));
+        tree = patches.find((p) => p.rowid === at)!.tree;
+      }
+      out.push({
+        id: digest({ task: task.id, plan_revision: task.plan_revision, step: step.id, at, tree }),
+        step_id: step.id,
+        step_key: step.key,
+        tree_digest: tree,
+        at,
+        files_changed: [...new Set(mine.map((p) => p.path))].sort(),
+      });
+    }
+    return out;
+  }
+  get(task: WorkTask, id: string): StationCheckpoint {
+    const found = this.list(task).find((c) => c.id === id);
+    if (!found) throw new ServiceError('not_found', 'No such checkpoint for this task', 404);
+    return found;
+  }
+  /** A path's content at a checkpoint, from the run's own patches only. */
+  fileAt(task: WorkTask, at: number, path: string): FileAtCheckpoint {
+    const patches = this.patches(task.session_id).filter((p) => p.path === path);
+    const before = patches.filter((p) => p.rowid <= at).at(-1);
+    if (before)
+      return before.content === null
+        ? { state: 'absent' }
+        : { state: 'content', content: before.content };
+    const first = patches.find((p) => p.rowid > at);
+    return first && first.expected_hash === null ? { state: 'absent' } : { state: 'unknown' };
+  }
+  /**
+   * What restoring this checkpoint would do, against the LIVE workspace (never the run's own
+   * receipts alone): every path this run wrote is read as it is now, so a change made outside the
+   * run since (an edit, a deletion, a file put back) shows as what the restore would undo. The
+   * restore digest binds the live tree, so a restore refuses a workspace that moved after review.
+   * Files this run never wrote are left as they are; `drift` says when the tree moved outside it.
+   */
+  async diff(task: WorkTask, id: string, live: LiveTree) {
+    const checkpoint = this.get(task, id);
+    const patches = this.patches(task.session_id);
+    const recorded = patches.at(-1)?.tree ?? checkpoint.tree_digest;
+    const paths = [...new Set(patches.map((p) => p.path))].sort();
+    const files = [];
+    for (const path of paths) {
+      const now = await live.file(path);
+      const then = this.fileAt(task, checkpoint.at, path);
+      const change =
+        now.state === 'unreadable' || then.state === 'unknown'
+          ? ('not_restorable' as const)
+          : then.state === 'absent'
+            ? now.state === 'absent'
+              ? ('unchanged' as const)
+              : ('delete' as const)
+            : now.state === 'absent'
+              ? ('bring_back' as const)
+              : now.content === then.content
+                ? ('unchanged' as const)
+                : ('revert' as const);
+      files.push({
+        path,
+        current: now.state === 'content' ? now.content : null,
+        current_state: now.state,
+        at_checkpoint: then,
+        change,
+        expected_hash: now.state === 'content' ? now.sha256 : null,
+      });
+    }
+    const shown = files.filter((f) => f.change !== 'unchanged');
+    const restore_digest = digest({
+      task: task.id,
+      plan_revision: task.plan_revision,
+      checkpoint: checkpoint.id,
+      checkpoint_tree: checkpoint.tree_digest,
+      recorded_tree: recorded,
+      current_tree: live.tree,
+      files: shown.map((f) => ({
+        path: f.path,
+        change: f.change,
+        target: f.at_checkpoint,
+        expected: f.expected_hash,
+      })),
+    });
+    return {
+      checkpoint,
+      current_tree: live.tree,
+      recorded_tree: recorded,
+      drift: live.tree !== recorded,
+      restore_digest,
+      files: shown.map(({ expected_hash: _, ...f }) => f),
+      writes: shown
+        .filter((f) => ['revert', 'delete', 'bring_back'].includes(f.change))
+        .map((f) => ({
+          path: f.path,
+          content: f.at_checkpoint.state === 'content' ? f.at_checkpoint.content : null,
+          expected_hash: f.expected_hash,
+        })),
+    };
+  }
+  /** Item 11b: exactly what a restore of this checkpoint writes, and the digest that binds it. */
+  async restorePlan(task: WorkTask, id: string, live: LiveTree) {
+    const { restore_digest, current_tree, writes, checkpoint } = await this.diff(task, id, live);
+    return { restore_digest, current_tree, writes, checkpoint };
+  }
+}

package/src/station-config.ts

@@ -28,6 +28,8 @@ export interface StationConfig {
   runtime_root: string;
   runtime_fingerprint: string;
   runtime_image_digest: string;
+  /** OS user the agent's local tools run as (salaam --tools-user). Optional. */
+  tools_user?: string;
 }
 const hashShape = /^[a-f0-9]{64}$/;
 export const stationHash = (bytes: Uint8Array): string =>
@@ -149,9 +151,15 @@ export function readStationConfig(
 ): StationConfig {
   try {
     const v = object(JSON.parse(stationPrivateFile(path, 16384).toString('utf8')));
+    const keys = Object.keys(v)
+      .filter((k) => k !== 'tools_user')
+      .sort()
+      .join(',');
     if (
-      Object.keys(v).sort().join(',') !==
+      keys !==
         'files,kind,runtime_fingerprint,runtime_image_digest,runtime_root,systemctl,systemd_run,version,workspace,workspace_identity' ||
+      (Object.hasOwn(v, 'tools_user') &&
+        (typeof v.tools_user !== 'string' || !/^[a-z_][a-z0-9_-]{0,31}$/.test(v.tools_user))) ||
       v.version !== 1 ||
       v.kind !== 'linux-systemd-station-v1' ||
       v.workspace !== workspace ||
@@ -174,6 +182,7 @@ export function readStationConfig(
       runtime_root: v.runtime_root,
       runtime_fingerprint: v.runtime_fingerprint,
       runtime_image_digest: v.runtime_image_digest,
+      ...(Object.hasOwn(v, 'tools_user') ? { tools_user: v.tools_user as string } : {}),
     };
     if (
       workspace

package/src/station-files.ts

@@ -22,9 +22,14 @@ export function stationFileResult(
   };
   const fields = keys[String(request.action)];
   if (!fields) bad();
+  // A new file's missing parent directories, created beneath the root, are part of its effect.
+  const extra =
+    request.action === 'patch' && 'created_directories' in v ? ['created_directories'] : [];
   if (
     Object.keys(v).sort().join(',') !==
-      ['version', 'ok', 'tree_digest', 'files', 'root_identity', ...fields!].sort().join(',') ||
+      ['version', 'ok', 'tree_digest', 'files', 'root_identity', ...fields!, ...extra]
+        .sort()
+        .join(',') ||
     v.version !== 1 ||
     v.ok !== true ||
     v.root_identity !== request.root_identity ||
@@ -47,6 +52,8 @@ export function stationFileResult(
     )
       bad();
   }
+  if (extra.length && !createdParents(String(request.path), v.created_directories, request.content))
+    bad();
   if (request.action === 'patch') {
     if (
       v.path !== request.path ||
@@ -102,3 +109,15 @@ export function stationFileResult(
   }
   return v;
 }
+
+/** The created directories must be a non-empty, in-order run of the path's own
+ * ancestors ending at its parent: each one beneath the last, nothing else. Only a
+ * new file creates them. */
+function createdParents(path: string, dirs: unknown, content: unknown): boolean {
+  if (typeof content !== 'string' || !Array.isArray(dirs) || dirs.length === 0) return false;
+  const parts = path.split('/');
+  if (parts.length < 2 || parts.some((p) => p === '' || p === '.' || p === '..')) return false;
+  const ancestors = parts.slice(0, -1).map((_, i) => parts.slice(0, i + 1).join('/'));
+  const tail = ancestors.slice(ancestors.length - dirs.length);
+  return dirs.length <= ancestors.length && dirs.every((d, i) => d === tail[i]);
+}

package/src/station-task-verification.ts

@@ -1,3 +1,4 @@
+import { requiredChecks } from './task-policy.js';
 import type { Store } from './store.js';
 import type { TaskWork, WorkTask } from './task-work.js';
 import type { TaskVerification, CheckReceipt } from './task-verification.js';
@@ -163,7 +164,7 @@ export class StationTaskVerification {
   private async dispatchOwned(id: string): Promise<void> {
     const receipt = this.verification.get(id),
       task = this.tasks.get(receipt.task_id);
-    const configured = task.acceptance.find((c) => c.key === receipt.check_key);
+    const configured = requiredChecks(task).find((c) => c.key === receipt.check_key);
     if (!configured || configured.cwd !== '.') this.fail();
     const binding = this.station.ready(task.session_id);
     const validate = (inspection?: string) => {
@@ -265,6 +266,7 @@ export class StationTaskVerification {
       objective: task.objective,
       constraints: task.constraints,
       acceptance: task.acceptance,
+      ...(task.completion_gate ? { completion_gate: task.completion_gate } : {}),
       deliverables: task.deliverables,
       limits: task.limits,
       steps: task.steps.map(({ key, title, instruction, depends_on, checks }) => ({
@@ -300,7 +302,7 @@ export class StationTaskVerification {
     });
   }
   private matches(check: CheckReceipt, task: WorkTask, call: StationCall): void {
-    const configured = task.acceptance.find((c) => c.key === check.check_key);
+    const configured = requiredChecks(task).find((c) => c.key === check.check_key);
     const args = JSON.parse(call.args_json);
     if (
       check.task_id !== task.id ||
@@ -526,7 +528,8 @@ export class StationTaskVerification {
         result.root_identity !== this.station.config.workspace_identity
       )
         this.fail();
-      deliverables.push({ path, sha256: result.sha256 });
+      // The verified bytes travel with the digest; completion keeps them as an artifact.
+      deliverables.push({ path, sha256: result.sha256, content: result.content });
     }
     const final = await this.observe(
       evidence[0]!.call_id,