What exists today
| Capability | Status |
|---|---|
| Six characters | Available in the app; each renders its own motion. |
| Eight animation IDs | Internal runtime: receive, complete, issue, pet, surprise, celebrate, sleep, typing. |
| External commands | Isolated debug mailbox only. No production command is installed. |
| Prompts and reminders | App features work internally; debug notice.create/dismiss is a limited adapter. |
| Choices, input, progress and long-poll waiting | Protocol draft; not a public implementation. |
Discover, then request an action
For developers with source access: use the existing signed, isolated DEBUG preview (app.monoware.shotloom.skinpreview), a temporary DESKCAPTURE_DIAGNOSTIC_DIR and the explicit --companion-agent-review launch argument. Its startup log reports CompanionAgentReview, the private session directory. This bridge cannot be enabled in a Release build. It is not a normal installation command or a downloadable SDK.
Use scripts/companion-agent-review.py from the source checkout. SESSION_DIR below is that logged directory, never the key itself.
python3 scripts/companion-agent-review.py --profile SESSION_DIR runtime.describe
python3 scripts/companion-agent-review.py --profile SESSION_DIR characters.list
python3 scripts/companion-agent-review.py --profile SESSION_DIR capabilities.list
python3 scripts/companion-agent-review.py --profile SESSION_DIR requests.create '{"capability":"animation.complete","params":{"durationSeconds":2}}'
python3 scripts/companion-agent-review.py --profile SESSION_DIR requests.get '{"id":"RETURNED_REQUEST_ID"}'
python3 scripts/companion-agent-review.py --profile SESSION_DIR requests.cancel '{"id":"RETURNED_REQUEST_ID"}'Use the discovered IDs, validate the response, and keep the returned request ID. Supported debug durations range from 0.1 to 10 seconds. The runtime may return BUSY or RUNTIME_UNAVAILABLE.
Show a prompt. Know what came back.
The debug bridge can show or dismiss a plain notice. Accepted means queued; it does not prove the person read it or completed a task. It does not return button choices or typed answers.
python3 scripts/companion-agent-review.py --profile SESSION_DIR notice.create '{"title":"Export complete","seconds":6}'
python3 scripts/companion-agent-review.py --profile SESSION_DIR notice.dismiss '{"id":"RETURNED_NOTICE_ID"}' Proposed interaction flow — not shipped
- Discover the authorized capabilities and their input/result schemas.
- Create an interaction with stable option IDs, a timeout and an idempotency key.
- The companion presents the prompt; the user chooses, replies, cancels or times out.
- Read the final result by request ID; resume the calling app or agent explicitly.
The draft proposes requests.create/get/wait/cancel, styles and capability discovery, plus interaction.text/choice/confirm. These are design contracts, not commands you can send to today’s Release app. A returned user choice is distinct from “shown” and from successful business execution.
Read the outcome, not just acceptance
Implemented animation requests expose running, completed or cancelled. Preempted actions finish as cancelled/preempted and do not replay later. Invalid parameters are rejected, and hidden or unavailable companions are not silently shown.
Debug results are in memory and session-bound; do not assume restart recovery, durable history, per-client ownership isolation or production availability. The full protocol additionally specifies timeout, cancellation and exactly one final user answer; these remain implementation requirements.
Local, deliberate access
The debug mailbox uses a private 0700 directory and 0600 files, with a random key read from its profile. Keys do not belong in command arguments, public docs, URLs or logs. No TCP listener is opened. The planned production transport is a local Unix domain socket with explicit pairing and revocation.
Companion expression does not grant screenshot capture, clipboard access, file reading or arbitrary shell execution. The caller owns its business task; the companion only presents declared, authorized capabilities.
Read the full 0.1 draft (Chinese)