@intentic/sandbox-contract 1.175.0 → 1.176.0

package/src/host-protocol.ts

@@ -0,0 +1,36 @@
+import { z } from "zod";
+
+/* The handshake on /system/hosts/connect — the ONE message that is not oRPC.
+ *
+ * Everything a connected computer is asked lives in `hostContract` (contracts/host.contract.ts), spoken over
+ * this socket by oRPC's websocket adapter: the machine hosts the server, the daemon holds the client. But a
+ * socket has to prove whose it is before it can be given a typed client, and that proof cannot itself be an
+ * oRPC call — the daemon has nothing to call yet, and would be attaching a link to a stranger.
+ *
+ * So the machine's first act is this frame, in plain JSON. The daemon verifies the token, learns which
+ * capability the socket belongs to, and only then attaches the link; from that message on, every byte on the
+ * wire is oRPC. Anything arriving before the link exists is either this frame or a closed socket. */
+
+// The MCP protocol revision the machine's tool server implements. Shared because the daemon answers the
+// handshake ITSELF when the machine is asleep (hosts/host.routes.ts) — two spellings of this would mean an
+// offline machine negotiating a different protocol than the same machine awake.
+export const MCP_PROTOCOL_VERSION = "2025-06-18";
+
+export const HostHelloSchema = z.object({
+    type: z.literal("hello"),
+    /* The machine's enrollment token — in the FIRST FRAME, never in the URL. A WebSocket has no headers to put
+     * it in, and the obvious `?token=` would write a durable key to somebody's laptop into Cloudflare's edge
+     * logs, the connector's logs and every proxy in between (the reasoning that moved the browser's upgrades
+     * onto one-shot tickets — auth/ws-tickets.ts). A frame is body, not URL, so it is logged nowhere. Until this
+     * arrives the socket is anonymous and short-lived: the daemon closes it in seconds if it never does. */
+    token: z.string(),
+    // The @intentic/host build the machine is running — surfaced per machine so an old binary is visible rather
+    // than mysteriously missing a tool. What the machine IS (`describe`) is not here: it is pulled over the
+    // typed link a moment later, so there is one definition of those facts rather than two.
+    version: z.string(),
+});
+export type HostHello = z.infer<typeof HostHelloSchema>;
+
+// The URL the machine's agent dials, given the sandbox's public URL. Carries no credential — the token rides
+// the hello frame. One place builds it, so the agent and the daemon route can't disagree about where it lives.
+export const hostConnectUrl = (sandboxUrl: string): string => `${sandboxUrl.replace(/^http/, "ws").replace(/\/$/, "")}/system/hosts/connect`;

package/src/index.ts

@@ -10,6 +10,7 @@ import { ciContract } from "./contracts/ci.contract.js";
 import { claudeContract } from "./contracts/claude.contract.js";
 import { codexContract } from "./contracts/codex.contract.js";
 import { draftsContract } from "./contracts/drafts.contract.js";
+import { endpointsContract } from "./contracts/endpoints.contract.js";
 import { extensionsContract } from "./contracts/extensions.contract.js";
 import { geminiContract } from "./contracts/gemini.contract.js";
 import { gitContract } from "./contracts/git.contract.js";
@@ -44,11 +45,15 @@ export { ciContract } from "./contracts/ci.contract.js";
 export { claudeContract } from "./contracts/claude.contract.js";
 export { codexContract } from "./contracts/codex.contract.js";
 export { draftsContract } from "./contracts/drafts.contract.js";
+export { endpointsContract } from "./contracts/endpoints.contract.js";
 export { extensionsContract } from "./contracts/extensions.contract.js";
 export { geminiContract } from "./contracts/gemini.contract.js";
 export { gitContract } from "./contracts/git.contract.js";
 export { grokContract } from "./contracts/grok.contract.js";
 export { historyContract } from "./contracts/history.contract.js";
+/* Deliberately NOT part of `sandboxContract` below: that map is the daemon's own HTTP surface, and this one is
+ * spoken the other way round — over a connected computer's WebSocket, with the MACHINE implementing it. */
+export { hostContract } from "./contracts/host.contract.js";
 export { intenticContract } from "./contracts/intentic.contract.js";
 export { inventoryContract } from "./contracts/inventory.contract.js";
 export { kimiContract } from "./contracts/kimi.contract.js";
@@ -67,12 +72,12 @@ export { translatorContract } from "./contracts/translator.contract.js";
 export { usageContract } from "./contracts/usage.contract.js";
 export { vpnContract } from "./contracts/vpn.contract.js";
 export { workspaceContract } from "./contracts/workspace.contract.js";
-export * from "./effects.js";
 export * from "./events.js";
 export * from "./sse.js";
 export * from "./routes.js";
 export * from "./workspace-state.js";
 export * from "./agent-catalog.js";
+export * from "./host-protocol.js";
 export * from "./hostnames.js";
 export * from "./model-order.js";
 export * from "./path-refs.js";
