@aiworker/web 1.23.0 → 1.23.1

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.

package/server/lib/session-assist/context.js

@@ -0,0 +1,127 @@
+const TURN_LIMIT = 3;
+const PAGE_SIZE = 50;
+const MAX_PAGES = 8;
+const USER_CHAR_LIMIT = 8_000;
+const ANSWER_CHAR_LIMIT = 16_000;
+
+// Mirrors the persisted context contract owned by UI lib/messages/contextParts.ts.
+// Read only the fields needed for model context; malformed attached text fails
+// this generation instead of silently dropping the user's comment.
+const QUOTE_FIELDS = new Map([
+  ['code-comment', 'code'], ['file-quote', 'quote'], ['chat-quote', 'quote'],
+  ['browser-annotation', 'prompt'], ['pr-comment', 'body'], ['pr-check', 'output'],
+  ['terminal', 'output'],
+]);
+const LINK_KINDS = new Set(['github-issue', 'github-pr', 'linear-issue']);
+
+export function excerpt(text, limit) {
+  if (text.length <= limit) return text;
+  const marker = '\n[Content omitted]\n';
+  if (limit <= marker.length) return text.slice(0, Math.max(0, limit));
+  const head = Math.ceil((limit - marker.length) / 2);
+  const tail = limit - marker.length - head;
+  return text.slice(0, head) + marker + (tail > 0 ? text.slice(-tail) : '');
+}
+
+function attachedText(part) {
+  const context = part.metadata?.aiworkerContext;
+  if (QUOTE_FIELDS.has(context?.kind)) {
+    const source = (context[QUOTE_FIELDS.get(context.kind)] ?? '').trim();
+    const authored = (context.text ?? '').trim();
+    const label = excerpt((context.fileLabel ?? context.label ?? context.pageUrl ?? context.terminalLabel ?? '').trim(), 300);
+    const location = Number.isInteger(context.startLine) ? `, lines ${context.startLine}-${context.endLine ?? context.startLine}` : '';
+    const quote = excerpt(source, 4_000).split('\n').map((line) => `> ${line}`).join('\n');
+    return { text: `Attached ${context.kind}${label ? ` (${label}${location})` : ''}:\n${quote}\n\nUser comment:\n${excerpt(authored, USER_CHAR_LIMIT)}`, authored };
+  }
+  if (LINK_KINDS.has(context?.kind)) return { text: excerpt(part.text, USER_CHAR_LIMIT), authored: '' };
+  const comment = part.metadata?.opencodeComment;
+  if (comment) {
+    const authored = comment.comment.trim();
+    const source = (comment.preview ?? '').trim();
+    const label = excerpt((comment.path ?? '').trim(), 300);
+    return { text: `Attached file context (${label}):\n${excerpt(source, 4_000)}\n\nUser comment:\n${excerpt(authored, USER_CHAR_LIMIT)}`, authored };
+  }
+  return null;
+}
+
+/** SDK message records are chronological; tool payloads never enter this view. */
+function readMessage({ info, parts }) {
+  const blocks = [];
+  const authored = [];
+  for (const part of parts) {
+    if (part.type !== 'text' || part.ignored) continue;
+    const attached = info.role === 'user' ? attachedText(part) : null;
+    if (attached) {
+      blocks.push(attached.text);
+      authored.push(attached.authored);
+    } else if (!part.synthetic) {
+      blocks.push(part.text);
+      if (info.role === 'user') {
+        // Legacy terminal selections are source material, not a language sample.
+        authored.push(part.text.replace(/\n*<terminal_context>\n[\s\S]*?\n<\/terminal_context>\s*$/, ''));
+      }
+    }
+  }
+  return {
+    id: info.id, role: info.role, parentID: info.parentID,
+    providerID: info.providerID, modelID: info.modelID,
+    complete: info.role === 'assistant' && info.finish === 'stop' && Boolean(info.time?.completed) && !info.error && !info.summary,
+    summary: Boolean(info.summary),
+    text: excerpt(blocks.join('\n\n').trim(), info.role === 'user' ? USER_CHAR_LIMIT : ANSWER_CHAR_LIMIT),
+    authored: excerpt(authored.filter(Boolean).join('\n\n').trim(), USER_CHAR_LIMIT),
+  };
+}
+
+function collectTurns(messages) {
+  const turns = [];
+  let active = null;
+  let parents = new Set();
+  for (const message of messages) {
+    if (message.role === 'user' && message.text) {
+      active = { user: message, assistant: null, complete: false };
+      parents = new Set([message.id]);
+      turns.push(active);
+    } else if (active && message.role === 'user') {
+      parents.add(message.id);
+    } else if (active && message.role === 'assistant' && parents.has(message.parentID) && !message.summary) {
+      // Compaction's synthetic continuation users belong to the same human
+      // turn. Parent IDs alone would lose its eventual final answer.
+      if (message.text) active.assistant = message;
+      active.complete = message.complete && Boolean(message.text);
+    }
+  }
+  return turns.slice(-TURN_LIMIT);
+}
+
+/** Failure is thrown; null means no eligible final answer within bounded history. */
+export async function loadAssistContext({ readPage, signal }) {
+  let messages = [];
+  let before;
+  const cursors = new Set();
+  const ids = new Set();
+  for (let pageNumber = 0; pageNumber < MAX_PAGES; pageNumber++) {
+    signal.throwIfAborted();
+    const page = await readPage({ limit: PAGE_SIZE, before });
+    signal.throwIfAborted();
+    if (!Array.isArray(page.data)) throw new Error('Session message page is unavailable');
+    const older = [];
+    for (const record of page.data) {
+      if (ids.has(record.info.id)) continue;
+      ids.add(record.info.id);
+      older.push(readMessage(record));
+    }
+    messages = older.concat(messages);
+    const last = messages.at(-1);
+    if (!last?.complete || !last.text) return null;
+    const turns = collectTurns(messages);
+    const cursor = page.response.headers.get('x-next-cursor');
+    if (turns.length === TURN_LIMIT || !cursor || pageNumber === MAX_PAGES - 1) {
+      if (!turns.at(-1)?.complete || turns.at(-1).assistant.id !== last.id) return null;
+      return { turns, last };
+    }
+    if (cursors.has(cursor)) throw new Error('Session message pagination made no progress');
+    cursors.add(cursor);
+    before = cursor;
+  }
+  return null;
+}

