@intentic/sandbox-contract 1.232.0 → 1.234.0

package/src/schemas/workspace-search.ts

@@ -0,0 +1,141 @@
+import { z } from "zod";
+// The workspace-search wire shape, shared by the daemon's /workspace/search route and the web client.
+// (Implementation detail, not part of the contract: the daemon backs this route with a resident in-process iq
+// engine; the engine is interchangeable behind this shape.) Groups are relevance-ranked (best first, never path
+// order); each hit carries the match-reason tags the fused engines contributed, and the char spans within `text`
+// that matched, so clients highlight without re-finding the needle.
+export const WorkspaceSearchQuerySchema = z.object({
+    query: z.string().min(2).max(512).describe("What to look for. Plain words, a pattern, a symbol name, or a question."),
+    // Search verbs only, anchor/git verbs (outline, context, log, who, …) are CLI-only surface. Natural language
+    // has no verb of its own: `q` classifies the query and answers it semantically when the words call for it.
+    mode: z
+        .enum(["q", "find", "files", "def", "refs", "sym", "ast"])
+        .optional()
+        .describe(
+            "Narrow the search to one kind: plain text, filenames, definitions, references, symbols, or code structure. Leave it out to blend them, which also answers a question asked in words.",
+        ),
+    includeIgnored: z.stringbool().optional().describe("Search inside installed packages and other ignored folders too."),
+    // How `find` reads the query, the three switches every editor's search box has (VSCode: Aa, ab, .*).
+    // `literal` treats it as fixed text instead of a regex; `caseSensitive` off means case-INSENSITIVE, not
+    // ripgrep's smart case.
+    literal: z.stringbool().optional().describe("Treat the query as fixed text rather than a pattern."),
+    word: z.stringbool().optional().describe("Match whole words only."),
+    caseSensitive: z.stringbool().optional().describe("Whether capitals matter. Off means they do not, rather than being guessed at from the query."),
+    // Which FILES the query is asked of, in VSCode's files-to-include grammar, as TYPED, because the reading
+    // of it is shared (search-globs.ts) rather than each end guessing: comma-separated patterns, each matched
+    // at any depth unless `./` anchors it, a leading `!` excluding instead. Distinct from `includeIgnored`,
+    // which decides whether the ignored layers are searched at all, this narrows within what that admitted.
+    include: z
+        .string()
+        .max(512)
+        .optional()
+        .describe(
+            "Which files to ask, in the same grammar an editor's files-to-include box takes: comma-separated patterns, matched at any depth unless anchored, a leading exclamation mark excluding instead.",
+        ),
+    limit: z.coerce.number().int().positive().optional().describe("How many results to return."),
+    after: z.string().optional().describe("Resume from the cursor a previous answer handed back."),
+});
+export const WorkspaceSearchTagSchema = z.object({
+    kind: z
+        .enum(["def", "text", "sem", "bm25", "rerank", "path", "import", "call", "type", "write", "fuzzy", "heuristic"])
+        .describe(
+            "Why this line matched: the literal text, its meaning, the path, a definition, a call, and so on. Several kinds can agree on one line.",
+        ),
+    score: z.number().optional().describe("How strongly that reason applied."),
+});
+export type WorkspaceSearchTag = z.infer<typeof WorkspaceSearchTagSchema>;
+export const WorkspaceSearchSpanSchema = z.object({
+    start: z.number().describe("First character of the match within the line."),
+    end: z.number().describe("One past the last."),
+});
+export type WorkspaceSearchSpan = z.infer<typeof WorkspaceSearchSpanSchema>;
+export const WorkspaceSearchHitSchema = z.object({
+    line: z.number().describe("Which line, counting from one."),
+    text: z.string().describe("The line itself."),
+    // Every matched span in `text`, in order, a text search marks all of them, the way an editor does. Empty
+    // where the LINE is the match and no span of it is (a semantic or definition hit reports none).
+    spans: z
+        .array(WorkspaceSearchSpanSchema)
+        .describe(
+            "Where in the line the matches are, so you can highlight without searching again. Empty when the whole line is the match rather than part of it.",
+        ),
+    tags: z.array(WorkspaceSearchTagSchema).describe("Why it matched."),
+    // Enclosing symbol ("createWidget (fn)"), parent-document context so the reader often needs no follow-up.
+    context: z
+        .string()
+        .optional()
+        .describe("What it sits inside: the function, the class, the heading. Often enough that you need not open the file."),
+});
+export type WorkspaceSearchHit = z.infer<typeof WorkspaceSearchHitSchema>;
+export const WorkspaceSearchGroupSchema = z.object({
+    path: z.string().describe("The file."),
+    score: z.number().describe("How well it matched. Groups arrive best first, never in path order."),
+    hits: z.array(WorkspaceSearchHitSchema).describe("The matching lines in it."),
+    // This file had more matching lines than the engine keeps per file, so `hits` is a floor, a panel showing a
+    // per-file count has to say "50+" rather than "50".
+    capped: z
+        .boolean()
+        .optional()
+        .describe("This file had more matches than are kept per file, so the count is a floor. Say fifty-plus rather than fifty."),
+});
+export type WorkspaceSearchGroup = z.infer<typeof WorkspaceSearchGroupSchema>;
+// `building` = index still filling (progress 0..1, e.g. embeddings pending); `stale` = revalidation was skipped
+// (cursor replay). ageMs = time since the index last matched the disk state.
+export const WorkspaceSearchFreshnessSchema = z.object({
+    state: z.enum(["fresh", "building", "stale"]).describe("Whether the index matches what is on disk, is still filling, or has fallen behind."),
+    ageMs: z.number().optional().describe("How long since it last matched the disk, in milliseconds."),
+    progress: z.number().optional().describe("How far through building it is, from zero to one."),
+    // How many files the index has not caught up with, when it is stale. A count is reportable; "stale" alone
+    // reads as a warning about the answer, which it almost never is.
+    behind: z
+        .number()
+        .optional()
+        .describe(
+            "How many files it has not caught up with. Worth showing, because the word stale on its own reads as a warning about the answer, which it almost never is.",
+        ),
+});
+export type WorkspaceSearchFreshness = z.infer<typeof WorkspaceSearchFreshnessSchema>;
+export const WorkspaceSearchResultSchema = z.object({
+    mode: z.string().describe("Which kind of search actually ran, which matters when you let it choose."),
+    total: z.number().describe("Matching lines across the whole workspace, not just this page."),
+    // Files the query matched in total, which `groups` reports only for the page it carries, the count a
+    // results panel puts beside the hit total ("218 results in 61 files").
+    files: z.number().describe("Files the query matched in total."),
+    shown: z.number().describe("How many of those lines are on this page."),
+    groups: z.array(WorkspaceSearchGroupSchema).describe("The results, grouped by file, best first."),
+    freshness: WorkspaceSearchFreshnessSchema.describe("Whether the index behind the answer is up to date."),
+    truncated: z.boolean().describe("This page is not all of it. Use the cursor."),
+    // `total` is a FLOOR: at least one file had more matches than the engine keeps per file. Distinct from
+    // `truncated`, which is about this PAGE, a result can be complete on the page and still count partially.
+    partial: z
+        .boolean()
+        .optional()
+        .describe(
+            "At least one file had more matches than are kept per file, so the total is a floor. Different from the page being truncated: a complete page can still count partially.",
+        ),
+    cursor: z.string().optional().describe("Pass this back as `after` to get the next page."),
+    hint: z.string().optional().describe("A suggestion for getting a better answer out of this query."),
+    // What the engine did with the query that the query did not ask for, a pattern rerun as literal text
+    // because it is not valid regex, grep-style escapes rewritten, a language filter that matched no files. The
+    // text surface has always printed this above the results; a JSON caller could not see it at all.
+    note: z
+        .string()
+        .optional()
+        .describe(
+            "What the engine did that you did not ask for: a pattern rerun as plain text because it was not valid, escapes rewritten, a language filter that matched nothing.",
+        ),
+    // Code-graph neighbors of the top hits (definition anchors + the strongest caller of each).
+    related: z.array(z.string()).optional().describe("Places next door to the best results: where each is defined, and whatever calls it most."),
+    // Ranked `path:line` anchors that placed but were NOT shown, best first, the answer often sits at rank 5–13,
+    // behind groups the budget spent itself on. The text surface has always printed this map; a JSON caller could
+    // not see it, so it had to page through `cursor` to learn what the terminal was told up front.
+    candidates: z
+        .array(z.string())
+        .optional()
+        .describe(
+            "Ranked places that scored but did not make the page, best first. The answer often sits at rank five to thirteen, so this saves paging through to find out.",
+        ),
+    // Run provenance for benchmarking: retrieval stages DISABLED this invocation (absent = full pipeline).
+    features: z.array(z.string()).optional().describe("Which stages of the search were switched off for this run. Absent means all of them ran."),
+});
+export type WorkspaceSearchResult = z.infer<typeof WorkspaceSearchResultSchema>;