@@ -95,6 +100,7 @@ export const sandboxContract = {
     claude: claudeContract,
     codex: codexContract,
     drafts: draftsContract,
+    endpoints: endpointsContract,
     extensions: extensionsContract,
     sessions: sessionsContract,
     settings: settingsContract,

package/src/quick-model.test.ts

@@ -86,3 +86,30 @@ test("skips a connected provider whose catalog has not loaded yet", () => {
     expect(resolveQuickModel([unloaded, CLAUDE], ``)).toEqual({ provider: `claude`, model: `claude-haiku-4-5-20251001` });
     expect(resolveQuickModel([unloaded], ``)).toBeUndefined();
 });
+
+/* A MODEL ENDPOINT the user configured is a provider like any other here, and the reason it has to be is the
+ * settings row: its options are built from the same picker catalog, so a pin naming one that this resolver
+ * dropped would print one model's name under the sparkle and spend a different account entirely. */
+const OLLAMA: QuickModelSource = { provider: `endpoint/ollama`, ready: true, models: [`qwen3-coder`, `gemma3-27b`] };
+
+test("honours a pin on a configured endpoint — the whole id, not the half before its slash", () => {
+    expect(resolveQuickModel([CLAUDE, OLLAMA], `endpoint/ollama:qwen3-coder`)).toEqual({ provider: `endpoint/ollama`, model: `qwen3-coder` });
+    // And it round-trips through the key shape the picker mints, which is where the slash-not-colon rule earns
+    // itself: parsePinned splits on the FIRST colon, so an `endpoint:ollama` id would have parsed the provider
+    // as "endpoint" and the model as "ollama:qwen3-coder" — a pin that silently resolves to nothing.
+    expect(quickModelKey({ provider: `endpoint/ollama`, model: `qwen3-coder` })).toBe(`endpoint/ollama:qwen3-coder`);
+});
+
+test("leaves Auto to the providers whose price is known, rather than reaching for someone's own server", () => {
+    // Claude publishes a Haiku-class row; the endpoint's ids carry no tier word at all, so they are UNRANKED and
+    // lose on tier. What a turn on a user's own model API costs is not a fact this repo holds, and Auto should
+    // not be asserting one.
+    expect(resolveQuickModel([CLAUDE, OLLAMA], ``)).toEqual({ provider: `claude`, model: `claude-haiku-4-5-20251001` });
+});
+
+test("still answers from an endpoint when it is the only thing configured", () => {
+    // No tier word in either id, so the shared id-derived ordering decides between them exactly as it does for
+    // Kimi above — the point here is that a sandbox whose only model API is its owner's still gets an answer
+    // rather than the disabled "nothing connected" button.
+    expect(resolveQuickModel([offline(CLAUDE), OLLAMA], ``)).toEqual({ provider: `endpoint/ollama`, model: `qwen3-coder` });
+});

package/src/quick-model.ts

@@ -1,6 +1,6 @@
 import { ACCESS_COST, accessFor, PROVIDERS } from "./agent-catalog.js";
 import { compareCheapestFirst, familyOf, tierRankOf } from "./model-order.js";
-import type { NativeProvider } from "./schemas.js";
+import type { AgentProvider } from "./schemas.js";
 
 /* THE QUICK MODEL — the cheap, fast model a one-click helper spends instead of the frontier model the chat runs
  * on. Today that is the commit box's autofill; anything else of that shape (a branch name, a PR description)
@@ -17,11 +17,19 @@ import type { NativeProvider } from "./schemas.js";
  * this repo's model handling: model-order.ts derives tier and recency from the id and curates nothing, and the
  * web's defaultModelFor reads the live catalog rather than naming an id that a release will falsify. */
 
-// One provider's standing in the decision: whether a turn on it can be sent at all, and what its catalog holds.
-// ACP agents are deliberately not expressible here — an ACP row's model id is empty because the agent owns its
-// own model, so there is no cheap rung to point it at.
+/* One provider's standing in the decision: whether a turn on it can be sent at all, and what its catalog holds.
+ *
+ * ACP agents are deliberately not expressible here — an ACP row's model id is empty because the agent owns its
+ * own model, so there is no cheap rung to point it at. `endpoint/<id>` providers ARE, and have to be: their
+ * models appear in the same picker the settings row builds its options from, so a pin naming one has to hold
+ * rather than fall silently back to Auto and spend an account the user was deliberately steering away from. */
 export interface QuickModelSource {
-    readonly provider: NativeProvider;
+    // AgentProvider, not NativeProvider: an endpoint's id is user-created and cannot be in a fixed union. Auto's
+    // ranking degrades gracefully for one — costOf falls to the metered rung and an id with no tier word is
+    // UNRANKED, which is genuine last place — so an endpoint effectively only wins Auto when nothing else is
+    // connected, while a PIN on one holds. Both are the right answers: what a turn on someone's own model server
+    // costs is not a fact this repo can know, so it is not one Auto should be asserting.
+    readonly provider: AgentProvider;
     // The same connection predicate every other surface gates on (access.ts web-side, the daemon's own account
     // stores daemon-side). A catalog is never empty by construction, so "has rows" says nothing about "can send".
     readonly ready: boolean;
@@ -29,7 +37,7 @@ export interface QuickModelSource {
 }
 
 export interface QuickModelChoice {
-    readonly provider: NativeProvider;
+    readonly provider: AgentProvider;
     readonly model: string;
 }
 
@@ -45,7 +53,7 @@ export const parsePinned = (pinned: string): QuickModelChoice | undefined => {
     if (separator <= 0 || separator === pinned.length - 1) {
         return undefined;
     }
-    return { provider: pinned.slice(0, separator) as NativeProvider, model: pinned.slice(separator + 1) };
+    return { provider: pinned.slice(0, separator), model: pinned.slice(separator + 1) };
 };
 
 // The cheapest row a provider publishes — its whole catalog read from the cheap end. Undefined for a catalog
@@ -59,12 +67,14 @@ const cheapestOf = (source: QuickModelSource): string | undefined => source.mode
 const tierOf = (model: string): number => tierRankOf(familyOf(model));
 
 // PROVIDERS order, as the final tiebreak. Arbitrary, but the SAME arbitrary answer on every read — the property
-// compareUnrankedModelIds exists to guarantee, and the one a default actually needs.
-const providerOrder = (provider: NativeProvider): number => PROVIDERS.findIndex((entry) => entry.value === provider);
+// compareUnrankedModelIds exists to guarantee, and the one a default actually needs. An endpoint is in no fixed
+// list, so it reads -1 and leads the tiebreak; unreachable in practice, since it can never tie on cost.
+const providerOrder = (provider: AgentProvider): number => PROVIDERS.findIndex((entry) => entry.value === provider);
 
-// How much a call on this provider costs at the margin. Every native provider declares an access kind, so the
-// fallback is unreachable — it exists because AgentProvider is a bare string on the wire.
-const costOf = (provider: NativeProvider): number => {
+// How much a call on this provider costs at the margin. Every native provider declares an access kind; an
+// endpoint declares none, and takes the metered rung — the conservative reading of a model API whose bill this
+// repo cannot see, which keeps Auto from reaching for someone's paid gateway on its own initiative.
+const costOf = (provider: AgentProvider): number => {
     const access = accessFor(provider);
     return access === undefined ? ACCESS_COST.key : ACCESS_COST[access.kind];
 };

package/src/schemas.ts

@@ -24,8 +24,10 @@ export const SessionTranscriptMessageSchema = z.object({ role: z.enum(["user", "
 export type SessionTranscriptMessage = z.infer<typeof SessionTranscriptMessageSchema>;
 
 // The agent runtimes the daemon can serve — the vocabulary every surface that picks an agent shares (chat
-// turns, automations). The NATIVE providers have dedicated adapters (and their ids are reserved); any
-// other value is the id of an installed `agent`-kind capability served over ACP (Agent Client Protocol).
+// turns, automations). The NATIVE providers have dedicated adapters (and their ids are reserved); an
+// `endpoint/<id>` value names an installed `endpoint`-kind capability (a model API the user pointed us at,
+// see EndpointConfigSchema); any other value is the id of an installed `agent`-kind capability served over
+// ACP (Agent Client Protocol).
 // Kept as a bare string on the wire (not an enum) so an unknown id is a clean error frame from the agent
 // route — the same bet RepoParamSchema makes — and adding an ACP agent needs no contract change.
 export const NATIVE_PROVIDERS = ["claude", "codex", "grok", "kimi", "gemini"] as const;
@@ -925,24 +927,45 @@ export const SavingsArmSchema = z.object({ turns: z.number(), mean: z.number() }
  * appends, so it belongs to neither arm.
  *
  * `metric` says what `mean` counts and what `deltaPct` is a delta in. The terse steer is judged on the model's
- * OWN output tokens, which is the thing it steers. Pre-injection is judged on COST, because it spends input
- * tokens deliberately to buy back search turns — scored on output tokens it would look like a pure expense,
- * and scored on input tokens like a pure loss; the trade only nets out in money. */
+ * own PROSE, which is the thing it steers and the only part of its output that responds to being asked to be
+ * brief (see UsageTurn.proseChars for why the turn's total output tokens cannot answer this). Pre-injection is
+ * judged on COST, because it spends input tokens deliberately to buy back search turns — scored on output
+ * tokens it would look like a pure expense, and scored on input tokens like a pure loss; the trade only nets
+ * out in money. */
 export const TurnExperimentSchema = z.object({
-    metric: z.enum(["outputTokens", "costUsd"]),
+    metric: z.enum(["proseChars", "costUsd"]),
     on: SavingsArmSchema,
     off: SavingsArmSchema,
+    /* How much of the treatment arm the treatment actually REACHED, when that is knowable and less than all of
+     * it — pre-injection's arm is the coin flip (intention-to-treat, deliberately), and a turn can be assigned
+     * the retrieval and still have nothing to prepend. Measured at four turns in five, which is the difference
+     * between a mechanism worth little and one worth five times what the delta says.
+     *
+     * Absent ⇒ delivery is not a separate question for this experiment (the terse steer always lands) or no
+     * turn in the window recorded it. The screen shows the delta as diluted rather than silently scaling it:
+     * the correction is a division by a rate this small only when the rate is itself well measured. */
+    deliveredPct: z.number().optional(),
     // Turns per arm before a delta is reported at all. Carried on the wire so the screen's "measuring…" state
     // counts toward the daemon's real threshold instead of a number the browser guessed.
     minTurns: z.number(),
-    /* The three below are present TOGETHER, and only once both arms clear `minTurns` — a schema that can't
-     * express a half-measured experiment is how a 34%-that-becomes-8%-tomorrow never reaches the screen.
-     *   deltaPct  — change in the metric's mean per turn under the mechanism; negative is a saving.
-     *   marginPct — ± percentage points, 95% (Welch, unequal variances and unequal arms).
-     *   saved     — what the delta is worth over the turns that actually ran with it, in this window, in the
-     *               metric's own unit (tokens, or dollars). */
-    deltaPct: z.number().optional(),
+    /* THE RESOLUTION, present as soon as both arms clear `minTurns`: ± percentage points at 95% (Welch,
+     * unequal variances and unequal arms). Present even when the delta below is withheld, because "whatever
+     * this mechanism does, it is smaller than ±35 points" is a true and useful thing to be told — it is the
+     * reading that says to keep collecting rather than to act. */
     marginPct: z.number().optional(),
+    /* THE CLAIM, present only once there is one. Both together, and only when the margin does NOT span zero.
+     *
+     * A schema that can't express a half-measured experiment is how a 34%-that-becomes-8%-tomorrow never
+     * reaches the screen — and clearing `minTurns` turned out not to be enough to buy that. The terse steer
+     * crossed its thirtieth control turn and immediately reported +31.2% ± 35.1pp: a confidence interval
+     * running from −3.4% to +66.7%, which is to say no effect was measured at all, rendered as an alarming
+     * number pointing the wrong way. Thirty turns is where the normal approximation starts to hold, not where
+     * this much per-turn spread resolves an effect; requiring the interval to exclude zero is the same
+     * withhold-until-it-means-something rule applied to the thing that actually decides whether it does.
+     *   deltaPct — change in the metric's mean per turn under the mechanism; negative is a saving.
+     *   saved    — what the delta is worth over the turns that actually ran with it, in this window, in the
+     *              metric's own unit (characters, or dollars). */
+    deltaPct: z.number().optional(),
     saved: z.number().optional(),
 });
 export type TurnExperiment = z.infer<typeof TurnExperimentSchema>;
@@ -963,17 +986,21 @@ export const IntenticRunSchema = z.object({ args: z.array(z.string()) });
 
 // ---- git ----
 
-// What a commit records — two shapes, each a real git spelling:
-//   all: true   ⇒ stage every change in the repo, then commit (`commit -a`; VSCode's "stage all and commit")
+// What a commit records — three shapes, each a real git spelling. The last two are for the case where nothing
+// is staged yet and the caller has said what to stage; they are alternatives, and a caller sends at most one:
 //   absent      ⇒ commit whatever is staged (plain `git commit`)
+//   all: true   ⇒ stage every change in the repo, then commit (`commit -a`; VSCode's "stage all and commit")
+//   paths       ⇒ `git add` those repo-relative paths, then commit the index
 //
-// There is deliberately no `paths`. The index IS git's mechanism for choosing what a commit contains, so a
-// second path-selection channel alongside it can only disagree with it: a `commit --only` over a partially
-// staged file records the WORKTREE content while the row the user picked showed the INDEX content. Staging is
-// the selection; this endpoint only ever records it.
+// `paths` is emphatically NOT `commit --only`. The index IS git's mechanism for choosing what a commit
+// contains, so a second path-selection channel alongside it could only disagree with it: a partial commit over
+// a half-staged file records the WORKTREE content while the row the user picked showed the INDEX content. This
+// stages and then records the whole index, which is why it is safe — and why it also survives a merge, where
+// git refuses a partial commit outright (and refuses it only AFTER moving the index).
 export const CommitSchema = RepoParamSchema.extend({
     message: z.string().min(1),
     all: z.boolean().optional(),
+    paths: z.array(z.string().min(1)).max(500).optional(),
 });
 export const DiscardSchema = RepoParamSchema.extend({
     // Repo-relative paths to discard; absent ⇒ discard every uncommitted change in the repo.
@@ -1002,13 +1029,21 @@ export const GitFilesSchema = z.object({ files: z.array(z.string()) });
 export const GitFileSchema = z.object({ path: z.string(), content: z.string() });
 export const CommitResultSchema = z.object({ committed: z.boolean() });
 
+// One repo's slice of a workspace-wide git action: the whole repo, or only the repo-relative paths named. The
+// same pair the per-repo routes take as {repo} + `paths`, in the one shape a caller that spans repos can send.
+export const RepoPathsSchema = z.object({ repo: z.string().min(1), paths: z.array(z.string().min(1)).max(500).optional() });
+export type RepoPaths = z.infer<typeof RepoPathsSchema>;
+
 /* AI-drafted commit message. Workspace-wide, not per repo, because the commit box's target IS a set of repos
  * sharing one message — so the draft has to see every one of their diffs to describe what the commit actually
- * records. `repos` and `all` mirror the panel's own commit target exactly: `all` reads the WORKTREE (what
- * "Commit all" would sweep), absent reads the INDEX (what a bare commit records). Getting that wrong would
- * describe changes the commit isn't going to contain. */
+ * records. The input mirrors CommitSchema field for field, which is the whole point: whatever the commit is
+ * about to do is what gets described, and the two cannot drift.
+ *   repos[].paths ⇒ the subset that commit will stage — read the WORKTREE, narrowed to those paths
+ *   all: true     ⇒ the whole worktree, untracked included (what "Commit all" sweeps)
+ *   neither       ⇒ the INDEX (what a bare commit records)
+ * Getting that wrong would describe changes the commit isn't going to contain. */
 export const CommitMessageDraftSchema = z.object({
-    repos: z.array(z.string().min(1)).min(1).max(50),
+    repos: z.array(RepoPathsSchema).min(1).max(50),
     all: z.boolean().optional(),
 });
 // The draft plus WHICH model wrote it, so the surface can name it rather than claiming an anonymous "AI" —
@@ -1604,6 +1639,16 @@ export const WorkspaceDepEdgeSchema = z.object({ from: z.string(), to: z.string(
 export type WorkspaceDepEdge = z.infer<typeof WorkspaceDepEdgeSchema>;
 export const WorkspaceGraphSchema = z.object({ packages: z.array(WorkspacePackageSchema), edges: z.array(WorkspaceDepEdgeSchema) });
 export type WorkspaceGraph = z.infer<typeof WorkspaceGraphSchema>;
+// One module a changed file can be grouped under in the review panels: a repo-relative dir ("_apps/web", or ""
+// for a repo that is itself one package) and the name its package.json declares. Distinct from
+// WorkspacePackage, which is the DEPENDENCY graph's node — that one is pnpm's view of the workspace and carries
+// the grouping axis its diagram colours by; this one is a filesystem fact about where a path lives.
+export const WorkspaceModuleSchema = z.object({ dir: z.string(), name: z.string() });
+export type WorkspaceModule = z.infer<typeof WorkspaceModuleSchema>;
+export const RepoModulesSchema = z.object({ repo: z.string(), modules: z.array(WorkspaceModuleSchema) });
+export type RepoModules = z.infer<typeof RepoModulesSchema>;
+export const WorkspaceModulesSchema = z.object({ repos: z.array(RepoModulesSchema) });
+export type WorkspaceModules = z.infer<typeof WorkspaceModulesSchema>;
 // Path params for the per-repo apps routes: the monorepo name (validated in the handler like PanelRepoParam)
 // and, for per-app preview control (start/stop), the app key (api/web/landing).
 export const RepoAppsParamSchema = z.object({ repo: z.string() });
@@ -1700,7 +1745,9 @@ export const CapabilityKindSchema = z.enum([
     "vpn",
     "docker",
     "browser",
+    "host",
     "agent",
+    "endpoint",
 ]);
 export type CapabilityKind = z.infer<typeof CapabilityKindSchema>;
 export const CapabilityStateSchema = z.enum(["active", "pending", "error", "inactive"]);
@@ -1868,6 +1915,43 @@ export const VpnConfigSchema = z.discriminatedUnion("provider", [WireguardVpnCon
 // Dockerfile fragment, applied on an owner rebuild. One capability = one platform (the id doubles as the profile).
 export const BrowserPlatformSchema = z.enum(["reddit", "x", "youtube"]);
 export const BrowserConfigSchema = z.object({ platform: BrowserPlatformSchema });
+/* A connected COMPUTER of the user's own — the inverse of `ssh`, which reaches a server the sandbox can dial.
+ * A machine behind NAT can't be dialled, so it dials US: the @intentic/host agent (installed by a one-liner,
+ * enrolled with a single-use pairing token) holds one outbound WebSocket to this daemon and serves an MCP tool
+ * surface — shell, files, screenshots — from the far end. The daemon tunnels the agent's JSON-RPC over it and
+ * never implements a tool itself, so the machine's capabilities evolve with ITS binary, not with a daemon release.
+ *
+ * One capability = one machine. The id is the machine's name and namespaces its tools (mcp__laptop__run_command),
+ * so several connected machines never collide — the `ssh` precedent. `platform` splits the SKILL pack: a Windows
+ * machine is taught PowerShell and a Linux one systemd/D-Bus, and neither carries the other's noise.
+ *
+ * SCOPES ARE THE GRANT, and they are enforced ON THE MACHINE, never here: the daemon pushes them down on every
+ * connect, and the agent refuses out-of-scope calls itself. So a sandbox that is compromised — or an agent talked
+ * into it by something it read on the internet — still cannot exceed what the owner ticked. `roots` bounds file
+ * reads AND writes to a set of directories (empty ⇒ the user's home). */
+export const HostPlatformSchema = z.enum(["windows", "linux"]);
+export type HostPlatform = z.infer<typeof HostPlatformSchema>;
+// on/off rather than a boolean: capability configs arrive from the add form as strings (the vpn autoConnect
+// precedent), and a select is what the form renders for an enum.
+const hostScope = z.enum(["on", "off"]);
+export const HostScopesSchema = z.object({
+    // Run commands in a real shell (PowerShell on Windows, the login shell on Linux). Off ⇒ files/screen only.
+    shell: hostScope.default("on"),
+    // Create, modify and trash files under `roots`. Reads are always allowed within them; this is the write half.
+    write: hostScope.default("off"),
+    // Capture the screen. Off ⇒ screenshot refuses, and the agent is told so rather than getting a black frame.
+    screen: hostScope.default("on"),
+    /* Move the pointer, click, type and scroll — GUI work, for the things with no command-line way in. Its own
+     * switch rather than part of `screen` because looking and touching are not the same permission: a screenshot
+     * is bounded by what is on the display, while one click can confirm a dialog nobody read. Default off, like
+     * `write`, and for the same reason — a user who has not thought about it should not discover the agent has
+     * been driving their desktop. */
+    control: hostScope.default("off"),
+    // One directory per line. Empty ⇒ the machine's home directory, which is what the agent reports at connect.
+    roots: z.string().optional(),
+});
+export type HostScopes = z.infer<typeof HostScopesSchema>;
+export const HostConfigSchema = HostScopesSchema.extend({ platform: HostPlatformSchema });
 // An ACP (Agent Client Protocol) agent served as a chat provider: the daemon spawns `command` as a long-lived
 // subprocess speaking JSON-RPC over stdio, and the capability id becomes the provider id in the chat picker
 // (see AgentProviderSchema). `command` is split on whitespace — no shell quoting. `env` is a pasted KEY=VALUE
@@ -1881,6 +1965,36 @@ export const AcpAgentConfigSchema = z.object({
     env: z.string().optional(),
     loginCommand: z.string().min(1).optional(),
 });
+
+/* A MODEL API THE USER POINTED US AT — one shape for every server that serves models over HTTP, whether it runs
+ * beside this container or in another datacentre. There is deliberately NO local/remote axis: an Ollama on the
+ * docker host, a vLLM on the GPU box down the hall, a LiteLLM gateway and OpenRouter differ only in the URL, and
+ * inventing a distinction would mean two code paths, two cards and two sets of bugs for one concept.
+ *
+ * `protocol` is the only real fork, and it is about the WIRE, not about where the server lives:
+ *   openai    — the endpoint speaks OpenAI /v1/chat/completions (Ollama, vLLM, llama.cpp, LM Studio, TGI,
+ *               OpenRouter, most gateways). The Claude Code harness speaks only the Anthropic Messages API, so
+ *               these are re-served through the bundled translator, which is already in the image for exactly
+ *               this job (agent/translator.ts). The user's key stays in the translator's config on /history and
+ *               never reaches the harness — it gets the loopback bearer instead.
+ *   anthropic — the endpoint already speaks the Anthropic Messages API (LiteLLM's /v1/messages, a Bedrock or
+ *               Vertex router, a corporate Anthropic gateway). Nothing to translate: the harness is pointed
+ *               straight at it with the user's own key.
+ *
+ * `headers` is a pasted `Name: value` block, one per line — the extra headers gateways ask for (a tenant id, a
+ * routing hint). The key is the secret field; the header block is not, because it is where non-credential
+ * routing metadata lives and hiding it would make a misrouted endpoint undiagnosable. */
+export const EndpointProtocolSchema = z.enum(["openai", "anthropic"]);
+export type EndpointProtocol = z.infer<typeof EndpointProtocolSchema>;
+export const EndpointConfigSchema = z.object({
+    // The API root, INCLUDING the version segment the server publishes (…:11434/v1). Taken verbatim rather than
+    // normalised: "which suffix does this server want" is the one thing that actually varies between them, and
+    // guessing it is how a working URL becomes an unexplainable 404.
+    baseUrl: z.string().url(),
+    protocol: EndpointProtocolSchema.default("openai"),
+    apiKey: z.string().optional(),
+    headers: z.string().optional(),
+});
 export type McpConfig = z.infer<typeof McpConfigSchema>;
 export type ServiceConfig = z.infer<typeof ServiceConfigSchema>;
 export type IntegrationConfig = z.infer<typeof IntegrationConfigSchema>;
@@ -1894,7 +2008,9 @@ export type IpsecVpnConfig = z.infer<typeof IpsecVpnConfigSchema>;
 export type VpnConfig = z.infer<typeof VpnConfigSchema>;
 export type BrowserPlatform = z.infer<typeof BrowserPlatformSchema>;
 export type BrowserConfig = z.infer<typeof BrowserConfigSchema>;
+export type HostConfig = z.infer<typeof HostConfigSchema>;
 export type AcpAgentConfig = z.infer<typeof AcpAgentConfigSchema>;
+export type EndpointConfig = z.infer<typeof EndpointConfigSchema>;
 
 export const CapabilitySchema = z.discriminatedUnion("kind", [
     z.object({ id: entryId, kind: z.literal("devops"), config: z.object({}) }),
@@ -1916,7 +2032,12 @@ export const CapabilitySchema = z.discriminatedUnion("kind", [
     // state (/var/lib/docker) and whatever runs on it make a silent de-privilege more destructive than useful.
     z.object({ id: entryId, kind: z.literal("docker"), config: z.object({}) }),
     z.object({ id: entryId, kind: z.literal("browser"), config: BrowserConfigSchema }),
+    z.object({ id: entryId, kind: z.literal("host"), config: HostConfigSchema }),
     z.object({ id: entryId, kind: z.literal("agent"), config: AcpAgentConfigSchema }),
+    // A model API (EndpointConfigSchema). The id becomes `endpoint/<id>` in the chat picker — the `agent` kind's
+    // precedent, with the prefix because these two are the only capability kinds that mint providers and they
+    // want opposite ability records (an ACP agent owns its own loop; an endpoint runs the full Claude Code one).
+    z.object({ id: entryId, kind: z.literal("endpoint"), config: EndpointConfigSchema }),
 ]);
 export type Capability = z.infer<typeof CapabilitySchema>;
 
@@ -1951,6 +2072,44 @@ export const CapabilitySecretInputSchema = z.object({ id: z.string(), value: z.s
 // which the web surfaces in the terminal panel for the user to complete the sign-in.
 export const CapabilityLoginSchema = z.object({ session: z.string() });
 
+// ---- hosts: the user's own connected computers (the `host` capability's live half) ----
+// The manifest says which machines the user INTENDS to have connected; this says which are actually holding a
+// socket right now. Nothing here is remembered across a daemon restart except the enrollment itself: a machine
+// is "online" exactly while its WebSocket is attached, so a laptop that closed its lid reads as offline within
+// a heartbeat rather than staying green until someone asks it to do something.
+
+// What a machine reports about itself once, at connect (the agent's own `host.describe`, cached until it
+// reconnects). It is the difference between an agent guessing what is on the box and knowing: the SKILL pack
+// tells it HOW to drive Windows, this tells it WHICH Windows this is.
+export const HostFactsSchema = z.object({
+    // The OS's own name for itself — "Windows 11 Pro 24H2", "Ubuntu 24.04.1 LTS".
+    os: z.string(),
+    arch: z.string(),
+    // The shell run_command actually spawns, so the agent writes for the right one from its first command.
+    shell: z.string(),
+    // The machine's home directory, and the default root when the capability declares none.
+    home: z.string(),
+    // Roots in force right now (the capability's `roots`, or [home]) — the agent sees its own boundary.
+    roots: z.array(z.string()),
+});
+export type HostFacts = z.infer<typeof HostFactsSchema>;
+
+export const HostSummarySchema = z.object({
+    // The capability id — the machine's name, and the prefix of its tools (mcp__<id>__run_command).
+    id: z.string(),
+    platform: HostPlatformSchema,
+    online: z.boolean(),
+    // The agent binary's version, so a machine running an old build is visible rather than mysteriously lacking
+    // a tool. Absent until the machine has connected once.
+    version: z.string().optional(),
+    // Epoch ms of the last time this machine held a socket. Absent ⇒ it has not connected since this daemon
+    // booted — liveness is a fact about a socket, so a restart forgets it rather than claiming stale uptime.
+    lastSeen: z.number().optional(),
+    facts: HostFactsSchema.optional(),
+});
+export type HostSummary = z.infer<typeof HostSummarySchema>;
+export const HostsListSchema = z.object({ hosts: z.array(HostSummarySchema) });
+
 // ---- vpn: live tunnel state + connect/disconnect ----
 // The manifest says which VPNs EXIST; this says which are UP right now. Every field is read back from the OS
 // (wg show / ip / openconnect's pidfile / swanctl), never remembered by the daemon — so a tunnel the agent
@@ -3187,6 +3346,35 @@ export const UsageTurnSchema = z.object({
      * would sort turns by how searchable their question was, which is a property of the question. The control
      * arm contains the same unsearchable questions in the same proportion, so they cancel. */
     iqContext: z.boolean().optional(),
+    /* Whether a note was actually PREPENDED on this turn — the companion to `iqContext`, and the answer to the
+     * question that field's design deliberately refuses to answer.
+     *
+     * Keeping the arm on the coin flip is right, and it costs something: the treatment arm contains turns the
+     * treatment never reached, so the delta it yields is diluted by however many those are. Measured over one
+     * day that was four turns in five, which makes the difference between "this mechanism is worth little" and
+     * "this mechanism is worth five times what the number says" — and nothing in the ledger could tell them
+     * apart, because a treated turn and an untreated one in the same arm looked identical.
+     *
+     * So the arm stays intention-to-treat and this records delivery beside it. Together they give both the
+     * unbiased estimate and the rate to divide it by; alone, either one misleads. Absent ⇒ outside the
+     * experiment, exactly as for the arm. */
+    iqContextNote: z.boolean().optional(),
+    /* Characters of the model's own PROSE this turn — the `delta` frames only, so no tool-call arguments and no
+     * thinking. What the terse steer is judged on, and the reason it can be judged at all.
+     *
+     * `outputTokens` cannot serve: measured over a day of real turns it is 91.6% tool-call arguments (an Edit's
+     * old_string and new_string, a Write's whole file body) and 7.8% prose. The steer moves prose. So a fifth
+     * off the model's narration moves the total by 1.6% — against a margin of ±35 points, which is to say the
+     * experiment was structurally unable to see its own treatment, and the number it printed instead was
+     * whichever arm happened to draw the bigger tasks.
+     *
+     * CHARACTERS, not tokens, because the provider bills a total and never breaks it down — a token figure here
+     * would be chars÷4 wearing a unit it had not earned. For a comparison of two arms the constant cancels
+     * anyway, and the honest unit is the one actually counted.
+     *
+     * Absent ⇒ the turn predates this being measured; `armOf` drops it from the population rather than reading
+     * it as a silent turn. */
+    proseChars: z.number().optional(),
 });
 export type UsageTurn = z.infer<typeof UsageTurnSchema>;
 

package/dist/effects.d.ts

@@ -1,42 +0,0 @@
-import type { ConnectorContribution, ExtensionManifest } from "@intentic/extension-api";
-import type { CapabilityKind } from "./schemas.js";
-export type CapabilityEffect = {
-    readonly kind: "skill";
-    readonly name?: string | undefined;
-} | {
-    readonly kind: "secret";
-    readonly exposure: "agent-env" | "disk";
-} | {
-    readonly kind: "clone";
-    readonly url?: string | undefined;
-} | {
-    readonly kind: "image";
-} | {
-    readonly kind: "runtime";
-    readonly level: "net-admin" | "privileged";
-} | {
-    readonly kind: "process";
-    readonly names: readonly string[];
-} | {
-    readonly kind: "mcp";
-} | {
-    readonly kind: "scaffold";
-    readonly repos: readonly string[];
-} | {
-    readonly kind: "deploy";
-    readonly provisions: boolean;
-} | {
-    readonly kind: "trusted-code";
-} | {
-    readonly kind: "profile";
-    readonly platform: string;
-};
-export interface CapabilityEffectInput {
-    readonly kind: CapabilityKind;
-    readonly id?: string | undefined;
-    readonly config: Record<string, string | number | boolean | undefined>;
-    readonly connector?: ConnectorContribution | undefined;
-    readonly manifest?: ExtensionManifest | undefined;
-}
-export declare const capabilityEffects: (input: CapabilityEffectInput) => readonly CapabilityEffect[];
-//# sourceMappingURL=effects.d.ts.map

package/dist/effects.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"effects.d.ts","sourceRoot":"","sources":["../src/effects.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACxF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAUnD,MAAM,MAAM,gBAAgB,GAGtB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GAG9D;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,CAAA;CAAE,GAEpE;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GAE7D;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAG1B;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,YAAY,CAAA;CAAE,GAExE;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAE/D;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;CAAE,GAExB;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAEhE;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;CAAE,GAEzD;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAAE,GAEjC;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9D,MAAM,WAAW,qBAAqB;IAClC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAE9B,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAEjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;IAEvE,QAAQ,CAAC,SAAS,CAAC,EAAE,qBAAqB,GAAG,SAAS,CAAC;IAEvD,QAAQ,CAAC,QAAQ,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;CACrD;AAOD,eAAO,MAAM,iBAAiB,UAAW,qBAAqB,KAAG,SAAS,gBAAgB,EAkFzF,CAAC"}