@intentic/sandbox-contract 1.235.0 → 1.237.0

package/src/chores/probes.test.ts

@@ -1,6 +1,8 @@
 import { describe, expect, test } from "vitest";
+import { choreById } from "./chores.js";
 import { probeSpec } from "./probes.js";
 import { IDIOM_RULES } from "./stack.js";
+import { WORKSPACE_ROOT_JSCPD_EXCLUDE_ARG, WORKSPACE_ROOT_RG_EXCLUDE_ARG } from "./workspace-scope.js";
 
 /* The parsers are the part of this library that faces someone else's output, so they are tested the way that
  * output actually arrives: real shapes, then the shapes that have historically broken things, a tool that
@@ -143,6 +145,11 @@ describe(`knip`, () => {
 });
 
 describe(`jscpd`, () => {
+    test(`the root-scoped command carries the reference-shelf prune argument`, () => {
+        expect(probeSpec(`jscpd`).command).toContain(WORKSPACE_ROOT_JSCPD_EXCLUDE_ARG);
+        expect(choreById(`duplication`)?.automation?.guard).toContain(WORKSPACE_ROOT_JSCPD_EXCLUDE_ARG);
+    });
+
     test(`takes the percentage of scanned lines and the biggest clones, longest first`, () => {
         const facts = parse(
             `jscpd`,
@@ -322,6 +329,11 @@ describe(`ui`, () => {
 describe(`the sweep's composed command`, () => {
     const stages = (): string[] => probeSpec(`ui`).command.split(`; `);
 
+    test(`both ripgrep entry points carry the root-scoped prune argument`, () => {
+        expect(probeSpec(`ui`).available).toContain(WORKSPACE_ROOT_RG_EXCLUDE_ARG);
+        expect(probeSpec(`ui`).command.split(WORKSPACE_ROOT_RG_EXCLUDE_ARG)).toHaveLength(3 + IDIOM_RULES.length);
+    });
+
     /* Given no path, ripgrep searches STDIN whenever stdin is not a TTY, which is exactly how a probe is spawned.
      * The sweep exited 0, printed its marker and matched nothing, in every repository, forever, which the marker
      * line cannot catch because the sweep really did run. It reproduces from a child process and never from an

package/src/chores/probes.ts

@@ -10,6 +10,7 @@ import {
     UI_FRAMEWORKS,
     TAILWIND_PACKAGES,
 } from "./stack.js";
+import { WORKSPACE_ROOT_JSCPD_EXCLUDE_ARG, WORKSPACE_ROOT_RG_EXCLUDE_ARG } from "./workspace-scope.js";
 
 /* THE PROBES, the measurements that cost a subprocess, declared once so the daemon that runs them and the panel
  * that explains them cannot disagree about what "outdated" meant.
@@ -348,7 +349,8 @@ const RULE_FILE_LIMIT = 500;
  * path reaches the chores no matter which tool produced it. */
 const SCAN_ROOT = `.`;
 
-const globArgs = (globs: readonly string[]): string => [...globs, ...SCAN_IGNORES].map((glob) => `-g '${glob}'`).join(` `);
+const globArgs = (globs: readonly string[]): string =>
+    [...[...globs, ...SCAN_IGNORES].map((glob) => `-g '${glob}'`), WORKSPACE_ROOT_RG_EXCLUDE_ARG].join(` `);
 
 // `path:count` from `rg --count-matches`, normalised. Split at the LAST colon: a path may contain one, a count is
 // always the digits at the end.
@@ -526,7 +528,7 @@ export const PROBES: readonly ProbeSpec[] = [
         // `--threshold 100` so jscpd never fails the command on its own opinion of what is too much duplication,
         // that judgement is the chore's, made from the percentage, not the tool's exit code.
         command:
-            `pnpm dlx jscpd --reporters json --output ${JSCPD_DIR} --min-lines 12 --threshold 100 . >/dev/null 2>&1; ` +
+            `pnpm dlx jscpd ${WORKSPACE_ROOT_JSCPD_EXCLUDE_ARG} --reporters json --output ${JSCPD_DIR} --min-lines 12 --threshold 100 . >/dev/null 2>&1; ` +
             `cat ${JSCPD_DIR}/jscpd-report.json 2>/dev/null`,
         parse: parseJscpd,
     },
