@intentic/sandbox-contract 1.310.0 → 1.312.0

package/src/chores/fix-deps.ts

@@ -13,10 +13,11 @@ export const FIX_DEPS_AUTOMATION = {
         "A landed change drifted this workspace's dependencies; the daemon reinstalled them and ran the project's own checks, " +
         "and they failed. The payload names the project (`deps.project`), the check command (`deps.command`), how it exited " +
         "(`deps.exitCode`) and the tail of its output (`deps.logTail`); the full log is in the project's `--verify` terminal.\n\n" +
-        "Re-run the check yourself to see the failure first-hand, then fix the ROOT CAUSE. That usually means updating call " +
+        "Re-run only what failed to see it first-hand (the failing package's tests or typecheck, not the whole check command), then fix the ROOT CAUSE. That usually means updating call " +
         "sites, types or tests to match what actually changed: never loosening or deleting the checks, pinning or downgrading " +
         "dependencies just to silence them, or editing generated files. If the breakage needs a decision only the owner can " +
         "make (an intentional breaking upgrade, a license change, a dependency that should be dropped), stop and say exactly " +
         "that instead of guessing.\n\n" +
-        "Finish by running the same check command and reporting what was broken, what you changed, and whether it is green now.",
+        "Finish by re-running what failed and reporting what was broken, what you changed, and whether it passes now; the " +
+        "daemon runs the whole check again once your fix lands.",
 } as const;

package/src/chores/prompt.ts

@@ -26,8 +26,9 @@ export const TRIAGE_NOTE =
 // Constraints for a change-making turn: every change must be explainable on its own line of the summary.
 export const CHORE_INVARIANTS =
     `Keep it mechanical and separately explainable: nothing lands that you could not justify on its own line of the ` +
-    `summary. Do not reformat, rename or "while I was in here" anything the finding did not name. Run the repository's ` +
-    `own type-check and tests before you finish, and if you cannot make them pass, leave the change out and say so.`;
+    `summary. Do not reformat, rename or "while I was in here" anything the finding did not name. Before you finish, run ` +
+    `the type-check and tests of what you changed (its package, the test files that cover it), not the whole ` +
+    `repository's; if you cannot make them pass, leave the change out and say so.`;
 
 // Constraints for a look-only turn, stated explicitly so a report chore never quietly starts editing.
 export const REPORT_INVARIANTS =

package/src/contracts/agents.contract.ts

