feat(backend): full remote implementation, untested

docs/remotes.md

@@ -0,0 +1,115 @@
+# Remotes
+
+## Overview
+
+A **session** is one authenticated `/ws` connection. Authentication is
+uniform — token or username/password — and every session is a user
+connection that receives event broadcasts and can send any action.
+
+A **remote** is a named set of functions served by a session:
+
+- Connected by that session with the `remote-connect` action (backed by the
+  `App.connectRemote` method), stored in `App.remotes` scoped to the user.
+- **Lifetime**: connected until `remote-disconnect` (manual, allowed from any
+  session of the same user) or until the serving session closes — session
+  close disconnects every remote it connected. Nothing is persisted.
+- **No overriding**: connecting a name that is already connected for that
+  user fails with an error reply.
+
+**Local Remotes** — purely user-side constructs, entirely implemented and
+stored in the frontend (`Remotes.vue`). They never touch the backend.
+
+Agents never link to remotes. A prompt passes remote names in
+`options.remotes`; `ExpertAgent.run` expands them into run-scoped tools.
+Every function of a remote becomes a tool named exactly after the function,
+prefixed only when the run input asks for it.
+
+This also implements the existing `server.py` TODO ("remotes aren't separate
+connections — any connection can create a remotes and listen for requests
+sent to them").
+
+The frontend is already implemented and out of scope; the backend serves the
+two actions it uses (`remote-list`, `remote-call`) with the shapes below.
+
+## Wire protocol
+
+Every message in both directions uses the existing action envelope. There is
+no separate `type`-keyed protocol.
+
+Upstream (session → backend):
+
+| action | payload | success reply | error reply |
+|---|---|---|---|
+| `remote-connect` | body `{remotename, tools}` | `{'message': 'remote connected', 'remotename', 'nonce'}` | `{'error': "remote 'x' is already connected", 'nonce'}` |
+| `remote-disconnect` | body `{remotename}` | `{'message': 'remote disconnected', 'remotename', 'nonce'}` | `{'error': "no connected remote named 'x'", 'nonce'}` |
+| `remote-list` | — | `{'remotes': [...], 'nonce'}` | — |
+| `remote-call` | body `{remotename, function, args}` | `{'result': <JSON value>, 'nonce'}` | `{'error': '...', 'nonce'}` |
+| `remote-call-result` | top-level `{requestId, result}` or `{requestId, error}` | none | none |
+
+`tools` entries (function specs) and the `remote-list` entries share one
+shape: `{name, description, parameters}` with `parameters` a full OpenAI
+tool-parameter schema dict.
+
+Downstream (backend → the session serving the remote):
+
+~~~json
+{"action": "remote-call", "requestId": "weather-service#0", "function": "get_forecast", "args": {"city": "Rome"}}
+~~~
+
+Result routing: requestIds are `'<remotename>#<n>'`, unique among a user's
+remotes. A `remote-call-result` is fanned out over the receiving session's
+own connections; `resolve`/`reject` ignore unknown ids, so one session can
+serve several remotes without ambiguity. Fan-out is session-scoped, so
+identical id strings belonging to another user's remote can never be
+resolved from this session.
+
+Example connect + call round trip:
+
+~~~json
+{"action": "remote-connect", "nonce": "c1", "body": {"remotename": "weather-service", "tools": [{"name": "get_forecast", "description": "Retrieve weather forecast for a location.", "parameters": {"type": "object", "properties": {"city": {"type": "string", "description": "City name."}}, "required": ["city"]}}]}}
+~~~
+
+~~~json
+{"action": "remote-call", "nonce": "c2", "body": {"remotename": "weather-service", "function": "get_forecast", "args": {"city": "Rome"}}}
+~~~
+
+~~~json
+{"action": "remote-call-result", "requestId": "weather-service#0", "result": {"forecast": "sunny", "city": "Rome"}}
+~~~
+
+Calls not answered within `REMOTE_CALL_TIMEOUT` (30s, constant in
+`remote.py`) fail; calls pending when the remote disconnects fail
+immediately. All failures surface as `RemoteError`, which becomes an error
+tool-result string for the model — never an exception that kills a run, and
+never a killed caller session.
+
+## The prompt contract
+
+~~~json
+{
+  "action": "send-agent-prompt",
+  "body": {
+    "agentId": 7,
+    "instruction": "What's the weather in Rome? Use your tools.",
+    "options": { "remotes": ["weather-service", { "name": "code-repo-indexer", "prefix": "repo_" }] }
+  }
+}
+~~~
+
+- `Agent.prompt` already splats options into the run input
+  (`input={"instruction": ..., "input": ..., **kwargs}`), so `options.remotes`
+  lands in `run.input["remotes"]`. No server or app change needed.
+- Each entry is a remote name or `{"name": ..., "prefix": ...}`. Every
+  function of the remote becomes one tool named `prefix + function_name`
+  (empty prefix by default).
+- Collisions: the agent's native tools are listed before remote tools and
+  the expert lookup takes the first match, so native tools win. Pass a
+  `prefix` to disambiguate.
+- Remotes are resolved once, at run start. A remote not connected at that
+  moment is skipped with a console warning and the run proceeds (remotes
+  disconnect independently of prompts). If a remote disconnects mid-run,
+  its pending calls fail and the model sees error tool results.
+- Existing expert rule unchanged: if the run input already carries its own
+  `tools`, those replace the agent toolset entirely and remotes are not in
+  play.
+- Users only see their own remotes — the registry key includes `user_id`.