@kelloggt/dsh-program-agents 0.0.0-stage → 0.1.1

package/skills/program-agents/references/chat-sidebar/backend.ts

@@ -0,0 +1,184 @@
+// SERVER ONLY. Never import this module (or connectProgram) into the browser bundle.
+import { connectProgram, type ConversationHandle, type ConversationMessage, type ConversationOpenOptions, type JsonValue, type ProgramConversations } from '@kelloggt/dsh-program-agents/app';
+import type { Context, Hono } from 'hono';
+import { canonicalJson, object, SIDEBAR_LIMITS, utf8Bytes, type NativeFrame } from './protocol.js';
+
+export interface AgentSidebarOptions<PageState extends JsonValue> {
+  /** Exact public app origin, including port. Do not derive this from incoming Host/Origin. */
+  appOrigin: string;
+  basePath?: string;
+  conversation: ConversationOpenOptions;
+  /** Mandatory application allowlist. Treat input as hostile; return a fresh minimal object. */
+  sanitizePageState: (input: unknown) => PageState;
+  /** Injection for app ownership/testing. Default connectProgram() remains backend-only and lazy. */
+  conversations?: ProgramConversations;
+  /** Add real app authentication here for non-loopback deployments. CSRF checks are not auth. */
+  authorize?: (request: Request) => boolean | Promise<boolean>;
+  /** Log codes/operation IDs, not raw prompt/context, credentials, headers, or arbitrary stacks. */
+  onError?: (operation: string, error: unknown) => void;
+}
+class HttpFailure extends Error { constructor(readonly status: 400 | 401 | 403 | 413 | 415 | 429, message: string) { super(message); } }
+function integer(value: string | undefined, fallback?: number): number {
+  if (value === undefined && fallback !== undefined) return fallback;
+  if (!value || !/^-?\d+$/.test(value) || !Number.isSafeInteger(Number(value))) throw new HttpFailure(400, 'Invalid history cursor');
+  return Number(value);
+}
+async function readJson(request: Request): Promise<unknown> {
+  if (request.headers.get('content-type')?.split(';')[0]?.trim().toLowerCase() !== 'application/json') throw new HttpFailure(415, 'Expected application/json');
+  const length = request.headers.get('content-length');
+  if (length !== null && (!/^\d+$/.test(length) || Number(length) > SIDEBAR_LIMITS.requestBytes)) throw new HttpFailure(413, 'Request exceeds 32 KiB');
+  if (!request.body) throw new HttpFailure(400, 'Expected JSON body');
+  const reader = request.body.getReader();
+  const chunks: Uint8Array[] = []; let size = 0;
+  try {
+    for (;;) {
+      const item = await reader.read(); if (item.done) break;
+      size += item.value.byteLength;
+      if (size > SIDEBAR_LIMITS.requestBytes) { await reader.cancel(); throw new HttpFailure(413, 'Request exceeds 32 KiB'); }
+      chunks.push(item.value);
+    }
+  } finally { reader.releaseLock(); }
+  const bytes = new Uint8Array(size); let offset = 0;
+  for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.byteLength; }
+  try { return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)); }
+  catch { throw new HttpFailure(400, 'Invalid JSON'); }
+}
+function messageInput<PageState extends JsonValue>(input: unknown, sanitize: (value: unknown) => PageState): { message: ConversationMessage; requestId: string } {
+  if (!object(input) || typeof input.text !== 'string' || !input.text.trim() || typeof input.requestId !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(input.requestId)) throw new HttpFailure(400, 'Expected text and an opaque requestId');
+  if (Object.keys(input).some(key => !['text', 'requestId', 'context'].includes(key))) throw new HttpFailure(400, 'Unknown message field');
+  const message: ConversationMessage = { text: input.text };
+  if (input.context !== undefined) {
+    if (!object(input.context) || !Object.hasOwn(input.context, 'state') || Object.keys(input.context).some(key => !['state', 'revision'].includes(key))) throw new HttpFailure(400, 'Invalid page context');
+    const revision = input.context.revision;
+    if (revision !== undefined && !((typeof revision === 'string' && revision.length <= 256) || (typeof revision === 'number' && Number.isSafeInteger(revision)))) throw new HttpFailure(400, 'Invalid page revision');
+    try {
+      // Bound both the submitted state and the allowlisted output, measured in UTF-8 bytes.
+      if (utf8Bytes(canonicalJson(input.context.state)) > SIDEBAR_LIMITS.stateBytes) throw new HttpFailure(413, 'Page state exceeds 16 KiB');
+      const state = sanitize(input.context.state);
+      const serialized = canonicalJson(state);
+      if (utf8Bytes(serialized) > SIDEBAR_LIMITS.stateBytes) throw new HttpFailure(413, 'Page state exceeds 16 KiB');
+      message.context = { ...(revision === undefined ? {} : { revision }), state: JSON.parse(serialized) as PageState };
+      // Native context admission also counts the small revision/state envelope.
+      if (utf8Bytes(canonicalJson(message.context)) > SIDEBAR_LIMITS.stateBytes) throw new HttpFailure(413, 'Page context envelope exceeds 16 KiB');
+    } catch (error) {
+      if (error instanceof HttpFailure) throw error;
+      throw new HttpFailure(400, 'Page state failed the application allowlist');
+    }
+  }
+  return { message, requestId: input.requestId };
+}
+
+/** Mount one app-owned conversation, not an arbitrary session/bridge proxy. No startup child. */
+export function mountAgentSidebar<PageState extends JsonValue>(app: Hono, options: AgentSidebarOptions<PageState>) {
+  const origin = new URL(options.appOrigin);
+  if (!['http:', 'https:'].includes(origin.protocol) || origin.origin !== options.appOrigin || origin.username || origin.password) throw new Error('appOrigin must be an exact HTTP(S) origin');
+  const basePath = options.basePath ?? '/api/assistant';
+  if (!/^\/[A-Za-z0-9/_-]+$/.test(basePath) || basePath.endsWith('/')) throw new Error('Invalid sidebar basePath');
+  // Freeze creation identity/instructions. Changing them does not rewrite an existing child.
+  const conversationOptions = { ...options.conversation };
+  let singleton: Promise<ConversationHandle> | undefined;
+  let activeStreams = 0;
+  let pendingSends = 0;
+  const conversation = (): Promise<ConversationHandle> => {
+    if (!singleton) {
+      singleton = Promise.resolve().then(() => (options.conversations ?? connectProgram().conversations).open(conversationOptions));
+      // A rejected open may be retried on a later explicit chat request, never in a startup loop.
+      void singleton.catch(() => { singleton = undefined; });
+    }
+    return singleton;
+  };
+  app.use(`${basePath}/*`, async (c, next) => {
+    c.header('Cache-Control', 'no-store'); c.header('X-Content-Type-Options', 'nosniff');
+    const request = c.req.raw;
+    const host = request.headers.get('host');
+    if (new URL(request.url).origin !== origin.origin || (host !== null && host.toLowerCase() !== origin.host)) return c.json({ error: 'Wrong app host' }, 403);
+    const suppliedOrigin = request.headers.get('origin');
+    const explicitSameOrigin = suppliedOrigin === options.appOrigin;
+    // Browsers omit Origin on same-origin GET and forbid JavaScript from setting it.
+    // Only this GET-only Fetch-Metadata + non-simple-header exception is permitted.
+    const sameOriginGet = request.method === 'GET' && suppliedOrigin === null && request.headers.get('sec-fetch-site') === 'same-origin';
+    if ((!explicitSameOrigin && !sameOriginGet) || request.headers.get('x-agent-sidebar') !== '1') return c.json({ error: 'Same-origin sidebar request required' }, 403);
+    if (options.authorize && !await options.authorize(request)) return c.json({ error: 'Authentication required' }, 401);
+    await next();
+  });
+  const guarded = (operation: string, handler: (c: Context) => Promise<Response>) => async (c: Context): Promise<Response> => {
+    try { return await handler(c); }
+    catch (error) {
+      if (error instanceof HttpFailure) return c.json({ error: error.message }, error.status);
+      options.onError?.(operation, error);
+      // A bridge error can contain private details. The browser sees only this stable summary.
+      return c.json({ error: `${operation} failed; inspect history before retrying a send` }, 502);
+    }
+  };
+  app.post(`${basePath}/messages`, guarded('Send', async c => {
+    const input = messageInput(await readJson(c.req.raw), options.sanitizePageState);
+    if (pendingSends >= 8) throw new HttpFailure(429, 'Too many pending sends');
+    pendingSends++;
+    try {
+      const handle = await conversation();
+      // No retries: a timeout/disconnect can happen after native admission. Always queue a new turn.
+      const receipt = await handle.send(input.message, { requestId: input.requestId, mode: 'queue', signal: c.req.raw.signal });
+      return c.json(receipt, 202);
+    } finally { pendingSends--; }
+  }));
+  app.get(`${basePath}/history`, guarded('History', async c => {
+    const throughSeq = integer(c.req.query('throughSeq'));
+    const beforeSeq = c.req.query('beforeSeq') === undefined ? undefined : integer(c.req.query('beforeSeq'));
+    const maxMessages = integer(c.req.query('maxMessages'), 20);
+    if (throughSeq < -1 || (beforeSeq !== undefined && (beforeSeq < 0 || beforeSeq > throughSeq + 1)) || maxMessages < 1 || maxMessages > 100) throw new HttpFailure(400, 'Invalid history range');
+    const handle = await conversation();
+    return c.json(await handle.history({ throughSeq, ...(beforeSeq === undefined ? {} : { beforeSeq }), maxMessages }, { signal: c.req.raw.signal }));
+  }));
+  app.post(`${basePath}/interrupt`, guarded('Interrupt', async c => {
+    const body = await readJson(c.req.raw);
+    if (!object(body) || Object.keys(body).length) throw new HttpFailure(400, 'Expected empty JSON object');
+    // Interrupting an unopened sidebar is a no-op, not a reason to create a child.
+    if (!singleton) return c.json({ accepted: true });
+    return c.json(await (await singleton).interrupt({ signal: c.req.raw.signal }));
+  }));
+  app.get(`${basePath}/events`, guarded('Subscribe', async c => {
+    if (activeStreams >= 2) throw new HttpFailure(429, 'Too many sidebar subscriptions');
+    activeStreams++;
+    const abort = new AbortController();
+    let iterator: AsyncIterator<NativeFrame> | undefined;
+    let closing: Promise<IteratorResult<NativeFrame>> | undefined;
+    const closeIterator = () => closing ??= iterator?.return?.();
+    let ended = false;
+    const cleanup = () => {
+      if (ended) return;
+      ended = true; activeStreams--; abort.abort();
+      c.req.raw.signal.removeEventListener('abort', requestAbort);
+      // Release even when the browser disconnects between pulls (no pending next()).
+      void closeIterator()?.catch(() => {});
+    };
+    const requestAbort = () => cleanup();
+    c.req.raw.signal.addEventListener('abort', requestAbort, { once: true });
+    if (c.req.raw.signal.aborted) cleanup();
+    try {
+      const handle = await conversation();
+      iterator = handle.events({ signal: abort.signal, maxMessages: 20 })[Symbol.asyncIterator]();
+      if (abort.signal.aborted) { await closeIterator(); throw new Error('Subscription cancelled'); }
+      const encoder = new TextEncoder();
+      // Pull, don't eagerly drain native events into an unbounded application queue.
+      // The bridge also bounds its queue and eventually disconnects a slow browser.
+      const body = new ReadableStream<Uint8Array>({
+        async pull(controller) {
+          try {
+            const item = await iterator!.next();
+            if (item.done) { cleanup(); controller.close(); return; }
+            const json = JSON.stringify(item.value);
+            if (utf8Bytes(json) > SIDEBAR_LIMITS.frameBytes) throw new Error('Native frame exceeds sidebar limit');
+            controller.enqueue(encoder.encode(`event: native\ndata: ${json}\n\n`));
+          } catch (error) {
+            const wasAborted = abort.signal.aborted; cleanup();
+            if (!wasAborted) options.onError?.('Subscribe', error);
+            controller.error(new Error('Assistant subscription disconnected'));
+          }
+        },
+        async cancel() { cleanup(); await closeIterator(); },
+      }, { highWaterMark: 0 });
+      return new Response(body, { headers: { 'Content-Type': 'text/event-stream; charset=utf-8', 'Cache-Control': 'no-store', 'X-Accel-Buffering': 'no', 'X-Content-Type-Options': 'nosniff' } });
+    } catch (error) { cleanup(); throw error; }
+  }));
+  return { basePath };
+}

