@intentic/sandbox-contract 1.248.0 → 1.249.0

package/src/state/definition.ts

@@ -0,0 +1,143 @@
+import { z } from "zod";
+import { NeedsActionSchema } from "../policy/needs-action.js";
+import { CapabilitySchema } from "../schemas/capabilities.js";
+import { SandboxSettingsSchema } from "../schemas/settings.js";
+
+// A definition is the reproducible half of a sandbox: repos as remotes, connections as shapes, the overlay as source
+// needing approval, secrets as names, never raw bytes (that's a bundle). Wire format is TOML (sandbox.toml); applying
+// it never bypasses consent, no credential ever travels.
+
+// One repository by reference: the workspace id, its clone remote, and an optional branch. No remote means it's
+// omitted, not invented.
+export const DefinitionRepositorySchema = z.strictObject({
+    // Workspace-relative repo id ("intentic", "clients/foo"), the same id the wire {repo} routes use.
+    id: z.string().min(1),
+    // The clone URL, verbatim from the source repo's own remote.
+    remote: z.string().min(1),
+    // The branch to check out; absent means the remote's default.
+    ref: z.string().optional(),
+});
+export type DefinitionRepository = z.infer<typeof DefinitionRepositorySchema>;
+
+// The /work git repo, by reference: tracks the owner's authored content (notes, skills, personas, automations, designs,
+// approvals). With a remote it's referenceable like any repo; without one it's omitted, not invented.
+export const DefinitionWorkspaceSchema = z.strictObject({
+    // The clone URL, verbatim from the workspace repo's own remote.
+    remote: z.string().min(1),
+    // The branch to check out; absent means the remote's default.
+    ref: z.string().optional(),
+});
+export type DefinitionWorkspace = z.infer<typeof DefinitionWorkspaceSchema>;
+
+export const DefinitionEnvironmentSchema = z.strictObject({
+    // The image the overlay extends, informational only; the target composes against its own base.
+    baseImage: z.string().optional(),
+    // The owner-approved overlay source, not the composed file or approval hash; consent doesn't travel with it.
+    dockerfile: z.string().optional(),
+});
+export type DefinitionEnvironment = z.infer<typeof DefinitionEnvironmentSchema>;
+
+// `.partial()` keeps each field's own `.default()`, so an absent key would still fill in at today's value. Unwrapping
+// first keeps it truly absent, so apply merges over the target's settings.
+// Strips both ZodDefault and ZodPrefault, in a loop: a field can be one wrapped inside the other.
+const bareField = (field: z.ZodType): z.ZodType => {
+    let inner = field;
+    while (inner instanceof z.ZodDefault || inner instanceof z.ZodPrefault) {
+        inner = inner.unwrap() as z.ZodType;
+    }
+    return inner;
+};
+
+const definitionSettings = (): z.ZodType<Partial<z.infer<typeof SandboxSettingsSchema>>> => {
+    const shape = Object.fromEntries(Object.entries(SandboxSettingsSchema.shape).map(([key, field]) => [key, bareField(field).optional()]));
+    return z.strictObject(shape).prefault({}) as unknown as z.ZodType<Partial<z.infer<typeof SandboxSettingsSchema>>>;
+};
+
+export const SandboxDefinitionSchema = z.strictObject({
+    // Bumped when the layout changes in a way an older daemon would misread; refused rather than guessed at.
+    schemaVersion: z.literal(1),
+    // What the source sandbox was called, for the reader; never used to authorize anything.
+    name: z.string().optional(),
+    environment: DefinitionEnvironmentSchema.prefault({}),
+    // The workspace repo, when it has a remote; absent is the ordinary unpublished state, not an error.
+    workspace: DefinitionWorkspaceSchema.optional(),
+    repositories: z.array(DefinitionRepositorySchema).prefault([]),
+    // Each connection in full (id, kind, config), never its credential; lands unauthenticated, waiting for one.
+    capabilities: z.array(CapabilitySchema).prefault([]),
+    // Secret names only, what the target should ask its owner for; values never enter a definition.
+    secrets: z.array(z.string()).prefault([]),
+    // Partial on purpose: states decisions only, a flag not mentioned keeps the target's own default.
+    settings: definitionSettings(),
+});
+export type SandboxDefinition = z.infer<typeof SandboxDefinitionSchema>;
+
+// A "do this by hand" line (bold subject, instruction detail), shared with the arrival surface.
+export { NeedsActionSchema, type NeedsAction } from "../policy/needs-action.js";
+
+// What GET /definition answers: the emitted TOML, plus anything the derivation couldn't express (e.g. a repo with no
+// remote), listed rather than silent.
+export const DefinitionExportSchema = z.object({
+    toml: z.string(),
+    omitted: z.array(NeedsActionSchema),
+});
+export type DefinitionExport = z.infer<typeof DefinitionExportSchema>;
+
+// Applying a definition happens through arrival.ts's shared pipeline (ArrivalPlan -> ArrivalApply -> ArrivalReport),
+// not a plan/apply/report trio here. This file only derives the document and diffs against it.
+
+// Where this sandbox stands relative to a definition: one line per difference, empty when they agree, computable since
+// the emitter is deterministic.
+export const DefinitionDiffSchema = z.object({
+    differences: z.array(NeedsActionSchema),
+});
+export type DefinitionDiff = z.infer<typeof DefinitionDiffSchema>;
+
+// Publishing /work to a remote (so [workspace] can name it) is its own route, not a side effect of export: an outward
+// act needs its own confirmation, and deriving a document must stay read-only.
+export const WorkspacePublishSchema = z.object({
+    // Given, an existing repo's URL is wired up and pushed to; nothing new is created.
+    remote: z.string().min(1).optional(),
+    // The repo to create when remote is absent; defaults to the sandbox's own name.
+    name: z.string().min(1).optional(),
+    // The account/org to create it under; absent means the authenticated user. Ignored when remote is given.
+    owner: z.string().min(1).optional(),
+});
+export type WorkspacePublish = z.infer<typeof WorkspacePublishSchema>;
+
+// Where the workspace now lives, and what a definition will name; created distinguishes making a repo from wiring up
+// one you gave.
+export const WorkspacePublishResultSchema = z.object({
+    remote: z.string(),
+    branch: z.string(),
+    created: z.boolean(),
+});
+export type WorkspacePublishResult = z.infer<typeof WorkspacePublishResultSchema>;
+
+// What the card shows before publishing: whether /work has a remote, and which connected hosts could make one.
+// Read-only, so the button can name the host directly.
+export const WorkspaceRemoteSchema = z.object({
+    remote: z.string().optional(),
+    branch: z.string().optional(),
+    // Hostnames of connected git accounts, in try order; empty means the owner must connect one or paste a URL.
+    hosts: z.array(z.string()),
+});
+export type WorkspaceRemote = z.infer<typeof WorkspaceRemoteSchema>;
+
+// A bundle is definition + state: the manifest embeds the same definition GET /definition emits; the tar carries what
+// no definition can reference. One schema, two doors, so the formats never disagree. An unknown version is refused.
+export const BundleManifestSchema = z.object({
+    // Bumped when the layout changes in a way an older daemon would misread; refused rather than guessed at.
+    version: z.literal(3),
+    // Where it came from, for the report's first line; never used to authorize anything.
+    sandbox: z.object({ name: z.string() }).optional(),
+    createdAt: z.number(),
+    // The owner's export choice, used only to explain gaps; the restorer re-derives from the manifests instead.
+    secrets: z.boolean(),
+    // Repos whose git dir rides along, by id, including ones with no remote to be named by. root isn't listed.
+    repos: z.array(z.string()),
+    // Exactly what a definition export emits, so restore reasons over the same facts either door gives.
+    definition: SandboxDefinitionSchema,
+    // Every path class left out, with a note when there is one; a silent skip becomes an actionable list.
+    excluded: z.array(z.object({ path: z.string(), portability: z.string(), note: z.string().optional() })),
+});
+export type BundleManifest = z.infer<typeof BundleManifestSchema>;

