41 InkCop Local Collab

41 InkCop Local Collab

Source: docs/design/41-inkcop-local-collab.md

Same number prefix as 41-Project-Team; different topic. Contract aligned with InkCop’s same-machine Connection bridge doc (v0.4).

Endpoint versions

endpoint.version	Capabilities
1	health / connections / messages SSE
≥ 2	+ GET /v1/agents
≥ 3	User API key + optional LAN; token = settings key
≥ 4	Agent items include description (main agent = main chat role definition)

Product surface

1. Extension Center → Local app collaboration — InkCop card: enable toggle (bridge status chip), API key, optional service URL. Does not create a system Bot.
2. When enabled — any Bot detail can multi-select linked InkCop agents from GET /v1/agents (name / kind / description). Selection writes runtime.inkcop_agent_keys only — does not switch message_transport, does not divert whole turns.
3. Runtime — Bot still uses its normal LLM. Linked agents register tool call_inkcop_agent (agent_key enum = checked keys; description injected). Call only when the user names it or the Bot judges a handoff is needed → connections + messages SSE → tool result → Bot replies.
4. When disabled — hide link UI; no discovery, no tool, no bridge calls.
5. ACP agent:inkcop remains a debug bypass. Knowledge base still talks to LoomVec directly.

Settings

settings.inkcopLocalCollab = { enabled, apiKey, baseUrl }.

• apiKey required for stable calls; empty may prefill from endpoint.json token during same-machine discovery
• baseUrl optional override (LAN / remote machine); empty → endpoint / http://127.0.0.1:<port>
• Legacy systemBotId removed from settings type (ignored if patched)
• Catalog jump cards: agents.inkcop-local-collab, bot.inkcop-agents

Runtime rules

• Resolve baseUrl / apiKey from settings with endpoint fallback; no key → no requests
• All /v1/* use Authorization: Bearer <apiKey>; 401 → “invalid or missing key”
• Whole-turn divert removed (shouldUseInkcopBridge always false)
• Tool gate: collab enabled and inkcop_agent_keys non-empty
• Legacy runtime.message_transport === 'inkcop-local' no longer changes send path (cleared on read/write)
• call_inkcop_agent is default-forbidden in tool description + system rules; only on explicit user handoff. Progress “Calling InkCop agent…” only during tool execute, never at turn start

Client API

GET /v1/health, GET /v1/agents, POST /v1/connections, messages SSE; internal handoffToInkcopAgent; RPC inkcop.health (see source for full list).