package/skills/program-agents/references/chat-sidebar/protocol.ts

@@ -0,0 +1,214 @@
+// Browser-safe: all SDK imports are types; no bridge client or Node builtins here.
+import type { ConversationFrame, JsonValue, SessionFollowFrame, SessionPage } from '@kelloggt/dsh-program-agents/app';
+
+export type NativeFrame = SessionFollowFrame;
+export type NativeEvent = Extract<NativeFrame, { type: 'event' }>['event'];
+type Snapshot = Extract<NativeFrame, { type: 'snapshot' }>;
+export type PageContext = { revision?: string | number; state: JsonValue };
+export const SIDEBAR_LIMITS = Object.freeze({ requestBytes: 32 * 1024, stateBytes: 16 * 1024, frameBytes: 512 * 1024, records: 1000, liveCharacters: 256 * 1024 });
+export type DisplayBlock = { type: 'text' | 'reasoning'; text: string } | { type: 'tool-call'; id: string; name: string; arguments: string };
+export interface LiveAttempt {
+  attemptId: string; turn: number; step: number; startedAfterSeq: number; nextIndex: number;
+  blocks: Readonly<Record<number, DisplayBlock>>;
+}
+export interface SidebarState {
+  sessionId?: string;
+  /** Fixed pagination cut from the most recent snapshot, not the moving live cursor. */
+  throughSeq: number;
+  cursor: number;
+  records: readonly NativeEvent[];
+  hasMore: boolean;
+  streamRevision: number;
+  active?: LiveAttempt;
+  status: 'idle' | 'running';
+  /** Native ask receipts are correlation, not an exactly-once guarantee. */
+  receipts: Readonly<Record<string, string>>;
+}
+export const initialSidebarState = (): SidebarState => ({ throughSeq: -1, cursor: -1, records: [], hasMore: false, streamRevision: 0, status: 'idle', receipts: {} });
+export function object(value: unknown): value is Record<string, unknown> { return value !== null && typeof value === 'object' && !Array.isArray(value); }
+export function utf8Bytes(value: string): number { return new TextEncoder().encode(value).byteLength; }
+
+/** Deterministic JSON data only. Useful for app-side revision fingerprints, NOT instructions. */
+export function canonicalJson(value: unknown, depth = 0): string {
+  if (depth > 32) throw new Error('JSON is too deeply nested');
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return JSON.stringify(value);
+  if (typeof value === 'number' && Number.isFinite(value)) return JSON.stringify(value);
+  if (Array.isArray(value)) return '[' + value.map(item => canonicalJson(item, depth + 1)).join(',') + ']';
+  if (object(value) && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)) {
+    return '{' + Object.keys(value).sort().map(key => JSON.stringify(key) + ':' + canonicalJson(value[key], depth + 1)).join(',') + '}';
+  }
+  throw new Error('Expected plain JSON data');
+}
+
+function block(value: unknown): DisplayBlock | undefined {
+  if (!object(value)) return;
+  if ((value.type === 'text' || value.type === 'reasoning') && typeof value.text === 'string') return { type: value.type, text: value.text };
+  if (value.type === 'tool-call' && typeof value.id === 'string' && typeof value.name === 'string' && typeof value.arguments === 'string') return { type: value.type, id: value.id, name: value.name, arguments: value.arguments };
+}
+/** Native text-delta uses text, not delta; block-end replaces accumulated text. */
+function foldChunk(blocks: Readonly<Record<number, DisplayBlock>>, value: unknown): Readonly<Record<number, DisplayBlock>> {
+  if (!object(value) || !Number.isSafeInteger(value.index) || (value.index as number) < 0) return blocks;
+  const index = value.index as number;
+  if (index > 1024) throw new Error('Too many stream blocks; reconnect');
+  const previous = blocks[index];
+  let next: DisplayBlock | undefined;
+  if ((value.type === 'text-delta' || value.type === 'reasoning-delta') && typeof value.text === 'string') {
+    const type = value.type === 'text-delta' ? 'text' : 'reasoning';
+    next = { type, text: (previous?.type === type ? previous.text : '') + value.text };
+  } else if (value.type === 'tool-call-delta' && typeof value.id === 'string' && typeof value.argumentsDelta === 'string') {
+    next = { type: 'tool-call', id: value.id, name: typeof value.name === 'string' ? value.name : previous?.type === 'tool-call' ? previous.name : 'Tool', arguments: (previous?.type === 'tool-call' ? previous.arguments : '') + value.argumentsDelta };
+  } else if (value.type === 'block-end') next = block(value.block);
+  if (!next) return blocks;
+  const result = { ...blocks, [index]: next };
+  if (Object.values(result).reduce((size, item) => size + (item.type === 'tool-call' ? item.arguments.length + item.name.length : item.text.length), 0) > SIDEBAR_LIMITS.liveCharacters) throw new Error('Live output limit reached; reconnect');
+  return result;
+}
+
+/** Native snapshot.stream is compact, unlike live chunk frames. Do not render it as deltas. */
+function expandCompact(records: readonly unknown[]): unknown[] {
+  const result: unknown[] = [];
+  for (const record of records) {
+    if (!object(record)) throw new Error('Invalid compact stream record');
+    if (record.type === 'chunk') result.push(record.chunk);
+    else if ((record.type === 'text-chunks' || record.type === 'reasoning-chunks') && Array.isArray(record.texts)) {
+      for (const text of record.texts) result.push({ type: record.type === 'text-chunks' ? 'text-delta' : 'reasoning-delta', index: record.index, text });
+    } else if (record.type === 'tool-call-chunks' && Array.isArray(record.args)) {
+      for (const argumentsDelta of record.args) result.push({ type: 'tool-call-delta', index: record.index, id: record.id, name: record.name, argumentsDelta });
+    } else throw new Error('Unknown compact stream record; update the reference');
+    if (result.length > 100_000) throw new Error('Compact stream exceeds reference limit');
+  }
+  return result;
+}
+function baseline(snapshot: Snapshot): LiveAttempt | undefined {
+  const attempt = snapshot.assistantStream?.activeAttempt;
+  if (!attempt) return;
+  const chunks = expandCompact(attempt.stream);
+  if (chunks.length !== attempt.nextIndex) throw new Error('Invalid native attempt baseline');
+  return { attemptId: attempt.attemptId, turn: attempt.turn, step: attempt.step, startedAfterSeq: attempt.startedAfterSeq, nextIndex: attempt.nextIndex, blocks: chunks.reduce<Readonly<Record<number, DisplayBlock>>>((blocks, chunk) => foldChunk(blocks, chunk), {}) };
+}
+function statusAfter(status: SidebarState['status'], event: NativeEvent): SidebarState['status'] {
+  if (event.type === 'turn/start') return 'running';
+  if (event.type === 'turn/end') return 'idle';
+  return status;
+}
+function mergeRecords(records: readonly NativeEvent[], additions: readonly NativeEvent[]): NativeEvent[] {
+  const bySeq = new Map(records.map(event => [event.seq, event]));
+  for (const event of additions) bySeq.set(event.seq, event);
+  const result = [...bySeq.values()].sort((a, b) => a.seq - b.seq);
+  if (result.length > SIDEBAR_LIMITS.records) throw new Error('Transcript window full; reconnect for a fresh bounded window');
+  return result;
+}
+
+/** Pure fold of the installed native SessionFollowFrame vocabulary. Snapshot is replacement. */
+export function reduceFrame(state: SidebarState, frame: ConversationFrame): SidebarState {
+  if (frame.type === 'receipt') return { ...state, receipts: Object.fromEntries(Object.entries({ ...state.receipts, [frame.requestId]: frame.messageId }).slice(-128)) };
+  if (frame.type === 'snapshot') {
+    const records = mergeRecords([], frame.records.map(record => record.event));
+    const active = baseline(frame);
+    return { ...initialSidebarState(), sessionId: frame.header.id, throughSeq: frame.cursor, cursor: frame.cursor, records, hasMore: frame.hasMore, streamRevision: frame.assistantStream?.revision ?? 0, active, status: active ? 'running' : records.reduce(statusAfter, 'idle'), receipts: state.receipts };
+  }
+  if (!state.sessionId) throw new Error('Expected a native snapshot first');
+  if (frame.type === 'event') {
+    if (frame.event.seq <= state.cursor) return state; // repeated durable entry, not repeated token deltas
+    if (frame.event.seq !== state.cursor + 1) throw new Error('Durable stream gap; reconnect');
+    return { ...state, cursor: frame.event.seq, records: mergeRecords(state.records, [frame.event]), status: statusAfter(state.status, frame.event) };
+  }
+  const live = frame.frame;
+  // Agent replacement restarts its process-local revision counter. Never keep a stale prefix.
+  if (live.type === 'start' && live.revision === 1 && state.streamRevision !== 0) throw new Error('Assistant lifecycle reset; reconnect');
+  if (live.revision <= state.streamRevision) return state;
+  if (live.revision !== state.streamRevision + 1) throw new Error('Assistant stream gap; reconnect');
+  const updated = { ...state, streamRevision: live.revision };
+  if (live.type === 'start') {
+    if (state.active) throw new Error('Overlapping attempt; reconnect');
+    return { ...updated, active: { attemptId: live.attemptId, turn: live.turn, step: live.step, startedAfterSeq: live.startedAfterSeq, nextIndex: 0, blocks: {} } };
+  }
+  const active = state.active;
+  // The host may attach after a start. Unknown transient suffixes cannot be reconstructed.
+  if (!active || active.attemptId !== live.attemptId) return updated;
+  if (live.index !== active.nextIndex) throw new Error('Assistant chunk gap; reconnect');
+  if (live.type === 'chunk') return { ...updated, active: { ...active, nextIndex: active.nextIndex + 1, blocks: foldChunk(active.blocks, live.chunk) } };
+  if (live.outcome.kind === 'committed') {
+    const settlementSeq = live.outcome.seq;
+    const settlement = state.records.find(event => event.seq === settlementSeq);
+    if (!settlement || settlement.type !== live.outcome.eventType || !object(settlement.data) || settlement.data.turn !== active.turn || settlement.data.step !== active.step) throw new Error('Missing native attempt settlement; reconnect');
+  }
+  // Durable settlement seq is authoritative; it replaces this exact transient attempt.
+  return { ...updated, active: undefined };
+}
+export function prependHistory(state: SidebarState, page: SessionPage, throughSeq: number): SidebarState {
+  if (throughSeq !== state.throughSeq) return state; // a reconnect superseded the in-flight page
+  return { ...state, records: mergeRecords(state.records, page.records.map(record => record.event).filter(event => event.seq <= throughSeq)), hasMore: page.hasMore };
+}
+export interface TranscriptRow { key: string; role: 'user' | 'assistant' | 'tool' | 'status'; blocks: readonly DisplayBlock[]; messageId?: string; requestId?: string; transient?: boolean }
+function messageBlocks(value: unknown): DisplayBlock[] {
+  if (!object(value) || !Array.isArray(value.content)) return [];
+  return value.content.flatMap(value => { const parsed = block(value); return parsed ? [parsed] : []; });
+}
+export function transcriptRows(state: SidebarState): TranscriptRow[] {
+  const rows: TranscriptRow[] = [];
+  for (const event of state.records) {
+    const data = object(event.data) ? event.data : {};
+    // Human transcript keeps append-origin events; compaction/replacement copies are model-only.
+    if ((event.type === 'user/message' || event.type === 'assistant/message' || event.type === 'tool/result') && event.surfaceOp !== 'append') continue;
+    if (event.type === 'assistant/message' && state.active && event.seq > state.active.startedAfterSeq && data.turn === state.active.turn && data.step === state.active.step) continue; // staged until end.outcome.seq retires the live attempt
+    if (event.type === 'user/message' || event.type === 'assistant/message' || event.type === 'tool/result') {
+      const message = event.type === 'user/message' ? data : data.message;
+      const source = object(message) && object(message.source) ? message.source : {};
+      rows.push({ key: `event:${event.seq}`, role: event.type === 'user/message' ? 'user' : event.type === 'assistant/message' ? 'assistant' : 'tool', blocks: messageBlocks(message), messageId: object(message) && typeof message.id === 'string' ? message.id : undefined, requestId: typeof source.rpcId === 'string' ? source.rpcId : undefined });
+    } else if (event.type === 'tool/call' && typeof data.callId === 'string' && typeof data.name === 'string' && typeof data.arguments === 'string') {
+      // Many assistants also carry tool-call blocks: show the explicit call only when absent there.
+      if (!rows.some(row => row.blocks.some(block => block.type === 'tool-call' && block.id === data.callId))) rows.push({ key: `event:${event.seq}`, role: 'tool', blocks: [{ type: 'tool-call', id: data.callId, name: data.name, arguments: data.arguments }] });
+    } else if (event.type === 'turn/end') {
+      const reason = object(data.reason) && typeof data.reason.kind === 'string' ? data.reason.kind : 'finished';
+      rows.push({ key: `event:${event.seq}`, role: 'status', blocks: [{ type: 'text', text: `Turn ${reason}` }] });
+    } else if (event.type === 'assistant/attempt') rows.push({ key: `event:${event.seq}`, role: 'status', blocks: [{ type: 'text', text: 'Model attempt settled without a message' }] });
+  }
+  if (state.active) rows.push({ key: `attempt:${state.active.attemptId}`, role: 'assistant', transient: true, blocks: Object.values(state.active.blocks) });
+  return rows;
+}
+
+/** Bounded fetch-SSE reader. Reconnection opens a NEW snapshot; there is no Last-Event-ID replay. */
+export async function consumeNativeSSE(response: Response, accept: (frame: NativeFrame) => void, signal: AbortSignal): Promise<void> {
+  if (!response.ok || !response.headers.get('content-type')?.includes('text/event-stream') || !response.body) throw new Error(`Assistant stream unavailable (${response.status})`);
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder('utf-8', { fatal: true });
+  let buffer = '';
+  const abort = () => { void reader.cancel().catch(() => {}); };
+  signal.addEventListener('abort', abort, { once: true });
+  if (signal.aborted) abort();
+  const deliver = (packet: string) => {
+    let event = 'message'; const data: string[] = [];
+    for (const line of packet.split('\n')) {
+      if (line.startsWith('event:')) event = line.slice(6).trimStart();
+      if (line.startsWith('data:')) data.push(line.slice(5).replace(/^ /, ''));
+    }
+    if (!data.length) return;
+    if (event === 'sidebar-error') throw new Error('Assistant stream disconnected; reconnect to inspect history');
+    if (event !== 'native') return;
+    const frame: unknown = JSON.parse(data.join('\n'));
+    if (!object(frame) || !['snapshot', 'event', 'assistant-stream'].includes(String(frame.type))) throw new Error('Invalid native frame');
+    // Native bridge is the schema-validation boundary; never interpret arbitrary HTML here.
+    accept(frame as unknown as NativeFrame);
+  };
+  try {
+    while (!signal.aborted) {
+      const item = await reader.read();
+      if (item.done) { buffer += decoder.decode(); break; }
+      buffer += decoder.decode(item.value, { stream: true });
+      // CRLF may be split across reads. Normalize complete packets, not each chunk.
+      let match: RegExpExecArray | null;
+      while ((match = /\r?\n\r?\n/.exec(buffer))) {
+        const packet = buffer.slice(0, match.index).replace(/\r\n/g, '\n');
+        if (utf8Bytes(packet) > SIDEBAR_LIMITS.frameBytes + 128) throw new Error('Assistant frame exceeds limit');
+        buffer = buffer.slice(match.index + match[0].length); deliver(packet);
+      }
+      if (utf8Bytes(buffer) > SIDEBAR_LIMITS.frameBytes + 128) throw new Error('Assistant frame exceeds limit');
+    }
+  } finally {
+    signal.removeEventListener('abort', abort);
+    await reader.cancel().catch(() => {}); reader.releaseLock();
+  }
+  if (signal.aborted) throw new DOMException('Assistant subscription cancelled', 'AbortError');
+  // An incomplete last frame is never committed. Caller reconnects on EOF.
+}

