@intentic/sandbox-contract 1.248.0 → 1.249.0

package/src/definition.ts

@@ -1,207 +0,0 @@
-import { z } from "zod";
-import { NeedsActionSchema } from "./needs-action.js";
-import { CapabilitySchema } from "./schemas/capabilities.js";
-import { SandboxSettingsSchema } from "./schemas/settings.js";
-
-/* THE SANDBOX DEFINITION: the declarable SHAPE of a sandbox, split off from its state.
- *
- * A bundle (BundleSchema, schemas/maintenance.ts) moves everything a sandbox holds; this is the half of it that
- * is a REFERENCE to a source of truth rather than bytes only this sandbox has: which repos (as remotes a
- * target can clone), which connections (as shapes a target re-authenticates), which overlay steps (as source
- * a target's owner approves), which secrets (as NAMES a target asks for), which agent settings. Everything
- * here can be reproduced against the world; everything a bundle carries beyond it (transcripts, checkpoint
- * timelines, unpushed branches, ledgers) cannot, which is the line between the two formats.
- *
- * ON THE WIRE AND ON DISK IT IS TOML (`sandbox.toml`), hand-writable and diffable; these schemas are what the
- * parsed document must satisfy. The choice of a definition never relaxes the consent model: applying one
- * writes the overlay as a PROPOSAL for the owner's approval gate, lands capabilities unauthenticated, and
- * never carries a credential value, so a definition is safe to publish in a way a bundle never is.
- */
-
-// One repository, by reference: the id it lands under in the workspace, where a target clones it from, and
-// (optionally) the branch to check out. A repo with NO remote cannot appear here, the exporter reports it as
-// omitted instead of inventing a source for bytes only the source sandbox holds.
-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 WORKSPACE ITSELF, by reference. `/work` is a git repo of its own (the daemon's `root` scope, git dir on
- * /history), tracking every workspace file that is not a nested repo, the reference shelf, or daemon-internal
- * state — which by the versioned-state allowlist means the owner's AUTHORED content: notes, skills, personas,
- * automations, workflow and loop designs, approvals, workspace extensions. None of that has a source anywhere else,
- * so before this section a definition could only shrug at it and a bundle was the sole way to move it.
- *
- * With a remote it becomes referenceable like any other repo, which is the whole point: `[workspace]` plus
- * `[[repositories]]` is a sandbox's code AND its way of working, and what remains bundle-only is exactly what
- * cannot be pushed anywhere — secrets, identity, /history, the built image.
- *
- * A workspace with no remote cannot appear here; the exporter says so in `omitted` rather than inventing one. */
-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: the target composes against ITS OWN base (see
-    // composeEnvironment's baseImageOf), this records what the source was on.
-    baseImage: z.string().optional(),
-    /* The owner-approved CUSTOM overlay section, as source. Deliberately not the composed file and
-     * deliberately without the approval hash: consent does not travel, so an applied definition parks this at
-     * the target owner's approval gate rather than executing it. */
-    dockerfile: z.string().optional(),
-});
-export type DefinitionEnvironment = z.infer<typeof DefinitionEnvironmentSchema>;
-
-/* The settings section: every SandboxSettings field, optional, WITHOUT its default. `.partial()` alone keeps
- * each field's `.default()`, so a document naming two flags would parse into the whole surface at today's
- * defaults — the opposite of "state only decisions", and it would freeze those defaults into every future
- * apply. Unwrapping first is what makes an absent key STAY absent, so applying merges over the target's own
- * settings and a definition round-trips through parse byte-identically. */
-// Both wrapper classes, in a loop: a field can be a default inside a prefault, and either one left on would
-// re-materialize its value for an absent key.
-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,
-    // the bundle manifest's own rule.
-    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 itself, when it has a remote to be named by. Absent is the ordinary state of a
-    // workspace nobody has published, not an error.
-    workspace: DefinitionWorkspaceSchema.optional(),
-    repositories: z.array(DefinitionRepositorySchema).prefault([]),
-    /* Each connection IN FULL (id, kind, config), not merely named: the manifest they come from carries the
-     * SHAPE of a connection and never its credential (workspace-state.ts argues the split on the
-     * capabilities.json entry, and the exporter sweeps before reading), so what lands on a target is the card,
-     * visibly unauthenticated, waiting for one credential apiece. */
-    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([]),
-    // The agent settings that differ from their defaults. Partial on purpose: a definition states decisions,
-    // not the whole flag surface, so a flag it does not mention keeps the target's own default.
-    settings: definitionSettings(),
-});
-export type SandboxDefinition = z.infer<typeof SandboxDefinitionSchema>;
-
-// One "do this by hand" line, the honesty unit the arrival surface carries too: a subject the UI bolds and a
-// detail written as an instruction to the owner. Defined in its own leaf module (needs-action.ts says why)
-// and re-exported here, where every consumer of the definition surface finds it.
-export { NeedsActionSchema, type NeedsAction } from "./needs-action.js";
-
-// What GET /definition answers: the emitted TOML, plus what the derivation could not express (a repo with no
-// remote), listed rather than silent, the export's own `excluded` discipline.
-export const DefinitionExportSchema = z.object({
-    toml: z.string(),
-    omitted: z.array(NeedsActionSchema),
-});
-export type DefinitionExport = z.infer<typeof DefinitionExportSchema>;
-
-/* APPLYING one is not here. A definition is one of four things that can ARRIVE in a sandbox, and it lands
- * through the shared pipeline in arrival.ts (ArrivalPlan → ArrivalApply → ArrivalReport) rather than through
- * a plan/apply/report trio of its own. What stays on this file is the outbound half and the read: deriving
- * the document, and where this sandbox stands relative to one. */
-
-// Where this sandbox stands relative to a definition: one line per difference, empty when they agree. The
-// drift answer, computable because the emitter is deterministic.
-export const DefinitionDiffSchema = z.object({
-    differences: z.array(NeedsActionSchema),
-});
-export type DefinitionDiff = z.infer<typeof DefinitionDiffSchema>;
-
-/* ---- publishing the workspace repo, the one step a definition cannot take for itself ----
- *
- * `[workspace]` names a remote; nothing can name one that does not exist. So the owner-facing half of the
- * feature is this: create a PRIVATE repo on a connected git host and push /work to it, or adopt a URL the
- * owner made themselves. Deliberately its own route rather than a side effect of the export, publishing a
- * workspace is an outward act with its own confirmation, and deriving a document must stay read-only.
- */
-export const WorkspacePublishSchema = z.object({
-    /* An existing repo's clone URL. Given, nothing is created: the remote is wired up and pushed to, which is
-     * the path for an owner who made the repo themselves or is moving hosts. */
-    remote: z.string().min(1).optional(),
-    // The repo to create when `remote` is absent. Owner-side default is the sandbox's own name.
-    name: z.string().min(1).optional(),
-    /* The account or organization 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 "made you a repo"
-// from "wired up the one you gave me", which is the difference the card reports back.
-export const WorkspacePublishResultSchema = z.object({
-    remote: z.string(),
-    branch: z.string(),
-    created: z.boolean(),
-});
-export type WorkspacePublishResult = z.infer<typeof WorkspacePublishResultSchema>;
-
-// What the card renders before anything is published: whether /work has a remote, and which connected git
-// hosts could make one. Read-only, so the button can say "Publish to github.com" rather than opening a form
-// into a void.
-export const WorkspaceRemoteSchema = z.object({
-    remote: z.string().optional(),
-    branch: z.string().optional(),
-    // Hostnames of connected github/gitlab accounts, in the order they would be tried. Empty means the owner
-    // must connect one (or paste a URL).
-    hosts: z.array(z.string()),
-});
-export type WorkspaceRemote = z.infer<typeof WorkspaceRemoteSchema>;
-
-/* ---- the bundle manifest, restated on the definition ----
- *
- * A bundle is DEFINITION + STATE: its manifest embeds the same definition `GET /definition` emits, and the
- * tar entries behind it carry what no definition can reference (git dirs, transcripts, ledgers). One schema,
- * two doors, which is what keeps the two formats from drifting into different answers about what an
- * environment IS. A manifest whose version this daemon does not know is refused rather than guessed at.
- *
- * Version 3 added `repos`, and it is the field that made a bundle previewable. Taking one in is now a plan
- * the owner ticks (arrival.ts), and a plan has to say what is in the tar BEFORE the tar is read: which
- * repositories a bundle carries could previously only be learned by walking every entry, because
- * `definition.repositories` lists only the ones that HAVE a remote to be named by. A bundle that cannot
- * describe its own contents can only be offered whole, which is exactly the all-or-nothing this replaced.
- */
-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-time choice; the restorer re-derives every decision from the manifests rather than
-    // trusting this, and uses it only to explain what is missing.
-    secrets: z.boolean(),
-    /* Every repository whose real git dir rides in this bundle, by workspace id — INCLUDING the ones no
-     * definition can name, which is the point: a repo with no remote is invisible to `definition.repositories`
-     * and is precisely the one an owner most wants carried by bytes. "root" is not listed; the workspace repo
-     * itself is not a nested repository and travels with the workspace files. */
-    repos: z.array(z.string()),
-    // The declarable shape, exactly what a definition export emits, so the restore report reasons over the
-    // same facts either door delivers.
-    definition: SandboxDefinitionSchema,
-    // Every path class the bundle deliberately left out, with the manifest's own note where it has one. This is
-    // what turns "the export skipped things" from a silence into a list the owner can act on.
-    excluded: z.array(z.object({ path: z.string(), portability: z.string(), note: z.string().optional() })),
-});
-export type BundleManifest = z.infer<typeof BundleManifestSchema>;

