@junejs/server 0.1.2 → 0.2.0

package/src/agent-durable.ts

@@ -17,24 +17,46 @@
 
 import {
   AgentSession,
+  FatalToolError,
+  grantAnswer,
+  ResumeAuthorizationError,
   withSystem,
-  type Broadcaster,
+  type Answerers,
+  type AuthorizeAnswer,
+  type InputAnnouncement,
+  type NoteKind,
+  type ChannelPolicy,
+  type EventSink,
+  type TurnEvent,
   type Model,
   type Msg,
   type Runtime,
+  type InboundEvent,
   type SessionStore,
+  type ProactiveTrigger,
   type Tool,
+  type TurnError,
+  type TurnFailurePhase,
 } from "@junejs/core/agent-runtime";
+import type { Principal } from "@junejs/core/context";
 import type { Resources } from "@junejs/core/resources";
+import { blobFileStore, type FileStore } from "@junejs/core/agent-files";
+import { observeTurnEvents } from "./turn-events";
 import {
   channelDispatch,
+  DeliverUnsupportedError,
+  actionToTool,
   resolveChannel,
   type AgentDefinition,
   type Channel,
   type ChannelContext,
   type ChannelFactory,
+  type ResumeDeliveryTarget,
 } from "@junejs/core/agent-config";
+import { connectAll, type Connection } from "@junejs/core/connections";
 import { ensureScope, runInScope } from "@junejs/db";
+import { isolateLocal } from "./isolate-local";
+import { assertCoreRuntimeVersion } from "./core-version";
 
 // ── minimal structural Cloudflare surface (no @cloudflare/workers-types dep) ──
 // SqlStorage row values are exactly what workerd's SQLite returns. Mirroring
