@aiworker/web 1.22.2 → 1.23.1

package/server/lib/relay/host-client.test.js

@@ -39,11 +39,17 @@ const startFakeRelay = () => {
     clients: new Map(), // connectionId -> ws
     buffered: new Map(), // connectionId -> [[data, isBinary]] awaiting host-data
     relayFrames: [], // observed forwarded frames (for plaintext assertions)
+    apps: new Map(),
   };
 
   wss.on('connection', (ws, req) => {
     const url = new URL(req.url, 'http://localhost');
     const role = url.searchParams.get('role');
+    state.apps.set(role, {
+      appId: url.searchParams.get('appId'),
+      appVersion: url.searchParams.get('appVersion'),
+      platform: url.searchParams.get('platform'),
+    });
     const connectionId = url.searchParams.get('connectionId');
 
     if (role === 'host-control') {
@@ -101,6 +107,7 @@ const startFakeRelay = () => {
           // A socket a failed test left open would hold server.close() until
           // the hook timeout; drop them so a failure is reported once.
           for (const client of wss.clients) client.terminate();
+          server.closeAllConnections();
           wss.close();
           server.close(() => r());
         }),
@@ -286,6 +293,13 @@ describe('relay host-client integration', () => {
     });
 
     expect(result.status).toBe(200);
+    for (const role of ['host-control', 'host-data']) {
+      expect(relay.state.apps.get(role)).toEqual({
+        appId: 'aiworker',
+        appVersion: expect.stringMatching(/^\d+\.\d+\.\d+/),
+        platform: process.env.AIWORKER_RUNTIME || 'web',
+      });
+    }
     expect(result.body.ok).toBe(true);
     expect(result.body.relayConn).toBe('conn-test-1');
     expect(result.body.origin).toBe(`http://127.0.0.1:${origin.port}`);

package/server/lib/relay/tunnel-codec.js

@@ -34,6 +34,7 @@ export const TunnelFrameType = {
   WsClose: 10,
   Ping: 11,
   Pong: 12,
+  DeliveryAck: 13,
 };
 
 const TUNNEL_FRAME_TYPE_VALUES = new Set(Object.values(TunnelFrameType));
@@ -43,6 +44,14 @@ export const isTunnelFrameType = (value) => TUNNEL_FRAME_TYPE_VALUES.has(value);
 
 const MAX_STREAM_ID = 0xffffffff;
 
+/** Decode the client's cumulative raw tunnel-frame byte count. */
+export const decodeDeliveryAck = (payload) => {
+  if (payload.length !== 8) throw new Error('invalid delivery acknowledgement');
+  const bytes = Number(new DataView(payload.buffer, payload.byteOffset, payload.byteLength).getBigUint64(0));
+  if (!Number.isSafeInteger(bytes)) throw new Error('invalid delivery acknowledgement');
+  return bytes;
+};
+
 export class TunnelCodecError extends Error {
   constructor(message) {
     super(message);

package/server/lib/relay/tunnel-host.js

@@ -15,7 +15,6 @@ import {
   createFragmentAssembler,
   decodeJsonPayload,
   decodeTunnelFrame,
-  encodeFragmentedMessage,
   encodeJsonPayload,
   encodeTunnelFrame,
 } from './tunnel-codec.js';
@@ -74,6 +73,11 @@ const BODY_BUFFER_MAX_BYTES = 512 * 1024;
 // completes, so a stalled tunnel converts into an ambiguous transport failure
 // (which the client already retries) instead of a hung loopback request.
 const BODY_DELIVERY_TIMEOUT_MS = 15_000;
+const MAX_PENDING_WS_BYTES = 16 * 1024 * 1024;
+const MAX_PENDING_WS_MESSAGES = 1024;
+// Node ws supports read backpressure. Bun's ws shim does not implement pause;
+// there the bounded queue fails the affected substream explicitly on overflow.
+const CAN_PAUSE_WS_READS = !process.versions.bun;
 
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
@@ -99,13 +103,17 @@ const isWsClosePayload = (parsed) => Boolean(parsed && typeof parsed === 'object
  *   sendFrame: (plaintextFrame: Uint8Array) => void | Promise<void>,
  *   getBufferedAmount: () => number,
  *   bodyDeliveryTimeoutMs?: number,
+ *   responseChunkBytes?: number,
+ *   cancelPendingFrames?: (streamId: number) => void,
  * }} deps
  */
-export const createTunnelHost = ({ connectionId, getLocalPort, sendFrame, getBufferedAmount, bodyDeliveryTimeoutMs = BODY_DELIVERY_TIMEOUT_MS }) => {
+export const createTunnelHost = ({ connectionId, getLocalPort, sendFrame, getBufferedAmount, bodyDeliveryTimeoutMs = BODY_DELIVERY_TIMEOUT_MS, responseChunkBytes = MAX_TUNNEL_PAYLOAD_BYTES, cancelPendingFrames = () => {} }) => {
   /** @type {Map<number, { kind: 'http', abort: AbortController, body: { enqueue(payload: Uint8Array): void, close(): void, error(error: Error): void } | null, noBody: boolean } | { kind: 'ws', socket: WebSocket, opened: boolean }>} */
   const streams = new Map();
   const assembler = createFragmentAssembler();
   let closed = false;
+  let pendingWsBytes = 0;
+  let pendingWsMessages = 0;
 
   const send = async (frame) => {
     if (closed) return;
@@ -128,6 +136,7 @@ export const createTunnelHost = ({ connectionId, getLocalPort, sendFrame, getBuf
     const stream = streams.get(streamId);
     if (!stream) return;
     dropStream(streamId);
+    cancelPendingFrames(streamId);
     if (stream.kind === 'http') {
       try {
         stream.body?.error(new Error(String(reason ?? 'aborted')));
@@ -205,17 +214,27 @@ export const createTunnelHost = ({ connectionId, getLocalPort, sendFrame, getBuf
       if (STRIPPED_RESPONSE_HEADERS.has(name)) continue;
       responseHeaders[name] = value;
     }
-    await sendJson(TunnelFrameType.HttpResponse, streamId, { status: response.status, headers: responseHeaders });
+    if (closed || stream.abort.signal.aborted) {
+      await response.body?.cancel();
+      return;
+    }
 
     try {
+      await sendJson(TunnelFrameType.HttpResponse, streamId, { status: response.status, headers: responseHeaders });
       if (response.body) {
         for await (const chunk of response.body) {
           if (closed || stream.abort.signal.aborted) return;
           const bytes = chunk instanceof Uint8Array ? chunk : new Uint8Array(chunk);
-          for (const piece of chunkPayload(bytes, MAX_TUNNEL_PAYLOAD_BYTES)) {
+          const pieces = chunkPayload(bytes, responseChunkBytes);
+          // Offer at most one plaintext-frame budget at a time. The scheduler
+          // can batch small slices and interleave streams without buffering the
+          // entire source or encrypting hundreds of tiny messages separately.
+          const groupSize = Math.max(1, Math.floor(MAX_TUNNEL_PAYLOAD_BYTES / responseChunkBytes));
+          for (let offset = 0; offset < pieces.length; offset += groupSize) {
             await waitForBackpressure(stream.abort.signal);
             if (closed || stream.abort.signal.aborted) return;
-            await send(encodeTunnelFrame(TunnelFrameType.HttpBody, streamId, piece));
+            await Promise.all(pieces.slice(offset, offset + groupSize).map(piece =>
+              send(encodeTunnelFrame(TunnelFrameType.HttpBody, streamId, piece))));
           }
         }
       }
@@ -448,6 +467,7 @@ export const createTunnelHost = ({ connectionId, getLocalPort, sendFrame, getBuf
     try {
       socket = new WebSocket(url, open.protocols, {
         headers: dialHeaders,
+        maxPayload: MAX_PENDING_WS_BYTES,
       });
     } catch (error) {
       void sendAbort(streamId, error?.message ?? 'ws dial failed');
@@ -455,6 +475,8 @@ export const createTunnelHost = ({ connectionId, getLocalPort, sendFrame, getBuf
     }
     const stream = { kind: 'ws', socket, opened: false };
     streams.set(streamId, stream);
+    let outputChain = Promise.resolve();
+    let socketPendingMessages = 0;
 
     socket.on('open', () => {
       if (streams.get(streamId) !== stream) return;
@@ -465,23 +487,47 @@ export const createTunnelHost = ({ connectionId, getLocalPort, sendFrame, getBuf
       if (streams.get(streamId) !== stream || closed) return;
       const bytes = Buffer.isBuffer(data) ? new Uint8Array(data) : new Uint8Array(Buffer.concat(data));
       const frameType = isBinary ? TunnelFrameType.WsBinary : TunnelFrameType.WsText;
-      void (async () => {
-        for (const frame of encodeFragmentedMessage(frameType, streamId, bytes)) {
+      if (pendingWsBytes + bytes.length > MAX_PENDING_WS_BYTES || pendingWsMessages >= MAX_PENDING_WS_MESSAGES) {
+        abortLocalStream(streamId, 'upstream WebSocket exceeded downstream queue limit');
+        void sendAbort(streamId, 'upstream WebSocket exceeded downstream queue limit');
+        return;
+      }
+      pendingWsBytes += bytes.length;
+      pendingWsMessages += 1;
+      socketPendingMessages += 1;
+      if (CAN_PAUSE_WS_READS) socket.pause();
+      outputChain = outputChain.then(async () => {
+        // Serialize entire messages, including their fragments. A later close
+        // must also wait here or it can overtake the final output.
+        const chunks = chunkPayload(bytes, responseChunkBytes);
+        const groupSize = Math.max(1, Math.floor(MAX_TUNNEL_PAYLOAD_BYTES / responseChunkBytes));
+        for (let offset = 0; offset < chunks.length; offset += groupSize) {
           await waitForBackpressure(null);
           if (streams.get(streamId) !== stream || closed) return;
-          await send(frame);
+          await Promise.all(chunks.slice(offset, offset + groupSize).map((chunk, index) =>
+            send(encodeTunnelFrame(frameType, streamId, chunk, offset + index < chunks.length - 1))));
         }
-      })();
+      }).catch(() => {
+        abortLocalStream(streamId, 'upstream WebSocket forwarding failed');
+        void sendAbort(streamId, 'upstream WebSocket forwarding failed');
+      }).finally(() => {
+        pendingWsBytes -= bytes.length;
+        pendingWsMessages -= 1;
+        socketPendingMessages -= 1;
+        if (CAN_PAUSE_WS_READS && socketPendingMessages === 0 && streams.get(streamId) === stream && socket.readyState === WebSocket.OPEN) socket.resume();
+      });
     });
     socket.on('close', (code, reasonBuffer) => {
-      if (streams.get(streamId) !== stream) return;
-      dropStream(streamId);
-      const reason = reasonBuffer ? reasonBuffer.toString('utf8') : '';
-      if (stream.opened) {
-        void sendJson(TunnelFrameType.WsClose, streamId, { code: code || 1000, reason });
-      } else {
-        void sendAbort(streamId, reason || `upstream ws closed (${code || 'no code'})`);
-      }
+      void outputChain.then(async () => {
+        if (streams.get(streamId) !== stream) return;
+        dropStream(streamId);
+        const reason = reasonBuffer ? reasonBuffer.toString('utf8') : '';
+        if (stream.opened) {
+          await sendJson(TunnelFrameType.WsClose, streamId, { code: code || 1000, reason });
+        } else {
+          await sendAbort(streamId, reason || `upstream ws closed (${code || 'no code'})`);
+        }
+      });
     });
     socket.on('error', (error) => {
       if (streams.get(streamId) !== stream) return;
@@ -512,6 +558,7 @@ export const createTunnelHost = ({ connectionId, getLocalPort, sendFrame, getBuf
     const stream = streams.get(streamId);
     if (!stream || stream.kind !== 'ws') return;
     dropStream(streamId);
+    cancelPendingFrames(streamId);
     let close = { code: 1000, reason: '' };
     try {
       close = decodeJsonPayload(payload, isWsClosePayload);
@@ -520,6 +567,8 @@ export const createTunnelHost = ({ connectionId, getLocalPort, sendFrame, getBuf
     }
     const code = Number.isInteger(close.code) && close.code >= 1000 && close.code <= 4999 ? close.code : 1000;
     try {
+      // A paused receiver still needs to read the peer's close handshake.
+      if (CAN_PAUSE_WS_READS) stream.socket.resume();
       stream.socket.close(code, typeof close.reason === 'string' ? close.reason : '');
     } catch {
       stream.socket.terminate();

package/server/lib/scheduled-tasks/DOCUMENTATION.md

@@ -25,6 +25,12 @@ in shared project config under the project write lock:
   from the winner's persisted `nextRunAt`.
 - Project config writes also take a cross-process `.json.lock` file so the
   read-modify-write is serialized across processes, not only within one process.
+- `syncAllProjects` (startup and every full resync) syncs each registered
+  project on its own: a project whose config cannot be read or written (a
+  broken file, a lock timeout) is logged with its id and skipped, and every
+  other project's tasks are still scheduled. Only `listProjects` failing
+  aborts the sync as a whole. `syncProject` for one project still throws, so
+  a route for that project reports the failure.
 - The sharing processes may run different AiWorker versions. Normalization
   keeps only the fields a build knows, so every writer persists tasks it did
   not change verbatim from disk and swaps only `state` onto a task whose state
@@ -63,7 +69,9 @@ in shared project config under the project write lock:
 - Claiming always writes `nextRunAt` (including `undefined`) so a past once-slot
   is cleared when there is no following occurrence.
 
-Manual `runNow` does not claim a schedule occurrence.
+Manual `runNow` does not claim a schedule occurrence. It also runs paused
+(`enabled: false`) tasks — that is the point of the button — while scheduled
+dispatches still skip disabled tasks, and completion never re-arms a paused task.
 
 ## Files
 

package/server/lib/scheduled-tasks/issue-2710-double-execution.test.js

@@ -485,4 +485,32 @@ describe('issue 2710: daily scheduled task double execution at the configured ti
 
     runtime.stop();
   });
+
+  it('manual runNow runs a paused task but does not schedule future runs', async () => {
+    vi.setSystemTime(UTC(2026, 0, 1, 14, 0, 0));
+    const task = { ...makeTask({ kind: 'daily', times: ['15:00'] }), enabled: false };
+    const projectConfigRuntime = createSharedProjectConfigRuntime(task);
+
+    const runtime = createScheduledTasksRuntime(createRuntimeDeps(projectConfigRuntime));
+    await runtime.start();
+
+    // The scheduler must not fire a disabled task on its own.
+    await vi.advanceTimersByTimeAsync(HOUR + 3_000);
+    expect(sdk.sessionCreates.length).toBe(0);
+
+    const manual = await runtime.runNow('p1', 'task-1');
+    expect(manual.ok).toBe(true);
+    expect(manual.sessionID).toBeTruthy();
+    expect(sdk.sessionCreates.length).toBe(1);
+    expect(runtime.getStatus().runningScheduledTasksCount).toBe(0);
+
+    // Completion records state but leaves the task paused with no next run.
+    const tasks = await projectConfigRuntime.listScheduledTasks('p1');
+    expect(tasks[0].enabled).toBe(false);
+    expect(tasks[0].state.lastStatus).toBe('success');
+    expect(tasks[0].state.lastSessionId).toBe('sess-1');
+    expect(tasks[0].state.nextRunAt).toBeUndefined();
+
+    runtime.stop();
+  });
 });

package/server/lib/scheduled-tasks/runtime.js

@@ -426,7 +426,16 @@ export const createScheduledTasksRuntime = (deps) => {
     }
 
     for (const projectID of activeProjectIDs) {
-      await syncProject(projectID);
+      try {
+        await syncProject(projectID);
+      } catch (error) {
+        // One project's config being unusable (a broken file, a lock timeout)
+        // must not keep every other project's tasks from being scheduled.
+        logger.warn?.('[ScheduledTasks] failed to sync project', {
+          projectID,
+          error: error?.message ?? String(error),
+        });
+      }
     }
   };
 
@@ -676,7 +685,8 @@ export const createScheduledTasksRuntime = (deps) => {
   const runTask = async (projectID, taskID, reason, scheduledFor) => {
     const taskMap = tasksByProject.get(projectID);
     const task = taskMap?.get(taskID);
-    if (!task || !task.enabled) {
+    // Manual runNow runs paused tasks too; only scheduled dispatches skip them.
+    if (!task || (reason !== 'manual' && !task.enabled)) {
       return { ok: false, skipped: true };
     }
 

package/server/lib/scheduled-tasks/runtime.test.js

@@ -206,3 +206,56 @@ Run daily.
     }
   });
 });
+
+describe('scheduled-tasks runtime syncAllProjects', () => {
+  it('keeps scheduling the other projects when one project cannot be synced', async () => {
+    const tempRoot = await mkdtemp(path.join(os.tmpdir(), 'oc-runtime-sync-all-'));
+    try {
+      const brokenPath = path.join(tempRoot, 'broken');
+      const healthyPath = path.join(tempRoot, 'healthy');
+      await mkdir(path.join(healthyPath, '.agents', 'loops'), { recursive: true });
+      await mkdir(brokenPath, { recursive: true });
+      await writeFile(path.join(healthyPath, '.agents', 'loops', 'daily.md'), `---
+name: daily
+schedule: "0 9 * * *"
+enabled: true
+model: openai/gpt-5
+---
+Run daily.
+`, 'utf8');
+
+      const projectConfigRuntime = createProjectConfigRuntime({
+        fsPromises: await import('fs/promises'),
+        path,
+        projectsDirPath: path.join(tempRoot, 'config'),
+        createTaskID: () => 'task-fixed-id',
+      });
+      await mkdir(path.join(tempRoot, 'config'), { recursive: true });
+      await writeFile(projectConfigRuntime.resolveProjectConfigPath('broken'), '{ not json', 'utf8');
+
+      const warnings = [];
+      const runtime = createScheduledTasksRuntime({
+        buildOpenCodeUrl: () => 'http://localhost',
+        getOpenCodeAuthHeaders: () => ({}),
+        waitForOpenCodeReady: async () => {},
+        projectConfigRuntime,
+        listProjects: async () => [
+          { id: 'broken', path: brokenPath },
+          { id: 'healthy', path: healthyPath },
+        ],
+        logger: { warn: (...args) => warnings.push(args) },
+      });
+
+      await expect(runtime.start()).resolves.toBeUndefined();
+
+      expect(runtime.getStatus().enabledScheduledTasksCount).toBe(1);
+      const healthyTasks = await projectConfigRuntime.listScheduledTasks('healthy');
+      expect(healthyTasks.map((task) => task.id)).toEqual(['loop:project:daily']);
+      expect(warnings).toHaveLength(1);
+      expect(warnings[0][1]).toMatchObject({ projectID: 'broken' });
+      runtime.stop();
+    } finally {
+      await rm(tempRoot, { recursive: true, force: true });
+    }
+  });
+});

package/server/lib/session-assist/DOCUMENTATION.md

@@ -1,66 +1,131 @@
-# Session Assist
-
-Server-side watcher that generates a short recap of the agent's last reply
-and one suggested user follow-up with the small model
-(`lib/small-model`), storing both on the session's metadata under
-`metadata.aiworker.assist`.
-
-## Flow
-
-1. `createSessionAssistRuntime` is a consumer of the server's global SSE
-   fan-out (`index.js` → `onPayload`), riding the same upstream connection as
-   notifications. Purely event-driven — dormant sessions never generate
-   anything, there is no backfill and no session scanning.
-2. `session.status: idle` arms a 60-second per-session timer; any `busy`/
-   `retry` status or a user `message.updated` clears it (the "1 minute of
-   quiet" rule).
-3. On fire: fetch the session (skip sub-agent sessions with `parentID`),
-   take the LAST exchange only — the final assistant reply plus the user
-   message it answered (assistant `parentID` → user id) — and call
-   `generateSmallModelText` with the
-   session's own provider/model taken from the last assistant message — so
-   the utility call spends the same subscription as the conversation.
-   `restrictToPreferredProvider` forbids the resolver's global fallback:
-   conversation content never goes to a provider the user didn't pick for
-   the session, unless the small model was chosen explicitly (settings
-   override or opencode config). A resolver 404 is silently skipped.
-4. The requested JSON fields (`recap`, `suggestion`, or both) are clamped and
-   PATCHed onto the session metadata together with `forMessageID` (the last
-   assistant message id) and `generatedAt`. Before writing, the session tail is
-   re-checked (a stale result is dropped) and the metadata is merged from a
-   fresh session read so concurrent metadata writes made during generation are
-   preserved.
-
-## Settings gate
-
-`sessionRecapEnabled` and `sessionSuggestionEnabled` in AiWorker settings
-(Settings → Chat, default on) are hard generation switches checked at fire
-time. When both are off, no small-model calls run and nothing is written. When
-one is on, the runtime still makes at most one small-model call and asks only
-for that field. The UI also hides disabled payload types immediately.
-
-## Freshness contract (no clearing writes)
-
-Clients do not need the payload to be deleted: they render it only while
-`assist.forMessageID` still equals the session's last assistant message id
-(and the session is idle). Any new message invalidates the payload
-everywhere instantly and offline; the next idle cycle overwrites it.
-
-## UI consumers (packages/ui)
-
-- `lib/sessionAssistMetadata.ts` — payload parsing.
-- `hooks/useSessionAssist.ts` — freshness gating + the 1-minute quiet window
-  for the recap (single timeout to the boundary, no polling).
-- `components/chat/SessionRecapSpacer.tsx` — renders the recap inside the
-  fixed-height reserved gap under the last message (height never changes).
-- `components/chat/SessionSuggestionChip.tsx` — one tappable suggestion chip
-  near the composer (desktop chips row + above the mobile pill); hidden as
-  soon as the composer has any content. Tap fills the input, never sends.
-
-## Limitations
-
-- The watcher lives in the web server, so VS Code (extension-only, no web
-  server) does not generate assists; it still renders payloads produced by a
-  web/desktop instance of the same OpenCode server via `session.updated`.
-- Metadata payloads ride every `session.updated` event — keep the clamps
-  (`RECAP_CHAR_LIMIT`, `SUGGESTION_CHAR_LIMIT`) small.
+# Session assist
+
+The server generates a short reminder of recent work and an optional next user
+message with Small Model. Results live in `metadata.aiworker.assist` with
+`recap`, `suggestion`, `forMessageID`, and `generatedAt`. The payload shape is
+unchanged; an empty suggestion is a successful outcome.
+
+## Ownership
+
+- `runtime.js` owns idle timers, cancellation, provider selection, SDK reads,
+  freshness checks, settings gates, and metadata writes.
+- `context.js` reads bounded history and constructs human turns. It removes
+  tool payloads and injected prompts before retaining message text.
+- `prompt.js` owns the generation instructions and total input budget.
+- `../small-model/DOCUMENTATION.md` owns provider/auth resolution, generation,
+  output limits, and overflow behavior.
+
+## What the model receives
+
+Read backward through the official SDK in pages of 50 messages until three
+human turns are covered, history ends, or eight pages have been read. A failed
+page or repeated cursor aborts generation; it is not treated as complete history.
+At the page limit, use fewer available human turns. If the latest answer's human
+request has not been found, skip generation rather than invent its context.
+
+Three turns retain the substance behind short commit confirmations without
+bringing an entire old task back into the prompt. This was compared against
+one, five, ten, and full-history contexts on long maintainer sessions. There
+is no full-history cache and no assumed provider prefix-cache behavior.
+
+The latest record must be a completed, successful, non-summary assistant answer
+with visible text. Child, archived, and reverted sessions are skipped. A new
+prompt clears the revert boundary before its next idle event.
+
+Human turns follow chronological message intervals. OpenCode can insert
+synthetic continuation users during compaction, so a final answer's `parentID`
+need not point directly at the original human request. These continuations stay
+within their human turn; compaction summaries are excluded. An interrupted
+request remains context with its last visible progress explicitly labeled as
+unfinished, rather than being dropped or called a final answer.
+An answer must still reference that human user or one of its continuation
+users; a late answer for an older request cannot be assigned to a newer request.
+
+### Attached context and language
+
+The persisted attachment contract is owned by
+`packages/ui/src/lib/messages/contextParts.ts`. Its user-facing Markdown
+formatter is `packages/ui/src/lib/messages/messageMarkdown.ts`.
+
+The server projects those persisted parts into model context without importing
+the UI runtime: code comments, file/chat quotes, browser annotations, PR comments,
+checks, terminal selections, and linked GitHub/Linear items remain attached to
+the user turn even when their transport part is synthetic. The OpenCode
+`opencodeComment` mirror is also accepted. Unrecognized synthetic prompts and
+ignored parts are excluded. Malformed attached text fails the generation.
+
+Quoted material and the user's own comment are separate blocks. The user's
+authored text is also supplied separately for language selection. Quoted source,
+logs, assistant replies, and injected memory instructions do not choose the
+language. A language-neutral final acknowledgment can use recent authored text.
+The existing Cyrillic/CJK mismatch guard uses that authored sample per field;
+it is not a complete language detector, and it is skipped if no sample exists.
+
+### Input bounds
+
+User text is bounded to 8,000 characters and each assistant answer to 16,000.
+Attached quote bodies have their own 4,000-character limit so a large quote
+does not consume the user's comment. Excerpts preserve both ends with an
+explicit omission marker, including the conclusion of a long final report.
+
+The complete user prompt is limited to 32,000 characters and the resolved small
+model's input allowance, reserving space for the system prompt. Under pressure,
+drop older whole turns first. If the latest pair itself is too large, excerpt
+both its user request and answer rather than discarding either side. If even
+the minimum prompt cannot fit, skip generation. `onOverflow: 'error'` prevents
+the Small Model service from silently cutting off the instructions. Expected
+context/output-budget failures are quiet and do not write metadata.
+
+OpenCode message pages still contain complete tool payloads on the wire. A
+single long turn can therefore require substantial I/O even though its retained
+model context is small. Page/count bounds are not a network-byte quota.
+
+## Generation and lifecycle
+
+1. The server's existing global event fan-out calls `processPayload`. An idle
+   event arms the 60-second quiet window. No history scan or startup backfill runs.
+2. Busy/retry events and newly created user messages clear pending work and
+   abort in-flight reads/generation. Re-emitted old user updates do not cancel it.
+3. One generation runs per session. If a newer quiet window expires while an
+   old canceled request is still settling, retain that pending run and start it
+   after the old one finishes. Later activity cancels the pending run as well.
+4. Resolve the small model using the last answer's provider/model and the
+   existing explicit settings/config overrides. `restrictToPreferredProvider`
+   prevents an implicit cross-provider fallback. Production does not pin the
+   experimental model. Generation accepts an abort signal and a 120-second limit.
+5. Recap describes the substantive work and its current result, including the
+   work behind a closing commit or acknowledgment. Suggestion is independent:
+   only unfinished requested agent work should produce a sendable user message.
+   Completed work, optional offers, or a decision/action belonging to the user
+   should return an empty suggestion. This is model judgment, not authorization
+   enforcement or a guarantee that every generated field is factually correct.
+6. Re-read the latest message and fresh session before writing. A moved tail,
+   canceled run, changed endpoint/directory, archive, revert, or failed fresh
+   read discards the result. Never merge from the old pre-generation metadata.
+7. Re-check settings, clamp the enabled fields, and merge into fresh metadata.
+   The OpenCode update endpoint has no compare-and-set operation; another
+   writer after the final read is not guarded atomically.
+
+Stopping the runtime clears pending timers/runs and aborts in-flight operations.
+No failed session blocks another session.
+
+## Settings and consumers
+
+`sessionRecapEnabled` and `sessionSuggestionEnabled` default on and are checked
+before work and before writing. With both off there are no reads, model calls,
+or writes. With one on, the shared recent context is still available, but only
+that field is requested. An empty suggestion does not erase a valid recap.
+
+Clients render an assist only while its `forMessageID` is the last message and
+the session is idle. A new message invalidates it without clearing writes.
+
+- `packages/ui/src/lib/sessionAssistMetadata.ts` parses the payload.
+- `packages/ui/src/hooks/useSessionAssist.ts` owns freshness/settings gating.
+- `SessionRecapSpacer` shows the reminder in the reserved gap under the reply.
+- `SessionSuggestionChip` fills the composer; it never sends automatically.
+
+Web, Electron, hosted mobile, and Capacitor use the server watcher. VS Code's
+extension-only runtime does not generate assists; shared UI can render payloads
+produced by a server. The background watcher cannot use the browser's message
+store when the UI is closed. Manual AI rename uses that store through
+`SessionMessageLoader`; these are intentionally different retrieval lifecycles.