package/src/documents.ts

@@ -1,67 +0,0 @@
-import type { CardDocument, ToolCallContent } from "./events.js";
-import { planParts } from "./title.js";
-import { PLAN_DOCUMENTS_DIR } from "./workspace-state.js";
-
-/* A DOCUMENT A TURN WROTE FOR A PERSON TO READ, told apart from the files it changed for the machine.
- *
- * A transcript renders ACTS: a file was written, a command ran, a page was fetched. That is the right shape for
- * nearly everything an agent does, and the wrong shape for the one thing it produces that is addressed to the
- * reader. An analysis, a findings write-up, a plan: the card for those said `Write · +135 −0` and folded, so the
- * document the next question was ABOUT was the one thing the chat would not show. Worse, the model reaches for a
- * file precisely BECAUSE prose in the answer is expensive, so the better it behaves the less the reader sees.
- *
- * The rules live here, in the contract, because both sides run them and they must not drift: the daemon reads
- * them to decide what a parked card is about (agent.ts), the browser to decide how a tool card draws
- * (toolPresentation.ts). Two copies would let a card render a document the question card had never heard of.
- *
- * ONLY A WHOLE-FILE WRITE COUNTS. An Edit's `newText` is the replacement fragment, not the document: rendered as
- * prose it is a mid-sentence slice with no heading, and the DIFF is what a reader wants from an edit anyway. So
- * a Write of a markdown file is a document, and an edit to one stays a diff. */
-
-// Prose, by extension. Deliberately short: a document is something the chat can RENDER, and markdown is what
-// the chat's prose pipeline speaks. A `.txt` report would render as an unstyled wall and reads better as the
-// plain text box it already gets.
-const DOCUMENT_EXTENSIONS = [".md", ".markdown"];
-
-export const isDocumentPath = (path: string): boolean => {
-    const lower = path.toLowerCase();
-    return DOCUMENT_EXTENSIONS.some((extension) => lower.endsWith(extension));
-};
-
-/* Whether a path is one of the CLI's plan files, which is what earns a document the plan treatment here rather
- * than the general markdown rule above: the harness owns that address, so there is no guessing whether prose is
- * a plan and no threshold on length. Matched on the DIRECTORY rather than on the name, which is a mint-fresh
- * three-word phrase (`map-of-this-wiggly-spring.md`) carrying no signal at all.
- *
- * The directory itself is declared in workspace-state.ts, beside the lock it is the one exception to. */
-export const isPlanDocumentPath = (path: string): boolean => path.startsWith(`${PLAN_DOCUMENTS_DIR}/`);
-
-/* What a document is CALLED. Its opening heading when it has one, which is the line the author wrote to name
- * the whole thing (planParts, the same split the plan card titles from), and its file name when it does not.
- *
- * Never the path: a card that says `.intentic/records/sessions/claude/plans/map-of-this-wiggly-spring.md`
- * has told the reader nothing about what is in it, and that string is the CLI's mint, not anybody's title. */
-export const documentTitle = (markdown: string, path: string): string => planParts(markdown).title ?? path.split("/").pop() ?? path;
-
-/* The document a tool call produced, or undefined when it produced none, the ONE test both sides ask.
- *
- * Reads the call's structured diff rather than its result text, because the content is already there: a Write's
- * whole file rides the tool_call frame as `newText` (capped at the wire limit, which `truncated` reports), so
- * nothing has to be re-read from disk to draw it, and a published transcript with no workspace behind it draws
- * exactly the same document. */
-export const documentOf = (name: string, content: readonly ToolCallContent[] | undefined): CardDocument | undefined => {
-    if (name.toLowerCase() !== "write") {
-        return undefined;
-    }
-    const diff = content?.find((entry) => entry.type === "diff" && isDocumentPath(entry.path));
-    if (diff === undefined || diff.type !== "diff") {
-        return undefined;
-    }
-    return {
-        path: diff.path,
-        title: documentTitle(diff.newText, diff.path),
-        markdown: diff.newText,
-        ...(diff.truncated === true ? { truncated: true } : {}),
-        ...(isPlanDocumentPath(diff.path) ? { plan: true } : {}),
-    };
-};

