@themoltnet/pi-extension 0.35.4 → 0.36.0

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { AgentSession } from '@earendil-works/pi-coding-agent';
 import { Api } from '@earendil-works/pi-ai';
 import { BashOperations } from '@earendil-works/pi-coding-agent';
+import { CommandAnalysis } from '@themoltnet/shell-command-analyzer';
 import { connect } from '@themoltnet/sdk';
 import { EditOperations } from '@earendil-works/pi-coding-agent';
 import { ExtensionAPI } from '@earendil-works/pi-coding-agent';
@@ -9,9 +10,11 @@ import { LoadSkillsResult } from '@earendil-works/pi-coding-agent';
 import { Model } from '@earendil-works/pi-ai';
 import { Readable } from 'node:stream';
 import { ReadOperations } from '@earendil-works/pi-coding-agent';
+import { ShellCommandAnalyzer } from '@themoltnet/shell-command-analyzer';
 import { Skill } from '@earendil-works/pi-coding-agent';
 import { Static } from 'typebox';
 import { TObject } from 'typebox';
+import { ToolCallEvent } from '@earendil-works/pi-coding-agent';
 import { ToolDefinition } from '@earendil-works/pi-coding-agent';
 import { TSchema } from 'typebox';
 import { Type } from 'typebox';
@@ -24,6 +27,18 @@ import { WriteOperations } from '@earendil-works/pi-coding-agent';
  */
 export declare function activateAgentEnv(agentEnv: Record<string, string | undefined>, repoRoot: string): void;
 
+/** Minimal shape of the SDK method the resolver needs (keeps deps testable). */
+export declare interface AllowedToolsClient {
+    runtimeProfiles: {
+        allowedTools: (profileId: string, options: {
+            teamId: string;
+        }) => Promise<{
+            enforcement: ToolEnforcement;
+            allowedTools: string[];
+        }>;
+    };
+}
+
 /**
  * Construct an `AgentSession`. By default it is in-memory; callers may opt
  * parent sessions into daemon-owned file persistence via `sessionPersistence`.
@@ -63,6 +78,12 @@ declare interface BuildAgentSessionArgs {
     otelSpanAttrs: Record<string, string | number | boolean>;
     /** Agent name for `gen_ai.agent.name` on the root span. */
     agentName: string;
+    /**
+     * Extra pi extension factories appended after the always-on telemetry (and
+     * model-options) extensions — e.g. the tool-policy `tool_call` gate. Each is a
+     * plain `(pi) => void` registrar, same shape as the OTel extension.
+     */
+    extraExtensionFactories?: ((pi: ExtensionAPI) => void)[];
     /**
      * Parent sessions may persist their conversation history in a daemon-owned
      * directory. Subagents should leave this unset and stay in-memory.
@@ -260,8 +281,58 @@ export declare interface CreateSubagentToolArgs {
      * with whatever stubs they need.
      */
     contractRegistry: SubagentContractRegistry;
+    /**
+     * Extra pi extension factories every subagent session registers — chiefly the
+     * tool-policy `tool_call` gate. A subagent runs in its own `AgentSession`, so
+     * without re-registering the gate here it would execute tools un-checked,
+     * escaping the parent's enforcement (#1348 B2). Empty/undefined when tool
+     * enforcement is `off`, so subagents then match the parent's un-gated
+     * behaviour. The factories are read-only closures, safe to share across the
+     * parent and every subagent session.
+     */
+    extraExtensionFactories?: ((pi: ExtensionAPI) => void)[];
 }
 