@@ -576,7 +578,7 @@ export const PROBES: readonly ProbeSpec[] = [
         // Any manifest in the repo declaring a UI framework or Tailwind, not just the root's, a monorepo keeps
         // React in the app package and the root manifest is a handful of build tools.
         available:
-            `rg -l --no-messages -g '**/package.json' -g '!**/node_modules/**' ` +
+            `rg -l --no-messages -g '**/package.json' -g '!**/node_modules/**' ${WORKSPACE_ROOT_RG_EXCLUDE_ARG} ` +
             `-e '[\\x22](${[...UI_FRAMEWORKS.flatMap((framework) => framework.packages), ...TAILWIND_PACKAGES].join(`|`)})[\\x22]\\s*:' . >/dev/null`,
         unavailable: `no package here declares a UI framework or Tailwind`,
         command: scanCommand(),

package/src/chores/workspace-scope.ts

@@ -0,0 +1,12 @@
+/* Maintenance probes normally run inside one discovered repository, where a `refs/` directory is ordinary
+ * project content. They also run once against the workspace root, where the same first segment is the reserved
+ * reference shelf and can hold hundreds of thousands of files. The daemon sets this variable only for that
+ * root scope; shell commands opt into the matching prune argument without baking the shelf's name into the
+ * browser-safe contract package. */
+export const WORKSPACE_ROOT_EXCLUDE_ENV = `INTENTIC_WORKSPACE_ROOT_EXCLUDE`;
+
+// Unquoted parameter expansion is intentional: when the variable is absent it contributes zero arguments;
+// when present, each expression expands to one whitespace-free CLI argument. The daemon supplies the value
+// from @intentic/workspace-ignore, never from user input.
+export const WORKSPACE_ROOT_RG_EXCLUDE_ARG = `\${${WORKSPACE_ROOT_EXCLUDE_ENV}:+--glob=!/\${${WORKSPACE_ROOT_EXCLUDE_ENV}}/**}`;
+export const WORKSPACE_ROOT_JSCPD_EXCLUDE_ARG = `\${${WORKSPACE_ROOT_EXCLUDE_ENV}:+--ignore=\${${WORKSPACE_ROOT_EXCLUDE_ENV}}/**}`;

package/src/contracts/extensions.contract.ts

@@ -12,7 +12,7 @@ import {
     ExtensionUpdatePolicyInputSchema,
     ExtensionUpdatePreviewSchema,
     ExtensionUpdatesCheckedSchema,
-    ExtensionUsageInputSchema,
+    ExtensionUsageBatchSchema,
     WorkspaceExtensionCreatedSchema,
     WorkspaceExtensionCreateSchema,
 } from "../schemas/extension-updates.js";
@@ -80,16 +80,17 @@ export const extensionsContract = {
         .output(OkSchema),
     // The host reporting which declared routes it just let through. Written by the browser because that is where
     // the permission gate runs (apiImpl.ts), the daemon sees an extension's traffic as ordinary authenticated
-    // requests and cannot tell which extension, or which declared entry, any of it belongs to.
+    // requests and cannot tell which extension, or which declared entry, any of it belongs to. Every extension's
+    // accumulated counts ride together so the bookkeeping is one request rather than a burst of them.
     recordUsage: oc
         .route({
             method: "POST",
-            path: "/extensions/{id}/usage",
-            summary: "Record what an extension just used",
+            path: "/extensions/usage",
+            summary: "Record what extensions just used",
             description:
-                "Written by the app rather than measured by the daemon, because the permission gate runs in the browser: from the sandbox's side an extension's traffic is indistinguishable from anyone else's. This is how the record of which powers an extension actually exercises gets kept.",
+                "One batch written by the app rather than measured by the daemon, because the permission gate runs in the browser: from the sandbox's side extension traffic is indistinguishable from anyone else's. This is how the record of which powers each extension actually exercises gets kept without one reporting request per extension.",
         })
-        .input(ExtensionUsageInputSchema)
+        .input(ExtensionUsageBatchSchema)
         .output(OkSchema),
     /* Whether this extension is fit for somebody else to run, the checks answerable from its files alone. Read
      * on demand rather than carried on the list: it reads the bundle off disk per extension, and it is looked at

package/src/contracts/workspace.contract.ts

@@ -53,13 +53,14 @@ export const workspaceContract = {
         .output(WorkspaceTreeSchema),
     // Lazy-load one directory's children, the tree returns ignored dirs (node_modules, .git, …) without children,
     // and the client fetches them here on expand so a giant node_modules can't blow the tree walk's entry budget.
+    // Bounded depth is for consumers that need a small subtree as data rather than one explorer row at a time.
     children: oc
         .route({
             method: "GET",
             path: "/workspace/children",
-            summary: "One folder's contents",
+            summary: "A bounded folder listing",
             description:
-                "The entries directly inside a single folder. This is how you open a folder the full tree walk deliberately left closed, such as an installed-packages directory with a hundred thousand files in it.",
+                "The entries inside a folder as one flat list. Direct children are the default, which is how the explorer opens a folder the full tree walk left closed; callers that need a small subtree can ask for up to five levels without a request per directory.",
         })
         .input(WorkspaceChildrenQuerySchema)
         .output(WorkspaceChildrenSchema),

package/src/events.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { AgentProviderSchema, PermissionModeSchema } from "./schemas/agent.js";
+import { AgentHarnessSchema, AgentProviderSchema, PermissionModeSchema } from "./schemas/agent.js";
 import { AgentSummarySchema, LandConflictSchema } from "./schemas/agents.js";
 import { RateLimitInfoSchema } from "./schemas/claude-gate.js";
 import { FastModeStateSchema } from "./schemas/fast-mode.js";
@@ -437,8 +437,24 @@ export const SessionTranscriptSchema = z.object({
             "The conversation, in order. Each block of the agent's prose is its own message with the tools that block introduced, which is what reproduces the way it actually unfolded.",
         ),
 });
+/* THE RECORD A REOPENED TAB IS REBUILT FROM: the messages, plus what the session behind them is BOUND to.
+ *
+ * A provider session is minted on one runtime under one credential, and it resumes only there, so a client
+ * deciding whether its next message continues this conversation or starts a fresh one needs all four facts
+ * together. The client cannot derive the last three: its tab holds the picks the NEXT turn would use, which
+ * after a mid-chat switch are exactly the ones the session does not belong to. Stamping those onto the session
+ * is what made switching BACK to the account that minted it announce a fresh session and then retire a
+ * perfectly resumable one, spending the whole transcript again on a cold prompt cache.
+ *
+ * All optional, and absent together on a conversation that has no session to resume. */
 export const AgentTranscriptSchema = SessionTranscriptSchema.extend({
     sessionId: z.string().optional().describe("The provider session behind the last turn, when there is one."),
+    provider: AgentProviderSchema.optional().describe("Which provider minted that session."),
+    harness: AgentHarnessSchema.optional().describe("Which runtime minted it: a session resumes only on the loop that opened it."),
+    account: z
+        .string()
+        .optional()
+        .describe("Which stored account it belongs to, as the daemon resolved it. Absent when no stored account paid for the turn."),
 });
 
 /* WHAT A PUBLISHED CONVERSATION'S PAGE IS HANDED, the whole of it, baked into the page as one JSON block.
@@ -495,8 +511,8 @@ const PlanCardSchema = z.object({
     kind: z.literal("plan").describe("The agent has written a plan and is waiting for a yes."),
     requestId: z.string().describe("What to send back when you answer."),
     text: z.string().describe("The plan itself."),
-    // Present when the plan text POINTS at a document instead of being one: the model wrote the real plan to a
-    // file and summarised it here. Absent when the text already is the whole plan, which is the ordinary case.
+    // Present when the adjacent plan prose POINTS at a document instead of being one: the model wrote the real
+    // plan to a file and summarised it there. Absent when the text already is the whole plan.
     document: CardDocumentSchema.optional().describe("The write-up this plan refers to, when the plan itself is a pointer to one."),
 });
 const QuestionCardSchema = z.object({
@@ -522,7 +538,22 @@ export type ParkedCard = z.infer<typeof ParkedCardSchema>;
 // `parentToolUseId` tags frames produced inside a subagent (Task tool); `subagent`/`subagent_update` report the
 // subagent itself, keyed by the same tool_use id those tagged frames carry.
 export const AgentEventSchema = z.discriminatedUnion("kind", [
-    z.object({ kind: z.literal("session"), sessionId: z.string() }),
+    /* THE SESSION THIS TURN IS RUNNING, and the credential it belongs to.
+     *
+     * `account` is the account the daemon RESOLVED for the turn, which is not always the one the request named:
+     * a turn that names none is given the connected account with the most headroom (agent/harness-credentials.ts),
+     * so "the client's pick" and "who is paying" are different questions and only the daemon can answer the
+     * second. It rides here because a session belongs to the credential that minted it — that pairing is what
+     * decides whether the next message resumes this session or opens a fresh one — and a client that stamped its
+     * own pick onto the session instead would announce a fresh session for the account that actually holds it.
+     *
+     * Absent when the turn ran on the container's env token or on a translator subscription, where there is no
+     * stored account to name. */
+    z.object({
+        kind: z.literal("session"),
+        sessionId: z.string(),
+        account: z.string().optional().describe("Which stored account this session belongs to, as the daemon resolved it for the turn."),
+    }),
     /* WHERE AN ISOLATED TURN IS STANDING: the conversation's worktree identity, its branch (agent/<id>) and
      * the ROOT repo's short base sha. First frame of the turn, before any provider frames, and again each time
      * the branch MOVES underneath it, which is why `base` names where the branch sits now rather than the

package/src/hostnames.ts

@@ -70,12 +70,12 @@ export const CATCH_ALL = { service: "http_status:404" } as const;
 // for as long as the file does.
 //
 // A *label* is the first-DNS-label prefix before `-<sandboxId>` (`preview-<panel>` / `port-<slot>` /
-// `public-<slot>`), the unit the platform's /sandbox/preview-route mints, so one endpoint serves all three.
+// `public-<slot>`), the unit reachability is expressed in, so one rule covers all three.
 export const previewLabel = (panel: string): string => `preview-${panel}`;
 export const portLabel = (slot: string): string => `port-${slot}`;
 export const publicLabel = (slot: string): string => `public-${slot}`;
 
-// The hostname a label resolves to, what the platform's /sandbox/preview-route mints from the label alone.
+// The hostname a label resolves to. Nothing mints it: the edge parses the sandbox id back out of the name.
 export const labelHostname = (label: string, id: string, zone: string): string => `${label}-${id}.${zone}`;
 export const previewHostname = (panel: string, id: string, zone: string): string => labelHostname(previewLabel(panel), id, zone);
 export const portHostname = (slot: string, id: string, zone: string): string => labelHostname(portLabel(slot), id, zone);

package/src/ingress-contract.ts

@@ -113,8 +113,10 @@ export const INGRESS_TUNNEL_PATH = "/tunnel/v1";
 export const INGRESS_GRANT_HEADER = "x-intentic-grant";
 
 /* The env vocabulary, every lane (connect one-liner, compose file, hosted machine env) hands the same pair
- * down and the entrypoint/daemon read exactly these names. SANDBOX_PUBLIC_URL is unchanged from the zrok era
- * and stays beside them. */
+ * down and the DAEMON reads exactly these names — the entrypoint reads neither, and that is the shape of the
+ * change: reachability stopped being something a shell script arranges before the daemon starts and became
+ * one outbound dial the daemon makes for itself. SANDBOX_PUBLIC_URL is unchanged from the fabric before this
+ * one and stays beside them. */
 export const ENV_INGRESS_URL = "INGRESS_URL";
 export const ENV_SANDBOX_GRANT = "SANDBOX_GRANT";