@intentic/sandbox-contract 1.316.0 → 1.318.0

package/src/contracts/agents.contract.ts

@@ -1,5 +1,5 @@
 import { procedure } from "../protocol/route-meta.js";
-import { AgentToolChildrenSchema, AgentTranscriptSchema } from "../events/transcript.js";
+import { AgentToolChildrenSchema, AgentTranscriptSchema, SessionTranscriptSchema } from "../events/transcript.js";
 import {
     AgentAssignSchema,
     AgentAutoLandSchema,
@@ -15,6 +15,7 @@ import {
     AgentRenameSchema,
     AgentStopJobSchema,
     AgentStopWatchingSchema,
+    AgentSubagentQuerySchema,
     AgentsArchivedSchema,
     AgentSearchQuerySchema,
     AgentSearchResultSchema,
@@ -25,7 +26,6 @@ import {
     LandResultSchema,
 } from "../schemas/agents.js";
 import { AgentsListSchema } from "../schemas/automations.js";
-import { PushFixResultSchema, PushFixSchema } from "../schemas/workspace/push-checks.js";
 import { AgentChangesSchema, AgentConflictsSchema, AgentScratchSchema, AgentHistorySchema } from "../schemas/git/git.js";
 import { FileDiffSchema } from "../schemas/history.js";
 import { OkSchema } from "../schemas/shared.js";
@@ -108,6 +108,17 @@ export const agentsContract = {
         })
         .input(AgentToolChildrenQuerySchema)
         .output(AgentToolChildrenSchema),
+    subagentTranscript: procedure
+        .route({
+            method: "GET",
+            path: "/agents/{id}/subagents/{subagentId}/transcript",
+            summary: "One in-process subagent's own record",
+            description:
+                "What a subagent this conversation's runtime ran in-process said and did, as a transcript of its own: its ask, its thinking, its calls and its words. Read from the runtime's own record of the subagent where it keeps one, which it writes as the subagent works, else from the calls the delegation's card holds in this conversation's record. A subagent spawned as a conversation of its own is read through `transcript` instead.",
+        })
+        .meta({ guest: true })
+        .input(AgentSubagentQuerySchema)
+        .output(SessionTranscriptSchema),
     // Also forgets the provider session, rewind-style, so the next fresh session reads the placed line as the agent's
     // own.
     place: procedure
@@ -283,17 +294,6 @@ export const agentsContract = {
         })
         .input(AgentScratchSchema)
         .output(OkSchema),
