agy-worker-mcp 0.3.1

package/dist/policy/ceiling.js

@@ -0,0 +1,273 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { canonicalize } from '../contract/paths.js';
+import { ValidationError } from '../contract/errors.js';
+import { HARD_DENY } from './hard-deny.js';
+import { matchesPathGlob, parseRule } from './rules.js';
+export const EMPTY_CEILING = Object.freeze({
+    present: false,
+    path: null,
+    allow: [],
+    deny: [],
+    exceptions: [],
+    sandbox: 'none',
+    read_roots: [],
+    write_roots: [],
+    command_policy: 'allowlist',
+    version: null,
+    warnings: [],
+});
+const ceilingSchemaV1 = z.object({
+    version: z.literal(1),
+    extra_allow: z.array(z.string()).optional(),
+    extra_deny: z.array(z.string()).optional(),
+    sandboxed: z.boolean().optional(),
+    additional_dirs: z.array(z.string()).optional(),
+    command_policy: z.enum(['allowlist', 'denylist']).optional(),
+}).strict();
+const ceilingSchemaV2 = z.object({
+    version: z.literal(2),
+    allow: z.array(z.string()).optional(),
+    deny: z.array(z.string()).optional(),
+    exceptions: z.array(z.string()).optional(),
+    sandbox: z.enum(['none', 'seatbelt', 'agy']).optional(),
+    /** Legacy spelling of `sandbox: 'agy'`; kept so a 0.2.x v2-shaped file still loads. */
+    sandboxed: z.boolean().optional(),
+    read_roots: z.array(z.string()).optional(),
+    write_roots: z.array(z.string()).optional(),
+    command_policy: z.enum(['allowlist', 'denylist']).optional(),
+}).strict();
+const ceilingSchema = z.discriminatedUnion('version', [ceilingSchemaV1, ceilingSchemaV2]);
+/** v1 → v2 key names, for the conversion warning and the error text. */
+const V1_RENAMES = [
+    ['extra_allow', 'allow'],
+    ['extra_deny', 'deny'],
+    ['additional_dirs', 'read_roots'],
+];
+/** `<project state dir>/policy.json`. Exported so callers (capabilities, tests) don't hardcode the filename. */
+export function ceilingPath(paths) {
+    return join(paths.dir, 'policy.json');
+}
+function expandHome(p) {
+    const home = process.env.HOME ?? homedir();
+    if (p === '~')
+        return home;
+    if (p.startsWith('~/'))
+        return join(home, p.slice(2));
+    return p;
+}
+/**
+ * Best-effort absolute form of a `read_roots` entry. `canonicalize()`
+ * (`contract/paths.ts`) never treats `*`/`**` specially — it only resolves real
+ * ancestors via `realpathSync` and appends whatever tail does not exist yet —
+ * so a glob segment simply survives as literal path content, which is exactly
+ * what `matchesPathGlob` expects to match against later.
+ */
+function resolveDirPattern(pattern) {
+    return canonicalize(expandHome(pattern));
+}
+/**
+ * Convert a ceiling `read_roots` pattern (potentially a glob like `~/.jdks/**`)
+ * into a concrete directory root for `--add-dir`.
+ *
+ * Takes the fixed prefix before the first wildcard (`*`), strips trailing `/`,
+ * resolves home expansion and canonicalization via `resolveDirPattern`, and returns
+ * the canonical directory path if it exists and is a directory; otherwise null.
+ */
+export function additionalDirRoot(pattern) {
+    const starIdx = pattern.indexOf('*');
+    let prefix = starIdx === -1 ? pattern : pattern.slice(0, starIdx);
+    while (prefix.length > 1 && prefix.endsWith('/')) {
+        prefix = prefix.slice(0, -1);
+    }
+    if (prefix === '')
+        return null;
+    const resolved = resolveDirPattern(prefix);
+    try {
+        if (existsSync(resolved) && statSync(resolved).isDirectory()) {
+            return canonicalize(resolved);
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+/** Every throw from `loadCeiling` goes through here so the shape stays uniform. */
+function fail(path, expected, value) {
+    throw new ValidationError({
+        field: 'ceiling',
+        value: value ?? path,
+        expected: `${expected} — fix ${path}`,
+    });
+}
+/**
+ * Load and validate the project ceiling.
+ *
+ * Missing file → {@link EMPTY_CEILING} (a project with no ceiling file grants
+ * nothing beyond the profiles' own defaults — narrower, not wider, than
+ * having one). Present but invalid — bad JSON, `version` other than `1`/`2`, a
+ * non-string entry, an entry that does not parse as `verb(pattern)`
+ * (`parseRule`), or a legacy `unsandboxed` entry — throws
+ * {@link ValidationError} with `field: 'ceiling'` and the file path, so
+ * `agy_start` fails closed and tells the human what to fix instead of quietly
+ * falling back to an empty ceiling (which would look like "nothing is
+ * misconfigured" when something very much is).
+ *
+ * `{workspace}` substitution on `allow`/`deny`/`exceptions` is
+ * deferred to `resolvePolicy` — this file has no workspace of its own; one
+ * project can run jobs against several `cwd` values under the same ceiling.
+ * `read_roots` entries are not job-specific, so they are `~`-expanded and
+ * canonicalized once, here.
+ */
+export function loadCeiling(paths) {
+    const path = ceilingPath(paths);
+    if (!existsSync(path))
+        return { ...EMPTY_CEILING, path };
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (e) {
+        return fail(path, `policy.json exists but could not be read (${String(e)})`);
+    }
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch {
+        return fail(path, 'policy.json is not valid JSON');
+    }
+    return parseCeilingJson(json, path);
+}
+/**
+ * The validation half of {@link loadCeiling}, separated so `agy_ceiling` can
+ * check a draft that exists only in the caller's hands — same rules, same
+ * error texts, no file. `path` only labels the error.
+ */
+export function parseCeilingJson(json, path) {
+    if (typeof json === 'object' && json !== null && 'unsandboxed' in json) {
+        return fail(path, 'the "unsandboxed" key was removed in 0.2.1; allowed commands now run without agy\'s OS sandbox by default. Delete "unsandboxed" from policy.json (and set "sandboxed": true if you want the old behaviour of forcing the sandbox on)');
+    }
+    const parsed = ceilingSchema.safeParse(json);
+    if (!parsed.success) {
+        return fail(path, `policy.json must be { version: 2, allow?, deny?, exceptions?, sandbox?, read_roots?, write_roots?, command_policy? } (${parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ')})`, json);
+    }
+    const warnings = [];
+    let allow;
+    let deny;
+    let exceptions;
+    let readRoots;
+    let writeRoots = [];
+    let sandbox;
+    const d = parsed.data;
+    if (d.version === 1) {
+        sandbox = d.sandboxed ? 'agy' : 'none';
+        allow = d.extra_allow ?? [];
+        deny = d.extra_deny ?? [];
+        exceptions = [];
+        readRoots = d.additional_dirs ?? [];
+        const present = V1_RENAMES.filter(([from]) => from in json);
+        warnings.push(`policy.json is version 1; rename ${present.length > 0 ? present.map(([a, b]) => `${a} → ${b}`).join(', ') : 'its keys'} and set "version": 2 (v1 is read and converted in 0.3.x, removed in 0.4)`);
+    }
+    else {
+        allow = d.allow ?? [];
+        deny = d.deny ?? [];
+        exceptions = d.exceptions ?? [];
+        readRoots = d.read_roots ?? [];
+        writeRoots = d.write_roots ?? [];
+        if (d.sandbox !== undefined && d.sandboxed !== undefined) {
+            return fail(path, 'policy.json sets both "sandbox" and the legacy "sandboxed"; keep "sandbox" only');
+        }
+        sandbox = d.sandbox ?? (d.sandboxed ? 'agy' : 'none');
+        if (d.sandboxed !== undefined) {
+            warnings.push('policy.json uses the legacy "sandboxed" key; write "sandbox": "agy" (or "none") instead');
+        }
+    }
+    const commandPolicy = d.command_policy ?? 'allowlist';
+    for (const root of writeRoots) {
+        if (root.includes('*')) {
+            return fail(path, `write_roots entry is a glob (${root}); write roots are plain directories`);
+        }
+    }
+    for (const rule of [...allow, ...deny, ...exceptions]) {
+        try {
+            parseRule(rule);
+        }
+        catch {
+            return fail(path, `allow/deny/exceptions entry is not a valid "verb(pattern)" rule: ${rule}`);
+        }
+    }
+    for (const rule of exceptions) {
+        if (HARD_DENY.includes(rule)) {
+            return fail(path, `exceptions may not lift a HARD_DENY rule (${rule}); those protect the gate itself (.agents, credentials, subagents) and cannot be opened by any file`);
+        }
+    }
+    return {
+        present: true,
+        path,
+        allow,
+        deny,
+        exceptions,
+        sandbox,
+        read_roots: readRoots.map(resolveDirPattern),
+        write_roots: Array.from(new Set(writeRoots.map(resolveDirPattern))),
+        command_policy: commandPolicy,
+        version: d.version,
+        warnings,
+    };
+}
+/**
+ * Is `canonicalDir` (already `~`-expanded/canonicalized, e.g. via
+ * {@link resolveDirPattern}) covered by some glob in the ceiling's
+ * `read_roots`? The one place `read_roots` matching happens, so
+ * `resolvePolicy` and any test never re-implement the glob semantics.
+ */
+export function additionalDirCovered(ceiling, canonicalDir) {
+    return ceiling.read_roots.some((pattern) => matchesPathGlob(pattern, canonicalDir));
+}
+/** `~`-expand and canonicalize a requested `read_roots` entry the same way ceiling entries are resolved. */
+export function resolveRequestedDir(pattern) {
+    return resolveDirPattern(pattern);
+}
+/**
+ * Render a loaded ceiling for `agy_capabilities`.
+ *
+ * No `{workspace}` substitution: capabilities has no per-job workspace (a
+ * project can run jobs against several `cwd` values), so a rule string
+ * carrying the literal `{workspace}` placeholder is returned exactly as
+ * written in `policy.json`. A caller sees the substituted, job-real form in
+ * `agy_start`'s own `policy_summary` instead.
+ */
+/**
+ * The one sentence every surface says when there is no ceiling file. Not an
+ * error — the profile as shipped is the safe default — but the agent and the
+ * user should both know that the door exists and who holds the key: the user
+ * approves, the agent (via `agy_ceiling` / the `agy-ceiling` skill) or the
+ * user (via `/agy-ceiling`) drafts.
+ */
+export function ceilingAbsenceHint(path) {
+    const where = path ? ` at ${path}` : '';
+    return (`no project ceiling${where}: jobs run with the profile as shipped (general_worker allows build/test tools and local git; ` +
+        `git push, curl, wget, ssh, sudo, docker, npm/pip install and rm -rf are denied, and any other command is denied unless the ceiling allows it). ` +
+        `If this project needs more, propose a ceiling: call agy_ceiling (or the user runs /agy-ceiling, or use the agy-ceiling skill), ` +
+        `show the draft, and write the file only after the user approves it in this conversation.`);
+}
+export function describeCeiling(ceiling, path, present) {
+    return {
+        path,
+        present,
+        version: ceiling.version,
+        allow: ceiling.allow,
+        deny: ceiling.deny,
+        exceptions: ceiling.exceptions,
+        sandbox: ceiling.sandbox,
+        read_roots: ceiling.read_roots,
+        write_roots: ceiling.write_roots,
+        command_policy: ceiling.command_policy,
+        warnings: present ? ceiling.warnings : [...ceiling.warnings, ceilingAbsenceHint(path)],
+    };
+}
+//# sourceMappingURL=ceiling.js.map

package/dist/policy/ceiling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ceiling.js","sourceRoot":"","sources":["../../src/policy/ceiling.ts"],"names":[],"mappings":"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"}

package/dist/policy/containment.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Read/write root enforcement.
+ *
+ * The primitives live in `contract/paths.ts` (`canonicalize`, `isWithin`,
+ * `assertContained`); this module is the policy layer that decides which roots a
+ * job gets and pulls the paths out of a tool call.
+ */
+export interface ContainmentRoots {
+    read: string[];
+    write: string[];
+}
+/**
+ * Roots for a job. Write is the workspace alone. Read may include a small set of
+ * additional canonical directories, but never credential paths.
+ */
+export declare function buildRoots(workspace: string, extraRead?: string[]): ContainmentRoots;
+/** @throws {import('../contract/errors.js').PathEscapeError} */
+export declare function checkRead(path: string, roots: ContainmentRoots): string;
+/** @throws {import('../contract/errors.js').PathEscapeError} */
+export declare function checkWrite(path: string, roots: ContainmentRoots): string;
+/** A bare, unquoted, absolute-looking token or NAME=/abs/path assignment inside a shell command line. */
+export declare const ABS_PATH_TOKEN: RegExp;
+/**
+ * Allowed non-workspace read targets (special pseudo-devices).
+ * Kept strictly to the standard dev sinks/sources documented in gate policy:
+ * /dev/null, /dev/stdin, /dev/stdout, /dev/stderr.
+ * All other paths outside workspace/read_roots are denied.
+ */
+export declare const ALLOWED_DEV_READS: Set<string>;
+export declare function getCanonicalHome(): string;
+/**
+ * Normalises a path token before containment:
+ * - a leading `~/` or bare `~` is expanded to the real home directory;
+ * - a glob (`*`, `?`, `[`) is cut back to its literal directory prefix
+ *   (`src/*.ts` → `src`, `*.ts` → `.`, `dist/**​/x` → `dist`), because a shell
+ *   glob can only ever expand inside the directory named before the first
+ *   glob character — containing that directory contains every match.
+ * Anything else (`$VAR`, backticks, a non-leading `~`) is left as is for
+ * {@link hasUnexpandedChars} to reject.
+ */
+export declare function expandLeadingTilde(token: string): string;
+/**
+ * True when a token still carries a shell expansion the gate cannot resolve:
+ * `$VAR`/`$HOME`/`$(…)`, backticks, or a `~` that is not the leading one
+ * (checked after {@link expandLeadingTilde}). Globs are not listed — they are
+ * cut back to their literal directory by `expandLeadingTilde` instead.
+ */
+export declare function hasUnexpandedChars(token: string): boolean;
+/**
+ * Tests whether a token looks like a path argument:
+ * - absolute (starts with / or isAbsolute)
+ * - starts with ~/ or is ~
+ * - starts with ./ or ../
+ * - contains /
+ * - matches an existing file relative to the workspace
+ */
+export declare function isPathLike(token: string, workspace?: string): boolean;
+export declare const MUTATION_COMMANDS: Set<string>;
+export declare const READ_UTILITIES: Set<string>;
+/**
+ * Extract target write paths for mutating commands.
+ * Includes rm, mv, cp, touch, mkdir, sed -i, sort -o, tee, git archive/clone/init/worktree,
+ * install, ln, truncate, dd of=, tar -C/-f, unzip -d, rsync, javac -d.
+ * Recurses into bash -c / sh -c.
+ */
+export declare function commandMutationWritePaths(commandLine: string, cwd?: string | null): string[];
+export interface CommandContainmentAnalysis {
+    writePaths: string[];
+    readPaths: string[];
+    unexpandedPath: string | null;
+    candidatePaths: string[];
+}
+/**
+ * Full structural extraction of paths from a command line.
+ * Extracts mutation targets, redirection targets, and read targets.
+ * Detects unexpanded shell expansions and collects candidate paths for credential checks.
+ */
+export declare function extractCommandContainment(commandLine: string, workspace: string): CommandContainmentAnalysis;
+export declare function pathsFromToolCall(toolName: string, args: Record<string, unknown>): {
+    read: string[];
+    write: string[];
+};
+export declare function assignmentReadPaths(commandLine: string): string[];
+/** Non-throwing containment probe over both root sets. */
+export declare function isContainedForKind(path: string, roots: ContainmentRoots, kind: 'read' | 'write'): boolean;
+/**
+ * I6: `{workspace}/.agents/**` holds the
+ * gate's own `hooks.json`, so it is write-protected even though it sits
+ * *inside* the workspace and would otherwise pass ordinary containment.
+ */
+export declare function isAgentsPath(path: string, workspace: string): boolean;
+export declare function redirectionTargets(commandLine: string, workspace: string): string[];
+export declare function escapingRedirectTarget(commandLine: string, workspace: string): string | null;
+/**
+ * Ceiling write_roots sanity.
+ * If an effective write root is /, the home directory, contains ~/.agy-worker,
+ * or contains the gate binary, refuse with ValidationError.
+ */
+export declare function validateWriteRoots(writeRoots: string[], gatePath?: string): void;
+//# sourceMappingURL=containment.d.ts.map

package/dist/policy/containment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"containment.d.ts","sourceRoot":"","sources":["../../src/policy/containment.ts"],"names":[],"mappings":"AAQA;;;;;;GAMG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,KAAK,EAAE,MAAM,EAAE,CAAA;CAChB;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,gBAAgB,CAIpF;AAED,gEAAgE;AAChE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAEvE;AAED,gEAAgE;AAChE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,MAAM,CAExE;AAED,yGAAyG;AACzG,eAAO,MAAM,cAAc,QAAyD,CAAA;AAEpF;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,aAK5B,CAAA;AAEF,wBAAgB,gBAAgB,IAAI,MAAM,CAMzC;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAYxD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAerE;AAED,eAAO,MAAM,iBAAiB,aAW5B,CAAA;AAEF,eAAO,MAAM,cAAc,aAuBzB,CAAA;AA4QF;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,EAAE,CAsF5F;AA4PD,MAAM,WAAW,0BAA0B;IACzC,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,cAAc,EAAE,MAAM,EAAE,CAAA;CACzB;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,0BAA0B,CA2H5G;AAED,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAoCrC;AAKD,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAqBjE;AAED,0DAA0D;AAC1D,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,gBAAgB,EACvB,IAAI,EAAE,MAAM,GAAG,OAAO,GACrB,OAAO,CAET;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAGrE;AASD,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CA0BnF;AAED,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQ5F;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAqChF"}