@oscharko-dev/keiko-tools 0.2.0

package/dist/registry.js

@@ -0,0 +1,240 @@
+// The tool host: WorkspaceToolHost implements the harness ToolPort. It narrows untrusted
+// `Record<string,unknown>` arguments, dispatches the 6 tools through a handler map, and returns
+// a ToolCallResult whose `output` is already redacted. run_command is the only tool that sets
+// commandExecuted:true (the executor counts those against maxCommandExecutions). All filesystem
+// reads go through the workspace layer; all writes through the WorkspaceWriter; all spawns through
+// the injected SpawnFn — so a unit test needs no real secrets and no real processes.
+import { discoverWithStats, readWorkspaceFile, } from "@oscharko-dev/keiko-workspace";
+import { nodeWorkspaceFs } from "@oscharko-dev/keiko-workspace/internal/fs";
+import { nodeSpawnFn, runCommand } from "./exec.js";
+import { CommandCancelledError, ToolArgumentError, UnknownToolError } from "./errors.js";
+import { applyPatch, renderDryRun, validatePatch } from "./patch.js";
+import { TOOL_DEFINITIONS } from "./schemas.js";
+import { nodeWorkspaceWriter } from "./writer.js";
+import { resolveToolHostConfig, } from "./types.js";
+function requireString(args, key, tool) {
+    const value = args[key];
+    if (typeof value !== "string" || value.length === 0) {
+        throw new ToolArgumentError(`argument '${key}' must be a non-empty string`, tool);
+    }
+    return value;
+}
+function optionalString(args, key, tool) {
+    const value = args[key];
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "string") {
+        throw new ToolArgumentError(`argument '${key}' must be a string`, tool);
+    }
+    return value;
+}
+function optionalNumber(args, key, tool) {
+    const value = args[key];
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        throw new ToolArgumentError(`argument '${key}' must be a non-negative number`, tool);
+    }
+    return value;
+}
+function optionalBoolean(args, key, tool) {
+    const value = args[key];
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "boolean") {
+        throw new ToolArgumentError(`argument '${key}' must be a boolean`, tool);
+    }
+    return value;
+}
+function optionalStringArray(args, key, tool) {
+    const value = args[key];
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+        throw new ToolArgumentError(`argument '${key}' must be a string array`, tool);
+    }
+    return value;
+}
+function summarizeCommand(result) {
+    return JSON.stringify({
+        exitCode: result.exitCode,
+        signal: result.signal,
+        timedOut: result.timedOut,
+        truncated: result.truncated,
+        stdout: result.stdout,
+        stderr: result.stderr,
+    });
+}
+export class WorkspaceToolHost {
+    workspace;
+    fs;
+    writer;
+    spawn;
+    resolveExecutable;
+    config;
+    processEnv;
+    now;
+    constructor(deps) {
+        this.workspace = deps.workspace;
+        this.fs = deps.fs ?? nodeWorkspaceFs;
+        this.writer = deps.writer ?? nodeWorkspaceWriter;
+        this.spawn = deps.spawn ?? nodeSpawnFn;
+        this.resolveExecutable = deps.resolveExecutable;
+        this.config = resolveToolHostConfig(deps.config);
+        this.processEnv = deps.processEnv ?? process.env;
+        this.now = deps.now ?? Date.now;
+    }
+    listTools() {
+        return TOOL_DEFINITIONS;
+    }
+    async execute(request) {
+        if (request.signal.aborted) {
+            throw new CommandCancelledError("tool call cancelled before dispatch");
+        }
+        const startedAt = this.now();
+        const handled = await this.dispatch(request);
+        return {
+            toolCallId: request.toolCallId,
+            output: handled.output,
+            durationMs: this.now() - startedAt,
+            commandExecuted: handled.commandExecuted,
+            ...(handled.metadata === undefined ? {} : { metadata: handled.metadata }),
+        };
+    }
+    dispatch(request) {
+        const args = request.arguments;
+        switch (request.toolName) {
+            case "read_file":
+                return Promise.resolve(this.readFile(args));
+            case "list_files":
+                return Promise.resolve(this.listFiles(args));
+            case "inspect_package_scripts":
+                return Promise.resolve(this.inspectScripts(args));
+            case "run_command":
+                return this.runCommandTool(args, request.signal);
+            case "propose_patch":
+                return Promise.resolve(this.proposePatch(args));
+            case "apply_patch":
+                return Promise.resolve(this.applyPatchTool(args, request.signal));
+            default:
+                throw new UnknownToolError(`no such tool: ${request.toolName}`, request.toolName);
+        }
+    }
+    readFile(args) {
+        const path = requireString(args, "path", "read_file");
+        const maxBytes = optionalNumber(args, "maxBytes", "read_file") ?? this.config.maxReadBytes;
+        const content = readWorkspaceFile(this.workspace, path, { maxBytes }, this.fs);
+        return { output: JSON.stringify(content), commandExecuted: false };
+    }
+    listFiles(args) {
+        const maxDepth = optionalNumber(args, "maxDepth", "list_files");
+        const maxFiles = optionalNumber(args, "maxFiles", "list_files");
+        const applyGitignore = optionalBoolean(args, "applyGitignore", "list_files");
+        const result = discoverWithStats(this.workspace, {
+            maxDepth: maxDepth ?? 12,
+            maxFiles: maxFiles ?? 5_000,
+            applyGitignore: applyGitignore ?? true,
+        }, this.fs);
+        return { output: JSON.stringify(result), commandExecuted: false };
+    }
+    inspectScripts(args) {
+        const path = optionalString(args, "path", "inspect_package_scripts") ?? "package.json";
+        const content = readWorkspaceFile(this.workspace, path, { maxBytes: this.config.maxReadBytes }, this.fs);
+        const scripts = parseScripts(content.text, path);
+        return { output: JSON.stringify({ path, scripts }), commandExecuted: false };
+    }
+    async runCommandTool(args, signal) {
+        const command = requireString(args, "command", "run_command");
+        const cmdArgs = optionalStringArray(args, "args", "run_command") ?? [];
+        const cwd = optionalString(args, "cwd", "run_command");
+        const timeoutMs = optionalNumber(args, "timeoutMs", "run_command");
+        const result = await runCommand({ command, args: cmdArgs, cwd, timeoutMs, signal }, {
+            workspace: this.workspace,
+            policy: this.config.sandbox,
+            commandRules: this.config.commandRules,
+            spawn: this.spawn,
+            resolveExecutable: this.resolveExecutable,
+            processEnv: this.processEnv,
+            now: this.now,
+        });
+        return {
+            output: summarizeCommand(result),
+            commandExecuted: true,
+            metadata: {
+                kind: "command",
+                executable: command,
+                argCount: cmdArgs.length,
+                exitCode: result.exitCode,
+                timedOut: result.timedOut,
+                sandbox: {
+                    envAllowlist: this.config.sandbox.envAllowlist,
+                    network: this.config.sandbox.network,
+                    maxOutputBytes: this.config.sandbox.maxOutputBytes,
+                    timeoutMs: timeoutMs ?? this.config.sandbox.defaultTimeoutMs,
+                    terminationGraceMs: this.config.sandbox.terminationGraceMs,
+                    cwdRequested: cwd !== undefined,
+                    filesystem: this.config.sandbox.filesystem,
+                    // ADR-0043: record how (and whether) egress was enforced for a network:"none" run.
+                    ...(result.attestation === undefined
+                        ? {}
+                        : {
+                            networkEnforced: result.attestation.networkEnforced,
+                            filesystemEnforced: result.attestation.filesystemEnforced,
+                            backend: result.attestation.backend,
+                        }),
+                },
+            },
+        };
+    }
+    proposePatch(args) {
+        const diff = requireString(args, "diff", "propose_patch");
+        const validation = validatePatch(this.workspace, diff, {
+            fs: this.fs,
+            limits: this.config.patchLimits,
+        });
+        return {
+            output: JSON.stringify({ validation, preview: renderDryRun(validation) }),
+            commandExecuted: false,
+        };
+    }
+    applyPatchTool(args, signal) {
+        const diff = requireString(args, "diff", "apply_patch");
+        const result = applyPatch(this.workspace, diff, {
+            applyEnabled: this.config.applyEnabled,
+            signal,
+            fs: this.fs,
+            writer: this.writer,
+            limits: this.config.patchLimits,
+        });
+        return {
+            output: JSON.stringify(result),
+            commandExecuted: false,
+            metadata: {
+                kind: "patch-apply",
+                changedFiles: result.changedFiles.length,
+                created: result.created.length,
+                deleted: result.deleted.length,
+            },
+        };
+    }
+}
+function parseScripts(text, path) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new ToolArgumentError(`${path} is not valid JSON`, "inspect_package_scripts");
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+        return {};
+    }
+    const scripts = parsed.scripts;
+    return typeof scripts === "object" && scripts !== null
+        ? scripts
+        : {};
+}

