@ashlr/hub 2.2.0 → 3.0.1

package/dist/core/mcp-native-engineer.d.ts

@@ -0,0 +1,123 @@
+/**
+ * M42: Native engineering tool surface — REAL, sandboxed tools for the hub's
+ * local-model agent loop.
+ *
+ * The hub loop (src/core/run/agent-loop.ts) only EXECUTES a tool spec that
+ * carries a callable `fn` (it builds toolExecutors from `spec.fn`). The native
+ * gateway tools from `listNativeTools()` ship NO `fn`, so they were dead in the
+ * loop. This module fixes that two ways:
+ *   1. `buildEngineerToolSpecs(eng)` — NEW read/write/exec tools (read_file,
+ *      glob, grep, write_file, edit_file, bash), each wrapped with a `fn` that
+ *      runs through `callEngineerTool` (the gated pipeline below).
+ *   2. `buildNativeToolSpecsWithFn()` — wraps the existing 11 native tools so
+ *      they are executable in-process via `callNativeTool`.
+ *
+ * SECURITY MODEL — defense in depth, in order of authority:
+ *   1. WORKSPACE BOUNDARY (the primary spine): every path is resolved with
+ *      `resolveInside(root, p)`, which realpath-resolves both the root and the
+ *      target and refuses anything that is not the root itself or a descendant
+ *      of `root + sep`. `workspaceRoot` is an absolute sandbox worktree path —
+ *      NEVER `/` or `~`. A symlink that points outside the root is rejected
+ *      because realpath resolves it before the prefix check.
+ *   2. KILL SWITCH + ENROLLMENT (reused, NOT reinvented): every mutating tool
+ *      calls `assertMayMutate(eng.sourceRepo, { allowAnyRepo: true })`, which
+ *      ALWAYS throws when ~/.ashlr/KILL is present and (unless the test env seam
+ *      ASHLR_TEST_ALLOW_ANY_REPO=1 is set) when the repo is not enrolled.
+ *      `callEngineerTool` also refuses non-read tools when the kill switch is on
+ *      BEFORE loading config or running a handler.
+ *   3. COMMAND DENY-LIST (`assertCommandAllowed`): a best-effort guard against
+ *      egress / destructive shell verbs. This is DEFENSE IN DEPTH only — the
+ *      worktree boundary + kill-switch + minimal env are the real containment.
+ *   4. MINIMAL ENV (`minimalEnv`): `bash` spawns with a hand-built env (PATH +
+ *      a scratch HOME under os.tmpdir() + LANG) merged with ashlr's NON-SECRET
+ *      keys via `withToolEnv`. The full `process.env` (and thus any API keys it
+ *      carries) is NEVER handed to the shell.
+ *
+ * Every tool result is rendered through `renderToolText` (serialize + scrub
+ * secrets + 32KB cap), and every call (ok / refused / error) is audited as
+ * 'mcp:engineer-call'. `callEngineerTool` NEVER throws — failures surface as
+ * error text the model can read.
+ */
+/**
+ * The agent's engineering context: the absolute sandbox worktree it may read /
+ * write / exec within, the source repo used for the kill-switch + enrollment
+ * gate, and the per-session capability flags.
+ *
+ * `workspaceRoot` MUST be an absolute path to a real sandbox worktree directory
+ * — NEVER `/` or `~`. Callers create it (a git worktree / tmp checkout) before
+ * constructing the context.
+ */
+export interface EngineerContext {
+    /** Absolute root the agent may read/write/exec within (a sandbox worktree). */
+    workspaceRoot: string;
+    /** Source repo path used for the assertMayMutate (kill-switch + enrollment) gate. */
+    sourceRepo: string;
+    /** Whether write_file / edit_file are permitted this session. */
+    allowWrite: boolean;
+    /** Whether bash is permitted this session. */
+    allowExec: boolean;
+}
+/** Clamp `n` into [min, max]. NaN/non-finite collapses to `min`. */
+export declare function clamp(n: number, min: number, max: number): number;
+/**
+ * Build the MINIMAL, cross-platform env for a spawned shell. Deliberately does
+ * NOT pass the full process.env — that would leak ANTHROPIC_API_KEY and friends
+ * to the shell. The full process.env (and any API keys it carries) is NEVER
+ * handed to the shell; ashlr's non-secret config keys are layered on by the
+ * caller via withToolEnv.
+ *
+ * Always carried: PATH and a scratch home dir under os.tmpdir().
+ *   - posix: HOME = scratch, LANG = process.env.LANG ?? 'C'.
+ *   - win32: USERPROFILE = scratch, plus the handful of system vars Windows
+ *     tools genuinely NEED to function (SystemRoot/windir/COMSPEC/PATHEXT/…)
+ *     and TEMP/TMP pointed AT the scratch dir. No secrets are passed through.
+ */
+export declare function minimalEnv(): NodeJS.ProcessEnv;
+/**
+ * Refuse a bash command that matches an egress / destructive / privilege verb.
+ *
+ * This is intentionally a coarse, defense-in-depth guard layered ON TOP of the
+ * real containment (workspace boundary + kill-switch + minimal env). It is NOT
+ * meant to be a complete shell parser — a determined adversary can obfuscate
+ * around any deny-list, which is exactly why the boundary + minimal env (no
+ * secrets, scratch HOME, cwd pinned to the worktree) are the load-bearing
+ * controls. Throws with a clear message on a match.
+ *
+ * NOTE: `bash` grants local code execution WITH network access; it must only be
+ * enabled (`--bash` / eng.allowExec) for goals you trust. This deny-list reduces
+ * the blast radius of an obviously-hostile command but is NOT the security
+ * boundary and must never be relied on as one.
+ */
+export declare function assertCommandAllowed(command: string): void;
+/**
+ * Execute an engineer tool through the full safety pipeline. NEVER throws:
+ * unknown tools, capability/kill-switch refusals, and handler failures all
+ * surface as rendered error text. Every outcome is audited. The returned
+ * string is always rendered through `renderToolText` (scrub + 32KB cap).
+ */
+export declare function callEngineerTool(name: string, rawArgs: unknown, eng: EngineerContext): Promise<string>;
+/** A tool spec carrying an executable `fn`, ready for the agent loop. */
+export interface ExecutableToolSpec {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: object;
+    };
+    name: string;
+    fn: (args: unknown) => Promise<string>;
+}
+/**
+ * Build executable specs for the engineer tools, filtered by capability:
+ * read tools always; write tools only when eng.allowWrite; exec tools only when
+ * eng.allowExec. Each spec's `fn` routes through `callEngineerTool` so the full
+ * gated pipeline (boundary + kill-switch + audit + render) always runs.
+ */
+export declare function buildEngineerToolSpecs(eng: EngineerContext): ExecutableToolSpec[];
+/**
+ * Wrap the existing native tools (from listNativeTools) so they are EXECUTABLE
+ * in-process via `callNativeTool`. This fixes the pre-existing dead-tool bug:
+ * the native specs the gateway exposes carry no `fn`, so the agent loop's
+ * toolExecutors map never picked them up.
+ */
+export declare function buildNativeToolSpecsWithFn(): ExecutableToolSpec[];