@intentic/sandbox-contract 1.328.0 → 1.330.0

package/src/schemas/workspace/workspace-graph.ts

@@ -0,0 +1,116 @@
+import { z } from "zod";
+
+// A monorepo's architecture as its files state it: the packages pnpm-workspace.yaml names, which siblings each declares
+// and what its own files do with them, and, inside one package, how its modules import each other. Facts only: what to
+// draw, and what counts as a finding, is the reader's.
+
+// A component of the repository's map, docs/architecture/repo.json, which the documentation extension writes.
+export const WorkspaceComponentSchema = z.object({
+    id: z.string().describe("The component's id."),
+    name: z.string().describe("What the map calls it."),
+    accent: z.string().optional().describe('The map\'s colour slot for it: "1" to "5", or "neutral".'),
+});
+export type WorkspaceComponent = z.infer<typeof WorkspaceComponentSchema>;
+
+// A pnpm-workspace package, discovered from pnpm-workspace.yaml's globs. group is the top-level dir segment; component
+// is the repo.json component listing its dir, when the repository has a map.
+export const WorkspacePackageSchema = z.object({
+    name: z.string().describe("The name the package declares."),
+    dir: z.string().describe("Where it lives, relative to the repository."),
+    group: z.string().describe("The top-level folder it sits under, which is what a diagram colours by."),
+    component: z.string().optional().describe("The component of docs/architecture/repo.json that lists it, by id. Absent without a map."),
+});
+export type WorkspacePackage = z.infer<typeof WorkspacePackageSchema>;
+export const WorkspaceDepTypeSchema = z.enum(["prod", "dev", "peer"]);
+export type WorkspaceDepType = z.infer<typeof WorkspaceDepTypeSchema>;
+
+// What the dependent's own files do with a sibling it declares, read from them: the strongest use found wins.
+export const WorkspaceDepUsageSchema = z
+    .enum(["code", "types", "tooling", "reference", "none"])
+    .describe(
+        "What the dependent's own files do with it: `code`, a shipped file imports a value from it; `types`, shipped files import only its types; `tooling`, only its tests, scripts and config files use it; `reference`, a shipped file names it without importing it (a Dockerfile copying its build, a manifest listing its files); `none`, nothing in the dependent names it.",
+    );
+export type WorkspaceDepUsage = z.infer<typeof WorkspaceDepUsageSchema>;
+
+// A workspace-internal dependency edge: from depends on to, typed by which dependency block declared it.
+export const WorkspaceDepEdgeSchema = z.object({
+    from: z.string().describe("The package that depends."),
+    to: z.string().describe("The package it depends on."),
+    type: WorkspaceDepTypeSchema.describe("Which kind of dependency declared it."),
+    usage: WorkspaceDepUsageSchema.optional(),
+});
+export type WorkspaceDepEdge = z.infer<typeof WorkspaceDepEdgeSchema>;
+export const WorkspaceGraphSchema = z.object({
+    packages: z.array(WorkspacePackageSchema).describe("Every package in the repository."),
+    edges: z.array(WorkspaceDepEdgeSchema).describe("Which of them use which. Pure data: how to lay it out is yours to decide."),
+    components: z
+        .array(WorkspaceComponentSchema)
+        .optional()
+        .describe("The components of docs/architecture/repo.json, in the map's order. Absent when the repository has no map."),
+});
+export type WorkspaceGraph = z.infer<typeof WorkspaceGraphSchema>;
+
+// layers.json beside a package's package.json: the layers its modules sit in, lowest first. A module may import its own
+// layer and any below it; an import reaching higher is a finding, and so is a cycle between units of one layer.
+export const PackageLayerSchema = z.object({
+    name: z.string().min(1).describe("The layer's name."),
+    about: z.string().optional().describe("What sits in it, in a sentence."),
+    units: z
+        .array(z.string().min(1))
+        .describe(
+            "Path prefixes under the root it holds: a directory, a subdirectory, or a module named without its extension. A file belongs to the layer whose unit matches it longest.",
+        ),
+});
+export type PackageLayer = z.infer<typeof PackageLayerSchema>;
+export const PackageLayersFileSchema = z.object({
+    root: z.string().optional().describe('The directory the units are relative to, from the package. Default "src".'),
+    shelves: z.array(z.string()).optional().describe("Top-level directories whose every subdirectory is a unit of its own, such as one per feature."),
+    surface: z
+        .array(z.string())
+        .optional()
+        .describe('File-name patterns, `*` a wildcard, of modules that sit above every layer, such as "*.routes.ts". Nothing below may import one.'),
+    layers: z.array(PackageLayerSchema).min(1).describe("The layers, lowest first."),
+});
+export type PackageLayersFile = z.infer<typeof PackageLayersFileSchema>;
+
+export const PackageModulesParamSchema = z.object({
+    repo: z.string().describe("Which repository."),
+    package: z.string().min(1).describe("Which of its workspace packages, by the name it declares."),
+});
+export const PackageUnitSchema = z.object({
+    id: z
+        .string()
+        .describe(
+            'The unit: a directory under the root, a shelf\'s subdirectory ("features/chat"), a unit layers.json names, "(surface)" for every surface module, or "(root)" for the modules directly in the root, which no rule judges.',
+        ),
+    modules: z.number().int().nonnegative().describe("How many source modules it holds."),
+    layer: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe("The declared layer it sits in, by index, lowest 0. Absent when the package declares no layers, or none places it."),
+    surface: z.literal(true).optional().describe("The surface modules' unit, above every layer."),
+});
+export type PackageUnit = z.infer<typeof PackageUnitSchema>;
+export const PackageUnitEdgeSchema = z.object({
+    from: z.string().describe("The importing unit."),
+    to: z.string().describe("The unit it imports."),
+    imports: z.number().int().positive().describe("How many value imports make the edge."),
+    sites: z.array(z.string()).describe("Up to five of them, as `path:line` relative to the root."),
+});
+export type PackageUnitEdge = z.infer<typeof PackageUnitEdgeSchema>;
+export const PackageModulesSchema = z.object({
+    package: z.string().describe("The package."),
+    root: z.string().describe("The directory read, relative to the repository."),
+    layers: z
+        .array(PackageLayerSchema.pick({ name: true, about: true }))
+        .optional()
+        .describe("Its declared layers, lowest first. Absent when it has no layers.json."),
+    invalid: z.string().optional().describe("Why its layers.json could not be read, when it has one that does not parse."),
+    units: z.array(PackageUnitSchema).describe("Every unit with a module in it."),
+    edges: z
+        .array(PackageUnitEdgeSchema)
+        .describe("Value imports between units: type-only imports erase and tests import their subject, so neither counts."),
+});
+export type PackageModules = z.infer<typeof PackageModulesSchema>;

