@tutti-os/agent-gui 0.0.94 → 0.0.96

package/README.md

@@ -5,25 +5,21 @@ UI. It is a UI package, not a host transport or business-core package.
 
 Before changing AgentGUI, AgentGuiNode, or the agent conversation module, read
 [AgentGuiNode Architecture and Troubleshooting](../../../docs/architecture/agent-gui-node.md).
-It records the source-of-truth rules, common chains, debugging playbooks, and
-the self-evolution loop for durable lessons.
+It defines daemon, workspace-engine, GUI-module, provider, and desktop-host
+ownership.
 
 ## Data Source
 
-`AgentActivityRuntime` is the AgentGUI source for agent activity data.
+The injected workspace `AgentSessionEngine`, reached through
+`AgentActivityRuntime`, is AgentGUI's only source for canonical agent activity
+data.
 
 Runtime-owned data includes:
 
-- workspace activity snapshots
-- session lists
-- paged session messages
-- retained live session events
-- session event subscriptions
-- session create, activate, unactivate, input, cancel, interactive submit,
-  delete, pin, settings update, control-state read, composer-options read, and
-  get session operations
-- provider/session preparation hooks that directly gate activity flow, such as
-  OpenClaw gateway warmup
+- canonical sessions, turns, interactions, and operation state
+- prompt queue and correlated optimistic intents
+- stable selector projections
+- semantic session, turn, prompt, interaction, settings, and goal commands
 
 Runtime-owned capability declarations are optional and default to enabled:
 
@@ -31,9 +27,25 @@ Runtime-owned capability declarations are optional and default to enabled:
 - `canSubmitInteractive`: shows approval, ask-user, and plan-decision
   interaction entries.
 - `canGoalControl`: shows goal banner controls, `/goal`, and the goal badge.
-- `canUploadAttachment`: enables prompt attachment upload paths such as pasted
-  images, pasted large text, and dropped or host-local files. Ordinary `@`
-  references and workspace-reference mentions remain available.
+- `canUploadAttachment`: enables prompt attachment paths. Pasted large text
+  additionally requires the explicit `AgentActivityRuntime.stagePastedText`
+  host method; AgentGUI does not infer that capability from generic file
+  upload support. Ordinary `@` references and workspace-reference mentions
+  remain available.
+
+## Pasted Text Staging
+
+AgentGUI classifies plain-text clipboard content before delegating structured
+mention HTML. A trimmed payload of at least 5,000 characters is never inserted
+into the prompt automatically. It becomes a pasted-text draft attachment and
+is passed as raw text to `AgentActivityRuntime.stagePastedText`; the host owns
+local persistence and returns `{ path, name, sizeBytes }`.
+
+If the method is absent or staging fails, the attachment remains in an explicit
+failed state and retains its in-memory text. AgentGUI must not silently put the
+payload back into the input. The user can explicitly choose “Show in text
+field” to do that. Generic `uploadPromptContent` remains the contract for
+images and host-local files; it is not a pasted-text capability signal.
 
 Slash commands come from the runtime session command snapshot. AgentGUI keeps
 legacy provider-default slash entries unless the host passes
@@ -49,34 +61,29 @@ render-state changes, and caught errors. Set
 fallback. Production builds stay silent unless the host provides
 `reportDiagnostic`.
 
-`AgentHostApi` is still accepted for host capabilities that are not agent
-activity data:
+Host capabilities remain separate from activity data. `AgentHostApi` is still
+accepted for host capabilities that are not agent activity data:
 
 - workspace files and file references
 - clipboard
-- runtime metadata and diagnostics
 - account/user lookup
 - user-project selection
 - local file picking/reading and batch export helpers
 
-Production AgentGUI must receive `agentActivityRuntime` and must not use legacy
-Host API methods as an agent data fallback. Compatibility helpers remain only
-for projection boundaries, non-desktop legacy hosts, and tests.
+AgentGUI has no host-API activity fallback. A host must inject the runtime and
+the grouped `AgentGUINodeProps` responsibility objects.
 
 ## Boundary Rule
 
 `AgentActivity*` types from `@tutti-os/agent-activity-core` are the canonical
-frontend agent activity model.
-
-`AgentHostWorkspaceAgent*` DTOs are allowed only in compatibility/projection
-code that adapts legacy AgentGUI internals. New production read paths should use
-`useAgentActivityRuntime()` or `useOptionalAgentActivityRuntime()` instead of
-calling `workspaceAgents.list`, `workspaceAgents.listSessionMessages`,
-`agentSessions.retainEventStream`, `agentSessions.subscribeEvents`, or
-`agentSessions.getState` directly. Production writes should call runtime methods
-instead of `agentSessions.activate`, `agentSessions.unactivate`,
-`agentSessions.exec`, `agentSessions.cancel`, `agentSessions.submitInteractive`,
-`agentSessions.updateSettings`, or `agentSessions.pinSession`.
+frontend agent activity model. Production reads use exported engine selectors;
+production writes use engine commands. GUI modules must not read entity maps,
+subscribe to daemon streams, or reconstruct session/turn lifecycle from
+messages.
+
+Runtime identity is explicit: each consumer resolves the injected engine and
+verifies its `(workspaceId, origin)` identity. Module-global runtime slots and
+hidden origin registries are forbidden.
 
 Run this boundary check after changing AgentGUI data flow:
 
