@treenity/core 1.0.48 → 3.0.0

package/src/server/actions.ts

@@ -0,0 +1,274 @@
+// Treenity Actions — Layer 4
+// Server-specific: ActionCtx, SchemaHandler, client proxy
+// Component registration lives in @/comp
+
+import { chain, type Chain } from '#chain';
+import { Class, type TypeProxy } from '#comp';
+import { makeTypedProxy, type ExecuteFn, type StreamFn } from '#comp/handle';
+import { collectDeps as _collectDeps, type ResolvedDeps } from '#comp/needs';
+import { type ComponentData, getComponentField, isComponent, type NodeData, register, resolve } from '#core';
+import { type Tree } from '#tree';
+import { createDraft, enablePatches, finishDraft, type Patch } from 'immer';
+import { OpError } from './errors';
+
+export type NodeHandle = ReturnType<typeof serverNodeHandle>;
+
+/** @opaque Runtime-injected, not part of public schema */
+export type ActionCtx = {
+  node: NodeData;
+  store: Tree;
+  signal: AbortSignal;
+  /** Typed client for cross-node action calls: ctx.nc(path).get(Type).method(data) */
+  nc: NodeHandle;
+  comp?: ComponentData;
+  deps?: ResolvedDeps;
+};
+
+// ── Client proxy ──
+
+export type { ExecuteInput } from '#comp/handle';
+
+export function createNodeHandle(
+  execute: ExecuteFn,
+  stream: StreamFn,
+  getNode?: (path: string) => NodeData | undefined,
+) {
+  return (path: string) => ({
+    get<T extends object>(cls: Class<T>, key?: string): Chain<TypeProxy<T>> {
+      return chain(makeTypedProxy(getNode?.(path), cls, path, execute, stream, key)) as Chain<TypeProxy<T>>;
+    },
+  });
+}
+// Server-side typed node client: wraps executeAction/executeStream into createNodeHandle.
+// Usage: const nc = serverNodeHandle(store); await nc(path).get(MyComp).myMethod();
+export function serverNodeHandle(store: Tree) {
+  return createNodeHandle(
+    (input) => executeAction(store, input.path, input.type, input.key, input.action, input.data),
+    (input) => executeStream(store, input.path, input.type, input.key, input.action, input.data),
+  );
+}
+
+export { collectSiblings, collectDeps } from '#comp/needs';
+export { registerActionNeeds, getActionNeeds } from '#comp/needs';
+
+// ── Server-side operations ──
+// Single entry point for tRPC, MCP, cook-bot, services — no boilerplate.
+// All ops throw OpError for domain errors (NOT_FOUND, BAD_REQUEST, CONFLICT).
+enablePatches();
+
+// Action timeout: env-configurable, default 5 min (was 30s)
+const ACTION_TIMEOUT = Number(process.env.ACTION_TIMEOUT) || 300_000;
+const STREAM_TIMEOUT = Number(process.env.STREAM_TIMEOUT) || 600_000;
+
+// ── Shared resolution: find handler + component for any action call ──
+// Resolution order:
+//   key given → node[key], verify $type === type (if type given)
+//   type given, no key → scan components for first matching $type
+//   neither → node.$type, then scan components for matching action handler
+
+type ResolvedAction = {
+  node: NodeData;
+  handler: (ctx: ActionCtx, data: unknown) => unknown;
+  type: string;
+  comp: ComponentData | undefined;
+  deps: ResolvedDeps;
+  fieldKey: string | undefined;
+};
+
+// Dynamic actions: load from /sys/types/{ns}/{name} node's `actions` component.
+// Code is compiled with new Function, registered for future calls.
+// Format: actions.{name} = "const node = ...; return result;"  (async function body)
+async function loadDynamicAction(
+  store: Tree, type: string, action: string,
+): Promise<((ctx: ActionCtx, data: unknown) => unknown) | null> {
+  if (!type.includes('.')) return null;
+
+  const typePath = `/sys/types/${type.replace(/\./g, '/')}`;
+  const typeNode = await store.get(typePath);
+  const actionCode = (typeNode as any)?.actions?.[action];
+  if (!actionCode || typeof actionCode !== 'string') return null;
+
+  try {
+    const fn = new Function('ctx', 'data', `return (async () => { ${actionCode} })()`) as
+      (ctx: ActionCtx, data: unknown) => unknown;
+    register(type, `action:${action}`, fn);
+    console.log(`[uix] loaded dynamic action "${action}" for "${type}"`);
+    return fn;
+  } catch (err: any) {
+    console.warn(`[uix] failed to compile action "${action}" for "${type}":`, err.message);
+    return null;
+  }
+}
+
+async function resolveActionHandler(
+  store: Tree,
+  path: string,
+  componentType: string | undefined,
+  componentKey: string | undefined,
+  action: string,
+): Promise<ResolvedAction> {
+  const node = await store.get(path);
+  if (!node) throw new OpError('NOT_FOUND', `Node not found: ${path}`);
+
+  const [comp, fieldKey] = getComponentField(node, componentType ?? 't.any', componentKey) ?? [];
+  if (!isComponent(comp)) throw new OpError('NOT_FOUND', `Component "${componentKey ?? componentType}" not found on ${path}`);
+
+  const type = comp.$type;
+
+  let deps: ResolvedDeps = await _collectDeps(node, fieldKey!, action, store);
+
+  let handler = resolve(comp, `action:${action}`);
+
+  // Fallback: try loading dynamic action from type definition node
+  if (!handler) handler = await loadDynamicAction(store, type, action);
+  if (!handler) throw new OpError('BAD_REQUEST', `No action "${action}" for type "${type}"`);
+
+  return { node, handler, type, comp, deps, fieldKey };
+}
+
+// ── executeAction: mutating action with Immer draft + patch collection ──
+// Patches attached as $patches for subscription layer (CDC Matrix in sub.ts).
+// Pure actions (no state changes) skip persist — patches.length === 0.
+
+export async function executeAction(
+  store: Tree,
+  path: string,
+  componentType: string | undefined,
+  componentKey: string | undefined,
+  action: string,
+  data?: unknown,
+): Promise<unknown> {
+  const { node, handler, type, deps, fieldKey } = await resolveActionHandler(
+    store, path, componentType, componentKey, action,
+  );
+
+  // Pre/post condition checking (Design by Contract)
+  const schemaHandler = resolve(type, 'schema') as (() => any) | null;
+  const methodSchema = schemaHandler?.()?.methods?.[action];
+  const preFields: string[] = methodSchema?.pre ?? [];
+  const postFields: string[] = methodSchema?.post ?? [];
+  const target = fieldKey ? node[fieldKey] as Record<string, unknown> : node as Record<string, unknown>;
+
+  for (const f of preFields) {
+    const v = target[f];
+    if (v === undefined || v === null || v === '' || v === 0) {
+      console.warn(`[pre] ${type}.${action}: field "${f}" is empty`);
+    }
+  }
+
+  const postSnap = Object.fromEntries(postFields.map(f => [f, target[f]]));
+
+  const draft = createDraft(node);
+  // comp must be the draft version so Immer captures mutations via `this.*`
+  const dc = fieldKey ? draft[fieldKey] : undefined;
+  const draftComp = isComponent(dc) ? dc as ComponentData : undefined;
+  const nc = serverNodeHandle(store);
+  const actx: ActionCtx = { node: draft, comp: draftComp, deps, store, signal: AbortSignal.timeout(ACTION_TIMEOUT), nc };
+  const result = await handler(actx, data ?? {});
+
+  let patches: Patch[] = [];
+  const nextNode = finishDraft(draft, (p) => { patches = p });
+
+  const postTarget = fieldKey ? nextNode[fieldKey] as Record<string, unknown> : nextNode as Record<string, unknown>;
+  for (const f of postFields) {
+    if (postTarget[f] === postSnap[f]) {
+      console.warn(`[post] ${type}.${action}: field "${f}" unchanged`);
+    }
+  }
+
+  if (patches.length > 0) await store.set({ ...nextNode, $patches: patches } as NodeData);
+  return result;
+}
+
+// ── executeStream: generator action — yields multiple values, no Immer draft ──
+// Generator actions persist via store.set() directly inside the generator body.
+
+export async function* executeStream(
+  store: Tree,
+  path: string,
+  componentType: string | undefined,
+  componentKey: string | undefined,
+  action: string,
+  data?: unknown,
+  signal?: AbortSignal,
+): AsyncGenerator<unknown> {
+  const { node, handler, comp, deps } = await resolveActionHandler(
+    store, path, componentType, componentKey, action,
+  );
+  // comp is already node[fieldKey] from resolution — no Immer draft needed for generators
+  const nc = serverNodeHandle(store);
+  const actx: ActionCtx = { node, comp, deps, store, signal: signal ?? AbortSignal.timeout(STREAM_TIMEOUT), nc };
+  const result = handler(actx, data ?? {});
+  if (!result || typeof (result as any)[Symbol.asyncIterator] !== 'function')
+    throw new OpError('BAD_REQUEST', `Action "${action}" is not a generator`);
+  yield* result as AsyncIterable<unknown>;
+}
+
+// ── setComponent: single component update with OCC ──
+
+export async function setComponent(
+  store: Tree,
+  path: string,
+  name: string,
+  data: Record<string, unknown>,
+  rev?: number,
+): Promise<void> {
+  const node = await store.get(path);
+  if (!node) throw new OpError('NOT_FOUND', `Node not found: ${path}`);
+
+  if (rev != null && node.$rev != null && rev !== node.$rev)
+    throw new OpError('CONFLICT', `Stale revision: expected ${rev}, got ${node.$rev}`);
+
+  node[name] = data;
+  await store.set(node);
+}
+
+// ── applyTemplate: copy template children to target path ──
+
+export async function applyTemplate(
+  store: Tree,
+  templatePath: string,
+  targetPath: string,
+): Promise<{ applied: string; blocks: number }> {
+  const tmpl = await store.get(templatePath);
+  if (!tmpl) throw new OpError('NOT_FOUND', `Template not found: ${templatePath}`);
+
+  const { items: blocks } = await store.getChildren(templatePath);
+  const { items: existing } = await store.getChildren(targetPath);
+
+  for (const child of existing) await store.remove(child.$path);
+
+  for (const block of blocks) {
+    const bname = block.$path.slice(block.$path.lastIndexOf('/') + 1);
+    const bpath = targetPath === '/' ? `/${bname}` : `${targetPath}/${bname}`;
+    const { $rev, ...rest } = block;
+    await store.set({ ...rest, $path: bpath });
+  }
+
+  return { applied: tmpl.$path, blocks: blocks.length };
+}
+
+// ── Generic patch action — deep merge data into node (Immer draft) ──
+// Registered on 'default' so every type inherits it via resolve fallback.
+// Guards $ fields. Deep-merges objects, replaces arrays/primitives.
+
+function deepAssign(target: any, source: Record<string, unknown>) {
+  for (const [k, v] of Object.entries(source)) {
+    if (k.startsWith('$')) continue;
+    if (v && typeof v === 'object' && !Array.isArray(v)
+      && target[k] && typeof target[k] === 'object' && !Array.isArray(target[k])) {
+      deepAssign(target[k], v as Record<string, unknown>);
+    } else {
+      target[k] = v;
+    }
+  }
+}
+
+export function registerBuiltinActions() {
+  register('default', 'action:patch', (ctx: ActionCtx, data: unknown) => {
+    if (!data || typeof data !== 'object') throw new OpError('BAD_REQUEST', 'patch: data must be an object');
+    deepAssign(ctx.node, data as Record<string, unknown>);
+  });
+}
+
+registerBuiltinActions();

