Claim Agent Ownership

Claim Agent Ownership

When two daemons (typically Mac Studio at home + a k8s pod) both run agent.host.declare for the same agent, the first one wins ownership and the second registers a contested binding. The user UI surfaces a "binding contested" badge and the cloud's resolveAgentDaemonRoute keeps routing dispatches to the original owner — but a human-driven or orchestrator-driven decision is needed to converge.

This skill is the orchestrator's tool for that decision. It calls the server's authoritative rebind endpoint, which atomically:

1. flips im_agent_bindings.boundDaemonId to the chosen target daemon
2. writes an audit row with boundBy='user-explicit' (or 'orchestrator')
3. returns the in-flight task count on the previous owner so the orchestrator can wait / drain before redirecting traffic
4. emits a sync event (agent.binding.rebound) so other daemons drop their hosting state for the agent

When to use

• A sync event with type agent.binding.contested arrives in your inbox.
• A user explicitly asks "the agent is bouncing between machines — pin it to my laptop".
• You (orchestrator) decide to migrate an agent off a misbehaving daemon (high error rate, stale heartbeats, etc.) and a target is available.
• Devices panel shows >1 daemon claiming the same agent and the user requests arbitration.

Do not use it for:

• Healthy single-daemon bindings (no contention — nothing to claim).
• Agents the orchestrator does not own / has no permission for (server rejects 403).
• Routing decisions that should be reversible at the chat-message level (use metadata.daemonId overrides in single dispatches instead).

API

There is no generic cloud im get / cloud im post subcommand in the runtime CLI contract described here (sdk/cloud/ and sdk/prismer/). A dedicated cloud agent rebind verb is not landed either. The skill calls the cloud HTTP endpoint directly via curl (or the equivalent fetch from the orchestrator's MCP runtime), authenticating with the daemon API key already present in the environment as $PRISMER_API_KEY:

Before a write, resolve the actual workspace, agent ID, target daemon ID and authorized identity from the current runtime. aip-identity is not a bundled prerequisite; use the available identity/read-only binding interface. Missing identity or unavailable endpoint is a stop condition, not permission to invent IDs or switch accounts. Confirm migration impact and drain in-flight work.

# Inspect the current bindings first.
curl -fsS \
  -H "Authorization: Bearer $PRISMER_API_KEY" \
  "$PRISMER_CLOUD_BASE/api/im/workspaces/<workspaceId>/agent-bindings"

# Issue the rebind. Requires workspace owner / active orchestrator / admin.
curl -fsS \
  -X POST \
  -H "Authorization: Bearer $PRISMER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"targetDaemonId":"<daemonId>","targetDaemonKind":"local","reason":"<short reason>"}' \
  "$PRISMER_CLOUD_BASE/api/im/agent-bindings/<agentImUserId>/rebind"

PRISMER_CLOUD_BASE defaults to the cloud the daemon paired with (https://prod.docbrew.cn in prod, http://127.0.0.1:3000 in local dev).

For pure-API use (orchestrator runtime, MCP tool, etc.), the underlying call is:

POST /api/im/agent-bindings/:agentImUserId/rebind
Authorization: Bearer <daemon api key>
Content-Type: application/json

{
  "targetDaemonId":   "daemon-mac-studio-01",   // required, must exist in workspace
  "targetDaemonKind": "local",                  // optional: 'k8s' | 'local' | 'edge'
  "targetDaemonLabel": "Mac Studio (home)",     // optional display label
  "reason":           "user prefers desktop daemon while on home network"
}

Successful response:

{
  "ok": true,
  "data": {
    "binding": {
      "agentImUserId":     "u_agent_ceo",
      "boundDaemonId":     "daemon-mac-studio-01",
      "boundDaemonKind":   "local",
      "boundDaemonLabel":  "Mac Studio (home)",
      "boundBy":           "user-explicit",
      "boundAt":           "2026-05-22T16:30:00.000Z"
    },
    "inFlightTaskCount":   3,
    "previousDaemonId":    "daemon-k8s-pod-7f4"
  }
}

Failure modes worth handling explicitly:

Workflow

1. Subscribe to agent.binding.contested sync events. The orchestrator's sync inbox delivers these out of band; the skill consumes them.
2. Resolve the target daemon. Read the binding list and pick the daemon you want to keep — usually the one with:
   • smaller lastDispatchAt skew (fresher),
   • matching device kind to user preference (local vs k8s),
   • lower contestCount (less flapping).
3. Decide whether to drain. If inFlightTaskCount > 0 on the previous owner, surface this to the user ("3 tasks finishing on the old daemon before switching"). The orchestrator should usually let those finish — the rebind takes effect for subsequent dispatches, in-flight tasks complete via the existing route.
4. Call rebind. Pass targetDaemonId + reason. Optional kind/label improve UI readability.
5. Verify. Read /workspaces/:wsId/agent-bindings again and confirm boundDaemonId matches your target. If still divergent, the daemon may have re-declared between read and write — repeat once.