@bolt-foundry/gambit-core 0.8.3 → 0.8.5-rc.4

package/esm/src/permissions.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Deno-native permission kinds supported by Gambit's permission contract.
+ */
+export declare const PERMISSION_KINDS: readonly ["read", "write", "run", "net", "env"];
+export type PermissionKind = (typeof PERMISSION_KINDS)[number];
+export type PathPermissionInput = boolean | Array<string>;
+export type RunPermissionInput = boolean | Array<string> | {
+    paths?: Array<string>;
+    commands?: Array<string>;
+};
+export type PermissionDeclarationInput = Partial<{
+    read: PathPermissionInput;
+    write: PathPermissionInput;
+    run: RunPermissionInput;
+    net: PathPermissionInput;
+    env: PathPermissionInput;
+}>;
+export type SerializedRunPermission = false | true | {
+    paths: Array<string>;
+    commands: Array<string>;
+};
+export type SerializedPermissionSet = {
+    read: false | true | Array<string>;
+    write: false | true | Array<string>;
+    run: SerializedRunPermission;
+    net: false | true | Array<string>;
+    env: false | true | Array<string>;
+};
+export type PermissionDeclaration = SerializedPermissionSet;
+type NormalizedScope = {
+    all: boolean;
+    values: Set<string>;
+};
+type NormalizedRunScope = {
+    all: boolean;
+    paths: Set<string>;
+    commands: Set<string>;
+};
+export type NormalizedPermissionSet = {
+    baseDir: string;
+    read: NormalizedScope;
+    write: NormalizedScope;
+    run: NormalizedRunScope;
+    net: NormalizedScope;
+    env: NormalizedScope;
+};
+export type PermissionLayerName = "parent" | "workspace" | "declaration" | "reference" | "session" | "host";
+export type PermissionLayerTrace = {
+    name: PermissionLayerName;
+    baseDir: string;
+    requested: SerializedPermissionSet;
+    effective: SerializedPermissionSet;
+};
+export type PermissionTrace = {
+    baseDir: string;
+    effective: SerializedPermissionSet;
+    layers: Array<PermissionLayerTrace>;
+};
+export declare function cloneNormalizedPermissions(input: NormalizedPermissionSet): NormalizedPermissionSet;
+/**
+ * Returns an allow-all permission set anchored to `baseDir`.
+ */
+export declare function allowAllPermissions(baseDir: string): NormalizedPermissionSet;
+/**
+ * Normalizes a permission declaration to a serializable, deterministic shape.
+ *
+ * Relative path grants are resolved against `baseDir`.
+ */
+export declare function normalizePermissionDeclaration(input: PermissionDeclarationInput | undefined, baseDir: string): PermissionDeclaration | undefined;
+/**
+ * Normalizes a declaration to the internal set form used during intersection.
+ */
+export declare function normalizePermissionDeclarationToSet(input: PermissionDeclarationInput | undefined, baseDir: string): NormalizedPermissionSet | undefined;
+/**
+ * Serializes an internal normalized permission set for traces/persistence.
+ */
+export declare function serializePermissions(set: NormalizedPermissionSet): SerializedPermissionSet;
+/**
+ * Computes the monotonic intersection between two permission sets.
+ *
+ * `baseDir` controls how relative checks (`canReadPath`/etc) are evaluated for
+ * the returned set.
+ */
+export declare function intersectPermissions(parent: NormalizedPermissionSet, next: NormalizedPermissionSet, baseDir: string): NormalizedPermissionSet;
+/**
+ * Resolves effective permissions and emits a layer-by-layer permission trace.
+ *
+ * Layer precedence:
+ * 1. `parent` (or host allow-all for roots)
+ * 2. `workspace` (root only)
+ * 3. `declaration` (deck/card declaration)
+ * 4. `reference` (parent reference override)
+ * 5. `session` (root only)
+ */
+export declare function resolveEffectivePermissions(args: {
+    baseDir: string;
+    parent?: NormalizedPermissionSet;
+    workspace?: {
+        baseDir: string;
+        permissions: PermissionDeclarationInput;
+    };
+    declaration?: {
+        baseDir: string;
+        permissions: PermissionDeclarationInput;
+    };
+    reference?: {
+        baseDir: string;
+        permissions: PermissionDeclarationInput;
+    };
+    session?: {
+        baseDir: string;
+        permissions: PermissionDeclarationInput;
+    };
+}): {
+    effective: NormalizedPermissionSet;
+    trace: PermissionTrace;
+};
+/**
+ * Returns whether `targetPath` is readable under `set`.
+ *
+ * Relative paths are resolved against `set.baseDir`.
+ */
+export declare function canReadPath(set: NormalizedPermissionSet, targetPath: string): boolean;
+/**
+ * Returns whether `targetPath` is writable under `set`.
+ *
+ * Relative paths are resolved against `set.baseDir`.
+ */
+export declare function canWritePath(set: NormalizedPermissionSet, targetPath: string): boolean;
+/**
+ * Returns whether `targetPath` is executable via run-path grants.
+ *
+ * Relative paths are resolved against `set.baseDir`.
+ */
+export declare function canRunPath(set: NormalizedPermissionSet, targetPath: string): boolean;
+/**
+ * Returns whether `commandName` is executable via run-command grants.
+ *
+ * This check intentionally does not apply basename/path fallback semantics.
+ */
+export declare function canRunCommand(set: NormalizedPermissionSet, commandName: string): boolean;
+export {};
+//# sourceMappingURL=permissions.d.ts.map