package/src/server/agent-sub.test.ts

@@ -0,0 +1,90 @@
+// Focused reproduction test: new child created via action → watcher notifies
+// Tests the exact agent scenario: action:task creates /agent/tasks/t-xxx,
+// user watching /agent/tasks prefix should get the event.
+
+import { createNode, register } from '#core';
+import { clearRegistry } from '#core/index.test';
+import { createMemoryTree } from '#tree';
+import assert from 'node:assert/strict';
+import { beforeEach, describe, it } from 'node:test';
+import { type ActionCtx, executeAction } from './actions';
+import { type NodeEvent, withSubscriptions } from './sub';
+import { createWatchManager } from './watch';
+
+describe('Agent task subscription', () => {
+  beforeEach(() => clearRegistry());
+
+  it('new child created via action triggers prefix watcher', async () => {
+    // Register the action (simulates agent's action:task)
+    register('agent.config', 'action:task', async (ctx: ActionCtx, data: { prompt: string }) => {
+      const id = `t-${Date.now()}`;
+      const taskPath = `${ctx.node.$path}/tasks/${id}`;
+      await ctx.store.set(createNode(taskPath, 'agent.task', {
+        prompt: data.prompt,
+        status: 'pending',
+        createdAt: Date.now(),
+      }));
+      return { taskPath };
+    });
+
+    // Build store pipeline: memory → subscriptions → watcher
+    const mem = createMemoryTree();
+    const watcher = createWatchManager();
+    const store = withSubscriptions(mem, (e) => watcher.notify(e));
+
+    // Seed the agent config node
+    await store.set(createNode('/agent', 'agent.config', { systemPrompt: 'test' }));
+    await store.set(createNode('/agent/tasks', 'dir'));
+
+    // Simulate user: connect SSE + register prefix watch
+    const events: NodeEvent[] = [];
+    watcher.connect('conn1', 'user1', (e) => events.push(e));
+    watcher.watch('user1', ['/agent/tasks'], { children: true, autoWatch: true });
+
+    // Execute the action (same as trpc.execute.mutate)
+    const result = await executeAction(store, '/agent', undefined, undefined, 'task', { prompt: 'test task' });
+    assert.ok(result && typeof (result as any).taskPath === 'string');
+
+    // Verify: the watcher should have received the new task event
+    assert.equal(events.length, 1, 'watcher should have received exactly 1 event');
+    assert.equal(events[0].type, 'set', 'event should be of type "set"');
+    assert.ok((events[0] as any).path.startsWith('/agent/tasks/t-'), 'event path should be the new task');
+    assert.equal((events[0] as any).node.$type, 'agent.task', 'node should have correct $type');
+  });
+
+  it('new child event includes correct node data for cache.put', async () => {
+    register('agent.config', 'action:task', async (ctx: ActionCtx, data: { prompt: string }) => {
+      const taskPath = `${ctx.node.$path}/tasks/t-1`;
+      await ctx.store.set(createNode(taskPath, 'agent.task', {
+        prompt: data.prompt,
+        status: 'pending',
+        createdAt: 12345,
+      }));
+      return { taskPath };
+    });
+
+    const mem = createMemoryTree();
+    const watcher = createWatchManager();
+    const store = withSubscriptions(mem, (e) => watcher.notify(e));
+
+    await store.set(createNode('/agent', 'agent.config'));
+    await store.set(createNode('/agent/tasks', 'dir'));
+
+    const events: NodeEvent[] = [];
+    watcher.connect('c1', 'u1', (e) => events.push(e));
+    watcher.watch('u1', ['/agent/tasks'], { children: true, autoWatch: true });
+
+    await executeAction(store, '/agent', undefined, undefined, 'task', { prompt: 'hello' });
+
+    // Simulate what the client does: reconstruct the node from the event
+    assert.equal(events.length, 1);
+    const evt = events[0] as { type: 'set'; path: string; node: any };
+    const reconstructed = { $path: evt.path, ...evt.node };
+
+    assert.equal(reconstructed.$path, '/agent/tasks/t-1');
+    assert.equal(reconstructed.$type, 'agent.task');
+    assert.equal(reconstructed.prompt, 'hello');
+    assert.equal(reconstructed.status, 'pending');
+    assert.equal(reconstructed.createdAt, 12345);
+  });
+});

