Chat-first workbench
Contract
The chat remains the primary surface. Workspace apps are a bounded discovery
rail, not a second navigation system. An app pane is opened from an explicit
app selection or a completed open_app action and carries only an app id plus a
validated app-relative path or view.
Client behavior
- The preference is opt-in and local to the client. Keep the existing app-first
shell unchanged when it is disabled.
- Electron uses the shared Code Agents rail and AppWebview.
- Dispatch uses list-workspace-apps and create_embed_session; never iframe a
raw workspace URL. Resolve an absolute open_app URL against the registered
app first, then pass the resulting app-relative path.
- Mobile uses the existing app registry and secure AppWebView routes instead of
accepting arbitrary URLs or adding a second navigator.
- Show no nested app sidebar or browser chrome in a contextual pane.
- Without
sections, the app shelf is capped at six visible entries and
supports pinning and drag-reordering (Desktop). Both are presentation
preferences; the agent-visible target remains the registered app id and
route.
- With
sections (Dispatch), the host owns grouping and order and the rail
shows every row it is given, expanded and collapsed, with an optional
emptyLabel and no drag or move controls. Dispatch's sidebar passes one
section: Pinned apps (pin order), or with no pins three suggested apps
(workspace apps A to Z, else Agent-Native.com hosted apps), plus the open app; All apps holds
the rest. Tier with Dispatch's tierWorkspaceApps so the sidebar, Home, New
chat, and All apps agree.
- Dispatch pins are one per-page store (
useWorkspaceAppLayout) saved to
device storage and application_state chat-first-app-layout. Read and
write pins only through it, and pass the rail its togglePinned as
onTogglePinned; a whole layout from another copy overwrites pins set
elsewhere. Workspace state is written only after it has been read; an
unreadable read keeps changes on the device, shows the one Layout-level
notice, and retries. When an organization hides Agent-Native.com hosted apps,
list-connected-agents still returns them marked hiddenFromLaunchers
(the Agents page and A2A directory need them); launchers drop them through
filterBuiltInApps and isWorkspaceAppVisibleInDefaultLaunchers, while
app registrations keep them so open_app and pane restore still resolve.
Agent and state boundaries
- Keep app discovery, embed-session minting, and thread operations on the
existing action surfaces.
- Emit the shared chat-first open-app event only for the completed first-party
open_app action with a real app, path, or view. A missing or unreadable
result is not success, and namespaced third-party tools cannot steer the
pane.
- Both web and desktop resolve the event through the same core origin/base-path
allow-list. An unresolved target produces a visible notice and no pane.
- If the agent needs to know which app is visible, expose a compact
application-state selection instead of scraping the iframe DOM.
- Cloud handoff is a future execution-residence seam. Do not claim that a local
run has moved to a worker until a durable worker snapshot and readback exist.
Verification
Test the disabled path and the enabled path separately. For the enabled path,
verify rail ordering, chat history, app selection, embed-session errors, pane
close, and completed open_app behavior in a running client. Treat configuration
alone as insufficient proof.
1---2name: chat-first-workbench3description: >-4 Implement or extend the opt-in Codex/T3-like chat-first shell. Use when5 changing chat rails, contextual app panes, app opening, or local/mobile shell6 preferences across Electron, Dispatch, or mobile.7scope: dev8metadata:9 source: https://skillmd.com/skills/builderio/chat-first-workbench10---1112# Chat-first workbench1314## Contract1516The chat remains the primary surface. Workspace apps are a bounded discovery17rail, not a second navigation system. An app pane is opened from an explicit18app selection or a completed open_app action and carries only an app id plus a19validated app-relative path or view.2021## Client behavior2223- The preference is opt-in and local to the client. Keep the existing app-first24 shell unchanged when it is disabled.25- Electron uses the shared Code Agents rail and AppWebview.26- Dispatch uses list-workspace-apps and create_embed_session; never iframe a27 raw workspace URL. Resolve an absolute open_app URL against the registered28 app first, then pass the resulting app-relative path.29- Mobile uses the existing app registry and secure AppWebView routes instead of30 accepting arbitrary URLs or adding a second navigator.31- Show no nested app sidebar or browser chrome in a contextual pane.32- Without `sections`, the app shelf is capped at six visible entries and33 supports pinning and drag-reordering (Desktop). Both are presentation34 preferences; the agent-visible target remains the registered app id and35 route.36- With `sections` (Dispatch), the host owns grouping and order and the rail37 shows every row it is given, expanded and collapsed, with an optional38 `emptyLabel` and no drag or move controls. Dispatch's sidebar passes one39 section: Pinned apps (pin order), or with no pins three suggested apps40 (workspace apps A to Z, else Agent-Native.com hosted apps), plus the open app; All apps holds41 the rest. Tier with Dispatch's `tierWorkspaceApps` so the sidebar, Home, New42 chat, and All apps agree.43- Dispatch pins are one per-page store (`useWorkspaceAppLayout`) saved to44 device storage and `application_state` `chat-first-app-layout`. Read and45 write pins only through it, and pass the rail its `togglePinned` as46 `onTogglePinned`; a whole layout from another copy overwrites pins set47 elsewhere. Workspace state is written only after it has been read; an48 unreadable read keeps changes on the device, shows the one Layout-level49 notice, and retries. When an organization hides Agent-Native.com hosted apps,50 `list-connected-agents` still returns them marked `hiddenFromLaunchers`51 (the Agents page and A2A directory need them); launchers drop them through52 `filterBuiltInApps` and `isWorkspaceAppVisibleInDefaultLaunchers`, while53 app registrations keep them so `open_app` and pane restore still resolve.5455## Agent and state boundaries5657- Keep app discovery, embed-session minting, and thread operations on the58 existing action surfaces.59- Emit the shared chat-first open-app event only for the completed first-party60 `open_app` action with a real app, path, or view. A missing or unreadable61 result is not success, and namespaced third-party tools cannot steer the62 pane.63- Both web and desktop resolve the event through the same core origin/base-path64 allow-list. An unresolved target produces a visible notice and no pane.65- If the agent needs to know which app is visible, expose a compact66 application-state selection instead of scraping the iframe DOM.67- Cloud handoff is a future execution-residence seam. Do not claim that a local68 run has moved to a worker until a durable worker snapshot and readback exist.6970## Verification7172Test the disabled path and the enabled path separately. For the enabled path,73verify rail ordering, chat history, app selection, embed-session errors, pane74close, and completed open_app behavior in a running client. Treat configuration75alone as insufficient proof.