Function buildManagedBashTool

packages/runtime/src/shell-tools.ts:144–312

(
  shellRuns: ShellRunLauncher,
  options: {
    executionFacts?: ToolExecutionFacts;
    shell?: ShellPlan;
    /** Opening sentence of the description, before the shared foreground/background/PTY contract. */
    lead?: string;
    /**
     * Whether this host has a sandbox boundary the model can be asked to declare.
     * False drops `required_boundary` from the schema entirely rather than
     * accepting and ignoring it: a parameter no host enforces is pure noise in
     * the model's tool selection.
     */
    declareSandboxBoundary?: boolean;
    /**
     * Foreground timeout when the model does not ask for one, per command —
     * the same hook shape buildForegroundBashTool exposes, so a host that
     * carves out a slow command keeps that carve-out on both paths instead of
     * re-implementing it on one.
     *
     * A host default is CLAMPED to MAX_FOREGROUND_BASH_TIMEOUT_MS rather than
     * passed through: the launcher REJECTS anything larger, so an operator who
     * raised their own floor past ten minutes would otherwise break every
     * foreground command instead of merely capping it. A timeout the model asks
     * for explicitly is still rejected above the maximum — that is a stated
     * schema bound, not a host misconfiguration.
     */
    defaultTimeoutMs?: (command: string) => number | undefined;
    /** Observes each committed result; used by hosts that record tool evidence. */
    afterResult?: (
      input: { command: string; cwd: string; timeoutMs?: number },
      result: TerminalToolResult | ShellRunToolResult,
      ctx: MakaToolContext,
    ) => Promise<void> | void;
    transformCommand?: (input: {
      command: string;
      pty: boolean;
      requiredBoundary?: SandboxBoundaryExpansion;
      ctx: MakaToolContext;
    }) =>
      | {
          argv?: readonly string[];
          cwd: string;
          env?: NodeJS.ProcessEnv;
          fdInputs?: readonly ChildFdInput[];
          sandboxType?: SandboxType;
          onCompletion?: (outcome: { successful: boolean }) => void;
        }
      | undefined;
  } = {},
)

}

export function buildManagedBashTool(
  shellRuns: ShellRunLauncher,
  options: {
    executionFacts?: ToolExecutionFacts;
    shell?: ShellPlan;
    /** Opening sentence of the description, before the shared foreground/background/PTY contract. */
    lead?: string;
    /**
     * Whether this host has a sandbox boundary the model can be asked to declare.
     * False drops `required_boundary` from the schema entirely rather than
     * accepting and ignoring it: a parameter no host enforces is pure noise in
     * the model's tool selection.
     */
    declareSandboxBoundary?: boolean;
    /**
     * Foreground timeout when the model does not ask for one, per command —
     * the same hook shape buildForegroundBashTool exposes, so a host that
     * carves out a slow command keeps that carve-out on both paths instead of
     * re-implementing it on one.
     *
     * A host default is CLAMPED to MAX_FOREGROUND_BASH_TIMEOUT_MS rather than
     * passed through: the launcher REJECTS anything larger, so an operator who
     * raised their own floor past ten minutes would otherwise break every
     * foreground command instead of merely capping it. A timeout the model asks
     * for explicitly is still rejected above the maximum — that is a stated
     * schema bound, not a host misconfiguration.
     */
    defaultTimeoutMs?: (command: string) => number | undefined;
    /** Observes each committed result; used by hosts that record tool evidence. */
    afterResult?: (
      input: { command: string; cwd: string; timeoutMs?: number },
      result: TerminalToolResult | ShellRunToolResult,
      ctx: MakaToolContext,
    ) => Promise<void> | void;
    transformCommand?: (input: {
      command: string;
      pty: boolean;
      requiredBoundary?: SandboxBoundaryExpansion;
      ctx: MakaToolContext;
    }) =>
      | {
          argv?: readonly string[];
          cwd: string;
          env?: NodeJS.ProcessEnv;
          fdInputs?: readonly ChildFdInput[];
          sandboxType?: SandboxType;
          onCompletion?: (outcome: { successful: boolean }) => void;
        }
      | undefined;
  } = {},
): MakaTool {
  const shell = options.shell ?? defaultShellPlan();
  const declareSandboxBoundary = options.declareSandboxBoundary !== false;
  const managedBashFields = {
    command: z.string().describe('The shell command to execute'),
    timeout_ms: z.number().int().positive().max(MAX_SHELL_RUN_TIMEOUT_MS).optional(),
    run_in_background: z.boolean().optional(),
    pty: z.boolean().optional(),