package/src/embed.ts

@@ -1,164 +0,0 @@
-/* THE ZOD-FREE HALF OF AN EMBED'S WIRE: what every script a customer drops on their own page does before it
- * does anything of its own. Two embeds exist, the Front Desk chat bubble (_sandbox/webchat-widget) and the bug
- * reporter (_sandbox/issue-widget), and each used to carry its own copy of this: the same three requests
- * against a public door, the same proof-of-work solver, the same localStorage-backed id, the same
- * read-my-own-script-tag boot. The daemon's side of the same doors is one module too (automations/public-door.ts).
- *
- * THE RULE FOR WHAT MAY LIVE HERE: no imports, ever. This module is bundled INTO a page that belongs to someone
- * else, so it must cost that page nothing it did not ask for; the contract's barrel would bring zod with it
- * (webext-links.ts measured that at 1.1 MB for two strings). Types are declared here for the same reason. */
-
-// Where an embed talks to: the daemon it came from, and the automation it is the public face of.
-export interface EmbedEndpoint {
-    readonly base: string;
-    readonly automationId: string;
-}
-
-// What the server said when it refused. The daemon answers every refusal as {"error": "..."}, and that sentence
-// is shown verbatim where a person can see it: "origin not allowed" tells a site owner exactly what to fix and
-// anything invented here would not.
-export class EmbedError extends Error {
-    constructor(
-        message: string,
-        readonly status: number,
-    ) {
-        super(message);
-        this.name = "EmbedError";
-    }
-}
-
-export const embedFailure = async (response: Response): Promise<EmbedError> => {
-    const body = (await response.json().catch(() => undefined)) as { error?: unknown } | undefined;
-    return new EmbedError(typeof body?.error === "string" ? body.error : `request failed (${response.status})`, response.status);
-};
-
-// One route of a public door: `<base>/<slug>/<automation>/<path>`, the daemon's own spelling.
-export const embedUrl = ({ base, automationId }: EmbedEndpoint, slug: string, path: string): string =>
-    `${base}/${slug}/${encodeURIComponent(automationId)}/${path}`;
-
-// One GET against a public door, answered as JSON or refused with the server's own sentence.
-export const fetchEmbedJson = async <T>(url: string): Promise<T> => {
-    const response = await fetch(url);
-    if (!response.ok) {
-        throw await embedFailure(response);
-    }
-    return (await response.json()) as T;
-};
-
-/* ---- proof of work ----
- *
- * The daemon issues a challenge: find a nonce whose SHA-256 of `${salt}:${nonce}` begins with `difficulty` zero
- * BITS. It costs the person a second or so and costs a script the same per identity it wants to burn, with no
- * third-party account anywhere. The challenge is minted FOR one caller (the daemon signs the caller's own id
- * into the salt), so a solution cannot be carried to another thread or another reporter; hence the id in the
- * challenge request rather than a bare GET.
- *
- * Solved on the main thread in yielding batches rather than in a Worker: a Worker would have to come from a
- * blob: URL, which a host page's Content-Security-Policy is entitled to forbid, and being unable to chat or send
- * feedback because of the SITE's CSP is a worse failure than a busy second. */
-export interface PowChallenge {
-    readonly salt: string;
-    readonly difficulty: number;
-}
-
-export const fetchEmbedChallenge = (endpoint: EmbedEndpoint, slug: string, param: string, id: string): Promise<PowChallenge> =>
-    fetchEmbedJson<PowChallenge>(`${embedUrl(endpoint, slug, "challenge")}?${param}=${encodeURIComponent(id)}`);
-
-const BATCH = 512;
-
-// Leading zero bits of a digest, up to `wanted`. Stops at the first non-zero byte, so a miss costs one byte.
-const leadingZeroBits = (digest: Uint8Array, wanted: number): number => {
-    let bits = 0;
-    for (const byte of digest) {
-        if (byte !== 0) {
-            // Math.clz32 counts 32-bit leading zeros; the byte sits in the low 8, so 24 of them are structural.
-            return bits + Math.clz32(byte) - 24;
-        }
-        bits += 8;
-        if (bits >= wanted) {
-            return bits;
-        }
-    }
-    return bits;
-};
-
-/* Resolves to the ANSWER the daemon expects, `<salt>:<nonce>`, carrying back the salt it signed so it can
- * re-derive the challenge it issued without having stored one. `insecure` is what to say on an http:// page:
- * `crypto.subtle` is only available in a secure context, and the fix is the site's TLS, not anything the
- * person can do, so the sentence names the thing they were trying to do. */
-export const solveProofOfWork = async (challenge: PowChallenge, insecure: string, onProgress?: (attempts: number) => void): Promise<string> => {
-    if (crypto.subtle === undefined) {
-        throw new Error(insecure);
-    }
-    const encoder = new TextEncoder();
-    for (let nonce = 0; ; nonce += 1) {
-        const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(`${challenge.salt}:${nonce}`)));
-        if (leadingZeroBits(digest, challenge.difficulty) >= challenge.difficulty) {
-            return `${challenge.salt}:${nonce}`;
-        }
-        if (nonce % BATCH === BATCH - 1) {
-            onProgress?.(nonce + 1);
-            // Hand the main thread back so the page (and the embed's own "checking…" line) keeps painting.
-            await new Promise((resolve) => setTimeout(resolve, 0));
-        }
-    }
-};
-
-/* ---- what an embed keeps in the visitor's browser ----
- *
- * localStorage throws in Safari's private mode and anywhere the site blocks storage. An embed with no storage
- * still works; it just mints a fresh id per page load, which costs only a slightly less useful thread or
- * rate-limit key. Silence here is deliberate: an embed must never be the thing that puts an error in the
- * console. */
-export const readStored = (name: string): string | undefined => {
-    try {
-        return window.localStorage.getItem(name) ?? undefined;
-    } catch {
-        return undefined;
-    }
-};
-
-export const writeStored = (name: string, value: string): void => {
-    try {
-        window.localStorage.setItem(name, value);
-    } catch {
-        /* no storage: this page load keeps the value in memory and the next one mints another */
-    }
-};
-
-/* A per-browser id under `name`, minted once and kept. NOT identity and NOT a secret: anyone can mint one, and
- * the daemon treats it as exactly what it is, the key that threads a visitor's messages into one conversation,
- * or that a rate window counts against so one runaway tab cannot spend the whole day's budget. */
-export const storedId = (name: string): string => {
-    const existing = readStored(name);
-    if (existing !== undefined && existing !== "") {
-        return existing;
-    }
-    const minted = crypto.randomUUID();
-    writeStored(name, minted);
-    return minted;
-};
-
-/* ---- the <script> tag an embed boots from ----
- *
- *   <script src="https://sandbox-<id>.<zone>/<slug>/…js" data-automation="support" defer></script>
- *
- * Everything else is derived: the daemon to talk to is the ORIGIN THIS SCRIPT CAME FROM, which is the one thing
- * a copy-pasted snippet can't get wrong. `data-base` overrides it for a site fronting the sandbox behind its
- * own proxy, the only case where the two legitimately differ.
- *
- * `document.currentScript` is only valid while the script body is executing, so it is read at module scope by
- * the caller rather than inside an async boot. The querySelector is the fallback for a bundler or tag manager
- * that re-executes the entry in a context where currentScript is null. */
-export const embedScript = (srcMatch: string): HTMLScriptElement | null =>
-    (document.currentScript as HTMLScriptElement | null) ?? document.querySelector<HTMLScriptElement>(`script[src*="${srcMatch}"]`);
-
-// The endpoint a script tag names, or undefined when it carries no automation id, the one mistake worth a
-// console line: without it the embed is silently absent and the site owner has nothing to go on.
-export const embedEndpointOf = (script: HTMLScriptElement): EmbedEndpoint | undefined => {
-    const automationId = script.dataset["automation"];
-    if (automationId === undefined || automationId === "") {
-        return undefined;
-    }
-    return { automationId, base: (script.dataset["base"] ?? new URL(script.src, window.location.href).origin).replace(/\/$/, "") };
-};