package/src/schemas/workspace/workspace-repos.ts

@@ -91,28 +91,6 @@ export const RepoAppSchema = z.object({
 export type RepoApp = z.infer<typeof RepoAppSchema>;
 export const AppsListSchema = z.object({ apps: z.array(RepoAppSchema).describe("The apps in this repository.") });
 export type AppsList = z.infer<typeof AppsListSchema>;
-// A pnpm-workspace package, discovered from pnpm-workspace.yaml's globs. group is the top-level dir segment, the
-// dependencies view's coloring axis.
-export const WorkspacePackageSchema = z.object({
-    name: z.string().describe("The name the package declares."),
-    dir: z.string().describe("Where it lives, relative to the repository."),
-    group: z.string().describe("The top-level folder it sits under, which is what a diagram colours by."),
-});
-export type WorkspacePackage = z.infer<typeof WorkspacePackageSchema>;
-export const WorkspaceDepTypeSchema = z.enum(["prod", "dev", "peer"]);
-export type WorkspaceDepType = z.infer<typeof WorkspaceDepTypeSchema>;
-// A workspace-internal dependency edge: from depends on to, typed by which dependency block declared it.
-export const WorkspaceDepEdgeSchema = z.object({
-    from: z.string().describe("The package that depends."),
-    to: z.string().describe("The package it depends on."),
-    type: WorkspaceDepTypeSchema.describe("Which kind of dependency declared it."),
-});
-export type WorkspaceDepEdge = z.infer<typeof WorkspaceDepEdgeSchema>;
-export const WorkspaceGraphSchema = z.object({
-    packages: z.array(WorkspacePackageSchema).describe("Every package in the repository."),
-    edges: z.array(WorkspaceDepEdgeSchema).describe("Which of them use which. Pure data: how to lay it out is yours to decide."),
-});
-export type WorkspaceGraph = z.infer<typeof WorkspaceGraphSchema>;
 // Path params for the per-repo apps routes: repo names the monorepo, validated like PanelRepoParam.
 export const RepoAppsParamSchema = z.object({ repo: z.string().describe("Which repository.") });
 export const AppParamSchema = z.object({

package/src/state/workspace-state.test.ts

@@ -5,6 +5,7 @@ import {
     isLockedWorkspacePath,
     isReportedManifest,
     isReviewableLockedPath,
+    isUnversionedStatePath,
     LOCKED_STATE_ENTRIES,
     lockedWorkspaceEntry,
     PLAN_DOCUMENTS_DIR,
@@ -29,7 +30,13 @@ const AUTOMATIONS: readonly FileContribution[] = [
 
 describe(`staleQueryKeys`, () => {
     it(`maps a manifest write to the queries it makes stale`, () => {
-        expect(staleQueryKeys([`.intentic/config/capabilities.json`], [])).toEqual([`capabilities`, `extensions`, `environment`, `panels`, `manifests`]);
+        expect(staleQueryKeys([`.intentic/config/capabilities.json`], [])).toEqual([
+            `capabilities`,
+            `extensions`,
+            `environment`,
+            `panels`,
+            `manifests`,
+        ]);
     });
 
     it(`refreshes the unreadable-manifest notice for the four files a person hand-edits`, () => {
@@ -299,6 +306,40 @@ describe(`isReviewableLockedPath`, () => {
     });
 });
 
+// What lets a git-reading reaction skip a batch: the daemon's own churn under `.intentic` must not rescan every repo,
+// while a tracked config file still has to.
+describe(`isUnversionedStatePath`, () => {
+    it(`holds the machine state the daemon rewrites constantly`, () => {
+        expect(isUnversionedStatePath(`.intentic/local/privacy-log.json`)).toBe(true);
+        expect(isUnversionedStatePath(`.intentic/local/.privacy-log.json.55.3275.tmp`)).toBe(true);
+        expect(isUnversionedStatePath(`.intentic/records/extension-usage.json`)).toBe(true);
+        expect(isUnversionedStatePath(`.intentic/records/artifacts/browser/page.png`)).toBe(true);
+        // An unversioned file beside versioned ones in config is still invisible to git.
+        expect(isUnversionedStatePath(`.intentic/config/docs/index.json`)).toBe(true);
+    });
+
+    it(`lets every versioned entry through, files and directories alike`, () => {
+        for (const path of VERSIONED_STATE_PATHS) {
+            const inside = path.endsWith(`/`) ? `${path}nested/file.json` : path;
+            expect([inside, isUnversionedStatePath(inside)]).toEqual([inside, false]);
+        }
+    });
+
+    it(`never claims a path outside the workspace's own state dir`, () => {
+        expect(isUnversionedStatePath(`intentic/_sandbox/sandbox/src/main.ts`)).toBe(false);
+        expect(isUnversionedStatePath(`README.md`)).toBe(false);
+        // A repo's nested state dir is its project's content, which git does track.
+        expect(isUnversionedStatePath(`myrepo/.intentic/local/privacy-log.json`)).toBe(false);
+        expect(isUnversionedStatePath(`.intentic`)).toBe(false);
+    });
+
+    it(`reads a platform path and a dot-relative one the same as a posix one`, () => {
+        expect(isUnversionedStatePath(`.intentic\\local\\privacy-log.json`)).toBe(true);
+        expect(isUnversionedStatePath(`./.intentic/local/privacy-log.json`)).toBe(true);
+        expect(isUnversionedStatePath(`./.intentic/config/capabilities.json`)).toBe(false);
+    });
+});
+
 describe(`VERSIONED_STATE_PATHS`, () => {
     // versioned exempts an entry from the `.intentic` exclusion; a mismarked credential can't be unmarked once
     // committed.

package/src/state/workspace-state.ts

@@ -397,7 +397,7 @@ const STATE_FILES = [
     {
         path: ".intentic/local/cache/",
         invalidates: [],
-        why: "Rebuildable indexes and caches, the iq index and its vector sidecar, the whisper model, fileq's derived/ markdown shadows of binary files; ignored by the watcher and recreated from carried workspace content.",
+        why: "Rebuildable indexes and caches, the iq index and its vector sidecar, the speech models an image does not bake, fileq's derived/ markdown shadows of binary files; ignored by the watcher and recreated from carried workspace content.",
         portability: "derived",
     },
     // Extension runtime scratch, one directory per extension via `extensionStateDir` below (the only way an extension
@@ -769,6 +769,17 @@ export const isReviewableLockedPath = (relPath: string): boolean => {
     return isLockedWorkspacePath(rel) && VERSIONED_STATE_PATHS.some((path) => (path.endsWith("/") ? rel.startsWith(path) : rel === path));
 };
 
+// Machine state the root repo never tracks: everything under the workspace's own `.intentic/` but the `versioned`
+// entries history.ts carves back out of the wholesale exclusion. A write here moves no git status, no landing and no
+// review, so a reaction that exists to re-read git can pass over a batch made only of these. The daemon rewrites
+// some of them every few seconds under load (the privacy ledger, extension usage, browser screenshots), and each
+// one used to rescan every repo. Root-level only, like the exclusion it mirrors: a repo's own nested `.intentic` is
+// its project's content. Accepts either slash.
+export const isUnversionedStatePath = (relPath: string): boolean => {
+    const rel = relPath.replaceAll("\\", "/").replace(/^\.\//, "");
+    return rel.startsWith(`${STATE_DIR}/`) && !VERSIONED_STATE_PATHS.some((path) => (path.endsWith("/") ? rel.startsWith(path) : rel === path));
+};
+
 // Every path this table declares, as a type; the daemon joins paths only through `statePath`
 // (workspace/state-paths.ts), which accepts one of these and nothing else, so renaming a store's file is a compile
 // error everywhere it's named rather than a view that silently stops refreshing.

package/src/text/transcript-page.test.ts

@@ -0,0 +1,39 @@
+import type { TranscriptRow, TranscriptTool } from "../events/transcript.js";
+import { fitNestedTool, fitPageRow, PAGE_TEXT_CAP } from "./transcript-page.js";
+
+// What a page carries of a row, which the daemon serves and the editor mirrors: the two have to agree to the byte.
+
+const long = `x`.repeat(PAGE_TEXT_CAP + 500);
+const call = (id: string, extra: Partial<TranscriptTool> = {}): TranscriptTool => ({
+    id,
+    name: `Bash`,
+    category: `execute`,
+    status: `completed`,
+    ...extra,
+});
+
+describe(`fitPageRow`, () => {
+    it(`hands back a row with no calls as it is`, () => {
+        const row: TranscriptRow = { role: `assistant`, text: `done` };
+        expect(fitPageRow(row)).toBe(row);
+    });
+
+    it(`keeps each output's start and counts a delegation's calls instead of carrying them`, () => {
+        const row: TranscriptRow = {
+            role: `assistant`,
+            text: ``,
+            tools: [call(`a`, { content: [{ type: `text`, text: long }] }), call(`b`, { name: `Agent`, children: [call(`c`), call(`d`)] })],
+        };
+        const fitted = fitPageRow(row);
+        expect(fitted.tools?.[0]?.content).toEqual([{ type: `text`, text: long.slice(0, PAGE_TEXT_CAP) }]);
+        expect(fitted.tools?.[1]?.children).toBeUndefined();
+        expect(fitted.tools?.[1]?.nested).toBe(2);
+    });
+});
+
+describe(`fitNestedTool`, () => {
+    it(`keeps every call under it, each output fitted at every depth`, () => {
+        const fitted = fitNestedTool(call(`a`, { children: [call(`b`, { content: [{ type: `text`, text: long }] })] }));
+        expect(fitted.children?.[0]?.content).toEqual([{ type: `text`, text: long.slice(0, PAGE_TEXT_CAP) }]);
+    });
+});

package/src/text/transcript-page.ts

@@ -0,0 +1,37 @@
+import type { ToolCallContent } from "../events/requests.js";
+import type { TranscriptRow, TranscriptTool } from "../events/transcript.js";
+
+// WHAT A TRANSCRIPT PAGE CARRIES OF A ROW, written once for both ends: the daemon fits every row of a page it serves to
+// this (sessions/agent-transcript.ts), and the editor fits the rows it mirrors to disk the same way, so a reopened chat
+// paints from its mirror exactly the rows the daemon's page then hands back, and keeps them rather than drawing them
+// again (transcriptState.ts rebuildKeeping matches rows by their contents).
+
+// What a page carries of one tool output: the pane truncates text at 4000 characters of its own accord
+// (toolPresentation.ts TEXT_CAP), so twice that leaves room to raise that cap without a second round trip.
+export const PAGE_TEXT_CAP = 8_000;
+
+const fitContent = (entry: ToolCallContent): ToolCallContent =>
+    entry.type === "text" && entry.text.length > PAGE_TEXT_CAP ? { ...entry, text: entry.text.slice(0, PAGE_TEXT_CAP) } : entry;
+
+// A delegation's own calls are left behind, counted rather than carried: the card draws collapsed until it is opened,
+// and the daemon answers that press with the calls themselves. On the records this was measured on they were 86% of the
+// bytes of the longest conversation.
+const fitPageTool = (tool: TranscriptTool): TranscriptTool => {
+    const { children, content, ...carried } = tool;
+    return {
+        ...carried,
+        ...(content !== undefined ? { content: content.map(fitContent) } : {}),
+        ...(children !== undefined && children.length > 0 ? { nested: children.length } : {}),
+    };
+};
+
+/** A row as a page carries it; a row with no calls is handed back as it is. */
+export const fitPageRow = <Row extends TranscriptRow>(row: Row): Row =>
+    row.tools === undefined ? row : { ...row, tools: row.tools.map(fitPageTool) };
+
+/** A call with everything under it, each output at every depth fitted the same way: what an opened delegation draws. */
+export const fitNestedTool = (tool: TranscriptTool): TranscriptTool => ({
+    ...tool,
+    ...(tool.content !== undefined ? { content: tool.content.map(fitContent) } : {}),
+    ...(tool.children !== undefined ? { children: tool.children.map(fitNestedTool) } : {}),
+});

package/dist/text/whisper.d.ts

@@ -1,3 +0,0 @@
-export declare const WHISPER_MODEL_REPO = "ggerganov/whisper.cpp";
-export declare const cleanTranscription: (stdout: string) => string | undefined;
-//# sourceMappingURL=whisper.d.ts.map

package/dist/text/whisper.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"whisper.d.ts","sourceRoot":"","sources":["../../src/text/whisper.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,kBAAkB,0BAA0B,CAAC;AAI1D,eAAO,MAAM,kBAAkB,WAAY,MAAM,KAAG,MAAM,GAAG,SAQ5D,CAAC"}

package/dist/text/whisper.js

@@ -1,11 +0,0 @@
-export const WHISPER_MODEL_REPO = "ggerganov/whisper.cpp";
-export const cleanTranscription = (stdout) => {
-    const text = stdout
-        .split("\n")
-        .map((line) => line.trim())
-        .filter((line) => line !== "" && !/^[[(].*[\])]$/.test(line))
-        .join(" ")
-        .trim();
-    return text === "" ? undefined : text;
-};
-//# sourceMappingURL=whisper.js.map

package/dist/text/whisper.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"whisper.js","sourceRoot":"","sources":["../../src/text/whisper.ts"],"names":[],"mappings":"AAIA,MAAM,CAAC,MAAM,kBAAkB,GAAG,uBAAuB,CAAC;AAI1D,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,MAAc,EAAsB,EAAE;IACrE,MAAM,IAAI,GAAG,MAAM;SACd,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;SAC1B,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,EAAE,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;SAC5D,IAAI,CAAC,GAAG,CAAC;SACT,IAAI,EAAE,CAAC;IACZ,OAAO,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1C,CAAC,CAAC"}

package/src/text/whisper.test.ts

@@ -1,18 +0,0 @@
-import { cleanTranscription } from "./whisper.js";
-
-test("flattens whisper output onto one line", () => {
-    expect(cleanTranscription(" Hello there.\n General Kenobi.\n")).toBe("Hello there. General Kenobi.");
-});
-
-// The whole reason this filter exists: whisper narrates silence, and a narration dispatched as speech is a
-// turn nobody asked for.
-test("drops noise-only annotations, in both bracket styles", () => {
-    expect(cleanTranscription(" [BLANK_AUDIO]\n")).toBeUndefined();
-    expect(cleanTranscription("(wind blowing)")).toBeUndefined();
-    expect(cleanTranscription("")).toBeUndefined();
-});
-
-// An annotation next to real speech drops the annotation and keeps the speech: the utterance did happen.
-test("keeps speech that arrived alongside an annotation", () => {
-    expect(cleanTranscription("[music] \nreal words")).toBe("real words");
-});

package/src/text/whisper.ts

@@ -1,17 +0,0 @@
-// Shared reading of whisper.cpp's stdout, used by the daemon's speech route and Discord's voice session, so both filter
-// non-speech annotations the same way.
-
-// Hugging Face repo the ggml-*.bin weights pull from on first use; each integration downloads its own size.
-export const WHISPER_MODEL_REPO = "ggerganov/whisper.cpp";
-
-// Cleans whisper's stdout to one line of text, or undefined for silence/noise-only output — a line that is entirely a
-// bracketed annotation like `[BLANK_AUDIO]`.
-export const cleanTranscription = (stdout: string): string | undefined => {
-    const text = stdout
-        .split("\n")
-        .map((line) => line.trim())
-        .filter((line) => line !== "" && !/^[[(].*[\])]$/.test(line))
-        .join(" ")
-        .trim();
-    return text === "" ? undefined : text;
-};