Agent Management

Agent management

Use this only when the user explicitly asks to use Autonomous Buddy, a Buddy session, or its selected desktop pane. For ordinary requests to ask an agent on the paired Mac to perform work, including research, use harness-use; do not require a Buddy pairing as a fallback.

Run python3 scripts/buddy_agents.py from this skill directory on the Autonomous device. The localhost API is the device API, not the Mac. Never start the coding CLI or edit the desktop project's files on the lamp. Buddy owns the terminal PTY, worktree and provider conversation; Swift relays the paired WebSocket.

Spoken tasks and follow-ups

Use the voice action for normal conversation. Send JSON via stdin (quoted heredoc) to preserve spoken text without shell interpolation:

python3 scripts/buddy_agents.py voice - <<'JSON'
{"operation":"send","target":"active","request_id":"UNIQUE_UUID_FOR_THIS_TURN","prompt":"Add a test for reconnect after network loss"}
JSON

• target:"active" (or its alias target:"current") explicitly addresses the worktree and focused pane selected inside Buddy. It does not guess from OS window focus, most recently updated session or terminal title. Use it for “current session”, “type to current session”, “agent/tab đang mở”, “session hiện tại”, “this selected agent”, or a request to switch to the currently selected tab. These explicit current-selection references override the retained voice target, even if the rest of the sentence says “it”. Fetch the live selection; do not substitute session IDs from conversation history. A plain shell pane cannot receive agent prompts.
• Omit target (or use target:"previous") only for follow-ups such as “thêm test nữa” or “ask the same agent to continue”, without a current/selected-tab reference: the helper retains the last voice session even if desktop tab focus changes. On the first voice request with no retained context it uses Buddy's selected pane. A missing/closed/stale target is an error, never permission to choose another agent.
• For an explicit project/session, call list and use the returned project_id and session_id. Named selectors project and worktree match exact returned names, IDs, branch names or paths; ambiguous matches return an error. Ask only which target is meant, then use those exact selectors. Do not invent Mac paths or IDs.
• To create a session, use new_session:true plus provider:"codex" or "claude", and the requested target worktree. Example: {"operation":"send","target":"active","new_session":true,"provider":"codex","request_id":"UUID","prompt":"Fix reconnect"} creates in the selected worktree, including a feature worktree. Only create when the user asks to start a task/session; never create merely because a follow-up target is unavailable. If the provider is unspecified, ask which available agent to use.
• operation:"select" retains an explicitly chosen session without sending a prompt. operation:"status" returns the target's session/events. operation:"stop" stops that target; it does not roll back edits.
• conversation_id defaults to voice for the device's single spoken conversation. For a separate chat channel use its stable conversation identifier; do not share a voice target across unrelated chats or invent a new conversation ID on every turn. If a different speaker's target is uncertain, select explicitly.

Keep one request_id UUID for each intended send. The helper stores the resolved IDs and receipt before dispatch, deduplicates successful repeats and preserves uncertainty on a lost response. Acceptance is not completion. Read the actual returned project/session and report that work was sent; wait for completion notification or inspect status for results.

If delivery is uncertain, inspect status and list; do not issue the same task under a new ID or infer failure from missing output. An unresolved receipt blocks another voice send in that conversation. After the user has reviewed the terminal and explicitly chooses to abandon that uncertain send, {"operation":"resolve","request_id":"ORIGINAL_UUID","resolution":"do_not_retry"} clears its block without resending anything. Preserve the target. Explicit desktop rejection (busy/manual input) is reported without claiming acceptance; it does not block unrelated later turns as an uncertain receipt would.