@superjackfruitlabs/salaam 0.0.1 → 0.0.2

package/src/a2a-protocol.ts

@@ -0,0 +1,286 @@
+import { randomUUID } from 'node:crypto';
+import { digest, canonical, ServiceError } from './protocol.js';
+import { a2aIdentity, a2aObject, type A2AObject } from './a2a-peer.js';
+
+export interface A2ACheckpoint {
+  schema_version: 1;
+  dialect: 'a2a';
+  run_id?: string;
+  worker_id: string;
+  attempt_id: string;
+  peer_id: string;
+  peer_digest: string;
+  tenant: string;
+  message_id: string;
+  task_id: string | null;
+  context_id: string | null;
+  state: 'prepared' | 'dispatching' | 'running' | 'terminal' | 'unknown';
+  prompt_digest: string;
+  cancel_requested: boolean;
+  cancel_state?: 'intent' | 'dispatching' | 'acknowledged' | 'unsupported';
+  result: A2AObject | null;
+  disclosure: { path: string; digest: string; bytes: number }[];
+  progress?: { remote_state: string | null; artifact_ids: string[] };
+  artifact_receipts?: { id: string; content_digest: string; upstream_ids: string[] }[];
+}
+export interface A2ARpc {
+  rpc(method: 'SendMessage' | 'GetTask' | 'CancelTask', params: A2AObject): Promise<A2AObject>;
+}
+export const A2A_TERMINAL = new Set([
+  'TASK_STATE_COMPLETED',
+  'TASK_STATE_FAILED',
+  'TASK_STATE_CANCELED',
+  'TASK_STATE_REJECTED',
+]);
+const STATES = new Set([
+  ...A2A_TERMINAL,
+  'TASK_STATE_SUBMITTED',
+  'TASK_STATE_WORKING',
+  'TASK_STATE_INPUT_REQUIRED',
+  'TASK_STATE_AUTH_REQUIRED',
+]);
+export function a2aTask(value: unknown): A2AObject {
+  const task = a2aObject(value);
+  a2aIdentity(task.id);
+  a2aIdentity(task.contextId);
+  const status = a2aObject(task.status);
+  if (!STATES.has(status.state) || canonical(task).length > 524288)
+    throw new ServiceError('a2a_task', 'Unsupported task state or size');
+  const artifacts = task.artifacts ?? [],
+    ids = new Set<string>();
+  if (!Array.isArray(artifacts) || artifacts.length > 64) throw Error('Unbounded remote artifacts');
+  for (const artifact of artifacts) {
+    const id = a2aIdentity(a2aObject(artifact).artifactId);
+    if (ids.has(id)) throw Error('Duplicate remote artifact identity');
+    ids.add(id);
+    validateParts(artifact.parts);
+  }
+  // Remote URIs are never fetched, even if authenticated or advertised as files.
+  for (const message of task.history ?? []) {
+    if (!['ROLE_AGENT', 'ROLE_USER'].includes(message.role))
+      throw Error('Unknown remote message role');
+    validateParts(message.parts);
+  }
+  if (status.message) validateParts(status.message.parts);
+  return structuredClone(task);
+}
+export function validateParts(value: unknown): void {
+  if (!Array.isArray(value) || value.length > 64) throw Error('Unsupported remote parts');
+  for (const raw of value) {
+    const p = a2aObject(raw),
+      keys = Object.keys(p).filter((k) => !['metadata', 'mediaType'].includes(k));
+    if (
+      keys.length !== 1 ||
+      !['text', 'data'].includes(keys[0]!) ||
+      (keys[0] === 'text' && typeof p.text !== 'string') ||
+      (keys[0] === 'data' && (!p.data || typeof p.data !== 'object' || Array.isArray(p.data)))
+    )
+      throw Error('Only bounded inline text/data parts are admitted');
+    if (
+      p.mediaType !== undefined &&
+      p.mediaType !== (keys[0] === 'text' ? 'text/plain' : 'application/json')
+    )
+      throw Error('Unsupported inline part media type');
+    if (canonical(p).length > 131072) throw Error('Remote part exceeds bound');
+  }
+}
+function terminalContent(task: A2AObject): unknown {
+  return {
+    id: task.id,
+    contextId: task.contextId,
+    status: {
+      state: task.status.state,
+      message: task.status.message
+        ? {
+            role: task.status.message.role,
+            parts: task.status.message.parts,
+            metadata: task.status.message.metadata ?? null,
+          }
+        : null,
+    },
+    artifacts: (task.artifacts ?? []).map(({ artifactId: _, ...content }: A2AObject) => content),
+    metadata: task.metadata ?? null,
+  };
+}
+/** Dispatch is never retried. Reconnect reads only the saved peer/task/context. */
+export class A2AInvocation {
+  private cp: A2ACheckpoint;
+  private broken = false;
+  constructor(
+    readonly peer: { id: string; tenant: string; digest: string; cancel: boolean; skill: string },
+    checkpoint: A2ACheckpoint,
+    readonly rpc: A2ARpc,
+    readonly save: (value: A2ACheckpoint) => undefined,
+  ) {
+    if (
+      checkpoint.dialect !== 'a2a' ||
+      checkpoint.schema_version !== 1 ||
+      checkpoint.peer_id !== peer.id ||
+      checkpoint.peer_digest !== peer.digest ||
+      checkpoint.tenant !== peer.tenant
+    )
+      throw Error('A2A peer ownership changed');
+    this.cp = structuredClone(checkpoint);
+    if (['dispatching', 'running'].includes(this.cp.state)) this.update({ state: 'unknown' });
+  }
+  view(): A2ACheckpoint {
+    return structuredClone(this.cp);
+  }
+  private update(change: Partial<A2ACheckpoint>): void {
+    if (this.broken) throw Error('A2A checkpoint control failed');
+    const next = { ...this.cp, ...change };
+    try {
+      if (this.save(structuredClone(next)) !== undefined)
+        throw Error('A2A checkpoint must commit synchronously');
+    } catch (e) {
+      this.broken = true;
+      throw e;
+    }
+    this.cp = next;
+  }
+  private accept(value: unknown): A2AObject {
+    const task = a2aTask(value);
+    if (
+      (this.cp.task_id && task.id !== this.cp.task_id) ||
+      (this.cp.context_id && task.contextId !== this.cp.context_id)
+    )
+      throw Error('Remote task/context ownership mismatch');
+    if (
+      this.cp.state === 'terminal' &&
+      digest(terminalContent(task)) !== digest(terminalContent(this.cp.result!))
+    )
+      throw Error('Conflicting remote terminal snapshot');
+    const artifact_receipts = (task.artifacts ?? []).map((artifact: A2AObject, index: number) => {
+      const { artifactId, ...content } = artifact,
+        content_digest = digest(content),
+        id = digest({ task_id: task.id, index, content_digest });
+      const old = this.cp.artifact_receipts?.find((a) => a.id === id);
+      return {
+        id,
+        content_digest,
+        upstream_ids: [...new Set([...(old?.upstream_ids ?? []), artifactId])].slice(
+          -8,
+        ) as string[],
+      };
+    });
+    this.update({
+      task_id: task.id,
+      context_id: task.contextId,
+      result: task,
+      artifact_receipts,
+      state: A2A_TERMINAL.has(task.status.state) ? 'terminal' : 'running',
+    });
+    return task;
+  }
+  async dispatch(text: string, data: A2AObject): Promise<A2AObject> {
+    if (
+      this.cp.state !== 'prepared' ||
+      this.cp.cancel_requested ||
+      this.cp.prompt_digest !== digest({ text, data })
+    )
+      throw Error('A2A invocation cannot dispatch again');
+    this.update({ state: 'dispatching' });
+    try {
+      const result = await this.rpc.rpc('SendMessage', {
+        message: {
+          messageId: this.cp.message_id,
+          role: 'ROLE_USER',
+          parts: [{ text }, { data }],
+          metadata: { 'salaam.skill': this.peer.skill },
+        },
+        configuration: {
+          acceptedOutputModes: ['text/plain', 'application/json'],
+          returnImmediately: true,
+          historyLength: 0,
+        },
+      });
+      if (!result.task || result.message) throw Error('A durable remote task receipt is required');
+      return this.accept(result.task);
+    } catch (e) {
+      this.update({ state: 'unknown' });
+      throw e;
+    }
+  }
+  async inspect(): Promise<A2AObject> {
+    if (!this.cp.task_id || !this.cp.context_id || this.broken)
+      throw Error('Remote acceptance identity is unknown; prompt will not be resent');
+    const result = await this.rpc.rpc('GetTask', { id: this.cp.task_id, historyLength: 0 });
+    return this.accept(result);
+  }
+  /** Stream chunks are tentative. Reconnect always reconciles an authoritative task snapshot. */
+  observe(raw: unknown): void {
+    const event = a2aObject(raw),
+      keys = Object.keys(event);
+    if (keys.length !== 1 || !['task', 'statusUpdate', 'artifactUpdate'].includes(keys[0]!))
+      throw new ServiceError('a2a_identity', 'Unsupported stream payload');
+    const value = a2aObject(event[keys[0]!]);
+    if (
+      (keys[0] === 'task' ? value.id : value.taskId) !== this.cp.task_id ||
+      value.contextId !== this.cp.context_id
+    )
+      throw new ServiceError('a2a_identity', 'Unowned stream task/context');
+    const progress = structuredClone(this.cp.progress ?? { remote_state: null, artifact_ids: [] });
+    if (keys[0] === 'task') {
+      const task = a2aTask(value);
+      progress.remote_state = task.status.state;
+      progress.artifact_ids = task.artifacts?.map((a: A2AObject) => a.artifactId) ?? [];
+    } else if (keys[0] === 'statusUpdate') {
+      if (!STATES.has(value.status?.state))
+        throw new ServiceError('a2a_identity', 'Unknown stream state');
+      progress.remote_state = value.status.state;
+    } else {
+      a2aIdentity(value.artifact?.artifactId);
+      validateParts(value.artifact.parts);
+      if (!progress.artifact_ids.includes(value.artifact.artifactId))
+        progress.artifact_ids.push(value.artifact.artifactId);
+      if (progress.artifact_ids.length > 64)
+        throw new ServiceError('a2a_identity', 'Unbounded stream artifacts');
+    }
+    if (this.cp.state !== 'terminal') this.update({ progress });
+  }
+  async cancel(): Promise<void> {
+    if (this.cp.state === 'terminal') return;
+    this.update({ cancel_requested: true, cancel_state: 'intent' });
+    if (!this.cp.task_id) throw Error('Unknown remote acceptance cannot be canceled safely');
+    await this.inspect();
+    if (this.view().state === 'terminal') return;
+    if (!this.peer.cancel) {
+      this.update({ cancel_state: 'unsupported' });
+      if (this.view().state !== 'terminal')
+        throw Error('Peer cancellation is unsupported; remote stop remains unconfirmed');
+      return;
+    }
+    this.update({ cancel_state: 'dispatching' });
+    const task = await this.rpc.rpc('CancelTask', { id: this.cp.task_id });
+    this.accept(task);
+    this.update({ cancel_state: 'acknowledged' });
+    if (this.view().state !== 'terminal')
+      throw Error('Cancellation acknowledgement does not confirm remote stop');
+  }
+  static prepare(
+    worker: string,
+    attempt: string,
+    peer: { id: string; tenant: string; digest: string },
+    text: string,
+    data: A2AObject,
+    disclosure: A2ACheckpoint['disclosure'],
+  ): A2ACheckpoint {
+    return {
+      schema_version: 1,
+      dialect: 'a2a',
+      worker_id: worker,
+      attempt_id: attempt,
+      peer_id: peer.id,
+      peer_digest: peer.digest,
+      tenant: peer.tenant,
+      message_id: randomUUID(),
+      task_id: null,
+      context_id: null,
+      state: 'prepared',
+      prompt_digest: digest({ text, data }),
+      cancel_requested: false,
+      result: null,
+      disclosure,
+    };
+  }
+}

