@intentic/sandbox-contract 1.334.0 → 1.335.0

package/src/schemas/data-protection.ts

@@ -0,0 +1,99 @@
+// data-protection: what a sandbox needs to run under a data protection officer's rules (GDPR/RODO, Poland's KRI, the
+// AI Act): how long what it keeps is kept, what its audit trail records and for how long, whether the product's own
+// analytics may watch it, and the notice its members read about working with an AI. Every default here is what the
+// sandbox did before these settings existed. A public office switches them on with the public-office preset on the
+// data protection page, never through a changed default: most sandboxes belong to developers and individuals, and a
+// stricter default would take away something they rely on.
+import { z } from "zod";
+
+export const RETENTION_DAYS_MAX = 3650;
+const retentionDays = () => z.number().int().min(0).max(RETENTION_DAYS_MAX).default(0);
+
+// One field per kind of copy the sandbox keeps of what people and agents wrote. Zero keeps that kind forever, which is
+// what every sandbox did before this block existed. A positive value DELETES (it does not archive) once the copy is
+// older than that many days, so a person's data asked to be forgotten is gone from every place it sat.
+export const RetentionSettingsSchema = z.object({
+    transcriptDays: retentionDays().describe(
+        "How many days a conversation's transcript is kept after its last message. After that the transcript and its backups are deleted for good, not archived. Zero keeps them forever.",
+    ),
+    restorePointDays: retentionDays().describe(
+        "How many days the workspace's restore points are kept. These are the snapshots taken every minute while agents work, so files deleted from the workspace stay recoverable until then. Zero keeps every restore point.",
+    ),
+    privacyVaultDays: retentionDays().describe(
+        "How many days the privacy shield remembers a personal value after it last saw it. After that the value and its token are deleted, and the value is matched as new if it comes back. Zero remembers them forever.",
+    ),
+    cacheDays: retentionDays().describe(
+        "How many days converted copies of documents are kept: text read out of PDFs and office files, and the results of reading scans and images. Zero keeps them until the cache needs the room.",
+    ),
+    rawOutputDays: retentionDays().describe(
+        "How many days the full, untrimmed output of commands is kept beside the trimmed version the agent read. Zero keeps it until the space is needed.",
+    ),
+});
+export type RetentionSettings = z.infer<typeof RetentionSettingsSchema>;
+
+export const AUDIT_RETENTION_DAYS_MIN = 30;
+export const AUDIT_RETENTION_DAYS_DEFAULT = 365;
+// Poland's KRI regulation (Dz.U. 2024 poz. 773, §20) keeps a public system's logs for two years; the preset uses this.
+export const AUDIT_RETENTION_DAYS_PUBLIC_OFFICE = 730;
+
+// The audit trail: who changed a policy, a member, a secret's gate or a setting, and (when asked) who read what. It is
+// separate from the activity log, which records the messages team-chat bots send and receive. It is hash-chained, so a
+// changed or removed record shows, and it is written by the daemon alone, outside the agent's workspace.
+export const AuditSettingsSchema = z.object({
+    retentionDays: z
+        .number()
+        .int()
+        .min(AUDIT_RETENTION_DAYS_MIN)
+        .max(RETENTION_DAYS_MAX)
+        .default(AUDIT_RETENTION_DAYS_DEFAULT)
+        .describe(
+            "How many days audit records are kept before the oldest are deleted. Public bodies in Poland keep system logs for two years (730 days).",
+        ),
+    recordReads: z
+        .boolean()
+        .default(false)
+        .describe(
+            "Also record who opened which conversation, transcript, file or log, not only who changed something. Off by default because it writes a record on every page someone opens.",
+        ),
+    forwardUrl: z
+        .union([z.literal(""), z.url({ protocol: /^https$/ })])
+        .default("")
+        .describe(
+            "An HTTPS address each audit record is also sent to as it is written, such as your organisation's log collector (SIEM). A copy kept outside the sandbox is the one nobody inside it can change. Empty sends nothing.",
+        ),
+    forwardSecret: z
+        .string()
+        .max(200)
+        .default("")
+        .describe(
+            "The name of a stored secret sent as a bearer token with each forwarded record. Empty sends none.",
+        ),
+});
+export type AuditSettings = z.infer<typeof AuditSettingsSchema>;
+
+export const AI_NOTICE_TEXT_MAX = 4000;
+
+// The AI Act's literacy duty (Art. 4) falls on whoever puts staff in front of an AI system. This is the card that tells
+// them, once, what they are working with. Off by default: a developer does not need to be told, and the preset turns
+// it on.
+export const AiNoticeSchema = z.object({
+    show: z
+        .boolean()
+        .default(false)
+        .describe(
+            "Show members a short notice the first time they open this sandbox: that they are working with an AI, that it makes mistakes, what to check before acting on its answers, and what not to paste into it. They confirm it once, and the confirmation is recorded.",
+        ),
+    text: z
+        .string()
+        .max(AI_NOTICE_TEXT_MAX)
+        .default("")
+        .describe(
+            "Your own wording for that notice, such as your office's rules for using AI. Empty shows the built-in text in the reader's language.",
+        ),
+});
+export type AiNotice = z.infer<typeof AiNoticeSchema>;
+
+// Where the key that encrypts the sandbox's stores at rest (secrets, the credential vault, the privacy shield's vault)
+// is read from: a file path in the daemon's environment, normally a secret mounted from outside the sandbox's volumes.
+// Unset, those stores stay plain files readable only by their owner, as they always were.
+export const AT_REST_KEY_FILE_ENV = "INTENTIC_AT_REST_KEY_FILE";

