@intentic/sandbox-contract 1.166.0 → 1.168.0

package/src/title.ts

@@ -15,8 +15,12 @@
  * names a turn that arrived without one — an automation, a Discord message, a webchat visitor (agents-
  * registry.ts). One rule, because two would let the same prompt open under two different names depending on
  * where it entered. Nothing here calls a model: the title has to exist before the first frame comes back.
- * (A model DOES get its say later — the daemon's title-summary pass renames a still-derived title once the
- * first turn has an answer to read — but that is a promotion over this title, never a replacement for it.) */
+ *
+ * Which is exactly the ceiling on it. Cutting is not naming — what comes out is the user's own sentence,
+ * shortened, and a column of those is scannable only where the users' sentences happened to differ early. The
+ * name a conversation ends up WEARING is written a second or two later by a model that reads the same prompt
+ * and answers in the fleet board's own shape (the daemon's title-namer.ts). This is the title that holds the
+ * tab until that arrives, and the one it keeps if nothing is connected to write a better one. */
 
 // The registry's title budget (agents-registry MAX_TITLE_LENGTH, the rename input's maxlength) — the widest
 // any surface stores. Every surface truncates in CSS to its own width, so the clamp here is a storage cap,

package/src/workspace-state.test.ts

@@ -0,0 +1,129 @@
+import type { FileContribution } from "@intentic/extension-api";
+import { describe, expect, it } from "vitest";
+import { staleQueryKeys, WORKSPACE_STATE_FILES } from "./workspace-state.js";
+
+// What the automations extension declares in its manifest, and what the memory extension WOULD declare if the
+// watcher reported its files. Literals rather than the real manifests: an extension package importing this one is
+// the dependency direction, so reaching back for them here would invert it. The real manifests are checked
+// against this rule where they are loaded — web's fileBindings.test.ts and the daemon's file-bindings.test.ts.
+const AUTOMATIONS: readonly FileContribution[] = [
+    { path: `.intentic/automations.json`, invalidates: [`automations`] },
+    { path: `.intentic/approvals/`, invalidates: [`automation-approvals`] },
+];
+
+describe(`staleQueryKeys`, () => {
+    it(`maps a manifest write to the queries it makes stale`, () => {
+        expect(staleQueryKeys([`.intentic/capabilities.json`], [])).toEqual([`capabilities`, `environment`, `panels`]);
+    });
+
+    it(`matches a name family and a one-file-per-entry directory through one prefix each`, () => {
+        // environment.Dockerfile, environment.custom.Dockerfile, environment.approved.Dockerfile — one entry.
+        expect(staleQueryKeys([`.intentic/environment.custom.Dockerfile`], [])).toEqual([`environment`]);
+        expect(staleQueryKeys([`.intentic/drafts/post-1.json`], [])).toEqual([`drafts`]);
+    });
+
+    it(`refreshes the Drafts view when the AGENT writes a draft`, () => {
+        // The regression this table was reorganized around: the drafts skill writes these files directly, so
+        // there is no browser mutation to hang an invalidate on — the watcher push is the only signal, and it
+        // used to be dropped on the floor.
+        expect(staleQueryKeys([`.intentic/drafts/post-1.json`], [])).toEqual([`drafts`]);
+    });
+
+    it(`ignores unrelated churn under .intentic/`, () => {
+        // The amplification that turned an iq index rebuild into an endless request storm: a prefix test on
+        // `.intentic/` alone would invalidate every one of these queries for each index write.
+        expect(staleQueryKeys([`.intentic/iq/index.db`, `.intentic/claude/projects/p/session.jsonl`], [])).toEqual([]);
+    });
+
+    it(`ignores a store's own temp file while it is mid-swap`, () => {
+        // jsonFile writes `.<name>.<pid>.tmp` beside the target precisely so the atomic rename can't be read as
+        // a write to the target itself. A trailing-tag temp would prefix-match and bill an extra refetch.
+        expect(staleQueryKeys([`.intentic/.settings.json.42.tmp`], [])).toEqual([]);
+        expect(staleQueryKeys([`.intentic/settings.json`], [])).toEqual([`settings`]);
+    });
+
+    it(`ignores ordinary workspace edits`, () => {
+        expect(staleQueryKeys([`src/main.ts`, `README.md`], [])).toEqual([]);
+    });
+
+    it(`dedupes keys across a batch that touches several manifests`, () => {
+        // A capability add recomposes the overlay, so both entries claim `environment` — one refetch, not two.
+        expect(staleQueryKeys([`.intentic/capabilities.json`, `.intentic/environment.Dockerfile`], [])).toEqual([
+            `capabilities`,
+            `environment`,
+            `panels`,
+        ]);
+    });
+
+    it(`invalidates an extension's queries from its own declaration`, () => {
+        expect(staleQueryKeys([`.intentic/automations.json`], AUTOMATIONS)).toEqual([`automations`]);
+        expect(staleQueryKeys([`.intentic/approvals/a1.json`], AUTOMATIONS)).toEqual([`automation-approvals`]);
+    });
+
+    it(`makes nothing stale for an extension that is not running`, () => {
+        // The reason the live set is passed in rather than read off the installed list: `automations` is the
+        // extension's query key, so with the extension gone there is no cache entry for it to be about. The core
+        // table used to carry these two keys itself, and would have kept invalidating them either way.
+        expect(staleQueryKeys([`.intentic/automations.json`, `.intentic/approvals/a1.json`], [])).toEqual([]);
+    });
+
+    it(`lets an extension claim a path the core table deliberately ignores`, () => {
+        // 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: `.intentic/claude/projects/p/memory/`, invalidates: [`memory`] }];
+        expect(staleQueryKeys([`.intentic/claude/projects/p/memory/note.md`], nested)).toEqual([`memory`]);
+        // …and a sibling under the same core prefix stays ignored.
+        expect(staleQueryKeys([`.intentic/claude/projects/p/session.jsonl`], nested)).toEqual([]);
+    });
+
+    it(`dedupes a key two extensions both claim`, () => {
+        const twice: readonly FileContribution[] = [
+            { path: `.intentic/automations.json`, invalidates: [`automations`] },
+            { path: `.intentic/automations.json`, invalidates: [`automations`] },
+        ];
+        expect(staleQueryKeys([`.intentic/automations.json`], twice)).toEqual([`automations`]);
+    });
+});
+
+describe(`WORKSPACE_STATE_FILES`, () => {
+    it(`declares every entry under .intentic/, root-relative and forward-slash`, () => {
+        for (const file of WORKSPACE_STATE_FILES) {
+            expect(file.path.startsWith(`.intentic/`), file.path).toBe(true);
+            expect(file.path.includes(`\\`), file.path).toBe(false);
+        }
+    });
+
+    it(`states a reason for every entry that invalidates nothing`, () => {
+        // An empty `invalidates` is a real answer (daemon machine state, a deliberately-polled surface, a path
+        // whose query keys belong to an extension), but a SILENT one is indistinguishable from the omission this
+        // table exists to prevent — which is exactly how drafts went missing. Requiring the reason is what makes
+        // 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();
+            } else {
+                expect(file.why, `${file.path} invalidates queries, so \`why\` is dead weight`).toBeUndefined();
+            }
+        }
+    });
+
+    it(`keeps directory entries slash-terminated so they cannot swallow a sibling`, () => {
+        // `.intentic/drafts` without the slash would also prefix-match a future `.intentic/drafts-archive.json`.
+        for (const file of WORKSPACE_STATE_FILES.filter((entry) => entry.invalidates.length > 0)) {
+            const isFamilyPrefix = file.path.endsWith(`.`);
+            const isFile = file.path.endsWith(`.json`) || file.path.endsWith(`.Dockerfile`);
+            expect(isFile || isFamilyPrefix || file.path.endsWith(`/`), file.path).toBe(true);
+        }
+    });
+
+    it(`has no entry that prefix-matches another, so one write can't be billed twice`, () => {
+        for (const file of WORKSPACE_STATE_FILES) {
+            const overlapping = WORKSPACE_STATE_FILES.filter((other) => other !== file && other.path.startsWith(file.path));
+            expect(
+                overlapping.map((other) => other.path),
+                `${file.path} is a prefix of another entry`,
+            ).toEqual([]);
+        }
+    });
+});