package/src/state/history-state.ts

@@ -0,0 +1,103 @@
+import type { StateFile } from "./state-portability.js";
+
+// /history holds daemon state outside /work's `.intentic/`: real git dirs (in-tree .git is a pointer file), the fleet
+// registry, turn journal, ledgers, checkpoint scopes, isolated checkouts. Nothing here is watched, unlike `.intentic`.
+// history-state-coverage.test.ts enforces this list stays complete.
+
+// historyRoot-relative paths, forward-slash, matched by prefix; a directory keeps its trailing slash so it can't
+// prefix-match a sibling file.
+export const HISTORY_STATE_FILES: readonly StateFile[] = [
+    /* ---- the machinery a restored workspace is inert without ---- */
+
+    // Every repo's real git dir, including root's own; missing it breaks a repo outright. Branches live here too.
+    { path: "gits/", portability: "carry" },
+    // Checkpoint timeline (one bare repo per scope); lets "restore to before that turn" still reach back.
+    { path: "scopes/", portability: "carry" },
+    // The fleet: every conversation card, its branch, session ids and standing.
+    { path: "agents.json", portability: "carry" },
+    { path: "turns/", portability: "carry" },
+    // Armed condition watches; carries safely: the journal holds no credential, only names re-derived on target.
+    { path: "watches/", portability: "carry" },
+    { path: "transcripts/", portability: "carry" },
+    // What each message can restore to (a checkpoint or isolated commit); the join between transcripts and scopes.
+    { path: "turn-anchors.json", portability: "carry" },
+    // Index of published-page conversations; the pages travel with /work anyway, this makes one withdrawable.
+    { path: "shares.json", portability: "carry" },
+    { path: "activity.jsonl", portability: "carry" },
+    { path: "usage.jsonl", portability: "carry" },
+    { path: "account-usage.json", portability: "carry" },
+    { path: "provider-refusals.json", portability: "carry" },
+    // Models refused to this sandbox's credentials; expires daily, same subscriptions apply elsewhere.
+    { path: "model-refusals.json", portability: "carry" },
+    // First-time dependency setup requests; carried so an interrupted queue survives export, entries self-remove.
+    { path: "dependency-requests.json", portability: "carry" },
+    // Which device cards were already offered; carry, not identity, since it holds ids, never a token.
+    { path: "host-setup-seeded.json", portability: "carry" },
+    // The deploy engine's own ledgers: a run's events and check results the Pipelines view reads.
+    { path: "apply-events.ndjson", portability: "carry" },
+    { path: "check-events/", portability: "carry" },
+
+    /* ---- regenerated by the target ---- */
+
+    // Deliberately omitted: the branch lives in gits/, the registry in agents.json; regenerated on the next turn.
+    {
+        path: "worktrees/",
+        portability: "derived",
+        note: "Each conversation re-attaches its checkout from its branch on its next turn.",
+    },
+    // Search phrase index, derived from transcripts/; rebuilt by the first boot's backfill instead of carried.
+    { path: "said-index/", portability: "derived", note: "Rebuilt from the carried transcripts by the first boot's backfill." },
+    { path: "overlays/", portability: "derived" },
+    { path: "logs/", portability: "derived" },
+    { path: "trash/", portability: "derived" },
+    { path: ".isolation-probe", portability: "derived" },
+    // Finished bundles, excluded so an export doesn't pack every prior export in; kept off /work, unwatched.
+    { path: "exports/", portability: "derived" },
+    // Bundles being taken in, mid-review; excluded as someone else's. Deleted on apply/abandon, swept after a crash.
+    { path: "arrivals/", portability: "derived" },
+
+    /* ---- credentials ---- */
+
+    // The ssh alias dir ~/.ssh/intentic-hosts symlinks to: per-host config, keys and passphrases.
+    {
+        path: "ssh-hosts/",
+        portability: "secret",
+        note: "Re-add each ssh host on the Capabilities view, its key does not travel.",
+    },
+    // The cli-proxy's config, which holds the routed subscriptions' provider tokens.
+    {
+        path: "translator/",
+        portability: "secret",
+        note: "Sign the routed AI subscriptions in again on the Agent tab.",
+    },
+
+    /* ---- identity: what binds this sandbox to its owner, its browsers and its host ---- */
+
+    // Signs every browser session cookie; carrying it would let the holder mint sessions against the target.
+    { path: "session-secret", portability: "identity", note: "Sign in again, the target signs its own sessions." },
+    {
+        path: "browser-access-disabled",
+        portability: "identity",
+        note: "Account-deletion retirement belongs to the source sandbox; the imported copy starts with fresh browser access.",
+    },
+    {
+        path: "push.json",
+        portability: "identity",
+        note: "Re-enable notifications in the browsers you use, a push subscription is bound to the sandbox that minted it.",
+    },
+    { path: "sync-enrollments.json", portability: "identity", note: "Re-pair desktop sync from the Sync tab." },
+    { path: "sync-pair-consumed.json", portability: "identity" },
+    { path: "host-enrollments.json", portability: "identity" },
+    // A connected browser's enrollment, paired to this sandbox; carrying it elsewhere is dead weight or worse.
+    { path: "webext-enrollments.json", portability: "identity", note: "Pair your browser again from its card: the extension is still installed." },
+    // The browser pairing burn list; a redeemed pairing must not read as fresh wherever this file travels.
+    { path: "webext-pair-consumed.json", portability: "identity" },
+    // Setup-device pairing burn list; carrying it would mark another sandbox's fresh pairing as spent.
+    { path: "host-pair-consumed.json", portability: "identity" },
+    // A runner's enrollment names this sandbox as parent; elsewhere its digest would dial the old parent.
+    { path: "runner-enrollments.json", portability: "identity" },
+    { path: "runner-pair-consumed.json", portability: "identity" },
+    // This container's own identity and reconnect token; elsewhere it would dial the parent as this runner.
+    { path: "runner-identity.json", portability: "identity" },
+    { path: "local-cert/", portability: "identity" },
+];