package/src/schemas/workspace-setup.ts

@@ -0,0 +1,43 @@
+// workspace setup (dependency readiness)
+import { z } from "zod";
+// One project under /work and whether its dependencies are actually installed. A drop omits node_modules/.venv
+// on purpose, so a freshly imported project is present-but-unusable until this says "ready", the import UI,
+// the agent's post-edit type-check, and the agent's turn context all gate on it.
+// `dir` is root-relative ("" = the workspace root itself); `manager` is the real binary (pnpm/npm/uv/…);
+// `evidence` is the file that decided it ("pnpm-lock.yaml"), so the UI can show WHY, not just what.
+// state: ready | installing | needs-setup | unsupported (manager absent from this sandbox, `manager` names it)
+//      | stale, installed ONCE and since outgrown: the manifests declare dependencies that are not on disk,
+//        which is what an agent leaves behind when it adds one and does not install it. Same command fixes it,
+//        so `missing` (how many names cannot resolve) is what separates the two in the UI's wording.
+export const ProjectSetupSchema = z.object({
+    dir: z.string().describe("Where the project is, relative to the workspace root. Empty means the root itself."),
+    ecosystem: z.enum(["node", "python"]).describe("Which language's tooling it uses."),
+    manager: z.string().describe("The tool that would do the installing."),
+    command: z.string().describe("The exact command that would run."),
+    evidence: z.string().describe("The file that decided all of the above, so the answer can be checked rather than trusted."),
+    state: z
+        .enum(["ready", "installing", "needs-setup", "unsupported", "stale"])
+        .describe(
+            "Ready means its dependencies are really there. Stale means it was installed once and has since outgrown that, which is what an agent leaves behind when it adds a dependency without installing it. Unsupported means this sandbox has no such tool.",
+        ),
+    missing: z.number().optional().describe("How many declared dependencies cannot be found on disk. What separates never-installed from outgrown."),
+});
+export type ProjectSetup = z.infer<typeof ProjectSetupSchema>;
+export const WorkspaceSetupSchema = z.object({
+    projects: z.array(ProjectSetupSchema).describe("Every project the sandbox found, and whether each is usable."),
+});
+export type WorkspaceSetup = z.infer<typeof WorkspaceSetupSchema>;
+// Install these projects' dependencies. Dirs already ready, already installing, or whose manager is missing are
+// skipped server-side, so a stale client list can't spawn redundant installs, `started` is what actually ran.
+export const WorkspaceInstallSchema = z.object({
+    dirs: z
+        .array(z.string().max(500))
+        .min(1)
+        .max(50)
+        .describe(
+            "Which projects to install, by folder. Ones already ready, already installing, or with no tool to install them are skipped rather than refused.",
+        ),
+});
+export const WorkspaceInstallResultSchema = z.object({
+    queued: z.array(z.string()).describe("Which of them actually started, which is not necessarily what you asked for."),
+});