package/skills/program-agents/schemas/dsh.http.request.v1.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://dsh.dev/schemas/dsh.http.request.v1.schema.json",
+  "title": "dsh.http.request.v1 required data payload",
+  "type": "object",
+  "required": ["method", "path", "status"],
+  "properties": {
+    "method": {"type": "string", "minLength": 1, "maxLength": 32},
+    "path": {"type": "string"},
+    "status": {"type": "integer", "minimum": 100, "maximum": 599},
+    "duration_ms": {"type": "number", "minimum": 0}
+  },
+  "additionalProperties": true
+}

package/skills/program-agents/schemas/dsh.program.error-batch.v1.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://dsh.dev/schemas/dsh.program.error-batch.v1.schema.json",
+  "title": "dsh.program.error-batch.v1 required data payload",
+  "type": "object", "required": ["key", "groups", "count", "range", "dropped"], "additionalProperties": true,
+  "properties": {
+    "key": {"type": "string"}, "count": {"type": "integer", "minimum": 1}, "dropped": {"type": "integer", "minimum": 0},
+    "range": {"type": "object", "required": ["first", "last"], "properties": {"first": {"type": "string"}, "last": {"type": "string"}}, "additionalProperties": false},
+    "groups": {
+      "type": "array", "minItems": 1, "maxItems": 20,
+      "items": {
+        "type": "object", "required": ["fingerprint", "count", "sample", "range"], "additionalProperties": true,
+        "properties": {
+          "fingerprint": {"type": "string"}, "count": {"type": "integer", "minimum": 1}, "sample": {"type": "object", "description": "Redacted representative standard record; large payloads/stacks/extensions may be omitted."},
+          "range": {"type": "object", "required": ["first", "last"], "properties": {"first": {"type": "string"}, "last": {"type": "string"}}, "additionalProperties": false},
+          "source": {
+            "type": "object", "additionalProperties": false,
+            "properties": {"path": {"type": "string"}, "offset": {"type": "integer", "minimum": 0}, "run": {"oneOf": [{"type": "string"}, {"type": "object", "required": ["id", "generation"], "properties": {"id": {"type": "string"}, "generation": {"type": "integer", "minimum": 0}}, "additionalProperties": false}]}}
+          }
+        }
+      }
+    }
+  }
+}