-    // The one way an agent is put on what a push left behind: only ever on a press, never by the sandbox itself.
-    pushFix: procedure
-        .route({
-            method: "POST",
-            path: "/agents/push-fix",
-            summary: "Put an agent on what a push left behind",
-            description:
-                "Opens an isolated conversation holding every open finding the project's push checks let through: what each check printed, the command that shows it again, and the commits that brought it. Pressed again while they stand, it continues that conversation.",
-        })
-        .input(PushFixSchema)
-        .output(PushFixResultSchema),
     land: procedure
         .route({
             method: "POST",

package/src/contracts/capabilities.contract.ts

@@ -13,6 +13,7 @@ import {
     CapabilitySchema,
     CapabilitySecretInputSchema,
     CapabilityStatusSchema,
+    SshKeySchema,
 } from "../schemas/capabilities.js";
 import { MarketplaceRequestSchema, MarketplaceSchema } from "../schemas/marketplace.js";
 import { RemoteRefsRequestSchema, RemoteRefsSchema } from "../schemas/git/remote-refs.js";
@@ -22,7 +23,7 @@ import { OkSchema } from "../schemas/shared.js";
 const capabilityRoute = procedure.meta({ floor: "maintainer", control: "never" });
 
 // The sandbox's unified capability manifest, spanning `list`/`add`/`remove`/`status`/`marketplace`. A VAULTED marker
-// with nothing stored behind it is refused rather than silently written.
+// with nothing stored behind it, or a stashed one (`sshKey`) with nothing held, is refused rather than silently written.
 export const capabilitiesContract = {
     list: capabilityRoute
         .route({
@@ -56,6 +57,18 @@ export const capabilitiesContract = {
         .meta({ panel: false })
         .input(CapabilitySchema)
         .output(CapabilityProbeSchema),
+    // The private half waits in the daemon's memory under the token; an add naming it installs the key.
+    sshKey: capabilityRoute
+        .route({
+            method: "POST",
+            path: "/capabilities/ssh-key",
+            summary: "Generate an SSH key for a connection",
+            description:
+                "Makes an ed25519 key pair inside the sandbox and answers with its public half, to authorize on the server, and a one-time token. The private half is never in the answer: it waits in the sandbox until an add sends the token where the private key goes, and lapses if none does within thirty minutes.",
+        })
+        // Mints the credential a later add installs: withheld from the panel token every panel process holds.
+        .meta({ panel: false })
+        .output(SshKeySchema),
     remove: capabilityRoute
         .route({
             method: "DELETE",

package/src/contracts/device.contract.ts

@@ -4,6 +4,7 @@ import { z } from "zod";
 import { DeviceAgentFlowSchema, DeviceFlowLineSchema, DeviceReportSchema, DeviceSandboxFlowSchema } from "../schemas/devices.js";
 import { DeviceScopesSchema } from "../schemas/capabilities.js";
 import { DeviceFactsSchema } from "../schemas/hosts.js";
+import { LoopbackCatchEventSchema, LoopbackCatchSchema } from "../schemas/loopback-catch.js";
 import { OkSchema } from "../schemas/shared.js";
 
 // What a connected device can be asked, over the socket it opened; the machine is the oRPC server, the daemon the
@@ -26,4 +27,8 @@ export const deviceContract = {
     runSandboxFlow: oc.input(DeviceSandboxFlowSchema).output(streamOf(DeviceFlowLineSchema)),
     // Spawns the work detached from the socket, so restarting the agent process cannot brick a swap in progress.
     runAgentFlow: oc.input(DeviceAgentFlowSchema).output(streamOf(DeviceFlowLineSchema)),
+    // Watches one loopback address on this machine for a sign-in's redirect (schemas/loopback-catch.ts); only the
+    // daemon arms it, never a tool, and aborting the stream is how it stops. Sent only to an agent advertising
+    // `loopback-catch`.
+    catchLoopback: oc.input(LoopbackCatchSchema).output(streamOf(LoopbackCatchEventSchema)),
 };

package/src/contracts/endpoints.contract.ts

@@ -34,12 +34,21 @@ export type TrialStatusResponse = z.infer<typeof TrialStatusSchema>;
 export const LocalModelGpuSchema = z.enum(["granted", "unsupported", "absent"]);
 export type LocalModelGpu = z.infer<typeof LocalModelGpuSchema>;
 
+// Which one device a model runs at full speed on: the GPU when one reached this sandbox, else the host's RAM. One, never
+// a sum: a model split between a card and the CPU runs at the CPU's pace.
+export const LocalModelDeviceSchema = z.enum(["gpu", "host"]);
+export type LocalModelDevice = z.infer<typeof LocalModelDeviceSchema>;
+
 // One window rung priced against one model, so a surface never has to redo the arithmetic the start check will.
 const LocalModelWindowFitSchema = z.object({
     tokens: z.number().int().positive(),
     // Weights + KV cache + the runtime's own floor: the same estimate the admission check refuses a start on.
     totalBytes: z.number().int().nonnegative(),
+    // Whether it can load at all, GPU and host together: what a start is refused on.
     fits: z.boolean(),
+    // Whether all of it fits in the free memory of the one device, so it runs at that device's pace. A rung can fit and
+    // still run mostly on the CPU. Absent from a daemon older than the distinction.
+    fullSpeed: z.boolean().optional(),
 });
 
 const LocalModelOptionFitSchema = z.object({
@@ -72,14 +81,21 @@ export const LocalModelFitSchema = z.object({
     memoryCapped: z.boolean(),
     gpu: LocalModelGpuSchema,
     gpuMemoryBytes: z.number().int().nonnegative(),
-    // The budget a start is actually admitted against, not the raw total: a view that sizes against anything else can
-    // recommend a model the daemon then refuses.
+    // The GPU's free memory, on the card with the most of it; zero before the grant. Absent from an older daemon.
+    gpuFreeBytes: z.number().int().nonnegative().optional(),
+    // What a start is refused on: the host and the GPU together, since llama.cpp can split a model between them. Only a
+    // model that cannot load at all is turned away here; a model that fits only this way runs mostly on the CPU.
     budgetBytes: z.number().int().nonnegative(),
+    // What a model may take and still run at full speed: the free memory of one device (fullSpeedDevice), plus whatever
+    // this sandbox's own local model holds there now, since a start stops it first. Both offers are sized against this,
+    // never against the sum. Zero means unmeasurable. Absent from a daemon older than the distinction.
+    fullSpeedBytes: z.number().int().nonnegative().optional(),
+    fullSpeedDevice: LocalModelDeviceSchema.optional(),
     // Whether llama-server is in this image. False means the local lane costs a rebuild before it can serve anything.
     serverReady: z.boolean(),
     options: z.array(LocalModelOptionFitSchema),
     // The two the connect view offers by name. Each is a model plus the window it was priced at, ready to be added
-    // verbatim; absent where nothing on the list fits this machine, which is an answer, not an error.
+    // verbatim, and each runs at full speed; absent where nothing on the list does, which is an answer, not an error.
     instant: z.object({ model: z.string(), context: z.string() }).optional(),
     best: z.object({ model: z.string(), context: z.string() }).optional(),
     prefetch: LocalModelPrefetchSchema,
@@ -114,7 +130,7 @@ export const endpointsContract = {
             path: "/endpoints/local-model/fit",
             summary: "Which local models this machine can actually run",
             description:
-                "The memory this sandbox may use, whether a GPU reached it, and every curated model priced against both, plus the two the connect view offers: one that downloads in a minute and one that is the best this machine can hold. Nothing here is a preference; it is what a start would be admitted or refused on.",
+                "The memory this sandbox may use, whether a GPU reached it, and every curated model priced two ways: whether it fits on one device's free memory and so runs at full speed, and whether it can load at all. The two the connect view offers, one that downloads in a minute and the best this machine runs at full speed, come from the first; a start is refused only on the second.",
         })
         .output(LocalModelFitSchema),
     // Start or stop fetching the instant model's weights before anyone has asked for them, so the first local turn does

package/src/contracts/needs.contract.ts

@@ -0,0 +1,103 @@
+import { procedure } from "../protocol/route-meta.js";
+import { OkSchema } from "../schemas/shared.js";
+import {
+    GrantRevokeSchema,
+    NeedAnswerInputSchema,
+    NeedIdParamSchema,
+    NeedRaisedSchema,
+    NeedRaiseSchema,
+    NeedSchema,
+    NeedSecretInputSchema,
+    NeedsListSchema,
+    NeedsQuerySchema,
+    StandingGrantsSchema,
+} from "../schemas/needs.js";
+
+// Needs (docs/architecture/needs.md): the agent's CLIs raise and withdraw them on the agent token; a person reads and
+// answers them from the chat, the board and the Needs you inbox. Answering is the operating tier's, like the capability
+// and secret routes an answer ends up writing through.
+
+const agentDoor = procedure.meta({ agent: true, control: "never" });
+const answerRoute = procedure.meta({ floor: "maintainer", control: "never" });
+
+export const needsContract = {
+    ask: agentDoor
+        .route({
+            method: "POST",
+            path: "/needs/ask",
+            summary: "Ask a person for something the task needs",
+            description:
+                "Raises a need in the conversation the calling shell belongs to and holds the call up to `wait` seconds for an answer. Answers `met` when it is usable now (or already was), `open` when it is still waiting, and `refused` when nothing was raised or a person declined. An open need's answer reaches the conversation by itself.",
+        })
+        // Held open while the person decides, by design.
+        .meta({ stream: true })
+        .input(NeedRaiseSchema)
+        .output(NeedRaisedSchema),
+    mine: agentDoor
+        .route({
+            method: "GET",
+            path: "/needs/mine",
+            summary: "This conversation's needs",
+            description: "Every need the calling shell's conversation raised, newest first, open or answered.",
+        })
+        .output(NeedsListSchema),
+    withdraw: agentDoor
+        .route({
+            method: "POST",
+            path: "/needs/{id}/withdraw",
+            summary: "Withdraw a need",
+            description: "Closes one of this conversation's open needs because the task no longer needs it. Its card says so.",
+        })
+        .input(NeedIdParamSchema)
+        .output(NeedSchema),
+    list: procedure
+        .route({
+            method: "GET",
+            path: "/needs",
+            summary: "What agents are waiting on people for",
+            description: "Needs across the sandbox, or one conversation's, newest first. Never a secret's value.",
+        })
+        .input(NeedsQuerySchema)
+        .output(NeedsListSchema),
+    answer: answerRoute
+        .route({
+            method: "POST",
+            path: "/needs/{id}/answer",
+            summary: "Answer a need",
+            description:
+                "Declines it, or says yes the way its card offered: accept a connection being set up, apply a change, grant for this conversation or the persona, release a gated credential, approve an environment proposal. A release is refused from anyone the gate does not name.",
+        })
+        .input(NeedAnswerInputSchema)
+        .output(NeedSchema),
+    provideSecret: answerRoute
+        .route({
+            method: "POST",
+            path: "/needs/{id}/secret",
+            summary: "Give a secret a need asked for",
+            description:
+                "Stores the value under the name the need asked for and meets it. The value goes to the sandbox's secret store and nowhere else: not the answer, not the transcript, not a log.",
+        })
+        // Puts a credential in motion: withheld from the panel token.
+        .meta({ panel: false })
+        .input(NeedSecretInputSchema)
+        .output(NeedSchema),
+    grants: answerRoute
+        .route({
+            method: "GET",
+            path: "/needs/grants",
+            summary: "The yeses still standing",
+            description:
+                "What people allowed conversations beyond their persona or area, and the gated credentials released to them, by conversation. Names only, never a value.",
+        })
+        .output(StandingGrantsSchema),
+    revokeGrant: answerRoute
+        .route({
+            method: "POST",
+            path: "/needs/grants/revoke",
+            summary: "Take a yes back",
+            description:
+                "Takes back one grant or one release. The conversation's next turn runs without it; a turn already running keeps what it mounted.",
+        })
+        .input(GrantRevokeSchema)
+        .output(OkSchema),
+};

package/src/contracts/secrets.contract.ts

@@ -7,6 +7,11 @@ import {
     CredentialRequestSchema,
     SecretInventorySchema,
     SecretKeyParamSchema,
+    SecretGeneratedSchema,
+    SecretGenerateSchema,
+    SecretHostGuardSetResultSchema,
+    SecretHostGuardSetSchema,
+    SecretHostGuardsSchema,
     SecretKeysSchema,
     SecretRevealSchema,
     SecretSetSchema,
@@ -16,8 +21,8 @@ import { OkSchema } from "../schemas/shared.js";
 // Credentials are the operating tier's, reads included: maintainer is the highest revokable grant, and no token's.
 const secretRoute = procedure.meta({ floor: "maintainer", control: "never" });
 
-// User-supplied secrets, in the gitignored desired-state/.env; `apply` reloads them, no restart. `inventory` aggregates
-// every store (never values) and always answers; the rest refuse until desired-state is scaffolded. `reveal` alone
+// User-supplied secrets, in the gitignored desired-state/.env once DevOps is active and the sandbox's own store before
+// it; `apply` reloads them, no restart. `inventory` aggregates every store (never values) and always answers. `reveal` alone
 // returns a value, owner-only, POST so the key avoids the URL.
 export const secretsContract = {
     set: secretRoute
@@ -26,10 +31,22 @@ export const secretsContract = {
             path: "/secrets",
             summary: "Store a secret",
             description:
-                "Writes one name and value into the sandbox's own store, where running processes pick it up without a restart. Refused until the sandbox has somewhere to keep them.",
+                "Writes one name and value where the agent's references resolve it, without a restart: desired-state/.env once DevOps is active, the sandbox's own secret store before that.",
         })
         .input(SecretSetSchema)
         .output(OkSchema),
+    generate: secretRoute
+        .route({
+            method: "POST",
+            path: "/secrets/generate",
+            summary: "Make and store a random secret",
+            description:
+                "Makes a random value and stores it under a new name, where `set` would have put it, for a secret nobody has to find or paste (a session key, a signing secret, a password the task sets up itself). Answers the name and its length, never the value. Refused for a name something here already holds.",
+        })
+        // The `secrets generate` CLI, on the agent token: it creates a value, and hands none back.
+        .meta({ agent: true })
+        .input(SecretGenerateSchema)
+        .output(SecretGeneratedSchema),
     list: secretRoute
         .route({
             method: "GET",
@@ -99,6 +116,31 @@ export const secretsContract = {
         })
         .input(CredentialGuardSubjectParamSchema)
         .output(OkSchema),
+    // The host guard, the gate's second half: kept beside the gates, off the agent-editable config for the same reason. The
+    // agent reads it so a use can aim where it may go, and may tighten it; loosening waits for the owner's click.
+    hosts: secretRoute
+        .route({
+            method: "GET",
+            path: "/secrets/hosts",
+            summary: "Which secrets are host-guarded, and where they may go",
+            description:
+                "Every secret and connected account whose host guard is set, on or off, and its hosts. With the guard on, a use aimed off the list, or anywhere a command's text does not show, asks a person first, whatever the safety judge says. Names and hosts only, never values.",
+        })
+        // The `secrets gates` and `secrets hosts` CLI's read, on the agent token.
+        .meta({ agent: true })
+        .output(SecretHostGuardsSchema),
+    setHosts: secretRoute
+        .route({
+            method: "PUT",
+            path: "/secrets/hosts/{subject}",
+            summary: "Turn a secret's host guard on or off, and set its hosts",
+            description:
+                "Replaces one secret's host guard. Anybody who may use secrets can turn it on or take hosts away; turning it off or adding a host is the owner's: from the agent it raises a card for the owner in the live conversation and waits for their answer.",
+        })
+        // The `secrets hosts` CLI's edits, on the agent token; the route itself decides what needs the owner.
+        .meta({ agent: true })
+        .input(SecretHostGuardSetSchema)
+        .output(SecretHostGuardSetResultSchema),
     request: secretRoute
         .route({
             method: "POST",

package/src/contracts/settings.contract.ts

@@ -1,7 +1,10 @@
 import { FIELD_NOTES_FILE } from "@intentic/constants";
 import { procedure } from "../protocol/route-meta.js";
 import {
+    AudienceAnswerSchema,
+    AudienceStateSchema,
     BuiltinPromptSchema,
+    MemberAudienceSchema,
     BuiltinPromptTextSchema,
     FieldNotesStatusSchema,
     REPO_CHECKS_FILE,
@@ -103,6 +106,32 @@ export const settingsContract = {
         })
         .input(TimezoneOfferSchema)
         .output(TimezoneStateSchema),
+    // A person's own preference rather than a sandbox setting: kept per member, so every device a person opens this
+    // sandbox on reads it, and nobody's answer changes another member's screen. Anyone signed in may read and give their
+    // own, a guest included, since it changes nothing but the words they are shown.
+    audience: procedure
+        .route({
+            method: "GET",
+            path: "/settings/audience",
+            summary: "Which words the editor uses for you here",
+            description:
+                "Whether your editor speaks git's own words (developer) or plain ones (maker) on this sandbox, in every browser and on every device. Absent until you have chosen here.",
+        })
+        .meta({ guest: true })
+        .output(MemberAudienceSchema),
+    // A browser handing over the answer it kept on its own must not overwrite one the person already gave on another
+    // device, which is what `offer` says; a plain answer replaces it.
+    setAudience: procedure
+        .route({
+            method: "POST",
+            path: "/settings/audience",
+            summary: "Choose which words the editor uses for you here",
+            description:
+                "Sets whether your editor speaks git's own words (developer) or plain ones (maker) on this sandbox, for every browser and device you open it on. Other members keep their own. With `offer` it is taken only while you have none kept, and the kept answer comes back unchanged.",
+        })
+        .meta({ guest: true, floor: "viewer" })
+        .input(AudienceAnswerSchema)
+        .output(AudienceStateSchema),
     adoptRepoChecks: procedure
         .route({
             method: "POST",

package/src/contracts/system.contract.ts

@@ -1,7 +1,6 @@
 import { procedure } from "../protocol/route-meta.js";
 import { streamOf } from "../protocol/routes.js";
 import { z } from "zod";
-import { SessionTranscriptSchema } from "../events/transcript.js";
 import { SystemEventSchema } from "../events/system-events.js";
 import {
     DeviceAgentFlowInputSchema,
@@ -15,10 +14,10 @@ import { PresenceReportSchema } from "../schemas/logs.js";
 import { SandboxMetricsSchema, StorageCleanInputSchema, StorageCleanResultSchema, StorageReportSchema } from "../schemas/metrics.js";
 import { OkSchema } from "../schemas/shared.js";
 import { DaemonSessionSchema, InfoSchema, ManifestProblemsSchema, ManifestRepairSchema } from "../schemas/system.js";
+import { SkipUpdateInputSchema } from "../schemas/updates.js";
 import {
     BrowserNameParamSchema,
     BrowsersListSchema,
-    SubagentIdParamSchema,
     SubagentsListSchema,
     TerminalNameParamSchema,
     TerminalScrollbackQuerySchema,
@@ -44,6 +43,19 @@ export const systemContract = {
         })
         .meta({ guest: true })
         .output(InfoSchema),
+    // The owner's "not this one" for the update card; /info's `skippedVersion` reads it back.
+    skipUpdate: systemRoute
+        .route({
+            method: "POST",
+            path: "/system/update/skip",
+            summary: "Stop offering one release",
+            description:
+                "Stops offering the named release as an update, typically one this sandbox already tried and went back from. A newer release is offered as usual. Null offers the newest release again.",
+        })
+        // Which version the sandbox runs is the operator's decision, like the update itself.
+        .meta({ floor: "maintainer" })
+        .input(SkipUpdateInputSchema)
+        .output(OkSchema),
     // Own route, not a field on /info: it goes stale on a manifest changing on disk, not on identity changing.
     manifestProblems: systemRoute
         .route({
@@ -214,26 +226,19 @@ export const systemContract = {
         })
         .input(BrowserNameParamSchema)
         .output(OkSchema),
-    // SDK subagents and delegated runs alike; watched via transcript, not a socket, live then from stored history.
+    // In-process and spawned alike: the board draws each under the card of the conversation that started it, and a chat
+    // draws it on the card of the call that started it. Pushed through the `subagents` runtime domain, never polled. A
+    // subagent's work is read where it lives: an in-process one's on its delegation's card in its parent's record, a
+    // spawned one's in its own conversation (agents.transcript), so there is no second transcript door here.
     subagents: systemRoute
         .route({
             method: "GET",
             path: "/system/subagents",
             summary: "Subagents the agents have started",
             description:
-                "Every subagent this sandbox's conversations have delegated work to, whichever tool started it, with what each one is doing.",
+                "Every subagent that conversations the caller can see have delegated work to, whichever tool started it, with what each one is doing: all that are still working, and the most recent that have settled.",
         })
         .output(SubagentsListSchema),
-    subagentTranscript: systemRoute
-        .route({
-            method: "GET",
-            path: "/system/subagents/{id}/transcript",
-            summary: "A subagent's record",
-            description:
-                "The full record of one delegated subagent, in the same shape as any other conversation. It comes live from the parent turn while it works, and from stored history once it has finished.",
-        })
-        .input(SubagentIdParamSchema)
-        .output(SessionTranscriptSchema),
     // On the contract, not a hand-written route beside it: this payload is what every "do it out there" button is
     // gated on, so its shape has to be fingerprinted like any other, or a daemon older than the app disagrees about
     // it silently and the buttons just stop being drawn.

package/src/contracts/translator.contract.ts

@@ -12,7 +12,8 @@ import { OkSchema } from "../schemas/shared.js";
 //
 // Two login shapes ride one pair of routes. Codex, Grok and Kimi use device authorization: the translator polls
 // to completion in the background, so the UI polls the attempt. Google redirects the browser to a loopback
-// URL this sandbox can't receive, so `complete` hands the landing URL to the translator. `connect.flow` tells the
+// URL this sandbox can't receive: a device or browser of the owner's catches it where one can (`connect.catchers`),
+// otherwise `complete` takes the landing URL pasted back; either way it reaches the translator the same way. `connect.flow` tells the
 // card which mechanic it received without inferring it from whether an optional device code happened to exist.
 export const translatorContract = {
     accounts: procedure

package/src/contracts/webext.contract.ts

@@ -2,6 +2,8 @@ import { oc } from "@orpc/contract";
 // Named imports rather than the `z` namespace: this module is bundled into the browser extension, where the
 // namespace keeps zod's 60 locales (~250 kB) that esbuild can otherwise drop. _devices/webext/scripts/size-budget.mjs holds the ceiling.
 import { unknown } from "zod";
+import { streamOf } from "../protocol/stream-of.js";
+import { LoopbackCatchEventSchema, LoopbackCatchSchema } from "../schemas/loopback-catch.js";
 import { OkSchema } from "../schemas/shared.js";
 import { WebExtFactsSchema, WebExtScopesSchema } from "../schemas/webext.js";
 
@@ -9,7 +11,8 @@ import { WebExtFactsSchema, WebExtScopesSchema } from "../schemas/webext.js";
 // inverted from device.contract.ts, since a browser cannot be dialled.
 // `mcp` stays one opaque procedure so a browser can gain a tool without a matching daemon release; the payload is
 // validated in the extension against the tool's own schema.
-// No `runSandboxFlow` twin: every browser operation is a click or read that either happened or did not.
+// No `runSandboxFlow` twin: every browser operation is a click or read that either happened or did not. The one stream
+// is `catchLoopback`, the device agent's own procedure answered the same way, so the daemon drives both alike.
 export const webextContract = {
     // Refetched on connect and each card read, never cached: the grant list changes in the browser, not here.
     describe: oc.output(WebExtFactsSchema),
@@ -19,4 +22,7 @@ export const webextContract = {
     ping: oc.output(OkSchema),
     // One MCP JSON-RPC message forwarded verbatim in both directions; kept opaque, not typed per tool.
     mcp: oc.input(unknown()).output(unknown()),
+    // Watches for a tab reaching one loopback address, a sign-in's redirect (schemas/loopback-catch.ts); armed by the
+    // daemon only, and sent only to a browser whose facts list `loopback-catch`.
+    catchLoopback: oc.input(LoopbackCatchSchema).output(streamOf(LoopbackCatchEventSchema)),
 };

package/src/contracts/workspace.contract.ts

@@ -16,13 +16,6 @@ import {
     WorkspaceGraphSchema,
     WorkspaceSyncSchema,
 } from "../schemas/workspace/workspace-repos.js";
-import {
-    PushChecksSchema,
-    PushDismissResultSchema,
-    PushDismissSchema,
-    PushRecheckResultSchema,
-    PushRecheckSchema,
-} from "../schemas/workspace/push-checks.js";
 import { WorkspaceSearchQuerySchema, WorkspaceSearchResultSchema } from "../schemas/workspace/workspace-search.js";
 import { WorkspaceInstallResultSchema, WorkspaceInstallSchema, WorkspaceSetupSchema } from "../schemas/workspace/workspace-setup.js";
 import {
@@ -283,36 +276,6 @@ export const workspaceContract = {
         })
         .input(WorkspaceInstallSchema)
         .output(WorkspaceInstallResultSchema),
-    // What the pre-push hook found and let through waits here until measured gone or dismissed; with the two hands on it.
-    pushChecks: procedure
-        .route({
-            method: "GET",
-            path: "/workspace/push-checks",
-            summary: "What pushes left behind",
-            description:
-                "Every push the pre-push hook measured, newest first, with what each brought in, and what is still owed per project. The hook never refuses a push, so this is where its findings wait. Nothing here is ever sent to an agent by itself.",
-        })
-        .output(PushChecksSchema),
-    pushDismiss: procedure
-        .route({
-            method: "POST",
-            path: "/workspace/push-checks/dismiss",
-            summary: "Set aside what a push left behind",
-            description:
-                "Marks findings a push check let through as not to be fixed, so they stop counting against the project, or opens dismissed ones again. Nothing is changed in the code.",
-        })
-        .input(PushDismissSchema)
-        .output(PushDismissResultSchema),
-    pushRecheck: procedure
-        .route({
-            method: "POST",
-            path: "/workspace/push-checks/recheck",
-            summary: "Measure what a push left behind again",
-            description:
-                "Runs the project's own push measurement over its main tree now and resolves every open finding it no longer prints. A few seconds; nothing is pushed.",
-        })
-        .input(PushRecheckSchema)
-        .output(PushRecheckResultSchema),
     repos: procedure
         .route({
             method: "GET",

package/src/events/agent-events.ts

@@ -5,6 +5,7 @@ import { LandConflictSchema } from "../schemas/agents.js";
 import { ContextTrimSchema } from "../schemas/context-trim.js";
 import { RateLimitInfoSchema } from "../schemas/providers/claude-gate.js";
 import { FastModeStateSchema } from "../schemas/providers/fast-mode.js";
+import { NeedSchema } from "../schemas/needs.js";
 import { PromptCacheOpeningSchema, PromptFingerprintSchema } from "../schemas/keep-warm.js";
 import { AgentReplySchema, UsageWindowSchema } from "../schemas/providers/plan-limits.js";
 import { SubagentKindSchema, SubagentStatusSchema, SubagentVerificationSchema } from "../schemas/terminal.js";
@@ -37,13 +38,16 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
         remote: z.string().optional(),
     }),
     // After a clean isolated turn's delta lands or not: `landed` puts it uncommitted in the main tree, `conflicts`
-    // names paths that failed, `held` means nothing happened. `deps` covers undeclared dependencies.
+    // names paths that failed, `held` means nothing happened. `deps` covers undeclared dependencies. `into` names the
+    // parent conversation a spawned child's work went into instead of the main tree, as an in-process subagent's edits
+    // go into its parent's checkout.
     z.object({
         kind: z.literal("landed"),
         landed: z.boolean(),
         conflicts: z.array(LandConflictSchema).optional(),
         held: z.boolean().optional(),
         deps: z.object({ missing: z.number(), started: z.array(z.string()), deferred: z.boolean() }).optional(),
+        into: z.string().optional(),
     }),
     // Notes the daemon prepends to the user's message before the model reads it, verbatim, one per note. Serialized
     // from the same typed notes the wire prompt uses, so disclosure cannot drift from what the model got.
@@ -179,6 +183,17 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("account_usage"), account: z.string().optional(), windows: z.array(UsageWindowSchema) }),
     ContextUsageSchema.extend({ kind: z.literal("context_usage") }),
     z.object({ kind: z.literal("compact"), trigger: z.string(), preTokens: z.number().optional(), postTokens: z.number().optional() }),
+    // An agent's own project-dependency install was let through the command gate: where it writes, and which projects
+    // it works on, so the chat says so before its output arrives. Said by every runtime the gate stands in front of.
+    z.object({
+        kind: z.literal("install"),
+        reach: z
+            .enum(["own-copy", "main-tree"])
+            .describe("Where it writes: this conversation's own copy of the tree, or the main tree every conversation reads."),
+        projects: z
+            .array(z.string())
+            .describe("The projects it works on, workspace-relative, the workspace root as an empty string; empty when none could be named."),
+    }),
     // The four interactive cards; each parks the turn until `POST /agent/reply` resolves its `requestId`.
     PlanRequestSchema,
     QuestionRequestSchema,
@@ -206,6 +221,9 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
     // Who released it: `released` names the approver's verified address, `refused` means someone said no. Nothing is
     // pushed for a card nobody answered; `resolved` already says that.
     CredentialReceiptSchema.extend({ kind: z.literal("credential_receipt"), requestId: z.string() }),
+    // Something the agent asked a person for (docs/architecture/needs.md). Parks nothing: the turn carries on, the need
+    // outlives it in the needs store, and its card draws the store's live state by `need.id`.
+    z.object({ kind: z.literal("need"), need: NeedSchema }),
     // The named card is released and the turn resumes; emitted the moment its waiter settles, since nothing else on
     // this stream marks a park's end. `reply` is what a rebuilt transcript freezes the card with.
     z.object({ kind: z.literal("resolved"), requestId: z.string(), reply: AgentReplySchema.optional() }),
@@ -248,6 +266,9 @@ export const AgentEventSchema = z.discriminatedUnion("kind", [
                 // The model cannot hold a turn this size, refused before sending; retrying the same request never
                 // helps.
                 "context-window-too-small",
+                // The model can only write one-shot jobs (Model.helperOnly: its server says it cannot call tools, or
+                // it is the quick-jobs local model), refused before sending; the words wait for another model.
+                "model-helper-only",
                 // The session outgrew the model's context window mid-turn; resuming that session only overflows again,
                 // so the daemon re-runs the turn once in a fresh session carrying the hand-off.
                 "context-overflow",