package/dist/sandbox.d.ts

@@ -0,0 +1,9 @@
+import type { CommandRule } from "./types.js";
+export declare function buildSandboxEnv(processEnv: NodeJS.ProcessEnv, allowlist: readonly string[]): Record<string, string>;
+export declare function collectSensitiveEnvValues(processEnv: NodeJS.ProcessEnv, allowlist: readonly string[]): readonly string[];
+export interface CommandDecision {
+    readonly allowed: boolean;
+    readonly reason?: string | undefined;
+}
+export declare function isCommandAllowed(rules: readonly CommandRule[], executable: string, args: readonly string[]): CommandDecision;
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAI9C,wBAAgB,eAAe,CAC7B,UAAU,EAAE,MAAM,CAAC,UAAU,EAC7B,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASxB;AAMD,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,MAAM,CAAC,UAAU,EAC7B,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,SAAS,MAAM,EAAE,CAYnB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAqGD,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,eAAe,CAajB"}

package/dist/sandbox.js

@@ -0,0 +1,131 @@
+// PURE sandbox logic: the trust boundary's decision functions. No filesystem, no spawn, no
+// node:child_process imports — every effect lives in exec.ts/writer.ts. These functions are
+// individually unit-testable so the security invariants (env isolation, deny-by-default) are
+// pinned down. Only node:path (a pure string utility) is imported here.
+import { basename } from "node:path";
+// Builds the child env by copying ONLY allowlisted names that are present in the parent.
+// NEVER spreads `...processEnv`, so no credential-bearing variable can leak into the child.
+export function buildSandboxEnv(processEnv, allowlist) {
+    const env = {};
+    for (const name of allowlist) {
+        const value = processEnv[name];
+        if (value !== undefined) {
+            env[name] = value;
+        }
+    }
+    return env;
+}
+// Collects the values of every parent env var that is NOT on the allowlist, so the command's
+// captured stdout/stderr can be scrubbed of any secret a child still managed to print (e.g. a
+// tool that reads a token from its own config and echoes it). Empty/short values are skipped to
+// avoid over-redaction. The allowlisted, non-secret values (PATH, HOME, …) are deliberately kept.
+export function collectSensitiveEnvValues(processEnv, allowlist) {
+    const allowed = new Set(allowlist);
+    const values = [];
+    for (const [name, value] of Object.entries(processEnv)) {
+        if (allowed.has(name)) {
+            continue;
+        }
+        if (value !== undefined && value.length >= 6) {
+            values.push(value);
+        }
+    }
+    return values;
+}
+function hasPathSeparator(value) {
+    return value.includes("/") || value.includes("\\");
+}
+function hasNul(value) {
+    return value.includes("\u0000");
+}
+// Resolves the subcommand: the first non-flag token, skipping leading flags AND the value of any
+// value-taking flag (`--prefix DIR`, `-C DIR`). This is the S-H2 fix — a value can no longer
+// masquerade as the subcommand. `--flag=value` carries its value inline, so only the flag token is
+// consumed. Returns undefined when no subcommand token is present.
+function resolveSubcommand(rule, args) {
+    const valueFlags = new Set(rule.valueFlags ?? []);
+    let skipNext = false;
+    for (const arg of args) {
+        if (skipNext) {
+            skipNext = false; // this token is the value of the preceding value-flag; skip it
+            continue;
+        }
+        if (!arg.startsWith("-")) {
+            return arg;
+        }
+        // A `-f=value` / `--flag=value` token carries its own value; consume just this token.
+        if (!arg.includes("=") && valueFlags.has(arg)) {
+            skipNext = true; // the following token is this flag's value
+        }
+    }
+    return undefined;
+}
+// Denies the whole invocation if any denied flag (e.g. npm/npx `-c`/`--call`) appears anywhere in
+// args, in either `--call x` or `--call=x` form. These execute a transitive shell (S-H2).
+function hasDeniedFlag(rule, args) {
+    const denied = rule.denyFlags;
+    if (denied === undefined) {
+        return false;
+    }
+    return args.some((arg) => {
+        const flag = arg.includes("=") ? arg.slice(0, arg.indexOf("=")) : arg;
+        return denied.includes(flag);
+    });
+}
+function hasRequiredLeadingFlags(rule, args) {
+    const required = rule.requiredLeadingFlags;
+    if (required === undefined || required.length === 0) {
+        return true;
+    }
+    return required.every((flag, index) => args[index] === flag);
+}
+function checkAllowlistMode(rule, allowed, sub) {
+    if (sub === undefined || !allowed.includes(sub)) {
+        return { allowed: false, reason: `subcommand not allowed: ${rule.executable} ${sub ?? ""}` };
+    }
+    return { allowed: true };
+}
+function checkDenylistMode(rule, sub) {
+    // Deny-by-default on the subcommand: when a known-subcommand set is declared, an unrecognized
+    // first non-flag token (e.g. a stray path from a value-flag bypass) is denied.
+    if (rule.knownSubcommands !== undefined &&
+        (sub === undefined || !rule.knownSubcommands.includes(sub))) {
+        return { allowed: false, reason: `unrecognized subcommand: ${rule.executable} ${sub ?? ""}` };
+    }
+    if (rule.deniedSubcommands !== undefined &&
+        sub !== undefined &&
+        rule.deniedSubcommands.includes(sub)) {
+        return { allowed: false, reason: `subcommand denied: ${rule.executable} ${sub}` };
+    }
+    return { allowed: true };
+}
+function checkSubcommand(rule, args) {
+    if (hasDeniedFlag(rule, args)) {
+        return { allowed: false, reason: `denied flag for ${rule.executable}` };
+    }
+    if (!hasRequiredLeadingFlags(rule, args)) {
+        return { allowed: false, reason: `missing required leading flag for ${rule.executable}` };
+    }
+    const sub = resolveSubcommand(rule, args);
+    if (rule.allowedSubcommands !== undefined) {
+        return checkAllowlistMode(rule, rule.allowedSubcommands, sub);
+    }
+    return checkDenylistMode(rule, sub);
+}
+// PURE deny-by-default decision. The executable must be a BARE name (no path separators, no
+// NUL): we match by basename against the rules and reject anything unlisted. This is evaluated
+// BEFORE any spawn, so a denied command never reaches child_process.
+export function isCommandAllowed(rules, executable, args) {
+    if (executable.length === 0 || hasNul(executable)) {
+        return { allowed: false, reason: "empty or NUL-containing executable" };
+    }
+    if (hasPathSeparator(executable)) {
+        return { allowed: false, reason: "executable must be a bare PATH-resolved name" };
+    }
+    const name = basename(executable);
+    const rule = rules.find((candidate) => candidate.executable === name);
+    if (rule === undefined) {
+        return { allowed: false, reason: `executable not allowlisted: ${name}` };
+    }
+    return checkSubcommand(rule, args);
+}