package/skills/program-agents/schemas/dsh.program.error.v1.schema.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://dsh.dev/schemas/dsh.program.error.v1.schema.json",
+  "title": "dsh.program.error.v1 optional data payload",
+  "description": "Payload schema only, not the full record. data may be omitted. Additional application/error metadata is allowed; errors under any other log_type are still monitored by ERROR level.",
+  "type": "object",
+  "additionalProperties": true
+}

package/skills/program-agents/schemas/standard-log-record.v1.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://dsh.dev/schemas/standard-log-record.v1.schema.json",
+  "title": "DSH extensible standard JSONL record v1",
+  "description": "One UTF-8 JSON object per line; at most 65536 bytes, JSON depth at most 32. Runtime rejects non-finite/lossy JSON. Unknown versioned log types are accepted by this base contract.",
+  "type": "object",
+  "required": ["timestamp", "level", "log_type", "message"],
+  "properties": {
+    "timestamp": {"type": "string", "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]{1,9})?(Z|[+-][0-9]{2}:[0-9]{2})$"},
+    "level": {"enum": ["DEBUG", "INFO", "WARNING", "ERROR"]},
+    "log_type": {"type": "string", "maxLength": 256, "pattern": "^[a-z][a-z0-9_-]*(\\.[a-z][a-z0-9_-]*)+\\.v[1-9][0-9]*$"},
+    "message": {"type": "string"},
+    "operation_id": {"type": "string"},
+    "event_id": {"type": "string"},
+    "fatal": {"type": "boolean", "description": "Advisory fatal/unhandled metadata; ERROR level determines monitoring independently."},
+    "error": {
+      "type": "object", "required": ["name", "message"], "additionalProperties": true,
+      "properties": {
+        "name": {"type": "string"}, "message": {"type": "string"}, "stack": {"type": "string"},
+        "code": {"type": ["string", "number"]}, "fingerprint": {"type": "string"}
+      }
+    },
+    "data": {}
+  },
+  "additionalProperties": true
+}