package/src/workspace-state.ts

@@ -0,0 +1,160 @@
+import type { FileContribution } from "@intentic/extension-api";
+
+/* WHICH WORKSPACE FILE BACKS WHICH CORE VIEW — one declaration, read by both sides of the wire.
+ *
+ * The daemon's own state lives under `<workspace>/.intentic/`, the agent edits it out-of-band with its file
+ * tools, and the file watcher pushes every change as a `workspaceChanged` batch. Turning those paths back into
+ * "and therefore this view is stale" used to be a hand-written table in the BROWSER (web's systemEventRouting),
+ * maintained separately from the paths the daemon actually writes (composition.ts) — two lists of the same
+ * fact, in two packages, with nothing tying them together.
+ *
+ * They drifted, exactly as that shape always does. `.intentic/drafts/` is written by the AGENT (the drafts
+ * skill puts a file there) and rendered by the Drafts view, but it was never added to the browser's table — so
+ * a draft appearing on disk while the owner watched the page changed nothing until they refocused the tab.
+ * Extension settings and the members list were missing for the same reason; writing them out is what showed
+ * that neither is a drafts-shaped hole — see their entries.
+ *
+ * So the binding is declared HERE, once, in the package both the daemon and the browser already import, and
+ * each side derives what it needs: the daemon builds its store paths from `path`, the browser builds its
+ * invalidation table from `invalidates`. Adding a manifest without saying what it makes stale is now a change
+ * to one visible list rather than an omission in a file nobody edits — and `workspace-state.test.ts` fails when
+ * a daemon store names a `.intentic` path this list doesn't carry.
+ *
+ * This mirrors what routes.ts does for the route surface ("nothing is generated and nothing is hand-maintained")
+ * one layer over: the same refusal to keep the same knowledge in two places.
+ *
+ * EXTENSIONS declare their own half in their manifest (`contributes.files`, @intentic/extension-api), in the same
+ * two fields, and the browser unions the two lists — see staleQueryKeys. That split is what this table is FOR:
+ * before it existed the core enumeration had to carry `automations` and `automation-approvals`, query keys owned
+ * by the automations extension, because the extension had no way to say so itself. A key belongs to whoever
+ * queries it. */
+
+// A core entry is an extension's `contributes.files` entry plus the one thing only the core list needs: the
+// right to declare NO invalidations, which for a daemon-owned file is the answer more often than not.
+export interface WorkspaceStateFile {
+    /* Workspace-root-relative, forward-slash — the space `workspaceChanged` paths arrive in. Matching is by
+     * PREFIX, which lets one entry cover three shapes without a second matching rule:
+     *   - an exact file      `.intentic/settings.json`
+     *   - a directory        `.intentic/drafts/`     (one file per draft)
+     *   - a name family      `.intentic/environment.` (…Dockerfile, .custom.Dockerfile, .approved.Dockerfile)
+     * A directory entry keeps its trailing slash so it can never prefix-match a sibling file. */
+    readonly path: string;
+    /* The browser query keys this file's contents feed. EMPTY is a real answer, not a gap — a file the browser
+     * renders nothing from, or one deliberately kept off the push path — and `why` says which. Never a prefix
+     * test over `.intentic/` as a whole: one stray write must not cost every view a refetch, which is the
+     * amplification that once turned an iq index rebuild into an endless request storm. */
+    readonly invalidates: readonly string[];
+    // Why this file has no invalidations, for the entries that declare none. Absent when it has some.
+    readonly why?: string;
+}
+
+export const WORKSPACE_STATE_FILES: readonly WorkspaceStateFile[] = [
+    // A capability add/remove recomposes the environment overlay and can add or drop a repo's panel.
+    { path: ".intentic/capabilities.json", invalidates: ["capabilities", "environment", "panels"] },
+    { path: ".intentic/environment.", invalidates: ["environment"] },
+    { path: ".intentic/settings.json", invalidates: ["settings"] },
+    // Written by the AGENT's file tools (the drafts skill), read by the owner's approval inbox — the one entry
+    // here whose whole point is that a change arrives from outside the browser that renders it.
+    { path: ".intentic/drafts/", invalidates: ["drafts"] },
+    // ---- declared by the extension that renders them (contributes.files), not here ----
+    // The path is the DAEMON's (automations-store writes both), the query keys are the intentic.automations
+    // extension's. It declares them in its own manifest and the browser unions the two lists, so uninstalling
+    // the extension takes its invalidations with it instead of leaving a rule for a view that no longer exists.
+    {
+        path: ".intentic/automations.json",
+        invalidates: [],
+        why: "Declared by the intentic.automations extension's contributes.files — `automations` is its query key, not core's.",
+    },
+    {
+        path: ".intentic/approvals/",
+        invalidates: [],
+        why: "Declared by the intentic.automations extension's contributes.files — `automation-approvals` is its query key, not core's.",
+    },
+
+    /* ---- reached by no query, for reasons that are not oversights ----
+     *
+     * This channel's currency is a QUERY KEY, and invalidation only reaches a query something is observing.
+     * Both entries below are outside that by design, so an empty set is the honest record — naming a key no
+     * query uses would put the drift this table exists to remove straight back into it. Each says which
+     * constraint would have to move first, so the next reader doesn't re-derive it. */
+    {
+        path: ".intentic/extension-settings.json",
+        invalidates: [],
+        why: "Held in a module-level shallowRef store per extension (web's extensionSettingsStore) with no query observer, and deliberately so: api.settings.get must answer SYNCHRONOUSLY from an extension's first activate() line, and the store outlives every component scope. A module-level QueryObserver is the one shape that would make invalidation refetch, and this app already ruled it out — it detaches on the queryClient.clear() at logout (see useSandbox's sandbox-list mirror). So a remote member's setting edit reaches this browser on its next load, not live.",
+    },
+    {
+        path: ".intentic/members.json",
+        invalidates: [],
+        why: "Not this view's source at all: SandboxAccess renders the PLATFORM's invite records (apiClient.invite.list), and this file is the daemon's ENFORCED copy — written first so a grant the enforcer never got is never recorded, then never read back. A change here means the two disagreed, which the write order makes fail-closed rather than stale.",
+    },
+
+    // ---- daemon-owned, nothing derives from watching them ----
+    {
+        path: ".intentic/gate.json",
+        invalidates: [],
+        why: "The landing gate's verdict is POLLED on purpose (web's useGate). Its fingerprint pass rewrites this file every couple of seconds while a check runs, and pushing that back would refetch the review set — the daemon's most expensive read — on every poll.",
+    },
+    {
+        path: ".intentic/gate-index/",
+        invalidates: [],
+        why: "The gate's per-repo git index. Machine state, rewritten continuously by the fingerprint pass.",
+    },
+    /* Agent session transcripts, rewritten on every streamed token.
+     *
+     * The memory notes under it (`projects/<slug>/memory/**`) ARE user-facing and the /memory view polls them
+     * every 30s, which is the one place in this table where a poll survives a real change feed being available.
+     * It stays a poll deliberately: the watcher's exclusion is a DESCENT filter, so reaching those notes means
+     * letting it walk `.intentic/claude` → `projects` → every project slug. Measured on the live workspace that
+     * is +119 watched directories against ~593 today (a fifth more), with 314 continuously-rewritten transcripts
+     * inside the newly-watched set, to make ONE memory directory live. Notes change at agent-turn cadence, so the
+     * poll costs a request a minute and the alternative costs a permanent 20% on the watcher. */
+    {
+        path: ".intentic/claude/",
+        invalidates: [],
+        why: "Agent session transcripts — see the note above on why the memory notes under it stay polled.",
+    },
+    {
+        path: ".intentic/ci.json",
+        invalidates: [],
+        why: "Webhook secret + conclusion memory; the Pipelines view reads it through /ci/runs, not off disk.",
+    },
+    { path: ".intentic/bridge-tokens.json", invalidates: [], why: "Hashed ACP bridge tokens, listed on demand by the owner." },
+    {
+        path: ".intentic/owner.json",
+        invalidates: [],
+        why: "Bound once on first use; a change here means the sandbox was re-owned, which re-authenticates anyway.",
+    },
+    { path: ".intentic/workspace.json", invalidates: [], why: "The workspace identity, read from the /events hello frame rather than as a file." },
+    { path: ".intentic/templates.json", invalidates: [], why: "Scaffold templates, read when the scaffold dialog opens." },
+    {
+        path: ".intentic/browser/",
+        invalidates: [],
+        why: "Browser-login profiles: Chromium rewrites these constantly. Descent-ignored by the watcher outright.",
+    },
+    {
+        path: ".intentic/extensions/",
+        invalidates: [],
+        why: "Extension checkouts — whole git clones. The `extensions` query is driven by the capability manifest above, not by their contents.",
+    },
+    { path: ".intentic/plugins/", invalidates: [], why: "Agent plugin dirs, read by the SDK's loader each turn." },
+];
+
+/* The query keys a batch of changed paths makes stale, deduped and stable. The browser's `/events` handler calls
+ * this; keeping it here rather than in the web means the rule is unit-testable without a query client, and the
+ * daemon can assert against the same table.
+ *
+ * `contributed` is what the ACTIVATED extensions declared in `contributes.files` — passed in rather than
+ * imported, because which extensions are live is a browser fact this package has no way to know. It is a
+ * required argument for the same reason: an added second source that callers may forget is a source that
+ * silently does nothing, which is the failure this whole file exists to remove. Extension entries are unioned
+ * flat with the core ones, not layered over them: both lists describe the same fact about the same file, and a
+ * path can legitimately match one entry in each — a core prefix that invalidates nothing must not veto a
+ * narrower extension entry beneath it, or everything under one of the daemon's machine-state prefixes would be
+ * unreachable to extensions by construction. */
+export const staleQueryKeys = (paths: readonly string[], contributed: readonly FileContribution[]): readonly string[] => [
+    ...new Set(
+        [...WORKSPACE_STATE_FILES, ...contributed]
+            .filter((file) => file.invalidates.length > 0 && paths.some((path) => path.startsWith(file.path)))
+            .flatMap((file) => file.invalidates),
+    ),
+];