@robota-sdk/agent-ui-web 0.0.0-stage → 3.0.0-beta.101

package/docs/README.md

@@ -0,0 +1,62 @@
+# @robota-sdk/agent-ui-web
+
+The **GUI presentation layer** for an agent session — the graphical analog of `@robota-sdk/agent-ui-terminal`.
+It reconstructs conversation state from the transport-neutral `TServerMessage` stream and renders it as React
+components. Its public `/client` entry supplies the browser-safe reducer, WebSocket client, session shell
+and runtime-host contract for a consumer-owned renderer. The same components serve the repository's GUI
+web app and browser-remote surface.
+
+## What it owns
+
+- `useSessionClient(makeClient)` — the transport-neutral session reducer (generic over the status type).
+- `useWsSession(url)` + `createWsSessionClient` — the localhost WebSocket binding.
+- `resolveClientRuntimeHost(environment)` — a browser endpoint resolver or a narrow desktop bridge
+  adapter. The desktop bridge owns trust, endpoint validation and runtime lifecycle; a renderer asks
+  `trustQuestion` before `getEndpoint` and calls `signalReady` after connection.
+- Prompt state: `applyPromptEvent`, `permissionResponse`, `askResponse`.
+- UI-intent state: `guiScreenForUiIntent` (the GUI screen a command's UI intent opens, if any) and
+  `describeUiIntentForGui` (the explicit "not available on this surface" line otherwise).
+- Components: `SessionSurface`, `CenteredChrome`, `ConversationView`, `AgentActivityPanel`,
+  `PermissionPrompt`, `SessionSidebar` (the host's sessions; switch or start one), `SessionMonitor` (a
+  self-contained session page for a WebSocket URL), and `PersonalUsageDashboard` (7- and 30-day usage).
+- Brand marks: `ProductMark`, `ProductWordmark` — render them inside a `agent-ui` scope.
+- `styles/surface.css` — the design scoped to `.agent-ui` (bundled Pretendard, light and dark tokens, Tailwind
+  token map, base layers); import it into a host app's Tailwind entry to embed the surface.
+- `styles/theme.css` — `surface.css` plus what a page that is only the surface owns (height, background,
+  scrollbars); that page puts `agent-ui` on its `<html>`.
+
+## Using it
+
+```tsx
+import { useWsSession, SessionSurface } from '@robota-sdk/agent-ui-web/client';
+
+export function App({ url }: { url: string }) {
+  const state = useWsSession(url);
+  return <SessionSurface state={state} surface="app" />;
+}
+```
+
+The components author Tailwind utility classes and ship **no compiled CSS** — the consumer owns the Tailwind
+entry and sources this package's `src`:
+
+```css
+/* app entry css */
+@import 'tailwindcss';
+@import '@robota-sdk/agent-ui-web/styles/theme.css';
+@source '../../node_modules/@robota-sdk/agent-ui-web/src';
+@source './';
+```
+
+A different transport supplies its own `makeClient` (a `TMakeSessionClient<TStatus>`) and, if it adds
+connection states, instantiates `useSessionClient<ItsStatus>` — see `useRtcSession` in `@robota-sdk/agent-transport-webrtc-web`.
+
+See [SPEC.md](./SPEC.md) for the full contract.
+
+The source repository's Cedar renderer fixture shows a consumer-owned toolbar calling a custom
+command, desktop trust admission, session restoration and reconnect. Its local-pack
+build is prerelease evidence; a clean registry-installed build is required after publication.
+
+The package tarball includes source styles, declarations and its AGPL license. React is a peer dependency;
+the consumer supplies React, React DOM, Tailwind v4 and a bundler. Third-party runtime dependencies are
+declared in `package.json`; a distributable renderer must include their notices and licenses in its own
+artifact. The package does not include the private GUI web app or Electron shell.

package/docs/SPEC.md

@@ -0,0 +1,130 @@
+# SPEC.md — @robota-sdk/agent-ui-web
+
+## Transport Admission
+
+transport-admission: none — a presentation layer. It renders a server-message stream that some
+other transport has already admitted a peer onto, and opens no socket of its own.
+
+## Purpose
+
+The GUI presentation layer for a running agent session — the graphical analog of the terminal
+presentation package. It reconstructs conversation state from the transport-neutral server-message
+stream and renders it as React components, and it ships the session shell (title/status bar,
+conversation column, background-activity rail, and a composer with the pending question docked above
+it). It is consumed by the GUI web app — which the desktop app loads and the CLI serves — and by the
+browser-remote surface.
+
+This package sits in the transport/presentation layer. It is a pure UI + wire-reducer library — it
+does not own session lifecycle, conversation history, or agent runtime state.
+
+## Contract and guarantees
+
+- The session reducer is generic over the connection-status type, so a transport can widen the
+  status union (e.g. to add pairing/failure states) without this package depending on that
+  transport.
+- Every server-message wire variant is assigned an explicit disposition — a specialized reducer
+  path, transport lifecycle handling, or an explicit "intentionally not rendered" marker. An
+  unrecognized or not-yet-supported message never falls through silently.
+- The conversation carries what the CLI's transcript carries: a typed command's outcome and a
+  finished turn's tool calls sit in it where they happened, and never push the composer out of view —
+  the same whether they streamed in live or were rebuilt from a reload, reconnect, or session resume's
+  history replay, never falling back to bare text once a tool call is gone from what a live stream
+  would have shown. A change made through a status control instead confirms itself through the
+  control's own label — never a conversation entry — with a failed change surfaced as a toast instead.
+  Session and protocol failures are also toasts, beside the conversation rather than in it.
+- A tool call's diff or output is server-computed and shown on demand, preserving its observation
+  types, call identity and success or denial/failure through live delivery and replay. Resource references remain inert because
+  displaying a contributor's URI grants no read authority; the one exception is a view the call's own
+  server declared for a model call, read on demand through its session-owned view authority. The host
+  admits the document only in an opaque frame with enforced native network isolation; the bridge
+  reaches only that view's declared tools through the session's permission gate. Replacing a view
+  or its session revokes its pending local requests. A surface without a suitable sandbox retains
+  the text result and explains why the app is unavailable.
+  Unsupported media is explained rather than silently discarded. Output is never recomputed here or buried behind a truncated path or argument; an internal signal tool never renders as a call,
+  and a projected `/command` tool shows the command it ran, not the provider-facing tool name.
+- A UI-intent opens its GUI screen when there is one — the session picker is the session sidebar
+  (unless the host cannot list sessions), settings and the plugin manager both open the Settings
+  modal (the plugin manager on its Plugins section), and the agent switcher is a sheet listing the
+  session's agent definitions with the current one checked. A command with no GUI path at all (its
+  presentation belongs to a terminal, or the product has deliberately left it out — see
+  `packages/agent-gui-web/docs/SPEC.md`) never reaches the session from this surface in the first
+  place: it is caught on the way out and answered with its own plain sentence naming what to use
+  instead. Any other UI-intent this surface simply has no screen for yet answers the same way, in its
+  own words — never the generic "not available on this surface" line, and never a silent no-op — in
+  place of the command's own reply when this surface's command awaits one, at once otherwise; an
+  intent kind not yet known when this package was written still gets an explicit, honest line.
+- The session sidebar lists the host's sessions by a stable title — never the latest reply, which
+  changes every turn — and never loses one silently: a record unreadable and belonging to this
+  workspace is folded into one plain line rather than shown as a row; a record belonging to another
+  workspace, or whose workspace cannot be told, is not this surface's business and is left off the
+  list entirely. A switch replaces everything the surface shows with what the new session holds; a
+  refused switch shows the host's reason. A row can be renamed or deleted from the list itself,
+  without switching to it first; a refusal states why.
+- The agent switcher's roster and current selection are a typed read (`get-agent-definitions`), but
+  choosing a row is not a dedicated write: it sends `/agent <name>` through the same `command` path
+  typing it would, and the sheet shows that command's own reply as a plain line — never a
+  conversation card, unlike every other command result this reducer renders.
+- The Agents panel's Scheduled group and Goal row are additive to the execution-workspace rail:
+  a schedule or a goal alone (no running background task or loop) still opens the rail, and a
+  schedule's Pause/Resume and Delete, and a goal's Cancel, run the same command/control paths their
+  slash commands already use — the panel adds no write this package did not already expose.
+- The title bar and the page title both name the workspace folder the session works in, once the
+  host has said one; the desktop window follows the page title.
+- A pending permission or ask prompt is visible whatever view is open, because a gated turn waits
+  on it. It never takes focus from a field the person is typing in, and its keys answer it only once
+  it has that focus; a click answers at once, except on a multi-select ask, whose options toggle
+  until it is submitted.
+- Nothing typed is lost to a lost connection: while the transport is not `connected`, the composer
+  keeps its draft and refuses to submit it, and a banner above the conversation — never a full-screen
+  replacement — says so: retrying while attempts continue, and once they give up, either the
+  host-supplied reconnect action or how to reopen the page.
+- A session-rename or history-clear broadcast from any other surface is folded into this reducer's
+  state, so co-driving surfaces stay in sync.
+- The personal usage dashboard is opt-in per surface (browser/remote consumers stay opted out by
+  default) and correlates its own requests, keeping latest-request-wins semantics on responses.
+- A background-activity entry opens a detail sheet (status, what it was asked, its paginated
+  transcript, its result) on click — except the main-thread entry, which instead returns to the
+  conversation already shown beside it. A stoppable entry's Stop is routed by whether the entry
+  carries a loop id, never guessed from its name or task kind: a `/loop`-managed entry (fixed or
+  self-paced) sends `/loop stop <id>`, because a self-paced loop's own background-task
+  representation, when it has one, is only its disposable wake timer — cancelling that would leave
+  the loop itself running. Every other entry sends `cancel-background-task`.
+- The Project panel (git status, one file's diff, project memory) correlates its own requests the
+  same way, and every file status it shows is a plain word, never a raw git XY code (#3277 "usable by
+  anyone"); a workspace that is not a git repository, or a diff whose path the host refused, is one
+  plain sentence, never left as a stuck loading state.
+- A session error finalizes any partial streamed text and clears thinking/running-tool state
+  before the next turn begins.
+- Malformed server frames are surfaced through the client's callback path and never thrown inside
+  the socket handler.
+- The package ships no compiled CSS — it authors Tailwind utility classes as source, and the
+  consumer owns the Tailwind entry point that compiles them. Its design applies only inside the
+  `agent-ui` scope that each of its root components opens, so a host with tokens of its own under the
+  same names can embed the surface without either overriding the other.
+- Its public browser entry exposes a narrow runtime-host contract: a native host owns trust and
+  endpoint authority, while a renderer can ask for trust before connecting, observe lifecycle
+  changes, and offer reconnect without importing the native implementation.
+
+## Non-goals / boundaries
+
+- Does not own the wire protocol framing (message types) — that belongs to the transport package.
+- Does not own the transport-facing contract types (interaction/event/workspace) — those belong to
+  the transport-interface package.
+- Does not own session/runtime contracts or agent-core types, and has no dependency on the
+  agent framework, session, or core packages.
+- Does not own the CLI sidecar server.
+- Does not own the WebRTC remote peer or pairing flow — that is a separate package that consumes
+  this package's reducer and components and widens the status union.
+- Does not own the Electron shell or sidecar process supervision — that is the desktop app.
+- Is not re-exported through a sibling product package; consumers import it directly.
+
+## Design decisions
+
+- The reducer is generic over its status type rather than importing a widened status union from
+  the WebRTC package, because importing that union would create a package cycle.
+- The session shell component holds no session/transport logic of its own — it only forwards user
+  intent through the reducer's send/answer handles — so a new GUI surface can reuse it purely by
+  supplying its own client factory.
+- There is deliberately no built-in screen for every UI-intent kind; unhandled kinds get an
+  explicit notice instead of a screen, so a future surface can add a real screen incrementally
+  without ever risking a silent drop in the meantime.

package/package.json

@@ -1,6 +1,102 @@
 {
   "name": "@robota-sdk/agent-ui-web",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "3.0.0-beta.101",
+  "description": "Browser-safe React session presentation, wire reducer, WebSocket client and runtime-host contract for consumer-owned agent renderers.",
+  "license": "AGPL-3.0-only OR LicenseRef-Commercial",
+  "type": "module",
+  "main": "dist/node/index.js",
+  "types": "dist/node/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "import": {
+        "types": "./dist/node/index.d.ts",
+        "default": "./dist/node/index.js"
+      },
+      "require": {
+        "types": "./dist/node/index.d.cts",
+        "default": "./dist/node/index.cjs"
+      },
+      "default": "./dist/node/index.js"
+    },
+    "./client": {
+      "source": "./src/index.ts",
+      "import": {
+        "types": "./dist/browser/index.d.ts",
+        "default": "./dist/browser/index.js"
+      },
+      "default": "./dist/browser/index.js"
+    },
+    "./styles/theme.css": {
+      "types": "./src/styles/theme.css.d.mts",
+      "browser": "./src/styles/theme.css",
+      "import": "./src/styles/theme.css"
+    },
+    "./styles/surface.css": {
+      "types": "./src/styles/surface.css.d.mts",
+      "browser": "./src/styles/surface.css",
+      "import": "./src/styles/surface.css"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/__tests__/**",
+    "!src/testing/**",
+    "README.md",
+    "docs/README.md",
+    "docs/SPEC.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "lucide-react": "^1.26.0",
+    "pretendard": "^1.3.9",
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1",
+    "@robota-sdk/agent-interface-command": "3.0.0-beta.101",
+    "@robota-sdk/agent-interface-execution": "3.0.0-beta.101",
+    "@robota-sdk/agent-interface-transport": "3.0.0-beta.101",
+    "@robota-sdk/agent-interface-session": "3.0.0-beta.101",
+    "@robota-sdk/agent-transport": "3.0.0-beta.101"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "jsdom": "^25.0.1",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "rimraf": "^5.0.0",
+    "tsdown": "^0.22.14",
+    "typescript": "^6.0.3",
+    "vitest": "^3.2.6"
+  },
+  "volta": {
+    "extends": "../../package.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/woojubb/robota"
+  },
+  "bugs": {
+    "url": "https://github.com/woojubb/robota/issues"
+  },
+  "homepage": "https://robota.io/",
+  "scripts": {
+    "build": "rimraf dist && tsdown",
+    "build:js": "pnpm run build",
+    "build:types": "pnpm run build",
+    "typecheck": "tsgo --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:coverage": "vitest run --coverage --passWithNoTests",
+    "clean": "rimraf dist"
+  }
 }

package/src/app-view/bridge.ts

@@ -0,0 +1,217 @@
+import { outcomeToCallToolResult, type ICallToolResult } from './call-tool-result.js';
+
+import type { TAppToolArguments, TAppToolOutcome, TAppView } from './types.js';
+
+export const APP_VIEW_PROTOCOL_VERSION = '2026-01-26';
+export const APP_VIEW_MIN_HEIGHT_PX = 48;
+export const APP_VIEW_MAX_HEIGHT_PX = 640;
+
+const INVALID_PARAMS = -32602;
+const METHOD_NOT_FOUND = -32601;
+const HOST_ERROR = -32000;
+
+const SANDBOX_PROXY_READY = 'ui/notifications/sandbox-proxy-ready';
+const SANDBOX_RESOURCE_READY = 'ui/notifications/sandbox-resource-ready';
+
+type TJsonRpcId = string | number;
+
+export interface IAppViewMessage {
+  jsonrpc: '2.0';
+  id?: TJsonRpcId;
+  method?: string;
+  params?: unknown;
+  result?: unknown;
+  error?: { code: number; message: string };
+}
+
+export interface IAppViewHostContext {
+  theme: 'light' | 'dark';
+  displayMode: 'inline';
+  availableDisplayModes: readonly ['inline'];
+  containerDimensions: { maxHeight: number };
+  platform: 'desktop' | 'web';
+  locale: string;
+  timeZone: string;
+}
+
+export interface IAppViewBridgeOptions {
+  view: TAppView;
+
+  toolResult: ICallToolResult;
+  hostInfo: { name: string; version: string };
+  hostContext: IAppViewHostContext;
+
+  post: (message: IAppViewMessage) => void;
+
+  source: () => MessageEventSource | null;
+
+  callAppTool: (runtimeName: string, args: TAppToolArguments) => Promise<TAppToolOutcome>;
+
+  onHeight: (px: number) => void;
+}
+
+export interface IAppViewBridge {
+  handleMessage: (event: MessageEvent) => void;
+  dispose: () => void;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const prototype: unknown = Object.getPrototypeOf(value);
+  return prototype === null || Object.getPrototypeOf(prototype) === null;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export function createAppViewBridge(options: IAppViewBridgeOptions): IAppViewBridge {
+  const { view } = options;
+  let disposed = false;
+  let sandboxAnswered = false;
+  let initialization: 'uninitialized' | 'initializing' | 'ready' = 'uninitialized';
+  let callInFlight = false;
+
+  const respond = (id: TJsonRpcId, result: unknown): void => {
+    options.post({ jsonrpc: '2.0', id, result });
+  };
+  const refuse = (id: TJsonRpcId, code: number, message: string): void => {
+    options.post({ jsonrpc: '2.0', id, error: { code, message } });
+  };
+
+  const callTool = (id: TJsonRpcId, params: unknown): void => {
+    if (initialization !== 'ready') {
+      refuse(id, HOST_ERROR, 'This app view has not initialized.');
+      return;
+    }
+    const name = isPlainObject(params) ? params['name'] : undefined;
+    const runtimeName =
+      typeof name === 'string' && Object.hasOwn(view.callableTools, name)
+        ? view.callableTools[name]
+        : undefined;
+    if (!isPlainObject(params) || runtimeName === undefined) {
+      refuse(id, INVALID_PARAMS, 'This tool is not available to this view.');
+      return;
+    }
+    const rawArguments = params['arguments'] === undefined ? {} : params['arguments'];
+    if (!isPlainObject(rawArguments)) {
+      refuse(id, INVALID_PARAMS, 'Tool arguments must be an object.');
+      return;
+    }
+    if (callInFlight) {
+      refuse(id, HOST_ERROR, 'Another tool call from this view is still running.');
+      return;
+    }
+    callInFlight = true;
+    let outcome: Promise<TAppToolOutcome>;
+    try {
+      outcome = options.callAppTool(runtimeName, rawArguments as TAppToolArguments);
+    } catch (error: unknown) {
+      outcome = Promise.reject(error);
+    }
+    outcome.then(
+      (settled) => {
+        callInFlight = false;
+        if (!disposed) respond(id, outcomeToCallToolResult(settled));
+      },
+      (error: unknown) => {
+        callInFlight = false;
+        if (!disposed) refuse(id, HOST_ERROR, errorMessage(error));
+      },
+    );
+  };
+
+  const handleRequest = (id: TJsonRpcId, method: string, params: unknown): void => {
+    switch (method) {
+      case 'ui/initialize':
+        if (initialization === 'uninitialized') initialization = 'initializing';
+        respond(id, {
+          protocolVersion: APP_VIEW_PROTOCOL_VERSION,
+          hostCapabilities: { serverTools: {} },
+          hostInfo: options.hostInfo,
+          hostContext: options.hostContext,
+        });
+        return;
+      case 'tools/call':
+        callTool(id, params);
+        return;
+      case 'ping':
+        respond(id, {});
+        return;
+      case 'ui/request-display-mode':
+        respond(id, { mode: 'inline' });
+        return;
+      default:
+        refuse(id, METHOD_NOT_FOUND, `This host does not support ${method}.`);
+    }
+  };
+
+  const handleNotification = (method: string, params: unknown): void => {
+    switch (method) {
+      case SANDBOX_PROXY_READY:
+        // The sandbox page is the only sender; the document goes to it once, never again.
+        if (sandboxAnswered) return;
+        sandboxAnswered = true;
+        options.post({
+          jsonrpc: '2.0',
+          method: SANDBOX_RESOURCE_READY,
+          params: { html: view.html },
+        });
+        return;
+      case 'ui/notifications/initialized':
+        if (initialization !== 'initializing') return;
+        initialization = 'ready';
+        options.post({
+          jsonrpc: '2.0',
+          method: 'ui/notifications/tool-input',
+          params: { arguments: view.toolInput ?? {} },
+        });
+        options.post({
+          jsonrpc: '2.0',
+          method: 'ui/notifications/tool-result',
+          params: options.toolResult,
+        });
+        return;
+      case 'ui/notifications/size-changed': {
+        const height = isPlainObject(params) ? params['height'] : undefined;
+        if (typeof height !== 'number' || !Number.isFinite(height)) return;
+        options.onHeight(
+          Math.min(APP_VIEW_MAX_HEIGHT_PX, Math.max(APP_VIEW_MIN_HEIGHT_PX, Math.round(height))),
+        );
+        return;
+      }
+      default:
+        // Anything else a view announces (logging, its own notices) has no consumer here.
+        return;
+    }
+  };
+
+  return {
+    handleMessage(event) {
+      if (disposed) return;
+      const frame = options.source();
+      if (frame === null || event.source !== frame) return;
+      const data: unknown = event.data;
+      if (!isPlainObject(data) || data['jsonrpc'] !== '2.0') return;
+      const { method, id } = data;
+      if (typeof method !== 'string') return;
+      if (id === undefined) {
+        handleNotification(method, data['params']);
+      } else if (typeof id === 'string' || typeof id === 'number') {
+        handleRequest(id, method, data['params']);
+      }
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      if (initialization === 'ready') {
+        options.post({
+          jsonrpc: '2.0',
+          id: 'teardown',
+          method: 'ui/resource-teardown',
+          params: { reason: 'closed' },
+        });
+      }
+    },
+  };
+}

package/src/app-view/call-tool-result.ts

@@ -0,0 +1,58 @@
+import type { TAppToolOutcome, TAppToolPart, TAppView } from './types.js';
+import type { IActiveTool } from '../hooks/session-client-types.js';
+
+export type TCallToolContent =
+  | { type: 'text'; text: string }
+  | { type: 'image'; data: string; mimeType: string }
+  | { type: 'audio'; data: string; mimeType: string };
+
+export interface ICallToolResult {
+  content: TCallToolContent[];
+  structuredContent?: Record<string, unknown>;
+  isError: boolean;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export function contentFromParts(parts: readonly TAppToolPart[] | undefined): TCallToolContent[] {
+  const content: TCallToolContent[] = [];
+  for (const part of parts ?? []) {
+    if (part.type === 'text') {
+      content.push({ type: 'text', text: part.text });
+    } else if (part.type === 'image_inline') {
+      content.push({ type: 'image', data: part.data, mimeType: part.mimeType });
+    } else if (part.type === 'audio_inline') {
+      content.push({ type: 'audio', data: part.data, mimeType: part.mimeType });
+    }
+  }
+  return content;
+}
+
+export function outcomeToCallToolResult(outcome: TAppToolOutcome): ICallToolResult {
+  let content = contentFromParts(outcome.parts);
+  if (content.length === 0 && typeof outcome.data === 'string') {
+    content = [{ type: 'text', text: outcome.data }];
+  }
+  if (!outcome.success && outcome.error !== undefined) {
+    content = [...content, { type: 'text', text: outcome.error }];
+  }
+  return {
+    content,
+    ...(isRecord(outcome.data) ? { structuredContent: outcome.data } : {}),
+    isError: !outcome.success,
+  };
+}
+
+export function toCallToolResult(tool: IActiveTool, view: TAppView): ICallToolResult {
+  let content = contentFromParts(tool.toolResultParts);
+  if (content.length === 0 && tool.toolResultData !== undefined) {
+    content = [{ type: 'text', text: tool.toolResultData }];
+  }
+  return {
+    content,
+    ...(isRecord(view.structuredContent) ? { structuredContent: view.structuredContent } : {}),
+    isError: tool.status === 'error',
+  };
+}

package/src/app-view/host-context.ts

@@ -0,0 +1,37 @@
+import { createContext } from 'react';
+
+import { APP_VIEW_MAX_HEIGHT_PX, type IAppViewHostContext } from './bridge.js';
+
+import type { TAppToolArguments, TAppToolOutcome, TAppView } from './types.js';
+
+export interface IAppViewHost {
+  sandboxUrl?: string;
+
+  readAppView: (viewKey: string, signal?: AbortSignal) => Promise<TAppView>;
+  callAppTool: (
+    viewKey: string,
+    name: string,
+    args: TAppToolArguments,
+    signal?: AbortSignal,
+  ) => Promise<TAppToolOutcome>;
+  hostInfo: { name: string; version: string };
+  platform: 'desktop' | 'web';
+}
+
+export const AppViewHostContext = createContext<IAppViewHost | null>(null);
+
+export function readAppViewHostContext(platform: IAppViewHost['platform']): IAppViewHostContext {
+  const dark =
+    typeof window !== 'undefined' &&
+    typeof window.matchMedia === 'function' &&
+    window.matchMedia('(prefers-color-scheme: dark)').matches;
+  return {
+    theme: dark ? 'dark' : 'light',
+    displayMode: 'inline',
+    availableDisplayModes: ['inline'],
+    containerDimensions: { maxHeight: APP_VIEW_MAX_HEIGHT_PX },
+    platform,
+    locale: typeof navigator === 'undefined' ? 'en-US' : navigator.language,
+    timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+  };
+}

package/src/app-view/types.ts

@@ -0,0 +1,12 @@
+import type { TClientMessage, TServerMessage } from '@robota-sdk/agent-transport';
+
+export type TAppView = Extract<TServerMessage, { type: 'app_view' }>['view'];
+
+export type TAppToolOutcome = Omit<
+  Extract<TServerMessage, { type: 'app_tool_result' }>,
+  'type' | 'requestId'
+>;
+
+export type TAppToolArguments = Extract<TClientMessage, { type: 'call-app-tool' }>['arguments'];
+
+export type TAppToolPart = NonNullable<TAppToolOutcome['parts']>[number];