@finalai/agents 0.10.0 → 0.12.0

package/HOSTING.md

@@ -1,274 +1,363 @@
-# Portable agent definitions and hosted bindings
+# Hosting agents: requirements, provide documents and local hosts
 
-An agent declares behavior and logical resources. Hosting supplies endpoints,
-resource identifiers, and credential references. The same compiled source can
-resolve against dev and production configuration without source edits.
+An agent is a document (data) that states what it requires: a harness within a
+permission ceiling, compute by capability, and named integration slots. Whoever
+starts work provides implementations in a plain `provide` object. This guide is
+for hosts that implement the agent platform API these packages call: what the
+SDK sends, what it expects back, and the connection a client dials to lend its
+own process to an agent.
 
 ## Selecting a deployment
 
 ```sh
-export FINAL_API_HOST=https://<dev-agents-api-host>/api
-export FINAL_API_KEY=<dev-api-key>
-pnpm exec final-agents build ./agent
-pnpm exec final-agents publish ./agent --agent my-agent
+export FINAL_API_HOST=https://<agents-api-host>
+export FINAL_API_KEY=<api-key>
+export FINAL_PROJECT_ID=<project-id>
+pnpm exec final-agents print ./agent.ts            # the document, as JSON; calls nothing
+pnpm exec final-agents publish ./agent.ts --name release-scout
 ```
 
-Choose production by changing the host and API key. `--host` overrides
-`FINAL_API_HOST`; without either, the existing production default remains. Build
-compiles locally and optionally checks installed-harness compatibility. Publish
-compiles again and sends source/release requests to the selected deployment.
-Neither rewrites authored URLs. A GitHub-backed definition uses remote source;
-push edits before explicitly publishing a ref. Caller API keys never become agent
-credentials merely because they were used to publish.
-
-## Hosted model resolution (SDK 0.2.0)
-
-Hosted Final, Pi, Codex and Claude configurations accept string model references.
-`serverless*ConfigSchema.parse(...).model` can be undefined: the host must choose
-its catalog default, resolve aliases and validate availability before dispatch.
-The host owns current candidates, runtime capabilities and dated prices, and
-advertises picker choices through its harness descriptions. Compilation remains
-offline and checks reference syntax.
-
-SDK 0.2.0 removes `@finalai/agents/models` and
-`@finalai/final-agent-provider/harnesses/models`, including their model arrays,
-defaults, model-ID unions and pricing helpers. Migrate callers to string model
-references and host-owned discovery, metadata and pricing.
-
-Publish the SDK release before upgrading host dependencies. Ship the host's
-catalog/default implementation together with its SDK dependency upgrade; a host
-that only changes the dependency will lose the old default and catalog APIs.
-
-## Hosted connections
-
-```ts
-import { defineHostedConnection } from '@finalai/agents';
-
-export default defineHostedConnection({
-  binding: 'issue-tracker',
-  tools: { allow: ['read_issue'], deny: ['delete_issue'] },
-});
-```
-
-`issue-tracker` is an example configuration name, not a built-in service.
-Hosting configures it with non-secret JSON:
+`--host` overrides `FINAL_API_HOST`; `--project` overrides `FINAL_PROJECT_ID`.
+`createClient({ host })` selects a deployment the same way. Nothing in an agent
+names a deployment, a server URL or a credential, so the same document runs
+against any host.
+
+## Agents are documents
+
+An agent value (`defineAgent`) becomes its document with `documentOf(agent)`:
+identity, instructions, skills, `require`, workspace seed files, each tool's
+name and schema, hooks, tool policy, secret names and schedules. The agent's
+identity is the content hash of the canonical document with defaults applied
+(`agentDocumentHash` from `@finalai/agent-provider/document`, `sha256:<hex>`).
+Hosts must hash with that function; any other canonicalization yields other
+hashes.
+
+Each tool and hook says where it runs:
+
+- **Serverless** code carries one self-contained ES module (`source`, `export`).
+  It runs on the host's serverless runtime from the document alone, whether or
+  not any client is connected. Hosts re-check that the source imports nothing.
+- **In-process** code carries only its interface. Its body never leaves the
+  process that created the session; the host calls it over that process's
+  local host connection (below). With no such connection the tool reports
+  itself unavailable and the session carries on.
+
+`@finalai/agent-provider/code-host` routes each call by placement
+(`createCodeHost`); the serverless runtime contract is `ServerlessRuntimeIface`.
+A serverless tool gives the model a projection apart from its structured output
+by returning `{ [Symbol.for(SERVERLESS_TOOL_RESULT)]: true, output, modelOutput }`;
+the runtime reads every tool return with `serverlessToolResultOf` and sends
+`modelOutput` on the result line. The model sees `modelOutput` when present,
+and `output` stays the structured result.
+
+Routes, under `/api/v1/projects/:projectId/agents`:
+
+| Route            | Body / query                        | Response                               |
+| ---------------- | ----------------------------------- | -------------------------------------- |
+| `PUT /documents` | `{ document, hash? }`               | `{ hash }`; refuse a hash that differs |
+| `POST /publish`  | `{ name, hash }`                    | `{ id, name, hash, publishedAt }`      |
+| `GET /lookup`    | exactly one of `name`, `id`, `hash` | `agentInfoSchema`                      |
+| `GET /history`   | `name`, `cursor?`, `limit?`         | `agentHistorySchema`                   |
+
+An agent is always passed as an object, `{ hash, document? }`, never a name. A
+request whose document is absent names a hash the host already stores.
+
+## Provide documents
 
 ```json
 {
-  "url": "https://issues.dev.example/mcp",
-  "auth": { "secretKey": "ISSUE_TRACKER_TOKEN", "headerName": null },
-  "headers": { "X-Workspace": "development" }
+  "harness": {
+    "harness": "pi",
+    "configuration": {
+      "model": "gpt-6.1-sol",
+      "inference": [{ "source": "final", "billTo": "project" }]
+    }
+  },
+  "compute": { "files": "asbx_01J…", "shell": "asbx_01J…" },
+  "integrations": { "issues": "intg_01H…" }
 }
 ```
 