@@ -1,7 +1,6 @@
 import { procedure } from "../protocol/route-meta.js";
 import { AgentToolChildrenSchema, AgentTranscriptSchema } from "../events/transcript.js";
 import {
-    AgentArchiveSchema,
     AgentAssignSchema,
     AgentAutoLandSchema,
     AgentBreakPolicySchema,
@@ -14,6 +13,7 @@ import {
     AgentPlaceSchema,
     AgentReactSchema,
     AgentRenameSchema,
+    AgentStopJobSchema,
     AgentStopWatchingSchema,
     AgentsArchivedSchema,
     AgentSearchQuerySchema,
@@ -24,9 +24,11 @@ import {
     LandResultSchema,
 } from "../schemas/agents.js";
 import { AgentsListSchema } from "../schemas/automations.js";
-import { AgentChangesSchema, AgentScratchSchema, AgentHistorySchema } from "../schemas/git/git.js";
+import { MainlinePushFixResultSchema, MainlinePushFixSchema } from "../schemas/workspace/mainline.js";
+import { AgentChangesSchema, AgentConflictsSchema, AgentScratchSchema, AgentHistorySchema } from "../schemas/git/git.js";
 import { FileDiffSchema } from "../schemas/history.js";
 import { OkSchema } from "../schemas/shared.js";
+import { AgentKeepWarmSchema } from "../schemas/keep-warm.js";
 import { ConversationPromptSchema } from "../schemas/system-prompt.js";
 
 // Every registered conversation-agent (AgentSummarySchema); an unknown {id} is NOT_FOUND across this whole family.
@@ -151,6 +153,18 @@ export const agentsContract = {
         .meta({ floor: "collaborator" })
         .input(AgentBreakPolicySchema)
         .output(AgentSummarySchema),
+    // Legal for a workspace conversation too, and only between turns in effect: a turn starting ends the hold.
+    keepWarm: procedure
+        .route({
+            method: "POST",
+            path: "/agents/{id}/keep-warm",
+            summary: "Keep this conversation's prompt cache warm while it sits idle",
+            description:
+                "Re-reads the conversation's cached context shortly before the provider would drop it, until the time asked for, so picking it back up costs a cache read instead of re-sending everything. Each refresh is a forked, unsaved request that adds nothing to the conversation. Stops by itself when the time runs out, when a turn starts, when the account nears its limit, or when the prompt the next turn would send has changed. Refused for a conversation whose cache is already cold or that this sandbox cannot replay. Null stops it.",
+        })
+        .meta({ floor: "collaborator" })
+        .input(AgentKeepWarmSchema)
+        .output(AgentSummarySchema),
     seen: procedure
         .route({
             method: "POST",
@@ -173,6 +187,16 @@ export const agentsContract = {
         })
         .input(AgentStopWatchingSchema)
         .output(AgentSummarySchema),
+    stopJob: procedure
+        .route({
+            method: "POST",
+            path: "/agents/{id}/stop-job",
+            summary: "Stop one of a conversation's background jobs",
+            description:
+                "Ends a command this conversation left running: the server it handed over, or the build it is waiting on. The watch that would have woken the conversation on its exit is disarmed first, so stopping it wakes nothing. Stopping a job that already ended is not an error.",
+        })
+        .input(AgentStopJobSchema)
+        .output(AgentSummarySchema),
     seenAll: procedure
         .route({
             method: "POST",
@@ -192,6 +216,18 @@ export const agentsContract = {
         })
         .input(AgentIdSchema)
         .output(AgentChangesSchema),
+    // For a press that needs only the verdict (asking the agent to resolve), without waiting on the review's per-file
+    // line counts, which on a branch of hundreds of files take tens of seconds.
+    conflicts: procedure
+        .route({
+            method: "GET",
+            path: "/agents/{id}/conflicts",
+            summary: "Why a conversation's last merge refused",
+            description:
+                "What still blocks the conversation's last refused merge, checked again against your workspace as it stands now. Returns the same `conflicts` the full change list carries, without the change list itself. Empty when nothing refused, or when what refused before has since stopped being in the way.",
+        })
+        .input(AgentIdSchema)
+        .output(AgentConflictsSchema),
     // Costs a `git log` per repo: ask only once `diff` reports something absorbed. Reading a file here reuses
     // `fileDiff`.
     history: procedure
@@ -235,6 +271,17 @@ 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(MainlinePushFixSchema)
+        .output(MainlinePushFixResultSchema),
     land: procedure
         .route({
             method: "POST",
@@ -306,7 +353,7 @@ export const agentsContract = {
                 "The gentle counterpart to discarding. Commits whatever the conversation still has in progress onto its own branch, releases its working copy, and keeps the entry and the record. Its scratch is not committed and goes with the copy. It leaves the live fleet and joins the archive. Refused for a conversation that is running.",
         })
         .meta({ floor: "collaborator", guest: true })
-        .input(AgentArchiveSchema)
+        .input(AgentIdsSchema)
         .output(AgentsArchivedSchema),
     unarchive: procedure
         .route({

package/src/contracts/offload.contract.ts

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import { procedure } from "../protocol/route-meta.js";
+import { streamOf } from "../protocol/routes.js";
+import { OffloadFrameSchema, OffloadKindSchema, OffloadRecordSchema, OffloadRunSchema, OffloadTargetSchema } from "../schemas/offload.js";
+import { OkSchema } from "../schemas/shared.js";
+
+// The in-sandbox `offload-run` command drives the first three on the agent token: the Bash hook and the check after
+// landing put it in front of a heavy line whose kind the owner sends to a runner (settings `offload`). A control token
+// never reaches them: they run code on another machine.
+const offloadRoute = procedure.meta({ agent: true, control: "never" });
+
+export const offloadContract = {
+    target: offloadRoute
+        .route({
+            method: "GET",
+            path: "/offload/runners/{runner}",
+            summary: "Whether a runner can take a heavy command",
+            description:
+                "Answers whether the runner a kind of heavy work is sent to is connected and able to run it, before anything is copied to it. When it is not, the command runs in this sandbox and says why.",
+        })
+        .input(z.object({ runner: z.string().min(1) }))
+        .output(OffloadTargetSchema),
+    run: offloadRoute
+        .route({
+            method: "POST",
+            path: "/offload/runs",
+            summary: "Run a heavy command on a runner",
+            description:
+                "Hands one command to a runner on one of your machines, together with a snapshot of the code as it stands, and streams its output back as it comes. It ends with the exit code, every file the command changed and any report it wrote.",
+        })
+        .meta({ stream: true })
+        .input(OffloadRunSchema)
+        .output(streamOf(OffloadFrameSchema)),
+    cancel: offloadRoute
+        .route({
+            method: "POST",
+            path: "/offload/runs/{runId}/cancel",
+            summary: "Stop an offloaded command",
+            description: "Stops a command running on a runner, with everything it started there.",
+        })
+        .input(z.object({ runId: z.string().min(1) }))
+        .output(OkSchema),
+    kinds: procedure
+        .route({
+            method: "GET",
+            path: "/offload/kinds",
+            summary: "Kinds of heavy work that can run elsewhere",
+            description:
+                "The kinds this sandbox sorts heavy commands into (tests, typechecks, verify…), each of which can be sent to a runner on one of your machines instead of running here.",
+        })
+        .output(z.object({ kinds: z.array(OffloadKindSchema) })),
+    runs: procedure
+        .route({
+            method: "GET",
+            path: "/offload/runs",
+            summary: "Recent offloaded commands",
+            description: "The heavy commands this sandbox sent to runners lately, newest first, with where they ran and how they ended.",
+        })
+        .output(z.object({ runs: z.array(OffloadRecordSchema) })),
+};

package/src/contracts/runner.contract.ts

@@ -2,7 +2,7 @@ import { oc } from "@orpc/contract";
 import { streamOf } from "../protocol/routes.js";
 import { z } from "zod";
 import { AgentEventSchema } from "../events/agent-events.js";
-import { RunnerFactsSchema, RunnerSyncLineSchema, RunnerSyncSchema, RunnerTurnSchema } from "../protocol/runner-protocol.js";
+import { RunnerCommandFrameSchema, RunnerCommandSchema, RunnerFactsSchema, RunnerSyncLineSchema, RunnerSyncSchema, RunnerTurnSchema } from "../protocol/runner-protocol.js";
 import { EditorContextSchema } from "../schemas/agent.js";
 import { AgentReplySchema } from "../schemas/providers/plan-limits.js";
 import { OkSchema } from "../schemas/shared.js";
@@ -35,6 +35,12 @@ export const runnerContract = {
     applyDefinition: oc.input(z.object({ toml: z.string() })).output(z.object({ settings: z.array(z.string()) })),
     // Stop the running turn; the parent's stop button reaching through.
     interrupt: oc.input(RunnerTurnSchema.pick({ conversationId: true })).output(OkSchema),
+    // One shell line the parent offloaded (settings `offload`), run against a snapshot of the parent's tree; its output
+    // streams back as it comes, then its exit with what it changed. An older runner lacks this procedure, which the
+    // parent reads as "can't take it" and runs the line itself.
+    runCommand: oc.input(RunnerCommandSchema).output(streamOf(RunnerCommandFrameSchema)),
+    // Stops an offloaded line and everything it started; the parent's stop reaching through.
+    cancelCommand: oc.input(RunnerCommandSchema.pick({ runId: true })).output(OkSchema),
     // Liveness driven by the parent: keepalive and gone-detection in one.
     ping: oc.output(OkSchema),
 };

package/src/contracts/workspace.contract.ts

@@ -16,6 +16,13 @@ import {
     WorkspaceGraphSchema,
     WorkspaceSyncSchema,
 } from "../schemas/workspace/workspace-repos.js";
+import {
+    MainlinePushDismissResultSchema,
+    MainlinePushDismissSchema,
+    MainlinePushRecheckResultSchema,
+    MainlinePushRecheckSchema,
+    MainlineStatusSchema,
+} from "../schemas/workspace/mainline.js";
 import { WorkspaceSearchQuerySchema, WorkspaceSearchResultSchema } from "../schemas/workspace/workspace-search.js";
 import { WorkspaceInstallResultSchema, WorkspaceInstallSchema, WorkspaceSetupSchema } from "../schemas/workspace/workspace-setup.js";
 import {
@@ -25,8 +32,11 @@ import {
     SidecarStatusSchema,
     WorkspaceDerivedQuerySchema,
     WorkspaceDerivedSchema,
+    WorkspaceDeletedSchema,
     WorkspaceDirSchema,
     WorkspaceExtractSchema,
+    WorkspaceRestoredSchema,
+    WorkspaceRestoreSchema,
     WorkspaceFileQuerySchema,
     WorkspaceFileReadQuerySchema,
     WorkspaceFileSchema,
@@ -191,11 +201,22 @@ export const workspaceContract = {
             path: "/workspace/entry",
             summary: "Delete a file or folder",
             description:
-                "Removes one entry and everything under it. The path travels in the body rather than the address, the same as every other write in this group.",
+                "Removes one entry and everything under it. It goes to the trash rather than being erased, and the answer carries the id that brings it back through the restore call for a day. The path travels in the body rather than the address, the same as every other write in this group.",
         })
         .meta({ floor: "writer" })
         .input(WorkspaceFileQuerySchema)
-        .output(OkSchema),
+        .output(WorkspaceDeletedSchema),
+    restore: procedure
+        .route({
+            method: "POST",
+            path: "/workspace/restore",
+            summary: "Bring back something deleted",
+            description:
+                "Puts an entry a delete sent to the trash back where it was, recreating the folders above it. Nothing is written over: when something new holds the name, it comes back beside it and the answer says where. Trash older than a day is gone.",
+        })
+        .meta({ floor: "writer" })
+        .input(WorkspaceRestoreSchema)
+        .output(WorkspaceRestoredSchema),
     move: procedure
         .route({
             method: "POST",
@@ -247,6 +268,37 @@ export const workspaceContract = {
         })
         .input(WorkspaceInstallSchema)
         .output(WorkspaceInstallResultSchema),
+    // Nothing is checked inside a turn; this is the check that runs instead, over the main tree after work lands.
+    mainline: procedure
+        .route({
+            method: "GET",
+            path: "/workspace/mainline",
+            summary: "The checks that run after work lands",
+            description:
+                "What the main tree's own check is measuring right now, which landed work waits for the next run, what the last run in each project said, and what became of a red one: sent back to the conversation that landed it, handed to a fresh conversation, or waiting on one still working. Nothing here ever holds a land, a commit or a push.",
+        })
+        .output(MainlineStatusSchema),
+    // What a push check found and let through waits here until measured gone or dismissed; these are the two hands on it.
+    mainlinePushDismiss: procedure
+        .route({
+            method: "POST",
+            path: "/workspace/mainline/push/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(MainlinePushDismissSchema)
+        .output(MainlinePushDismissResultSchema),
+    mainlinePushRecheck: procedure
+        .route({
+            method: "POST",
+            path: "/workspace/mainline/push/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(MainlinePushRecheckSchema)
+        .output(MainlinePushRecheckResultSchema),
     repos: procedure
         .route({
             method: "GET",