@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/autonomy.d.ts

@@ -0,0 +1,45 @@
+import { type EnvironmentDiagnostic } from './environment/contract.js';
+import type { CockpitConfig, Decider, WorkGrading } from './schema.js';
+export type WorkGate = 'accept' | 'amend' | 'answer' | 'signoff' | 'acknowledge';
+type AutonomyDecision = 'sync' | 'stale_delete' | 'reset' | 'mcp_approve';
+export interface EffectivePolicy {
+    readonly grading: WorkGrading;
+    readonly gates: Readonly<Record<WorkGate, Decider>>;
+    readonly autonomy: Readonly<Record<AutonomyDecision, Decider>>;
+}
+export declare const GATE_DEFAULTS: Readonly<Record<WorkGate, Decider>>;
+export declare const AUTONOMY_DEFAULTS: Readonly<Record<AutonomyDecision, Decider>>;
+export declare function effectivePolicy(config: Readonly<{
+    work: Readonly<Pick<CockpitConfig['work'], 'grading'> & {
+        gates: Readonly<CockpitConfig['work']['gates']>;
+    }>;
+    autonomy: Readonly<CockpitConfig['autonomy']>;
+}>): EffectivePolicy;
+/** cockpit detects CI from the CI variable, as every hosted runner sets it; an agent can set it too. */
+export declare function runningInCi(env: Readonly<Record<string, string | undefined>>): boolean;
+/**
+ * Whether this run may pass the decision without a person. A `person` decision is never passed here:
+ * its caller asks for the typed digest. A `ci` decision passes only under CI, where a protected
+ * environment's reviewers are the human gate; locally that is best-effort, as an agent can set CI too.
+ */
+export declare function decide(decider: Decider, env: Readonly<Record<string, string | undefined>>): 'proceed' | 'person' | 'ci-only';
+export interface PolicyWeakening {
+    readonly field: string;
+    readonly from: string;
+    readonly to: string;
+}
+/** Every field `current` sets weaker than `recorded`, named as cockpit.toml spells it. */
+export declare function policyWeakening(recorded: EffectivePolicy, current: EffectivePolicy): readonly PolicyWeakening[];
+/** The error `check` reports while cockpit.toml sits weaker than the recorded policy; sync would refuse the same change. */
+export declare function policyWeakeningDiagnostic(weakened: readonly PolicyWeakening[]): EnvironmentDiagnostic;
+/** The digest a person types to accept exactly these weakenings of exactly this recorded policy. */
+export declare function weakeningDigest(recorded: EffectivePolicy, current: EffectivePolicy): string;
+/** The policy the last sync recorded, or undefined before the first; an unreadable record refuses. */
+export declare function readRecordedPolicy(root: string): Promise<EffectivePolicy | undefined>;
+export declare function writeRecordedPolicy(root: string, policy: EffectivePolicy): Promise<void>;
+/**
+ * The cockpit.toml tables the guard keeps an agent from editing, as parsed values to compare, or
+ * undefined when the text is not TOML. [mcp] is pinned only while a person approves MCP servers.
+ */
+export declare function pinnedPolicyTables(text: string): Readonly<Record<string, unknown>> | undefined;
+export {};

package/dist/autonomy.js