package/src/server/agent.test.ts

@@ -0,0 +1,305 @@
+import { createNode, R, S, W } from '#core';
+import { clearRegistry } from '#core/index.test';
+import { createMemoryTree, type Tree } from '#tree';
+import assert from 'node:assert/strict';
+import { afterEach, beforeEach, describe, it } from 'node:test';
+import { AGENT_SESSION_TTL, hashAgentKey, timingSafeCompare } from './agent';
+import { buildClaims, createSession, resolveToken, withAcl } from './auth';
+
+// Import agent-port type registration (side-effect: registers t.agent.port)
+import '../mods/treenity/agent-port';
+
+let store: Tree;
+
+beforeEach(async () => {
+  clearRegistry();
+  // Re-import registers via dynamic import won't re-run, so import at top level
+  await import('../mods/treenity/agent-port');
+
+  store = createMemoryTree();
+  // Root with public read
+  await store.set({ ...createNode('/', 'root'), $acl: [{ g: 'public', p: R }] });
+});
+
+describe('hashAgentKey', () => {
+  it('produces consistent SHA-256 hex', () => {
+    const h1 = hashAgentKey('test-secret');
+    const h2 = hashAgentKey('test-secret');
+    assert.equal(h1, h2);
+    assert.equal(h1.length, 64); // SHA-256 = 32 bytes = 64 hex chars
+  });
+
+  it('different keys produce different hashes', () => {
+    assert.notEqual(hashAgentKey('key-a'), hashAgentKey('key-b'));
+  });
+});
+
+describe('timingSafeCompare', () => {
+  it('returns true for matching hashes', () => {
+    const h = hashAgentKey('secret');
+    assert.equal(timingSafeCompare(h, h), true);
+  });
+
+  it('returns false for different hashes', () => {
+    assert.equal(timingSafeCompare(hashAgentKey('a'), hashAgentKey('b')), false);
+  });
+
+  it('returns false for different lengths', () => {
+    assert.equal(timingSafeCompare('aa', 'bbbb'), false);
+  });
+});
+
+describe('agent session', () => {
+  it('createSession with custom TTL', async () => {
+    const token = await createSession(store, 'agent:/agents/bot', { ttlMs: AGENT_SESSION_TTL });
+    assert.ok(token);
+    const session = await resolveToken(store, token);
+    assert.ok(session);
+    assert.equal(session.userId, 'agent:/agents/bot');
+  });
+
+  it('createSession with custom claims stores and retrieves them', async () => {
+    const claims = ['u:agent:/agents/bot', 'agent'];
+    const token = await createSession(store, 'agent:/agents/bot', { claims });
+    const session = await resolveToken(store, token);
+    assert.ok(session);
+    assert.deepEqual(session.claims, claims);
+  });
+
+  it('regular session has no claims field', async () => {
+    const token = await createSession(store, 'alice');
+    const session = await resolveToken(store, token);
+    assert.ok(session);
+    assert.equal(session.claims, undefined);
+  });
+});
+
+describe('agent TOFU flow', () => {
+  const PORT_PATH = '/agents/test-bot';
+  const AGENT_KEY = 'super-secret-agent-key-12345';
+
+  beforeEach(async () => {
+    // Create agent port node (admin action)
+    await store.set({
+      ...createNode(PORT_PATH, 't.agent.port'),
+      label: 'Test Bot',
+      status: 'idle',
+      connected: false,
+      $acl: [{ g: 'admins', p: R | W | S }],
+    });
+  });
+
+  it('idle → pending on first connect', async () => {
+    const keyHash = hashAgentKey(AGENT_KEY);
+    const node = await store.get(PORT_PATH);
+    assert.ok(node);
+
+    // Simulate agentConnect: idle → pending
+    await store.set({ ...node, status: 'pending', pendingKey: keyHash });
+
+    const updated = await store.get(PORT_PATH);
+    assert.equal((updated as any).status, 'pending');
+    assert.equal((updated as any).pendingKey, keyHash);
+  });
+
+  it('pending + same key = still pending', async () => {
+    const keyHash = hashAgentKey(AGENT_KEY);
+    await store.set({
+      ...(await store.get(PORT_PATH))!,
+      status: 'pending',
+      pendingKey: keyHash,
+    });
+
+    // Same key: verify it matches
+    assert.ok(timingSafeCompare(hashAgentKey(AGENT_KEY), keyHash));
+  });
+
+  it('pending + different key = rejected', async () => {
+    const keyHash = hashAgentKey(AGENT_KEY);
+    await store.set({
+      ...(await store.get(PORT_PATH))!,
+      status: 'pending',
+      pendingKey: keyHash,
+    });
+
+    // Different key doesn't match
+    assert.equal(timingSafeCompare(hashAgentKey('wrong-key'), keyHash), false);
+  });
+
+  it('approve moves pending → approved, creates user, sets ACL', async () => {
+    const keyHash = hashAgentKey(AGENT_KEY);
+    const agentUserId = `agent:${PORT_PATH}`;
+
+    // Set to pending
+    await store.set({
+      ...(await store.get(PORT_PATH))!,
+      status: 'pending',
+      pendingKey: keyHash,
+    });
+
+    // Simulate approve action effects
+    const node = (await store.get(PORT_PATH))!;
+    const acl = [...(node.$acl ?? []), { g: `u:${agentUserId}`, p: R | W | S }];
+    await store.set({
+      ...node,
+      status: 'approved',
+      approvedKey: keyHash,
+      pendingKey: undefined,
+      $acl: acl,
+    });
+
+    // Create agent user
+    await store.set({
+      ...createNode(`/auth/users/${agentUserId}`, 'user'),
+      groups: { $type: 'groups', list: ['agent'] },
+    });
+
+    // Verify
+    const approved = await store.get(PORT_PATH);
+    assert.equal((approved as any).status, 'approved');
+    assert.equal((approved as any).approvedKey, keyHash);
+    assert.equal((approved as any).pendingKey, undefined);
+
+    const user = await store.get(`/auth/users/${agentUserId}`);
+    assert.ok(user);
+
+    // Agent ACL is set
+    assert.ok(approved!.$acl?.some(e => e.g === `u:${agentUserId}` && e.p === (R | W | S)));
+  });
+
+  it('approved + correct key = session with agent userId', async () => {
+    const keyHash = hashAgentKey(AGENT_KEY);
+    const agentUserId = `agent:${PORT_PATH}`;
+
+    // Setup approved state
+    await store.set({
+      ...(await store.get(PORT_PATH))!,
+      status: 'approved',
+      approvedKey: keyHash,
+      $acl: [
+        { g: 'admins', p: R | W | S },
+        { g: `u:${agentUserId}`, p: R | W | S },
+      ],
+    });
+    await store.set({
+      ...createNode(`/auth/users/${agentUserId}`, 'user'),
+      groups: { $type: 'groups', list: ['agent'] },
+    });
+
+    // Agent connects with correct key
+    assert.ok(timingSafeCompare(hashAgentKey(AGENT_KEY), keyHash));
+
+    // Create session
+    const token = await createSession(store, agentUserId, { ttlMs: AGENT_SESSION_TTL });
+    const session = await resolveToken(store, token);
+    assert.ok(session);
+    assert.equal(session.userId, agentUserId);
+
+    // buildClaims includes 'agent' group
+    const claims = await buildClaims(store, agentUserId);
+    assert.ok(claims.includes(`u:${agentUserId}`));
+    assert.ok(claims.includes('authenticated'));
+    assert.ok(claims.includes('agent'));
+  });
+
+  it('agent can write to its subtree via ACL', async () => {
+    const agentUserId = `agent:${PORT_PATH}`;
+    const claims = [`u:${agentUserId}`, 'authenticated', 'agent'];
+
+    // Setup: agent port with ACL granting agent access
+    await store.set({
+      ...(await store.get(PORT_PATH))!,
+      status: 'approved',
+      $acl: [
+        { g: 'admins', p: R | W | S },
+        { g: `u:${agentUserId}`, p: R | W | S },
+      ],
+    });
+
+    const aclStore = withAcl(store, agentUserId, claims);
+
+    // Agent can write to its subtree
+    await aclStore.set(createNode(`${PORT_PATH}/state`, 'agent.state'));
+    const child = await aclStore.get(`${PORT_PATH}/state`);
+    assert.ok(child);
+    assert.equal(child.$type, 'agent.state');
+  });
+
+  it('agent cannot write outside its subtree', async () => {
+    const agentUserId = `agent:${PORT_PATH}`;
+    const claims = [`u:${agentUserId}`, 'authenticated', 'agent'];
+
+    // Setup
+    await store.set({
+      ...(await store.get(PORT_PATH))!,
+      status: 'approved',
+      $acl: [
+        { g: 'admins', p: R | W | S },
+        { g: `u:${agentUserId}`, p: R | W | S },
+      ],
+    });
+
+    const aclStore = withAcl(store, agentUserId, claims);
+
+    // Agent cannot write to root-level paths (root ACL: public R only)
+    await assert.rejects(
+      () => aclStore.set(createNode('/something-else', 'dir')),
+      (err: Error) => err.message.includes('Access denied'),
+    );
+  });
+
+  it('revoke clears access', async () => {
+    const agentUserId = `agent:${PORT_PATH}`;
+
+    // Setup approved state with ACL
+    await store.set({
+      ...(await store.get(PORT_PATH))!,
+      status: 'approved',
+      approvedKey: hashAgentKey(AGENT_KEY),
+      $acl: [
+        { g: 'admins', p: R | W | S },
+        { g: `u:${agentUserId}`, p: R | W | S },
+      ],
+    });
+
+    // Simulate revoke: clear key, remove agent ACL
+    const node = (await store.get(PORT_PATH))!;
+    const acl = (node.$acl ?? []).filter(e => e.g !== `u:${agentUserId}`);
+    await store.set({
+      ...node,
+      status: 'revoked',
+      approvedKey: undefined,
+      connected: false,
+      $acl: acl,
+    });
+
+    const revoked = await store.get(PORT_PATH);
+    assert.equal((revoked as any).status, 'revoked');
+    assert.equal((revoked as any).approvedKey, undefined);
+    assert.ok(!revoked!.$acl?.some(e => e.g === `u:${agentUserId}`));
+  });
+
+  it('reset returns to idle', async () => {
+    const agentUserId = `agent:${PORT_PATH}`;
+
+    // Start from revoked
+    await store.set({
+      ...(await store.get(PORT_PATH))!,
+      status: 'revoked',
+      $acl: [{ g: 'admins', p: R | W | S }],
+    });
+
+    // Simulate reset
+    await store.set({
+      ...(await store.get(PORT_PATH))!,
+      status: 'idle',
+      pendingKey: undefined,
+      approvedKey: undefined,
+      connected: false,
+      connectedAt: undefined,
+    });
+
+    const reset = await store.get(PORT_PATH);
+    assert.equal((reset as any).status, 'idle');
+  });
+});

package/src/server/agent.ts

@@ -0,0 +1,17 @@
+// Agent Port — TOFU (Trust On First Use) connection system
+// Utilities for agent key hashing and session management.
+
+import { createHash, timingSafeEqual } from 'node:crypto';
+
+export const AGENT_SESSION_TTL = 7 * 24 * 60 * 60 * 1000; // 7 days
+
+/** SHA-256 hex hash — fast, sufficient for high-entropy agent keys */
+export function hashAgentKey(key: string): string {
+  return createHash('sha256').update(key).digest('hex');
+}
+
+/** Constant-time comparison of two hex hashes */
+export function timingSafeCompare(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(Buffer.from(a, 'hex'), Buffer.from(b, 'hex'));
+}