+/**
+ * A pi extension factory that gates every `tool_call` against the resolved
+ * policy. Blocks in `enforce`, audits (and allows) in `watch`, and is a no-op in
+ * `off`. Register it in a session's `extensionFactories`.
+ */
+export declare function createToolPolicyExtension(deps: ToolPolicyExtensionDeps): (pi: ExtensionAPI) => void;
+
+/**
+ * Map a pi `tool_call` event to a gate decision, extracting the shell command
+ * for `bash` and delegating to {@link decideToolCall}.
+ */
+export declare function decideForEvent(event: ToolCallEvent, policy: SessionToolPolicy, analyze: ShellCommandAnalyzer['analyze']): GateDecision;
+
+/**
+ * Decide whether a tool call is permitted by the resolved policy.
+ *
+ * Fail-closed in `enforce` (audited-but-allowed in `watch`, no-op in `off`) for:
+ *
+ * 1. **Unresolvable commands** — a `bash` command whose executables cannot be
+ *    statically resolved (command substitution, `eval`, non-literal command
+ *    names, unparseable input).
+ * 2. **Arbitrary-code interpreters** — a `bash` command that invokes a shell or
+ *    language interpreter (`bash -c`, `python`, `node`, `perl`, …; the
+ *    analyzer's `arbitrary-code` risk tier). Being name-listed is NOT enough:
+ *    we cannot statically see the code such an interpreter runs, so the policy's
+ *    allow-set can't bound it. This is the interim conservative stance for
+ *    issue #1348 — an operator who lists `bash` still cannot smuggle
+ *    `bash -c "curl … | sh"` past `enforce`.
+ * 3. **Unlisted executables** — any resolved executable not in `allowedTools`.
+ *
+ * KNOWN LIMITATION (follow-up): the `escapable` risk tier (GTFOBins binaries
+ * like `find`, `tar`, `awk` that document shell-spawn / file-write techniques)
+ * is NOT blocked on the tier alone. The analyzer already re-analyzes the
+ * sub-commands it can see through documented escape flags (`find -exec`,
+ * `tar --to-command`, …), but techniques it cannot parse statically could still
+ * escape a name-based allow-set. Tightening `escapable` (e.g. an LLM judge or a
+ * capability-aware allow-set) is tracked as future work.
+ */
+export declare function decideToolCall(input: GateInput): GateDecision;
+
 /**
  * Ensure a cached snapshot exists, building one if needed.
  * Returns the absolute path to the qcow2 checkpoint file.
@@ -324,6 +395,14 @@ export declare interface ExecutePiTaskOptions {
      * claim. Task entries override profile entries with the same slug.
      */
     runtimeProfileContext?: readonly ContextRef[];
+    /**
+     * Runtime profile id, used to resolve the tool-policy allow-set at session
+     * start. Required together with a non-`off` `toolEnforcement` for the
+     * `tool_call` gate to run.
+     */
+    runtimeProfileId?: string;
+    /** Tool-policy enforcement mode for the selected runtime profile. */
+    toolEnforcement?: ToolEnforcement;
     /**
      * Forwarded to `buildTaskUserPrompt` for per-type builders. Static
      * across tasks. Today no built-in builder needs per-task `extras` —
@@ -455,6 +534,13 @@ export declare interface ExecutePiTaskOptions {
      * contracts. See #1106.
      */
     subagentContractRegistry?: SubagentContractRegistry;
+    /**
+     * Structured logger for tool-policy resolution/gate events. The daemon passes
+     * its task-bound pino child so these lines carry taskId/attemptN and join the
+     * run's NDJSON stream. When omitted, tool-policy events fall back to raw
+     * NDJSON on stderr (single-process / test callers). See #1348.
+     */
+    toolPolicyLogger?: ToolPolicyLogger;
 }
 
 /**
@@ -463,6 +549,38 @@ export declare interface ExecutePiTaskOptions {
  */
 export declare function findMainWorktree(): string;
 
