@superjackfruitlabs/salaam 0.0.3 → 0.0.4

package/src/agent-profiles.ts

@@ -208,6 +208,54 @@ export class AgentProfiles {
     if (!profile) throw new ServiceError('not_found', 'Agent profile not found', 404);
     return profile;
   }
+  /**
+   * The task critic's grant (item 8): always the built-in salaam/reviewer, never another profile,
+   * with no facts. It is granted under the work admission, not by an operator controller, and
+   * only while the caller's authorize holds (the admitted plan declares a critic). The reviewer
+   * reads only the immutable snapshot it is given and can only report findings.
+   */
+  async admitCritic(session: string, request: string, authorize: () => void): Promise<AgentGrant> {
+    const profileId = 'salaam/reviewer';
+    const profile = this.inspect(session, profileId);
+    const expectedDigest = digest(profile);
+    const input = { kind: 'critic-admit', session, profileId, expectedDigest };
+    const saved = this.store.cachedRequest<AgentGrant>('task-critic', request, input);
+    if (saved) return saved;
+    if (!BUILTIN_PROFILES.some((p) => p.id === profileId && digest(p) === expectedDigest))
+      throw new ServiceError('profile_changed', 'The critic must be the built-in reviewer');
+    const prepared = await this.prepareRoute(this.route, session);
+    return this.store.request('task-critic', request, input, () => {
+      authorize();
+      const grant: AgentGrant = {
+        schema_version: 1,
+        id: randomUUID(),
+        owner_session: session,
+        profile,
+        profile_digest: expectedDigest,
+        route: prepared.route,
+        output_cap: prepared.output_cap,
+        facts: [],
+      };
+      this.store.db
+        .prepare(
+          'INSERT INTO agent_grants(id,owner_session,profile_id,document,digest,state) VALUES (?,?,?,?,?,?)',
+        )
+        .run(grant.id, session, profileId, canonical(grant), digest(grant), 'active');
+      this.store.db
+        .prepare(
+          'INSERT OR IGNORE INTO worker_profiles(id,revision,digest,document) VALUES (?,?,?,?)',
+        )
+        .run(profile.id, profile.revision, expectedDigest, canonical(profile));
+      this.store.event(session, 'agent.admitted', {
+        grant_id: grant.id,
+        profile_id: profileId,
+        profile_digest: expectedDigest,
+        route: prepared.route,
+        critic: true,
+      });
+      return grant;
+    });
+  }
   async admit(
     session: string,
     request: string,

package/src/agentpod-authority.ts

@@ -8,10 +8,12 @@ import {
   writeFileSync,
   fsyncSync,
   realpathSync,
+  mkdirSync,
 } from 'node:fs';
 import { join } from 'node:path';
 import type { Store } from './store.js';
-import { canonical, digest, ServiceError, object, integer } from './protocol.js';
+import { canonical, digest, ServiceError, object, integer, type Session } from './protocol.js';
+import { forkPiSession } from './pi-sessions.js';
 import {
   agentpodBinding,
   AGENTPOD_LEASE_MS,
@@ -80,10 +82,45 @@ export function readAgentPodPins(configPath: string, state: string): AgentPodPin
 }
 
 /** A local node admission, not an Accounts token issuer or a provider login. */
+/** An agent's standing "Always allow" rule (approval scopes). v1 knows one scope: workspace
+ * writes, never deletes, hidden paths, commands, network or anything outside the workspace. */
+export interface ApprovalRule {
+  id: string;
+  scope: 'workspace-write';
+  set_by: string;
+}
+const ruleId = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/** Closed: 1 to 16 rules, exact keys, a known scope, unique ids. Absent means none. */
+export function approvalRules(value: unknown): ApprovalRule[] {
+  if (value === undefined) return [];
+  const bad = () => {
+    throw new ServiceError('invalid_approval_rules', 'Malformed approval rules', 400);
+  };
+  if (!Array.isArray(value) || value.length < 1 || value.length > 16) bad();
+  const rules = (value as unknown[]).map((r) => {
+    if (!r || typeof r !== 'object' || Array.isArray(r)) bad();
+    const v = r as Record<string, unknown>;
+    if (
+      Object.keys(v).sort().join(',') !== 'id,scope,set_by' ||
+      typeof v.id !== 'string' ||
+      !ruleId.test(v.id) ||
+      v.scope !== 'workspace-write' ||
+      typeof v.set_by !== 'string' ||
+      v.set_by.length < 1 ||
+      v.set_by.length > 128 ||
+      /[\u0000-\u001f\u007f]/.test(v.set_by)
+    )
+      bad();
+    return { id: v.id as string, scope: 'workspace-write' as const, set_by: v.set_by as string };
+  });
+  if (new Set(rules.map((r) => r.id)).size !== rules.length) bad();
+  return rules.sort((a, b) => a.id.localeCompare(b.id));
+}
 export class AgentPodAuthority {
   readonly boot = randomUUID();
   readonly pins: AgentPodPins;
   private key: Buffer;
+  private readonly stateDir: string;
   constructor(
     readonly store: Store,
     state: string,
@@ -92,6 +129,7 @@ export class AgentPodAuthority {
     readonly ownedResourcesStopped: (session: string) => boolean = () => true,
   ) {
     this.pins = readAgentPodPins(configPath, state);
+    this.stateDir = state;
     const keyPath = join(state, 'agentpod-control-key');
     try {
       const fd = openSync(keyPath, 'wx', 0o600);
@@ -112,6 +150,9 @@ export class AgentPodAuthority {
     }
     this.key = privateBytes(keyPath);
     if (this.key.length !== 32) throw Error('Invalid AgentPod control key');
+    store.db.exec(
+      'CREATE TABLE IF NOT EXISTS agentpod_approval_rules(admission_id TEXT NOT NULL,rule_id TEXT NOT NULL,scope TEXT NOT NULL,set_by TEXT NOT NULL,revoked_at TEXT,PRIMARY KEY(admission_id,rule_id))',
+    );
     store.agentpodAuthorityCheck = (session) => this.assert(this.bySession(session));
     store.requireAgentPodAuthority = true;
   }
@@ -158,6 +199,19 @@ export class AgentPodAuthority {
       );
     return remaining;
   }
+  /** The session's pinned approval rules that no renewal has revoked. */
+  approvalRules(session: string): ApprovalRule[] {
+    return this.store.db
+      .prepare(
+        'SELECT r.rule_id AS id,r.scope,r.set_by FROM agentpod_approval_rules r JOIN agentpod_admissions a ON a.id=r.admission_id WHERE a.session_id=? AND r.revoked_at IS NULL ORDER BY r.rule_id',
+      )
+      .all(session)
+      .map((r) => ({
+        id: String(r.id),
+        scope: 'workspace-write' as const,
+        set_by: String(r.set_by),
+      }));
+  }
   private checked(input: unknown): AgentPodBinding {
     const b = agentpodBinding(input);
     for (const k of Object.keys(this.pins) as (keyof AgentPodPins)[])
@@ -247,12 +301,30 @@ export class AgentPodAuthority {
     this.assert(row);
     return { session_id: row.session_id, binding: JSON.parse(row.binding) };
   }
-  admit(input: unknown, request: string) {
+  /**
+   * `continueFrom` names an earlier interactive admission (its hub session id) whose conversation
+   * this new admission carries on. The earlier execution stays revoked: the new admission gets a
+   * NEW session, its own lease and its own authority, seeded with a branch of the old Pi
+   * transcript and its entries. Only a revoked, stopped and reconciled interactive admission for
+   * the same organization, station, occupant and workspace can be continued, and only once.
+   */
+  admit(input: unknown, request: string, continueFrom?: string, rulesInput?: unknown) {
     const b = this.checked(input);
+    const rules = approvalRules(rulesInput);
+    if (
+      continueFrom !== undefined &&
+      (typeof continueFrom !== 'string' || !continueFrom || continueFrom.length > 128)
+    )
+      throw new ServiceError('invalid_continuation', 'continue_from must be a hub session id', 400);
     const admitted = this.store.request(
       'agentpod-node',
       request,
-      { kind: 'admit', binding: b },
+      {
+        kind: 'admit',
+        binding: b,
+        ...(continueFrom === undefined ? {} : { continue_from: continueFrom }),
+        ...(rules.length ? { approval_rules: rules } : {}),
+      },
       () => {
         const old = this.store.db
           .prepare('SELECT id FROM agentpod_admissions WHERE hub_session_id=?')
@@ -303,17 +375,56 @@ export class AgentPodAuthority {
             'INSERT INTO agentpod_station_epochs VALUES (?,?,?) ON CONFLICT(station_id) DO UPDATE SET occupancy_epoch=excluded.occupancy_epoch,principal_id=excluded.principal_id',
           )
           .run(b.station_id, b.occupancy_epoch, b.principal_id);
+        const prior = continueFrom === undefined ? undefined : this.continuable(b, continueFrom);
         const session = randomUUID(),
           id = randomUUID();
-        this.store.db
-          .prepare('INSERT INTO sessions(id,cwd,pi_session_id) VALUES (?,?,?)')
-          .run(session, b.workspace, session);
-        this.store.event(
-          session,
-          'session.created',
-          { cwd: b.workspace, authority: 'agentpod-v1' },
-          request,
-        );
+        if (prior) {
+          const source = this.store.session(prior.session_id);
+          const file = source.pi_session_file
+            ? (() => {
+                const dir = join(this.stateDir, 'workers', session, 'sessions');
+                mkdirSync(dir, { recursive: true, mode: 0o700 });
+                return forkPiSession(source.pi_session_file, source.cwd, dir, session);
+              })()
+            : null;
+          this.store.db
+            .prepare(
+              'INSERT INTO sessions(id,cwd,pi_session_id,pi_session_file,pi_cursor,pi_leaf) VALUES (?,?,?,?,?,?)',
+            )
+            .run(session, b.workspace, session, file, source.pi_cursor, source.pi_leaf);
+          this.store.event(
+            session,
+            'session.created',
+            { cwd: b.workspace, authority: 'agentpod-v1', forked_from: prior.session_id },
+            request,
+          );
+          this.store.db
+            .prepare(
+              'INSERT INTO pi_entries SELECT ?,entry_id,payload FROM pi_entries WHERE session_id=?',
+            )
+            .run(session, prior.session_id);
+          this.store.event(
+            session,
+            'session.forked',
+            {
+              parent: prior.session_id,
+              parent_revision: source.revision,
+              leaf: source.pi_leaf,
+              cursor: source.pi_cursor,
+            },
+            request,
+          );
+        } else {
+          this.store.db
+            .prepare('INSERT INTO sessions(id,cwd,pi_session_id) VALUES (?,?,?)')
+            .run(session, b.workspace, session);
+          this.store.event(
+            session,
+            'session.created',
+            { cwd: b.workspace, authority: 'agentpod-v1' },
+            request,
+          );
+        }
         this.store.db
           .prepare(
             'INSERT INTO agentpod_admissions(id,session_id,hub_session_id,run_key,binding,digest,pins_digest,expires_at) VALUES (?,?,?,?,?,?,?,?)',
@@ -328,10 +439,20 @@ export class AgentPodAuthority {
             digest(this.pins),
             Date.now() + AGENTPOD_LEASE_MS,
           );
+        // The agent's standing rules, pinned for this run; a renewal may add or revoke one.
+        for (const r of rules)
+          this.store.db
+            .prepare('INSERT INTO agentpod_approval_rules VALUES (?,?,?,?,NULL)')
+            .run(id, r.id, r.scope, r.set_by);
         this.store.event(
           session,
           'agentpod.admitted',
-          { admission_id: id, binding_digest: digest(b), binding: b },
+          {
+            admission_id: id,
+            binding_digest: digest(b),
+            binding: b,
+            ...(prior ? { continued_from: continueFrom, continued_admission: prior.id } : {}),
+          },
           request,
         );
         return { admission_id: id };
@@ -340,13 +461,14 @@ export class AgentPodAuthority {
     const row = this.row(admitted.admission_id);
     return { ...this.status(row), token: this.token(row.id) };
   }
-  renew(input: unknown, request: string, sequence: number) {
+  renew(input: unknown, request: string, sequence: number, rulesInput?: unknown) {
     const b = this.checked(input);
     integer(sequence, 'lease_sequence');
+    const rules = approvalRules(rulesInput);
     return this.store.request(
       'agentpod-node',
       request,
-      { kind: 'renew', binding: b, sequence },
+      { kind: 'renew', binding: b, sequence, ...(rules.length ? { approval_rules: rules } : {}) },
       () => {
         const row = this.bound(b);
         if (
@@ -375,6 +497,44 @@ export class AgentPodAuthority {
             performance.now() + AGENTPOD_LEASE_MS,
             row.id,
           );
+        // Revocation is immediate: a pinned rule the hub no longer lists ends now, for good.
+        const listed = new Set(rules.map((r) => r.id));
+        for (const pinned of this.store.db
+          .prepare(
+            'SELECT rule_id FROM agentpod_approval_rules WHERE admission_id=? AND revoked_at IS NULL',
+          )
+          .all(row.id)) {
+          if (listed.has(String(pinned.rule_id))) continue;
+          this.store.db
+            .prepare(
+              'UPDATE agentpod_approval_rules SET revoked_at=? WHERE admission_id=? AND rule_id=?',
+            )
+            .run(new Date().toISOString(), row.id, String(pinned.rule_id));
+          this.store.event(
+            row.session_id,
+            'approval_rule.revoked',
+            { admission_id: row.id, rule_id: pinned.rule_id },
+            request,
+          );
+        }
+        // A rule the hub newly lists joins the run now (operator ruling 2026-10-28: a person who
+        // chose "Always allow" mid-run is not asked again). One this run already holds, or held
+        // and lost to revocation, is left as it is: revocation stays final for the run.
+        for (const r of rules) {
+          const known = this.store.db
+            .prepare('SELECT 1 FROM agentpod_approval_rules WHERE admission_id=? AND rule_id=?')
+            .get(row.id, r.id);
+          if (known) continue;
+          this.store.db
+            .prepare('INSERT INTO agentpod_approval_rules VALUES (?,?,?,?,NULL)')
+            .run(row.id, r.id, r.scope, r.set_by);
+          this.store.event(
+            row.session_id,
+            'approval_rule.added',
+            { admission_id: row.id, rule_id: r.id, scope: r.scope, set_by: r.set_by },
+            request,
+          );
+        }
         this.store.event(
           row.session_id,
           'agentpod.renewed',
@@ -385,6 +545,59 @@ export class AgentPodAuthority {
       },
     );
   }
+  /** The earlier admission a new interactive admission may continue, or a refusal. */
+  private continuable(b: AgentPodBinding, continueFrom: string): Admission {
+    if (b.run.source !== 'agentpod')
+      throw new ServiceError(
+        'continuation_refused',
+        'Only an interactive admission can continue an earlier conversation',
+      );
+    const row = this.store.db
+      .prepare('SELECT id FROM agentpod_admissions WHERE hub_session_id=?')
+      .get(continueFrom);
+    if (!row)
+      throw new ServiceError(
+        'admission_not_found',
+        'The session to continue has no admission',
+        404,
+      );
+    const prior = this.row(String(row.id));
+    const before = JSON.parse(prior.binding) as AgentPodBinding;
+    if (
+      prior.binding !== canonical(before) ||
+      prior.digest !== digest(before) ||
+      before.run.source !== 'agentpod' ||
+      before.organization_id !== b.organization_id ||
+      before.station_id !== b.station_id ||
+      before.principal_id !== b.principal_id ||
+      before.workspace !== b.workspace ||
+      before.hub_session_id === b.hub_session_id
+    )
+      throw new ServiceError(
+        'continuation_refused',
+        'Only the same station, occupant and workspace can continue this conversation',
+      );
+    const status = this.status(prior);
+    if (
+      prior.state !== 'revoked' ||
+      !status.revoked ||
+      !status.owned_execution_stopped ||
+      status.unresolved_operations.length
+    )
+      throw new ServiceError(
+        'execution_unconfirmed',
+        'The conversation to continue must be revoked, stopped and reconciled first',
+      );
+    if (
+      this.store.db
+        .prepare(
+          "SELECT 1 FROM events WHERE kind='agentpod.admitted' AND json_extract(payload,'$.continued_admission')=? LIMIT 1",
+        )
+        .get(prior.id)
+    )
+      throw new ServiceError('already_continued', 'This conversation was already continued');
+    return prior;
+  }
   revoke(input: unknown, request: string, reason: string) {
     const b = this.checked(input);
     this.store.request('agentpod-node', request, { kind: 'revoke', binding: b, reason }, () => {
@@ -482,9 +695,15 @@ export class AgentPodAuthority {
       this.assert(row);
       authorized = true;
     } catch {}
+    const continued = this.store.db
+      .prepare(
+        "SELECT json_extract(payload,'$.continued_from') AS source FROM events WHERE session_id=? AND kind='agentpod.admitted' LIMIT 1",
+      )
+      .get(row.session_id) as { source: string | null } | undefined;
     return {
       admission_id: row.id,
       session_id: row.session_id,
+      continued_from: continued?.source ?? null,
       binding: JSON.parse(row.binding) as AgentPodBinding,
       binding_digest: row.digest,
       lease_sequence: row.lease_sequence,

package/src/agentpod-default-config.ts

@@ -0,0 +1,16 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * The AgentPod pins a node operator drops for this user, used when
+ * `service start` names no --agentpod-config. Without it a daemon an AgentPod
+ * node expects to bind starts unbound and the node never detects a station.
+ */
+export function defaultAgentPodConfig(
+  env: NodeJS.ProcessEnv,
+  exists: (path: string) => boolean,
+): string | undefined {
+  const base = env.XDG_CONFIG_HOME || join(env.HOME || homedir(), '.config');
+  const path = join(base, 'salaam', 'agentpod-pins.json');
+  return exists(path) ? path : undefined;
+}

package/src/agentpod-work-decision-protocol.ts

@@ -12,7 +12,27 @@ export interface WorkDecision {
   approval_revision: number;
   expires_at: number;
   question: string;
-  options: [{ id: 'approve'; title: string }, { id: 'deny'; title: string }];
+  /** Readable approvals: what is being approved, as structured fields. */
+  detail?: WorkDecisionDetail;
+  /** approve, [approve-run], [always], deny, in that order. "Always allow" (operator ruling
+   * 2026-10-28) is a workspace owner's or admin's choice only: `requires` says so to the board, and
+   * the hub checks the answerer's role and sets the standing rule before it forwards the answer. */
+  options: WorkDecisionOption[];
+}
+export type WorkDecisionOption =
+  | { id: 'approve' | 'approve-run' | 'deny'; title: string }
+  | { id: 'always'; title: string; requires: 'workspace-admin' };
+export interface WorkDecisionDetail {
+  version: 1;
+  summary: string;
+  reason: string | null;
+  files: {
+    path: string;
+    change: 'create' | 'edit' | 'delete';
+    bytes: number | null;
+    preview: string | null;
+  }[];
+  digest: string;
 }
 export interface WorkDecisionAnswer {
   version: 1;
@@ -20,7 +40,7 @@ export interface WorkDecisionAnswer {
   decision: WorkDecision;
   decision_digest: string;
   elicitation_id: string;
-  option_id: 'approve' | 'deny';
+  option_id: 'approve' | 'approve-run' | 'always' | 'deny';
   answered_by: string;
   answered_at: string;
 }
@@ -57,7 +77,9 @@ export function workDecision(value: unknown): WorkDecision {
     'expires_at',
     'question',
     'options',
+    ...('detail' in v ? ['detail'] : []),
   ]);
+  if ('detail' in v) workDecisionDetail(v.detail);
   if (
     v.version !== 1 ||
     !['request_id', 'work_request_id', 'task_id', 'operation_id', 'approval_id'].every((k) =>
@@ -71,13 +93,25 @@ export function workDecision(value: unknown): WorkDecision {
     ) ||
     !text(v.question, 8192) ||
     !Array.isArray(v.options) ||
-    v.options.length !== 2
+    ![2, 3, 4].includes(v.options.length)
+  )
+    fail();
+  // approve, [approve-run], [always], deny. Nothing else, in that order.
+  const ids = v.options.map((o) => String(object(o).id));
+  if (
+    ![
+      'approve,deny',
+      'approve,approve-run,deny',
+      'approve,always,deny',
+      'approve,approve-run,always,deny',
+    ].includes(ids.join(','))
   )
     fail();
-  for (let i = 0; i < 2; i++) {
-    const opt = object(v.options[i]);
-    keys(opt, ['id', 'title']);
-    if (opt.id !== ['approve', 'deny'][i] || !text(opt.title, 256)) fail();
+  for (const value of v.options) {
+    const opt = object(value);
+    keys(opt, opt.id === 'always' ? ['id', 'title', 'requires'] : ['id', 'title']);
+    if (!text(opt.title, 256) || (opt.id === 'always' && opt.requires !== 'workspace-admin'))
+      fail();
   }
   return v as unknown as WorkDecision;
 }
@@ -101,7 +135,7 @@ export function workDecisionAnswer(value: unknown): WorkDecisionAnswer {
     !/^[a-f0-9]{64}$/.test(v.decision_digest) ||
     !text(v.elicitation_id, 128) ||
     !/^elc_[A-Za-z0-9]{6,}$/.test(v.elicitation_id) ||
-    !['approve', 'deny'].includes(String(v.option_id)) ||
+    !['approve', 'approve-run', 'always', 'deny'].includes(String(v.option_id)) ||
     !text(v.answered_by, 128) ||
     typeof v.answered_at !== 'string' ||
     !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d+)?Z$/.test(v.answered_at) ||
@@ -111,3 +145,30 @@ export function workDecisionAnswer(value: unknown): WorkDecisionAnswer {
     fail();
   return v as unknown as WorkDecisionAnswer;
 }
+
+function workDecisionDetail(value: unknown): WorkDecisionDetail {
+  const d = object(value);
+  keys(d, ['version', 'summary', 'reason', 'files', 'digest']);
+  if (
+    d.version !== 1 ||
+    !text(d.summary, 200) ||
+    (d.reason !== null && !text(d.reason, 300)) ||
+    typeof d.digest !== 'string' ||
+    !/^[a-f0-9]{64}$/.test(d.digest) ||
+    !Array.isArray(d.files) ||
+    d.files.length > 16
+  )
+    fail();
+  for (const f of d.files as unknown[]) {
+    const file = object(f);
+    keys(file, ['path', 'change', 'bytes', 'preview']);
+    if (
+      !text(file.path, 512) ||
+      !['create', 'edit', 'delete'].includes(String(file.change)) ||
+      (file.bytes !== null && (!Number.isSafeInteger(file.bytes) || Number(file.bytes) < 0)) ||
+      (file.preview !== null && (typeof file.preview !== 'string' || file.preview.length > 1200))
+    )
+      fail();
+  }
+  return d as unknown as WorkDecisionDetail;
+}