@@ -58,6 +80,10 @@ export interface SqlStorage {
 export interface DurableStorage {
   sql: SqlStorage;
   transactionSync<T>(fn: () => T): T;
+  // Schedules the object's alarm() — the watchdog and retry for input-announcement delivery
+  // (#260). Optional so a storage without alarms (a test double) still works; delivery then
+  // waits for the next announcement, settled turn or rebuild.
+  setAlarm?(scheduledTime: number): unknown;
 }
 export interface DurableObjectState {
   storage: DurableStorage;
@@ -93,8 +119,8 @@ export class DoSessionStore implements SessionStore {
   messages(): Msg[] {
     return this.sql.exec<{ body: string }>("SELECT body FROM agent_messages ORDER BY seq").toArray().map((r) => JSON.parse(r.body));
   }
-  hasUserTurn(turnId: string): boolean {
-    return this.messages().some((m) => m.role === "user" && m.turnId === turnId);
+  hasOpeningMessage(turnId: string): boolean {
+    return this.messages().some((m) => (m.role === "user" || m.role === "trigger") && m.turnId === turnId);
   }
   getStep(id: string): unknown | undefined {
     const rows = this.sql.exec<{ output: string }>("SELECT output FROM agent_steps WHERE id = ?", id).toArray();
@@ -103,6 +129,9 @@ export class DoSessionStore implements SessionStore {
   putStep(id: string, output: unknown) {
     this.sql.exec("INSERT INTO agent_steps (id, output) VALUES (?, ?)", id, JSON.stringify(output));
   }
+  delStep(id: string) {
+    this.sql.exec("DELETE FROM agent_steps WHERE id = ?", id);
+  }
   getStatus(): string {
     const rows = this.sql.exec<{ v: string }>("SELECT v FROM agent_meta WHERE k = 'status'").toArray();
     return rows.length ? rows[0]!.v : "new";
@@ -110,18 +139,52 @@ export class DoSessionStore implements SessionStore {
   setStatus(s: string) {
     this.sql.exec("INSERT INTO agent_meta (k, v) VALUES ('status', ?) ON CONFLICT(k) DO UPDATE SET v = ?", s, s);
   }
+  // The externally-assigned session key (#75). A DO cannot read its own idFromName
+  // name, so the key arrives on the first routed request and is persisted here —
+  // surviving hibernation/eviction, where the constructor re-runs with no request
+  // in hand. Not part of core's SessionStore contract: only the DO seam needs it.
+  getSessionKey(): string | undefined {
+    const rows = this.sql.exec<{ v: string }>("SELECT v FROM agent_meta WHERE k = 'session_key'").toArray();
+    return rows.length ? rows[0]!.v : undefined;
+  }
+  setSessionKey(key: string) {
+    this.sql.exec("INSERT INTO agent_meta (k, v) VALUES ('session_key', ?) ON CONFLICT(k) DO UPDATE SET v = ?", key, key);
+  }
   tx<T>(fn: () => T): T {
     return this.storage.transactionSync(fn);
   }
+  // Session reset (#129): ARCHIVE messages/steps under the current generation (the audit
+  // trail — never deleted), clear the live tables, status → "new". The session key in
+  // agent_meta is deliberately untouched: the DO's identity survives its history. Archive
+  // tables + the generation counter are created lazily, so existing objects stay
+  // untouched until their first reset. seq keeps counting across generations (DELETE
+  // doesn't reset AUTOINCREMENT), so an archived (generation, seq) stays unique.
+  reset(inTx?: () => void): number {
+    return this.storage.transactionSync(() => {
+      const sql = this.sql;
+      sql.exec(`CREATE TABLE IF NOT EXISTS agent_messages_archive (generation INTEGER, seq INTEGER, body TEXT)`);
+      sql.exec(`CREATE TABLE IF NOT EXISTS agent_steps_archive (generation INTEGER, id TEXT, output TEXT)`);
+      const rows = this.sql.exec<{ v: string }>("SELECT v FROM agent_meta WHERE k = 'generation'").toArray();
+      const generation = rows.length ? Number(rows[0]!.v) : 0;
+      sql.exec("INSERT INTO agent_messages_archive (generation, seq, body) SELECT ?, seq, body FROM agent_messages", generation);
+      sql.exec("DELETE FROM agent_messages");
+      sql.exec("INSERT INTO agent_steps_archive (generation, id, output) SELECT ?, id, output FROM agent_steps", generation);
+      sql.exec("DELETE FROM agent_steps");
+      this.setStatus("new");
+      sql.exec("INSERT INTO agent_meta (k, v) VALUES ('generation', ?) ON CONFLICT(k) DO UPDATE SET v = ?", String(generation + 1), String(generation + 1));
+      inTx?.(); // writes into the fresh generation, committed with the archive (#260)
+      return generation;
+    });
+  }
   unwrap<H = unknown>(): H {
     return this.sql as unknown as H;
   }
 }
 
-class InProcBroadcaster implements Broadcaster {
-  private subs = new Set<(t: string) => void>();
-  publish(turnId: string) { this.subs.forEach((cb) => { try { cb(turnId); } catch { /* a bad subscriber must not break publish */ } }); }
-  subscribe(cb: (t: string) => void): () => void { this.subs.add(cb); return () => this.subs.delete(cb); }
+class InProcEventSink implements EventSink {
+  private subs = new Set<(e: TurnEvent) => void>();
+  emit(e: TurnEvent) { this.subs.forEach((cb) => { try { cb(e); } catch { /* a bad subscriber must not break emit */ } }); }
+  subscribe(cb: (e: TurnEvent) => void): () => void { this.subs.add(cb); return () => this.subs.delete(cb); }
 }
 
 // A DO can't run in-process subagents; a subagent there is a sibling DO (cross-DO
@@ -152,8 +215,52 @@ export type DoAgentDef = {
   model: Model;
   tools: Tool[];
   instructions?: string;
-  resources?: Resources;
+  // Per-channel-source turn policies (see AgentDefinition.channelInstructions):
+  // an overlay string, or a ChannelPolicy carrying overlay/overlayMode/denyTools
+  // (#149 — derived from agent-level instructions.<source>.md + surfaces config
+  // by assembleDurable). The shared agent branches by real inbound source, no
+  // userText marker.
+  channelInstructions?: Record<string, string | ChannelPolicy>;
+  // Channels whose CAPABILITY tools should be available to this session's turns. Their
+  // tools are built HERE, in the DO isolate, from `env` — because a channel's tool `run`
+  // is a closure (over the bot token, etc.) that can't cross the worker→DO RPC. This is
+  // the edge equivalent of defineAgent merging channel.tools() on native: pass the same
+  // channel factories you mount on the worker, plus this DO's env.
+  channels?: (Channel | ChannelFactory)[];
+  env?: unknown;
+  // A resolved bag, OR an env-driven — possibly async — provider
+  // (bindWorkerResources' shape): opening a D1 handle is async and a DO
+  // constructor cannot await, so a provider is resolved lazily at the first
+  // turn (once per DO instance) with this def's `env`.
+  resources?: Resources | ((env: unknown) => Promise<Resources> | Resources);
+  // Outbound connection DEFINITIONS (external MCP/OpenAPI servers). Wiring them
+  // is network I/O (connectAll), which a DO constructor cannot await — resolved
+  // lazily at the first turn, their tools merged into the agent's tool set
+  // before any session is constructed. The native equivalent happens at
+  // assembly (assembleAgent → connectAll).
+  connections?: Connection[];
   services?: unknown;
+  // Called on every turn.failed for this session — the app's seam for routing turn
+  // failures to its own telemetry (Sentry, a ledger, …). Providing it REPLACES the
+  // default console.error; if the hook throws (or an async hook rejects), the default
+  // log fires anyway (both errors), so a failure is never silent. `error` carries the
+  // full serialized failure (stack, cause chain — see TurnError, #96), and phase/step
+  // name the engine step that was in flight — for a DETACHED turn this hook is the
+  // only failure-surfacing path, so nothing may be flattened before it fires. It
+  // happens to run inside the failed turn's request scope today (turn.failed is
+  // emitted mid-turn and ALS propagates), but that is NOT contract — don't rely on
+  // ambient db/services; close over what you need.
+  onTurnError?: (failure: { turnId: string; error: TurnError; phase?: TurnFailurePhase; step?: string }) => void | Promise<void>;
+  // Decides a { policy } answerer of a parked requestInput at /resume (#261) — the same hook
+  // an AgentDefinition carries natively; assembleDurable passes agent.ts's through.
+  authorizeAnswer?: AuthorizeAnswer;
+  // Receives this session's input announcements (#260) — run inside the request scope, so it
+  // can write the app's cross-session index with the ambient db.
+  onInputAnnouncement?: (a: InputAnnouncement) => void | Promise<void>;
+  // Where this session's tools store the files they produce (docs/rfc-agent-files.md), and
+  // where host-side delivery reads them back. Default: the `blob` of `resources` (an R2
+  // bucket), under agent-files/. Without either, a tool's ctx.files.put fails the turn.
+  files?: FileStore;
 };
 
 // The agent runtime INSIDE a Durable Object. A plain class (constructor takes the
@@ -171,17 +278,288 @@ export type DoAgentDef = {
 //     fetch(req) { return this.agent.fetch(req); }
 //   }
 export class AgentDurableObject {
-  private session: AgentSession;
-  // Built from the DO's env in the constructor (this isolate), shared across turns —
-  // env is stable per isolate, like bindWorkerResources memoizes per worker isolate.
-  private readonly resources: Resources;
+  // The AgentSession is constructed LAZILY (#75): the DO is keyed externally by
+  // idFromName(`${agent}:${session}`) but cannot read its own name, so the true
+  // session key only exists on a routed request (the SESSION_HEADER durableFetch
+  // sets). First keyed request wins and persists the key (agent_meta) so it
+  // survives hibernation; key-less paths fall back to the persisted key, then
+  // "self" (the pre-#75 behavior, kept for backward compatibility).
+  private session: AgentSession | undefined;
+  private sessionKey: string | undefined;
+  private readonly name: string;
+  private readonly store: DoSessionStore;
+  private readonly sink: InProcEventSink;
+  private readonly model: Model;
+  private readonly tools: Tool[];
+  private readonly channels: Channel[];
+  private readonly channelInstructions?: Record<string, string | ChannelPolicy>;
+  // A bag is used as-is; a provider (bindWorkerResources' shape) is resolved
+  // lazily at the first turn with the def's env — opening a D1 handle is async
+  // and this constructor cannot await. Resolved once, shared across turns (env
+  // is stable per isolate, like bindWorkerResources memoizes per worker isolate).
+  private readonly resourcesInput: DoAgentDef["resources"];
+  private resourcesOpened: Promise<Resources> | undefined;
+  private readonly connectionsInput: Connection[] | undefined;
+  private connectionsOpened: Promise<void> | undefined;
+  private readonly doEnv: unknown;
   private readonly services: unknown;
+  private readonly authorizeAnswer?: AuthorizeAnswer;
+  private readonly onInputAnnouncement?: (a: InputAnnouncement) => void | Promise<void>;
+  private readonly storage: DurableStorage;
+  private readonly files: FileStore;
+  // Consecutive failed announcement deliveries (#260) — sets the alarm retry's backoff.
+  private announceFailures = 0;
+  private resolveResources(): Promise<Resources> {
+    return (this.resourcesOpened ??= Promise.resolve(
+      typeof this.resourcesInput === "function" ? this.resourcesInput(this.doEnv) : (this.resourcesInput ?? {}),
+    ));
+  }
+  // Wire outbound connections once (network I/O the constructor can't await):
+  // their tools merge into this.tools BEFORE any session is constructed — the
+  // ready() callers hoist this ahead of resolveSession. A failed connection is
+  // reported and skipped (connectAll never throws), matching native assembly.
+  private resolveConnections(): Promise<void> {
+    return (this.connectionsOpened ??= (async () => {
+      if (!this.connectionsInput?.length) return;
+      const { actions, report } = await connectAll(this.connectionsInput);
+      for (const r of report) {
+        if (r.error) console.error(`[june] agent "${this.name}": connection "${r.name}" (${r.url}) failed: ${r.error}`);
+      }
+      const seen = new Set(this.tools.map((t) => t.spec.name));
+      for (const a of actions) {
+        const tool = actionToTool(a);
+        if (seen.has(tool.spec.name)) {
+          throw new Error(`AgentDurableObject(${this.name}): duplicate tool name "${tool.spec.name}" from a connection — rename so dispatch is unambiguous.`);
+        }
+        seen.add(tool.spec.name);
+        this.tools.push(tool);
+      }
+    })());
+  }
+  // Everything a turn needs opened BEFORE its synchronous scope-and-subscribe
+  // section: resources (possibly an async provider) and outbound connections.
+  private async ready(): Promise<Resources> {
+    const [resources] = await Promise.all([this.resolveResources(), this.resolveConnections()]);
+    return resources;
+  }
   constructor(state: DurableObjectState, def: DoAgentDef) {
+    assertCoreRuntimeVersion(`AgentDurableObject(${def.name ?? "agent"})`); // #94: fail power-on, not mid-turn
     const store = new DoSessionStore(state.storage);
     const model = def.instructions ? withSystem(def.model, def.instructions) : def.model;
-    this.resources = def.resources ?? {};
+    this.resourcesInput = def.resources;
+    this.connectionsInput = def.connections;
+    this.doEnv = def.env;
     this.services = def.services;
-    this.session = new AgentSession(def.name ?? "agent", "self", store, new InProcBroadcaster(), model, def.tools, crossDoUnsupported);
+    this.authorizeAnswer = def.authorizeAnswer;
+    this.onInputAnnouncement = def.onInputAnnouncement;
+    this.storage = state.storage;
+    const name = def.name ?? "agent";
+    // The blob resource opens with the rest of resources, lazily — the store is installed
+    // on the session before then, and only a tool that stores a file opens it.
+    this.files =
+      def.files ??
+      blobFileStore(async () => {
+        const blob = (await this.resolveResources()).blob;
+        if (!blob) throw new FatalToolError(`agent "${name}": no file store — declare a blob resource (DoAgentDef.resources) or pass DoAgentDef.files`);
+        return blob;
+      });
+    // Failure observability (#76): a turn that dies after the fast-ACK has no other
+    // observable surface on the edge — the webhook already 200'd and runBackground
+    // swallows the rejection unless the channel wired onError. Subscribing HERE (the
+    // session sink) covers every turn path — turn(), /turn, /resume — with one seam.
+    // Default: console.error, which wrangler tail surfaces. An app onTurnError takes
+    // over reporting; if IT throws, fall back to the default so nothing goes silent.
+    // (InProcEventSink already guards emit against a throwing subscriber.)
+    const sink = new InProcEventSink();
+    // Announcement watchdog (#260): a park is committed inside a turn, after turn.started, so
+    // arming here comes before its announcement can commit — whichever path started the turn,
+    // a held turn drained later included. Resume, reset and a held inbound turn arm at their
+    // call sites (armWatchdog).
+    sink.subscribe((e) => {
+      if (e.type === "turn.started") this.armWatchdog();
+    });
+    sink.subscribe((e) => {
+      if (e.type !== "turn.failed") return;
+      // The stack already opens with the message; log it INSTEAD of the message line
+      // when present so wrangler tail shows one coherent trace, not the message twice.
+      const defaultLog = () =>
+        console.error(`[june] agent "${name}" turn ${e.turnId} failed${e.step ? ` at ${e.step}` : ""}: ${e.error.stack ?? e.error.message}${e.error.causeChain?.length ? `\ncaused by: ${e.error.causeChain.join(" ← ")}` : ""}`);
+      if (def.onTurnError) {
+        try {
+          const out = def.onTurnError({ turnId: e.turnId, error: e.error, phase: e.phase, step: e.step });
+          // An async hook (e.g. `await sendToSentry(...)`) types as void but returns a
+          // Promise — a rejection there must hit the same fallback as a sync throw, or
+          // the failure goes silent again (plus an unhandled rejection). No waitUntil
+          // keeper is needed here: unlike a Worker, a DO stays active while it has
+          // pending work/IO, and DurableObjectState.waitUntil is documented as a no-op —
+          // this .then subscription is what retains the promise.
+          if (out && typeof (out as Promise<void>).then === "function") {
+            (out as Promise<void>).then(undefined, (hookErr) => {
+              console.error(`[june] agent "${name}": onTurnError hook rejected:`, hookErr);
+              defaultLog();
+            });
+          }
+          return;
+        } catch (hookErr) {
+          console.error(`[june] agent "${name}": onTurnError hook threw:`, hookErr);
+        }
+      }
+      defaultLog();
+    });
+    // Merge the mounted channels' capability tools (built here from this DO's env, since a
+    // tool's `run` closure can't cross the RPC). The cross-channel source gate on each tool
+    // keeps a Slack tool inert during a Crisp turn, so merging all of them is safe. The
+    // resolved channels are also RETAINED (this.channels): a delivered turn (/turn?deliver=1)
+    // renders its reply through the source channel's deliver() from inside this DO.
+    const channels = (def.channels ?? []).map((c) => resolveChannel(c, def.env));
+    const channelTools = channels.flatMap((c) => c.tools?.() ?? []);
+    const tools: Tool[] = [...def.tools];
+    const seen = new Set(tools.map((t) => t.spec.name));
+    for (const t of channelTools) {
+      if (seen.has(t.spec.name)) throw new Error(`AgentDurableObject(${def.name ?? "agent"}): duplicate tool name "${t.spec.name}" from a channel — rename so dispatch is unambiguous.`);
+      seen.add(t.spec.name);
+      tools.push(t);
+    }
+    this.name = name;
+    this.store = store;
+    this.sink = sink;
+    this.model = model;
+    this.tools = tools;
+    this.channels = channels;
+    this.channelInstructions = def.channelInstructions;
+    // Orphan-policy check (#149): assembly can't validate surface keys against
+    // factory channels (they resolve only here, with env) — so warn now, once,
+    // when a policy's source matches no resolved channel. A policy that never
+    // fires is the old silent failure; a warning is its floor.
+    if (def.channelInstructions) {
+      const names = new Set(channels.map((c) => c.name));
+      for (const source of Object.keys(def.channelInstructions)) {
+        if (!names.has(source)) {
+          console.warn(`[june] agent "${name}": surface policy "${source}" matches no channel wired into this DO (${[...names].join(", ") || "none"}) — it will never fire.`);
+        }
+      }
+    }
+  }
+  // Resolve THE session for this DO: explicit key (from a routed request) → persisted
+  // key (a prior life learned it) → "self". A key that contradicts the persisted or
+  // live identity is a mis-route (or a key-less path was used first) — fail loudly:
+  // silently proceeding is exactly the per-conversation data corruption #75 hit.
+  private resolveSession(key?: string): AgentSession {
+    // Every entry point shares the session-key contract (turn({ session }) and hand-rolled
+    // SESSION_HEADER values included, not just durableFetch): an invalid key persisted here
+    // would bind an identity no routed request could ever address — an orphaned session.
+    if (key !== undefined) assertSessionKey(key);
+    // Live fast path — no storage read once the session exists: this method is the only
+    // writer of the persisted key, so within one life it cannot diverge from the live one.
+    if (this.session) {
+      if (key !== undefined && this.sessionKey !== key) {
+        throw new Error(
+          this.sessionKey === "self"
+            ? `agent "${this.name}": request session "${key}" arrived, but this session is bound to the placeholder "self" (first used without a real key) — carry the key on every path (route through durableFetch, or pass turn({ session }) on the direct API)`
+            : `agent "${this.name}": request session "${key}" does not match this object's session "${this.sessionKey}" — one DO is one session; address each session by its own key (durableFetch, or turn({ session }) on the direct API)`,
+        );
+      }
+      return this.session;
+    }
+    const stored = this.store.getSessionKey();
+    if (key !== undefined && stored !== undefined && key !== stored) {
+      throw new Error(`agent "${this.name}": request session "${key}" does not match this object's session "${stored}" — one DO is one session; address each session by its own key (durableFetch, or turn({ session }) on the direct API)`);
+    }
+    const resolved = key ?? stored ?? "self";
+    // "self" is deliberately NOT persisted — even when a caller passes it EXPLICITLY: it
+    // is a placeholder ("no identity externally assigned yet"), not an identity. Within
+    // one life a keyed request after a "self" binding is refused above — two concurrently
+    // active paths disagreeing is a live bug. But across eviction a keyed request ADOPTS
+    // the legacy transcript: that asymmetry IS the migration path from pre-keyed
+    // deployments, where a persisted "self" would 409 every keyed request forever.
+    if (key !== undefined && key !== "self" && stored === undefined) this.store.setSessionKey(key);
+    this.sessionKey = resolved;
+    this.session = new AgentSession(this.name, resolved, this.store, this.sink, this.model, this.tools, crossDoUnsupported, this.channelInstructions);
+    this.session.files = this.files;
+    // A held turn (#263) that asked for delivery is rendered through its source channel when
+    // it finally runs — possibly in a later life of this object, which is why the ask rides
+    // in the turn's hostContext and this hook is installed on every rebuild.
+    this.session.onDequeue = (heldTurnId, held) => {
+      if ((held.hostContext as { deliver?: boolean } | undefined)?.deliver && held.event) this.deliverHeld(this.session!, heldTurnId, held.event);
+    };
+    // Input announcements (#260): delivered in the request scope (the hook writes the app's
+    // index), and flushed on every rebuild — an earlier life may have committed a park and
+    // died before delivering it.
+    const announce = this.onInputAnnouncement;
+    if (announce) {
+      // ensureScope() here, not only in the request handlers: a session can first be rebuilt by
+      // a path that never wires async scope (/reset, /transcript, the direct API), and without it
+      // runInScope is a pass-through and the hook would see no ambient db.
+      this.session.onAnnounce = async (a) => {
+        await ensureScope();
+        const resources = await this.ready();
+        try {
+          await runInScope({ resources, services: this.services }, () => announce(a));
+        } catch (err) {
+          // The engine keeps the announcement and logs; retry it on the alarm, 5 s doubling
+          // to 5 min — a quiet session would otherwise hold it until its next activity.
+          this.scheduleAlarm(Math.min(5_000 * 2 ** this.announceFailures, 300_000));
+          this.announceFailures++;
+          throw err;
+        }
+        this.announceFailures = 0;
+      };
+      void this.session.flushAnnouncements();
+    }
+    return this.session;
+  }
+
+  // The Durable Object alarm (#260): delivers input announcements left undelivered — a hook
+  // that failed (its retry), or an object that died between committing one and delivering
+  // it (the watchdog). The shell forwards it — `alarm() { return this.agent.alarm(); }`;
+  // june build's does. Resolves the session like any key-less path (the persisted key),
+  // which rebuilds it after an eviction and flushes. Never rejects: a failed delivery
+  // reschedules itself through onAnnounce.
+  async alarm(): Promise<void> {
+    if (!this.onInputAnnouncement) return;
+    await this.resolveSession().flushAnnouncements();
+  }
+  // A watchdog alarm a minute out, armed BEFORE anything can commit an announcement (a
+  // turn starting, a resume, a reset, a held inbound turn): arming after the commit would
+  // leave exactly the window it exists for. A delivery that succeeds leaves it to find
+  // nothing.
+  private armWatchdog(): void {
+    if (this.onInputAnnouncement) this.scheduleAlarm(60_000);
+  }
+  // One alarm per object: the latest schedule wins.
+  private scheduleAlarm(inMs: number): void {
+    const failed = (err: unknown) => console.error(`[june] agent "${this.name}": could not schedule the announcement alarm — delivery waits for the next announcement, turn or rebuild:`, err);
+    try {
+      Promise.resolve(this.storage.setAlarm?.(Date.now() + inMs)).catch(failed);
+    } catch (err) {
+      failed(err);
+    }
+  }
+
+  // Render a held turn's reply through its source channel (#263), like /turn?deliver=1 does
+  // for a turn started now. Called from onDequeue, synchronously as the turn starts: the
+  // event subscription is taken HERE, before any event can emit, and buffers until the
+  // (async) resources are ready. Nothing may escape — there is no caller to report to; the
+  // log is the only surfacing path, as for any delivered render.
+  private deliverHeld(session: AgentSession, turnId: string, event: InboundEvent): void {
+    const logRenderFailure = (err: unknown) =>
+      console.error(`[june] agent "${this.name}": delivered render for held turn ${turnId} failed:`, err);
+    try {
+      const channel = this.channels.find((c) => c.name === event.source);
+      if (!channel?.deliver) {
+        logRenderFailure(new Error(`no deliver()-capable channel named "${event.source}" is wired into this DO — the held turn runs, but its reply is not rendered`));
+        return;
+      }
+      const it = observeTurnEvents(session, turnId)[Symbol.asyncIterator]();
+      const events: AsyncIterable<TurnEvent> = { [Symbol.asyncIterator]: () => it };
+      const target = { channelId: event.channelId, threadId: event.threadId, recipientUserId: event.user?.id, recipientTeamId: event.teamId };
+      this.ready()
+        .then((resources) => runInScope({ resources, services: this.services }, () => channel.deliver!(target, events, { session: this.sessionKey, files: this.files })))
+        .catch(logRenderFailure)
+        .finally(() => { void it.return?.(); });
+    } catch (err) {
+      logRenderFailure(err);
+    }
   }
   // Run the whole turn inside a request scope seeded from this DO's env, so ambient
   // `db`/`kv`/`blob` and `currentServices()` resolve inside a tool exactly as in a
@@ -190,30 +568,405 @@ export class AgentDurableObject {
   // Juno's batch-loader registry) can't leak across turns on a long-lived DO.
   // ensureScope() lazily wires node:async_hooks (workerd via nodejs_compat), as the
   // pipeline does; without it runInScope is a pass-through and ambient reads throw.
-  async turn(input: { turnId?: string; userText: string }): Promise<string> {
+  async turn(input: { turnId?: string; userText: string; event?: InboundEvent; trigger?: ProactiveTrigger; session?: string }): Promise<string> {
+    await ensureScope();
+    const resources = await this.ready();
+    const session = this.resolveSession(input.session);
+    return runInScope({ resources, services: this.services }, () => session.turn(input));
+  }
+  // Fire-and-forget for custom shells (#77): resolves once the turn is durably ACCEPTED;
+  // it then runs under the DO's own lifetime (a DO stays alive while it has pending
+  // work), not the caller's. No live consumer sees the result — failures surface via
+  // the default turn-failure log / onTurnError (#76).
+  async start(input: { turnId?: string; userText: string; event?: InboundEvent; trigger?: ProactiveTrigger; session?: string }): Promise<{ turnId: string }> {
     await ensureScope();
-    return runInScope({ resources: this.resources, services: this.services }, () => this.session.turn(input));
+    const resources = await this.ready();
+    const session = this.resolveSession(input.session);
+    return runInScope({ resources, services: this.services }, () => session.start(input));
   }
+  // An attributed note (#262) for custom shells — the direct sibling of the /note route. No
+  // scope needed: a note touches only the store.
+  note(input: { by: string; kind: NoteKind; text: string; session?: string }): Promise<{ noteId: string }> {
+    const { session, ...note } = input;
+    return this.resolveSession(session).note(note);
+  }
+  // Session reset (#129) for custom shells — the direct sibling of the /reset route. No
+  // scope needed: reset touches only the store (no tools run).
+  reset(opts?: { session?: string }): Promise<{ previousSession: string; generation: number }> {
+    const session = this.resolveSession(opts?.session);
+    this.armWatchdog(); // a reset can retire a park (#260)
+    return session.reset();
+  }
+  // Read-only: folds the durable log. When an identity exists (live, or persisted from a
+  // prior life) the session resolves and caches like any other path. Only a read on a
+  // NEVER-keyed object stays non-committal — caching there would bake "self" in as the
+  // identity and 409 a later keyed turn — so it folds through an ephemeral AgentSession.
   transcript() {
-    return this.session.transcript();
+    if (this.session) return this.session.transcript();
+    if (this.store.getSessionKey() !== undefined) return this.resolveSession().transcript();
+    return new AgentSession(this.name, "self", this.store, this.sink, this.model, this.tools, crossDoUnsupported, this.channelInstructions).transcript();
   }
-  // Default HTTP surface: POST …/turn runs a durable turn; GET …/transcript reads
-  // the log. The app can call turn()/transcript() directly instead.
+  // Default HTTP surface: POST …/turn STREAMS the turn's TurnEvents as SSE (start the
+  // turn in-scope, then stream from the session sink); GET …/transcript reads the log.
+  // The app can call turn()/transcript() directly instead (turn() awaits the final text).
   async fetch(req: Request): Promise<Response> {
     const url = new URL(req.url);
+    // The session key durableFetch stamped on the routed request (#75); absent on a
+    // hand-rolled fetch → the pre-#75 "self" fallback keeps old callers working.
+    const key = req.headers.get(SESSION_HEADER) ?? undefined;
     if (req.method === "POST" && url.pathname.endsWith("/turn")) {
-      const { userText, turnId } = (await req.json()) as { userText: string; turnId?: string };
-      return Response.json({ text: await this.turn({ userText, turnId }) });
+      const { userText, turnId, event, trigger, ifSuspended } = (await req.json()) as { userText: string; turnId?: string; event?: InboundEvent; trigger?: ProactiveTrigger; ifSuspended?: "reject" | "queue" };
+      await ensureScope();
+      // CANCEL-AND-REPLACE (#129): supersede every unfinished turn on this session before
+      // queuing this one (debounce). A mode flag like deliver/detach, so it rides the query
+      // string and composes with both. A suspended session still 409s below — replace
+      // never cancels a parked approval.
+      const replace = url.searchParams.get("replace") === "1";
+      // DELIVERED: like detach=1, the caller gets a 202 and goes away — but the reply is NOT
+      // dropped: this DO renders the turn's event stream through the source channel's own
+      // deliver() (the inbound renderer), under the DO's lifetime. Capability is checked
+      // BEFORE the turn starts — that ordering is DeliverUnsupportedError's contract at the
+      // surface: on a pre-start rejection the caller may fall back to consumer-side rendering
+      // without double-running the turn.
+      const wantsDeliver = url.searchParams.get("deliver") === "1";
+      const detached = url.searchParams.get("detach") === "1";
+      // HOLD (#263): only a caller with no live consumer may ask to be held — a streaming
+      // caller wants the reply now, and a held turn's reply comes after the park resolves.
+      if (ifSuspended === "queue" && !wantsDeliver && !detached) {
+        return Response.json({ error: `ifSuspended "queue" needs deliver=1 or detach=1: a held turn runs later, when no one is streaming it` }, { status: 400 });
+      }
+      if (ifSuspended === "queue" && replace) {
+        return Response.json({ error: `ifSuspended "queue" and replace=1 cannot be combined — replacing would drop held turns that were accepted` }, { status: 400 });
+      }
+      let deliverChannel: Channel | undefined;
+      if (wantsDeliver) {
+        if (!event?.channelId) {
+          return Response.json({ error: "deliver=1 needs an inbound event (event.channelId names the reply target)" }, { status: 400 });
+        }
+        deliverChannel = this.channels.find((c) => c.name === event.source);
+        if (!deliverChannel?.deliver) {
+          return Response.json(
+            { error: `agent "${this.name}": no deliver()-capable channel named "${event.source}" is wired into this DO (DoAgentDef.channels) — the turn was NOT started` },
+            { status: 501 },
+          );
+        }
+      }
+      // start() schedules the turn on the chain WITHIN the scope, so it runs with ambient
+      // db/services (ALS propagates to the .then continuation registered here); subscribing
+      // happens synchronously right after, before any event can emit. Resources resolve
+      // BEFORE this block — the section from start() to the subscription stays synchronous.
+      const resources = await this.ready();
+      let session: AgentSession;
+      let started: { turnId: string; queued?: true };
+      try {
+        session = this.resolveSession(key);
+        // `hostContext` tells onDequeue how to finish a held turn (#263): a delivered one is
+        // rendered through its source channel when it runs, exactly as it would be now.
+        // start() itself runs turns a restart left held ahead of this one.
+        this.armWatchdog(); // a held turn commits a "held" announcement without starting (#260)
+        started = runInScope({ resources, services: this.services }, () =>
+          session.start({ userText, turnId, event, trigger, replace, ifSuspended, hostContext: wantsDeliver ? { deliver: true } : undefined }));
+      } catch (err) {
+        // e.g. the session is suspended awaiting input, or the key mis-matches this
+        // object's identity — a client-resolvable conflict, not a crash
+        return Response.json({ error: err instanceof Error ? err.message : String(err) }, { status: 409 });
+      }
+      if (started.queued) return Response.json({ turnId: started.turnId, queued: true }, { status: 202 });
+      if (wantsDeliver) {
+        // Subscribe synchronously (same guarantee sseTurnStream relies on: start() scheduled
+        // the turn, no event can have emitted yet), then render under THIS DO's lifetime —
+        // the retained promise is pending work that keeps the DO alive, so a long turn's
+        // rendering survives however briefly the caller held its connection. The event is
+        // present (checked above); its author/thread are the reply target, exactly the
+        // surface the channel's inbound renderStream derives.
+        //
+        // Once start() has queued the turn, NOTHING here may escape: a throw would 500 the
+        // caller for a turn that runs anyway — the exact ambiguity delivered turns exist to
+        // remove. deliver() is app/third-party code that can throw synchronously before
+        // returning its promise, so it is deferred into the chain (the eager subscription
+        // above stays synchronous — that timing guarantee must not move); the try/catch
+        // backstops the subscription itself. Rendering failures have no live consumer —
+        // this log is their only surfacing path (the TURN's own failures already surface
+        // via the #76 sink subscription).
+        const logRenderFailure = (err: unknown) =>
+          console.error(`[june] agent "${this.name}": delivered render for turn ${started.turnId} failed:`, err);
+        try {
+          // Own the iterator here: observeTurnEvents subscribes EAGERLY, and a deliver()
+          // that throws before ever iterating would otherwise leave that subscription
+          // attached, buffering this turn's events forever. return() is idempotent, so
+          // closing in finally is safe whether deliver consumed the stream or died early.
+          const it = observeTurnEvents(session, started.turnId)[Symbol.asyncIterator]();
+          const events: AsyncIterable<TurnEvent> = { [Symbol.asyncIterator]: () => it };
+          const target = { channelId: event!.channelId, threadId: event!.threadId, recipientUserId: event!.user?.id, recipientTeamId: event!.teamId };
+          Promise.resolve()
+            .then(() => runInScope({ resources, services: this.services }, () => deliverChannel!.deliver!(target, events, { session: this.sessionKey, files: this.files })))
+            .catch(logRenderFailure)
+            .finally(() => { void it.return?.(); });
+        } catch (err) {
+          logRenderFailure(err);
+        }
+        return Response.json({ turnId: started.turnId }, { status: 202 });
+      }
+      // DETACHED (#77): the turn is accepted — 202 now, no stream. It keeps running under
+      // this DO's lifetime (alive while work is pending), so its duration is no longer
+      // bounded by however long the CALLER can hold a connection (the edge waitUntil
+      // ceiling). Nobody consumes the result; failures surface via the #76 log/hook.
+      if (detached) return Response.json({ turnId: started.turnId }, { status: 202 });
+      return new Response(sseTurnStream(session, started.turnId), { headers: SSE_HEADERS });
+    }
+    // Provide the input a suspended turn is waiting on and stream its continuation as SSE.
+    // NOTE: this default surface passes `by` straight from the body — the engine treats it as a
+    // VERIFIED identity, so the app must authenticate it upstream (e.g. take the user id from a
+    // signature-checked Slack interaction payload), never expose this endpoint raw to clients.
+    if (req.method === "POST" && url.pathname.endsWith("/resume")) {
+      const { turnId, inputId, input, by, principal, source, target } = (await req.json()) as {
+        turnId: string; inputId: string; input: unknown; by?: string; principal?: Principal;
+        source?: string; target?: ResumeDeliveryTarget;
+      };
+      await ensureScope();
+      // DELIVERED resume: like /turn?deliver=1, the caller 202s away and THIS DO renders the
+      // continuation through the source channel's deliverResume() — a long continuation no
+      // longer dies with the webhook isolate. Capability is checked BEFORE resume() applies
+      // the answer — the DeliverUnsupportedError contract at the surface: on a pre-effect
+      // refusal the caller may fall back to consumer-side rendering without double-answering
+      // (a second resume of an already-applied input would 409).
+      const wantsDeliver = url.searchParams.get("deliver") === "1";
+      let resumeChannel: Channel | undefined;
+      if (wantsDeliver) {
+        if (!source || !target?.channelId || !target.messageTs) {
+          return Response.json({ error: "resume deliver=1 needs `source` (the channel name) and `target` (channelId + messageTs of the prompt message)" }, { status: 400 });
+        }
+        resumeChannel = this.channels.find((c) => c.name === source);
+        if (!resumeChannel?.deliverResume) {
+          return Response.json(
+            { error: `agent "${this.name}": no deliverResume()-capable channel named "${source}" is wired into this DO (DoAgentDef.channels) — the answer was NOT applied` },
+            { status: 501 },
+          );
+        }
+      }
+      // Same discipline as /turn: resolve resources before the synchronous
+      // resume-then-subscribe section.
+      const resources = await this.ready();
+      let session: AgentSession;
+      try {
+        session = this.resolveSession(key);
+      } catch (err) {
+        return Response.json({ error: err instanceof Error ? err.message : String(err) }, { status: 409 });
+      }
+      // A { policy } answerer is the app's call (#261), made before the synchronous
+      // resume-then-subscribe section and inside the request scope (the hook may read the db).
+      // The hook is app code: a failure there (a db outage) is a 500 — never the 409 a
+      // resume-state conflict gets, which would tell the caller its answer is stale.
+      let granted: Answerers | undefined;
+      try {
+        granted = await runInScope({ resources, services: this.services }, () =>
+          grantAnswer(session, { turnId, inputId, by, principal }, this.authorizeAnswer));
+      } catch (err) {
+        console.error(`[june] agent "${this.name}": authorizeAnswer failed for input "${inputId}" of turn ${turnId}:`, err);
+        return Response.json({ error: `authorizeAnswer failed: ${err instanceof Error ? err.message : String(err)} — the answer was NOT applied` }, { status: 500 });
+      }
+      this.armWatchdog(); // the answer commits a "resolved" announcement (#260)
+      try {
+        runInScope({ resources, services: this.services }, () => session.resume(turnId, inputId, input, { by, granted }));
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        // 403: the resumer may not answer; 409: not suspended / wrong turn / wrong input id / key mismatch
+        return Response.json({ error: message }, { status: err instanceof ResumeAuthorizationError ? 403 : 409 });
+      }
+      if (wantsDeliver) {
+        // Same post-acceptance discipline as delivered turns: subscribe synchronously, render
+        // under this DO's lifetime, and let NOTHING escape past the accepted resume — the log
+        // is the render failure's only surfacing path (the TURN's own failures surface via
+        // the #76 sink subscription).
+        const logRenderFailure = (err: unknown) =>
+          console.error(`[june] agent "${this.name}": delivered resume render for turn ${turnId} failed:`, err);
+        try {
+          // Own the iterator (same rationale as the delivered-turn path): the eager
+          // subscription must be released even when deliverResume throws before
+          // iterating — e.g. its very first message update fails.
+          const it = observeTurnEvents(session, turnId)[Symbol.asyncIterator]();
+          const events: AsyncIterable<TurnEvent> = { [Symbol.asyncIterator]: () => it };
+          Promise.resolve()
+            .then(() => runInScope({ resources, services: this.services }, () => resumeChannel!.deliverResume!(target!, events, { session: this.sessionKey, files: this.files })))
+            .catch(logRenderFailure)
+            .finally(() => { void it.return?.(); });
+        } catch (err) {
+          logRenderFailure(err);
+        }
+        return Response.json({ turnId }, { status: 202 });
+      }
+      return new Response(sseTurnStream(session, turnId), { headers: SSE_HEADERS });
     }
-    if (url.pathname.endsWith("/transcript")) return Response.json({ transcript: this.transcript() });
-    return new Response("agent DO — POST /turn or GET /transcript", { status: 404 });
+    // SESSION RESET (#129): terminally retire this session's history — supersede unfinished
+    // turns, archive messages/steps under the current generation (the audit trail), and
+    // answer with the audit handle. The response waits for in-flight turns to unwind at
+    // their next checkpoint boundary (the reset op runs on the turn chain), which is fine:
+    // a DO stays alive while it has pending work.
+    if (req.method === "POST" && url.pathname.endsWith("/reset")) {
+      let session: AgentSession;
+      try {
+        session = this.resolveSession(key);
+      } catch (err) {
+        return Response.json({ error: err instanceof Error ? err.message : String(err) }, { status: 409 });
+      }
+      this.armWatchdog(); // a reset can retire a park (#260)
+      try {
+        return Response.json(await session.reset());
+      } catch (err) {
+        // e.g. a store without reset() — a caller-resolvable refusal, not a crash
+        return Response.json({ error: err instanceof Error ? err.message : String(err) }, { status: 409 });
+      }
+    }
+    // An attributed note (#262): body { by, kind, text } → { noteId }. A malformed body is a
+    // 400; a session-key conflict is a 409, like every other route.
+    if (req.method === "POST" && url.pathname.endsWith("/note")) {
+      let input: { by?: unknown; kind?: unknown; text?: unknown };
+      try {
+        input = (await req.json()) as typeof input;
+      } catch {
+        return Response.json({ error: "note: the body must be JSON { by, kind, text }" }, { status: 400 });
+      }
+      let session: AgentSession;
+      try {
+        session = this.resolveSession(key);
+      } catch (err) {
+        return Response.json({ error: err instanceof Error ? err.message : String(err) }, { status: 409 });
+      }
+      try {
+        return Response.json(await session.note(input as { by: string; kind: string; text: string }));
+      } catch (err) {
+        if (err instanceof TypeError) return Response.json({ error: err.message }, { status: 400 });
+        throw err;
+      }
+    }
+    if (url.pathname.endsWith("/transcript")) {
+      // A keyed read still conflict-checks (and may commit the key — it is authentic,
+      // idFromName routed it here); a key-less read stays non-committal via transcript().
+      if (key !== undefined) {
+        try {
+          return Response.json({ transcript: this.resolveSession(key).transcript() });
+        } catch (err) {
+          return Response.json({ error: err instanceof Error ? err.message : String(err) }, { status: 409 });
+        }
+      }
+      return Response.json({ transcript: this.transcript() });
+    }
+    return new Response("agent DO — POST /turn, POST /resume, POST /reset, POST /note, or GET /transcript", { status: 404 });
+  }
+}
+
+// ── SSE transport for the turn event stream (crosses the worker→DO isolate) ───
+// The DO streams a turn's TurnEvents as text/event-stream; the worker either pipes
+// that straight to a browser (live chat) or collapses it to the final text (channels).
+// no-store (not no-cache): an intermediary must NOT store chat/user content at all, and it
+// matches the repo's other SSE surface (dev-reload).
+const SSE_HEADERS = { "content-type": "text/event-stream", "cache-control": "no-store" };
+
+// A ReadableStream of SSE frames from a session's live event stream, scoped to one turn
+// and closed on its terminal event. Subscribes synchronously (no replay needed — we start
+// the turn then subscribe before any event can emit). A `:hb` comment heartbeat keeps the
+// connection alive across long model/tool gaps (a silent SSE stream gets culled by idle
+// timeouts on hosts/proxies) — cleared on terminal close and on cancel.
+function sseTurnStream(session: AgentSession, turnId: string): ReadableStream<Uint8Array> {
+  const enc = new TextEncoder();
+  let unsub: (() => void) | undefined;
+  let heartbeat: ReturnType<typeof setInterval> | undefined;
+  const stop = () => { unsub?.(); clearInterval(heartbeat); };
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      heartbeat = setInterval(() => {
+        try { controller.enqueue(enc.encode(":hb\n\n")); } catch { clearInterval(heartbeat); }
+      }, 20_000);
+      unsub = session.observe((e) => {
+        controller.enqueue(enc.encode(`data: ${JSON.stringify(e)}\n\n`));
+        // terminal for the STREAM: completed, failed, cancelled, OR suspended (input.requested
+        // → the turn parked; the stream ends and a later /resume opens a fresh continuation stream).
+        if (e.type === "turn.completed" || e.type === "turn.failed" || e.type === "turn.cancelled" || e.type === "input.requested") { stop(); controller.close(); }
+      }, { turnId });
+    },
+    cancel() { stop(); },
+  });
+}
+
+// Consume an SSE turn stream to its terminal state: the final text, or throw on failure.
+// The non-streaming path (channels, a JSON chat response) uses this. Guards a non-SSE /
+// body-less upstream response (a misroute or an error) into a clear error, not a TypeError.
+export async function sseTurnFinalText(res: Response): Promise<string> {
+  const ct = res.headers.get("content-type") ?? "";
+  if (!res.body || !ct.includes("text/event-stream")) {
+    const detail = res.body ? (await res.text()).slice(0, 200) : "no body";
+    throw new Error(`turn stream: expected an SSE response, got ${ct || "no content-type"} (status ${res.status}): ${detail}`);
+  }
+  const reader = res.body.getReader();
+  const dec = new TextDecoder();
+  let buf = "";
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (value) buf += dec.decode(value, { stream: true });
+    let i: number;
+    while ((i = buf.indexOf("\n\n")) >= 0) {
+      const line = buf.slice(0, i).split("\n").find((l) => l.startsWith("data:"));
+      buf = buf.slice(i + 2);
+      if (!line) continue;
+      const e = JSON.parse(line.slice(5).trim()) as TurnEvent;
+      if (e.type === "turn.completed") return e.text;
+      if (e.type === "turn.failed") throw new Error(e.error.message, { cause: e.error }); // full TurnError rides along
+      if (e.type === "turn.cancelled") throw new Error(`turn ${e.turnId} was cancelled (${e.reason})`);
+    }
+    if (done) break;
+  }
+  throw new Error("turn stream ended without a terminal event");
+}
+
+// Parse an SSE turn response into the stream of TurnEvents (skipping `:hb` heartbeats).
+// The streaming consumer (a channel's render path) iterates this to drive live UI.
+export async function* sseTurnEvents(res: Response): AsyncIterable<TurnEvent> {
+  const ct = res.headers.get("content-type") ?? "";
+  if (!res.body || !ct.includes("text/event-stream")) {
+    const detail = res.body ? (await res.text()).slice(0, 200) : "no body";
+    throw new Error(`turn stream: expected an SSE response, got ${ct || "no content-type"} (status ${res.status}): ${detail}`);
+  }
+  const reader = res.body.getReader();
+  const dec = new TextDecoder();
+  let buf = "";
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (value) buf += dec.decode(value, { stream: true });
+    let i: number;
+    while ((i = buf.indexOf("\n\n")) >= 0) {
+      const line = buf.slice(0, i).split("\n").find((l) => l.startsWith("data:"));
+      buf = buf.slice(i + 2);
+      if (line) yield JSON.parse(line.slice(5).trim()) as TurnEvent;
+    }
+    if (done) break;
+  }
+}
+
+// The header durableFetch stamps the session key on (#75). A DO cannot read its own
+// idFromName name, so this is how the externally-assigned session identity crosses
+// into the object — exported so a custom shell that bypasses durableFetch can set it.
+export const SESSION_HEADER = "x-june-session";
+
+// A session key rides an HTTP header (SESSION_HEADER) and the DO name (idFromName) —
+// reject values that can't: CR/LF would be header injection, and Headers.set throws a
+// bare TypeError on control/non-ASCII bytes, turning a bad client value into an opaque
+// 500 deep inside durableFetch. Non-empty printable ASCII is the contract.
+const SESSION_KEY_RE = /^[\x20-\x7E]+$/;
+function assertSessionKey(session: string) {
+  if (typeof session !== "string" || !SESSION_KEY_RE.test(session)) {
+    throw new Error(`invalid session key ${JSON.stringify(session)} — a session key must be a non-empty printable-ASCII string (it rides an HTTP header and the DO name)`);
   }
 }
 
 // Worker-side routing: address a session's DO by (agent, session) and forward the
-// request to it. `env.AGENT` is the DO namespace binding.
+// request to it. `env.AGENT` is the DO namespace binding. The session key rides a
+// header (not the body): one seam covers /turn, /resume, and /transcript without
+// touching any body contract, and an older DO simply ignores it.
 export function durableFetch(namespace: DurableObjectNamespace, agent: string, session: string, req: Request): Promise<Response> {
-  return namespace.get(namespace.idFromName(`${agent}:${session}`)).fetch(req);
+  assertSessionKey(session);
+  const headers = new Headers(req.headers);
+  headers.set(SESSION_HEADER, session);
+  return namespace.get(namespace.idFromName(`${agent}:${session}`)).fetch(new Request(req, { headers }));
 }
 
 // The EDGE agent surface for June's router: route the chat endpoint to the
@@ -235,13 +988,26 @@ export function durableAgentSurface(
     const namespace = getNamespace();
     if (!namespace) return null; // no DO binding → not mounted here
     const { message, session } = (await req.json()) as { message: string; session?: string };
-    // Forward to the session's DO on its /turn contract (AgentDurableObject.fetch).
-    return durableFetch(
+    // `session` is CLIENT input here — an un-headerable value must be a clear 400, not
+    // the opaque 500 assertSessionKey would become this deep in the worker.
+    if (session !== undefined) {
+      try {
+        assertSessionKey(session);
+      } catch (err) {
+        return Response.json({ error: err instanceof Error ? err.message : String(err) }, { status: 400 });
+      }
+    }
+    // Forward to the session's DO on its /turn contract — which now STREAMS SSE. A client
+    // that asks for the stream (Accept: text/event-stream) gets live TurnEvents piped
+    // through; otherwise collapse to the final { text } (the prior JSON contract).
+    const res = await durableFetch(
       namespace,
       opts.agentName,
       session ?? "default",
       new Request("https://do/turn", { method: "POST", body: JSON.stringify({ userText: message }) }),
     );
+    if (req.headers.get("accept")?.includes("text/event-stream")) return res;
+    return Response.json({ text: await sseTurnFinalText(res) });
   };
 }
 
@@ -271,13 +1037,68 @@ export function durableAgentSurface(
 // fails in the background — surfaced via the channel's onError IF one is configured,
 // otherwise swallowed (runBackground never rejects). The app is expected to bind
 // env.AGENT when it mounts channels. Returns null for unclaimed requests.
+// The services bag, memoized per (env object, agentName).
+//
+// Why that key. `env` identity is what makes the memo survive: a worker builds
+// the surface inside `fetch`, so the only thing stable across requests is the
+// env object the host hands in — and NOT the provider function, which the
+// documented shape (`services: (e) => makeServices(e)`) recreates on every
+// fetch. But env alone is too coarse: two surfaces mounted in one worker over
+// the same env would then share whichever bag was built first, making the
+// result depend on mount order. `agentName` is the surface's own stable
+// identity, so it partitions them. (One agent must therefore have ONE services
+// provider — mounting the same agentName twice with different providers is
+// incoherent and keeps the first bag.)
+//
+// Held in an isolateLocal so duplicate module instances (workspace symlinks)
+// share one cache; the outer WeakMap is keyed by env so a host handing out
+// fresh env objects gets fresh bags instead of a leak. A non-object env (tests
+// passing a primitive) skips memoization rather than throwing.
+function resolveServices(
+  factory: ((env: unknown) => unknown) | undefined,
+  env: unknown,
+  agentName: string,
+): unknown {
+  if (!factory) return undefined;
+  if (typeof env !== "object" || env === null) return factory(env);
+  const cache = isolateLocal(
+    "june.durableChannelSurface.services",
+    () => new WeakMap<object, Map<string, unknown>>(),
+  );
+  let perAgent = cache.get(env);
+  if (!perAgent) {
+    perAgent = new Map<string, unknown>();
+    cache.set(env, perAgent);
+  }
+  if (!perAgent.has(agentName)) perAgent.set(agentName, factory(env));
+  return perAgent.get(agentName);
+}
+
 export function durableChannelSurface(
   getNamespace: () => DurableObjectNamespace | undefined,
   opts: {
     agentName: string;
     channels: (Channel | ChannelFactory)[];
     env: unknown;
+    // The app's services factory — the SAME one AgentDurableObject uses — resolved HERE
+    // (worker isolate) and exposed to channel hooks as ctx.services. Channel hooks run at
+    // the edge, outside the DO, so they can't read the DO's ambient currentServices(); this
+    // gives them the same DI bag.
+    //
+    // Called once per (env object, agentName) — NOT once per surface. A worker
+    // typically constructs the surface inside `fetch` (env only exists inside an
+    // invocation), so resolving per construction rebuilt every client on every
+    // request and any cache the bag held could never hit. Memoizing on env
+    // identity fixes that; see resolveServices above for why the key is env ×
+    // agentName and not the provider function. Practical consequences: the
+    // provider must be a function of `env` alone, it runs again whenever the
+    // host hands in a different env object (a new isolate, or a test), and one
+    // agentName must have one provider.
+    services?: (env: unknown) => unknown;
     waitUntil?: (p: Promise<unknown>) => void;
+    // Where the channels read the files a turn attached (docs/rfc-agent-files.md) — the
+    // same storage the Durable Object's tools write, opened from this isolate's env.
+    files?: FileStore;
   },
 ): (req: Request) => Promise<Response | null> {
   const resolved = opts.channels.map((c) => resolveChannel(c, opts.env));
@@ -285,7 +1106,9 @@ export function durableChannelSurface(
     // A minimal but complete AgentDefinition — channels only read ctx.agent.name; the
     // full def isn't present in the worker (tools/model live in the DO).
     agent: { name: opts.agentName, instructions: "", tools: [], skills: [], channels: [], connections: [] } satisfies AgentDefinition,
+    services: resolveServices(opts.services, opts.env, opts.agentName),
     waitUntil: opts.waitUntil,
+    files: opts.files,
     run: async (message, o) => {
       const namespace = getNamespace();
       if (!namespace) throw new Error("durableChannelSurface: no Durable Object namespace bound (env.AGENT)");
@@ -293,11 +1116,156 @@ export function durableChannelSurface(
         namespace,
         opts.agentName,
         o?.session ?? "default",
-        new Request("https://do/turn", { method: "POST", body: JSON.stringify({ userText: message, turnId: o?.turnId }) }),
+        new Request(`https://do/turn${o?.replace ? "?replace=1" : ""}`, { method: "POST", body: serializeTurn(message, o) }),
+      );
+      // /turn streams SSE; the simple path collapses it to the final text.
+      return sseTurnFinalText(res);
+    },
+    // FIRE-AND-FORGET (#77): POST /turn?detach=1 — the DO 202s once the turn is accepted
+    // and runs it under its OWN lifetime. This is how a shadow/observe hook (onEvent →
+    // assessment turn, reply dropped) escapes the edge waitUntil ceiling that killed
+    // 24–38s turns in production: nothing holds the edge open while the turn runs.
+    runDetached: async (message, o) => {
+      const namespace = getNamespace();
+      if (!namespace) throw new Error("durableChannelSurface: no Durable Object namespace bound (env.AGENT)");
+      const res = await durableFetch(
+        namespace,
+        opts.agentName,
+        o?.session ?? "default",
+        new Request(`https://do/turn?detach=1${o?.replace ? "&replace=1" : ""}`, { method: "POST", body: serializeTurn(message, o) }),
       );
-      const { text } = (await res.json()) as { text: string };
-      return text;
+      if (res.status !== 202) {
+        const detail = (await res.text()).slice(0, 200);
+        throw new Error(`runDetached: turn was not accepted (status ${res.status}): ${detail}`);
+      }
+      return (await res.json()) as { turnId: string; queued?: true };
+    },
+    // DELIVERED: runDetached's reply-bearing sibling — the DO runs the turn AND renders its
+    // reply through the source channel's deliver() under its OWN lifetime, so a reply-bearing
+    // turn escapes the edge waitUntil ceiling exactly as a shadow turn does. A 501 means the
+    // DO refused BEFORE starting the turn (the channel isn't wired there / has no deliver) —
+    // surfaced as DeliverUnsupportedError, the one rejection a channel may answer with a
+    // consumer-side rendering fallback without double-running the turn.
+    runDelivered: async (message, o) => {
+      const namespace = getNamespace();
+      if (!namespace) throw new Error("durableChannelSurface: no Durable Object namespace bound (env.AGENT)");
+      const res = await durableFetch(
+        namespace,
+        opts.agentName,
+        o?.session ?? "default",
+        new Request(`https://do/turn?deliver=1${o?.replace ? "&replace=1" : ""}`, { method: "POST", body: serializeTurn(message, o) }),
+      );
+      if (res.status === 501) {
+        throw new DeliverUnsupportedError(`runDelivered: ${((await res.json().catch(() => undefined)) as { error?: string } | undefined)?.error ?? "the turn host cannot deliver this turn"}`);
+      }
+      if (res.status !== 202) {
+        const detail = (await res.text()).slice(0, 200);
+        throw new Error(`runDelivered: delivered turn was not accepted (status ${res.status}): ${detail}`);
+      }
+      return (await res.json()) as { turnId: string; queued?: true };
+    },
+    // The LIVE path: hand the channel the TurnEvent stream so it can render as the turn runs.
+    runStream: async function* (message, o) {
+      const namespace = getNamespace();
+      if (!namespace) throw new Error("durableChannelSurface: no Durable Object namespace bound (env.AGENT)");
+      const res = await durableFetch(
+        namespace,
+        opts.agentName,
+        o?.session ?? "default",
+        new Request(`https://do/turn${o?.replace ? "?replace=1" : ""}`, { method: "POST", body: serializeTurn(message, o) }),
+      );
+      yield* sseTurnEvents(res);
+    },
+    // Resume a parked turn on its session's DO and stream the continuation.
+    resumeStream: async function* (o) {
+      const namespace = getNamespace();
+      if (!namespace) throw new Error("durableChannelSurface: no Durable Object namespace bound (env.AGENT)");
+      const res = await durableFetch(
+        namespace,
+        opts.agentName,
+        o.session ?? "default",
+        new Request("https://do/resume", { method: "POST", body: serializeResume(o) }),
+      );
+      yield* sseTurnEvents(res);
+    },
+    // DELIVERED resume (runDelivered's sibling for the HITL leg): the DO applies the answer
+    // AND renders the continuation through the source channel's deliverResume() under its
+    // OWN lifetime. A 501 means the DO refused BEFORE applying the answer (channel not
+    // wired there / no deliverResume) — surfaced as DeliverUnsupportedError, the one
+    // rejection a channel may answer with a consumer-side fallback without double-answering.
+    // Engine rejections (403 unauthorized clicker / 409 stale-or-double click) throw as
+    // ordinary errors, mirroring what resumeStream's first pull would do.
+    resumeDelivered: async (o) => {
+      const namespace = getNamespace();
+      if (!namespace) throw new Error("durableChannelSurface: no Durable Object namespace bound (env.AGENT)");
+      const res = await durableFetch(
+        namespace,
+        opts.agentName,
+        o.session ?? "default",
+        new Request("https://do/resume?deliver=1", { method: "POST", body: serializeResume(o) }),
+      );
+      if (res.status === 501) {
+        throw new DeliverUnsupportedError(`resumeDelivered: ${((await res.json().catch(() => undefined)) as { error?: string } | undefined)?.error ?? "the turn host cannot deliver this continuation"}`);
+      }
+      if (res.status !== 202) {
+        const detail = (await res.text()).slice(0, 200);
+        throw new Error(`resumeDelivered: resume was not accepted (status ${res.status}): ${detail}`);
+      }
+      return (await res.json()) as { turnId: string };
+    },
+    // SESSION RESET (#129): retire the session's history on its DO. The response carries
+    // the audit handle ({ previousSession, generation }); a 409 (store without reset(),
+    // key mismatch) surfaces as an ordinary error — there is no fallback to invent.
+    resetSession: async (o) => {
+      const namespace = getNamespace();
+      if (!namespace) throw new Error("durableChannelSurface: no Durable Object namespace bound (env.AGENT)");
+      const res = await durableFetch(
+        namespace,
+        opts.agentName,
+        o?.session ?? "default",
+        new Request("https://do/reset", { method: "POST" }),
+      );
+      if (!res.ok) {
+        const detail = (await res.text()).slice(0, 200);
+        throw new Error(`resetSession: reset was not accepted (status ${res.status}): ${detail}`);
+      }
+      return (await res.json()) as { previousSession: string; generation: number };
     },
   };
   return channelDispatch(resolved, ctx);
 }
+
+// Serialize a turn for the /turn RPC body. InboundEvent.raw is `unknown` — the
+// untouched platform payload — so a (third-party) channel could attach something
+// JSON.stringify chokes on (a circular object, a BigInt). raw isn't needed to route or
+// run the turn, so on a serialization failure we drop it rather than let an
+// unserializable payload take down turn forwarding entirely. (raw is optional on
+// InboundEvent precisely because it may not survive this boundary.)
+// Serialize a /resume RPC body. `input` (the human's answer) and `principal` (the resumer,
+// whose extra fields are `unknown`) come from a (third-party) host and could hold something
+// JSON.stringify chokes on (BigInt, circular). Unlike serializeTurn's `raw`, neither is
+// droppable: resuming without them answers wrongly or as the wrong person. So fail loudly,
+// naming the field that failed, rather than corrupt the resume.
+function serializeResume(o: { turnId: string; inputId: string; input: unknown; by?: string; principal?: Principal; source?: string; target?: ResumeDeliveryTarget }): string {
+  try {
+    return JSON.stringify({ turnId: o.turnId, inputId: o.inputId, input: o.input, by: o.by, principal: o.principal, source: o.source, target: o.target });
+  } catch (err) {
+    const culprit = (["input", "principal"] as const).find((field) => {
+      try { JSON.stringify(o[field]); return false; } catch { return true; }
+    }) ?? "payload";
+    // API-neutral prefix: this serializer backs both resumeStream and resumeDelivered.
+    throw new Error(`resume: ${culprit} is not JSON-serializable (${(err as Error).message}) — a resume must round-trip to the DO`);
+  }
+}
+
+// `trigger` is ProactiveTrigger — plain strings by construction — so only event.raw can make
+// the stringify throw; the fallback that strips it stays sufficient.
+function serializeTurn(userText: string, o?: { turnId?: string; event?: InboundEvent; trigger?: ProactiveTrigger; ifSuspended?: "reject" | "queue" }): string {
+  const payload = { userText, turnId: o?.turnId, event: o?.event, trigger: o?.trigger, ifSuspended: o?.ifSuspended };
+  try {
+    return JSON.stringify(payload);
+  } catch {
+    const event = o?.event ? { ...o.event, raw: undefined } : undefined;
+    return JSON.stringify({ ...payload, event });
+  }
+}