package/esm/src/permissions.d.ts.map

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

package/esm/src/permissions.js

@@ -0,0 +1,406 @@
+import * as dntShim from "../_dnt.shims.js";
+import * as path from "../deps/jsr.io/@std/path/1.1.4/mod.js";
+/**
+ * Deno-native permission kinds supported by Gambit's permission contract.
+ */
+export const PERMISSION_KINDS = ["read", "write", "run", "net", "env"];
+const DENY_SCOPE = { all: false, values: new Set() };
+const DENY_RUN_SCOPE = {
+    all: false,
+    paths: new Set(),
+    commands: new Set(),
+};
+function cloneScope(scope) {
+    return {
+        all: scope.all,
+        values: new Set(scope.values),
+    };
+}
+function cloneRunScope(scope) {
+    return {
+        all: scope.all,
+        paths: new Set(scope.paths),
+        commands: new Set(scope.commands),
+    };
+}
+export function cloneNormalizedPermissions(input) {
+    return {
+        baseDir: input.baseDir,
+        read: cloneScope(input.read),
+        write: cloneScope(input.write),
+        run: cloneRunScope(input.run),
+        net: cloneScope(input.net),
+        env: cloneScope(input.env),
+    };
+}
+function normalizeList(input, kind, baseDir, opts) {
+    if (input === true)
+        return { all: true, values: new Set() };
+    if (input === false || input === undefined || input === null) {
+        return cloneScope(DENY_SCOPE);
+    }
+    if (!Array.isArray(input)) {
+        throw new Error(`permissions.${kind} must be boolean or array`);
+    }
+    const values = new Set();
+    for (const entry of input) {
+        if (typeof entry !== "string") {
+            throw new Error(`permissions.${kind} entries must be strings`);
+        }
+        const trimmed = entry.trim();
+        if (!trimmed)
+            continue;
+        const normalized = opts?.resolvePaths
+            ? path.resolve(baseDir, trimmed)
+            : trimmed;
+        values.add(normalized);
+    }
+    return { all: false, values };
+}
+function normalizeRun(input, baseDir) {
+    if (input === true) {
+        return {
+            all: true,
+            paths: new Set(),
+            commands: new Set(),
+        };
+    }
+    if (input === false || input === undefined || input === null) {
+        return cloneRunScope(DENY_RUN_SCOPE);
+    }
+    if (Array.isArray(input)) {
+        const commands = new Set();
+        for (const entry of input) {
+            if (typeof entry !== "string") {
+                throw new Error("permissions.run entries must be strings");
+            }
+            const trimmed = entry.trim();
+            if (!trimmed)
+                continue;
+            commands.add(trimmed);
+        }
+        return { all: false, paths: new Set(), commands };
+    }
+    if (typeof input !== "object") {
+        throw new Error("permissions.run must be boolean, array, or object");
+    }
+    const record = input;
+    if (typeof record.paths === "boolean") {
+        throw new Error("permissions.run.paths must be an array in object form; use permissions.run=true for full run access");
+    }
+    if (typeof record.commands === "boolean") {
+        throw new Error("permissions.run.commands must be an array in object form; use permissions.run=true for full run access");
+    }
+    const pathsScope = normalizeList(record.paths, "run", baseDir, {
+        resolvePaths: true,
+    });
+    const commandsScope = normalizeList(record.commands, "run", baseDir, {
+        resolvePaths: false,
+    });
+    return {
+        all: false,
+        paths: pathsScope.values,
+        commands: commandsScope.values,
+    };
+}
+function intersectScope(a, b) {
+    if (a.all)
+        return cloneScope(b);
+    if (b.all)
+        return cloneScope(a);
+    const values = new Set();
+    for (const value of a.values) {
+        if (b.values.has(value))
+            values.add(value);
+    }
+    return { all: false, values };
+}
+function intersectRun(a, b) {
+    if (a.all)
+        return cloneRunScope(b);
+    if (b.all)
+        return cloneRunScope(a);
+    const paths = new Set();
+    for (const value of a.paths) {
+        if (b.paths.has(value))
+            paths.add(value);
+    }
+    const commands = new Set();
+    for (const value of a.commands) {
+        if (b.commands.has(value))
+            commands.add(value);
+    }
+    return {
+        all: false,
+        paths,
+        commands,
+    };
+}
+/**
+ * Returns an allow-all permission set anchored to `baseDir`.
+ */
+export function allowAllPermissions(baseDir) {
+    return {
+        baseDir,
+        read: { all: true, values: new Set() },
+        write: { all: true, values: new Set() },
+        run: { all: true, paths: new Set(), commands: new Set() },
+        net: { all: true, values: new Set() },
+        env: { all: true, values: new Set() },
+    };
+}
+function normalizePermissionSet(input, baseDir) {
+    return {
+        baseDir,
+        read: normalizeList(input.read, "read", baseDir, { resolvePaths: true }),
+        write: normalizeList(input.write, "write", baseDir, {
+            resolvePaths: true,
+        }),
+        run: normalizeRun(input.run, baseDir),
+        net: normalizeList(input.net, "net", baseDir),
+        env: normalizeList(input.env, "env", baseDir),
+    };
+}
+/**
+ * Normalizes a permission declaration to a serializable, deterministic shape.
+ *
+ * Relative path grants are resolved against `baseDir`.
+ */
+export function normalizePermissionDeclaration(input, baseDir) {
+    if (!input)
+        return undefined;
+    return serializePermissions(normalizePermissionSet(input, baseDir));
+}
+/**
+ * Normalizes a declaration to the internal set form used during intersection.
+ */
+export function normalizePermissionDeclarationToSet(input, baseDir) {
+    if (!input)
+        return undefined;
+    return normalizePermissionSet(input, baseDir);
+}
+/**
+ * Serializes an internal normalized permission set for traces/persistence.
+ */
+export function serializePermissions(set) {
+    const serializeScope = (scope) => {
+        if (scope.all)
+            return true;
+        if (scope.values.size === 0)
+            return false;
+        return Array.from(scope.values).sort();
+    };
+    const serializeRunScope = (scope) => {
+        if (scope.all)
+            return true;
+        if (scope.paths.size === 0 && scope.commands.size === 0) {
+            return false;
+        }
+        return {
+            paths: Array.from(scope.paths).sort(),
+            commands: Array.from(scope.commands).sort(),
+        };
+    };
+    return {
+        read: serializeScope(set.read),
+        write: serializeScope(set.write),
+        run: serializeRunScope(set.run),
+        net: serializeScope(set.net),
+        env: serializeScope(set.env),
+    };
+}
+/**
+ * Computes the monotonic intersection between two permission sets.
+ *
+ * `baseDir` controls how relative checks (`canReadPath`/etc) are evaluated for
+ * the returned set.
+ */
+export function intersectPermissions(parent, next, baseDir) {
+    return {
+        baseDir,
+        read: intersectScope(parent.read, next.read),
+        write: intersectScope(parent.write, next.write),
+        run: intersectRun(parent.run, next.run),
+        net: intersectScope(parent.net, next.net),
+        env: intersectScope(parent.env, next.env),
+    };
+}
+/**
+ * Resolves effective permissions and emits a layer-by-layer permission trace.
+ *
+ * Layer precedence:
+ * 1. `parent` (or host allow-all for roots)
+ * 2. `workspace` (root only)
+ * 3. `declaration` (deck/card declaration)
+ * 4. `reference` (parent reference override)
+ * 5. `session` (root only)
+ */
+export function resolveEffectivePermissions(args) {
+    const layers = [];
+    let effective = args.parent
+        ? {
+            ...cloneNormalizedPermissions(args.parent),
+            // Rebase relative-path checks to the current invocation scope.
+            baseDir: args.baseDir,
+        }
+        : allowAllPermissions(args.baseDir);
+    if (args.parent) {
+        layers.push({
+            name: "parent",
+            baseDir: args.parent.baseDir,
+            requested: serializePermissions(args.parent),
+            effective: serializePermissions(effective),
+        });
+    }
+    else {
+        layers.push({
+            name: "host",
+            baseDir: args.baseDir,
+            requested: serializePermissions(effective),
+            effective: serializePermissions(effective),
+        });
+    }
+    const applyLayer = (name, input) => {
+        if (!input)
+            return;
+        const requested = normalizePermissionSet(input.permissions, input.baseDir);
+        effective = intersectPermissions(effective, requested, args.baseDir);
+        layers.push({
+            name,
+            baseDir: input.baseDir,
+            requested: serializePermissions(requested),
+            effective: serializePermissions(effective),
+        });
+    };
+    if (!args.parent) {
+        applyLayer("workspace", args.workspace);
+    }
+    applyLayer("declaration", args.declaration);
+    applyLayer("reference", args.reference);
+    if (!args.parent) {
+        applyLayer("session", args.session);
+    }
+    return {
+        effective,
+        trace: {
+            baseDir: args.baseDir,
+            effective: serializePermissions(effective),
+            layers,
+        },
+    };
+}
+/**
+ * Checks whether `target` is covered by `scope`, treating each value as either
+ * an exact path grant or the root of an allowed directory tree.
+ */
+function matchScope(scope, target) {
+    if (scope.all)
+        return true;
+    const canonicalTarget = canonicalizePath(target);
+    if (!canonicalTarget)
+        return false;
+    for (const root of scope.values) {
+        const canonicalRoot = canonicalizePath(root);
+        if (!canonicalRoot)
+            continue;
+        if (pathWithinRoot(canonicalRoot, canonicalTarget))
+            return true;
+    }
+    return false;
+}
+function pathWithinRoot(root, target) {
+    if (root === target)
+        return true;
+    const rel = path.relative(root, target);
+    return rel.length > 0 && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+function canonicalizePath(target) {
+    const resolved = path.resolve(target);
+    try {
+        return path.resolve(dntShim.Deno.realPathSync(resolved));
+    }
+    catch (err) {
+        if (err instanceof dntShim.Deno.errors.NotFound) {
+            return canonicalizeMissingPath(resolved);
+        }
+        return undefined;
+    }
+}
+function canonicalizeMissingPath(target) {
+    const suffix = [];
+    let probe = target;
+    while (true) {
+        try {
+            const canonicalBase = path.resolve(dntShim.Deno.realPathSync(probe));
+            if (suffix.length === 0)
+                return canonicalBase;
+            return path.resolve(canonicalBase, ...suffix.reverse());
+        }
+        catch (err) {
+            if (err instanceof dntShim.Deno.errors.NotFound) {
+                const parent = path.dirname(probe);
+                if (parent === probe)
+                    return undefined;
+                suffix.push(path.basename(probe));
+                probe = parent;
+                continue;
+            }
+            return undefined;
+        }
+    }
+}
+/**
+ * Returns whether `targetPath` is readable under `set`.
+ *
+ * Relative paths are resolved against `set.baseDir`.
+ */
+export function canReadPath(set, targetPath) {
+    return matchScope(set.read, path.resolve(set.baseDir, targetPath));
+}
+/**
+ * Returns whether `targetPath` is writable under `set`.
+ *
+ * Relative paths are resolved against `set.baseDir`.
+ */
+export function canWritePath(set, targetPath) {
+    return matchScope(set.write, path.resolve(set.baseDir, targetPath));
+}
+/**
+ * Returns whether `targetPath` is executable via run-path grants.
+ *
+ * Relative paths are resolved against `set.baseDir`.
+ */
+export function canRunPath(set, targetPath) {
+    if (set.run.all)
+        return true;
+    const resolvedTarget = path.resolve(set.baseDir, targetPath);
+    const canonicalTarget = canonicalizePath(resolvedTarget);
+    if (!canonicalTarget)
+        return false;
+    // Run-path grants are exact binary grants; deny symlink-mediated execution.
+    if (canonicalTarget !== resolvedTarget)
+        return false;
+    for (const allowedPath of set.run.paths) {
+        const resolvedAllowed = path.resolve(set.baseDir, allowedPath);
+        if (resolvedAllowed !== resolvedTarget)
+            continue;
+        const canonicalAllowed = canonicalizePath(resolvedAllowed);
+        if (!canonicalAllowed)
+            continue;
+        if (canonicalAllowed !== resolvedAllowed)
+            continue;
+        if (canonicalAllowed === canonicalTarget)
+            return true;
+    }
+    return false;
+}
+/**
+ * Returns whether `commandName` is executable via run-command grants.
+ *
+ * This check intentionally does not apply basename/path fallback semantics.
+ */
+export function canRunCommand(set, commandName) {
+    if (set.run.all)
+        return true;
+    return set.run.commands.has(commandName);
+}

package/esm/src/runtime.d.ts

@@ -1,5 +1,6 @@
 import type { Guardrails, ModelProvider } from "./types.js";
 import type { SavedState } from "./state.js";
+import type { NormalizedPermissionSet, PermissionDeclarationInput } from "./permissions.js";
 export type GambitEndSignal = {
     __gambitEnd: true;
     payload?: unknown;
@@ -9,7 +10,7 @@ export type GambitEndSignal = {
     meta?: Record<string, unknown>;
 };
 export declare function isGambitEndSignal(value: unknown): value is GambitEndSignal;
-type RunOptions = {
+export type RunOptions = {
     path: string;
     input: unknown;
     inputProvided?: boolean;
@@ -30,7 +31,31 @@ type RunOptions = {
     onStreamText?: (chunk: string) => void;
     allowRootStringInput?: boolean;
     responsesMode?: boolean;
+    workspacePermissions?: PermissionDeclarationInput;
+    workspacePermissionsBaseDir?: string;
+    sessionPermissions?: PermissionDeclarationInput;
+    sessionPermissionsBaseDir?: string;
+    parentPermissions?: NormalizedPermissionSet;
+    referencePermissions?: PermissionDeclarationInput;
+    referencePermissionsBaseDir?: string;
+    runDeadlineMs?: number;
+    workerSandbox?: boolean;
+    inOrchestrationWorker?: boolean;
+    signal?: AbortSignal;
+    onCancel?: () => unknown | Promise<unknown>;
+    onTool?: (input: {
+        name: string;
+        args: Record<string, unknown>;
+        runId: string;
+        actionCallId: string;
+        parentActionCallId?: string;
+        deckPath: string;
+    }) => unknown | Promise<unknown>;
 };
+export declare class RunCanceledError extends Error {
+    code: string;
+    constructor(message?: string);
+}
+export declare function isRunCanceledError(err: unknown): boolean;
 export declare function runDeck(opts: RunOptions): Promise<unknown>;
-export {};
 //# sourceMappingURL=runtime.d.ts.map

package/esm/src/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/src/runtime.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAEV,UAAU,EAIV,aAAa,EAKd,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAc,UAAU,EAAE,MAAM,YAAY,CAAC;AAEzD,MAAM,MAAM,eAAe,GAAG;IAC5B,WAAW,EAAE,IAAI,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAM1E;AAiBD,KAAK,UAAU,GAAG;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,aAAa,EAAE,aAAa,CAAC;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,YAAY,EAAE,UAAU,KAAK,IAAI,CAAC;IACzD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IAC5C,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,wBAAsB,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAkGhE"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/src/runtime.ts"],"names":[],"mappings":"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"}