package/server/lib/session-assist/context.test.js

@@ -0,0 +1,132 @@
+import { describe, expect, it } from 'vitest';
+import { excerpt, loadAssistContext } from './context.js';
+import { buildAssistPrompt } from './prompt.js';
+
+const record = (id, role, text, extra = {}, parts = []) => ({
+  info: { id, role, parentID: 'user', finish: 'stop', time: { completed: 1 }, providerID: 'provider', modelID: 'model', ...extra },
+  parts: [...(text ? [{ type: 'text', text }] : []), ...parts],
+});
+const pair = (id) => [record(`u${id}`, 'user', `request ${id}`), record(`a${id}`, 'assistant', `answer ${id}`, { parentID: `u${id}` })];
+const page = (data, cursor = '') => ({ data, response: { headers: new Headers({ 'x-next-cursor': cursor }) } });
+const load = (readPage) => loadAssistContext({ readPage, signal: new AbortController().signal });
+
+describe('session assist context', () => {
+  it('stops paging at three human turns and excludes tools and injected instructions', async () => {
+    let calls = 0;
+    const records = [...pair(1), ...pair(2), ...pair(3), ...pair(4)];
+    records.at(-1).parts.push({ type: 'tool', state: { output: 'TOOL_PAYLOAD' } }, { type: 'text', synthetic: true, text: 'INJECTED_PROMPT' });
+    const context = await load(async ({ limit, before }) => {
+      calls++;
+      expect(limit).toBe(50);
+      expect(before).toBeUndefined();
+      return page(records, 'more');
+    });
+    expect(calls).toBe(1);
+    expect(context.turns.map((t) => t.user.id)).toEqual(['u2', 'u3', 'u4']);
+    expect(context.last.text).toBe('answer 4');
+    expect(JSON.stringify(context)).not.toContain('TOOL_PAYLOAD');
+    expect(JSON.stringify(context)).not.toContain('INJECTED_PROMPT');
+  });
+
+  it('finds the real user across a page boundary and compaction continuations', async () => {
+    const summary = record('summary', 'assistant', 'INTERNAL SUMMARY', { summary: true });
+    const continuation = record('continuation', 'user', '', {}, [{ type: 'text', synthetic: true, text: 'Continue' }]);
+    const final = record('final', 'assistant', 'All requested work done', { parentID: 'continuation' });
+    const context = await load(async ({ before }) => before
+      ? page([...pair(1), ...pair(2), record('human', 'user', 'Finish the requested work')])
+      : page([summary, continuation, final], 'older'));
+    expect(context.last.id).toBe('final');
+    expect(context.turns.at(-1).user.id).toBe('human');
+    expect(context.turns.at(-1).assistant.id).toBe('final');
+    expect(JSON.stringify(context)).not.toContain('INTERNAL SUMMARY');
+  });
+
+  it('retains interrupted requests as progress, not as completed turns', async () => {
+    const context = await load(async () => page([
+      record('u1', 'user', 'Implement both fixes'),
+      record('a1', 'assistant', 'First fix done', { finish: 'tool-calls', parentID: 'u1' }),
+      ...pair(2),
+    ]));
+    expect(context.turns[0].complete).toBe(false);
+    expect(context.turns[0].assistant.text).toBe('First fix done');
+    expect(context.turns[1].complete).toBe(true);
+  });
+
+  it('keeps synthetic annotations and separates author language from quoted material', async () => {
+    const user = record('u', 'user', '', {}, [{
+      type: 'text', synthetic: true, text: 'Serialized attachment',
+      metadata: { aiworkerContext: { kind: 'chat-quote', quote: 'English quoted source', text: 'Виправ саме це' } },
+    }]);
+    const context = await load(async () => page([user, record('a', 'assistant', 'Done', { parentID: 'u' })]));
+    expect(context.turns[0].user.text).toContain('> English quoted source');
+    expect(context.turns[0].user.text).toContain('User comment:\nВиправ саме це');
+    expect(context.turns[0].user.authored).toBe('Виправ саме це');
+  });
+
+  it('retains the comment after a large quote and the conclusion after a long answer', async () => {
+    const user = record('u', 'user', '', {}, [{ type: 'text', synthetic: true, text: 'attachment', metadata: {
+      aiworkerContext: { kind: 'browser-annotation', prompt: 'x'.repeat(30_000), text: 'USER_REQUEST_END' },
+    } }]);
+    const context = await load(async () => page([user, record('a', 'assistant', `START${'x'.repeat(30_000)}CONCLUSION`, { parentID: 'u' })]));
+    expect(context.turns[0].user.text).toContain('USER_REQUEST_END');
+    expect(context.last.text).toMatch(/^START/);
+    expect(context.last.text).toMatch(/CONCLUSION$/);
+    expect(context.last.text.length).toBeLessThanOrEqual(16_000);
+  });
+
+  it('fails explicitly on malformed annotation text instead of losing the comment', async () => {
+    const user = record('u', 'user', '', {}, [{ type: 'text', synthetic: true, text: 'attachment', metadata: {
+      aiworkerContext: { kind: 'chat-quote', quote: 'source', text: 42 },
+    } }]);
+    await expect(load(async () => page([user, record('a', 'assistant', 'done')]))).rejects.toThrow();
+  });
+
+  it('does not treat a failed or repeated page as complete history', async () => {
+    await expect(load(async () => ({ data: undefined }))).rejects.toThrow('unavailable');
+    await expect(load(async () => page(pair(1), 'repeated'))).rejects.toThrow('no progress');
+    let calls = 0;
+    await expect(load(async () => {
+      if (++calls === 2) throw new Error('offline');
+      return page(pair(1), 'next');
+    })).rejects.toThrow('offline');
+  });
+
+  it('bounds retrieval and refuses to invent a user for an orphaned answer', async () => {
+    let calls = 0;
+    const context = await load(async () => page([record(`a${++calls}`, 'assistant', 'answer')], `cursor${calls}`));
+    expect(calls).toBe(8);
+    expect(context).toBeNull();
+  });
+
+  it('skips unfinished, failed, summary, and user tails', async () => {
+    for (const tail of [
+      record('tail', 'user', 'New request'),
+      record('tail', 'assistant', 'Working', { finish: 'tool-calls' }),
+      record('tail', 'assistant', 'Failed', { error: { name: 'error' } }),
+      record('tail', 'assistant', 'Summary', { summary: true }),
+    ]) expect(await load(async () => page([...pair(1), tail]))).toBeNull();
+  });
+
+  it('keeps both sides of the newest exchange within a small model budget', async () => {
+    const context = await load(async () => page([
+      ...pair(1), ...pair(2), record('latest', 'user', `REQUEST_START${'u'.repeat(8000)}REQUEST_END`),
+      record('answer', 'assistant', `ANSWER_START${'a'.repeat(16000)}ANSWER_END`, { parentID: 'latest' }),
+    ]));
+    for (const budget of [1_000, 4_000, 14_000, 32_000, 1_000_000]) {
+      const prompt = buildAssistPrompt(context.turns, { recap: true, suggestion: true }, budget);
+      expect(prompt.text.length).toBeLessThanOrEqual(Math.min(budget, 32_000));
+      for (const marker of ['REQUEST_START', 'REQUEST_END', 'ANSWER_START', 'ANSWER_END']) expect(prompt.text).toContain(marker);
+    }
+    expect(buildAssistPrompt(context.turns, { recap: true }, 500)).toBeNull();
+    expect(excerpt('long text', 0)).toBe('');
+    expect(excerpt('long text', 2)).toBe('lo');
+    for (let limit = 0; limit < 60; limit++) expect(excerpt('x'.repeat(100), limit).length).toBeLessThanOrEqual(limit);
+  });
+
+  it('does not assign an older parent\'s late answer to a newer user request', async () => {
+    expect(await load(async () => page([
+      ...pair(1), record('new-user', 'user', 'A different request'),
+      record('late-answer', 'assistant', 'Old work done', { parentID: 'u1' }),
+    ]))).toBeNull();
+  });
+});