@@ -84,6 +91,27 @@ Run this boundary check after changing AgentGUI data flow:
 pnpm check:agent-activity-runtime-boundaries
 ```
 
+## Node Contract
+
+`AgentGUINodeProps` has eight required top-level responsibilities:
+`identity`, `workspace`, `frame`, `state`, `runtimeRequests`,
+`hostCapabilities`, `hostActions`, and `renderSlots`. Extend the owning object;
+do not restore flat compatibility props.
+
+## Home Suggestions
+
+The five starter entries below the empty new-session composer are enabled by
+default. External hosts can hide individual entries with the public
+`AgentGUI.disabled` array:
+
+```tsx
+<AgentGUI disabled={["meet-tutti", "import-session"]} {...props} />
+```
+
+The supported stable IDs are `meet-tutti`, `task-breakdown`, `quality-review`,
+`agent-interaction`, and `import-session`. Omitting `disabled` (or passing an
+empty array) renders all five entries.
+
 ## Agent Directory
 
 `AgentGUI` requires the host's `/agents` projection through its `agents` prop.
@@ -95,6 +123,7 @@ export interface AgentGUIAgent {
   agentTargetId: string;
   name: string;
   iconUrl: string;
+  heroImageUrl?: string | null;
   description?: string | null;
   owner?: {
     name?: string | null;
@@ -121,9 +150,14 @@ may share the same `provider` and remain distinct. `provider` is runtime metadat
 for provider-native execution, composer policy, probes, and capabilities; it
 must not be used to group, deduplicate, name, icon, or select agents.
 
-Agent names and primary icons always come from `agents[].name` and
-`agents[].iconUrl`. `owner.avatarUrl` is rendered separately as an ownership
-badge. Invalid entries and duplicate `agentTargetId` values are discarded by
+Runnable provider targets are host-supplied. If the target catalog is absent,
+AgentGUI presents an explicit unavailable state; it does not synthesize local
+targets from presentation metadata.
+
+Agent names, primary icons, and optional home-carousel artwork come from
+`agents[].name`, `agents[].iconUrl`, and `agents[].heroImageUrl`.
+`owner.avatarUrl` is rendered separately as an ownership badge. Invalid entries
+and duplicate `agentTargetId` values are discarded by
 `normalizeAgentGUIAgents`, with the first occurrence preserving host order.
 
 With one agent, AgentGUI hides the aggregate `All` entry and renders that agent
@@ -131,6 +165,19 @@ directly. With multiple agents, it shows `All` plus the host-ordered agent rail
 and empty-home carousel. Hosts may customize the aggregate icon with
 `allAgentsPresentation.iconUrl`.
 
+Hosts adapting daemon-owned agent targets must resolve the target's descriptor
+`iconKey` instead of assuming it equals the provider ID. The narrow
+`@tutti-os/agent-gui/provider-icons` subpath exports
+`resolveProviderIconAsset(iconKey, variant)` for that adapter seam. Unknown
+keys return `null`; hosts should render a neutral icon rather than silently
+substituting another provider's icon.
+
+Hosts that need provider identity presentation may call
+`resolveAgentGUIProviderIdentity(value)` from the narrow
+`@tutti-os/agent-gui/provider-identity` subpath. Migrated providers resolve from
+the generated descriptor catalog, which is checked against the daemon provider
+registry and OpenAPI provider enums.
+
 Inside AgentGUI, normalized directory entries use the canonical
 `AgentGUIAgentTarget` / `agentTargets` vocabulary. `provider` is execution
 metadata, not target identity. Rail tiles, the single-agent empty state, and
@@ -143,8 +190,9 @@ for that asset. The WebGL carousel keeps a local programmatic owner marker when
 the remote image cannot be decoded or uploaded safely, while DOM avatar
 surfaces continue using the same shared presentation.
 
-Use `agentsLoading` for directory hydration and `renderAgentsEmpty` for a
-host-specific loaded-empty state. Use `renderAgentUnavailableState` or
+Pass the full `agentDirectory` lifecycle snapshot for directory hydration and
+use `renderAgentsEmpty` for a host-specific loaded-empty state. Use
+`renderAgentUnavailableState` or
 `renderAgentReadinessState` for host-specific availability presentation, and
 handle install/login/refresh requests through `onAgentAvailabilityAction`.