-Production supplies another value under the same name. The helper uses an ordinary
-`defineDynamic` connection at `session.started`, then the usual HTTP MCP lowering,
-validation, permissions, and credential broker. Hosting supplies transport settings,
-not tool policies. URL, authentication references, transport headers belong to hosting; the hosted helper does
-not accept authored overrides for these fields. Referenced secrets still need the agent's secret allowlist and normal
-authorization. Actual tokens must not be returned in configuration headers.
+`provideDocumentSchema` (`@finalai/agent-protocol/agent-platform`) is the one
+shape on every call that can start work: `sessions.create`, `conversations.create`
+(per participant, plus a shared document for the conversation), direct and Home
+conversations, `addParticipant`, `PUT …/participants/:pid/provide`, channel
+installs (`agents.provide`) and schedules. It names only things that exist: a
+sandbox or integration by id, harness settings inline. Hosts store it as given
+and resolve participant, then conversation, then the install or schedule that
+created the conversation, taking each top-level key whole from the nearest scope
+that sets it. A conversation returns its shared document as `provide`, so a
+client can run the same check before adding a participant. Nothing has a
+default on the host.
+
+`files` and `shell` must name the same sandbox. A sandbox or integration id
+must belong to the session's project.
+
+## The requirements check
+
+Every call that can start work runs `unmetRequirements` from
+`@finalai/agent-provider/requirements-check` with what the host knows (each
+sandbox's capabilities, which integrations exist, the composed harness via
+`harnessCheckInputOf`, whether a client holding the in-process code is
+connected). If anything is unmet, nothing is created and the response is:
 