package/src/{runtime-state.test.ts → state/runtime-state.test.ts}

@@ -7,22 +7,16 @@ describe(`staleRuntimeQueryKeys`, () => {
     });
 
     it(`dedupes across a batch, because one sweep can move several domains at once`, () => {
-        // The port sampler publishes both: a dev server binding its port is a new port AND the panel above it
-        // turning healthy (panels.ts reads health off the listening sockets). Order is the TABLE's, not the
-        // frame's, so a repeated domain and a reordered frame produce the same list.
+        // ports also invalidates apps: the panel above it turns healthy too. Order follows the table, not the input.
         expect(staleRuntimeQueryKeys([`ports`, `panels`, `ports`])).toEqual([[`panels`], [`apps`], [`ports`]]);
     });
 
     it(`ignores a domain this build has never heard of`, () => {
-        // A daemon newer than the browser names domains this table doesn't carry. Refreshing what we understand
-        // and dropping the rest beats throwing away the whole frame.
         expect(staleRuntimeQueryKeys([`terminals`, `something-later`])).toEqual([[`terminals`]]);
     });
 
     it(`names a NESTED key whole, so a domain can refresh one family without its siblings`, () => {
-        // The review is filed under ["git","changes"] and the commit log under ["git","log"]. A landing's drafted
-        // message belongs to the first and has nothing to say about the second, which is the case the single
-        // segment this table used to carry could not express.
+        // landings maps to ["git","changes"], distinct from ["git","log"] the commit log uses.
         expect(staleRuntimeQueryKeys([`landings`])).toEqual([[`git`, `changes`]]);
     });
 
