| name | ama-panel |
| user-invocable | false |
| description | Drive an agent's HTML dashboard side panel via the frozen aimaestro-panel.sh CLI — push HTML or a live URL, open/close/refresh the panel, check how many dashboard clients are connected, and drain feedback events the panel's HTML posted back. Use when an agent wants to render a status view, a form, or a live page in its own dashboard panel. Trigger with /ama-panel, 'show this in my side panel', 'push this HTML to my panel', 'check if anyone is watching my panel', 'read panel feedback'. CRITICAL gotcha: 'delivered: 0' from open/set means the content was DROPPED, not queued — always check status first when delivery matters. Loaded by ai-maestro-plugin |
| allowed-tools | Bash(aimaestro-panel.sh:*), Bash(jq:*), Read, Grep, Glob |
| metadata | {"author":"Emasoft","version":"1.0.0"} |
ama-panel — drive an agent's HTML dashboard side panel
Overview
ama-panel wraps the frozen aimaestro-panel.sh CLI (Tier A, §2.1 of
SCRIPT-MANIFEST.md): the surface an agent uses to render content — HTML or
a live URL — into its own dashboard side panel, and to read back feedback
the rendered page posts. It never talks to the AI Maestro API directly; the
CLI resolves the API base and the caller's identity internally.
THE GOTCHA — read this before relying on any set / open result
delivered: N on open/set is a live-channel count, not a queue
depth. Unlike ama-session's queue, the panel is a live surface —
there is no server-side hold-and-drain for it. delivered: 0 means the
content was DROPPED, not "waiting for someone to look" — it means no
dashboard client currently has that agent's panel open. If delivery
actually matters (the panel is carrying something the user needs to see,
not just a nice-to-have), check status first:
aimaestro-panel.sh status <agent>
status reports the number of connected dashboard clients and the pending
feedback-event count. If it reports zero clients, set/open will report
delivered: 0 and you should not treat the push as having reached anyone.
Authorization
Per TRDD-D3RP7KQZ: an agent drives its own panel by default. Targeting
another agent's panel requires MANAGER (any agent) or CHIEF-OF-STAFF
(agents of its own team). Strict verbs (agent: AID + title; human: fresh
sudo-token): open, close, refresh, set. Non-strict: status,
feedback.
Security constraints on pushed content
- Pushed HTML renders in a sandboxed
iframe srcdoc — no
allow-same-origin, so it cannot read the dashboard's own cookies/storage.
- A live
--url renders with allow-same-origin (it's a real page you
are choosing to trust), and only https:/http: schemes are accepted —
javascript:, file:, and data: URLs are rejected with a 400.
- HTML content is capped at 2 MB.
Prerequisites
- AI Maestro running;
aimaestro-panel.sh on PATH (installed by
install-messaging.sh; re-run it if missing).
- The CLI resolves your agent identity + bearer token internally.
jq for parsing JSON output.
Instructions
-
Decide what you're rendering: static HTML (--html inline or
--html-file <path>) or a live page (--url).
-
If delivery matters, check who's watching first:
aimaestro-panel.sh status <agent>
-
Push the content and open the panel:
aimaestro-panel.sh set <agent> --html-file /tmp/status.html
aimaestro-panel.sh open <agent>
Or push a live URL:
aimaestro-panel.sh set <agent> --url "https://example.com/live-status"
-
Check the delivered count in the response. 0 means dropped — the
panel wasn't open anywhere. If the content is important, open the
panel first (or tell the user to open their dashboard) and re-set.
-
refresh <agent> to re-render after pushing new content without
toggling open/close. close <agent> when done.
-
Drain any feedback the pushed HTML posted back (e.g. a form submit inside
the iframe):
aimaestro-panel.sh feedback <agent>
feedback drains — it reads and clears in one call; a second call
returns nothing new until more feedback arrives.
Quick CLI Reference
| Subcommand | Flags | Verb class |
|---|
open <agent> | --url <https-url> | strict |
close <agent> | — | strict |
refresh <agent> | — | strict |
set <agent> | exactly one of --html-file <path> | --html "<html>" | --url <https-url> | strict |
status <agent> | — | non-strict |
feedback <agent> | — | non-strict, drains (read + clear) |
Output
JSON on STDOUT (pipe to jq). set/open return { "delivered": N, ... }.
status returns the connected-client count and pending-feedback count.
feedback returns the drained events (empty array if none).
Error Handling
| Symptom | Likely cause |
|---|
delivered: 0 | no dashboard client has this agent's panel open — check status, ask the user to open it, or accept the push was a no-op |
400 on --url | scheme is not https:/http:, or the URL was javascript:/file:/data: |
400 on --html/--html-file | content exceeds the 2 MB cap |
| 403 targeting another agent | you are not MANAGER, and not that agent's own-team COS |
feedback returns empty every time | either nothing has been submitted yet, or it was already drained by a prior call |
Examples
Push a status page and confirm it actually reached someone.
→ `aimaestro-panel.sh status ` (check client count) → if non-zero,
`aimaestro-panel.sh set --html-file status.html` → confirm
`delivered` in the response is non-zero.
Render a live external dashboard instead of static HTML.
→ `aimaestro-panel.sh set --url "https://example.com/dashboard"`
(rejected 400 if the scheme isn't `https:`/`http:`).
Read back a form the panel's HTML posted.
→ `aimaestro-panel.sh feedback ` — remember this drains; the same
events won't show up on a second call.
Scope
Drives an agent's own dashboard panel, or another agent's when the
caller is MANAGER (any) / COS (own team). Terminal/state control is
ama-session. Server-mediated TRDD search/read is ama-trdd-server.
Resources
.claude/rules/aimaestro-manager-approval-defaults.md — the
EXEMPT/NON-EXEMPT split this skill's strict/non-strict verbs mirror
(the ai-maestro DEP overlay, seeded into every agent workdir).
Use also
Skill(skill: "ama-session") — drive the agent's terminal/state; the
companion self-drive surface to this one.Skill(skill: "team-governance") — the titles (MANAGER/COS/…) this
skill's cross-agent targeting rule is keyed on.