package/server/lib/session-assist/prompt.js

@@ -0,0 +1,54 @@
+import { excerpt } from './context.js';
+
+const MAX_PROMPT_CHARS = 32_000;
+
+export function buildAssistSystemPrompt({ recap, suggestion }) {
+  return [
+    `Return exactly one JSON object with string fields: ${[recap ? '"recap"' : '', suggestion ? '"suggestion"' : ''].filter(Boolean).join(', ')}.`,
+    recap ? 'recap is a reminder of the actual work accomplished or conclusion reached in the recent conversation. In at most 20 words, name the concrete behavior or subject and its current result. The reader wants to remember WHAT changed or was learned.' : '',
+    recap ? 'Write the recap for the person using the app, not for someone reviewing its code. Name the feature and the concrete difference the user will notice. Replace generic "implemented and tested" summaries with what now works differently or what was learned. File paths, internal module names, test counts, and lists of checks belong in the recap only when they are the subject of the user\'s request. Preserve a specific finding or limitation when it changes the meaning of the result.' : '',
+    recap ? 'For a closing exchange such as a commit, push, acknowledgment, or thank-you, summarize the substantive work from the preceding answers. Commit bookkeeping, authorship, branch names, and hashes are secondary and usually omitted. A recap saying only that optimizations or changes were committed does not serve this purpose.' : '',
+    recap ? 'Use the latest state of that work. Distinguish recommendations from actions already performed, and implementations from verified deployments. Retain the reported conclusion without recalculating detailed lists. Earlier unrelated topics are not part of the recap.' : '',
+    suggestion ? 'suggestion is optional. Return "" when the current request is satisfied or continuing requires a user decision. Otherwise return one concise message the user could send to continue specific unfinished work they requested.' : '',
+    suggestion ? 'suggestion: return an empty string if the latest request has been satisfied, the next move requires the user\'s decision, or the context does not establish unfinished requested work. Finishing is a normal outcome.' : '',
+    suggestion ? 'Otherwise write one concise, specific next message the user can send unchanged to continue the unfinished request. Use the user\'s voice addressing the agent.' : '',
+    suggestion ? 'A request to analyze, explain, or recommend is satisfied by that analysis, explanation, or recommendation unless the user also asked for execution. An optional offer, an implementation plan, a caveat about untested platforms, or uncommitted work is not permission for a new task. Do not revive old requests after the user changes topic.' : '',
+    'Language: all requested fields follow the latest user-authored communication, including the user\'s comments on quotes. Ignore the language of the quoted material, code, logs, assistant responses, and these instructions. For a language-neutral acknowledgment use recent user-authored communication. Keep technical names unchanged where useful.',
+    recap && suggestion ? 'Keep recap and suggestion independent: recap may carry earlier substantive work forward, while suggestion must be justified by the current request, not by that earlier work.' : '',
+    suggestion ? 'Only suggest work the coding agent can perform in the session. If the next action belongs to the user, such as checking their phone, choosing a design, or approving a change, return "". A suggestion is a message sent TO the agent, never a reminder addressed to the user.' : '',
+  ].filter(Boolean).join('\n');
+}
+
+function renderTurn(turn, index, userText = turn.user.text, answerText = turn.assistant?.text ?? '') {
+  return [
+    `Turn ${index + 1}${turn.complete ? '' : ' (interrupted before a final response)'}`,
+    'User message with attached context:', userText,
+    turn.complete ? 'Assistant final response:' : 'Assistant progress before interruption:', answerText,
+  ].join('\n');
+}
+
+export function buildAssistPrompt(turns, targets, charBudget) {
+  const budget = Math.min(MAX_PROMPT_CHARS, Math.floor(charBudget));
+  if (!Number.isFinite(budget) || budget < 1_000 || !turns.length) return null;
+  const languageBudget = Math.min(3_600, Math.floor(budget / 5));
+  const language = excerpt(turns.map((turn) => excerpt(turn.user.authored, 1_200)).filter(Boolean).join('\n'), languageBudget);
+  const header = 'Recent conversation turns, oldest first. Older turns may be omitted.\n\n';
+  const requested = [targets.recap ? 'a reminder of the recent substantive work in recap' : '', targets.suggestion ? 'an optional current next step in suggestion' : ''].filter(Boolean).join(', and ');
+  const footer = `\n\n--- End of conversation evidence ---\n\nRecent user-authored communication, excluding attached quotes, oldest first:\n\n${language}\n\nReturn ${requested}.`;
+  const available = budget - header.length - footer.length;
+  const kept = turns.slice();
+  let body = kept.map((turn, i) => renderTurn(turn, i)).join('\n\n---\n\n');
+  while (body.length > available && kept.length > 1) {
+    kept.shift();
+    body = kept.map((turn, i) => renderTurn(turn, i)).join('\n\n---\n\n');
+  }
+  if (body.length > available) {
+    const turn = kept[0];
+    const textBudget = available - renderTurn(turn, 0, '', '').length;
+    if (textBudget < 128) return null;
+    const answer = turn.assistant?.text ?? '';
+    const userBudget = Math.min(turn.user.text.length, Math.max(Math.floor(textBudget / 3), textBudget - answer.length));
+    body = renderTurn(turn, 0, excerpt(turn.user.text, userBudget), excerpt(answer, textBudget - userBudget));
+  }
+  return { text: header + body + footer, language };
+}