@@ -33,8 +27,7 @@ describe(`staleRuntimeQueryKeys`, () => {
 
 describe(`runtimeBoundQueryKeys`, () => {
     it(`covers every declared domain, since a reconnect is the only recovery for a frame nobody received`, () => {
-        // Compared as joined paths: the assertion is about which keys are covered, and two equal paths are two
-        // different arrays.
+        // Joined into strings for comparison: two equal arrays are still different object identities.
         const joined = (keys: readonly (readonly string[])[]): string[] => [...new Set(keys.map((key) => key.join(`/`)))].toSorted();
         expect(joined(runtimeBoundQueryKeys())).toEqual(joined(RUNTIME_DOMAIN_BINDINGS.flatMap((binding) => binding.invalidates)));
     });

package/src/state/runtime-state.ts

@@ -0,0 +1,62 @@
+// Twin of workspace-state.ts for state with no file to watch: tmux sessions, dev-server panels, sockets, browsers,
+// spawned children. The daemon pushes a domain on the existing stream instead of the browser polling; keeping the
+// mapping here only prevents drift. A key belongs to whoever queries it, so one entry can refresh several surfaces.
+
+// A segment per level, so a binding can name a nested key, not only a top-level one: the review's key is
+// ["git","changes"], distinct from the commit log's ["git","log"].
+export type QueryKeyPath = readonly string[];
+
+export interface RuntimeDomainBinding {
+    // What moved, in the daemon's words; wire data riding the runtimeChanged frame.
+    readonly domain: string;
+    // Reaches only queries something is observing, so pushing a domain eagerly costs unwatched tabs nothing.
+    readonly invalidates: readonly QueryKeyPath[];
+}
+
+// Declared `as const` so domain names survive as literal types (RuntimeDomain below).
+const RUNTIME_DOMAINS = [
+    // Every attachable tmux session: the tab strip, activity badge and process rows; sampled once, daemon-side.
+    { domain: "terminals", invalidates: [["terminals"]] },
+
+    // A dev server's state (running, healthy, preview URL); apps shares it, same underlying managed-process fact.
+    { domain: "panels", invalidates: [["panels"], ["apps"]] },
+
+    // Every listening socket and which are forwarded publicly; only the LISTEN set is sampled cheaply.
+    { domain: "ports", invalidates: [["ports"]] },
+
+    // The agent's Chromiums and open pages, daemon-held, minted from its own browser tool-call hooks.
+    { domain: "browsers", invalidates: [["browsers"]] },
+
+    // Daemon-held; changes continuously (tokens, tool uses), so it's rate-limited rather than pushed per mutation.
+    { domain: "subagents", invalidates: [["subagents"]] },
+
+    // Machines on the other end of a socket (devices, browsers, runners); "online" is the socket itself, never sampled.
+    // hosts/webext land on capabilities since a pairing card's state is literally the hub's online answer.
+    { domain: "hosts", invalidates: [["capabilities"], ["devices"]] },
+    { domain: "webext", invalidates: [["capabilities"]] },
+    { domain: "runners", invalidates: [["runners"]] },
+
+    // Watched because rows act on their own while nobody's watching (coming due, a turn writing back).
+    { domain: "approvals", invalidates: [["approvals"]] },
+
+    // Commit subject drafted after landing; arrives too late for the turn-end refresh, needs its own push.
+    { domain: "landings", invalidates: [["git", "changes"]] },
+] as const satisfies readonly RuntimeDomainBinding[];
+
+export const RUNTIME_DOMAIN_BINDINGS: readonly RuntimeDomainBinding[] = RUNTIME_DOMAINS;
+
+// Every declared domain as a type, so a rename is a compile error rather than a silently dropped frame.
+export type RuntimeDomain = (typeof RUNTIME_DOMAINS)[number]["domain"];
+
+// Dedupes by joined segments: two domains can feed the same key, but each path is its own array so a Set won't catch
+// it. Exact, since a segment is always this file's own identifier, never a caller's string.
+const dedupe = (keys: readonly QueryKeyPath[]): readonly QueryKeyPath[] => [...new Map(keys.map((key) => [key.join(`/`), key])).values()];
+
+// The query keys a pushed domain set makes stale, deduped; called by the browser's /events handler so daemon and
+// browser share one table. An unknown domain is dropped rather than throwing, for forward compatibility.
+export const staleRuntimeQueryKeys = (domains: readonly string[]): readonly QueryKeyPath[] =>
+    dedupe(RUNTIME_DOMAIN_BINDINGS.filter((binding) => domains.includes(binding.domain)).flatMap((binding) => binding.invalidates));
+
+// Every key any runtime domain feeds; what a fresh /events connection re-asks wholesale, since a missed push here is
+// gone for good. Bounds the cost to one read per key, letting these views stay unpolled.
+export const runtimeBoundQueryKeys = (): readonly QueryKeyPath[] => dedupe(RUNTIME_DOMAIN_BINDINGS.flatMap((binding) => binding.invalidates));

package/src/state/starter.ts

@@ -0,0 +1,5 @@
+// Names of the starter site seeded on first boot (scaffold/starter-site.ts), shared so the browser can find what the
+// daemon started. site is the repo dir; landing is the app name, also in the preview hostname
+// (preview-site--landing-<id>.<zone>) and its _apps/ folder. Renaming breaks already-seeded workspaces.
+export const STARTER_REPO = "site";
+export const STARTER_APP = "landing";

package/src/state/state-portability.ts

@@ -0,0 +1,27 @@
+// Whether a piece of daemon state travels, declared per manifest entry so the bundler and restorer both derive from it
+// rather than a hand-kept list. The classes are exhaustive, no unset default, since a credential store left
+// unclassified would default to carry and leave the sandbox in an exported file.
+export type Portability =
+    /* Ordinary state. Travels in every bundle. */
+    | "carry"
+    // Holds a credential (token, webhook secret, ssh key); travels only when the owner opts in at export.
+    | "secret"
+    // Binds this sandbox to its owner, browsers or host; never travels, the target mints its own.
+    | "identity"
+    // Regenerated by the target from state that does travel; left out for size, not safety.
+    | "derived";
+
+// One manifest entry: the path and what happens to it at export. note is user-facing, an instruction to the owner ('log
+// in again'), not a rationale.
+export interface StateFile {
+    readonly path: string;
+    readonly portability: Portability;
+    readonly note?: string;
+}
+
+// Longest-prefix match: a nested, more specific entry wins over a general one, like .gitignore's deepest matcher.
+// Undefined for an unclaimed path; callers pick the default (workspace carry, history derived).
+export const stateFileFor = <T extends StateFile>(path: string, files: readonly T[]): T | undefined =>
+    files
+        .filter((file) => path === file.path || path.startsWith(file.path) || `${path}/` === file.path)
+        .reduce<T | undefined>((best, file) => (best === undefined || file.path.length > best.path.length ? file : best), undefined);

package/src/state/versions.ts

@@ -0,0 +1,26 @@
+// Compares versions this system stamps on the daemon, sandbox image and device agents; one release stamps all of them
+// the same, so both ends can ask "is this behind" with a shared comparator. A hand-rolled duplicate wouldn't disagree
+// until 1.9.0 vs 1.10.0 broke it.
+
+// Plain dotted numerics, no semver dependency needed. A missing segment counts as 0, so "1.2" and "1.2.0" compare
+// equal.
+export const isNewer = (a: string, b: string): boolean => {
+    const left = a.split(".").map(Number);
+    const right = b.split(".").map(Number);
+    for (let i = 0; i < Math.max(left.length, right.length); i++) {
+        const l = left[i] ?? 0;
+        const r = right[i] ?? 0;
+        if (l !== r) {
+            return l > r;
+        }
+    }
+    return false;
+};
+
+// Sentinel for a non-release build; excluded from comparison rather than merely outranked by every release.
+export const DEV_VERSION = `0.0.0`;
+
+// False whenever uncertain: no installed version, no latest version, or installed is the dev sentinel.
+// A malformed version compares as not-newer only, so it can withhold a nag but never invent one.
+export const isBehind = (installed: string | undefined, latest: string | undefined): boolean =>
+    installed !== undefined && latest !== undefined && installed !== DEV_VERSION && isNewer(latest, installed);