package/src/schemas/workspace-tree.ts

@@ -0,0 +1,234 @@
+// workspace tree + files
+import { z } from "zod";
+import { ConversationIdSchema } from "./agent.js";
+/* WHOSE COPY OF THE WORKSPACE A READ MEANS, the half of a file address that used to be implicit, and wrong.
+ *
+ * There is not one workspace. There is the shared /work tree, and there is one private checkout per isolated
+ * conversation, each holding files that conversation created and versions of files it edited. Every workspace
+ * read route named a PATH and nothing else, so it could only ever answer from the shared tree, and an agent
+ * that had just written `docs/plan.md` in its own checkout described a file the viewer could not open, while
+ * an agent that had EDITED a file got something worse: the shared version, same path, different text, with
+ * nothing to say so.
+ *
+ * So the conversation rides the request. Absent ⇒ the shared tree, which is what every existing caller means
+ * and why the field is optional rather than a second set of routes. Present ⇒ that conversation's own
+ * checkout, resolved daemon-side in ONE place (workspaceRootFor) so the escape guard, the control-plane
+ * denylist and the ignore rules apply to it exactly as they do to /work.
+ *
+ * A conversation that is not isolated resolves BACK to the shared tree rather than failing: the shared tree
+ * genuinely is its tree, and a caller should not have to know which mode a conversation runs in to link to a
+ * file in it. */
+export const WorkspaceScopeSchema = z.object({
+    agent: ConversationIdSchema.optional().describe(
+        "Read a conversation's own private copy of the workspace rather than the shared tree. Leave it out for the shared tree. A conversation that is not working privately resolves back to the shared tree rather than failing, so a link need not know which mode it runs in.",
+    ),
+});
+export type WorkspaceScope = z.infer<typeof WorkspaceScopeSchema>;
+/* One node of the full /work filesystem tree the agent sees (untracked + generated files included), distinct
+ * from the git-tracked listing. `path` is root-relative with forward slashes so it feeds straight back to the
+ * file route.
+ *
+ * Recursive, and the type is declared rather than inferred. Zod's getter form does infer one, but it collapses
+ * to `{}` below the first level of nesting, so `entry.children[0].name` type-checked as an index-signature
+ * read on both sides of the wire, and the tree walker's own suite was reading a `hidden` field off entries
+ * that has never existed there without the compiler minding. The interface is the contract; the schema
+ * validates against it, and z.ZodType makes a divergence between the two an error here. */
+/* A SYMLINK, as the tree reports one. Present only on entries that are links; `type` beside it is the type of
+ * whatever the link POINTS AT, so a link to a directory expands and a link to a file opens, exactly like the
+ * real thing (the model VSCode uses, its FileType carries SymbolicLink as a bit alongside File/Directory,
+ * precisely so every consumer can keep asking "file or folder?").
+ *
+ * `to` is the link's own text, verbatim, `../../.agents/skills/discord`, not the resolved path. That is what
+ * the row shows on hover, because it is what the person who made the link wrote and what they would edit.
+ *
+ * `state` is absent for the ordinary case: it resolves, and it resolves to somewhere inside the workspace.
+ *   - "broken", nothing at the other end. Listed anyway, because a dangling link is a fact about the
+ *     workspace worth seeing rather than an entry to hide.
+ *   - "outside", it resolves to bytes outside the workspace. The daemon will not read, list or descend
+ *     through it (workspace-files.ts realWithin), so the row is shown and refused, like a locked one. */
+export interface WorkspaceLink {
+    readonly to: string;
+    readonly state?: "broken" | "outside" | undefined;
+}
+export const WorkspaceLinkSchema = z.object({
+    to: z
+        .string()
+        .describe("What the link says, verbatim, rather than where it ends up. That is what the person who made it wrote, and what they would edit."),
+    state: z
+        .enum(["broken", "outside"])
+        .optional()
+        .describe(
+            "Absent for an ordinary link. Broken means there is nothing at the other end, and it is listed anyway because a dangling link is worth seeing. Outside means it leads out of the workspace, so it is shown and refused.",
+        ),
+});
+export interface WorkspaceTreeEntry {
+    readonly name: string;
+    readonly path: string;
+    readonly type: "file" | "dir";
+    readonly size?: number | undefined;
+    // Ignored-by-tooling (node_modules, .git, .gitignore'd paths, browser profiles): the client grays the row.
+    readonly ignored?: boolean | undefined;
+    // Set when this entry is a symlink, `type` above is then its TARGET's type. See WorkspaceLink.
+    readonly link?: WorkspaceLink | undefined;
+    // A DIR without `children` was listed but not descended into, because it's ignored, or because the walk's
+    // breadth-first budget stopped above it. Either way the client lazy-loads it via /workspace/children on
+    // expand, so "not loaded yet" and "empty directory" (`children: []`) stay distinguishable.
+    readonly children?: readonly WorkspaceTreeEntry[] | undefined;
+}
+export const WorkspaceTreeEntrySchema: z.ZodType<WorkspaceTreeEntry> = z.object({
+    name: z.string().describe("Just this entry's own name."),
+    path: z.string().describe("Its full path from the workspace root, which feeds straight back into the file routes."),
+    type: z.enum(["file", "dir"]).describe("What it is. For a link, what it points at, so a link to a folder opens like a folder."),
+    size: z.number().optional().describe("Size in bytes, for a file."),
+    ignored: z
+        .boolean()
+        .optional()
+        .describe("Tooling ignores it: installed packages, git internals, anything the ignore rules exclude. Usually drawn greyed out."),
+    link: WorkspaceLinkSchema.optional().describe("Present when this entry is a link."),
+    get children() {
+        return z
+            .array(WorkspaceTreeEntrySchema)
+            .optional()
+            .describe(
+                "What is inside a folder. Absent means it was not opened, either because it is ignored or because the walk ran out of budget above it, so ask for it separately. An empty list means it really is empty.",
+            );
+    },
+});
+export const WorkspaceTreeSchema = z.object({
+    root: z.string().describe("The path everything below is relative to."),
+    tree: z.array(WorkspaceTreeEntrySchema).describe("The workspace, one entry per file and folder."),
+    // How many of the ROOT's own entries the budget cut (0 = complete); per-dir cuts are counted on each dir entry.
+    hidden: z.number().describe("How many entries at the top level were cut for size. Zero means the listing is complete."),
+});
+export type WorkspaceTree = z.infer<typeof WorkspaceTreeSchema>;
+// Lazy-load one directory's children, for a dir the tree walk listed but didn't descend into. Child dirs again
+// carry no `children`, so they lazy-load on their own expand. `hidden` = how many entries the cap cut (0 = all
+// listed).
+export const WorkspaceChildrenQuerySchema = WorkspaceScopeSchema.extend({
+    path: z.string().min(1).describe("The folder to open, as a workspace path."),
+});
+export const WorkspaceChildrenSchema = z.object({
+    entries: z
+        .array(WorkspaceTreeEntrySchema)
+        .describe("What is directly inside it. Folders in here carry no contents of their own, so they open the same way."),
+    hidden: z.number().describe("How many entries were cut for size. Zero means the listing is complete."),
+});
+export type WorkspaceChildren = z.infer<typeof WorkspaceChildrenSchema>;
+// Write routes (delete) and the read they mirror. No scope: a conversation's own checkout is READ-ONLY through
+// the file API, see workspaceRootFor for why the refusal lives daemon-side rather than in each screen.
+export const WorkspaceFileQuerySchema = z.object({ path: z.string().min(1).describe("The file or folder, as a workspace path.") });
+export const WorkspaceMediaTicketQuerySchema = WorkspaceScopeSchema.extend({
+    path: z.string().min(1).describe("The media file the ticket should cover."),
+});
+/* The credential a <video>/<audio> element carries to GET /workspace/media, which is the one workspace route a
+ * browser cannot put a header on. Minted here, over the ordinary bearer-authenticated contract, and scoped to
+ * the single FILE it was asked for, the resolved one, so a ticket minted against a conversation's checkout
+ * buys that file and not its shared-tree namesake (see auth/media-tickets.ts for why scope rather than
+ * single-use is what bounds it). `expiresAt` is epoch ms so a player can tell a dead ticket from a dead file. */
+export const WorkspaceMediaTicketSchema = z.object({
+    ticket: z.string().describe("Hand this to the streaming route in the query string. It buys exactly the one file it was minted for."),
+    expiresAt: z.number().describe("When it stops working, in milliseconds, so a player can tell a dead ticket from a dead file."),
+});
+/* A text read is a read of a WINDOW: `offset` is the byte to start at (negative reads that many bytes from the
+ * END, which is what following a growing log means, the tail's offset isn't knowable until the size is), and
+ * `limit` how many bytes to serve. The daemon clamps `limit` to its own cap, so an omitted or oversized one is
+ * the cap rather than the file. Coerced: these arrive as query strings. */
+export const WorkspaceFileReadQuerySchema = WorkspaceScopeSchema.extend({
+    path: z.string().min(1).describe("The file to read, as a workspace path."),
+    offset: z.coerce
+        .number()
+        .int()
+        .optional()
+        .describe(
+            "Which byte to start at. A negative number reads that many bytes from the end, which is how you follow a growing log without knowing its size first.",
+        ),
+    limit: z.coerce
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe(
+            "How many bytes to read. Capped by the sandbox, so leaving it out or asking for too much gives you the cap rather than the whole file.",
+        ),
+});
+// `size` is the whole file; `offset`/`bytes` the byte range `content` decodes from, so the reader can tell a
+// window from a whole file (offset > 0 || offset + bytes < size ⇒ there is more) and ask for the next one.
+export const WorkspaceFilePresentSchema = z.object({
+    present: z.literal(true).describe("There is something at that path."),
+    path: z.string().describe("The path, as asked for."),
+    content: z.string().describe("The bytes of the window you asked for, as text."),
+    size: z.number().describe("How large the whole file is. Compare it with the window below to know whether there is more."),
+    offset: z.number().describe("Which byte the window starts at."),
+    bytes: z.number().describe("How many bytes the window holds."),
+    // Which tree answered. Always true when no `agent` was asked for; true DESPITE one when that conversation's
+    // checkout doesn't carry the path (see scopedTarget, its checkout is not a superset of /work), which is
+    // the one case the reader has to be told about rather than left to assume.
+    shared: z
+        .boolean()
+        .describe(
+            "Which tree answered. True when no conversation was named, and also when one was but its own copy has no such file, which is the case a reader has to be told about rather than left to assume.",
+        ),
+});
+/* NOTHING TO READ AT THAT PATH, an ANSWER, not a failure, which is the whole reason this branch exists.
+ *
+ * Most reads in this product are "read it if it is there": the file each extension keeps of what its badge has
+ * already shown, a repo's documentation index, a run's result, a directory's own UI document. Absent is their
+ * ordinary FIRST state, and every one of them already treats it as a value. Answering those with a 404 made the
+ * browser log a failed request per read, around a dozen red lines on every page load, none of which meant
+ * anything was wrong, and none of which a `catch` can suppress: the log happens in the network stack before any
+ * JavaScript sees the response.
+ *
+ * A read that is REFUSED (an escape, the control plane, a denylisted path) is still an error, because that is a
+ * real answer about the caller rather than about the file. */
+export const WorkspaceFileAbsentSchema = z.object({
+    present: z
+        .literal(false)
+        .describe(
+            "Nothing there. An answer, not a failure: reading a file that may not exist yet is the ordinary case for half the reads in this product.",
+        ),
+    path: z.string().describe("The path, as asked for."),
+});
+export const WorkspaceFileSchema = z.discriminatedUnion("present", [WorkspaceFilePresentSchema, WorkspaceFileAbsentSchema]);
+// Resolve a file reference an agent (or a compiler, or a terminal) NAMED to the workspace path it means. Prose
+// paths are routinely partial, a model that has been discussing `_editor/web/src` writes
+// `pages/workspace/Foo.vue`, so a clickable mention has to be matched as a path SUFFIX against the real tree,
+// not read as root-relative. `path` is absent when nothing in the workspace ends in that reference.
+export const WorkspaceResolveQuerySchema = WorkspaceScopeSchema.extend({
+    path: z
+        .string()
+        .min(1)
+        .max(512)
+        .describe(
+            "The reference as somebody wrote it. Often only the tail of the real path, which is why this is matched against the tree rather than read as-is.",
+        ),
+});
+export const WorkspaceResolveSchema = z.object({
+    path: z.string().optional().describe("The real path it means. Absent when nothing in the workspace ends that way."),
+});
+// Direct file management over the /work tree (delete / new folder / rename+move / copy). Byte writes + the
+// editor's text save go through the plain POST /workspace/upload route (a body doesn't fit oRPC), not here.
+export const WorkspaceDirSchema = z.object({ path: z.string().min(1).describe("The folder to create. Missing folders above it are created too.") });
+export const WorkspaceMoveSchema = z.object({
+    from: z.string().min(1).describe("What to move or copy, as a workspace path."),
+    to: z.string().min(1).describe("Where it should end up. Changing only the last part is how you rename something."),
+});
+// Deterministic (no-LLM) classification of the dropped workspace: each repo dir and loose file sorted into one
+// coarse bucket. Read-only, the browser turns it into a proposed layout and applies the accepted moves via the
+// existing /workspace/move route. `reason` records the winning signal (magic:<mime>, ext:<ext>,
+// repository:<marker>, text-content, unknown) so the proposal is explainable.
+export const WorkspaceBucketSchema = z.enum(["repositories", "documents", "media", "archives", "other"]);
+export type WorkspaceBucket = z.infer<typeof WorkspaceBucketSchema>;
+export const WorkspaceClassificationSchema = z.object({
+    classifications: z
+        .array(
+            z.object({
+                path: z.string().describe("What was looked at."),
+                bucket: WorkspaceBucketSchema.describe("Which bucket it was sorted into."),
+                reason: z.string().describe("The signal that decided it, so the proposal can be argued with rather than trusted."),
+            }),
+        )
+        .describe(
+            "One entry per repository folder and loose file at the top of the workspace. A read-only proposal: nothing moves until you apply it.",
+        ),
+});
+export type WorkspaceClassification = z.infer<typeof WorkspaceClassificationSchema>;