@@ -0,0 +1,173 @@
+// Owns the autonomy policy: who may pass each decision point cockpit gates, as cockpit.toml's [work]
+// and [autonomy] tables declare it, what an unset field means, which change weakens it, and the
+// record of the policy the last sync accepted. Every command that gates a decision asks `decide`
+// here, so a field cannot mean one thing to sync and another to the guard.
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, open, rename, rm } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { parse as parseToml, TomlError } from 'smol-toml';
+import { readBoundedFile } from './bounded-read.js';
+import { hasErrorCode, RefusalError } from './environment/contract.js';
+// The owner's defaults: an agent runs cockpit end to end except where stack data is lost or a process
+// would start outside the guard, and a team opts into person or CI gates field by field. A sibling's
+// MCP source is an ordinary file an agent writes, and a harness starts an enabled server outside every
+// guard boundary, so an agent approving MCP servers could run any command it wrote there. Test
+// weakening is judged by the grading model where one grades, so acknowledging it is the agent's too.
+export const GATE_DEFAULTS = Object.freeze({ accept: 'agent', amend: 'agent', answer: 'agent', signoff: 'agent', acknowledge: 'agent' });
+export const AUTONOMY_DEFAULTS = Object.freeze({ sync: 'agent', stale_delete: 'agent', reset: 'person', mcp_approve: 'person' });
+export function effectivePolicy(config) {
+    const pick = (declared, defaults) => Object.fromEntries(Object.entries(defaults).map(([key, value]) => [key, declared[key] ?? value]));
+    return {
+        grading: config.work.grading,
+        gates: pick(config.work.gates, GATE_DEFAULTS),
+        autonomy: pick({ sync: config.autonomy.sync, stale_delete: config.autonomy.stale_delete,
+            reset: config.autonomy.reset, mcp_approve: config.autonomy.mcp_approve }, AUTONOMY_DEFAULTS),
+    };
+}
+/** cockpit detects CI from the CI variable, as every hosted runner sets it; an agent can set it too. */
+export function runningInCi(env) {
+    return typeof env.CI === 'string' && env.CI.length > 0 && env.CI !== 'false' && env.CI !== '0';
+}
+/**
+ * Whether this run may pass the decision without a person. A `person` decision is never passed here:
+ * its caller asks for the typed digest. A `ci` decision passes only under CI, where a protected
+ * environment's reviewers are the human gate; locally that is best-effort, as an agent can set CI too.
+ */
+export function decide(decider, env) {
+    if (decider === 'agent')
+        return 'proceed';
+    if (decider === 'person')
+        return 'person';
+    return runningInCi(env) ? 'proceed' : 'ci-only';
+}
+// Stronger is later: an agent decision is the weakest, CI behind reviewers the strongest.
+const DECIDER_RANK = Object.freeze({ agent: 0, person: 1, ci: 2 });
+const GRADING_RANK = Object.freeze({ self: 0, checks: 1, independent: 2 });
+/** Every field `current` sets weaker than `recorded`, named as cockpit.toml spells it. */
+export function policyWeakening(recorded, current) {
+    const rows = [];
+    if (GRADING_RANK[current.grading] < GRADING_RANK[recorded.grading])
+        rows.push({ field: 'work.grading', from: recorded.grading, to: current.grading });
+    for (const [table, field] of [['gates', 'work.gates'], ['autonomy', 'autonomy']]) {
+        for (const [key, was] of Object.entries(recorded[table])) {
+            const now = current[table][key];
+            if (DECIDER_RANK[now] < DECIDER_RANK[was])
+                rows.push({ field: `${field}.${key}`, from: was, to: now });
+        }
+    }
+    return rows;
+}
+/** The error `check` reports while cockpit.toml sits weaker than the recorded policy; sync would refuse the same change. */
+export function policyWeakeningDiagnostic(weakened) {
+    const shown = weakened.map(row => `${row.field}: ${row.from} -> ${row.to}`).join('; ');
+    return { severity: 'error', target: 'autonomy',
+        code: 'POLICY_WEAKENING_UNCONFIRMED',
+        message: `cockpit.toml weakens the policy the last sync recorded (${shown})`,
+        fix: 'a person runs npx --no cockpit sync --config <your cockpit.toml> --interactive in a terminal outside CI, reads the weakening it shows and types its digest, or the change is reverted' };
+}
+/** The digest a person types to accept exactly these weakenings of exactly this recorded policy. */
+export function weakeningDigest(recorded, current) {
+    return createHash('sha256').update(JSON.stringify({ recorded, current })).digest('hex');
+}
+// Written only by cockpit: the guard protects `.cockpit/policy.json` as a control, so the policy an
+// agent's edit would weaken still stands until a person accepts the weakening at sync.
+const POLICY_RECORD_PATH = '.cockpit/policy.json';
+const RECORD_FORMAT = 'cockpit-policy/v1';
+// A record written before a decision point existed lacks its key: the 0.1.0 record has no
+// `acknowledge`. The missing decider is read as `person`, so a default that now hands it to the agent
+// is reported as a weakening a person accepts once at sync, not refused for good nor passed unseen. An
+// unknown key or value was not written by cockpit and refuses.
+function recordedPolicy(value) {
+    const deciders = (table, defaults) => {
+        if (typeof table !== 'object' || table === null || Array.isArray(table))
+            return undefined;
+        if (Object.entries(table).some(([key, entry]) => !Object.hasOwn(defaults, key) || !Object.hasOwn(DECIDER_RANK, entry)))
+            return undefined;
+        const declared = table;
+        return Object.fromEntries(Object.keys(defaults).map(key => [key, declared[key] ?? 'person']));
+    };
+    if (typeof value !== 'object' || value === null || Object.keys(value).sort().join() !== 'autonomy,gates,grading')
+        return undefined;
+    const row = value;
+    const gates = deciders(row.gates, GATE_DEFAULTS);
+    const autonomy = deciders(row.autonomy, AUTONOMY_DEFAULTS);
+    return Object.hasOwn(GRADING_RANK, row.grading) && gates && autonomy ? { grading: row.grading, gates, autonomy } : undefined;
+}
+// Restoring the committed copy helps only where the damage is uncommitted; where the committed copy is the
+// damaged one, the record is a person's to remove, after which the next sync records cockpit.toml's policy.
+const DAMAGED_RECORD_REMEDY = `restore the committed copy with git restore -- ${POLICY_RECORD_PATH}, or if that copy is the damaged one, `
+    + `a person deletes ${POLICY_RECORD_PATH} and runs npx --no cockpit sync --config <your cockpit.toml> --interactive to record the policy cockpit.toml declares`;
+/** The policy the last sync recorded, or undefined before the first; an unreadable record refuses. */
+export async function readRecordedPolicy(root) {
+    const path = join(root, POLICY_RECORD_PATH);
+    const unusable = `${POLICY_RECORD_PATH} is not a regular file of at most 64 KiB; restore it with git restore -- ${POLICY_RECORD_PATH}`;
+    let read;
+    try {
+        read = readBoundedFile(path, 65_536);
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'ENOENT'))
+            return undefined;
+        if (hasErrorCode(error, 'ELOOP', 'EISDIR', 'EIO'))
+            throw new RefusalError(unusable);
+        throw error;
+    }
+    if (read.kind === 'too-large')
+        throw new RefusalError(unusable);
+    const bytes = read.bytes;
+    let parsed;
+    try {
+        parsed = JSON.parse(bytes.toString('utf8'));
+    }
+    catch (error) {
+        if (!(error instanceof SyntaxError))
+            throw error;
+        throw new RefusalError(`${POLICY_RECORD_PATH} is not JSON; ${DAMAGED_RECORD_REMEDY}`);
+    }
+    const record = parsed;
+    const policy = record?.format === RECORD_FORMAT ? recordedPolicy(record.policy) : undefined;
+    if (!policy)
+        throw new RefusalError(`${POLICY_RECORD_PATH} is not a ${RECORD_FORMAT} record (an unknown format, table, key, decider or grading); ${DAMAGED_RECORD_REMEDY}`);
+    return policy;
+}
+export async function writeRecordedPolicy(root, policy) {
+    const path = join(root, POLICY_RECORD_PATH);
+    if (isDeepStrictEqual(await readRecordedPolicy(root), policy))
+        return;
+    await mkdir(dirname(path), { recursive: true });
+    const staged = `${path}.${randomUUID()}.tmp`;
+    const handle = await open(staged, 'wx', 0o644);
+    try {
+        await handle.writeFile(`${JSON.stringify({ format: RECORD_FORMAT, policy }, null, 2)}\n`);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    try {
+        await rename(staged, path);
+    }
+    catch (error) {
+        await rm(staged, { force: true });
+        throw error;
+    }
+}
+/**
+ * The cockpit.toml tables the guard keeps an agent from editing, as parsed values to compare, or
+ * undefined when the text is not TOML. [mcp] is pinned only while a person approves MCP servers.
+ */
+export function pinnedPolicyTables(text) {
+    let parsed;
+    try {
+        parsed = parseToml(text);
+    }
+    catch (error) {
+        if (error instanceof TomlError)
+            return undefined;
+        throw error;
+    }
+    const autonomy = parsed.autonomy;
+    const mcpByAgent = (autonomy?.mcp_approve ?? AUTONOMY_DEFAULTS.mcp_approve) === 'agent';
+    return { work: parsed.work, autonomy: parsed.autonomy, ...(mcpByAgent ? {} : { mcp: parsed.mcp }) };
+}

package/dist/bounded-read.d.ts

@@ -0,0 +1,14 @@
+export type BoundedRead = Readonly<{
+    kind: 'complete';
+    bytes: Buffer;
+}> | Readonly<{
+    kind: 'too-large';
+}>;
+/**
+ * Reads a whole regular file without following a symbolic link at its last component and without
+ * blocking on a FIFO, so an agent-writable path cannot redirect or stall the read. A file larger
+ * than maxBytes is `too-large`. One that is not regular is refused with code EISDIR; one whose
+ * identity, size or times change while it is read, or whose name stops naming the opened file, with
+ * code EIO. Open errors such as ENOENT or ELOOP propagate.
+ */
+export declare function readBoundedFile(path: string, maxBytes: number): BoundedRead;

package/dist/bounded-read.js

@@ -0,0 +1,42 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync } from 'node:fs';
+import { RefusalError } from './environment/contract.js';
+function sameFile(left, right) {
+    return left.dev === right.dev && left.ino === right.ino && left.size === right.size
+        && left.mtimeMs === right.mtimeMs && left.ctimeMs === right.ctimeMs;
+}
+/**
+ * Reads a whole regular file without following a symbolic link at its last component and without
+ * blocking on a FIFO, so an agent-writable path cannot redirect or stall the read. A file larger
+ * than maxBytes is `too-large`. One that is not regular is refused with code EISDIR; one whose
+ * identity, size or times change while it is read, or whose name stops naming the opened file, with
+ * code EIO. Open errors such as ENOENT or ELOOP propagate.
+ */
+export function readBoundedFile(path, maxBytes) {
+    const descriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const opened = fstatSync(descriptor);
+        if (!opened.isFile())
+            throw Object.assign(new RefusalError(`${path} is not a regular file`), { code: 'EISDIR' });
+        if (opened.size > maxBytes)
+            return { kind: 'too-large' };
+        // One byte past the observed size shows a file that grew while it was read.
+        const buffer = Buffer.alloc(opened.size + 1);
+        let length = 0;
+        while (length < buffer.length) {
+            const read = readSync(descriptor, buffer, length, buffer.length - length, null);
+            if (read === 0)
+                break;
+            length += read;
+        }
+        if (length > maxBytes)
+            return { kind: 'too-large' };
+        const named = lstatSync(path);
+        if (length !== opened.size || !sameFile(opened, fstatSync(descriptor)) || named.isSymbolicLink() || !sameFile(opened, named)) {
+            throw Object.assign(new RefusalError(`${path} changed while it was read`), { code: 'EIO' });
+        }
+        return { kind: 'complete', bytes: buffer.subarray(0, length) };
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}