-Final uses the same generic helper:
-
-```ts
-import { defineFinalConnection } from '@finalai/agents';
-
-export default defineFinalConnection({
-  tools: { deny: ['create_agent_session'] },
-});
+```json
+{
+  "error": {
+    "code": "requirements_unmet",
+    "message": "…",
+    "details": {
+      "agent": "sha256:…",
+      "requirements": [
+        {
+          "kind": "integration",
+          "name": "issues",
+          "description": "Issue tracker",
+          "problem": "not_provided",
+          "detail": null
+        }
+      ]
+    }
+  }
+}
 ```
 
-This resolves the `final` binding. Hosting supplies its URL and
-`auth: { kind: 'final-session' }`, just as it supplies authentication for any
-other hosted connection. `binding`
-selects another name. Existing explicit `url` calls remain static and compatible;
-they always point at that URL. There is no Final-specific compiler rewrite.
-
-## Connection tool policy
+`harness_unsuitable` has the same body for a harness change refused on its own.
+The SDK runs the same function before sending, so a caller sees the same list
+either way; the SDK error carries `code` and `requirements`
+(`isRequirementsUnmetError`).
+
+A running agent therefore always has what it requires: the host adds nothing to
+its context about requirements. An optional requirement that was not provided is
+simply absent.
+
+## Harnesses, ACP adapters and environments
+
+Three independent pieces reach a model loop, and the host speaks only ACP v2:
+
+- a **harness** definition: the agent program (it need not speak ACP);
+- an **ACP adapter** definition: maps one harness interface to ACP v2, reusable
+  across harnesses; a harness that speaks ACP v2 needs none;
+- an **environment**: a sandbox that runs them, or an ACP v2 endpoint already
+  running at a URL.
+
+Harness settings name them:
+`{ harness, adapter?, configuration, environment? }`. `adapter` defaults to the
+harness definition's. `environment` is a sandbox id (the pair is started
+there), `{ url, hop? }` (nothing is started), or absent: a harness that uses
+`files` or `shell` natively then runs in the sandbox provided for `shell`; any
+other harness is refused.
+
+Definitions are data (`harnessDefinitionSchema`, `acpAdapterDefinitionSchema`
+in `@finalai/agent-provider/harness-definition`), published by name and stored
+by content hash. A harness definition carries its configuration's JSON Schema,
+supported features, `lowestPermission`, accepted inference sources, what it uses
+natively from where it runs (`native.files`, `native.shell`), its interface and
+default adapter, ACP behaviour (`promptWhileRunning`, `sessionSurvivesDisconnect`,
+`supports`, `mcp`, `consumes`), and `run` entries per runtime kind:
+
+- `process`: a command, with arguments and environment derived from the
+  configuration by templates (`{{configuration.model}}`, groups included
+  `when` a value is set). An adapter's process entry wraps the harness's
+  (`{{harness.command}}`, `{ spread: 'harness.args' }`).
+- `worker`: a program built for a worker runtime, by name.
+
+An environment runs what its sandbox provider declares
+(`SandboxEnvironmentImplementationIface.runtimes`: `process`, `worker`; absent
+means `process` when it offers `shell`). A worker runtime is not a machine: it
+offers the model no files or shell, so a harness running there reaches the
+sandboxes provided for them over the handle RPC. `composeHarness` picks a
+runtime kind the environment, the harness and the adapter all have, and
+`harnessCheckInputOf` turns the result into the requirements check's input: a
+harness's native capabilities are its environment's, so only that sandbox may
+be provided for them. `harnessStartFor` renders what to start.
+
+A harness provider (`HarnessProviderIface`, `@finalai/agent-provider/harness-provider`)
+reaches a harness: `open` and `resume` return an ACP endpoint (`ws`, `http`, or
+`sandbox`: a process or worker program the session service starts in the
+environment sandbox over the handle RPC, ACP on its stdio or stream, with no
+port exposed), and `park`, `close` and `health` follow its lifecycle. The
+general provider starts adapter(harness) from the definitions; a definition
+whose harness is reached some other way carries its own provider code
+(`defineHarnessProvider`), one self-contained module run on the serverless
+runtime.
+
+Routes, under `/api/v1/projects/:projectId`:
+
+| Route                                      | Body or query                        | Response                          |
+| ------------------------------------------ | ------------------------------------ | --------------------------------- |
+| `POST /harnesses/check`                    | `{ agent: hash, harness, compute? }` | `harnessCheckResponseSchema`      |
+| `POST /harnesses/publish`                  | `{ name, definition, hash? }`        | `definitionPublicationSchema`     |
+| `GET /harnesses/lookup`                    | `name` or `hash`                     | `harnessDefinitionInfoSchema`     |
+| `GET /harnesses`                           |                                      | `harnessDefinitionListSchema`     |
+| `POST /acp-adapters/publish`               | `{ name, definition, hash? }`        | `definitionPublicationSchema`     |
+| `GET /acp-adapters/lookup`                 | `name` or `hash`                     | `acpAdapterDefinitionInfoSchema`  |
+| `GET /acp-adapters`                        |                                      | `acpAdapterDefinitionListSchema`  |
+| `GET /subscription-allowances`             |                                      | `subscriptionAllowanceListSchema` |
+| `PUT /subscription-allowances/:harness`    | `{}`                                 | `subscriptionAllowanceSchema`     |
+| `DELETE /subscription-allowances/:harness` |                                      | `{ ok }`                          |
+
+The check answers `{ suitable, problems, compute, environment, adapter,
+runtime }`, where `compute[capability].status` is `harness` (its environment
+serves it natively), `sandbox` (a provided sandbox must) or `unavailable`. A
+project can name its own definitions, its ancestors' and the public catalog's.
+A subscription inference source reaches a harness only when the project allows
+that harness, or the public catalog does for its own definitions. The model is
+a string the harness validates; the host never substitutes a default model.
+
+## Sandboxes and setups
+
+Under `/api/v1/projects/:projectId`: `POST /sandboxes` (`{ provider, environment,
+setup?, ownedBy?, idempotencyKey? }`; creating boots nothing), `GET` and
+`DELETE /sandboxes/:id`, `GET /sandboxes/:id/description`, and
+`POST /sandboxes/:id/run` (`{ command, cwd?, env?, timeoutMs? }` →
+`{ exitCode, stdout, stderr }`, booting the sandbox if needed). A sandbox owned
+by a conversation or session is deleted with its owner. A retried create with
+the same `idempotencyKey` returns the first sandbox. Sandbox setups are
+published with `POST /sandbox-setups` (`{ name, setup }`); `latest` resolves once,
+when a sandbox is created.
+
+## Integrations and sign-in
+
+Integrations are project resources: an MCP server and how calls to it
+authenticate (`oauth` personal or shared, `secret` by project secret name,
+`platform-identity`, `none`). A person's own sign-in is runtime state: on the
+first call that needs it, the host raises a `sign_in` decision for that person,
+holds the call, and continues it when `POST /api/v1/sign-ins/complete` succeeds.
+`platform-identity` sends a short-lived signed assertion of the calling session
+that any server can verify against the host's published keys; Final's gateway is
+an ordinary integration with this auth.
+
+### Integration tool policy
+
+A slot's `tools` (`allow`, `deny`, `load`, `allowAnnotations`,
+`denyAnnotations`) and `approvals` are a ceiling over whatever integration fills
+it. Keys are tool names or `*` patterns: `*` matches any run of characters,
+`deny` wins over `allow`, and the most specific key governs (an exact name, else
+the pattern with the most literal characters, ties toward `ask`). Hosts enforce
+this with `isToolExposed`, `isToolLoaded`, `toolApprovalOf` and
+`resolveToolApprovalKey` from `@finalai/agent-provider`.
+
+An annotation selector matches when every hint it sets equals the tool's hint,
+reading omitted hints as the MCP spec's defaults (not read-only, destructive, not
+idempotent, open world). Annotations come from the integration's server, so
+select on them only for servers trusted to classify their own tools.
+
+With `load`, the host lists only the loaded tools and keeps every other exposed
+tool reachable through a search over the integration's remaining tools and a
+call that runs a found tool by its real name, with the same exposure and
+approval checks as a direct call. Without `load`, the host lists every exposed
+tool except tools a server labels with a connector in `_meta`
+(`{ "ai.final/connector": { "namespace": "…", "name": "…" } }`) and tools past
+the host's listing limit, which it searches instead. A harness that declares
+`supports.deferredToolSearch` searches tools itself, so the host lists every
+exposed tool to it.
+
+## Local hosts
+
+A client that starts an agent can lend its own process to it: it serves the
+agent's `files` and `shell` (any it was not given a sandbox for, unless created
+with `localCompute: false`) and answers calls to the agent's in-process tools,
+hooks and approval predicates. It does so over one WebSocket per agent it
+started:
 
-`tools.allow`, `tools.deny` and `tools.approval` keys are tool names or `*`
-patterns, so a definition can scope a connection whose tool list it does not know:
-
-```ts
-export default defineFinalConnection({
-  tools: {
-    allow: ['github.*', 'list_goals'],
-    deny: ['github.delete_repo'],
-    approval: { 'github.delete_*': always() },
-  },
-});
+```
+GET /api/v1/projects/:projectId/local-hosts   (WebSocket upgrade)
+Sec-WebSocket-Protocol: final.local-host.v1
+Authorization: Bearer <the client's credential>
 ```
 