package/skills/program-agents/ui-patterns.md

@@ -0,0 +1,39 @@
+# UI Patterns
+
+This file documents and gives ideas for how to use UI to interact with the user. You are by no means limited to these ideas. These are just suggestions.
+
+Overarching themes:
+- Reduce text
+- Use more visuals & interactive components
+- Simplicity is good
+- Challenge yourself in creating richer & more explanatory UI
+
+## Dashboards
+Create a static HTML with image plots & widgets.
+
+Suggested tech stack
+* DuckDB-Wasm for in-browser processing
+* plotly.js
+* Use DuckDB on the backend, or simple datasets, and stream parquet to the browser where most data processing happens
+
+
+## Documents
+Establish a common theme for the user, maybe their corporate marketing theme, and stick to it. Make heavy use of visuals to explain. Think hard about what could explain a concept more clearly.
+
+Include annotate.js and do something with the comments. This is a fantastic way to communicate clearly with the user. Wire up annotate.js with a custom event listener when localStorage is updated (or create a button! better!). Setup a backend endpoint to handle the comments and funnel them to an agent as a message, or send them to collaborators. However the user wants it.
+
+## Interactive diagrams
+Use SVG, HTML, CSS, and JS to create rich and detailed diagrams. Think VERY hard on how a diagram can be made even simpler, or explain a concept more clearly. Remember that simpler explanations almost always are more clear.
+
+Consider using a Three.js scene, especially when the data or concept needs more dimensions.
+
+## Live data / Polling
+If there's ever a need for live or up-to-date data, use React and SSE heavily. As always with live data, be wary of how much memory you're consuming. Shedding data to the backend is a reasonable choice. Prefer to do more on the frontend unless it can't happen on the backend (e.g. polling the filesystem, web services).
+
+## Asking questions
+Sometimes questions involve mediums that you, the agent can't see, like video or audio. And so writing an app for the human to help you out is a perfectly sensible thing to do.
+
+In addition to documents, consider how writing a program agent can leverage the user to a much greater extent.
+
+## Wire in work tools
+Poll github issues, reach out to people over Slack/Teams, integrate with apps. A program agent is a great way to monitor things that are happening in the world around the user. If you can tighten their touch points for them, you'll increase your own ability to see what's going on and anticipate their needs.