@zgeoff/atc 2.11.0 → 2.12.0

package/src/daemon/daemon-connection.ts

@@ -1,5 +1,6 @@
 import { basename } from 'node:path';
-import type { AgentAdapter, AgentID, SpawnOptions } from '../agents/agent-adapter';
+import type { AgentAdapter, AgentID, SpawnOptions, SpawnOverrides } from '../agents/agent-adapter';
+import { DaemonError } from '../protocol/daemon-error';
 import { DAEMON_FEATURES } from '../protocol/daemon-features';
 import { decodeCursor } from '../protocol/decode-cursor';
 import { encodeCursor } from '../protocol/encode-cursor';
@@ -14,19 +15,29 @@ import {
   encodeMessage,
 } from '../protocol/protocol';
 import type { ErrorCode, EventMsg, RequestMsg } from '../protocol/protocol';
+import type { TargetConfigError } from '../shared/collect-targets';
+import type { DaemonID } from '../shared/daemon-id';
 import type { MessageID } from '../shared/message-id';
+import { isRecord } from '../shared/report';
 import type { SessionID } from '../shared/session-id';
+import { toSessionID } from '../shared/to-session-id';
 import type { FleetEntry } from '../store/fleet-entry';
 import type { MessageRecord } from '../store/message-record';
 import type { Dims } from './attach-registry';
 import type { AgentEntry } from './build-agent-list';
 import type { FleetEvent } from './build-fleet-events';
+import { buildPayloadHash } from './build-payload-hash';
+import { buildScopedContext } from './build-scoped-context';
+import type { TargetEntry } from './build-target-list';
+import type { KeyedRequest } from './idempotency-ledger';
 import type { TranscriptPage, TranscriptPosition } from './load-transcript-page';
+import { parseSpawnOverrides } from './parse-spawn-overrides';
 import type { AnswerResult } from './permission-registry';
 import type { ScreenText } from './screen-model';
 import type { SessionDescriptor } from './sessions';
+import type { TargetAccess, TargetGrant } from './target-access';
 
