@agent-native/core 0.117.1 → 0.118.0

package/corpus/README.md

@@ -28,6 +28,6 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- core files: 1531
-- toolkit files: 145
-- template files: 6410
+- core files: 1544
+- toolkit files: 159
+- template files: 6455

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @agent-native/core
 
+## 0.118.0
+
+### Minor Changes
+
+- f0da2e0: Add the styling-runtime-agnostic custom design system contract, safe component adapters, semantic theme tokens, and build-time theme CSS generation. New scaffolded apps now include the explicit design-system module, ToolkitProvider seam, and toolkit dependency so custom adapters can be registered from the first render.
+
+### Patch Changes
+
+- f0da2e0: Harden custom design system color gamut handling, semantic default-adapter behavior, sharing controller reuse, and build-time theme cascade ordering. Add complete MUI and Ant Design Chat examples that exercise the public conformance contract, and route normalized settings, sharing, sidebar, and agent-panel chrome through the registered semantic adapters.
+- f0da2e0: Preserve staged cookies across MCP OAuth redirects so browser callbacks retain their authorization flow state.
+- f0da2e0: Add horizontal breathing room around in-chat MCP connection suggestions.
+- f0da2e0: Keep parent chats alive while a delegated A2A task is actively processing.
+- f0da2e0: Clip the active tool-call shine to the tool label instead of painting it across the full row.
+- f0da2e0: Preserve normalized core control icon sizing and semantic button styling while keeping settings defaults and sharing overlays consistent.
+- f0da2e0: Preserve the active chat when page chat and sidebar chat share a thread store.
+- f0da2e0: Serialize realtime voice responses and recover from overlapping response requests without ending the voice session.
+- f0da2e0: Make the Dispatch chat composer recover from unavailable AI status checks and keep its Add menu clickable.
+- f0da2e0: Route the Builder connection card and chat history rail through semantic design-system components while preserving their default presentation and shared controller paths.
+- f0da2e0: Consolidate sharing query, mutation, member-search, optimistic-cache, and
+  error-handling primitives behind the ShareButton and ShareDialog controllers.
+- f0da2e0: ShareButton and ShareDialog controllers now share optimistic updates, rollback handling, organization-member search, and error reporting while preserving pending state across close and reopen.
+- f0da2e0: Show a pending spinner while an MCP OAuth connection is preparing its redirect.
+- Updated dependencies [f0da2e0]
+- Updated dependencies [f0da2e0]
+- Updated dependencies [f0da2e0]
+- Updated dependencies [f0da2e0]
+- Updated dependencies [f0da2e0]
+- Updated dependencies [f0da2e0]
+  - @agent-native/toolkit@0.10.0
+
+## 0.117.2
+
+### Patch Changes
+
+- bc91e11: Archive extensions without deleting their history, data, or sharing configuration.
+- bc91e11: Add a shared editable user profile to settings and the workspace switcher.
+- bc91e11: Render transactional email branding with a SendGrid-compatible inline logo and text fallback.
+- bc91e11: Bound foreground serverless database pools to one connection and retry transient connection-exhaustion errors.
+- bc91e11: Render the default Share trigger as a text-only button without a visibility icon.
+
 ## 0.117.1
 
 ### Patch Changes

package/corpus/core/docs/content/custom-design-system.mdx