package/src/title.test.ts

@@ -1,5 +1,5 @@
 import { expect, test } from "vitest";
-import { AgentTurnSchema } from "./schemas.js";
+import { AgentTurnSchema } from "./schemas/agent.js";
 import { deriveTitle } from "./title.js";
 
 /* The name a conversation opens under. Every case here is a shape the naive rule (collapse whitespace, cut at

package/src/tunnel-ids.test.ts

@@ -42,7 +42,9 @@ test("slots are not derivable from the sandbox id: only from the token behind it
     expect(portSlotsFromToken(OTHER)).not.toEqual(portSlotsFromToken(TOKEN));
     // No slot leaks the id it will be paired with in `port-<slot>-<sandboxId>`.
     const id = sandboxIdFromToken(TOKEN);
-    expect(id).toBeDefined();
+    // Load-bearing, and not merely tidy: `not.toContain(undefined)` is true of every slot list ever produced,
+    // so without a real id the leak check below would pass on a function that had stopped deriving one at all.
+    expect(id).toEqual(expect.any(String));
     expect(portSlotsFromToken(TOKEN)).not.toContain(id);
     // And none of them is the old fixed alphabet, which is what made the hostnames guessable.
     expect(portSlotsFromToken(TOKEN).some((slot) => slot.length === 1)).toBe(false);

package/src/webext-links.ts

@@ -0,0 +1,90 @@
+/* THE ZOD-FREE HALF OF THE BROWSER CONNECTOR'S WIRE: three URL builders, one code format, two message names.
+ *
+ * Split out of webext-protocol.ts for exactly one reason, and it is a real one rather than tidiness. A browser
+ * extension's CONTENT SCRIPT — the few lines that run on the sandbox's own page to hand a pairing code over —
+ * needs two of these constants and nothing else. Importing them through the contract's barrel pulls in every
+ * schema this repo has and the whole of zod with them: measured at 1.1 MB of JavaScript injected into a page,
+ * for two strings. Nothing here imports anything, so that file is now a few hundred bytes.
+ *
+ * The rule for what may live here: no imports, ever. A zod schema in this file would undo the split silently.
+ */
+
+// The URL the extension dials, given the sandbox's public URL. Carries no credential — the token rides the
+// hello frame (webext-protocol.ts). One place builds it, so the extension and the daemon route cannot disagree
+// about where the door is.
+export const webextConnectUrl = (sandboxUrl: string): string => `${sandboxUrl.replace(/^http/, "ws").replace(/\/$/, "")}/system/webext/connect`;
+
+/* Where the extension POSTS a site's session when the owner asks for one to be handed to the sandbox
+ * ("Connect this site"), authenticated by the same enrollment token as a bearer.
+ *
+ * A SEPARATE DOOR FROM THE SOCKET, deliberately, and this is the load-bearing decision of that feature: the
+ * socket's answers are MCP tool results, which means they land in the agent's context. Cookies must never do
+ * that. So the payload goes browser → daemon directly, the agent's tool call gets back a sentence and a count,
+ * and the one thing that would be catastrophic to leak is the one thing the model never sees. */
+export const webextSessionUrl = (sandboxUrl: string): string => `${sandboxUrl.replace(/\/$/, "")}/system/webext/session`;
+
+/* The same door in the other direction: where the extension asks for a sandbox account's session to be LENT to
+ * this browser, so the owner can finish a step no remote browser can do — a passkey, a hardware second factor,
+ * an employer's SSO that checks the device.
+ *
+ * A separate path rather than a verb on the one above, because the two are different acts with different
+ * refusals ("no such account" versus "that account is not signed in there") and a single endpoint doing both
+ * would have to be read twice to know which. Same bearer, and the same rule about the socket: the cookies come
+ * back on THIS request, never as an MCP result. */
+export const webextLendUrl = (sandboxUrl: string): string => `${sandboxUrl.replace(/\/$/, "")}/system/webext/lend`;
+
+/* ---- the pairing code: the one string that travels from the sandbox's card into the extension ----
+ *
+ * A connected computer is paired by a shell one-liner, which can carry two values in two environment variables
+ * because a terminal is a place where long strings are normal. A browser extension's popup is not: what a
+ * person will actually do there is paste ONE thing, once, and anything that asks them to copy a URL into one
+ * box and a token into another is a flow that fails on the second box.
+ *
+ * So both halves ride in one code. It is not encryption and does not pretend to be — base64url of two fields,
+ * so that the thing on the clipboard is opaque enough not to be edited by hand, short enough to paste, and
+ * carries its own sandbox address, which is the field a person could not possibly be expected to type. The
+ * secret in it is the pairing token, which is single-use and expires in ten minutes (webext-store.ts).
+ *
+ * The prefix is a version marker, and it is here so that a code from an older sandbox meets a clear "this code
+ * is from a different version" in the extension rather than a JSON parse error. */
+const PAIRING_PREFIX = "ixb1_";
+
+const base64url = (value: string): string => btoa(value).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+
+export const webextPairingCode = (pairing: { readonly url: string; readonly token: string }): string =>
+    `${PAIRING_PREFIX}${base64url(JSON.stringify({ url: pairing.url, token: pairing.token }))}`;
+
+// The extension's side. Undefined for anything that is not one of ours, so a person who pasted the wrong thing
+// is told that rather than watching a connection attempt to nowhere.
+export const parseWebextPairingCode = (code: string): { readonly url: string; readonly token: string } | undefined => {
+    const trimmed = code.trim();
+    if (!trimmed.startsWith(PAIRING_PREFIX)) {
+        return undefined;
+    }
+    try {
+        const decoded = JSON.parse(atob(trimmed.slice(PAIRING_PREFIX.length).replaceAll("-", "+").replaceAll("_", "/"))) as {
+            url?: unknown;
+            token?: unknown;
+        };
+        // An http(s) URL and a non-empty token, or nothing: the extension is about to open a socket to whatever
+        // this says, so "looks like a URL" is checked here rather than by the WebSocket constructor throwing.
+        if (typeof decoded.url !== "string" || typeof decoded.token !== "string" || decoded.token === "" || !/^https?:\/\//.test(decoded.url)) {
+            return undefined;
+        }
+        return { url: decoded.url, token: decoded.token };
+    } catch {
+        return undefined;
+    }
+};
+
+/* How the sandbox's own page hands that code over without anybody copying anything: it posts this message on
+ * its own window, and the extension's content script (which is only ever loaded on the sandbox's own origins)
+ * picks it up and answers.
+ *
+ * A window message rather than `chrome.runtime.sendMessage` from the page, which would be the obvious route,
+ * because that one needs the extension's STORE ID baked into the web app — a value that does not exist until
+ * the listing is approved, differs for an unlisted build, and would make a locally-loaded extension
+ * un-pairable. A window message needs neither side to know the other's identity: the content script is proof
+ * enough that the extension is installed, and the page's origin is proof enough for the extension. */
+export const WEBEXT_PAIR_MESSAGE = "intentic:webext:pair";
+export const WEBEXT_PAIRED_MESSAGE = "intentic:webext:paired";