package/dist/browser/commands.d.ts

@@ -0,0 +1,117 @@
+import { type HolderId, type StackId } from '../environment/contract.js';
+import { type StateNamespace } from '../environment/state.js';
+import { type BrowserRuntimeProjection } from './runtime.js';
+import { type BrowserProjectClient } from './surfaces.js';
+export type BrowserCommandKind = 'drive' | 'screenshot';
+interface BrowserRouteDeclaration {
+    readonly name: string;
+    readonly path: string;
+}
+export interface BrowserRoutePolicy {
+    readonly origin: string;
+    readonly surfaces: readonly Readonly<{
+        name: string;
+        url: string;
+    }>[];
+}
+type BrowserDiagnosticEntry = Readonly<{
+    kind: 'console';
+    path?: string;
+    line?: number;
+}> | Readonly<{
+    kind: 'pageerror';
+    name: string;
+}> | Readonly<{
+    kind: 'request';
+    method: string;
+    path: string;
+    status: number;
+} | {
+    kind: 'request';
+    method: string;
+    path: string;
+    failure: string;
+}>;
+/**
+ * Console and uncaught error text, capped in count and bytes. It is page content, so a reader treats
+ * it as data and never as instructions. Present only for a data posture that is isolated, not
+ * restored and not reaching production; otherwise `omitted` says why there is none.
+ */
+type BrowserMessageExcerpt = Readonly<{
+    trust: 'untrusted-page-content';
+    messages: readonly Readonly<{
+        kind: 'console' | 'pageerror';
+        text: string;
+    }>[];
+}> | Readonly<{
+    omitted: string;
+}>;
+/** What a route's page did wrong. Identifiers and counts, plus a message excerpt where the data posture allows it: never bodies, headers or cookies. */
+interface BrowserRouteDiagnostics {
+    readonly consoleErrors: number;
+    readonly consoleWarnings: number;
+    readonly pageErrors: number;
+    readonly failedRequests: number;
+    readonly abortedRequests: number;
+    readonly thirdParty: Readonly<{
+        requests: number;
+        failed: number;
+    }>;
+    readonly entries: readonly BrowserDiagnosticEntry[];
+    readonly omitted: number;
+    readonly excerpt: BrowserMessageExcerpt;
+}
+type BrowserRouteVerdict = 'clean' | 'findings';
+export interface BrowserCommandInput {
+    readonly runtime: BrowserRuntimeProjection;
+    readonly client: BrowserProjectClient;
+    readonly policy: BrowserRoutePolicy;
+    readonly kind: BrowserCommandKind;
+    /** A declared route's name or path; every declared route is driven when absent. */
+    readonly route?: string;
+    readonly role?: string;
+    readonly state?: Readonly<{
+        namespace: StateNamespace;
+        stackId: StackId;
+        ownerId: HolderId;
+    }>;
+}
+interface BrowserCommandSurfaceReceipt {
+    readonly name: string;
+    readonly url: string;
+    readonly screenshot?: Readonly<{
+        path: string;
+        sha256: string;
+        byteLength: number;
+    }>;
+    readonly diagnostics?: BrowserRouteDiagnostics;
+    readonly verdict?: BrowserRouteVerdict;
+}
+export interface BrowserCommandReceipt {
+    readonly kind: BrowserCommandKind;
+    readonly activation: 'application';
+    readonly authentication: Readonly<{
+        posture: 'bypassed' | 'none';
+    } | {
+        posture: 'real';
+        role: string;
+        policy: 'serialized' | 'per-worker';
+    }>;
+    readonly surfaces: readonly Readonly<BrowserCommandSurfaceReceipt>[];
+    /** drive only: findings when any route has console errors, uncaught errors or failed own-origin requests. */
+    readonly verdict?: BrowserRouteVerdict;
+}
+export type BrowserCommandResult = Readonly<{
+    kind: 'complete';
+    receipt: BrowserCommandReceipt;
+}> | Readonly<{
+    kind: 'refusal';
+    reason: string;
+}>;
+export declare function issueBrowserRoutePolicy(runtime: BrowserRuntimeProjection, input: Readonly<{
+    origin: string;
+    routes: readonly BrowserRouteDeclaration[];
+}>): BrowserRoutePolicy;
+export declare function isIssuedBrowserCommandReceipt(value: unknown): value is BrowserCommandReceipt;
+export declare function executeBrowserCommand(value: BrowserCommandInput): Promise<BrowserCommandResult>;
+export {};