@@ -0,0 +1,445 @@
+---
+title: "Custom Design Systems"
+description: "Use your company’s React design system across Agent Native apps and shared Toolkit experiences without replacing Agent Native behavior."
+---
+
+# Custom Design Systems
+
+Agent Native can render app-owned screens and shared Toolkit experiences with
+your company’s React components. Register an explicit, typed adapter once; the
+same feature controllers continue to own actions, state, accessibility
+requirements, and agent-visible behavior.
+
+The adapter contract does not require Tailwind, shadcn, Radix, `className`, or
+any particular styling runtime. A component may use a theme provider,
+CSS-in-JS, CSS Modules, React Aria, or ordinary CSS. `className` and `style` are
+optional interoperability hooks, not styling requirements.
+
+See the runnable [Material UI Chat example](https://github.com/BuilderIO/agent-native/tree/main/examples/chat-mui) and [Ant Design Chat example](https://github.com/BuilderIO/agent-native/tree/main/examples/chat-antd) for complete adapters, theme-provider wiring, dark mode, and documented v1 gaps.
+
+## Choose the smallest customization tier
+
+| Tier                    | Use it for                                                                                  | What remains shared                                           |
+| ----------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| **Theme tokens**        | Fast brand alignment across default and not-yet-adapted surfaces                            | Toolkit components, controllers, and behavior                 |
+| **Semantic components** | Company controls such as buttons, fields, pickers, dialogs, menus, and surfaces             | Feature controllers and product contracts                     |
+| **Product slots**       | A company-specific layout for one feature, such as the connection card or chat-history rail | The feature’s controller and actions                          |
+| **Eject**               | Product behavior or structure that cannot be expressed by a supported slot                  | Core runtime contracts; the ejected feature becomes app-owned |
+
+Start with tokens, add semantic components where your system has an equivalent,
+use a product slot for feature-level composition, and eject only the smallest
+unit that still needs ownership.
+
+## Register an adapter
+
+Customer adapters are ordinary npm packages. Import one explicitly in
+`app/design-system.ts`; Agent Native never scans dependencies, auto-detects a
+library, or loads components from JSON.
+
+Keep the build-time theme in a dependency-light module so Vite does not need to
+evaluate the customer React package while loading its config:
+
+```ts filename="app/design-system-theme.ts"
+import { defineTheme } from "@agent-native/toolkit/design-system";
+
+export const acmeTheme = defineTheme({
+  colors: {
+    light: {
+      background: "#ffffff",
+      foreground: "oklch(24% 0.03 255)",
+      primary: "rgb(33 82 255)",
+      "primary-foreground": "white",
+      border: "hsl(218 20% 88%)",
+    },
+    dark: {
+      background: "#11131a",
+      foreground: "#f7f8fb",
+      primary: "oklch(72% 0.17 259)",
+      "primary-foreground": "#07102f",
+    },
+  },
+  radius: "0.625rem",
+  typography: { fontFamily: "Acme Sans, sans-serif" },
+});
+```
+
+```tsx filename="app/design-system.ts"
+import { defineDesignSystem } from "@agent-native/toolkit/design-system";
+import { acmeComponents } from "@acme/agent-native-design-system";
+
+import { acmeTheme } from "@/design-system-theme";
+
+export const designSystem = defineDesignSystem({
+  name: "Acme",
+  theme: acmeTheme,
+  components: acmeComponents,
+});
+```
+
+Wire the definition through the app’s provider seam:
+
+```tsx filename="app/components/ui/toolkit-provider.tsx"
+import { ToolkitProvider } from "@agent-native/toolkit/provider";
+
+import { designSystem } from "@/design-system";
+
+export function AppToolkitProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <ToolkitProvider designSystem={designSystem}>{children}</ToolkitProvider>
+  );
+}
+```
+
+Partial adapters are supported. Any component you omit uses Agent Native’s
+default adapter. If one custom component throws while rendering, a
+per-component error boundary logs the failure and renders the default component
+for that control; the rest of the custom system stays active.
+
+Two complete Chat applications keep this contract honest against real design
+systems: [the Material UI example](https://github.com/BuilderIO/agent-native/tree/main/examples/chat-mui)
+uses Emotion, `ThemeProvider`, and MUI’s overlay stack, while [the Ant Design
+example](https://github.com/BuilderIO/agent-native/tree/main/examples/chat-antd)
+uses `ConfigProvider` and Ant Design’s form and overlay primitives. Their
+`app/design-system.tsx` files are the primary integration references; the Acme
+fixture above remains intentionally small and is used for unit tests.
+
+The older `components={{ Button }}` provider API remains compatible and is
+treated as the lowest-precedence `ActionButton` adapter. If both are supplied,
+`designSystem.components.ActionButton` wins and development builds log a
+warning.
+
+## Build-time theme tokens
+
+`defineTheme` accepts standard CSS colors, including hex, `rgb()`, `hsl()`, and
+OKLCH. The Core Vite plugin validates and normalizes them to Agent Native’s
+existing semantic variables. Dark colors fall back token-by-token to the light
+palette; Agent Native does not derive a dark palette automatically.
+
+Pass the theme to the Vite plugin:
+
+```tsx filename="vite.config.ts"
+import { agentNative } from "@agent-native/core/vite";
+import { defineConfig } from "vite";
+
+import { acmeTheme } from "./app/design-system-theme";
+
+export default defineConfig({
+  plugins: [...agentNative({ designSystemTheme: acmeTheme })],
+});
+```
+
+Import the virtual stylesheet once from the app root so both development and
+React Router production builds include it:
+
+```tsx filename="app/root.tsx"
+import "virtual:agent-native-theme.css";
+```
+
+The plugin generates that virtual theme CSS at build time. Its semantic tokens
+override the scaffold's fallback values without removing fallback-only tokens.
+Version 1 does not choose a theme per request or per organization.
+
+## The 17 semantic contracts
+
+The contract is deliberately about meaning and behavior, not DOM shape or
+visual implementation. Values and open state are controlled wherever product
+state must remain portable.
+
+### Leaf contracts
+
+| Component      | Required contract                     | Important optional semantics                                                     |
+| -------------- | ------------------------------------- | -------------------------------------------------------------------------------- |
+| `ActionButton` | `children` and `onPress` as needed    | `intent`, `emphasis`, `size`, `pending`, icons, disabled state, button type, ref |
+| `IconButton`   | accessible `label`, `icon`            | button semantics matching `ActionButton`                                         |
+| `TextField`    | controlled string `value`, `onChange` | label, description, error, input type/mode, validation, adornments, events, ref  |
+| `TextArea`     | controlled string `value`, `onChange` | label, description, error, rows, validation, events, ref                         |
+| `Spinner`      | progress indicator                    | accessible label and semantic size                                               |
+| `Skeleton`     | non-interactive placeholder           | width, height, line/rectangle/circle shape                                       |
+| `Status`       | `children`                            | neutral/info/success/warning/danger tone, icon, size                             |
+| `Surface`      | `children`                            | semantic element, elevation, padding, interactive press behavior                 |
+| `Avatar`       | accessible `name`                     | image source, fallback, size, presence status, image ref                         |
+
+### Behavior contracts
+
+| Component  | Required contract                                  | Behavior the adapter owns                                                        |
+| ---------- | -------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `Tooltip`  | trigger and content                                | controlled/uncontrolled open state, delay, placement, portal behavior            |
+| `Menu`     | trigger, items/sections, `onAction`                | keyboard navigation, nested items, selection, dismissal, portal behavior         |
+| `Popover`  | trigger and children                               | controlled/uncontrolled open state, dismissal, focus, modality, portal behavior  |
+| `Dialog`   | controlled `open`, `onOpenChange`, title, children | dialog semantics, dismissal, initial/restore focus, portal and stacking behavior |
+| `Picker`   | `mode`, options, controlled `value`, `onChange`    | select/combobox semantics, search/open state, validation, loading/empty state    |
+| `Checkbox` | controlled `checked`, `onChange`                   | checkbox semantics, indeterminate/required/invalid state                         |
+| `Switch`   | controlled `checked`, `onChange`                   | switch semantics and disabled state                                              |
+| `Tabs`     | items, controlled `value`, `onChange`              | tab semantics, orientation, automatic/manual activation                          |
+
+`intent` is `primary`, `neutral`, or `danger`; `emphasis` is `solid`,
+`outline`, or `ghost`; and size is `compact`, `default`, or `large`. These
+values describe purpose, not a class or variant name from the default UI.
+
+The default adapter gives these visual props observable behavior as well as
+semantic attributes: button, spinner, status, skeleton, avatar, and dialog
+sizes select concrete variants; skeleton shape and avatar presence status
+change their presentation; menu selection and `closeOnAction` affect behavior.
+Custom adapters remain responsible for mapping the same meanings to their own
+visual vocabulary.
+
+`Picker` covers select and combobox behavior only. Date picking is not part of
+the version 1 semantic contract.
+
+### What the Chat examples actually render
+
+The runnable MUI and Ant Design Chat examples register all 17 components and
+render 16/17 through those adapters in the normalized shared surfaces:
+
+| Adapter component                                               | Reachable proving surface                                                                                                                          |
+| --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ActionButton`, `IconButton`                                    | Chat-history rail, settings actions, sharing actions                                                                                               |
+| `TextField`, `TextArea`, `Picker`, `Checkbox`, `Switch`, `Tabs` | Settings and sharing controls                                                                                                                      |
+| `Dialog`, `Avatar`, `Status`                                    | Core Share dialog on each example's shipped `/design-system-proof` route                                                                           |
+| `Tooltip`, `Popover`, `Spinner`, `Skeleton`                     | Agent-panel, runs-tray, and sidebar chrome                                                                                                         |
+| `Surface`                                                       | Builder connection card                                                                                                                            |
+| `Menu`                                                          | Explicit gap: the agent-panel header menu embeds the live `RunsTrayMenuItem` compound submenu, which the v1 data-only menu contract cannot express |
+
+The `Menu` row is intentionally called out rather than counted as bridged.
+The everyday Chat share button remains the legacy popover; the proof route makes
+the complete Core `ShareDialog` reachable without misrepresenting that popover.
+The assistant-ui composer/message renderer, cmdk command-menu internals, and
+Tiptap editor remain v1 non-goals. Their surrounding chrome is tokenized or
+bridged where the semantic contract fits. If a product needs arbitrary nested
+menu content, use a product slot or propose a contract extension instead of
+silently mixing the default menu into a custom adapter.
+
+The framework-owned sign-in shell is outside both the semantic bridge and the
+build-time token tier in v1; the authenticated settings, sharing, history rail,
+and agent-panel surfaces are the design-system proving surfaces. The main Chat
+canvas remains tokens-only because the assistant-ui renderer is a documented
+v1 non-goal. In the runnable examples, dark mode is exercised from the
+`Cmd/Ctrl+K` Appearance command rather than a second settings section.
+
+## Overlays, portals, and focus
+
+Behavior components may use your design system’s overlay and focus
+implementation wholesale. They do not need to wrap Radix. They must honor the
+semantic contract, including controlled state, accessible roles, and the
+provided `portalContainer`, `initialFocusRef`, and `restoreFocusRef` seams.
+
+This matters when a native design-system dialog opens from a Radix-hosted
+Toolkit surface. The adapter owns its overlay stack, while the seams let both
+systems agree on the portal layer, z-index order, initial focus, and focus
+restoration. Test nested and adjacent overlays in the real app, not only in an
+isolated component explorer.
+
+## Headless feature controllers and product slots
+
+Semantic components are the shared vocabulary. Feature controllers are the
+behavior boundary. A controller owns state transitions, actions, tracking, and
+the view model; both the default view and a product slot consume that same
+controller.
+
+```tsx
+<BuilderConnectCard
+  className="connection-card"
+  render={({ viewModel, className }) => (
+    <AcmeConnectionPanel
+      className={className}
+      title={viewModel.title}
+      status={viewModel.status}
+      pending={viewModel.action?.pending ?? false}
+      onConnect={viewModel.action?.onPress}
+    />
+  )}
+/>
+```
+
+This is feature-level headless UI, not a second set of low-level hooks for every
+widget. `BuilderConnectCard` and `ChatHistoryRail` are the first proving slices;
+settings and sharing follow the same controller/default-view/custom-view
+invariant.
+
+`ChatHistoryRail` keeps one deliberately opaque `renderRail` slot in v1. The
+slot replaces the rail view wholesale and receives the shared controller plus
+list props; discrete header, footer, and row slots are deferred until a second
+product needs them. This bounds the API while keeping history state and actions
+on the shared controller.
+
+If a slot cannot express the required product change, inspect and eject the
+smallest published unit:
+
+```bash
+agent-native eject --list
+agent-native eject inspect toolkit/design-system
+agent-native eject toolkit/design-system --app my-app --apply
+```
+
+Ejection transfers ownership; it does not fork Core auth, actions, persistence,
+access checks, chat transport, or agent execution.
+
+## Run the conformance kit
+
+Export a complete component map from the customer package and run the shipped
+test kit in a browser-like test environment:
+
+```tsx filename="design-system.conformance.spec.tsx"
+import { describe, it } from "vitest";
+import { assertDesignSystemConformance } from "@agent-native/toolkit/conformance";
+import { DESIGN_SYSTEM_CONTRACT_VERSION } from "@agent-native/toolkit/design-system";
+import { acmeComponents } from "@acme/agent-native-design-system";
+
+describe("Acme Agent Native adapter", () => {
+  it("conforms", async () => {
+    await assertDesignSystemConformance({
+      adapterName: "Acme",
+      components: acmeComponents,
+      contractVersion: DESIGN_SYSTEM_CONTRACT_VERSION,
+    });
+  });
+});
+```
+
+The suite checks all 17 exports, controlled values and open state, accessible
+roles, keyboard interaction, selection, portal targeting, z-index
+interoperability, initial focus, and focus restoration. Run it in the adapter
+package’s CI and retain a small app-level overlay test for provider-specific
+composition.
+
+Contract evolution follows semantic versioning:
+
+- New components and optional props are a compatible minor change.
+- New required props, removed components/props, or behavioral contract changes
+  require a new contract major.
+- The conformance kit fails when the adapter’s contract major and Toolkit’s
+  contract major differ.
+
+## Adapter recipes
+
+### MUI-style theme-provider systems
+
+The [Chat + Material UI example](https://github.com/BuilderIO/agent-native/tree/main/examples/chat-mui) is the primary worked reference. Its single
+`app/design-system.tsx` module exports the semantic adapter, the MUI light and
+dark `createTheme` values, and the `defineTheme` token source. The app's
+`AppToolkitProvider` keeps the MUI `ThemeProvider` above shared Toolkit
+surfaces, while `vite.config.ts` imports that same `theme` value for build-time
+CSS generation. This keeps Emotion styles, MUI portals, and Agent Native
+tokens on one source of truth.
+
+Keep the company theme provider above `AppToolkitProvider`, and adapt semantic
+props at the package boundary. Map `intent`, `emphasis`, and `size` to your
+system’s own vocabulary inside the adapter—not in Agent Native feature code.
+For overlays, forward `portalContainer` to the design system’s container or
+portal prop and implement `initialFocusRef`/`restoreFocusRef` using its focus
+manager.
+
+```tsx
+export const ActionButton: DesignSystemComponents["ActionButton"] = ({
+  intent = "neutral",
+  emphasis = "solid",
+  pending,
+  onPress,
+  children,
+  ...props
+}) => (
+  <CompanyButton
+    {...props}
+    color={intent === "danger" ? "error" : intent}
+    variant={emphasis === "solid" ? "contained" : emphasis}
+    loading={pending}
+    onClick={onPress}
+  >
+    {children}
+  </CompanyButton>
+);
+```
+
+Do not copy a feature’s theme provider into each adapter component. Install it
+once at the app boundary so portals and overlays inherit the same context.
+
+The [Chat MUI adapter](https://github.com/BuilderIO/agent-native/blob/main/examples/chat-mui/app/design-system.tsx)
+is the worked example: it exports one `defineTheme` value, imports that value
+into `defineDesignSystem`, and imports the same module from `vite.config.ts`.
+That single source of truth keeps the MUI light/dark provider tokens and the
+build-time semantic CSS tokens aligned without runtime theme generation.
+
+### React Aria-based systems
+
+Use React Aria components or hooks to implement the semantics directly. Preserve
+controlled `value`/`open` props and forward their change callbacks rather than
+creating a second state store. For behavior contracts, use your overlay provider
+and focus scope, set its portal root from `portalContainer`, and connect
+initial/restore refs to the focus-management API. The conformance suite is the
+minimum behavior check; your design system remains responsible for its full
+keyboard and screen-reader test matrix.
+
+```tsx
+export const Checkbox: DesignSystemComponents["Checkbox"] = ({
+  checked,
+  onChange,
+  label,
+  ...props
+}) => (
+  <AriaCheckbox {...props} isSelected={checked} onChange={onChange}>
+    {label}
+  </AriaCheckbox>
+);
+```
+
+### CSS Modules and plain React
+
+The adapter can be ordinary React and CSS Modules. Ignore `className` entirely
+when it would bypass your component’s style contract; it is optional. Keep DOM
+roles, accessible names, keyboard behavior, and controlled state explicit.
+
+```tsx
+import styles from "./action-button.module.css";
+
+export const ActionButton: DesignSystemComponents["ActionButton"] = ({
+  intent = "neutral",
+  emphasis = "solid",
+  pending,
+  disabled,
+  onPress,
+  children,
+  elementRef,
+}) => (
+  <button
+    ref={elementRef}
+    className={styles[`${intent}-${emphasis}`]}
+    disabled={disabled || pending}
+    aria-busy={pending || undefined}
+    onClick={onPress}
+  >
+    {children}
+  </button>
+);
+```
+
+## Version 1 boundaries
+
+The semantic bridge does not replace every third-party UI ecosystem in version
+
+1. These surfaces receive theme tokens and feature slots where available, but
+   their internal widgets are not semantic-adapter contracts yet:
+
+- `@assistant-ui/react` chat and composer internals
+- Tiptap editor kits
+- `cmdk`, `vaul`, Recharts, and `react-day-picker`
+- date-picker components (the `Picker` contract is select/combobox only)
+- Dispatch’s independent primitive fork
+- Pinpoint’s Solid.js and Shadow DOM UI
+
+These boundaries are explicit so an adapter package can make accurate support
+claims. Propose a new semantic component only when the same meaning and behavior
+is useful across more than one feature; use product slots or eject for
+one-feature differences.
+
+## What’s next
+
+- [**Toolkit UI Primitives**](/docs/toolkit-ui) — local adapters, provider
+  wiring, and shared primitive imports.
+- [**Agent-Native Toolkit**](/docs/agent-native-toolkit) — reusable feature
+  ownership and package boundaries.
+- [**Settings Kit**](/docs/toolkit-settings) and [**Sharing Kit**](/docs/toolkit-sharing)
+  — shared feature controllers that preserve app actions and access contracts.

package/corpus/core/docs/content/toolkit-ui.mdx

@@ -8,6 +8,14 @@ description: "How to use @agent-native/toolkit UI primitives, the local app-adap
 Toolkit UI primitives live under `@agent-native/toolkit/ui/*`. They are the
 shared shadcn-style building blocks used by templates and reusable kits.
 
+If your company already has a React component library, register it through the
+semantic design-system bridge instead of replacing feature code. The bridge is
+styling-runtime agnostic, supports partial adapters with per-control fallback,
+and lets shared Toolkit and Core-owned feature views consume the same company
+components. See [Custom Design Systems](/docs/custom-design-system) for the 17
+semantic contracts, build-time theme tokens, conformance tests, and adapter
+recipes.
+
 <WireframeBlock id="doc-block-toolkit-ui-primitives">
   <Screen
     surface="desktop"
@@ -105,6 +113,14 @@ keep importing `@agent-native/toolkit/ui/*` without adopting local adapters.
 Core also keeps old imports working through its own re-export shims for code
 written before Toolkit adapters existed.
 
+For new customization, prefer `designSystem={designSystem}` over the legacy
+`components={{ Button }}` override. The design-system adapter uses semantic
+props such as intent, emphasis, pending state, controlled values, and controlled
+open state rather than shadcn variant names. When both APIs provide the button,
+`designSystem.components.ActionButton` wins. A missing or failed custom control
+falls back to Toolkit’s default adapter without disabling the rest of the
+registered system.
+
 ## Shell hooks {#shell-hooks}
 
 Toolkit includes small shell helpers and hooks that are useful across apps:

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.117.1",
+  "version": "0.118.0",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -162,6 +162,7 @@
     },
     "./application-state": "./dist/application-state/index.js",
     "./settings": "./dist/settings/index.js",
+    "./user-profile": "./dist/user-profile/index.js",
     "./feature-flags": "./dist/feature-flags/index.js",
     "./feature-flags/registry": "./dist/feature-flags/registry.js",
     "./feature-flags/actions/get-feature-flags": "./dist/feature-flags/actions/get-feature-flags.js",

package/corpus/core/src/a2a/types.ts

@@ -36,6 +36,7 @@ export interface Message {
 export type TaskState =
   | "submitted"
   | "working"
+  | "processing"
   | "completed"
   | "failed"
   | "canceled"

package/corpus/core/src/agent/types.ts

@@ -290,7 +290,7 @@ export type AgentChatEvent =
        */
       type: "agent_call_progress";
       agent: string;
-      /** Remote A2A task state for this poll, e.g. "working" | "submitted". */
+      /** Remote A2A task state for this poll, e.g. "working" | "processing". */
       state: string;
       /** Elapsed wall-clock seconds since the cross-app call began. */
       elapsedSeconds: number;

package/corpus/core/src/cli/context-xray-local.ts

@@ -1933,7 +1933,7 @@ function renderHtml(sessions, args) {
   return "<!doctype html><html><head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width,initial-scale=1\"><title>Context X-Ray</title><style>" +
     "@import url(\"https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap\");" +
     ":root{--background:0 0% 100%;--foreground:220 10% 10%;--card:0 0% 100%;--muted:220 10% 95%;--muted-foreground:220 5% 45%;--accent:220 10% 92%;--border:220 10% 90%;--ring:220 10% 55%;--destructive:0 84% 60%;--radius:.5rem;--shadow:0 1px 2px rgba(16,24,40,.06);}" +
-    "@media(prefers-color-scheme:dark){:root{--background:220 10% 7%;--foreground:220 8% 92%;--card:220 9% 9%;--muted:220 8% 15%;--muted-foreground:220 6% 64%;--accent:220 8% 17%;--border:220 8% 18%;--ring:220 8% 54%;--destructive:0 72% 51%;--shadow:none;}}" +
+    "@media(prefers-color-scheme:dark){:root{--background:220 10% 7%;--foreground:220 8% 92%;--card:220 9% 9%;--muted:220 8% 15%;--muted-foreground:220 6% 64%;--accent:220 8% 17%;--border:220 8% 18%;--ring:220 8% 54%;--destructive:0 84% 60%;--shadow:none;}}" +
     "*{box-sizing:border-box}html{background:hsl(var(--background))}body{margin:0;background:hsl(var(--background));color:hsl(var(--foreground));font-family:Inter,ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,\"Segoe UI\",sans-serif;font-feature-settings:\"cv02\",\"cv03\",\"cv04\",\"cv11\";line-height:1.45}button{font:inherit;color:inherit}main{max-width:1180px;margin:0 auto;padding:20px 18px 44px}.topbar{border-bottom:1px solid hsl(var(--border));background:hsl(var(--background));position:sticky;top:0;z-index:10}.topbar-inner{max-width:1180px;margin:0 auto;padding:14px 18px;display:flex;align-items:center;justify-content:space-between;gap:16px}.title-row{display:flex;align-items:center;gap:9px}.logo-dot{width:10px;height:10px;border-radius:999px;background:#38bdf8;box-shadow:0 0 0 4px rgba(56,189,248,.12)}h1{font-size:20px;line-height:1.1;margin:0;font-weight:650;letter-spacing:0}h2{font-size:15px;line-height:1.2;margin:0;font-weight:650}h3{font-size:14px;line-height:1.3;margin:0;font-weight:600}p{margin:0}.muted,.eyebrow,.meta,.empty{color:hsl(var(--muted-foreground))}.eyebrow{text-transform:uppercase;letter-spacing:.08em;font-size:11px;font-weight:650}.meta{font-size:12px}.tabs{display:inline-flex;align-items:center;gap:2px;border:1px solid hsl(var(--border));background:hsl(var(--muted)/.35);border-radius:8px;padding:2px}.tab{border:0;background:transparent;border-radius:6px;padding:6px 10px;font-size:12px;line-height:1.1;cursor:pointer}.tab:hover{background:hsl(var(--accent)/.5)}.tab.active{background:hsl(var(--background));box-shadow:var(--shadow)}.stats{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:10px;margin:18px 0}.card{background:hsl(var(--card));border:1px solid hsl(var(--border));border-radius:8px;padding:14px;box-shadow:var(--shadow)}.stat-value{display:block;font-size:28px;line-height:1.1;font-weight:700;margin-top:6px}.panel{display:none}.panel.active{display:block}.grid{display:grid;grid-template-columns:minmax(0,1.35fr) minmax(280px,.8fr);gap:14px;align-items:start}.grid.equal{grid-template-columns:repeat(2,minmax(0,1fr))}.section-head{display:flex;align-items:flex-start;justify-content:space-between;gap:10px;margin-bottom:12px}.bar{display:flex;overflow:hidden;height:10px;border-radius:999px;background:hsl(var(--muted));margin:10px 0 12px}.bar span{display:block;min-width:2px}.table{width:100%;border-collapse:collapse;font-size:12px}.table th{text-align:left;color:hsl(var(--muted-foreground));font-weight:600;border-bottom:1px solid hsl(var(--border));padding:7px 8px}.table td{border-bottom:1px solid hsl(var(--border));padding:8px;vertical-align:top}.table th:last-child,.table td:last-child{text-align:right}.row-button{width:100%;display:grid;grid-template-columns:minmax(0,1fr) 74px 70px;gap:10px;align-items:center;text-align:left;border:1px solid transparent;background:transparent;border-radius:6px;padding:8px;cursor:pointer}.row-button:hover,.row-button.active{border-color:hsl(var(--border));background:hsl(var(--accent)/.35)}.row-title{font-size:13px;font-weight:600;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.row-meta{font-size:12px;color:hsl(var(--muted-foreground));text-align:right}.badge-list{display:flex;flex-wrap:wrap;gap:6px}.badge{display:inline-flex;align-items:center;gap:5px;border:1px solid hsl(var(--border));border-radius:999px;padding:3px 7px;font-size:11px;background:hsl(var(--background));max-width:100%}.badge .dot{width:7px;height:7px;border-radius:999px;flex:0 0 auto}.tips{margin:0;padding-left:20px}.tips li{margin:0 0 8px}.detail{min-height:228px}.detail-list{display:grid;gap:8px;margin-top:10px}.sample{border:1px solid hsl(var(--border));border-radius:8px;padding:10px;background:hsl(var(--muted)/.22)}.sample-top{display:flex;justify-content:space-between;gap:10px;margin-bottom:5px;font-size:11px;color:hsl(var(--muted-foreground))}.sample p{font-size:12px;color:hsl(var(--foreground));overflow-wrap:anywhere}.session-card{border:1px solid hsl(var(--border));border-radius:8px;background:hsl(var(--card));margin-bottom:10px;overflow:hidden}.session-card summary{list-style:none;display:flex;justify-content:space-between;gap:14px;cursor:pointer;padding:13px 14px}.session-card summary::-webkit-details-marker{display:none}.session-body{border-top:1px solid hsl(var(--border));padding:12px 14px}.session-title{font-size:13px;font-weight:650;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.session-path{font-size:12px;color:hsl(var(--muted-foreground));margin-top:3px;overflow-wrap:anywhere}.token-big{font-size:20px;font-weight:700;white-space:nowrap}.mini-label{margin:10px 0 6px;font-size:11px;text-transform:uppercase;letter-spacing:.08em;font-weight:650;color:hsl(var(--muted-foreground))}.footer{margin-top:20px;color:hsl(var(--muted-foreground));font-size:12px}.hidden{display:none!important}@media(max-width:840px){.topbar-inner{align-items:flex-start;flex-direction:column}.stats,.grid,.grid.equal{grid-template-columns:1fr}.tabs{width:100%;overflow:auto}.tab{white-space:nowrap}.row-button{grid-template-columns:minmax(0,1fr) 64px 58px}.session-card summary{align-items:flex-start;flex-direction:column}}" +
     "</style></head><body><header class=\"topbar\"><div class=\"topbar-inner\"><div><div class=\"title-row\"><span class=\"logo-dot\"></span><h1>Context X-Ray</h1></div><p class=\"meta\">Generated " + escapeHtml(report.generatedLabel) + " · mode=" + escapeHtml(report.mode) + " · source=" + escapeHtml(report.source) + " · since=" + escapeHtml(report.since) + "</p></div><nav class=\"tabs\" aria-label=\"Report views\"><button class=\"tab active\" data-tab=\"overview\">Overview</button><button class=\"tab\" data-tab=\"tools\">Tool Calls</button><button class=\"tab\" data-tab=\"mcp\">MCP</button><button class=\"tab\" data-tab=\"metadata\">Metadata</button><button class=\"tab\" data-tab=\"sessions\">Sessions</button></nav></div></header><main><section class=\"stats\" id=\"stats\"></section><section class=\"panel active\" id=\"panel-overview\"></section><section class=\"panel\" id=\"panel-tools\"></section><section class=\"panel\" id=\"panel-mcp\"></section><section class=\"panel\" id=\"panel-metadata\"></section><section class=\"panel\" id=\"panel-sessions\"></section><p class=\"footer\">Reads local transcript and MCP config files only. No transcript content is uploaded.</p></main><script type=\"application/json\" id=\"xray-data\">" + jsonScript(report) + "</script><script>" +
     "(function(){var report=JSON.parse(document.getElementById('xray-data').textContent);var cats=['user','assistant','tool_call','tool_output','reasoning','instructions','attachment','metadata','other'];var labels={user:'User asks',assistant:'Assistant text',tool_call:'Tool calls',tool_output:'Tool output',reasoning:'Reasoning',instructions:'Instructions/context',attachment:'Attachments',metadata:'Metadata',other:'Other'};var colors={user:'#8ba8ff',assistant:'#55b982',tool_call:'#f0a85b',tool_output:'#e06b73',reasoning:'#a77be8',instructions:'#6ac3d5',attachment:'#d6a85a',metadata:'#9aa3ad',other:'#c3c8ce'};function esc(v){return String(v||'').replace(/[&<>\"']/g,function(ch){return {'&':'&amp;','<':'&lt;','>':'&gt;','\"':'&quot;',\"'\":'&#39;'}[ch];});}function fmt(n){n=Number(n)||0;if(n>=1000000)return(n/1000000).toFixed(1)+'m';if(n>=1000)return(n/1000).toFixed(1)+'k';return String(n);}function tok(chars){chars=Number(chars)||0;return chars>0?Math.max(1,Math.ceil(chars/4)):0;}function pc(part,total){return total>0?Math.max(0,Math.min(100,(part/total)*100)):0;}function totalCounter(counter){return Object.keys(counter||{}).reduce(function(sum,key){return sum+(Number(counter[key])||0);},0);}function bar(counter){var total=totalCounter(counter);if(!total)return'<div class=\"bar\"></div>';return'<div class=\"bar\">'+cats.map(function(cat){var value=counter[cat]||0;if(!value)return'';return'<span title=\"'+esc(labels[cat])+'\" style=\"width:'+Math.max(1,pc(value,total)).toFixed(2)+'%;background:'+colors[cat]+'\"></span>';}).join('')+'</div>';}function metric(label,value){return'<article class=\"card\"><div class=\"eyebrow\">'+esc(label)+'</div><span class=\"stat-value\">'+esc(value)+'</span></article>';}function tableRows(entries,kind){if(!entries||!entries.length)return'<tr><td>None detected</td><td></td></tr>';return entries.map(function(entry){var value=entry[1];var shown=kind==='chars'?fmt(tok(value)):(kind==='tokens'?fmt(value):String(value));return'<tr><td>'+esc(entry[0])+'</td><td>'+esc(shown)+'</td></tr>';}).join('');}function toolToken(name){var found=(report.toolTokens||[]).filter(function(entry){return entry[0]===name;})[0];return found?found[1]:0;}function renderStats(){var counts=report.sourceCounts||{};document.getElementById('stats').innerHTML=metric('Sessions',report.sessionCount)+metric('Observed/estimated tokens',fmt(report.totalTokens))+metric('Codex',counts.codex||0)+metric('Claude',counts.claude||0);}function renderOverview(){var categoryTotal=totalCounter(report.categories);var categoryRows=cats.map(function(cat){var chars=(report.categories||{})[cat]||0;if(!chars)return'';return'<tr><td><span class=\"badge\"><span class=\"dot\" style=\"background:'+colors[cat]+'\"></span>'+esc(labels[cat])+'</span></td><td>'+fmt(tok(chars))+'</td><td>'+pc(chars,categoryTotal).toFixed(0)+'%</td></tr>';}).join('');document.getElementById('panel-overview').innerHTML='<div class=\"grid\"><section class=\"card\"><div class=\"section-head\"><div><h2>Where The Context Is Going</h2><p class=\"meta\">Approximate contribution by transcript bucket.</p></div></div>'+bar(report.categories)+'<table class=\"table\"><tbody>'+categoryRows+'</tbody></table></section><section class=\"card\"><div class=\"section-head\"><div><h2>Warnings And Optimizations</h2><p class=\"meta\">Promptable changes you control.</p></div></div><ol class=\"tips\">'+(report.recommendations||[]).map(function(tip){return'<li>'+esc(tip)+'</li>';}).join('')+'</ol></section></div><div class=\"grid equal\" style=\"margin-top:14px\"><section class=\"card\"><h2>Top Paths</h2><table class=\"table\"><tbody>'+tableRows(report.paths,'count')+'</tbody></table></section><section class=\"card\"><h2>Metadata Types</h2><table class=\"table\"><tbody>'+tableRows(report.metadata,'chars')+'</tbody></table></section></div>';}function renderTools(){var rows=(report.tools||[]).map(function(entry,index){var name=entry[0];var count=entry[1];return'<button class=\"row-button'+(index===0?' active':'')+'\" data-tool=\"'+esc(name)+'\"><span><span class=\"row-title\">'+esc(name)+'</span><span class=\"meta\">Click to inspect sampled calls</span></span><span class=\"row-meta\">x'+count+'</span><span class=\"row-meta\">'+fmt(toolToken(name))+' tok</span></button>';}).join('')||'<div class=\"empty\">No tool calls detected in these sessions.</div>';document.getElementById('panel-tools').innerHTML='<div class=\"grid\"><section class=\"card\"><div class=\"section-head\"><div><h2>Tool Calls</h2><p class=\"meta\">Calls are clickable; samples are capped so the report stays light.</p></div></div><div>'+rows+'</div></section><aside class=\"card detail\" id=\"tool-detail\"></aside></div>';Array.prototype.forEach.call(document.querySelectorAll('[data-tool]'),function(btn){btn.addEventListener('click',function(){Array.prototype.forEach.call(document.querySelectorAll('[data-tool]'),function(item){item.classList.remove('active');});btn.classList.add('active');renderToolDetail(btn.getAttribute('data-tool'));});});if((report.tools||[]).length)renderToolDetail(report.tools[0][0]);else document.getElementById('tool-detail').innerHTML='<h2>Tool Detail</h2><p class=\"empty\">Nothing to inspect yet.</p>';}function renderToolDetail(name){var events=(report.toolEvents||[]).filter(function(event){return event.tool===name;}).slice(0,30);document.getElementById('tool-detail').innerHTML='<div class=\"section-head\"><div><h2>'+esc(name)+'</h2><p class=\"meta\">'+events.length+' sampled call'+(events.length===1?'':'s')+'</p></div></div><div class=\"detail-list\">'+(events.map(function(event){return'<article class=\"sample\"><div class=\"sample-top\"><span>'+esc(event.source)+' · '+esc(event.sessionTitle||event.sessionId)+'</span><span>'+fmt(event.tokens||0)+' tok</span></div><p>'+esc(event.preview||'No preview captured.')+'</p></article>';}).join('')||'<p class=\"empty\">No sampled call payloads for this tool.</p>')+'</div>';}function renderMcp(){var servers=report.mcpServers||[];var usage=report.mcpUsage||[];var configured=servers.map(function(server){return'<button class=\"row-button\" data-mcp=\"'+esc(server.name)+'\"><span><span class=\"row-title\">'+esc(server.name)+'</span><span class=\"meta\">'+esc(server.source)+' · '+esc(server.target)+'</span></span><span class=\"row-meta\">config</span><span class=\"row-meta\"></span></button>';}).join('')||'<div class=\"empty\">No MCP server config found in the common local config files.</div>';var detected=usage.map(function(entry,index){return'<button class=\"row-button'+(!servers.length&&index===0?' active':'')+'\" data-mcp=\"'+esc(entry[0])+'\"><span><span class=\"row-title\">'+esc(entry[0])+'</span><span class=\"meta\">Detected from mcp__server__tool style names</span></span><span class=\"row-meta\">x'+entry[1]+'</span><span class=\"row-meta\"></span></button>';}).join('')||'<div class=\"empty\">No MCP-prefixed tool calls detected in the selected sessions.</div>';document.getElementById('panel-mcp').innerHTML='<div class=\"grid\"><section class=\"card\"><div class=\"section-head\"><div><h2>MCP Servers</h2><p class=\"meta\">Configured locally plus inferred calls from transcripts.</p></div></div><div class=\"mini-label\">Configured</div>'+configured+'<div class=\"mini-label\">Detected usage</div>'+detected+'</section><aside class=\"card detail\" id=\"mcp-detail\"></aside></div>';Array.prototype.forEach.call(document.querySelectorAll('[data-mcp]'),function(btn){btn.addEventListener('click',function(){Array.prototype.forEach.call(document.querySelectorAll('[data-mcp]'),function(item){item.classList.remove('active');});btn.classList.add('active');renderMcpDetail(btn.getAttribute('data-mcp'));});});if(usage.length)renderMcpDetail(usage[0][0]);else if(servers.length)renderMcpDetail(servers[0].name);else document.getElementById('mcp-detail').innerHTML='<h2>MCP Detail</h2><p class=\"empty\">Install or run sessions with MCP tools to see usage here.</p>';}function renderMcpDetail(name){var server=(report.mcpServers||[]).filter(function(item){return item.name===name;})[0];var tools=(report.mcpTools||[]).filter(function(entry){return entry[0].indexOf(name+' / ')===0;});var events=(report.toolEvents||[]).filter(function(event){return event.mcpServer===name;}).slice(0,25);document.getElementById('mcp-detail').innerHTML='<div class=\"section-head\"><div><h2>'+esc(name)+'</h2><p class=\"meta\">'+(server?esc(server.source+' · '+server.target):'Detected from tool call names')+'</p></div></div><div class=\"mini-label\">Tools</div><table class=\"table\"><tbody>'+tableRows(tools,'count')+'</tbody></table><div class=\"mini-label\">Sample calls</div><div class=\"detail-list\">'+(events.map(function(event){return'<article class=\"sample\"><div class=\"sample-top\"><span>'+esc(event.mcpTool||event.tool)+'</span><span>'+fmt(event.tokens||0)+' tok</span></div><p>'+esc(event.preview||'No preview captured.')+'</p></article>';}).join('')||'<p class=\"empty\">No sampled MCP calls for this server in the selected sessions.</p>')+'</div>';}function renderMetadata(){var rows=(report.metadata||[]).map(function(entry,index){return'<button class=\"row-button'+(index===0?' active':'')+'\" data-meta=\"'+esc(entry[0])+'\"><span><span class=\"row-title\">'+esc(entry[0])+'</span><span class=\"meta\">Click to inspect sampled records</span></span><span class=\"row-meta\">'+fmt(tok(entry[1]))+' tok</span><span class=\"row-meta\">'+fmt(entry[1])+' ch</span></button>';}).join('')||'<div class=\"empty\">No metadata-heavy records detected.</div>';document.getElementById('panel-metadata').innerHTML='<div class=\"grid\"><section class=\"card\"><div class=\"section-head\"><div><h2>Metadata</h2><p class=\"meta\">Breakdown by transcript record type.</p></div></div>'+rows+'</section><aside class=\"card detail\" id=\"metadata-detail\"></aside></div>';Array.prototype.forEach.call(document.querySelectorAll('[data-meta]'),function(btn){btn.addEventListener('click',function(){Array.prototype.forEach.call(document.querySelectorAll('[data-meta]'),function(item){item.classList.remove('active');});btn.classList.add('active');renderMetadataDetail(btn.getAttribute('data-meta'));});});if((report.metadata||[]).length)renderMetadataDetail(report.metadata[0][0]);else document.getElementById('metadata-detail').innerHTML='<h2>Metadata Detail</h2><p class=\"empty\">Nothing to inspect yet.</p>';}function renderMetadataDetail(type){var events=(report.metadataEvents||[]).filter(function(event){return event.type===type;}).slice(0,30);document.getElementById('metadata-detail').innerHTML='<div class=\"section-head\"><div><h2>'+esc(type)+'</h2><p class=\"meta\">'+events.length+' sampled record'+(events.length===1?'':'s')+'</p></div></div><div class=\"detail-list\">'+(events.map(function(event){return'<article class=\"sample\"><div class=\"sample-top\"><span>'+esc(event.source)+' · '+esc(event.sessionTitle||event.sessionId)+'</span><span>'+fmt(event.tokens||0)+' tok</span></div><p>'+esc(event.preview||'No preview captured.')+'</p></article>';}).join('')||'<p class=\"empty\">No sampled records for this metadata type.</p>')+'</div>';}function renderSessions(){document.getElementById('panel-sessions').innerHTML=(report.sessions||[]).map(function(session,index){var catRows=Object.keys(session.categories||{}).sort(function(a,b){return session.categories[b]-session.categories[a];}).map(function(cat){var chars=session.categories[cat];return'<tr><td>'+esc(labels[cat]||cat)+'</td><td>'+fmt(tok(chars))+'</td><td>'+pc(chars,session.totalChars||0).toFixed(0)+'%</td></tr>';}).join('');var tools=(session.tools?Object.keys(session.tools):[]).sort(function(a,b){return session.tools[b]-session.tools[a];}).slice(0,8).map(function(name){return'<span class=\"badge\">'+esc(name)+' x'+session.tools[name]+'</span>';}).join('')||'<span class=\"empty\">none detected</span>';var paths=(session.paths?Object.keys(session.paths):[]).sort(function(a,b){return session.paths[b]-session.paths[a];}).slice(0,8).map(function(name){return'<span class=\"badge\">'+esc(name)+' x'+session.paths[name]+'</span>';}).join('')||'<span class=\"empty\">none detected</span>';return'<details class=\"session-card\"'+(index===0?' open':'')+'><summary><span><span class=\"eyebrow\">'+esc(session.source)+' · '+esc(session.updatedAt||'unknown time')+'</span><span class=\"session-title\">'+esc(session.title||session.sessionId)+'</span><span class=\"session-path\">'+esc(session.cwd||session.path)+'</span></span><span class=\"token-big\">'+fmt(session.tokens)+'</span></summary><div class=\"session-body\">'+bar(session.categories)+'<div class=\"grid equal\"><div><div class=\"mini-label\">Buckets</div><table class=\"table\"><tbody>'+catRows+'</tbody></table></div><div><div class=\"mini-label\">Frequent tools</div><div class=\"badge-list\">'+tools+'</div><div class=\"mini-label\">Repeated paths</div><div class=\"badge-list\">'+paths+'</div></div></div></div></details>';}).join('')||'<section class=\"card\"><p class=\"empty\">No matching sessions found.</p></section>';}function activate(name){Array.prototype.forEach.call(document.querySelectorAll('.tab'),function(tab){tab.classList.toggle('active',tab.getAttribute('data-tab')===name);});Array.prototype.forEach.call(document.querySelectorAll('.panel'),function(panel){panel.classList.toggle('active',panel.id==='panel-'+name);});if(location.hash!=='#'+name)history.replaceState(null,'','#'+name);}Array.prototype.forEach.call(document.querySelectorAll('.tab'),function(tab){tab.addEventListener('click',function(){activate(tab.getAttribute('data-tab'));});});renderStats();renderOverview();renderTools();renderMcp();renderMetadata();renderSessions();var initial=(location.hash||'#overview').slice(1);if(document.getElementById('panel-'+initial))activate(initial);})();" +