package/src/agent-profiles.ts

@@ -0,0 +1,379 @@
+import {
+  constants,
+  openSync,
+  closeSync,
+  readFileSync,
+  fstatSync,
+  lstatSync,
+  existsSync,
+  readdirSync,
+} from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import {
+  canonical,
+  digest,
+  integer,
+  object,
+  ServiceError,
+  string,
+  textDigest,
+  type Controller,
+} from './protocol.js';
+import { providerRoute, type ProviderRoute } from './provider-config.js';
+import type { Store } from './store.js';
+import { DIAGNOSTIC_PROFILE } from './worker-boundary.js';
+
+export interface AgentProfile {
+  schema_version: 1;
+  id: string;
+  revision: number;
+  tools: readonly string[];
+  max_depth: number;
+  role?: 'explorer' | 'reviewer' | 'builder' | 'tester' | 'integrator';
+  description?: string;
+  prompt?: string;
+  max_requests?: number;
+  provider?: string;
+  model?: string;
+  source_digest?: string;
+}
+export interface AgentGrant {
+  schema_version: 1;
+  id: string;
+  owner_session: string;
+  profile: AgentProfile;
+  profile_digest: string;
+  route: ProviderRoute;
+  output_cap: boolean;
+  facts: { id: string; kind: string; text: string }[];
+}
+const ROLE_TOOLS = {
+  explorer: ['salaam_probe', 'salaam_repository'],
+  reviewer: ['salaam_probe', 'salaam_repository', 'salaam_findings'],
+  builder: ['salaam_probe', 'salaam_repository', 'salaam_files', 'salaam_command'],
+  tester: ['salaam_probe', 'salaam_repository', 'salaam_command', 'salaam_findings'],
+  integrator: ['salaam_probe', 'salaam_repository', 'salaam_findings'],
+} as const;
+export function profileTools(role: keyof typeof ROLE_TOOLS): string[] {
+  return [...ROLE_TOOLS[role]].sort();
+}
+export const BUILTIN_PROFILES: AgentProfile[] = [
+  DIAGNOSTIC_PROFILE,
+  ...(['explorer', 'reviewer', 'builder', 'tester', 'integrator'] as const).map((role) => ({
+    schema_version: 1 as const,
+    id: 'salaam/' + role,
+    revision: 1,
+    role,
+    tools: profileTools(role),
+    max_depth: 1,
+    max_requests: 8,
+    description:
+      role === 'explorer'
+        ? 'Bounded evidence from an immutable repository snapshot'
+        : role === 'reviewer'
+          ? 'Independent findings over an immutable repository diff'
+          : role === 'builder'
+            ? 'Implement a proposal in a private owned workspace'
+            : role === 'tester'
+              ? 'Run bounded checks in an isolated disposable copy'
+              : 'Review integration evidence without applying changes',
+    prompt:
+      role === 'explorer'
+        ? 'Investigate only the supplied repository snapshot. Cite actual file paths, line numbers and hashes. Do not claim edits or execution.'
+        : role === 'builder'
+          ? 'Implement only the assigned change in your private owned workspace using salaam_files. Run bounded checks through salaam_command. Command edits are disposable. Do not claim the root workspace was changed or verified; return a proposal for explicit integration.'
+          : role === 'tester'
+            ? 'Inspect the admitted snapshot and run bounded checks using salaam_command. You cannot edit persistent files. Report actual outcomes; a model answer is not a root verification receipt.'
+            : 'Review only the supplied immutable diff and repository snapshot. Report concrete findings with file/line evidence through salaam_findings. A finding is analysis, not a verification receipt.',
+  })),
+];
+
+/** JSON front matter is a deliberately bounded subset, not an executable config format. */
+export function parseAgentProfile(name: string, source: string): AgentProfile {
+  if (!/^[a-z][a-z0-9-]{0,63}$/.test(name) || Buffer.byteLength(source) > 49152)
+    throw new ServiceError('invalid_profile', 'Invalid profile name or size');
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/.exec(source);
+  if (!match) throw new ServiceError('invalid_profile', 'Use JSON front matter between --- lines');
+  let metadata: Record<string, unknown>;
+  try {
+    metadata = object(JSON.parse(match[1]!));
+  } catch {
+    throw new ServiceError('invalid_profile', 'Invalid JSON profile metadata');
+  }
+  const allowed = [
+    'description',
+    'revision',
+    'role',
+    'tools',
+    'provider',
+    'model',
+    'max_requests',
+    'max_depth',
+  ];
+  if (Object.keys(metadata).some((key) => !allowed.includes(key)))
+    throw new ServiceError(
+      'invalid_profile',
+      'Profiles cannot define executables, credentials, plugins, environment or additional fields',
+    );
+  const role = string(metadata.role, 'role', 32) as keyof typeof ROLE_TOOLS;
+  if (!Object.hasOwn(ROLE_TOOLS, role))
+    throw new ServiceError('invalid_profile', 'Unsupported specialist role');
+  const tools =
+    metadata.tools === undefined
+      ? profileTools(role)
+      : [
+          ...new Set(
+            (Array.isArray(metadata.tools) ? metadata.tools : []).map((x) =>
+              string(x, 'tool', 128),
+            ),
+          ),
+        ].sort();
+  if (!tools.length || tools.some((x) => !profileTools(role).includes(x)))
+    throw new ServiceError('invalid_profile', 'Tools exceed the specialist role');
+  const revision = integer(metadata.revision ?? 1, 'revision');
+  const maxRequests = integer(metadata.max_requests ?? 8, 'max_requests');
+  if (revision < 1 || maxRequests < 1 || maxRequests > 8 || (metadata.max_depth ?? 1) !== 1)
+    throw new ServiceError(
+      'invalid_profile',
+      'Invalid revision, request limit or delegation depth',
+    );
+  if ((metadata.provider === undefined) !== (metadata.model === undefined))
+    throw new ServiceError('invalid_profile', 'Select both provider and model');
+  const prompt = string(match[2]!.trim(), 'prompt', 32768);
+  return {
+    schema_version: 1,
+    id: 'project/' + name,
+    revision,
+    role,
+    tools,
+    max_depth: 1,
+    description: string(metadata.description ?? name, 'description', 512),
+    prompt,
+    max_requests: maxRequests,
+    source_digest: textDigest(source),
+    ...(metadata.provider
+      ? {
+          provider: string(metadata.provider, 'provider', 128),
+          model: string(metadata.model, 'model', 256),
+        }
+      : {}),
+  };
+}
+
+export class AgentProfiles {
+  assertExecution?: () => void;
+  validateFrame?: (session: string) => void;
+  constructor(
+    readonly store: Store,
+    private route: ProviderRoute,
+    private prepareRoute: (
+      route: ProviderRoute,
+      session: string,
+    ) => Promise<{ route: ProviderRoute; output_cap: boolean }>,
+  ) {}
+  list(session: string): AgentProfile[] {
+    const root = this.store.session(session).cwd;
+    const control = join(root, '.salaam'),
+      directory = join(control, 'agents');
+    for (const path of [control, directory]) {
+      if (!existsSync(path)) return structuredClone(BUILTIN_PROFILES);
+      const stat = lstatSync(path);
+      if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new ServiceError('invalid_profile', 'Profile directories must not be symlinks');
+    }
+    const names = readdirSync(directory)
+      .filter((name) => name.endsWith('.md'))
+      .sort();
+    if (names.length > 32) throw new ServiceError('invalid_profile', 'At most 32 project profiles');
+    const profiles = names.map((file) => {
+      const path = join(directory, file),
+        fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+      try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > 49152)
+          throw new ServiceError('invalid_profile', 'Profile must be a bounded regular file');
+        return parseAgentProfile(file.slice(0, -3), readFileSync(fd, 'utf8'));
+      } finally {
+        closeSync(fd);
+      }
+    });
+    return [...structuredClone(BUILTIN_PROFILES), ...profiles];
+  }
+  inspect(session: string, id: string): AgentProfile {
+    this.store.session(session);
+    const builtin = BUILTIN_PROFILES.find((profile) => profile.id === id);
+    if (builtin) return structuredClone(builtin);
+    const profile = this.list(session).find((x) => x.id === id);
+    if (!profile) throw new ServiceError('not_found', 'Agent profile not found', 404);
+    return profile;
+  }
+  async admit(
+    session: string,
+    request: string,
+    profileId: string,
+    expectedDigest: string,
+    factIds: string[],
+    controller: Controller,
+  ): Promise<AgentGrant> {
+    const input = { kind: 'agent-admit', session, profileId, expectedDigest, factIds };
+    const saved = this.store.cachedRequest<AgentGrant>('local-operator', request, input);
+    if (saved) return saved;
+    this.store.authorizeControl(session, controller);
+    const profile = this.inspect(session, profileId);
+    if (digest(profile) !== expectedDigest)
+      throw new ServiceError('profile_changed', 'Review the current profile digest');
+    const writing = profile.tools.some((tool) => ['salaam_files', 'salaam_command'].includes(tool));
+    if (writing) {
+      if (!this.assertExecution)
+        throw new ServiceError(
+          'profile_unavailable',
+          'Writing roles require the parallel execution boundary',
+        );
+      this.assertExecution();
+    }
+    const prepared = await this.prepareRoute(
+      profile.provider
+        ? providerRoute(profile.provider, profile.model, Math.min(2048, this.route.max_tokens))
+        : this.route,
+      session,
+    );
+    return this.store.request('local-operator', request, input, () => {
+      this.store.authorizeControl(session, controller);
+      if (writing) this.assertExecution!();
+      if (digest(this.inspect(session, profileId)) !== expectedDigest)
+        throw new ServiceError('profile_changed', 'Profile changed during admission');
+      if (
+        profile.role &&
+        !this.store.db.prepare('SELECT id FROM workspaces WHERE session_id=?').get(session)
+      )
+        throw new ServiceError(
+          'workspace_unavailable',
+          'Specialists need an admitted coding workspace',
+        );
+      if (factIds.length > 16 || new Set(factIds).size !== factIds.length)
+        throw new ServiceError('invalid_profile', 'Select at most 16 distinct facts');
+      const facts = factIds.map((id) => {
+        const fact = this.store.db
+          .prepare(
+            'SELECT id,kind,text FROM task_facts WHERE id=? AND session_id=? AND id NOT IN (SELECT supersedes FROM task_facts WHERE supersedes IS NOT NULL)',
+          )
+          .get(id, session);
+        if (!fact) throw new ServiceError('not_found', 'Selected fact is unavailable', 404);
+        return { id: String(fact.id), kind: String(fact.kind), text: String(fact.text) };
+      });
+      const grant: AgentGrant = {
+        schema_version: 1,
+        id: randomUUID(),
+        owner_session: session,
+        profile,
+        profile_digest: expectedDigest,
+        route: prepared.route,
+        output_cap: prepared.output_cap,
+        facts,
+      };
+      const priorProfile = this.store.db
+        .prepare('SELECT digest FROM worker_profiles WHERE id=? AND revision=?')
+        .get(profile.id, profile.revision);
+      if (priorProfile && priorProfile.digest !== expectedDigest)
+        throw new ServiceError(
+          'profile_revision_conflict',
+          'Changed profile contents require a new revision',
+        );
+      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,
+      });
+      this.validateFrame?.(session);
+      return grant;
+    });
+  }
+  resolve(session: string, id: string): AgentGrant {
+    const row = this.store.db
+      .prepare(
+        "SELECT document,digest FROM agent_grants WHERE owner_session=? AND profile_id=? AND state='active' ORDER BY rowid DESC LIMIT 1",
+      )
+      .get(session, id);
+    if (!row)
+      throw new ServiceError('authority_denied', 'Operator must admit this agent profile first');
+    const grant = JSON.parse(String(row.document)) as AgentGrant;
+    if (digest(grant) !== row.digest || digest(this.inspect(session, id)) !== grant.profile_digest)
+      throw new ServiceError('profile_changed', 'Profile changed; renew its admission');
+    return grant;
+  }
+  validate(grant: AgentGrant): void {
+    const row = this.store.db
+      .prepare('SELECT document,digest,state FROM agent_grants WHERE id=? AND owner_session=?')
+      .get(grant.id, grant.owner_session);
+    if (
+      !row ||
+      row.state !== 'active' ||
+      row.digest !== digest(grant) ||
+      row.document !== canonical(grant) ||
+      digest(this.inspect(grant.owner_session, grant.profile.id)) !== grant.profile_digest
+    )
+      throw new ServiceError(
+        'worker_profile_revoked',
+        'Specialist admission was revoked or changed',
+      );
+  }
+  revoke(session: string, grantId: string, request: string, controller: Controller): unknown {
+    return this.store.request(
+      'local-operator',
+      request,
+      { kind: 'agent-revoke', session, grantId },
+      () => {
+        this.store.authorizeControl(session, controller);
+        const result = this.store.db
+          .prepare("UPDATE agent_grants SET state='revoked' WHERE id=? AND owner_session=?")
+          .run(grantId, session);
+        if (!result.changes) throw new ServiceError('not_found', 'Agent admission not found', 404);
+        this.store.event(session, 'agent.revoked', { grant_id: grantId });
+        return { grant_id: grantId, state: 'revoked' };
+      },
+    );
+  }
+  snapshot(session: string) {
+    return this.store.db
+      .prepare(
+        'SELECT document,state FROM agent_grants WHERE owner_session=? ORDER BY rowid DESC LIMIT 64',
+      )
+      .all(session)
+      .reverse()
+      .map((row) => {
+        const grant = JSON.parse(String(row.document)) as AgentGrant;
+        let state = String(row.state);
+        if (state === 'active') {
+          try {
+            this.validate(grant);
+          } catch {
+            state = 'stale';
+          }
+        }
+        return {
+          grant_id: grant.id,
+          profile_id: grant.profile.id,
+          revision: grant.profile.revision,
+          profile_digest: grant.profile_digest,
+          tools: grant.profile.tools,
+          role: grant.profile.role,
+          route: grant.route,
+          output_cap: grant.output_cap,
+          selected_facts: grant.facts.map((f) => f.id),
+          state,
+        };
+      });
+  }
+}