comisai 1.0.37 → 1.0.41

package/node_modules/@comis/skills/dist/tools/builtin/exec-tool/exec-shared.js

@@ -0,0 +1,386 @@
+// SPDX-License-Identifier: Apache-2.0
+// @allow-throw: builtin tool boundary; throws caught by AgentTool wrapper.
+/**
+ * Exec tool shared helpers.
+ *
+ * Extracted from `exec-tool.ts` (1,626L monolith). Block-move of the 10
+ * module-level helpers (resolveCwd, killTree, buildSpawnCommand,
+ * resolveDataEnv, commandUsesRawInterpreter, resolveSecretRefs, ecosystemFor,
+ * buildInstallDetourHint, buildSoftStopErrorTemplate, buildInstallDetourEventPayload)
+ * plus two factory-body extractions (evaluateInstallDetourGate, buildExecEnv)
+ * required to keep `index.ts` thin.
+ *
+ * @module
+ */
+import { existsSync } from "node:fs";
+import { PathTraversalError, safePath, systemEnvSnapshot, systemNowMs, tryGetContext, } from "@comis/core";
+import { resolvePaths } from "../file/safe-path-wrapper.js";
+import { throwToolError } from "../../../platform-tools/tool-helpers.js";
+import { parseInstallDetour, } from "../install-detour.js";
+import { SECRET_REF_NAME_PATTERN } from "./exec-types.js";
+// ---------------------------------------------------------------------------
+// cwd resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a user-supplied `cwd` against the workspace root via safePath.
+ * Throws via throwToolError when the path escapes workspace bounds.
+ */
+export function resolveCwd(workspacePath, cwdParam) {
+    try {
+        return safePath(workspacePath, cwdParam);
+    }
+    catch (error) {
+        if (error instanceof PathTraversalError) {
+            throwToolError("invalid_value", `Working directory outside workspace bounds: ${cwdParam}`);
+        }
+        throw error;
+    }
+    // unreachable — throwToolError never returns, but TS needs this
+    return workspacePath;
+}
+// ---------------------------------------------------------------------------
+// Process tree kill
+// ---------------------------------------------------------------------------
+/**
+ * Kill a process tree. When sandboxed, uses positive PID kill (bwrap's
+ * --die-with-parent + --unshare-pid cascade to all children). When not
+ * sandboxed, uses negative PID (process group kill) with fallback to
+ * direct PID kill.
+ */
+export function killTree(pid, sandboxed) {
+    try {
+        if (sandboxed) {
+            process.kill(pid, "SIGKILL");
+        }
+        else {
+            process.kill(-pid, "SIGKILL");
+        }
+    }
+    catch {
+        try {
+            process.kill(pid, "SIGKILL");
+        }
+        catch {
+            // Process already dead
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Sandbox spawn command builder
+// ---------------------------------------------------------------------------
+/**
+ * Build spawn command arguments, optionally wrapping in the platform sandbox
+ * and/or a PTY via Python pty.spawn. Exported for direct unit testing.
+ */
+export function buildSpawnCommand(command, cwd, sandboxConfig, workspacePath, tempDir, pty) {
+    let result;
+    if (!sandboxConfig) {
+        result = { bin: "/bin/bash", args: ["-c", command], cwd };
+    }
+    else {
+        const allReadOnlyPaths = [
+            ...sandboxConfig.readOnlyPaths,
+            ...sandboxConfig.configReadOnlyPaths,
+        ];
+        const resolvedShared = resolvePaths(sandboxConfig.sharedPaths);
+        const sandboxArgs = sandboxConfig.sandbox.buildArgs({
+            workspacePath,
+            sharedPaths: resolvedShared,
+            readOnlyPaths: allReadOnlyPaths,
+            cwd,
+            tempDir,
+        });
+        // bwrap handles cwd internally via --chdir; sandbox-exec does not.
+        const providerHandlesCwd = sandboxConfig.sandbox.name === "bwrap";
+        result = {
+            bin: sandboxArgs[0],
+            args: [...sandboxArgs.slice(1), "/bin/bash", "-c", command],
+            cwd: providerHandlesCwd ? undefined : cwd,
+        };
+    }
+    // PTY via Python pty.spawn(): creates a PTY pair via openpty(), forks,
+    // connects the child to the PTY slave, and proxies I/O between piped
+    // stdin/stdout and the PTY master. Handles piped stdin gracefully where
+    // `script` would fail with tcgetattr on non-TTY stdin.
+    if (pty) {
+        result = {
+            bin: "python3",
+            args: ["-c", "import pty,sys;sys.exit(pty.spawn(sys.argv[1:]))", result.bin, ...result.args],
+            cwd: result.cwd,
+        };
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// secretRefs helpers
+// ---------------------------------------------------------------------------
+/**
+ * Workspace-internal data env resolver. Returns env vars derived from
+ * `workspaceDir` so python/matplotlib subprocesses do NOT inherit the
+ * daemon's host PATH or cache-dir defaults. Shape mirrors
+ * `packages/agent/src/workspace/data-env.ts` verbatim; lifted inline to
+ * avoid a cross-package agent import (skills + agent are siblings).
+ */
+function resolveDataEnv(opts) {
+    const venvBin = safePath(opts.workspaceDir, "venv", "bin");
+    const cacheDir = safePath(opts.workspaceDir, ".cache");
+    const mplDir = safePath(cacheDir, "matplotlib");
+    return {
+        PATH: venvBin,
+        MPLCONFIGDIR: mplDir,
+        XDG_CACHE_HOME: cacheDir,
+        MPLBACKEND: "Agg",
+        PIP_DISABLE_PIP_VERSION_CHECK: "1",
+    };
+}
+/**
+ * Detect raw-interpreter command shapes (python -c, node -e, bash -c, etc.).
+ * Used to refuse secretRefs on commands where `echo $TOKEN` would be trivial.
+ */
+export function commandUsesRawInterpreter(command) {
+    const stripped = command
+        .replace(/^\s*cd\s+\S+\s*&&\s*/i, "")
+        .replace(/^\s*env\s+(?:[A-Z_][A-Z0-9_]*=\S+\s+)*/i, "")
+        .trim();
+    const rawPattern = /^(python3?|node|nodejs|ruby|perl|php|bash|sh|zsh|dash|lua|deno|bun)(?:\s+-[cCeE](?:\s+|$)|\s+-(?:\s|$))/i;
+    return rawPattern.test(stripped);
+}
+/**
+ * Resolve a list of secret names into an env-var record via SecretManager.
+ * Rejects invalid names, platform-managed names, and missing names.
+ * The returned record is merged into the child's env AFTER userEnv so
+ * `secretRefs` wins on collision.
+ */
+export function resolveSecretRefs(refs, secretManager, platformSecretNames) {
+    const env = {};
+    const seen = new Set();
+    for (const name of refs) {
+        if (typeof name !== "string" || !SECRET_REF_NAME_PATTERN.test(name)) {
+            return {
+                ok: false,
+                error: `Invalid secretRefs name "${String(name)}". Names must match /^[A-Z][A-Z0-9_]*$/ (e.g. CLOUDFLARE_API_TOKEN).`,
+            };
+        }
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        if (platformSecretNames.has(name)) {
+            return {
+                ok: false,
+                error: `Secret "${name}" is referenced by the daemon config and is platform-managed — ` +
+                    `exec cannot expose it. This rule prevents agents from exfiltrating credentials ` +
+                    `the daemon uses to talk to providers. Ask the user to store a separate ` +
+                    `user-task secret under a different name, or invoke this command locally.`,
+            };
+        }
+        const value = secretManager.get(name);
+        if (value === undefined || value.length === 0) {
+            return {
+                ok: false,
+                error: `Secret "${name}" is not configured. Call gateway(action:"env_list", filter:"${name.split("_")[0]}*") ` +
+                    `to see available names, or ask the user to store it via env_set.`,
+            };
+        }
+        env[name] = value;
+    }
+    return { ok: true, env };
+}
+// ---------------------------------------------------------------------------
+// Install-detour helpers
+// ---------------------------------------------------------------------------
+function ecosystemFor(pm) {
+    return pm === "pip" ? "python" : "node";
+}
+/**
+ * Build the structured install-detour hint augmentation for advise mode.
+ * Returns BOTH a string (for `details.installDetourHint`) AND a sibling
+ * `[hint]` content block (for the `result.content` array).
+ */
+export function buildInstallDetourHint(decision) {
+    const lines = decision.overlaps.map((o) => {
+        const cluster = o.cluster ? ` (cluster: ${o.cluster})` : "";
+        return o.sourceType === "mcp"
+            ? `- ${o.packageName} -> connected MCP server "${o.sourceName}"${cluster}`
+            : `- ${o.packageName} -> available skill "${o.sourceName}"${cluster}`;
+    });
+    const text = `[hint] Installed packages overlap available capabilities:\n${lines.join("\n")}\n` +
+        `If you can use these capabilities directly, do so before relying on the install.`;
+    return {
+        installDetourHint: text,
+        hintContentBlock: { type: "text", text },
+    };
+}
+/**
+ * Build the soft-stop error template. Returns null when no overlap source
+ * remains connected/visible at error-build time (overlaps disappeared
+ * mid-call; refusal no longer justified — caller falls through to spawn).
+ */
+function buildSoftStopErrorTemplate(decision, port) {
+    const connectedServers = new Set(port.getConnectedMcpServers());
+    const visibleSkills = new Set(port.getPromptSkillCapabilities().map((s) => s.name));
+    const filtered = decision.overlaps.filter((o) => o.sourceType === "mcp" ? connectedServers.has(o.sourceName) : visibleSkills.has(o.sourceName));
+    if (filtered.length === 0)
+        return null;
+    const bullets = filtered.map((o) => {
+        const cluster = o.cluster ? ` (cluster: ${o.cluster})` : "";
+        return o.sourceType === "mcp"
+            ? `- ${o.packageName} -> connected MCP server "${o.sourceName}"${cluster}`
+            : `- ${o.packageName} -> available skill "${o.sourceName}"${cluster}`;
+    });
+    return [
+        "Refused: install overlaps with available capability source(s).",
+        "",
+        "Overlapping packages:",
+        ...bullets,
+        "",
+        "To proceed, choose one:",
+        "1. Use the connected tool(s) or available skill(s) listed above for the overlapping work.",
+        "2. If you only need the non-overlapping packages, rerun exec with the overlapping ones removed.",
+        "3. If you genuinely need the install despite the overlap, ask the user/operator to approve the install-detour override, then rerun this exact command with `allowInstallDetour: true`.",
+    ].join("\n");
+}
+/**
+ * Build the closed `tool:install_detour_detected` event payload. Sanitized
+ * only: NEVER includes `command`, `rawCommand`, `stdout`, `stderr`, raw shell
+ * fragments, URLs, paths, or credentials.
+ */
+function buildInstallDetourEventPayload(decision, mode, action) {
+    const ctx = tryGetContext();
+    return {
+        agentId: ctx?.sessionKey ?? "unknown",
+        sessionKey: ctx?.sessionKey ?? "unknown",
+        traceId: ctx?.traceId,
+        packageManager: decision.packageManager,
+        commandDigest: decision.commandDigest,
+        packages: decision.packages.map((p) => ({
+            normalizedName: p,
+            ecosystem: ecosystemFor(decision.packageManager),
+        })),
+        overlaps: decision.overlaps.map((o) => ({
+            packageName: o.packageName,
+            sourceType: o.sourceType,
+            sourceName: o.sourceName,
+            reason: o.reason,
+        })),
+        mode,
+        action,
+        timestamp: systemNowMs(),
+    };
+}
+/**
+ * Run the install-detour policy gate BEFORE any subprocess spawn. Decision
+ * computed ONCE here, propagated to event emission + ProcessSession + envelope.
+ * Block-extracted from the createExecTool factory.
+ */
+export async function evaluateInstallDetourGate(deps) {
+    const { command, allowInstallDetourOverride, toolCapabilityPort, approvalGate, eventBus, logger } = deps;
+    const installDetourMode = toolCapabilityPort.getInstallDetourMode();
+    const installDetourDecision = parseInstallDetour(command, toolCapabilityPort);
+    let terminalAction = "no-decision";
+    let errorMessage = null;
+    if (installDetourDecision !== null) {
+        if (installDetourMode === "observe") {
+            for (const overlap of installDetourDecision.overlaps) {
+                eventBus?.emit("tool:install_detour_detected", buildInstallDetourEventPayload({ ...installDetourDecision, overlaps: [overlap] }, "observe", "observed"));
+                terminalAction = "observed";
+            }
+        }
+        else if (installDetourMode === "advise") {
+            for (const overlap of installDetourDecision.overlaps) {
+                eventBus?.emit("tool:install_detour_detected", buildInstallDetourEventPayload({ ...installDetourDecision, overlaps: [overlap] }, "advise", "hinted"));
+                terminalAction = "hinted";
+            }
+        }
+        else if (installDetourMode === "soft-stop") {
+            if (!allowInstallDetourOverride) {
+                eventBus?.emit("tool:install_detour_detected", buildInstallDetourEventPayload(installDetourDecision, "soft-stop", "soft_stopped"));
+                terminalAction = "soft_stopped";
+                const built = buildSoftStopErrorTemplate(installDetourDecision, toolCapabilityPort);
+                if (built === null) {
+                    logger?.debug({ toolName: "exec", commandDigest: installDetourDecision.commandDigest, mode: "soft-stop", outcome: "overlaps-disappeared" }, "install-detour overlap sources disappeared mid-call; falling through to spawn");
+                }
+                else {
+                    errorMessage = built;
+                }
+            }
+            else {
+                const ctx = tryGetContext();
+                if (!approvalGate || !ctx) {
+                    eventBus?.emit("tool:install_detour_detected", buildInstallDetourEventPayload(installDetourDecision, "soft-stop", "override_denied"));
+                    terminalAction = "override_denied";
+                    const built = buildSoftStopErrorTemplate(installDetourDecision, toolCapabilityPort);
+                    errorMessage = built ?? "Install-detour override denied: missing approval gate or request context.";
+                }
+                else {
+                    // override_requested event is emitted BEFORE the await (event-pair
+                    // contract). terminalAction is NOT set here because both downstream
+                    // branches (resolution.approved / !approved) reassign it; the
+                    // event-bus emit is the observable signal of the override-request.
+                    eventBus?.emit("tool:install_detour_detected", buildInstallDetourEventPayload(installDetourDecision, "soft-stop", "override_requested"));
+                    const resolution = await approvalGate.requestApproval({
+                        toolName: "exec",
+                        action: `exec.install_detour.override:${installDetourDecision.commandDigest}`,
+                        params: {
+                            packageManager: installDetourDecision.packageManager,
+                            packages: installDetourDecision.packages,
+                            overlaps: installDetourDecision.overlaps,
+                            mode: "soft-stop",
+                            commandDigest: installDetourDecision.commandDigest,
+                        },
+                        agentId: ctx.userId ?? "unknown",
+                        sessionKey: ctx.sessionKey,
+                        trustLevel: (ctx.trustLevel ?? "admin"),
+                        channelType: ctx.channelType,
+                    });
+                    if (!resolution.approved) {
+                        eventBus?.emit("tool:install_detour_detected", buildInstallDetourEventPayload(installDetourDecision, "soft-stop", "override_denied"));
+                        terminalAction = "override_denied";
+                        errorMessage = `Install-detour override denied: ${resolution.reason ?? "no reason given"}`;
+                    }
+                    else {
+                        eventBus?.emit("tool:install_detour_detected", buildInstallDetourEventPayload(installDetourDecision, "soft-stop", "overridden"));
+                        terminalAction = "overridden";
+                    }
+                }
+            }
+        }
+        logger?.info({
+            toolName: "exec",
+            commandDigest: installDetourDecision.commandDigest,
+            packageManager: installDetourDecision.packageManager,
+            packageCount: installDetourDecision.packages.length,
+            overlapCount: installDetourDecision.overlaps.length,
+            mode: installDetourMode,
+            action: terminalAction,
+        }, "install-detour policy gate evaluated");
+    }
+    return { decision: installDetourDecision, mode: installDetourMode, errorMessage };
+}
+/**
+ * Build the final environment record for the subprocess by merging:
+ *   baseEnv → dataEnv → userEnv → resolvedSecretEnv (last wins on collision).
+ * Block-extracted from the createExecTool factory.
+ */
+export function buildExecEnv(deps) {
+    const { workspacePath, subprocessEnv, userEnv, resolvedSecretEnv, sandboxConfig, logger } = deps;
+    const baseEnv = subprocessEnv ?? systemEnvSnapshot();
+    const dataEnv = resolveDataEnv({ workspaceDir: workspacePath });
+    const venvBin = safePath(workspacePath, "venv", "bin");
+    if (existsSync(venvBin)) {
+        logger?.debug({ toolName: "exec", workspaceDir: workspacePath, hint: "Prepending workspace-prewarmed venv/bin to PATH" }, "Exec workspace venv detected");
+        if (dataEnv.PATH && baseEnv.PATH) {
+            dataEnv.PATH = `${dataEnv.PATH}:${baseEnv.PATH}`;
+        }
+    }
+    else {
+        delete dataEnv.PATH;
+    }
+    const env = {
+        ...baseEnv,
+        ...dataEnv,
+        ...(userEnv ?? {}),
+        ...(resolvedSecretEnv ?? {}),
+    };
+    const finalEnv = sandboxConfig?.sandbox.wrapEnv?.(env, workspacePath) ?? env;
+    return finalEnv;
+}

package/node_modules/@comis/skills/dist/tools/builtin/exec-tool/exec-types.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Exec tool types and parameter schema.
+ *
+ * Holds the interfaces, the TypeBox parameter schema, and the module-private
+ * constants consumed by foreground/background helpers in this directory.
+ *
+ * @module
+ */
+import type { spawn } from "node:child_process";
+import type { createWriteStream } from "node:fs";
+import { Type } from "typebox";
+import type { TypedEventBus, SecretManager, ToolCapabilityPort, ApprovalGate } from "@comis/core";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { ExecSandboxConfig } from "../sandbox/types.js";
+import type { ProcessRegistry } from "../process-registry.js";
+import type { InstallDetourDecision } from "../install-detour.js";
+/** Maximum bytes to persist to disk for truncated output. */
+export declare const MAX_PERSIST_BYTES: number;
+/** Max output chars for background mode's ProcessSession rolling buffer. */
+export declare const BACKGROUND_MAX_OUTPUT_CHARS: number;
+/** Rolling buffer size for foreground streaming (2x DEFAULT_MAX_BYTES). */
+export declare const ROLLING_BUFFER_MAX: number;
+export declare const DEFAULT_TIMEOUT_MS = 120000;
+export declare const MAX_TIMEOUT_MS = 600000;
+/** Valid secret env var name (same rule as env.set). */
+export declare const SECRET_REF_NAME_PATTERN: RegExp;
+export declare const ExecParams: Type.TObject<{
+    command: Type.TString;
+    cwd: Type.TOptional<Type.TString>;
+    timeoutMs: Type.TOptional<Type.TInteger>;
+    env: Type.TOptional<Type.TRecord<"^.*$", Type.TString>>;
+    background: Type.TOptional<Type.TBoolean>;
+    input: Type.TOptional<Type.TString>;
+    autoBackgroundMs: Type.TOptional<Type.TInteger>;
+    description: Type.TOptional<Type.TString>;
+    pty: Type.TOptional<Type.TBoolean>;
+    secretRefs: Type.TOptional<Type.TArray<Type.TString>>;
+    allowInstallDetour: Type.TOptional<Type.TBoolean>;
+}>;
+/** Minimal pino-compatible logger for structured tool logging. */
+export interface ToolLogger {
+    debug(obj: Record<string, unknown>, msg: string): void;
+    info(obj: Record<string, unknown>, msg: string): void;
+}
+/**
+ * Dependencies for the exec tool factory. Backward compatibility is NOT
+ * preserved (see CLAUDE.md user-memory `feedback_no_backward_compat`).
+ *
+ * `toolCapabilityPort` is REQUIRED — wires the install-detour policy gate
+ * inside `execute(...)` consuming `port.getInstallDetourMode()`. Daemon
+ * wiring may inject `createNoOpCapabilityPort()` at the construction site
+ * (`packages/daemon/src/wiring/setup-tools.ts`); the no-op returns empty
+ * connected-server and skill arrays so the parser sees no overlaps.
+ *
+ * `approvalGate` is OPTIONAL — only required by the `soft-stop` mode
+ * override path. Missing gate → `soft-stop` denies override
+ * (fail-closed per AGENTS.md §2.1).
+ */
+export interface ExecToolDeps {
+    readonly workspacePath: string;
+    readonly registry: ProcessRegistry;
+    readonly secretManager: SecretManager;
+    readonly platformSecretNames: ReadonlySet<string>;
+    readonly logger?: ToolLogger;
+    readonly subprocessEnv?: Record<string, string>;
+    readonly sandboxConfig?: ExecSandboxConfig;
+    readonly eventBus?: TypedEventBus;
+    readonly getToolResultsDir?: () => string | undefined;
+    /** REQUIRED for v1.1 capability layer. */
+    readonly toolCapabilityPort: ToolCapabilityPort;
+    /** Optional. Required only for soft-stop override path. */
+    readonly approvalGate?: ApprovalGate;
+}
+export interface EscalationContext {
+    command: string;
+    child: ReturnType<typeof spawn>;
+    /** performance.now() at spawn -- monotonic, used for elapsed durationMs. */
+    startTime: number;
+    /** systemNowMs() at spawn -- Unix epoch ms, used for ProcessSession.startedAt
+     *  (which downstream code subtracts from systemNowMs() to compute runtimeMs).
+     *  Captured separately because performance.now() is a monotonic clock relative
+     *  to process start, not a wall clock. */
+    startTimeMs: number;
+    stdoutBuf: string;
+    stderrBuf: string;
+    registry: ProcessRegistry;
+    sandboxConfig?: ExecSandboxConfig;
+    logger?: ToolLogger;
+    spillStream: ReturnType<typeof createWriteStream> | null;
+    signal?: AbortSignal;
+    onAbort: () => void;
+    timeoutTimer: ReturnType<typeof setTimeout>;
+    resolve: (value: AgentToolResult<unknown>) => void;
+    setResolved: () => void;
+    description?: string;
+    /** Install-detour spawn-time decision (advise+overlap only). */
+    installDetourDecision?: InstallDetourDecision;
+    /** Install-detour mode at spawn time (drives augmentation). */
+    installDetourMode?: "observe" | "advise" | "soft-stop";
+}

package/node_modules/@comis/skills/dist/tools/builtin/exec-tool/exec-types.js

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Exec tool types and parameter schema.
+ *
+ * Holds the interfaces, the TypeBox parameter schema, and the module-private
+ * constants consumed by foreground/background helpers in this directory.
+ *
+ * @module
+ */
+import { Type } from "typebox";
+import { DEFAULT_MAX_BYTES } from "../truncate.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Maximum bytes to persist to disk for truncated output. */
+export const MAX_PERSIST_BYTES = 64 * 1024 * 1024;
+/** Max output chars for background mode's ProcessSession rolling buffer. */
+export const BACKGROUND_MAX_OUTPUT_CHARS = 1024 * 1024; // 1MB
+/** Rolling buffer size for foreground streaming (2x DEFAULT_MAX_BYTES). */
+export const ROLLING_BUFFER_MAX = DEFAULT_MAX_BYTES * 2; // 100KB
+export const DEFAULT_TIMEOUT_MS = 120_000;
+export const MAX_TIMEOUT_MS = 600_000;
+/** Valid secret env var name (same rule as env.set). */
+export const SECRET_REF_NAME_PATTERN = /^[A-Z][A-Z0-9_]*$/;
+// ---------------------------------------------------------------------------
+// Parameter schema
+// ---------------------------------------------------------------------------
+export const ExecParams = Type.Object({
+    command: Type.String({ description: "The shell command to execute (single-line only — use 'input' param for multi-line scripts)" }),
+    cwd: Type.Optional(Type.String({ description: "Working directory (defaults to workspace)" })),
+    timeoutMs: Type.Optional(Type.Integer({
+        description: "Timeout in ms (default 120000, max 600000)",
+        default: 120_000,
+    })),
+    env: Type.Optional(Type.Record(Type.String(), Type.String(), {
+        description: "Environment variable overrides",
+    })),
+    background: Type.Optional(Type.Boolean({ description: "Run in background and return immediately" })),
+    input: Type.Optional(Type.String({ description: "String to write to process stdin" })),
+    autoBackgroundMs: Type.Optional(Type.Integer({
+        description: "Auto-background threshold in ms. Foreground commands exceeding this duration transition to background. Default 15000. Set 0 to disable.",
+        default: 15_000,
+    })),
+    description: Type.Optional(Type.String({
+        description: "Human-readable label for this command (e.g. 'Installing dependencies'). Appears in UI activity indicators and structured logs.",
+    })),
+    pty: Type.Optional(Type.Boolean({
+        description: "Allocate a pseudo-terminal for the command. Required for interactive CLI tools that check process.stdout.isTTY. Wraps the command in 'script' to provide a real TTY.",
+    })),
+    secretRefs: Type.Optional(Type.Array(Type.String(), {
+        maxItems: 8,
+        description: "Secret/credential NAMES (not values) to inject as env vars into the subprocess. Use this to pass API tokens to CLI tools like wrangler/gh/gcloud/kubectl without tripping the env-var allowlist. Names are resolved server-side via SecretManager; values never flow through agent context. Call env_list first to discover available names. Platform-managed secrets (referenced by the daemon config, e.g. ANTHROPIC_API_KEY) are rejected. Raw-interpreter commands (python -c, node -e, bash -c, etc.) are rejected with secretRefs to prevent trivial echo-to-stdout leaks. Example: {command: 'npx wrangler pages deploy ./dist', secretRefs: ['CLOUDFLARE_API_TOKEN', 'CLOUDFLARE_ACCOUNT_ID']}",
+    })),
+    allowInstallDetour: Type.Optional(Type.Boolean({
+        description: "Request an operator-approved override when the user explicitly needs " +
+            "package installation despite an equivalent connected MCP server or " +
+            "available skill. Submits an approval request — does NOT self-authorize. " +
+            "Per-commandDigest scoped (one approval does not cover a different install).",
+    })),
+});

package/node_modules/@comis/skills/dist/tools/builtin/exec-tool/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Exec tool module.
+ *
+ * Barrel + thin createExecTool factory. The factory body delegates to:
+ *   - `evaluateInstallDetourGate` / `buildExecEnv` (exec-shared.ts)
+ *   - `executeForeground` (exec-foreground.ts)
+ *   - `executeBackground` (exec-background.ts)
+ *
+ * No aliases — every export keeps its canonical name.
+ *
+ * @module
+ */
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { ExecParams, type ExecToolDeps } from "./exec-types.js";
+export type { ExecToolDeps } from "./exec-types.js";
+export { killTree, buildSpawnCommand, buildInstallDetourHint } from "./exec-shared.js";
+/**
+ * Create an exec tool for shell command execution.
+ *
+ * Backward compat NOT preserved (memory `feedback_no_backward_compat`).
+ *
+ * @param deps - Dependencies bundle. See `ExecToolDeps` for field semantics.
+ *   `toolCapabilityPort` is REQUIRED; `approvalGate` is optional but
+ *   required for the soft-stop override path.
+ * @returns AgentTool implementing the exec interface.
+ */
+export declare function createExecTool(deps: ExecToolDeps): AgentTool<typeof ExecParams>;