-`*` matches any run of characters; everything else matches literally. `deny` wins
-over `allow`. The most specific key governs a tool: an exact name, else the matching
-pattern with the most literal characters, with ties resolved toward `ask`. Hosts
-enforce this through `isToolExposed` and `toolApprovalOf` from
-`@finalai/agent-provider`, and look up a tool's input-approval predicate under the
-key `resolveToolApprovalKey` returns.
-
-## Loaded and searchable tools
+The socket carries two protocols. Binary frames are always the sandbox handle
+RPC's stream chunks. A text frame belongs to the **host protocol** when it is a
+JSON-RPC request or notification whose method starts with `host/` or `code/`, or
+a response (or `$/cancel_request`) whose id is a string starting with `host:`.
+Every other text frame is the **sandbox handle RPC**
+(`@finalai/agent-provider/sandbox/wire`), in which the host is the RPC client and
+the client process serves the sandbox: the host sends `initialize`,
+`sandbox/readFile`, `sandbox/run` and the rest, with numeric ids, gated by a grant
+of the access the agent requires on the capabilities it serves.
+`splitLocalHostChannel` and `createHostPeer` from `@finalai/agents/client/local-host`
+implement both sides of the split.
 
-A connection that can expose many tools, such as Final's with every service the
-person has connected, can name the ones the harness should list up front:
+**`host/hello`** (client → host, first): the client's id is `host:1`.
 
