Studio: use Harper's built-in agent, with sessions, approvals and settings

Start with src/integrations/api/chat/getChatTransport.ts to see how Studio sends commands, then read src/hooks/useRollingConfigUpdate.tsx for the existing settings save and restart flow. The issue names Harper’s agent operations and session behavior, but does not identify the instance page or session UI entry points. Done means admins can manage sessions, approvals, and settings for one instance, with the stated version, permission, restart, and error behavior.

Problem

Harper has a built-in AI agent that runs inside Harper. It takes a request in plain language, then works on the instance itself: reading data, logs and app files, and running Harper's admin commands. Fabric turns it on for Harper 5.2+. Studio has no screen for it, so a customer can only use it by typing raw commands into the Operations console. Studio's own chat assistant is separate: it runs through central-manager with its own AI model and doesn't use this agent (getChatTransport.ts).

What core already provides (harper, as of 5.3.4)

• Six admin-only commands:
  • agent_prompt sends a request. Without a session_id it starts a new session; with one, it continues that session. It answers at once with the session id and running, and the agent keeps working in the background.
  • get_agent_session returns a session: its status, the full conversation and any actions waiting for approval.
  • list_agent_sessions lists sessions.
  • cancel_agent_run stops a session.
  • approve_agent_action approves or denies one waiting action, then the agent carries on.
  • set_agent_config changes some of the agent's settings, but only until Harper restarts.
• Session statuses: idle, running, awaiting_approval, completed, aborted and error. A new prompt is refused while a session is running or awaiting_approval.
• Restarts: sessions and waiting approvals are kept across restarts. Nothing in Harper picks up a run that a restart cut off.
• What the agent can use:
  • Harper's admin commands, from the same list as the MCP server's operations part, filtered by mcp.operations.allow and deny. By default that's the read-only set.
  • Its own tools: read and write app files, read logs and settings files, fetch web addresses, attach a debugger to Harper's threads, and schedule a follow-up.
• Approvals: with allowDestructive off, the tools that change things are removed (writing app files and running code in the debugger, plus any change command), so the agent never asks for approval. With allowDestructive on and autoApprove off, each of those actions waits for a person to approve it.
• Settings (agent block): enabled, provider, model, maxTurns, autoApprove, allowDestructive, user, systemPromptAppend, componentsScope and maxCostUsd. They're saved with set_configuration and take effect after a restart.
  • When the agent is off at startup, its commands don't exist, so only a settings change and a restart can turn it on.
  • maxCostUsd is accepted, but Harper doesn't enforce it. maxTurns is the only limit that applies.
• Who the agent acts as: agent.user, by default hdb_agent. That user's role limits the admin commands the agent runs.
• Sessions stay on one node. They're stored on the node that ran them and aren't shared across a cluster, and a running session lives on that node.
• Source (v5.3.4): agent/, operations.ts, agent.ts, toolset.ts, session.ts, epic harper-pro#676.

On Fabric today

• Host-manager turns the agent on for Harper 5.2+, with autoApprove and allowDestructive off and maxTurns 12 (agentConfig.js).
  • These are defaults, so a customer's own settings win.
  • They reach an existing instance only when Fabric next rebuilds it, so older instances may still have the agent off.
  • A host can be set to force the agent off. Then a customer's settings can't turn it back on.
• The agent has an AI model to call only on hosts that run one, which today means GPU hosts set up for it. Elsewhere the agent is on but has no model. That's covered by CM#457, CM#458 and HM#201, not this issue.

What to build

• An "Agent" page for each instance, shown only on Harper 5.2+ and only to admin users.
• Send every agent command to one specific instance (/HDBInstance/:id/operation), not to the cluster, since sessions live on one node. On a cluster, say which node each session is on.
• Sessions:
  • Start a session with a request, and continue it with follow-ups.
  • Show the conversation as it grows, including the actions the agent took, by checking get_agent_session until the session stops running.
  • List past sessions with their status, and open one.
  • Stop a running session.
  • Don't offer a new prompt while a session is running or waiting for approval. When a session shows as running but isn't moving, for example after a restart, offer to stop it so it can continue.
• Approvals: when a session is waiting, show each waiting action with its command and inputs. Let the customer approve or deny it.
• Settings:
  • Turn the agent on or off. Set allowDestructive, autoApprove, maxTurns, user (pick a database user) and systemPromptAppend.
  • Save with Studio's existing settings save and restart (useRollingConfigUpdate.tsx), not with set_agent_config, which is lost on restart. Before saving, say that the instances restart, and warn when a session is running.
  • Don't offer maxCostUsd while Harper doesn't enforce it.
  • When the agent is off on the instance, say so, and offer to turn it on.
• Explain, on the page:
  • the agent acts on the instance itself
  • choose a user for the agent: its role limits the admin commands the agent runs
  • turning on allowDestructive lets it change things, and turning on autoApprove lets it do so without asking
  • the commands it can run come from the same list as the MCP server (studio#2011)
• Show Harper's own error when a command is refused or a session ends in error, for example when the host has no AI model.

Acceptance criteria

• A customer can send the agent a request from Studio and follow the session until it finishes, without the Operations console.
• A customer can approve or deny a waiting action, and the session carries on.
• A customer can stop a running session.
• Settings saved in Studio still apply after a restart.
• Non-admin users don't see the page. On Harper below 5.2, the page is hidden or explains that it needs 5.2.

Dependencies

• No central-manager or host-manager work is needed for this page. Studio already sends admin commands to a single instance through Fabric's command channel, and that requires "update" permission on the cluster in Fabric.
• The agent only gets answers on hosts with an AI model until CM#457 and CM#458 land.