package/src/schemas/engines.ts

@@ -4,7 +4,7 @@ import { z } from "zod";
 // An engine is the installed program a runtime (agent-catalog.ts) spawns or imports — the `claude` binary, `codex`
 // wrapper, `@cursor/sdk`, `opencode`, `cli-proxy-api` — not the loop itself; one engine can back several runtimes.
 
-export const ENGINE_IDS = ["claude", "codex", "cursor", "devin", "opencode", "translator"] as const;
+export const ENGINE_IDS = ["claude", "codex", "cursor", "devin", "grok-build", "kimi", "muse", "opencode", "translator"] as const;
 export type EngineId = (typeof ENGINE_IDS)[number];
 export const EngineIdSchema = z.enum(ENGINE_IDS);
 

package/src/schemas/git/git.ts

@@ -275,6 +275,21 @@ export type ScratchPath = z.infer<typeof ScratchPathSchema>;
 // Whether a scratch entry covers `path`: a directory entry everything under it, a file entry only itself.
 export const isScratch = (path: string, scratch: readonly Pick<ScratchPath, "path">[]): boolean =>
     scratch.some((entry) => (entry.path.endsWith("/") ? path.startsWith(entry.path) : path === entry.path));
+// Apart from scratch, which is left out for its shape: these are left out because the repository says so, and the
+// owner usually wants them most (a render in `out/`, a build in `dist/`).
+export const IgnoredOutputKindSchema = z
+    .enum(["new", "changed"])
+    .describe("Whether your tree has nothing at this path yet, or holds a different file there that copying would replace.");
+export type IgnoredOutputKind = z.infer<typeof IgnoredOutputKindSchema>;
+export const IgnoredOutputSchema = z.object({
+    path: z.string().describe("Relative to its repository. Always one file, never a directory."),
+    kind: IgnoredOutputKindSchema,
+    bytes: z.number().describe("Its size in bytes."),
+});
+export type IgnoredOutput = z.infer<typeof IgnoredOutputSchema>;
+// How many ignored outputs one repository lists by name; past it they are only counted, since a turn that ran a build
+// can leave tens of thousands.
+export const IGNORED_OUTPUTS_LISTED = 200;
 export const RepoChangesSchema = z.object({
     // The {repo} param the per-repo git routes accept: "root" or a repo id (its root-relative dir).
     repo: z.string(),
@@ -501,6 +516,25 @@ export const AgentChangesSchema = z.object({
         .describe(
             "Untracked files the conversation left in its copy that look like scratch: logs, probe scripts, dumps, a checkout of its own. They are not in the list above and no merge carries them. They stay in its copy until they are included or deleted, and go with the copy when it is archived or retired. Absent when there are none.",
         ),
+    // Read off the live copy like scratch, and judged against the main tree as it stands now, so a file already copied
+    // over drops out.
+    ignored: z
+        .array(
+            z.object({
+                repo: z.string().describe("Which repository."),
+                paths: z.array(IgnoredOutputSchema).describe(`What it wrote there, sorted by path, at most ${IGNORED_OUTPUTS_LISTED} of them.`),
+                more: z
+                    .number()
+                    .optional()
+                    .describe(
+                        "How many more such files it wrote there past the listed ones. A floor, not an exact count, when the copy holds more files than are looked at. Absent when every one is listed.",
+                    ),
+            }),
+        )
+        .optional()
+        .describe(
+            "Files the conversation wrote in its copy that the repository's ignore rules exclude, such as a render in `out/` or a build in `dist/`, which your tree lacks or holds differently. No merge carries them and they never enter git; copying one puts it at the same path in your tree. Dependencies (`node_modules`), hidden files and folders, and logs, dumps and caches are never listed. Absent when there are none.",
+        ),
 });
 export type AgentChanges = z.infer<typeof AgentChangesSchema>;
 
@@ -522,6 +556,18 @@ export const AgentScratchSchema = z.object({
 });
 export type AgentScratch = z.infer<typeof AgentScratchSchema>;
 
+// Names ignored outputs as `AgentChanges.ignored` lists them, one file each; a path that is not one now is refused.
+export const AgentIgnoredSchema = z.object({
+    id: z.string().min(1).describe("Which conversation."),
+    repo: z.string().min(1).describe("Which repository of its composition."),
+    paths: z
+        .array(z.string().min(1))
+        .min(1)
+        .max(MAX_ACTION_PATHS)
+        .describe("Paths exactly as the review lists them under ignored, each a file relative to the repository."),
+});
+export type AgentIgnored = z.infer<typeof AgentIgnoredSchema>;
+
 // Own read (a `git log` per repo), not folded into the review, whose rows are differences against main and these are
 // not. A commit CARRIES the work without authoring it: a path is attributed to the newest commit that left it there.
 export const AgentHistoryCommitSchema = z.object({

package/src/schemas/hosts.ts

@@ -1,5 +1,6 @@
 // hosts: the user's own connected devices (the `host` capability's live half)
 import { z } from "zod";
+import { IntenticOsFactsSchema } from "./intentic-os.js";
 // Manifest says which machines are intended; this says which actually hold a socket now. Nothing persists across a
 // daemon restart except the enrollment itself, so a closed laptop reads offline within a heartbeat.
 
@@ -83,6 +84,10 @@ export const DeviceFactsSchema = z.object({
     // a daemon bug for an afternoon. Override values are the agent's own redaction (secret-looking ones by length).
     ic: z.object({ path: z.string(), version: z.string(), modified: z.string().optional() }).optional(),
     icOverrides: z.array(z.string()).optional(),
+    // (2026-10-13) Present only on Intentic OS (`/usr/lib/intentic-os/release.json`): which edition, version and channel
+    // the machine boots, so the daemon tells the agent it may be this box's steward and the os_* tools are there. `os`
+    // above stays the human name. Absent everywhere else, and from an agent older than the field.
+    intenticOs: IntenticOsFactsSchema.optional(),
 });
 export type DeviceFacts = z.infer<typeof DeviceFactsSchema>;
 

package/src/schemas/intentic-os.test.ts

@@ -0,0 +1,86 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { packageRoot } from "@intentic/constants/node";
+import { DeviceFactsSchema } from "./hosts.js";
+import {
+    icOsChannelArgs,
+    icOsRebootArgs,
+    icOsRollbackArgs,
+    icOsStatusArgs,
+    icOsUpdateArgs,
+    type IntenticOsChannel,
+    intenticOsFactsFrom,
+    IntenticOsReleaseSchema,
+    IntenticOsStatusSchema,
+    IntenticOsUpdateCheckSchema,
+    isIntenticOs,
+} from "./intentic-os.js";
+
+// What `ic os` answers, as examples: golden/intentic-os.json holds a release.json, the shapes `ic os status --json`
+// gives (a quiet box, one with an update staged and a failed boot, one whose bootc said little) and both answers of
+// `ic os update --check --json`. This is the TS half: what ic gives is what the contract reads, to the field.
+
+// SAFETY: the golden is this package's own file; the assertions below fail on any field it lacks.
+const GOLDEN = JSON.parse(readFileSync(join(packageRoot(import.meta.url), "golden", "intentic-os.json"), "utf8")) as {
+    readonly release: unknown;
+    readonly status: readonly Readonly<Record<string, unknown>>[];
+    readonly updateCheck: readonly Readonly<Record<string, unknown>>[];
+};
+
+test("every status and update check in the golden reads back field for field", () => {
+    expect(GOLDEN.status.length).toBe(3);
+    for (const status of GOLDEN.status) {
+        const read: unknown = IntenticOsStatusSchema.parse(status);
+        expect(read).toEqual(status);
+    }
+    for (const check of GOLDEN.updateCheck) {
+        const read: unknown = IntenticOsUpdateCheckSchema.parse(check);
+        expect(read).toEqual(check);
+    }
+});
+
+test("a status from a newer ic keeps what this side reads, and only a wrong verdict, isolation or OS is no status", () => {
+    const [quiet] = GOLDEN.status;
+    const read: unknown = IntenticOsStatusSchema.parse({ ...quiet, pinned: true });
+    expect(read).toEqual(quiet);
+    expect(IntenticOsStatusSchema.safeParse({ ...quiet, health: { verdict: "amber", failed: [] } }).success).toBe(false);
+    expect(IntenticOsStatusSchema.safeParse({ ...quiet, isolation: "gvisor" }).success).toBe(false);
+    expect(IntenticOsStatusSchema.safeParse({ ...quiet, os: "fedora" }).success).toBe(false);
+});
+
+test("the facts a device reports are release.json's edition, version and channel, under the OS's own name", () => {
+    const release = IntenticOsReleaseSchema.parse(GOLDEN.release);
+    const facts = intenticOsFactsFrom(release);
+    expect(facts).toEqual({ name: "intentic-os", edition: "server", version: "2026.10.13.0", channel: "stable" });
+    expect(isIntenticOs({ intenticOs: facts })).toBe(true);
+    expect(isIntenticOs({})).toBe(false);
+    expect(isIntenticOs(undefined)).toBe(false);
+    expect(isIntenticOs({ intenticOs: { name: "Intentic OS" } })).toBe(false);
+    // An optional fact: a device on any other OS says nothing, and an older daemon's read of a newer one is unharmed.
+    const device = { os: "Intentic OS 2026.10.13.0 (kernel 6.11)", arch: "x64", shell: "/bin/bash", home: "/var/home/intentic", roots: [] };
+    expect(DeviceFactsSchema.parse({ ...device, intenticOs: facts }).intenticOs).toEqual(facts);
+    expect(DeviceFactsSchema.parse(device).intenticOs).toBeUndefined();
+});
+
+test("a release.json without its edition, version or channel is not one", () => {
+    expect(IntenticOsReleaseSchema.safeParse({ name: "Intentic OS", edition: "server", version: "2026.10.13.0" }).success).toBe(false);
+});
+
+test("the argv is ic's own verbs, the one spelling every caller uses", () => {
+    expect(icOsStatusArgs()).toEqual(["os", "status", "--json"]);
+    expect(icOsUpdateArgs("check")).toEqual(["os", "update", "--check", "--json"]);
+    expect(icOsUpdateArgs("stage")).toEqual(["os", "update"]);
+    expect(icOsUpdateArgs("apply")).toEqual(["os", "update", "--apply"]);
+    expect(icOsRollbackArgs(false)).toEqual(["os", "rollback"]);
+    expect(icOsRollbackArgs(true)).toEqual(["os", "rollback", "--apply"]);
+    expect(icOsRebootArgs()).toEqual(["os", "reboot"]);
+    expect(icOsChannelArgs("beta")).toEqual(["os", "channel", "beta"]);
+    expect(icOsChannelArgs("stable")).toEqual(["os", "channel", "stable"]);
+});
+
+test("a channel ic does not have never reaches it, even past the type", () => {
+    for (const channel of ["--apply", "nightly"]) {
+        // SAFETY: deliberately not a channel: what a caller that skipped its own schema would pass.
+        expect(() => icOsChannelArgs(channel as IntenticOsChannel), channel).toThrow();
+    }
+});

package/src/schemas/intentic-os.ts

@@ -0,0 +1,130 @@
+import { z } from "zod";
+
+// INTENTIC OS (2026-10-13): the immutable Linux that boots straight into Intentic (_os/README.md). Everything that changes
+// the OS goes through `ic os`, and everything that calls it reads ic's JSON rather than bootc's. This is that JSON as the
+// TypeScript side reads it, and the argv every caller spells it with: the machine agent's os_* tools run it, and a page
+// that cannot reach the machine can print it for a person to type. golden/intentic-os.json holds an example of each
+// answer, for ic's Rust to produce field for field.
+
+/** What `ic os status` says the OS is called, and what the machine agent reports in its facts. */
+export const INTENTIC_OS_NAME = "intentic-os";
+
+/** Written by the image build; a machine without it is not Intentic OS, and `ic os` refuses there. */
+export const INTENTIC_OS_RELEASE_PATH = "/usr/lib/intentic-os/release.json";
+
+/** The exit code `ic os` refuses with on a machine that is not Intentic OS. */
+export const IC_OS_NOT_INTENTIC_OS_EXIT = 3;
+
+// `/usr/lib/intentic-os/release.json`, as the image build writes it. `name` is the human one ("Intentic OS").
+// Read loosely: a field a newer image adds is ignored, and only the four the facts carry are required.
+export const IntenticOsReleaseSchema = z.object({
+    name: z.string(),
+    edition: z.string().min(1),
+    version: z.string().min(1),
+    channel: z.string().min(1),
+    repository: z.string().optional(),
+});
+export type IntenticOsRelease = z.infer<typeof IntenticOsReleaseSchema>;
+
+// What a device on Intentic OS reports in its facts (DeviceFacts.intenticOs), read off release.json at connect. Strings
+// on the wire, like every fact, so an edition or channel a newer image names never fails an older daemon's read.
+export const IntenticOsFactsSchema = z.object({
+    // Always INTENTIC_OS_NAME from a current agent; compared, never trusted to be a literal.
+    name: z.string(),
+    edition: z.string(),
+    version: z.string(),
+    channel: z.string(),
+});
+export type IntenticOsFacts = z.infer<typeof IntenticOsFactsSchema>;
+
+export const intenticOsFactsFrom = (release: IntenticOsRelease): IntenticOsFacts => ({
+    name: INTENTIC_OS_NAME,
+    edition: release.edition,
+    version: release.version,
+    channel: release.channel,
+});
+
+/** Whether a device's facts say it runs Intentic OS. */
+export const isIntenticOs = (facts: { readonly intenticOs?: { readonly name: string } | undefined } | undefined): boolean =>
+    facts?.intenticOs?.name === INTENTIC_OS_NAME;
+
+// A channel is the image tag. `ic os channel` takes only these two; `status` reads the booted image's tag and says
+// whatever it is, so the status field stays a string.
+export const IntenticOsChannelSchema = z.enum(["stable", "beta"]);
+export type IntenticOsChannel = z.infer<typeof IntenticOsChannelSchema>;
+
+// One bootc deployment (`status.booted|staged|rollback`), each field `null` where bootc does not say.
+export const IntenticOsDeploymentSchema = z.object({
+    image: z.string().nullable(),
+    version: z.string().nullable(),
+    digest: z.string().nullable(),
+    // ISO 8601, as bootc gives it.
+    timestamp: z.string().nullable(),
+});
+export type IntenticOsDeployment = z.infer<typeof IntenticOsDeploymentSchema>;
+
+// The boot's health as `ic os health` last wrote it (`/run/intentic-os/health.json`): `unknown` before it ran, and
+// `failed` names each failed check.
+export const IntenticOsHealthVerdictSchema = z.enum(["green", "red", "unknown"]);
+export const IntenticOsHealthSchema = z.object({ verdict: IntenticOsHealthVerdictSchema, failed: z.array(z.string()) });
+export type IntenticOsHealth = z.infer<typeof IntenticOsHealthSchema>;
+
+// How sandbox containers run (`/etc/intentic/os.json`): `container` is runc, `vm` a Kata microVM for every sandbox, and
+// `auto` a microVM only for a sandbox started privileged.
+export const IntenticOsIsolationSchema = z.enum(["auto", "vm", "container"]);
+export type IntenticOsIsolation = z.infer<typeof IntenticOsIsolationSchema>;
+
+// `ic os status --json`: one line. A key a newer ic adds is dropped, not refused.
+export const IntenticOsStatusSchema = z.object({
+    os: z.literal(INTENTIC_OS_NAME),
+    edition: z.string(),
+    version: z.string(),
+    channel: z.string(),
+    image: z.string(),
+    // Nullable for a bootc that would not answer; `staged` and `rollback` are null when there is none.
+    booted: IntenticOsDeploymentSchema.nullable(),
+    staged: IntenticOsDeploymentSchema.nullable(),
+    rollback: IntenticOsDeploymentSchema.nullable(),
+    rollbackQueued: z.boolean(),
+    // `staged != null || rollbackQueued`: the next boot changes what runs.
+    rebootRequired: z.boolean(),
+    health: IntenticOsHealthSchema,
+    isolation: IntenticOsIsolationSchema,
+    // Whether dockerd has the `kata` runtime.
+    vmRuntime: z.boolean(),
+});
+export type IntenticOsStatus = z.infer<typeof IntenticOsStatusSchema>;
+
+// `ic os update --check --json`: whether the registry has a newer image, and which. `version` and `digest` are null
+// when there is none.
+export const IntenticOsUpdateCheckSchema = z.object({
+    available: z.boolean(),
+    version: z.string().nullable(),
+    digest: z.string().nullable(),
+});
+export type IntenticOsUpdateCheck = z.infer<typeof IntenticOsUpdateCheckSchema>;
+
+// What an update does: `check` asks and changes nothing, `stage` downloads and stages for the next boot and restarts
+// nothing, `apply` stages and then reboots the machine into it.
+export const IntenticOsUpdateOpSchema = z.enum(["check", "stage", "apply"]);
+export type IntenticOsUpdateOp = z.infer<typeof IntenticOsUpdateOpSchema>;
+
+// THE ARGV, the one place any caller spells `ic os`. The verbs that reboot (`update --apply`, `rollback --apply`,
+// `reboot`) first leave every running sandbox the daemon's resume ask and record what runs, as every restart ic makes
+// does: none of that is the caller's to do.
+export const icOsStatusArgs = (): string[] => ["os", "status", "--json"];
+
+export const icOsUpdateArgs = (op: IntenticOsUpdateOp): string[] => {
+    if (op === "check") {
+        return ["os", "update", "--check", "--json"];
+    }
+    return op === "apply" ? ["os", "update", "--apply"] : ["os", "update"];
+};
+
+export const icOsRollbackArgs = (apply: boolean): string[] => (apply ? ["os", "rollback", "--apply"] : ["os", "rollback"]);
+
+export const icOsRebootArgs = (): string[] => ["os", "reboot"];
+
+// Checked here too, not only by a caller's schema: a channel is a positional, and one beginning with a hyphen would
+// reach ic as a flag.
+export const icOsChannelArgs = (channel: IntenticOsChannel): string[] => ["os", "channel", IntenticOsChannelSchema.parse(channel)];

package/src/schemas/members.test.ts

@@ -0,0 +1,47 @@
+import { accessRefusal, memberAccess, tierOf } from "./members.js";
+
+// A person's access is three answers, and the tier is what they add up to; a row from before the answers reads as its
+// role meant, so nobody's access moves when the daemon learns the new fields.
+
+describe(`memberAccess`, () => {
+    it(`reads a row written before agents and edit as its role meant`, () => {
+        expect(memberAccess({ role: `guest`, areas: [`support`] })).toEqual({ manage: false, agents: `chat`, see: [`support`], edit: `none` });
+        expect(memberAccess({ role: `viewer` })).toEqual({ manage: false, agents: `off`, see: undefined, edit: `none` });
+        expect(memberAccess({ role: `collaborator`, areas: [`web`] })).toEqual({ manage: false, agents: `run`, see: [`web`], edit: `none` });
+        expect(memberAccess({ role: `writer`, areas: [`web`] })).toEqual({ manage: false, agents: `run`, see: [`web`], edit: [`web`] });
+        expect(memberAccess({ role: `maintainer`, areas: [`web`] })).toEqual({ manage: true, agents: `run`, see: undefined, edit: `all` });
+    });
+
+    it(`takes what a row says when it says it, and never lets a chat edit`, () => {
+        expect(memberAccess({ role: `writer`, agents: `off`, edit: [`web`] })).toEqual({ manage: false, agents: `off`, see: undefined, edit: [`web`] });
+        expect(memberAccess({ role: `guest`, agents: `chat`, areas: [`support`], edit: `all` }).edit).toBe(`none`);
+    });
+});
+
+describe(`tierOf`, () => {
+    it(`names the tier the answers add up to`, () => {
+        expect(tierOf({ manage: true, agents: `run`, see: undefined, edit: `all` })).toBe(`maintainer`);
+        expect(tierOf({ manage: false, agents: `chat`, see: [`support`], edit: `none` })).toBe(`guest`);
+        expect(tierOf({ manage: false, agents: `off`, see: undefined, edit: [`web`] })).toBe(`writer`);
+        expect(tierOf({ manage: false, agents: `run`, see: undefined, edit: `none` })).toBe(`collaborator`);
+        expect(tierOf({ manage: false, agents: `off`, see: [`web`], edit: `none` })).toBe(`viewer`);
+    });
+});
+
+describe(`accessRefusal`, () => {
+    const access = (over: Partial<Parameters<typeof tierOf>[0]>) => ({ manage: false, agents: `run` as const, see: undefined, edit: `none` as const, ...over });
+
+    it(`asks a chat for the areas whose assistants it talks to`, () => {
+        expect(accessRefusal(access({ agents: `chat` }))).toContain(`at least one area`);
+        expect(accessRefusal(access({ agents: `chat`, see: [`support`] }))).toBeUndefined();
+    });
+
+    // Editing reaches only where they can look: everything needs the whole workspace, and each area named must be seen.
+    it(`keeps editing inside what they see`, () => {
+        expect(accessRefusal(access({ see: [`web`], edit: `all` }))).toContain(`whole workspace`);
+        expect(accessRefusal(access({ edit: `all` }))).toBeUndefined();
+        expect(accessRefusal(access({ see: [`web`], edit: [`web`, `finance`] }))).toContain(`finance`);
+        expect(accessRefusal(access({ edit: [`web`] }))).toBeUndefined();
+        expect(accessRefusal(access({ edit: [] }))).toContain(`at least one area`);
+    });
+});

package/src/schemas/members.ts

@@ -1,17 +1,134 @@
 // members: the daemon's shared-access roster (GET/POST/DELETE /members), who besides the owner reaches this sandbox
 import { z } from "zod";
-import { GrantedRoleSchema } from "./shared.js";
+import type { CapabilityKind } from "./capabilities.js";
+import { type GrantedRole, GrantedRoleSchema, MemberRoleSchema } from "./shared.js";
+
+// WHAT A PERSON'S CONVERSATIONS MAY SPEND: the connected capabilities (by id) and the stored secrets (by name) an agent
+// working for them is handed. Enforced by the daemon, not told to the model: a capability outside it is never mounted
+// for their turns, its variables and skill are left out, and every exit that spends a credential (a `{{secret:…}}`
+// reference, the credential gateway, an ssh signature, an account's password) refuses it with no card that could lift
+// it (secrets/credential-reach.ts). A conversation reaches only what every person who has written in it reaches, so
+// a person can never borrow more by replying in somebody else's.
+export const CredentialReachSchema = z.object({
+    capabilities: z.array(z.string().min(1)).max(500).describe("Connected capability ids their conversations may use."),
+    secrets: z.array(z.string().min(1)).max(500).describe("Stored secret names (not a capability's own) their conversations may use."),
+});
+export type CredentialReach = z.infer<typeof CredentialReachSchema>;
+
+// The capability kinds a reach can hold back, because each one reaches a turn only through something the daemon hands
+// it per turn (a mount, a variable, a signature, a gateway request). The rest are the sandbox's own machinery with no
+// value to withhold (Docker, a VPN once dialled, a mounted share, a local model, the wallet's owner-approved cards), so a
+// reach neither lists nor removes them: a switch for one would be a line on a screen.
+export const REACHABLE_CREDENTIAL_KINDS: readonly CapabilityKind[] = [
+    "cli",
+    "mcp",
+    "browser",
+    "identity",
+    "ssh",
+    "device",
+    "phone",
+    "webext",
+    "plugin",
+    "extension",
+];
+
+// WHAT ONE PERSON MAY DO, as three independent answers rather than one rung of a ladder: whether their conversations
+// run agents (`agents`), where they may look (`areas`, the fence their agents run inside too) and where they may change
+// files by hand (`edit`), and whether they manage the sandbox (the maintainer tier, which implies every other answer).
+// The `role` a row carries is the tier those answers make (`tierOf`), kept because the platform's invite record, the
+// presence list and every route's floor read a tier; a row written before the answers existed reads as its role meant
+// (`memberAccess`).
+// `chat` is the guest's way of working: it talks to the assistants that work in its areas and is shown nothing else of
+// the sandbox. `off` watches; `run` drives agents, whose work lands only when somebody who manages the sandbox lands it.
+export const AgentAccessSchema = z.enum(["off", "chat", "run"]);
+export type AgentAccess = z.infer<typeof AgentAccessSchema>;
+
+// Where a person may change files by hand: every folder they may see, or the areas named (each one they may see too).
+export const EditScopeSchema = z.union([z.literal("all"), z.array(z.string().min(1)).max(20)]);
+export type EditScope = z.infer<typeof EditScopeSchema>;
+
+/** A person's access resolved from their row: `see` undefined is the whole workspace, `edit` `none` changes nothing. */
+export interface MemberAccess {
+    readonly manage: boolean;
+    readonly agents: AgentAccess;
+    readonly see: readonly string[] | undefined;
+    readonly edit: "none" | "all" | readonly string[];
+}
+
+// The fields of a row or a grant that decide a person's access.
+interface AccessFields {
+    readonly role: GrantedRole;
+    readonly areas?: readonly string[] | undefined;
+    readonly agents?: AgentAccess | undefined;
+    readonly edit?: EditScope | undefined;
+}
+
+/** A row's access: what it says, and for a row written before `agents` and `edit` existed, what its role meant then. */
+export const memberAccess = (row: AccessFields): MemberAccess => {
+    if (row.role === "maintainer") {
+        return { manage: true, agents: "run", see: undefined, edit: "all" };
+    }
+    const agents = row.agents ?? (row.role === "guest" ? "chat" : row.role === "viewer" ? "off" : "run");
+    // A writer from before `edit` changes files where it sees them, which its areas always named.
+    const edit = row.edit ?? (row.role === "writer" && row.areas !== undefined ? [...row.areas] : "none");
+    return { manage: false, agents, see: row.areas, edit: agents === "chat" ? "none" : edit };
+};
+
+/** The tier an access makes: what every route's floor, the platform's record and the presence list read. */
+export const tierOf = (access: MemberAccess): GrantedRole => {
+    if (access.manage) {
+        return "maintainer";
+    }
+    if (access.agents === "chat") {
+        return "guest";
+    }
+    if (access.edit !== "none") {
+        return "writer";
+    }
+    return access.agents === "run" ? "collaborator" : "viewer";
+};
+
+/** Why an access cannot be granted on its face, before any area or assistant is looked up; undefined when it can. */
+export const accessRefusal = (access: MemberAccess): string | undefined => {
+    if (access.manage) {
+        return undefined;
+    }
+    if (access.agents === "chat" && (access.see?.length ?? 0) === 0) {
+        return "chatting with assistants needs at least one area: the assistants that work there are the ones they talk to";
+    }
+    if (access.edit === "all") {
+        return access.see === undefined ? undefined : "editing everything they see needs the whole workspace; name the areas to edit instead";
+    }
+    if (access.edit === "none") {
+        return undefined;
+    }
+    if (access.edit.length === 0) {
+        return "editing needs at least one area to edit in";
+    }
+    const seen = access.see;
+    const unseen = seen === undefined ? [] : access.edit.filter((area) => !seen.includes(area));
+    return unseen.length === 0 ? undefined : `they can only edit where they can see: ${unseen.join(", ")} is not among their areas`;
+};
 
 // One person on the roster as the daemon answers it. `areas` fences what of the workspace they reach, and with it which
 // assistants they may talk to: absent is the whole workspace, empty is nothing.
 export const MemberSchema = z.object({
     email: z.string().describe("Who, lowercased."),
-    role: GrantedRoleSchema.describe("The tier they were granted."),
-    areas: z.array(z.string()).optional().describe("The areas they are fenced to. Absent means the whole workspace."),
+    role: GrantedRoleSchema.describe("The tier their access makes: maintainer when they manage the sandbox, else what `agents` and `edit` add up to."),
+    areas: z.array(z.string()).optional().describe("The areas they may see, and their agents work in. Absent means the whole workspace."),
+    agents: AgentAccessSchema.optional().describe(
+        "Whether their conversations run agents: off (they watch), chat (only with the assistants in their areas, nothing else of the sandbox), or run. Absent means what their role meant.",
+    ),
+    edit: EditScopeSchema.optional().describe(
+        "Where they may change files by hand: everything they see, or these areas. Absent means nowhere, or for a writer its areas.",
+    ),
     emailSignIn: z
         .boolean()
         .optional()
         .describe("Whether they may sign in with an email code the platform confirmed, rather than only with Google or a passkey. Absent means no."),
+    credentials: CredentialReachSchema.optional().describe(
+        "The capabilities and secrets their conversations may spend. Absent means every one, including any connected later.",
+    ),
 });
 export type Member = z.infer<typeof MemberSchema>;
 
@@ -24,18 +141,36 @@ export type MembersList = z.infer<typeof MembersListSchema>;
 export const MembersRosterSchema = MembersListSchema.extend({ owner: z.string().optional() });
 export type MembersRoster = z.infer<typeof MembersRosterSchema>;
 
-// POST /members: a grant is a role decision, so the role is required. Areas are optional, their absence being the whole
-// workspace; a writer and a guest are refused without them, since for those two tiers the fence is the tier.
+// POST /members: the role is required, the tier the grant makes. Areas are optional, their absence being the whole
+// workspace; chatting with assistants needs them, since the assistants working there are the whole of that access.
 // `emailSignIn` lets the platform's identity assertion open this sandbox for them (policy/identity-assertion.ts): true
 // allows it, false takes it back, absent keeps what the row already says, so a re-grade from an editor that predates
-// the field never drops it.
+// the field never drops it. `credentials` the same way: `all` lifts a reach, a list sets one, absent keeps the row's,
+// so a re-grade that never mentions it can never widen what a person's conversations may spend. A maintainer is refused
+// a list: that tier reads every credential.
+// `agents` and `edit` decide the rest of the access; absent, the role's own meaning stands, so an editor that predates
+// them still grants what it always did. The role sent must be the tier the access makes (`tierOf`): two answers to one
+// question are refused rather than one of them guessed away.
 export const MemberGrantSchema = z.object({
     email: z.string(),
     role: GrantedRoleSchema,
     areas: z.array(z.string().min(1)).max(20).optional(),
+    agents: AgentAccessSchema.optional(),
+    edit: EditScopeSchema.optional(),
     emailSignIn: z.boolean().optional(),
+    credentials: z.union([z.literal("all"), CredentialReachSchema]).optional(),
 });
 export type MemberGrant = z.infer<typeof MemberGrantSchema>;
 
+// GET /members/self: what the signed-in person may do here, for an editor that offers only what will be taken. The
+// owner reads as managing everything.
+export const MemberSelfSchema = z.object({
+    role: MemberRoleSchema.describe("Their tier on this sandbox."),
+    agents: AgentAccessSchema.describe("Whether their conversations run agents."),
+    areas: z.array(z.string()).optional().describe("The areas they may see. Absent means the whole workspace."),
+    edit: z.union([z.literal("none"), EditScopeSchema]).describe("Where they may change files by hand."),
+});
+export type MemberSelf = z.infer<typeof MemberSelfSchema>;
+
 // DELETE /members: whose access to take back.
 export const MemberEmailSchema = z.object({ email: z.string() });

package/src/schemas/providers/provider-oauth.ts

@@ -20,7 +20,7 @@ export const OauthAccountSchema = z.object({
         .string()
         .optional()
         .describe(
-            "Which of the provider's estates it signs in to, for a provider selling more than one (Z.ai's international or mainland plan). With the email and organisation, it is who the account is: a sign-in matching all three lands on this account again, same id.",
+            "Which of the provider's sign-ins it came from: the estate, for a provider selling more than one (Z.ai's international or mainland plan), or the loop's own door, for a loop that signs in with a program of its own (Grok Build's CLI beside Grok's OpenCode sign-in). With the email and organisation, it is who the account is: a sign-in matching all three lands on this account again, same id.",
         ),
     scope: z.string().optional().describe("What the credential is permitted to do, in the provider's terms."),
     connectedAt: z.number().describe("When it was connected, in milliseconds."),