+/**
+ * The gate's verdict:
+ * - `{ allow: true }` — let the tool run.
+ * - `{ allow: false, reason }` — block it (enforce mode).
+ * - `{ audit, ... }` — would-block, but proceed and record it (watch mode).
+ */
+export declare type GateDecision = {
+    allow: true;
+} | {
+    allow: false;
+    reason: string;
+} | {
+    audit: string;
+    missing?: string[];
+};
+
+export declare interface GateInput {
+    /** Pi tool name (e.g. 'bash', 'read', 'write', or a custom tool id). */
+    toolName: string;
+    /** The shell command, when `toolName === 'bash'`. */
+    command?: string;
+    enforcement: ToolEnforcement;
+    /** Names the policy allows (structured tool names + shell executable names). */
+    allowedTools: ReadonlySet<string>;
+    /**
+     * Synchronous shell analyzer (`ShellCommandAnalyzer.analyze`). Injected so the
+     * decision stays pure and testable; the analyzer's async WASM init happens
+     * once at session start.
+     */
+    analyze: (command: string) => CommandAnalysis;
+}
+
 /**
  * Baseline env keys forwarded to host-exec child processes.
  * Callers can extend this set at sandbox startup via `MoltNetToolsConfig.hostExecBaseEnv`.
@@ -732,6 +850,42 @@ export declare interface ProviderErrorRetryUi {
 
 export declare function redactRetryTriageSecrets(value: string): string;
 
+/**
+ * Resolve the session's tool policy at start-up.
+ *
+ * `off` short-circuits without a network call. Otherwise the allowed-tool set
+ * is fetched from the API. If that fetch fails, the mode decides the fallback:
+ * `enforce` **fails closed** (empty allow-set → every non-`off` tool is
+ * blocked); `watch` fails open (empty allow-set → every tool is audited but
+ * allowed).
+ *
+ * The result is a **session-start snapshot**: it is resolved once and cached for
+ * the session's lifetime. Policy edits made while a task is running do not take
+ * effect until the next session — a deliberate trade-off (one resolution per
+ * session, stable enforcement for the run) accepted over re-fetching per call.
+ */
+export declare function resolveSessionToolPolicy(input: ResolveSessionToolPolicyInput): Promise<SessionToolPolicy>;
+
+declare interface ResolveSessionToolPolicyInput {
+    agent: AllowedToolsClient;
+    profileId: string;
+    teamId: string;
+    /**
+     * The profile's enforcement mode, already known to the daemon from the
+     * resolved runtime profile. Used to decide fail-open vs fail-closed when the
+     * allowed-tools fetch fails.
+     */
+    enforcement: ToolEnforcement;
+    logger: ToolPolicyLogger;
+    /**
+     * Deadline for the allowed-tools fetch. A hung API call must not stall session
+     * start-up indefinitely, so on timeout we abort and fall back to the
+     * mode-appropriate degraded policy. Defaults to
+     * {@link DEFAULT_RESOLVE_TIMEOUT_MS}; `0`/negative disables the deadline.
+     */
+    timeoutMs?: number;
+}
+
 export declare function resolveTaskWorktreePath(mainRepo: string, workspaceId: string): string;
 
 export declare interface ResumeCommand {
@@ -836,6 +990,22 @@ export declare interface SandboxConfig {
     };
 }
 
+/** The resolved allow-set + enforcement mode for a runtime session. */
+export declare interface SessionToolPolicy {
+    enforcement: ToolEnforcement;
+    allowedTools: ReadonlySet<string>;
+    /**
+     * `true` when the allow-set is a **degraded fallback** — the allowed-tools
+     * fetch failed or timed out and this policy is the fail-closed/fail-open
+     * default, NOT the operator's actual configuration. An intentional
+     * empty-but-resolved policy (e.g. a profile with no bound tools) has
+     * `degraded: false`. Surfaced in every audit/block log so an operator can tell
+     * "blocked because the policy is empty" from "blocked because we couldn't read
+     * the policy". `off` and successful resolutions are never degraded.
+     */
+    degraded: boolean;
+}
+
 /** Extract snapshot-specific config for backwards compat with ensureSnapshot. */
 export declare type SnapshotConfig = NonNullable<SandboxConfig['snapshot']>;
 
@@ -1086,6 +1256,27 @@ declare type TaskUsage = Static<typeof TaskUsage>;
  */
 export declare function toGuestPath(localCwd: string, localPath: string, guestWorkspace: string): string;
 
+/** Enforcement mode resolved for the session's runtime profile. */
+export declare type ToolEnforcement = 'off' | 'watch' | 'enforce';
+
+export declare interface ToolPolicyExtensionDeps {
+    policy: SessionToolPolicy;
+    analyzer: ShellCommandAnalyzer;
+    logger: ToolPolicyLogger;
+}
+
+/**
+ * Structured logger the resolver and gate emit to. Deliberately the pino
+ * `(obj, msg)` shape so the daemon can pass a task-bound pino child directly —
+ * every tool-policy line then carries the daemon's taskId/attemptN context and
+ * lands in the same NDJSON stream as the rest of the run.
+ */
+declare interface ToolPolicyLogger {
+    debug: (obj: Record<string, unknown>, msg: string) => void;
+    info: (obj: Record<string, unknown>, msg: string) => void;
+    warn: (obj: Record<string, unknown>, msg: string) => void;
+}
+
 declare interface TrackedError {
     toolName: string;
     toolCallId: string;