-```ts
-export default defineFinalConnection({
-  tools: { load: ['list_goals', 'get_goal', 'draft_goal', 'notify_user'] },
-});
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "host:1",
+  "method": "host/hello",
+  "params": {
+    "protocolVersion": 1,
+    "owner": { "kind": "session", "id": "ases_…" },
+    "agent": "sha256:…",
+    "capabilities": ["files", "shell"],
+    "tools": ["find_order"],
+    "hooks": [],
+    "approvals": [],
+    "resume": "lhost_…"
+  }
+}
 ```
 
-With `load`, the host lists only the loaded tools and must keep every other exposed
-tool reachable: it serves a search over the connection's remaining exposed tools
-(name, description, input schema) and a call that runs a found tool by its real
-name, with the same exposure and approval checks as a direct call. A host may
-instead add a found tool to the list and send `notifications/tools/list_changed`;
-harnesses that ignore that notification still need the call path. `load: []`
-leaves every tool to search. Entries are tool names or `*` patterns.
-`isToolLoaded` from `@finalai/agent-provider` applies the rule after exposure.
-
-Without `load`, the harness lists the connection's exposed tools except:
-
-- **Connector tools.** A server can label a tool with the connector it belongs to
-  in the tool's `_meta`:
-  `{ "ai.final/connector": { "namespace": "salesforce", "name": "Salesforce" } }`.
-  The namespace identifies the connector (unique within the server's tools); the
-  name is for display, and two connectors may share one. Final's server labels
-  every connector tool with the namespace and name of the install it comes from.
-  The host never lists labelled tools up front. Its search tool names each
-  connector and how many tools it has, so the agent knows what is connected
-  without any of those definitions in its context, and searches for the tools it
-  needs. A `load` entry that names a labelled tool still lists it.
-- **Tools past a size limit.** When a connection exposes more unlabelled tools
-  than the host lists directly (100 in Final's host), those are searched too.
-
-A harness that declares `supports.deferredToolSearch` defers and searches tools
-itself, so the host lists every exposed tool to it and serves no search.
-
-A host's search should name the connectors it covers and accept a connector's
-namespace to narrow to. Once a host has listed its search and call tools, it keeps answering them for
-that harness even if the connection stops hiding tools, unless the connection
-then lists its own tool by one of those names.
-
-## Selecting tools by annotation
-
-`tools.allow` and `tools.deny` entries can be MCP annotation selectors as well as
-tool names, so a definition can scope tools it cannot name in advance:
-
-```ts
-export default defineFinalConnection({
-  tools: {
-    allow: ['list_goals', 'draft_goal', { readOnlyHint: true }],
-    deny: [{ destructiveHint: true, readOnlyHint: false }],
-  },
-});
-```
+`owner.kind` is `session` or `conversation`; `owner.id` is absent when the
+caller chose no id, and the host reserves one the client then creates with.
+`resume` is a host id from an earlier connection. The result:
 
-A selector matches when every hint it sets equals the tool's hint, reading hints the
-tool omits as the MCP spec's defaults (not read-only, destructive, not idempotent,
-open world). The annotations come from the connection's server, so select on them
-only for servers trusted to classify their own tools.
-
-Selectors lower to `allowAnnotations` (each with the connection default approval and
-input predicate) and `denyAnnotations`. A host exposes a tool when nothing in `deny`
-or `denyAnnotations` matches it and either an `approvals` key (name or pattern)
-governs it, `approvals` is null, or `toolAnnotationRuleFor` finds a rule; a tool an
-`approvals` key governs keeps that approval, otherwise it runs under the rule's. `tools.approval` overrides apply only to
-named tools.
-
-## Resources and provider packages
-
-`HostedBindingsIface` is the shared `@finalai/agent-provider` contract. Hosting
-implements `get(name)` to return scoped JSON or null. `requireHostedBinding` rejects
-missing hosting, absent names, and invalid JSON without an environment fallback.
-Names are configuration keys, not global permissions or inferred URLs.
-
-Tools, hooks, dynamic resolvers, sandbox selectors, and harness/sandbox/channel
-provider contexts expose an optional `bindings` reader. A third-party resolver can
-use the same reader for model or resource configuration:
-
-```ts
-import { defineDynamic, requireHostedBinding } from '@finalai/agents';
-
-export const model = defineDynamic({
-  requiredBindings: [{ name: 'primary-model', schema: { type: 'string', minLength: 1 } }],
-  description: 'The deployment model',
-  preview: 'Resolved from primary-model',
-  events: {
-    'session.started': async (_event, ctx) =>
-      requireHostedBinding({ bindings: ctx.bindings, name: 'primary-model' }),
-  },
-});
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "host:1",
+  "result": {
+    "hostId": "lhost_…",
+    "owner": { "kind": "session", "id": "ases_…" },
+    "sandboxId": "asbx_…"
+  }
+}
 ```
 
-Use that value in a harness configuration supporting dynamic models. A resource
-binding can similarly contain a repository, guide slug, device ID, or non-secret
-SDK base URL; the consumer validates the resource-specific schema. Literal IDs,
-custom URLs, and external credential choices are never silently rewritten.
-
-Installed providers already accept factory configuration injected by hosting.
-Keep supplying deployment service URLs there. Computer/WebSocket clients retain
-explicit configuration; a hosted provider can obtain it through this shared reader.
-Package versions stay pinned. Packages do not read a global DEV/PROD flag.
-
-## Declared requirements and user experience
-
-`defineHostedConnection` declares its binding name and JSON configuration schema
-in the compiled dynamic slot automatically. Other dynamic consumers declare
-`requiredBindings` as in the model example. Hosts can inspect these requirements
-without running authored resolvers. Repeated names must satisfy every declared
-schema; names are looked up once per preflight.
-
-Before accepting a release, hosting calls
-`validateHostedBindings({ manifest, bindings })` with a reader scoped to the
-selected deployment, organization, and agent. Hosts compiling source can instead
-pass `hostedBindings` to `compile`; failed preflight returns error diagnostics and
-no manifest or bundle. An offline build can still compile and expose requirements
-without accessing deployment configuration. The CLI does not yet fetch binding
-configuration itself: server-side publication must enable this preflight.
-
-When dev is selected, lookups use only dev configuration. A missing dev binding
-fails even if production has the same name; never retry against production or
-substitute a production default. Changing the CLI host selects where to publish;
-the runtime reader comes from that deployment, not from the author's environment.
-Explicit authored URLs retain their literal destination.
-
-Authors keep one source definition. Operators configure its named connections
-and resources once in each deployment. End users start the agent as usual; an
-unconfigured required resource produces a configuration failure instead of a
-session silently missing tools. Dynamic handlers validate declared requirements
-before running. Shared manifest resolution rejects null results for required slots,
-even if a host catches a resolver exception and returns null. Hosts must propagate
-that failure to startup. Session-started values stay pinned across turns and resume.
-
-Hosts can use the compiled requirements to show
-which names need configuration and return an actionable deployment-specific error.
+`sandboxId` names this connection's compute in `provide.compute` (one sandbox for
+both capabilities, as the requirements check demands); it is null when the
+client serves no capability. The sandbox belongs to the owner and is deleted
+with it.
+
+**`code/run`** (host → client): params are one code invocation
+(`codeInvocationSchema` from `@finalai/agent-provider/code-host`: `kind` tool,
+hook or approval, the `name` in the document, `input` or `event` and `payload`,
+and a `context` with `sessionId`, `callId`, `actingUserId` and the session's
+compute endpoints for `ctx.sandbox(capability)`). A hook's payload is
+`{ data, meta: { id, at, seq } }`. The result is the final line:
+`{ "type": "result", "output": …, "modelOutput"?: … }` or
+`{ "type": "error", "message": "…" }`; an approval answers `output: true` to
+ask first. While it runs the client sends **`code/progress`** notifications
+`{ "requestId": "host:7", "data": …, "label"?: "…" }`. The host cancels with
+`$/cancel_request { "requestId": "host:7" }`.
+
+**`code/secret`** (client → host): in-process code reading `ctx.secrets.get(name)`
+asks with `{ "requestId": "host:7", "name": "BILLING_TOKEN" }`, where
+`requestId` is the `code/run` it runs for. The host answers
+`{ "value": "…" | null }` (null when the secret is not set). It refuses a name
+the agent's document does not list in `secrets`, a `requestId` that is not a
+`code/run` in flight on this connection, and resolves the name in the project
+of the session or conversation the host serves. The client refuses unlisted
+names itself before asking.
+
+When the socket closes the session carries on. Until a connection resumes it,
+the host reports this process's in-process tools as unavailable
+(`CodeErrorCode.Unavailable`) and its sandbox as unreachable. The SDK's socket
+does not keep a Node process alive, so a script that is done exits and its tools
+become unavailable.
 
 ## Host integration
 