package/src/webext-protocol.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+
+/* The handshake on /system/webext/connect, the ONE message on that socket that is not oRPC.
+ *
+ * Same two-phase shape as a connected computer's (host-protocol.ts) and for the same reason: the daemon has
+ * nothing to call until it knows whose socket this is, so the proof cannot itself be an oRPC call. The browser
+ * extension's first frame carries its enrollment token, the daemon resolves WHICH capability it belongs to, and
+ * from that message on every byte is `webextContract` with the EXTENSION serving.
+ *
+ * WHY A SEPARATE PROTOCOL FROM host's, when the frame is the same two fields: because the thing on the other
+ * end is not a computer. It has no shell, no filesystem and no screen; what it has is tabs, origins the person
+ * granted one at a time, and a human watching every click. Sharing the host's schema would have meant a card of
+ * switches that mean nothing (`roots`, `sandboxRemove`) and an agent told about a home directory it cannot
+ * reach. The two connectors are siblings, not one connector with a flag. */
+
+export const WebExtHelloSchema = z.object({
+    type: z.literal("hello"),
+    /* The extension's enrollment token, in the FIRST FRAME, never in the URL: a WebSocket has no headers, and
+     * `?token=` would write a durable key into every proxy log between a browser and the sandbox. Until this
+     * arrives the socket is anonymous and short-lived. */
+    token: z.string(),
+    // The extension build the browser is running. Surfaced per connection so an old, un-updated extension is
+    // visible rather than mysteriously missing a tool. What the BROWSER is (`describe`) 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 WebExtHello = z.infer<typeof WebExtHelloSchema>;

package/src/workflow-faults.test.ts

@@ -1,5 +1,5 @@
 import { expect, test } from "vitest";
-import { type Workflow, WorkflowSchema, type WorkflowStep } from "./schemas.js";
+import { type Workflow, WorkflowSchema, type WorkflowStep } from "./schemas/workflows.js";
 import { workflowFaults, workflowRunFaults } from "./workflow-faults.js";
 
 /* The GATE rules. The graph rules beside them are exercised by the scheduler's own integration tests, which

package/src/workflow-faults.ts

@@ -7,7 +7,7 @@
  */
 
 import { duplicateOutputFieldNames } from "./output-fields.js";
-import type { Workflow, WorkflowStep } from "./schemas.js";
+import type { Workflow, WorkflowStep } from "./schemas/workflows.js";
 
 // One id, one node: the scheduler keys needs, runs and the drawn graph by it, so a repeat makes the same node
 // mean two things.

package/src/workspace-state.test.ts

@@ -100,8 +100,8 @@ describe(`staleQueryKeys`, () => {
         // The two lists are unioned flat, not layered: a narrow extension entry under a broad core entry that
         // invalidates nothing must still fire. Without this, every path beneath one of the daemon's
         // machine-state prefixes would be unreachable to extensions.
-        const nested: readonly FileContribution[] = [{ path: `${STATE_DIR}/records/sessions/claude/projects/p/memory/`, invalidates: [`memory`] }];
-        expect(staleQueryKeys([`.intentic/records/sessions/claude/projects/p/memory/note.md`], nested)).toEqual([`memory`]);
+        const nested: readonly FileContribution[] = [{ path: `${STATE_DIR}/records/sessions/claude/plans/`, invalidates: [`plans`] }];
+        expect(staleQueryKeys([`.intentic/records/sessions/claude/plans/a-plan.md`], nested)).toEqual([`plans`]);
         // …and a sibling under the same core prefix stays ignored.
         expect(staleQueryKeys([`.intentic/records/sessions/claude/projects/p/session.jsonl`], nested)).toEqual([]);
     });
@@ -162,7 +162,9 @@ describe(`WORKSPACE_STATE_FILES`, () => {
         // the difference visible at review time.
         for (const file of WORKSPACE_STATE_FILES) {
             if (file.invalidates.length === 0) {
-                expect(file.why, `${file.path} invalidates nothing and must say why`).toBeTruthy();
+                // A string with something in it. Truthiness would accept the number 1 or an object, and the
+                // failure this guards against — a `why` left blank to quiet the check — reads as whitespace.
+                expect(file.why, `${file.path} invalidates nothing and must say why`).toEqual(expect.stringMatching(/\S/));
             } else {
                 expect(file.why, `${file.path} invalidates queries, so \`why\` is dead weight`).toBeUndefined();
             }
@@ -198,7 +200,7 @@ describe(`WORKSPACE_STATE_FILES`, () => {
         for (const file of WORKSPACE_STATE_FILES) {
             for (const parent of WORKSPACE_STATE_FILES.filter((other) => other !== file && file.path.startsWith(other.path))) {
                 expect(
-                    parent.portability === file.portability && parent.invalidates.join() === file.invalidates.join(),
+                    parent.portability === file.portability && parent.invalidates.join(",") === file.invalidates.join(","),
                     `${file.path} says nothing its parent ${parent.path} doesn't already say`,
                 ).toBe(false);
             }