feat(kiloclaw) Plumbing for multi agent channel binding management

[St0rmz1]

Summary

Adds agent channel-binding management to KiloClaw, end to end. The controller
now surfaces each agent's routing bindings on reads and exposes a declarative
endpoint to set an agent's channel-level default routes, delegating all routing
semantics to the OpenClaw CLI. The change is plumbed through the Durable Object,
the Worker platform route, the web internal client, and tRPC (personal and
organization namespaces). No UI is included; this is the backend for a later
binding management surface.

Changes

Controller (services/kiloclaw/controller):

• Agent read summaries now include routing bindings (channel, account id, and an
  advanced flag), sourced from the OpenClaw CLI. Every response that returns an
  agent summary carries them.
• New PUT /_kilo/config/agents/:agentId/bindings that declaratively sets an
  agent's channel-level default routes to exactly the requested channel set, by
  diffing the CLI's view and issuing bind/unbind.
• New capability config.agents.bindings.update and error codes
  agent_binding_conflict (409) and agent_binding_rollback_failed (500).
• Atomicity: on a conflict or a result that does not match the request, the
  operation rolls back only the routes it created (diffed against a pre-change
  snapshot) and confirms restoration. An unconfirmable restoration returns 500
  rather than report a clean result over changed routing.
• Input guard: channel values reject a leading dash and the : account
  specifier (this endpoint manages channel-level default routes only).

Cloud passthrough:

• DO updateAgentBindings method and callGatewayController widened to PUT.
• Worker route PUT /api/platform/agents/:agentId/bindings with the binding
  error codes mapped through (services/kiloclaw/src/routes/platform.ts).
• Web internal client method and tRPC updateAgentBindings in both the personal
  (kiloclaw-router.ts) and organization (organization-kiloclaw-router.ts)
  routers, sharing AgentBindingsInputSchema.
• AgentSummary types carry bindings worker-side and web-side.

Spec and tests:

• Controller spec documents the binding endpoint, capability, error codes, and
  managed-scope/concurrency limits (.specs/kiloclaw-controller.md).
• Unit tests across the controller, DO, Worker, and tRPC layers; the entrypoint
  smoke test exercises a binding round-trip against the pinned OpenClaw image.

Verification

Run against the pinned openclaw@2026.5.26 controller image:

• Set, narrow, and clear a channel set (200, managed routes match the request)
• Conflict when a channel is already routed to another agent (409, both agents' routing left unchanged)
• Create-with-bindings and settings-update responses carry the agent's bindings
• Missing agent, including unconfigured implicit main (404)

Visual Changes

N/A

Reviewer Notes

• Routing semantics (conflict detection, account canonicalization, $include,
  ordering) are delegated to the version-matched OpenClaw CLI; the controller
  does not edit route config directly.
• The endpoint manages only channel-key-only default routes. Account-scoped,
  advanced (peer/guild/team/roles), and externally authored routes are surfaced
  in reads but left intact (see spec rule 22).
• Capability-gated end to end: the cloud layer fails closed when the controller
  does not advertise config.agents.bindings.update.

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Executive Summary

All previously identified issues have been resolved; the channel validation guards are now correctly applied in AgentBindingsInputSchema, and no new issues were found in the PR-scoped incremental diff.

Resolved Issues

File	Previous Issue	Status
apps/web/src/lib/kiloclaw/agent-schemas.ts	AgentBindingsInputSchema missing : and leading-- guards on channel values	Fixed in commit 06046a510

Files Reviewed (25 files)

• .specs/kiloclaw-controller.md
• apps/web/src/lib/kiloclaw/agent-schemas.ts — fix confirmed
• apps/web/src/lib/kiloclaw/agent-schemas.test.ts
• apps/web/src/lib/kiloclaw/kiloclaw-internal-client.ts
• apps/web/src/lib/kiloclaw/types.ts
• apps/web/src/routers/kiloclaw-router.ts
• apps/web/src/routers/kiloclaw-router-agents.test.ts
• apps/web/src/routers/organizations/organization-kiloclaw-router.ts
• services/kiloclaw/controller/src/endpoint-capabilities.ts
• services/kiloclaw/controller/src/endpoint-capabilities.test.ts
• services/kiloclaw/controller/src/openclaw-agent-bindings.ts
• services/kiloclaw/controller/src/openclaw-agent-bindings.test.ts
• services/kiloclaw/controller/src/openclaw-agent-cli.ts
• services/kiloclaw/controller/src/openclaw-agent-cli.test.ts
• services/kiloclaw/controller/src/openclaw-agent-config.ts
• services/kiloclaw/controller/src/openclaw-agent-config.test.ts
• services/kiloclaw/controller/src/routes/config-agents.ts
• services/kiloclaw/controller/src/routes/config-agents.test.ts
• services/kiloclaw/scripts/controller-entrypoint-smoke-test.sh
• services/kiloclaw/src/durable-objects/gateway-controller-types.ts
• services/kiloclaw/src/durable-objects/kiloclaw-instance/gateway.ts
• services/kiloclaw/src/durable-objects/kiloclaw-instance/gateway.test.ts
• services/kiloclaw/src/durable-objects/kiloclaw-instance/index.ts
• services/kiloclaw/src/routes/platform.ts
• services/kiloclaw/src/routes/platform-agents.test.ts

---

_{Reviewed by claude-4.6-sonnet-20260217 · 2,634,754 tokens}

_{Review guidance: REVIEW.md from base branch main}