agent-shell/README.md

agent-shell

agent-shell is a Flutter package for embeddable agent interaction surfaces. It is not a product app. It provides the shared shell that IOP, NomadCode, and future host apps can compose with their own capability packs.

Purpose

• Render agent messages, tool calls, and approval prompts.
• Provide capability and event interfaces that host apps can wire to their own backends.
• Stay product-agnostic: no IOP, NomadCode, WebView, workflow, or Control Plane dependency lives here.
• Fit into different workbench layouts, including NomadCode's right rail and IOP's left rail.

Package Boundary

agent_shell
  AgentShell widget
  AgentMessage / AgentToolCall models
  AgentCapability / AgentCommand / AgentEvent interfaces
  Tool call and approval UI primitives

iop_console_flutter
  IOP-specific capability pack
  IOP Control Plane / Edge / Node integration

nomadcode_app
  NomadCode workbench shell
  NomadCode WebView/workflow capability pack
  optional IOP composition package

Example

AgentShell(
  messages: messages,
  busy: isRunning,
  onSubmit: (text) => agentRuntime.send(text),
  onToolAction: (action) => agentRuntime.handleToolAction(action),
)

Intended Composition

IOP standalone:

iop/apps/client
  -> iop_console_flutter
  -> agent_shell

NomadCode without IOP:

nomadcode/apps/client
  -> nomadcode workbench shell
  -> agent_shell

NomadCode with IOP:

nomadcode optional composition layer
  -> nomadcode workbench shell
  -> iop_console_flutter
  -> agent_shell

The IOP import must stay in the optional composition layer so the default NomadCode build can succeed without IOP dependencies.