-interface SpawnParams {
+export interface SpawnParams {
   readonly cwd: string;
   readonly name: string;
   readonly prompt: string;
@@ -36,6 +47,8 @@ interface SpawnParams {
   readonly namedBy: 'user' | 'auto';
   readonly agent: AgentID;
   readonly parent: SessionID | null;
+  readonly overrides: SpawnOverrides;
+  readonly target: string;
 }
 
 interface SessionRecord {
@@ -55,13 +68,46 @@ interface SessionTranscriptRead {
 
 export interface DaemonContext {
   readonly build: string;
+  readonly daemonID: DaemonID;
   readonly collectSessions: () => SessionDescriptor[];
   readonly collectSpawnDirs: () => Promise<string[]>;
   readonly collectAgents: () => AgentList;
   readonly collectFleet: () => Promise<FleetEntry[]>;
   readonly loadLastUsedAgent: () => Promise<AgentID>;
   readonly findAdapter: (id: AgentID) => AgentAdapter | null;
-  readonly spawnSession: (p: SpawnParams) => SessionDescriptor;
+
+  // The targets a principal may use.
+  readonly buildTargetAccess: (principal: string) => TargetAccess;
+
+  // The target and identity a session is bound to, or null when no
+  // session holds the id.
+  readonly findSessionGrant: (id: SessionID) => TargetGrant | null;
+
+  // The identity a target holds now, or null when the config holds no such
+  // target.
+  readonly findTargetIdentity: (target: string) => string | null;
+
+  // The ids of a session's sub-sessions.
+  readonly collectChildIDs: (id: SessionID) => SessionID[];
+
+  // The session a permission request belongs to, answered or not, or null
+  // for an unknown request.
+  readonly findPermissionSession: (request: string) => SessionID | null;
+
+  // The target a spawn runs on: the one it names, else the default. Throws
+  // the refusal for a target the spawn cannot run on, and for a spawn
+  // without a target when the config gives no default.
+  readonly resolveSpawnTarget: (requested: string | undefined) => string;
+
+  // Runs the plan, which throws the refusal for a spawn it refuses, then
+  // spawns. Answers with the `session.spawn` ok payload, which a keyed
+  // retry replays as the first spawn answered it while the access, when
+  // there is one, still reaches the target the spawn's session was bound to.
+  readonly spawnSession: (
+    plan: () => SpawnParams,
+    keyed: KeyedRequest | null,
+    access: TargetAccess | null,
+  ) => Promise<Readonly<Record<string, unknown>>>;
   readonly killSession: (id: SessionID) => Promise<boolean>;
   readonly updateSession: (id: SessionID, name?: string, pinned?: boolean) => boolean | 'child_pin';
   readonly quitDaemon: () => void;
@@ -100,17 +146,25 @@ export interface DaemonContext {
     from: TranscriptPosition | null,
     limit: number,
   ) => Promise<SessionTranscriptRead | 'missing' | 'unsupported'>;
+
+  // Reads the trail, leaving out each event of a session outside the access
+  // when there is one.
   readonly readEvents: (
     afterID: number | null,
     limit: number,
     waitMs: number,
     sessionID: SessionID | null,
+    access: TargetAccess | null,
   ) => Promise<EventsPage>;
+
+  // Answers with the `session.message` ok payload, which a keyed retry
+  // replays with the message's current status, or with the refusal.
   readonly writeSessionMessage: (
     sessionID: SessionID,
     from: string,
     text: string,
-  ) => Promise<MessageRecord | 'missing' | 'dead' | 'unsupported' | 'no_tap'>;
+    keyed: KeyedRequest | null,
+  ) => Promise<Readonly<Record<string, unknown>> | MessageRefusal>;
   readonly readMessage: (messageID: MessageID, waitMs: number) => Promise<MessageView | null>;
   readonly attachTap: (client: TapClient, sessionID: SessionID) => 'ok' | 'missing' | 'unsupported';
   readonly ackMessage: (
@@ -126,7 +180,10 @@ export interface OutputClient {
   readonly sendOutput: (sessionID: SessionID, event: EventMsg, byteLength: number) => void;
 }
 
-// The `agents.list` answer: the host the daemon runs on, and each agent.
+// The `agents.list` answer: the host the daemon runs on, each agent, each
+// execution target, what a spawn without either runs with, a digest of
+// the target config, and the target config problems the daemon started
+// with.
 interface AgentList {
   readonly daemon: {
     readonly hostname: string;
@@ -135,6 +192,10 @@ interface AgentList {
     readonly build: string;
   };
   readonly agents: readonly AgentEntry[];
+  readonly targets: readonly TargetEntry[];
+  readonly spawnDefaults: { readonly agent: AgentID; readonly target: string | null };
+  readonly configRevision: string;
+  readonly targetErrors: readonly TargetConfigError[];
 }
 
 // One `events.read` answer: the events, and whether more follow them.
@@ -151,11 +212,23 @@ interface MessageView {
   readonly answeredWith: readonly MessageID[];
 }
 
+// Why a session refuses a message before the daemon accepts it.
+export type MessageRefusal = 'missing' | 'dead' | 'unsupported' | 'no_tap';
+
 // The slice of a connection a tap subscription needs.
 export interface TapClient {
   readonly sendEvent: (event: EventMsg) => void;
 }
 
+// The targets a request may use and the namespace of its idempotency keys.
+interface RequestScope {
+  readonly access: TargetAccess;
+  readonly keyNamespace: string;
+}
+
+// The requests that act on the whole daemon, which only its owner may make.
+const OWNER_METHODS: ReadonlySet<string> = new Set(['daemon.quit', 'fleet.restore']);
+
 interface PeerSocket extends SocketWriter {
   readonly end: () => void;
 }
@@ -180,6 +253,17 @@ export class DaemonConnection {
 
   private readonly desynced = new Map<SessionID, number>();
 
+  // The principal the whole connection acts as, from its handshake, and the
+  // targets that principal may use; null for the daemon's owner, whose
+  // reach has no limit.
+  private principal: string | null = null;
+
+  private access: TargetAccess | null = null;
+
+  // The sessions and permission requests this limited connection was shown,
+  // so the events that end them reach it after the session is gone.
+  private readonly shown = new Set<string>();
+
   constructor(peer: PeerSocket, ctx: DaemonContext) {
     this.peer = peer;
     this.ctx = ctx;
@@ -195,7 +279,11 @@ export class DaemonConnection {
   }
 
   sendEvent(event: EventMsg): void {
-    if (this.helloed && !this.queue.send(encodeMessage(event))) {
+    if (!this.helloed || !this.canSeeEvent(event)) {
+      return;
+    }
+
+    if (!this.queue.send(encodeMessage(event))) {
       this.peer.end();
     }
   }
@@ -298,18 +386,88 @@ export class DaemonConnection {
       return false;
     }
 
-    this.answerAsync(req.id, () => this.applyRequest(req));
+    const scope = this.findRequestScope(req);
+
+    if (scope !== null && OWNER_METHODS.has(req.m)) {
+      this.sendErr(req.id, 'unauthorized', `${req.m} is open to the daemon's owner only`);
+
+      return true;
+    }
+
+    const ctx =
+      scope === null ? this.ctx : buildScopedContext(this.ctx, scope.access, scope.keyNamespace);
+
+    this.answerAsync(req.id, () => this.applyRequest(req, ctx));
+
+    return true;
+  }
+
+  // The targets a request may use and the namespace its idempotency keys
+  // live in: the request's own principal, limited to what the connection's
+  // may use, else the connection's. Null is the daemon's owner. The owner
+  // may act as any principal, that principal's keys included; a connection
+  // that acts as a principal always keeps its own keys, whatever principal
+  // a request acts as.
+  private findRequestScope(req: RequestMsg): RequestScope | null {
+    if (req.as === undefined) {
+      return this.principal === null || this.access === null
+        ? null
+        : { access: this.access, keyNamespace: `client:${this.principal}` };
+    }
+
+    const access = this.ctx.buildTargetAccess(req.as);
+
+    if (this.principal === null || this.access === null) {
+      return { access, keyNamespace: `client:${req.as}` };
+    }
+
+    return { access: this.access.merge(access), keyNamespace: `client:${this.principal}` };
+  }
+
+  // Whether this connection may see an event: always for the daemon's
+  // owner, and otherwise only for an event of a session the connection may
+  // see or was already shown.
+  private canSeeEvent(event: EventMsg): boolean {
+    if (this.access === null) {
+      return true;
+    }
+
+    const sessionID = findEventSession(event);
+    const request = typeof event['request'] === 'string' ? event['request'] : null;
+
+    if (sessionID === null) {
+      return request !== null && this.shown.has(`request:${request}`);
+    }
+
+    const grant = this.ctx.findSessionGrant(sessionID);
+
+    if (grant === null || !this.access.canUse(grant)) {
+      return this.shown.has(`session:${sessionID}`);
+    }
+
+    this.shown.add(`session:${sessionID}`);
+
+    if (request !== null) {
+      this.shown.add(`request:${request}`);
+    }
 
     return true;
   }
 
   // A store query that rejects must end one request, never the daemon: a
-  // floating promise here would take the whole process down with it.
+  // floating promise here would take the whole process down with it. A
+  // rejection that carries a protocol error code answers with that code.
   private answerAsync(id: number, answered: () => Promise<void>): void {
     void (async () => {
       try {
         await answered();
       } catch (error) {
+        if (error instanceof DaemonError) {
+          this.sendErr(id, error.code, error.message, error.data);
+
+          return;
+        }
+
         const reason = error instanceof Error ? error.message : String(error);
 
         this.sendErr(id, 'internal', reason);
@@ -317,7 +475,7 @@ export class DaemonConnection {
     })();
   }
 
-  private async applyRequest(req: RequestMsg): Promise<void> {
+  private async applyRequest(req: RequestMsg, ctx: DaemonContext): Promise<void> {
     await this.helloAnswered;
 
     switch (req.m) {
@@ -327,33 +485,33 @@ export class DaemonConnection {
         return;
       }
       case 'session.list': {
-        this.sendOk(req.id, { sessions: this.ctx.collectSessions() });
+        this.sendOk(req.id, { sessions: ctx.collectSessions() });
 
         return;
       }
       case 'agents.list': {
-        this.sendOk(req.id, { ...this.ctx.collectAgents() });
+        this.sendOk(req.id, { ...ctx.collectAgents() });
 
         return;
       }
       case 'dirs.list': {
-        this.sendOk(req.id, { dirs: await this.ctx.collectSpawnDirs() });
+        this.sendOk(req.id, { dirs: await ctx.collectSpawnDirs() });
 
         return;
       }
       case 'fleet.list': {
-        this.sendOk(req.id, { fleet: await this.ctx.collectFleet() });
+        this.sendOk(req.id, { fleet: await ctx.collectFleet() });
 
         return;
       }
       case 'session.spawn': {
-        this.applySpawn(req);
+        await this.applySpawn(req, ctx);
 
         return;
       }
       case 'daemon.quit': {
         this.sendOk(req.id, {});
-        this.ctx.quitDaemon();
+        ctx.quitDaemon();
 
         return;
       }
@@ -367,7 +525,7 @@ export class DaemonConnection {
         }
 
         const sessionID = parsed.data.session;
-        const updated = this.ctx.updateSession(sessionID, parsed.data.name, parsed.data.pinned);
+        const updated = ctx.updateSession(sessionID, parsed.data.name, parsed.data.pinned);
 
         if (updated === 'child_pin') {
           this.sendErr(
@@ -384,12 +542,12 @@ export class DaemonConnection {
         return;
       }
       case 'session.kill': {
-        await this.applySessionVerb(req, 'session.kill', this.ctx.killSession);
+        await this.applySessionVerb(req, 'session.kill', ctx.killSession);
 
         return;
       }
       case 'session.ack': {
-        await this.applySessionVerb(req, 'session.ack', this.ctx.ackSession);
+        await this.applySessionVerb(req, 'session.ack', ctx.ackSession);
 
         return;
       }
@@ -403,7 +561,7 @@ export class DaemonConnection {
         }
 
         const id = parsed.data.session;
-        const command = this.ctx.buildResumeCommand(id);
+        const command = ctx.buildResumeCommand(id);
 
         if (command === null) {
           this.sendErr(req.id, 'no_such_session', `no session '${id}'`);
@@ -424,7 +582,7 @@ export class DaemonConnection {
 
         const id = parsed.data.session;
 
-        const screen = await this.ctx.readSessionScreen(id);
+        const screen = await ctx.readSessionScreen(id);
 
         if (screen === 'missing') {
           this.sendErr(req.id, 'no_such_session', `no session '${id}'`);
@@ -446,7 +604,7 @@ export class DaemonConnection {
         }
 
         const sessionID = parsed.data.session;
-        const result = this.ctx.ejectSession(sessionID, parsed.data.prompt);
+        const result = ctx.ejectSession(sessionID, parsed.data.prompt);
 
         if (result === 'ok') {
           this.sendOk(req.id, {});
@@ -478,7 +636,7 @@ export class DaemonConnection {
         }
 
         const sessionID = parsed.data.session;
-        const adoptResult = this.ctx.adoptSession(sessionID, parsed.data.cols, parsed.data.rows);
+        const adoptResult = ctx.adoptSession(sessionID, parsed.data.cols, parsed.data.rows);
 
         if (adoptResult === 'ok') {
           this.sendOk(req.id, {});
@@ -499,7 +657,7 @@ export class DaemonConnection {
         return;
       }
       case 'session.attach': {
-        this.applyAttach(req);
+        this.applyAttach(req, ctx);
 
         return;
       }
@@ -512,43 +670,43 @@ export class DaemonConnection {
           return;
         }
 
-        this.ctx.detachSession(this, parsed.data.session);
+        ctx.detachSession(this, parsed.data.session);
         this.sendOk(req.id, {});
 
         return;
       }
       case 'session.input': {
-        this.applyInput(req);
+        this.applyInput(req, ctx);
 
         return;
       }
       case 'session.resize': {
-        this.applyResize(req);
+        this.applyResize(req, ctx);
 
         return;
       }
       case 'permission.respond': {
-        this.applyPermissionRespond(req);
+        this.applyPermissionRespond(req, ctx);
 
         return;
       }
       case 'session.message': {
-        await this.applySessionMessage(req);
+        await this.applySessionMessage(req, ctx);
 
         return;
       }
       case 'session.tap': {
-        this.applyTap(req);
+        this.applyTap(req, ctx);
 
         return;
       }
       case 'message.get': {
-        await this.applyMessageGet(req);
+        await this.applyMessageGet(req, ctx);
 
         return;
       }
       case 'message.ack': {
-        await this.applyMessageAck(req);
+        await this.applyMessageAck(req, ctx);
 
         return;
       }
@@ -562,23 +720,23 @@ export class DaemonConnection {
         }
 
         this.sendOk(req.id, {
-          restored: await this.ctx.restoreFleet(parsed.data.cols, parsed.data.rows),
+          restored: await ctx.restoreFleet(parsed.data.cols, parsed.data.rows),
         });
 
         return;
       }
       case 'session.get': {
-        await this.applySessionGet(req);
+        await this.applySessionGet(req, ctx);
 
         return;
       }
       case 'session.read': {
-        await this.applySessionRead(req);
+        await this.applySessionRead(req, ctx);
 
         return;
       }
       case 'events.read': {
-        await this.applyEventsRead(req);
+        await this.applyEventsRead(req, ctx);
 
         return;
       }
@@ -588,7 +746,7 @@ export class DaemonConnection {
     }
   }
 
-  private applySpawn(req: RequestMsg): void {
+  private async applySpawn(req: RequestMsg, ctx: DaemonContext): Promise<void> {
     const parsed = parseRequestParams('session.spawn', req.p);
 
     if (!parsed.ok) {
@@ -597,48 +755,78 @@ export class DaemonConnection {
       return;
     }
 
-    const cwd = parsed.data.cwd;
-    const name = parsed.data.name;
-    const agent: AgentID = parsed.data.agent ?? 'claude';
-
-    if (this.ctx.findAdapter(agent) === null) {
-      this.sendErr(req.id, 'unsupported', `no adapter for agent '${agent}'`);
+    const data = parsed.data;
+
+    // Every refusal is thrown from the plan, which runs only once a key is
+    // claimed: a retry of a held key answers from the key without checking
+    // anything again, and a refused spawn drops its claim.
+    const plan = (): SpawnParams => {
+      // The target goes first: a config or target problem is the cause a
+      // spawn reports, ahead of any agent check that problem can skew.
+      const target = ctx.resolveSpawnTarget(data.target);
+      const agent: AgentID = data.agent ?? 'claude';
+      const adapter = ctx.findAdapter(agent);
+      const entry = ctx.collectAgents().agents.find((candidate) => candidate.id === agent);
+
+      if (adapter === null || entry === undefined) {
+        throw new DaemonError('unsupported', `no adapter for agent '${agent}'`);
+      }
 
-      return;
-    }
+      // A stand-in adapter declares no binary to check, so only a profiled
+      // agent's missing binary refuses the spawn.
+      if (adapter.profile !== undefined && !entry.installed) {
+        throw new DaemonError(
+          'unsupported',
+          `agent '${agent}' is registered but not installed on this host`,
+        );
+      }
 
-    let parent: SessionID | null = null;
+      const overrides = parseSpawnOverrides(entry, { model: data.model, effort: data.effort });
 
-    if (parsed.data.parent !== undefined) {
-      const owner = this.ctx.collectSessions().find((s) => s.id === parsed.data.parent);
+      if (!overrides.ok) {
+        throw new DaemonError(overrides.code, overrides.message);
+      }
 
-      if (owner === undefined) {
-        this.sendErr(req.id, 'no_such_session', `no session '${parsed.data.parent}'`);
+      let parent: SessionID | null = null;
 
-        return;
-      }
+      if (data.parent !== undefined) {
+        const owner = ctx.collectSessions().find((s) => s.id === data.parent);
 
-      // A sub-session spawning a sub-session of its own lands beside it,
-      // so a set stays one level deep.
-      parent = owner.parent ?? owner.id;
-    }
+        if (owner === undefined) {
+          throw new DaemonError('no_such_session', `no session '${data.parent}'`);
+        }
 
-    const session = this.ctx.spawnSession({
-      cwd,
-      name: name === '' ? basename(cwd) : name,
-      prompt: parsed.data.prompt,
-      cols: parsed.data.cols,
-      rows: parsed.data.rows,
-      resume: parsed.data.resume,
-      namedBy: name === '' ? 'auto' : 'user',
-      agent,
-      parent,
-    });
+        // A sub-session spawning a sub-session of its own lands beside it,
+        // so a set stays one level deep.
+        parent = owner.parent ?? owner.id;
+      }
 
-    this.sendOk(req.id, { session });
+      return {
+        cwd: data.cwd,
+        name: data.name === '' ? basename(data.cwd) : data.name,
+        prompt: data.prompt,
+        cols: data.cols,
+        rows: data.rows,
+        resume: data.resume,
+        namedBy: data.name === '' ? 'auto' : 'user',
+        agent,
+        parent,
+        overrides: overrides.overrides,
+        target,
+      };
+    };
+
+    const keyed =
+      data.idempotencyKey === undefined
+        ? null
+        : { key: data.idempotencyKey, payloadHash: buildPayloadHash(data) };
+
+    const spawned = await ctx.spawnSession(plan, keyed, null);
+
+    this.sendOk(req.id, spawned);
   }
 
-  private applyAttach(req: RequestMsg): void {
+  private applyAttach(req: RequestMsg, ctx: DaemonContext): void {
     const parsed = parseRequestParams('session.attach', req.p);
 
     if (!parsed.ok) {
@@ -649,7 +837,7 @@ export class DaemonConnection {
 
     const sessionID = parsed.data.session;
 
-    const result = this.ctx.attachSession(this, sessionID, {
+    const result = ctx.attachSession(this, sessionID, {
       cols: parsed.data.cols,
       rows: parsed.data.rows,
     });
@@ -666,12 +854,12 @@ export class DaemonConnection {
       return;
     }
 
-    const dims = this.ctx.getEffectiveDims(sessionID);
+    const dims = ctx.getEffectiveDims(sessionID);
 
     this.sendOk(req.id, { cols: dims.cols, rows: dims.rows });
   }
 
-  private applyInput(req: RequestMsg): void {
+  private applyInput(req: RequestMsg, ctx: DaemonContext): void {
     const parsed = parseRequestParams('session.input', req.p);
 
     if (!parsed.ok) {
@@ -681,7 +869,7 @@ export class DaemonConnection {
     }
 
     const sessionID = parsed.data.session;
-    const result = this.ctx.writeSessionInput(sessionID, parsed.data.d);
+    const result = ctx.writeSessionInput(sessionID, parsed.data.d);
 
     if (result === 'missing') {
       this.sendErr(req.id, 'no_such_session', `no session '${sessionID}'`);
@@ -708,7 +896,7 @@ export class DaemonConnection {
     this.sendOk(req.id, {});
   }
 
-  private applyResize(req: RequestMsg): void {
+  private applyResize(req: RequestMsg, ctx: DaemonContext): void {
     const parsed = parseRequestParams('session.resize', req.p);
 
     if (!parsed.ok) {
@@ -719,9 +907,7 @@ export class DaemonConnection {
 
     const sessionID = parsed.data.session;
 
-    if (
-      !this.ctx.resizeSession(this, sessionID, { cols: parsed.data.cols, rows: parsed.data.rows })
-    ) {
+    if (!ctx.resizeSession(this, sessionID, { cols: parsed.data.cols, rows: parsed.data.rows })) {
       this.sendErr(req.id, 'bad_args', `not attached to session '${sessionID}'`);
 
       return;
@@ -730,7 +916,7 @@ export class DaemonConnection {
     this.sendOk(req.id, {});
   }
 
-  private applyPermissionRespond(req: RequestMsg): void {
+  private applyPermissionRespond(req: RequestMsg, ctx: DaemonContext): void {
     const parsed = parseRequestParams('permission.respond', req.p);
 
     if (!parsed.ok) {
@@ -741,7 +927,7 @@ export class DaemonConnection {
 
     const request = parsed.data.request;
     const decision = parsed.data.decision;
-    const result = this.ctx.answerPermission(request, decision);
+    const result = ctx.answerPermission(request, decision);
 
     switch (result) {
       case 'ok': {
@@ -765,7 +951,7 @@ export class DaemonConnection {
     }
   }
 
-  private async applySessionGet(req: RequestMsg): Promise<void> {
+  private async applySessionGet(req: RequestMsg, ctx: DaemonContext): Promise<void> {
     const parsed = parseRequestParams('session.get', req.p);
 
     if (!parsed.ok) {
@@ -776,7 +962,7 @@ export class DaemonConnection {
 
     const id = parsed.data.session;
 
-    const record = await this.ctx.readSessionRecord(id);
+    const record = await ctx.readSessionRecord(id);
 
     if (record === 'missing') {
       this.sendErr(req.id, 'no_such_session', `no session '${id}'`);
@@ -787,7 +973,7 @@ export class DaemonConnection {
     this.sendOk(req.id, { ...record });
   }
 
-  private async applySessionRead(req: RequestMsg): Promise<void> {
+  private async applySessionRead(req: RequestMsg, ctx: DaemonContext): Promise<void> {
     const parsed = parseRequestParams('session.read', req.p);
 
     if (!parsed.ok) {
@@ -811,7 +997,7 @@ export class DaemonConnection {
       from = { path: decoded.path, offset: decoded.offset };
     }
 
-    const read = await this.ctx.loadSessionTranscript(id, from, parsed.data.limit);
+    const read = await ctx.loadSessionTranscript(id, from, parsed.data.limit);
 
     if (read === 'missing') {
       this.sendErr(req.id, 'no_such_session', `no session '${id}'`);
@@ -830,7 +1016,7 @@ export class DaemonConnection {
     }
   }
 
-  private async applyEventsRead(req: RequestMsg): Promise<void> {
+  private async applyEventsRead(req: RequestMsg, ctx: DaemonContext): Promise<void> {
     const parsed = parseRequestParams('events.read', req.p);
 
     if (!parsed.ok) {
@@ -853,11 +1039,12 @@ export class DaemonConnection {
       afterID = decoded.id;
     }
 
-    const page = await this.ctx.readEvents(
+    const page = await ctx.readEvents(
       afterID,
       parsed.data.limit,
       parsed.data.waitMs,
       parsed.data.session ?? null,
+      null,
     );
 
     const last = page.events.at(-1);
@@ -870,7 +1057,7 @@ export class DaemonConnection {
     });
   }
 
-  private async applySessionMessage(req: RequestMsg): Promise<void> {
+  private async applySessionMessage(req: RequestMsg, ctx: DaemonContext): Promise<void> {
     const parsed = parseRequestParams('session.message', req.p);
 
     if (!parsed.ok) {
@@ -881,10 +1068,16 @@ export class DaemonConnection {
 
     const sessionID = parsed.data.session;
 
-    const result = await this.ctx.writeSessionMessage(
+    const keyed =
+      parsed.data.idempotencyKey === undefined
+        ? null
+        : { key: parsed.data.idempotencyKey, payloadHash: buildPayloadHash(parsed.data) };
+
+    const result = await ctx.writeSessionMessage(
       sessionID,
       parsed.data.from,
       parsed.data.text,
+      keyed,
     );
 
     if (result === 'missing') {
@@ -915,10 +1108,10 @@ export class DaemonConnection {
       return;
     }
 
-    this.sendOk(req.id, { message: result.id, status: result.status });
+    this.sendOk(req.id, result);
   }
 
-  private applyTap(req: RequestMsg): void {
+  private applyTap(req: RequestMsg, ctx: DaemonContext): void {
     const parsed = parseRequestParams('session.tap', req.p);
 
     if (!parsed.ok) {
@@ -928,7 +1121,7 @@ export class DaemonConnection {
     }
 
     const sessionID = parsed.data.session;
-    const result = this.ctx.attachTap(this, sessionID);
+    const result = ctx.attachTap(this, sessionID);
 
     if (result === 'missing') {
       this.sendErr(req.id, 'no_such_session', `no session '${sessionID}'`);
@@ -945,7 +1138,7 @@ export class DaemonConnection {
     this.sendOk(req.id, {});
   }
 
-  private async applyMessageGet(req: RequestMsg): Promise<void> {
+  private async applyMessageGet(req: RequestMsg, ctx: DaemonContext): Promise<void> {
     const parsed = parseRequestParams('message.get', req.p);
 
     if (!parsed.ok) {
@@ -956,7 +1149,7 @@ export class DaemonConnection {
 
     const messageID = parsed.data.message;
 
-    const view = await this.ctx.readMessage(messageID, parsed.data.waitMs);
+    const view = await ctx.readMessage(messageID, parsed.data.waitMs);
 
     if (view === null) {
       this.sendErr(req.id, 'bad_args', `no message '${messageID}'`);
@@ -981,7 +1174,7 @@ export class DaemonConnection {
     });
   }
 
-  private async applyMessageAck(req: RequestMsg): Promise<void> {
+  private async applyMessageAck(req: RequestMsg, ctx: DaemonContext): Promise<void> {
     const parsed = parseRequestParams('message.ack', req.p);
 
     if (!parsed.ok) {
@@ -993,7 +1186,7 @@ export class DaemonConnection {
     const sessionID = parsed.data.session;
     const messageID = parsed.data.message;
 
-    const result = await this.ctx.ackMessage(this, sessionID, messageID);
+    const result = await ctx.ackMessage(this, sessionID, messageID);
 
     if (result === 'not_tapping') {
       this.sendErr(req.id, 'bad_args', `this connection is not tapping session '${sessionID}'`);
@@ -1038,6 +1231,21 @@ export class DaemonConnection {
     const parsedHello = parseRequestParams('daemon.hello', req.p);
     const client = parsedHello.ok ? parsedHello.data.client : 'unknown client';
 
+    // A principal the handshake cannot read would otherwise leave the
+    // connection with the owner's reach.
+    if (!parsedHello.ok && req.p?.['principal'] !== undefined) {
+      this.sendErr(req.id, 'bad_args', parsedHello.message);
+
+      return false;
+    }
+
+    const principal = parsedHello.ok ? (parsedHello.data.principal ?? null) : null;
+
+    if (principal !== null) {
+      this.principal = principal;
+      this.access = this.ctx.buildTargetAccess(principal);
+    }
+
     if (req.v !== PROTOCOL_V) {
       this.sendErr(
         req.id,
@@ -1059,6 +1267,7 @@ export class DaemonConnection {
   private async sendHelloOk(id: number): Promise<void> {
     this.sendOk(id, {
       daemon: this.ctx.build,
+      daemonID: this.ctx.daemonID,
       limits: { maxLine: MAX_LINE, maxChunk: MAX_CHUNK },
       features: DAEMON_FEATURES,
       lastUsedAgent: await this.ctx.loadLastUsedAgent(),
@@ -1069,7 +1278,34 @@ export class DaemonConnection {
     this.queue.send(encodeMessage({ v: PROTOCOL_V, id, ok }));
   }
 
-  private sendErr(id: number, code: ErrorCode, msg: string): void {
-    this.queue.send(encodeMessage({ v: PROTOCOL_V, id, err: { code, msg } }));
+  private sendErr(
+    id: number,
+    code: ErrorCode,
+    msg: string,
+    data?: Readonly<Record<string, unknown>>,
+  ): void {
+    this.queue.send(
+      encodeMessage({
+        v: PROTOCOL_V,
+        id,
+        err: { code, msg, ...(data === undefined ? {} : { data }) },
+      }),
+    );
+  }
+}
+
+// The session an event belongs to, from its session id or the session it
+// adds, or null for an event of no session.
+function findEventSession(event: EventMsg): SessionID | null {
+  if (typeof event['s'] === 'string') {
+    return toSessionID(event['s']);
   }
+
+  const session = event['session'];
+
+  if (isRecord(session) && typeof session['id'] === 'string') {
+    return toSessionID(session['id']);
+  }
+
+  return null;
 }