package/dist/schemas.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from "@oscharko-dev/keiko-contracts";
+export declare const TOOL_DEFINITIONS: readonly ToolDefinition[];
+//# sourceMappingURL=schemas.d.ts.map

package/dist/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AASpE,eAAO,MAAM,gBAAgB,EAAE,SAAS,cAAc,EA2DpD,CAAC"}

package/dist/schemas.js

@@ -0,0 +1,51 @@
+// The model-facing tool contract: 6 ToolDefinitions with JSON-Schema `parameters`. Kept apart
+// from registry.ts so the dispatch logic stays small and the schema table is a single frozen
+// surface the gateway/model see. No runtime logic — just the frozen definitions.
+function obj(properties, required) {
+    return { type: "object", properties, required, additionalProperties: false };
+}
+export const TOOL_DEFINITIONS = Object.freeze([
+    {
+        name: "read_file",
+        description: "Read a UTF-8 file inside the workspace. Output is redacted; files above the byte cap are rejected.",
+        parameters: obj({
+            path: { type: "string", description: "Workspace-relative file path." },
+            maxBytes: { type: "number", description: "Optional read cap in bytes." },
+        }, ["path"]),
+    },
+    {
+        name: "list_files",
+        description: "List workspace files (deny-list and optional .gitignore applied).",
+        parameters: obj({
+            maxDepth: { type: "number", description: "Optional recursion depth cap." },
+            maxFiles: { type: "number", description: "Optional result count cap." },
+            applyGitignore: { type: "boolean", description: "Apply the .gitignore subset." },
+        }, []),
+    },
+    {
+        name: "inspect_package_scripts",
+        description: "Return the `scripts` object from a package.json inside the workspace.",
+        parameters: obj({ path: { type: "string", description: "Optional path; defaults to package.json." } }, []),
+    },
+    {
+        name: "run_command",
+        description: "Run an allowlisted read-only command (npm/git by default) with no shell, a clean env, " +
+            "a trusted executable path, a workspace cwd, a timeout, and capped redacted output.",
+        parameters: obj({
+            command: { type: "string", description: "Bare executable name (PATH-resolved)." },
+            args: { type: "array", items: { type: "string" }, description: "Argument vector." },
+            cwd: { type: "string", description: "Optional workspace-relative working directory." },
+            timeoutMs: { type: "number", description: "Optional wall-time budget in ms." },
+        }, ["command"]),
+    },
+    {
+        name: "propose_patch",
+        description: "Validate a unified diff and return a dry-run preview. Never writes to disk.",
+        parameters: obj({ diff: { type: "string", description: "Unified diff text." } }, ["diff"]),
+    },
+    {
+        name: "apply_patch",
+        description: "Apply a validated unified diff atomically. Fail-closed: refuses unless apply is enabled.",
+        parameters: obj({ diff: { type: "string", description: "Unified diff text." } }, ["diff"]),
+    },
+]);

package/dist/terminal-policy.d.ts

@@ -0,0 +1,10 @@
+import type { CommandRule } from "./types.js";
+declare const FROZEN_NONE: readonly string[];
+export declare const TERMINAL_COMMAND_RULES: readonly CommandRule[];
+export interface TerminalCommandDecision {
+    readonly allowed: boolean;
+    readonly reason?: string | undefined;
+}
+export declare function isTerminalCommandAllowed(command: string, args: readonly string[]): TerminalCommandDecision;
+export { FROZEN_NONE as TERMINAL_NO_FLAGS };
+//# sourceMappingURL=terminal-policy.d.ts.map

package/dist/terminal-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal-policy.d.ts","sourceRoot":"","sources":["../src/terminal-policy.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,QAAA,MAAM,WAAW,EAAE,SAAS,MAAM,EAAsB,CAAC;AAIzD,eAAO,MAAM,sBAAsB,EAAE,SAAS,WAAW,EAyEvD,CAAC;AA4DH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAuKD,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,GACtB,uBAAuB,CAkBzB;AAGD,OAAO,EAAE,WAAW,IAAI,iBAAiB,EAAE,CAAC"}