@junejs/server 1.0.0-dev.29 → 1.0.0-dev.42

package/src/agent-durable.ts

@@ -17,8 +17,13 @@
 
 import {
   AgentSession,
+  grantAnswer,
   ResumeAuthorizationError,
   withSystem,
+  type Answerers,
+  type AuthorizeAnswer,
+  type InputAnnouncement,
+  type NoteKind,
   type ChannelPolicy,
   type EventSink,
   type TurnEvent,
@@ -32,6 +37,7 @@ import {
   type TurnError,
   type TurnFailurePhase,
 } from "@junejs/core/agent-runtime";
+import type { Principal } from "@junejs/core/context";
 import type { Resources } from "@junejs/core/resources";
 import { observeTurnEvents } from "./turn-events";
 import {
@@ -72,6 +78,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;
@@ -147,7 +157,7 @@ export class DoSessionStore implements SessionStore {
   // 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(): number {
+  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)`);
@@ -160,6 +170,7 @@ export class DoSessionStore implements SessionStore {
       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;
     });
   }
@@ -238,6 +249,12 @@ export type DoAgentDef = {
   // 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>;
 };
 
 // The agent runtime INSIDE a Durable Object. A plain class (constructor takes the
@@ -280,6 +297,11 @@ export class AgentDurableObject {
   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;
+  // 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 ?? {}),
@@ -321,6 +343,9 @@ export class AgentDurableObject {
     this.connectionsInput = def.connections;
     this.doEnv = def.env;
     this.services = def.services;
+    this.authorizeAnswer = def.authorizeAnswer;
+    this.onInputAnnouncement = def.onInputAnnouncement;
+    this.storage = state.storage;
     const name = def.name ?? "agent";
     // 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
@@ -330,6 +355,13 @@ export class AgentDurableObject {
     // 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
@@ -427,8 +459,91 @@ export class AgentDurableObject {
     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);
+    // 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 })))
+        .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
   // route loader. `locals` is intentionally NOT set here: a fresh scope object per
@@ -452,10 +567,18 @@ export class AgentDurableObject {
     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 }> {
-    return this.resolveSession(opts?.session).reset();
+    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
@@ -475,7 +598,7 @@ export class AgentDurableObject {
     // 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, event, trigger } = (await req.json()) as { userText: string; turnId?: string; event?: InboundEvent; trigger?: ProactiveTrigger };
+      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
@@ -489,6 +612,15 @@ export class AgentDurableObject {
       // 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) {
@@ -508,15 +640,21 @@ export class AgentDurableObject {
       // BEFORE this block — the section from start() to the subscription stays synchronous.
       const resources = await this.ready();
       let session: AgentSession;
-      let started: { turnId: string };
+      let started: { turnId: string; queued?: true };
       try {
         session = this.resolveSession(key);
-        started = runInScope({ resources, services: this.services }, () => session.start({ userText, turnId, event, trigger, replace }));
+        // `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 —
@@ -556,7 +694,7 @@ export class AgentDurableObject {
       // 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 (url.searchParams.get("detach") === "1") return Response.json({ turnId: started.turnId }, { status: 202 });
+      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.
@@ -564,8 +702,8 @@ export class AgentDurableObject {
     // 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, source, target } = (await req.json()) as {
-        turnId: string; inputId: string; input: unknown; by?: string;
+      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();
@@ -595,7 +733,24 @@ export class AgentDurableObject {
       let session: AgentSession;
       try {
         session = this.resolveSession(key);
-        runInScope({ resources, services: this.services }, () => session.resume(turnId, inputId, input, { by }));
+      } 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
@@ -637,6 +792,7 @@ export class AgentDurableObject {
       } 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) {
@@ -644,6 +800,28 @@ export class AgentDurableObject {
         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().
@@ -656,7 +834,7 @@ export class AgentDurableObject {
       }
       return Response.json({ transcript: this.transcript() });
     }
-    return new Response("agent DO — POST /turn, POST /resume, POST /reset, or GET /transcript", { status: 404 });
+    return new Response("agent DO — POST /turn, POST /resume, POST /reset, POST /note, or GET /transcript", { status: 404 });
   }
 }
 
@@ -939,7 +1117,7 @@ export function durableChannelSurface(
         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 };
+      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
@@ -963,7 +1141,7 @@ export function durableChannelSurface(
         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 };
+      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) {
@@ -1042,23 +1220,27 @@ export function durableChannelSurface(
 // 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` is `unknown` — the human's answer — so a
-// (third-party) host could hand us something JSON.stringify chokes on (BigInt, circular).
-// Unlike serializeTurn's `raw`, `input` is essential: silently dropping it would resume the
-// turn with the wrong answer. So fail loudly with a clear message rather than corrupt the resume.
-function serializeResume(o: { turnId: string; inputId: string; input: unknown; by?: string; source?: string; target?: ResumeDeliveryTarget }): string {
+// 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, source: o.source, target: o.target });
+    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: input is not JSON-serializable (${(err as Error).message}) — a resume answer must round-trip to the DO`);
+    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 }): string {
-  const payload = { userText, turnId: o?.turnId, event: o?.event, trigger: o?.trigger };
+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 {

package/src/agent-native.ts

@@ -9,9 +9,11 @@
 
 import {
   AgentSession,
+  grantAnswer,
   withSystem,
   type ChannelPolicy,
   type EventSink,
+  type InputAnnouncement,
   type TurnEvent,
   type Model,
   type Msg,
@@ -91,7 +93,7 @@ class SqliteSessionStore implements SessionStore {
   // generation (audit trail — never deleted), clear the live rows, status → "new".
   // Archive tables + the generation counter are created lazily here, so existing
   // databases stay untouched until the first reset.
-  reset(): number {
+  reset(inTx?: () => void): number {
     return this.tx(() => {
       this.db.exec(`CREATE TABLE IF NOT EXISTS agent_messages_archive (session_id TEXT, generation INTEGER, seq INTEGER, body TEXT)`);
       this.db.exec(`CREATE TABLE IF NOT EXISTS agent_steps_archive (session_id TEXT, generation INTEGER, id TEXT, output TEXT)`);
@@ -104,6 +106,7 @@ class SqliteSessionStore implements SessionStore {
       this.db.query("DELETE FROM agent_steps WHERE session_id = ?").run(this.sid);
       this.db.query("INSERT INTO agent_sessions (session_id, status) VALUES (?, 'new') ON CONFLICT(session_id) DO UPDATE SET status = 'new'").run(this.sid);
       this.db.query("INSERT INTO agent_session_generations (session_id, generation) VALUES (?, ?) ON CONFLICT(session_id) DO UPDATE SET generation = ?").run(this.sid, generation + 1, generation + 1);
+      inTx?.(); // writes into the fresh generation, committed with the archive (#260)
       return generation;
     });
   }
@@ -119,7 +122,68 @@ class InProcEventSink implements EventSink {
 
 // `instructions` (the agent's system prompt) is injected into the model per turn
 // by the runtime (withSystem) — single-sourced on the def, not baked into `model`.
-export type AgentDef = { model: Model; tools: Tool[]; instructions?: string; channelInstructions?: Record<string, string | ChannelPolicy> };
+export type AgentDef = {
+  model: Model;
+  tools: Tool[];
+  instructions?: string;
+  channelInstructions?: Record<string, string | ChannelPolicy>;
+  // The app's receiver for input announcements (#260), installed on every session this
+  // runtime builds; undelivered announcements from an earlier process are flushed then.
+  onInputAnnouncement?: (a: InputAnnouncement) => void | Promise<void>;
+};
+
+// Retries a failed announcement delivery on a timer (#260): the engine keeps an undelivered
+// announcement and flushes again on the next announcement, settled turn or rebuild — but a
+// session that goes quiet would hold it until then. 5 s doubling to 5 min, per session;
+// unref'd, so a pending retry never holds the process open. Owned by the runtime, so the
+// backoff survives an evicted-and-rebuilt actor.
+class AnnouncementRetry {
+  // Explicit fields (not parameter properties) — keep the shipped source erasable.
+  private readonly flush: (agent: string, id: string) => void;
+  private readonly state = new Map<string, { failures: number; timer?: ReturnType<typeof setTimeout> }>();
+  constructor(flush: (agent: string, id: string) => void) {
+    this.flush = flush;
+  }
+  delivered(key: string) {
+    const s = this.state.get(key);
+    if (s?.timer) clearTimeout(s.timer);
+    this.state.delete(key);
+  }
+  failed(key: string, agent: string, id: string) {
+    const s = this.state.get(key) ?? { failures: 0 };
+    this.state.set(key, s);
+    if (s.timer) return; // one retry pending at a time
+    const delay = Math.min(5_000 * 2 ** s.failures, 300_000);
+    s.failures++;
+    s.timer = setTimeout(() => { s.timer = undefined; this.flush(agent, id); }, delay);
+    (s.timer as { unref?: () => void }).unref?.();
+  }
+}
+
+// Install the announcement hook on a freshly built session and deliver what an earlier life
+// of it recorded but never delivered (#260). The flush never rejects; it logs — and a
+// failure schedules a retry.
+function wireAnnouncements(session: AgentSession, def: AgentDef, retry: AnnouncementRetry): AgentSession {
+  const hook = def.onInputAnnouncement;
+  if (hook) {
+    const key = `${session.agent}:${session.id}`;
+    session.onAnnounce = async (a) => {
+      try {
+        await hook(a);
+      } catch (err) {
+        retry.failed(key, session.agent, session.id);
+        throw err; // the engine keeps the announcement and logs
+      }
+      retry.delivered(key);
+    };
+    void session.flushAnnouncements();
+  }
+  return session;
+}
+
+// The step the engine keeps its announcement outbox under (#260) — read by the native
+// runtime's startup scan. Mirrors ANNOUNCE_OUTBOX in @junejs/core/agent-runtime.
+const ANNOUNCE_OUTBOX_STEP = "announce-outbox";
 
 // The runtime-side def for an assembled AgentDefinition (#173): the tools (channel
 // capability tools and read_skill included), the system prompt (instructions + the
@@ -133,6 +197,7 @@ export function toAgentDef(agent: AgentDefinition, model: Model): AgentDef {
     tools: agent.tools,
     instructions: buildSystemPrompt(agent),
     ...(agent.channelInstructions ? { channelInstructions: agent.channelInstructions } : {}),
+    ...(agent.onInputAnnouncement ? { onInputAnnouncement: agent.onInputAnnouncement } : {}),
   };
 }
 
@@ -155,6 +220,8 @@ export class NativeRuntime implements Runtime {
   private actors = new Map<string, { session: AgentSession; sink: InProcEventSink }>();
   private readonly agents: Record<string, AgentDef>;
   private readonly db: SyncSqlite;
+  // Retries failed announcement deliveries (#260), across actor rebuilds.
+  private readonly announceRetry = new AnnouncementRetry((agent, id) => { void this.session(agent, id).flushAnnouncements(); });
   private readonly maxSessions: number;
 
   constructor(agents: Record<string, AgentDef>, db: SyncSqlite, opts: NativeRuntimeOptions = {}) {
@@ -187,7 +254,7 @@ export class NativeRuntime implements Runtime {
     if (!def) throw new Error(`unknown agent: ${agent}`);
     const model = def.instructions ? withSystem(def.model, def.instructions) : def.model;
     const sink = new InProcEventSink();
-    const session = new AgentSession(agent, id, new SqliteSessionStore(this.db, key), sink, model, def.tools, this, def.channelInstructions);
+    const session = wireAnnouncements(new AgentSession(agent, id, new SqliteSessionStore(this.db, key), sink, model, def.tools, this, def.channelInstructions), def, this.announceRetry);
     this.evictIdle();
     this.actors.set(key, { session, sink });
     return session;
@@ -196,6 +263,19 @@ export class NativeRuntime implements Runtime {
   // Number of memoized actors (observability / tests).
   get sessionCount(): number { return this.actors.size; }
 
+  // Deliver announcements an earlier process recorded but never delivered (#260), without
+  // waiting for their sessions to be used again: build every session whose outbox is not
+  // empty — building one flushes it. The agent and session come from the announcement
+  // itself, not from splitting the store key (an agent name may contain ":"). Called once
+  // by createNativeRuntime; safe to call again.
+  recoverAnnouncements(): void {
+    const rows = this.db.query("SELECT output FROM agent_steps WHERE id = ?").all(ANNOUNCE_OUTBOX_STEP) as { output: string }[];
+    for (const { output } of rows) {
+      const [first] = JSON.parse(output) as InputAnnouncement[];
+      if (first && this.agents[first.agent]?.onInputAnnouncement) this.session(first.agent, first.session);
+    }
+  }
+
   // Drop least recently used idle actors until one more fits under the cap. Runs before
   // the new actor is inserted, so the actor being handed out is never a candidate.
   private evictIdle() {
@@ -215,7 +295,9 @@ export async function createNativeRuntime(
   path = ":memory:",
   opts: NativeRuntimeOptions = {},
 ): Promise<NativeRuntime> {
-  return new NativeRuntime(agents, await openLocalSqliteSync(path), opts);
+  const runtime = new NativeRuntime(agents, await openLocalSqliteSync(path), opts);
+  runtime.recoverAnnouncements(); // #260
+  return runtime;
 }
 
 // ── memory backend — in-process, ephemeral (no DB, no disk) ───────────────────
@@ -241,12 +323,13 @@ class MemorySessionStore implements SessionStore {
   getStatus(): string { return this.status; }
   setStatus(s: string) { this.status = s; }
   tx<T>(fn: () => T): T { return fn(); } // no rollback: an in-memory store is not a durability tier
-  reset(): number {
+  reset(inTx?: () => void): number {
     const generation = this.generation++;
     this.archives.push({ generation, msgs: this.msgs, steps: this.steps });
     this.msgs = [];
     this.steps = new Map();
     this.status = "new";
+    inTx?.(); // writes into the fresh generation (#260)
     return generation;
   }
   unwrap<H = unknown>(): H { return undefined as unknown as H; }
@@ -256,6 +339,7 @@ export class MemoryRuntime implements Runtime {
   private actors = new Map<string, AgentSession>();
   private stores = new Map<string, MemorySessionStore>();
   private readonly agents: Record<string, AgentDef>;
+  private readonly announceRetry = new AnnouncementRetry((agent, id) => { void this.session(agent, id).flushAnnouncements(); }); // #260
   constructor(agents: Record<string, AgentDef>) {
     assertCoreRuntimeVersion("MemoryRuntime"); // #94: fail power-on, not mid-turn
     this.agents = agents;
@@ -271,7 +355,7 @@ export class MemoryRuntime implements Runtime {
       this.stores.set(key, store);
       // Same def handling as NativeRuntime: switching backend must not change behavior.
       const model = def.instructions ? withSystem(def.model, def.instructions) : def.model;
-      a = new AgentSession(agent, id, store, new InProcEventSink(), model, def.tools, this, def.channelInstructions);
+      a = wireAnnouncements(new AgentSession(agent, id, store, new InProcEventSink(), model, def.tools, this, def.channelInstructions), def, this.announceRetry);
       this.actors.set(key, a);
     }
     return a;
@@ -363,7 +447,10 @@ export function mountAgent(
     // HITL: answer a parked turn and stream its continuation (the approval-button path).
     resumeStream: async function* (o) {
       const session = runtime.session(agent.name, o.session ?? "default");
-      const { turnId } = session.resume(o.turnId, o.inputId, o.input, { by: o.by });
+      // A { policy } answerer is the app's call (#261): decided here, before the synchronous
+      // resume, so resume-then-subscribe stays free of awaits.
+      const granted = await grantAnswer(session, o, agent.authorizeAnswer);
+      const { turnId } = session.resume(o.turnId, o.inputId, o.input, { by: o.by, granted });
       yield* observeTurnEvents(session, turnId);
     },
     // SESSION RESET (#129): same seam as durableChannelSurface — the in-process runtimes'