@zhin.js/client 2.1.9 → 2.1.11

package/README.md

@@ -27,6 +27,10 @@ Peer：`react >= 18`（`createPluginRegisterHostApi` 需要 React 引用）。
 | `normalizeConsolePushType` / `normalizeConsolePushMessage` | 在 SDK 边界兼容旧 `endpoint:*` 推送并输出规范事件与 payload |
 | `parseConsoleInboxEvent` | 一次完成 Inbox 推送名称、身份别名和 message/request/notice 分类 |
 | `ConsoleEndpointSummary` / `EndpointManagementCapability` | Host 与 Remote Console 共享的 Endpoint wire 类型 |
+| `fetchConsoleEventHistory` | 按 `(runtimeId, eventId)` 拉取有界事件历史 |
+| `WebSocketManager.onConsoleEvent` | 订阅带 `live/history` 投递来源的强类型事件 |
+| `WebSocketManager.onConsoleEventRecoveryGap` | 观察不可续接游标并触发领域全量重同步 |
+| `ConsoleInboxNoticesQuery` / `ConsoleInboxNoticesResult` | 以 `unreadOnly` 从持久 Inbox 重建未读通知 |
 
 类型与 Entry 契约来自 `@zhin.js/contract`。
 
@@ -97,6 +101,8 @@ const res = await apiFetch("/api/console/request", {
 
 辅助：`resolveApiUrl`、`resolveWebSocketUrl`（SSE `/api/events` 等）。
 
+Client 在连接 `/api/events` 前先补拉 `/api/events/history`，再携带最新游标进入 SSE；Host 会原子重放 HTTP 与订阅之间产生的事件。游标只在 Inbox 持久化成功后推进，重复的 history/live 投递按 `(runtimeId, eventId)` 幂等写入 IndexedDB。`gap` 不会被吞掉，页面可订阅恢复缺口并改走领域 HTTP 全量投影。
+
 ## `createPluginRegisterHostApi`
 
 将壳层已有的 React 与路由/工具注册函数适配为契约中的 `PluginRegisterHostApi`（含 `addPage` 别名 → `addRoute`）：

package/client/console-events.ts

@@ -0,0 +1,37 @@
+import type {
+  ConsoleEventHistoryPage,
+  ConsoleEventHistoryQuery,
+} from '@zhin.js/console-protocol';
+import { getStoredToken, resolveApiUrl } from './websocket/remote-settings.js';
+
+export interface FetchConsoleEventHistoryOptions {
+  readonly signal?: AbortSignal;
+}
+
+/** Read a typed page from the Host's bounded Console event journal. */
+export async function fetchConsoleEventHistory(
+  query: ConsoleEventHistoryQuery = {},
+  options: FetchConsoleEventHistoryOptions = {},
+): Promise<ConsoleEventHistoryPage> {
+  const params = new URLSearchParams();
+  if (query.runtimeId) params.set('runtimeId', query.runtimeId);
+  if (query.after !== undefined) params.set('after', String(query.after));
+  if (query.limit !== undefined) params.set('limit', String(query.limit));
+  const token = getStoredToken();
+  const headers: Record<string, string> = { Accept: 'application/json' };
+  if (token) headers.Authorization = `Bearer ${token}`;
+  const suffix = params.size ? `?${params}` : '';
+  const response = await fetch(resolveApiUrl(`/api/events/history${suffix}`), {
+    headers,
+    signal: options.signal,
+  });
+  const body = await response.json() as {
+    success?: boolean;
+    data?: ConsoleEventHistoryPage;
+    error?: string;
+  };
+  if (!response.ok || body.success !== true || !body.data) {
+    throw new Error(body.error ?? `Console event history failed: HTTP ${response.status}`);
+  }
+  return body.data;
+}

package/client/index.ts

@@ -2,6 +2,7 @@
 export * from "./types";
 export {
   ENDPOINT_RPC,
+  CONSOLE_EVENT_RECOVERY_GAP_EVENT,
   ENDPOINT_MANAGEMENT_CAPABILITIES,
   INBOX_RPC,
   SIDE_EVENT_PUSH,
@@ -11,14 +12,55 @@ export {
   parseConsoleInboxEvent,
   type ConsoleInboxEvent,
   type ConsoleInboxEventKind,
+  type ConsoleInboxNoticeRow,
+  type ConsoleInboxNoticesQuery,
+  type ConsoleInboxNoticesResult,
   type ConsoleEndpointPhase,
   type ConsoleEndpointSummary,
+  type ConsoleEventActor,
+  type ConsoleEventChannel,
   type EndpointManagementCapability,
+  parseConsoleSseFrame,
+  type ConsoleEventDelivery,
+  type ConsoleEventData,
+  type ConsoleEndpointEventData,
+  type ConsoleEventEnvelope,
+  type ConsoleEventHistoryPage,
+  type ConsoleEventHistoryQuery,
+  type ConsoleEventPayloadMap,
+  type ConsoleMessageEventData,
+  type ConsoleNoticeEventData,
+  type ConsoleRequestEventData,
+  type KnownConsoleEventType,
+  type KnownConsoleEventEnvelope,
+  type ParsedConsoleSseFrame,
 } from "@zhin.js/console-protocol";
 
+export {
+  fetchConsoleEventHistory,
+  type FetchConsoleEventHistoryOptions,
+} from './console-events.js';
+
 // Media URL resolution
 export { resolveMediaSrc, pickMediaRawUrl, type MediaKind } from "./mediaSrc";
 
+// Safe rich message rendering (Markdown + code blocks; no raw HTML execution)
+export {
+  MarkdownContent,
+  CodeBlock,
+  type MarkdownContentProps,
+} from "./message-content/MarkdownContent.js";
+export {
+  parseMarkdown,
+  parseMarkdownInline,
+  highlightCodeLine,
+  isSafeMarkdownHref,
+  type MarkdownBlock,
+  type MarkdownInline,
+  type CodeToken,
+  type CodeTokenKind,
+} from "./message-content/markdown.js";
+
 // Segment IM visibility (inbox vs agent panel)
 export { segmentsForImDelivery, segmentsForAgentPanel } from "./segments.js";
 
@@ -67,8 +109,8 @@ export {
   type LoadConsoleEntriesOptions,
 } from "./bootstrap/loadConsoleEntries.js";
 
-export { registerOrchestrationConsole } from "./orchestration/registerOrchestrationConsole.js";
-export { default as OrchestrationRunsPage } from "./orchestration/OrchestrationRunsPage.js";
+export { registerWorkroomConsole } from "./workroom/registerWorkroomConsole.js";
+export { default as WorkroomRunsPage } from "./workroom/WorkroomRunsPage.js";
 
 export {
   startAgentSession,

package/client/mediaSrc.test.ts

@@ -31,4 +31,19 @@ describe('pickMediaRawUrl', () => {
     expect(pickMediaRawUrl(undefined)).toBeUndefined();
     expect(pickMediaRawUrl({})).toBeUndefined();
   });
+
+  it('rejects executable data URLs, credentials, and malformed base64', () => {
+    expect(resolveMediaSrc('data:text/html;base64,PHNjcmlwdD4=', 'image')).toBeUndefined();
+    expect(resolveMediaSrc('data:image/svg+xml;base64,PHN2Zz4=', 'image')).toBeUndefined();
+    expect(resolveMediaSrc('https://user:secret@example.com/a.png', 'image')).toBeUndefined();
+    expect(resolveMediaSrc('base64://not:base64', 'image')).toBeUndefined();
+  });
+
+  it('accepts only data MIME types matching the rendered media kind', () => {
+    expect(resolveMediaSrc('data:image/png;base64,aGVsbG8=', 'image')).toBe(
+      'data:image/png;base64,aGVsbG8=',
+    );
+    expect(resolveMediaSrc('data:image/png;base64,aGVsbG8=', 'video')).toBeUndefined();
+    expect(resolveMediaSrc('javascript:alert(1)', 'image')).toBeUndefined();
+  });
 });

package/client/mediaSrc.ts

@@ -3,10 +3,54 @@ export type MediaKind = 'image' | 'video' | 'audio'
 
 const BASE64_PROTO = 'base64://'
 
-const SAFE_URL_SCHEMES = ['data:', 'blob:', 'http://', 'https://']
+const SAFE_DATA_MIME: Readonly<Record<MediaKind, ReadonlySet<string>>> = Object.freeze({
+  image: new Set(['image/avif', 'image/gif', 'image/jpeg', 'image/png', 'image/webp']),
+  video: new Set(['video/mp4', 'video/ogg', 'video/webm']),
+  audio: new Set(['audio/mpeg', 'audio/mp4', 'audio/ogg', 'audio/wav', 'audio/webm']),
+})
 
-function isSafeUrl(url: string): boolean {
-  return SAFE_URL_SCHEMES.some((scheme) => url.startsWith(scheme))
+function resolveSafeRemoteUrl(value: string): string | undefined {
+  try {
+    const parsed = new URL(value)
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:' && parsed.protocol !== 'blob:') {
+      return undefined
+    }
+    if (parsed.username || parsed.password) return undefined
+    return parsed.href
+  } catch {
+    return undefined
+  }
+}
+
+function resolveSafeDataUrl(value: string, kind: MediaKind): string | undefined {
+  if (!value.startsWith('data:')) return undefined
+  const separator = value.indexOf(',')
+  if (separator < 0) return undefined
+  const header = value.slice('data:'.length, separator).toLowerCase()
+  if (!header.endsWith(';base64')) return undefined
+  const mime = header.slice(0, -';base64'.length)
+  if (!SAFE_DATA_MIME[kind].has(mime)) return undefined
+  const payload = compactBase64(value.slice(separator + 1))
+  return payload ? `data:${mime};base64,${payload}` : undefined
+}
+
+function compactBase64(value: string): string | undefined {
+  let compact = ''
+  for (const character of value) {
+    if (character === ' ' || character === '\n' || character === '\r' || character === '\t') continue
+    const code = character.charCodeAt(0)
+    const allowed = (code >= 48 && code <= 57)
+      || (code >= 65 && code <= 90)
+      || (code >= 97 && code <= 122)
+      || character === '+' || character === '/' || character === '='
+    if (!allowed) return undefined
+    compact += character
+  }
+  const padding = compact.indexOf('=')
+  if (padding >= 0 && (compact.length - padding > 2 || compact.slice(padding).replace(/=/g, '') !== '')) {
+    return undefined
+  }
+  return compact || undefined
 }
 
 /**
@@ -27,26 +71,29 @@ export function resolveMediaSrc(
   const s = raw.trim()
   if (!s) return undefined
 
-  if (isSafeUrl(s)) {
-    return s
-  }
+  const dataUrl = resolveSafeDataUrl(s, kind)
+  if (dataUrl) return dataUrl
+
+  const remoteUrl = resolveSafeRemoteUrl(s)
+  if (remoteUrl) return remoteUrl
 
   if (!s.startsWith(BASE64_PROTO)) {
-    return isSafeUrl(s) ? s : undefined
+    return undefined
   }
 
-  const payload = s.slice(BASE64_PROTO.length).replace(/^\s+/, '')
+  const payload = s.slice(BASE64_PROTO.length).trimStart()
   if (!payload) return undefined
 
   // 已是 type/subtype;base64, 片段（不含 data: 前缀）
-  if (/^[\w+.-]+\/[\w+.-]+;base64,/i.test(payload)) {
-    return `data:${payload}`
+  const declared = resolveSafeDataUrl(`data:${payload}`, kind)
+  if (declared) {
+    return declared
   }
 
   const defaultMime =
     kind === 'image' ? 'image/png' : kind === 'video' ? 'video/mp4' : 'audio/mpeg'
-  const b64 = payload.replace(/\s/g, '')
-  return `data:${defaultMime};base64,${b64}`
+  const b64 = compactBase64(payload)
+  return b64 ? `data:${defaultMime};base64,${b64}` : undefined
 }
 
 /** 从 segment.data 取常见媒体字段（优先 canonical MediaRef） */

package/client/message-content/MarkdownContent.tsx

@@ -0,0 +1,128 @@
+import { Fragment, useMemo, useState, type ReactNode } from 'react';
+import {
+  highlightCodeLine,
+  parseMarkdown,
+  type MarkdownInline,
+} from './markdown.js';
+
+export interface MarkdownContentProps {
+  readonly text: string;
+  readonly className?: string;
+}
+
+function InlineContent({ content }: { readonly content: readonly MarkdownInline[] }) {
+  const nodes: ReactNode[] = [];
+  content.forEach((token, index) => {
+    const key = `${token.type}-${index}`;
+    const value = token.value.split('\n').map((line, lineIndex, lines) => (
+      <Fragment key={`${key}-line-${lineIndex}`}>
+        {line}
+        {lineIndex < lines.length - 1 ? <br /> : null}
+      </Fragment>
+    ));
+    if (token.type === 'strong') nodes.push(<strong key={key}>{value}</strong>);
+    else if (token.type === 'emphasis') nodes.push(<em key={key}>{value}</em>);
+    else if (token.type === 'strike') nodes.push(<del key={key}>{value}</del>);
+    else if (token.type === 'code') nodes.push(<code key={key} className="im-inline-code">{token.value}</code>);
+    else if (token.type === 'link') nodes.push(
+      <a key={key} href={token.href} target={token.href.startsWith('#') ? undefined : '_blank'} rel="noreferrer" className="im-message-link">{value}</a>,
+    );
+    else nodes.push(<Fragment key={key}>{value}</Fragment>);
+  });
+  return <>{nodes}</>;
+}
+
+export function CodeBlock({ code, language = '', closed = true }: { readonly code: string; readonly language?: string; readonly closed?: boolean }) {
+  const [copied, setCopied] = useState(false);
+  const [wrapped, setWrapped] = useState(false);
+  const [expanded, setExpanded] = useState(false);
+  const lines = useMemo(() => code.split('\n'), [code]);
+  const isLong = lines.length > 18 || code.length > 1800;
+  const visibleLines = isLong && !expanded ? lines.slice(0, 18) : lines;
+
+  const copy = async () => {
+    try {
+      await navigator.clipboard.writeText(code);
+      setCopied(true);
+      window.setTimeout(() => setCopied(false), 1600);
+    } catch {
+      setCopied(false);
+    }
+  };
+
+  return (
+    <figure className="zhin-code-block">
+      <figcaption className="zhin-code-toolbar">
+        <span className="zhin-code-language">{language || 'plain text'}</span>
+        {!closed ? <span className="zhin-code-streaming">生成中</span> : null}
+        <span className="zhin-code-actions">
+          <button type="button" onClick={() => setWrapped((value) => !value)} aria-pressed={wrapped}>{wrapped ? '不折行' : '折行'}</button>
+          <button type="button" onClick={() => void copy()}>{copied ? '已复制' : '复制'}</button>
+        </span>
+      </figcaption>
+      <pre className={wrapped ? 'zhin-code-pre zhin-code-pre--wrap' : 'zhin-code-pre'}>
+        <code>
+          {visibleLines.map((line, lineIndex) => (
+            <span className="zhin-code-line" key={`${lineIndex}-${line}`}>
+              <span className="zhin-code-line-number" aria-hidden="true">{lineIndex + 1}</span>
+              <span className="zhin-code-line-content">
+                {highlightCodeLine(line, language).map((token, tokenIndex) => (
+                  <span key={`${token.kind}-${tokenIndex}`} className={`zhin-code-token zhin-code-token--${token.kind}`}>{token.value}</span>
+                ))}
+                {'\n'}
+              </span>
+            </span>
+          ))}
+        </code>
+      </pre>
+      {isLong ? (
+        <button type="button" className="zhin-code-expand" onClick={() => setExpanded((value) => !value)}>
+          {expanded ? '收起代码' : `展开其余 ${lines.length - visibleLines.length} 行`}
+        </button>
+      ) : null}
+    </figure>
+  );
+}
+
+export function MarkdownContent({ text, className }: MarkdownContentProps) {
+  const blocks = useMemo(() => parseMarkdown(text), [text]);
+
+  return (
+    <div className={['im-markdown-body', 'zhin-markdown', className].filter(Boolean).join(' ')}>
+      {blocks.map((block, index) => {
+        if (block.type === 'heading') {
+          const Heading = `h${block.level}` as keyof React.JSX.IntrinsicElements;
+          return <Heading key={index} className={`im-markdown-heading im-markdown-heading-${block.level}`}><InlineContent content={block.content} /></Heading>;
+        }
+        if (block.type === 'paragraph') return <p key={index} className="im-markdown-paragraph"><InlineContent content={block.content} /></p>;
+        if (block.type === 'quote') return <blockquote key={index} className="im-markdown-quote"><InlineContent content={block.content} /></blockquote>;
+        if (block.type === 'rule') return <hr key={index} className="zhin-markdown-rule" />;
+        if (block.type === 'code') return <CodeBlock key={index} code={block.value} language={block.language} closed={block.closed} />;
+        if (block.type === 'list') {
+          const List = block.ordered ? 'ol' : 'ul';
+          return (
+            <List key={index} className={`im-markdown-list${block.ordered ? ' im-markdown-list-ordered' : ''}`}>
+              {block.items.map((item, itemIndex) => (
+                <li key={itemIndex} className={item.checked === undefined ? undefined : 'zhin-markdown-task'}>
+                  {item.checked === undefined ? null : <input type="checkbox" checked={item.checked} readOnly aria-label={item.checked ? '已完成' : '未完成'} />}
+                  <InlineContent content={item.content} />
+                </li>
+              ))}
+            </List>
+          );
+        }
+        if (block.type === 'table') {
+          return (
+            <div className="zhin-markdown-table-wrap" key={index}>
+              <table className="zhin-markdown-table">
+                <thead><tr>{block.header.map((cell, cellIndex) => <th key={cellIndex}><InlineContent content={cell} /></th>)}</tr></thead>
+                <tbody>{block.rows.map((row, rowIndex) => <tr key={rowIndex}>{row.map((cell, cellIndex) => <td key={cellIndex}><InlineContent content={cell} /></td>)}</tr>)}</tbody>
+              </table>
+            </div>
+          );
+        }
+        return null;
+      })}
+    </div>
+  );
+}

package/client/message-content/markdown.test.ts

@@ -0,0 +1,48 @@
+import { highlightCodeLine, isSafeMarkdownHref, parseMarkdown, parseMarkdownInline } from './markdown.js';
+
+describe('message markdown', () => {
+  it('parses rich blocks including tables and tasks', () => {
+    const blocks = parseMarkdown(`# Result
+
+- [x] inspect runtime
+- [ ] publish patch
+
+| field | value |
+| --- | --- |
+| status | **ready** |`);
+
+    expect(blocks.map((block) => block.type)).toEqual(['heading', 'list', 'table']);
+    expect(blocks[1]).toMatchObject({ type: 'list', items: [{ checked: true }, { checked: false }] });
+  });
+
+  it('keeps incomplete streaming fences renderable', () => {
+    expect(parseMarkdown('```ts\nconst ready = true')).toEqual([
+      { type: 'code', language: 'ts', value: 'const ready = true', closed: false },
+    ]);
+  });
+
+  it('rejects unsafe markdown links without emitting active links', () => {
+    expect(isSafeMarkdownHref('javascript:alert(1)')).toBe(false);
+    expect(isSafeMarkdownHref('https://zhin.dev/docs')).toBe(true);
+    expect(parseMarkdownInline('[run](javascript:alert(1))')).toEqual([
+      { type: 'text', value: '[run](javascript:alert(1))' },
+    ]);
+  });
+
+  it('treats repeated unmatched link openers as plain text', () => {
+    const value = '['.repeat(20_000);
+    expect(parseMarkdownInline(value)).toEqual([{ type: 'text', value }]);
+  });
+
+  it('tokenizes common code without producing html', () => {
+    expect(highlightCodeLine('const answer = "<safe>" // note', 'ts')).toEqual([
+      { kind: 'keyword', value: 'const' },
+      { kind: 'plain', value: ' ' },
+      { kind: 'plain', value: 'answer' },
+      { kind: 'plain', value: ' = ' },
+      { kind: 'string', value: '"<safe>"' },
+      { kind: 'plain', value: ' ' },
+      { kind: 'comment', value: '// note' },
+    ]);
+  });
+});