-These packages implement contracts and authored runtime behavior, not a deployment
-configuration store or RPC service. Existing hosting needs to:
-
-1. Resolve names within the authorized deployment, organization, and agent; never
-   expose the process environment or an unrestricted cross-tenant registry.
-2. Inject `bindings` into lifecycle resolution and the tool/hook/selector/provider
-   contexts using it. Dynamic approval evaluation and tool reconstruction after
-   isolate eviction need the same reader. Readers and tokens are not persisted in
-   boundary snapshots.
-3. Configure `final` with that deployment's approved MCP endpoint. The ordinary
-   broker continues restricting `final-session` grants to that endpoint.
-4. Return non-secret configuration and credential references, with normal provider,
-   secret, resource, and organization authorization.
-5. Run the release preflight above and validate again before starting a new
-   session. Treat failed required-binding resolution as a startup/configuration error, not
-   an omitted connection or a fallback to production. Preserve existing runtime
-   revisions when publication fails.
-6. Retain session-started resolved values across turns/resume; resolve new sessions
-   against their own deployment.
-
-Optional readers preserve source compatibility with existing hosts. Definitions
-requesting bindings fail clearly if hosting does not provide them. Installing these
-packages alone does not change Final's deployed service wiring or provision secrets.
-
-New compiles emit manifest version 4. Hosts read versions 2 through 4; older
-channel entries default to no credentials and an empty surface. Upgrade hosting
-before publishing newly compiled agents.
+These packages define contracts and client behaviour, not a platform. A host
+implementing them must:
+
+1. Store documents by `agentDocumentHash`, re-check self-contained serverless
+   source, and point names at hashes only when someone publishes.
+2. Run `unmetRequirements` on every call that starts work and at every session
+   open, and create nothing when it fails.
+3. Store each `provide` as given; never fill a requirement on a caller's behalf.
+4. Route each tool and hook by its placement: serverless code to its runtime with
+   the source from the document, in-process code to the local host that holds it.
+5. Resolve integration auth per call for the acting person, raising sign-in as
+   that integration's auth step.