<Runbook>

// @smithers-type-exports-begin
/** @typedef {import("./RunbookProps.ts").RunbookProps} RunbookProps */
/** @typedef {import("./RunbookStep.ts").RunbookStep} RunbookStep */
// @smithers-type-exports-end

import React from "react";
import { SmithersContext } from "@smthrs/react-reconciler/context";
import { Sequence } from "./Sequence.js";
import { Task } from "./Task.js";
import { Approval } from "./Approval.js";
/**
 * <Runbook> — Sequential steps with risk classification.
 *
 * Safe steps auto-execute. Risky and critical steps require human approval first.
 * Composes: Sequence of [Approval? → Task] per step, chained via `needs`.
 * @param {RunbookProps} props
 */
export function Runbook(props) {
  if (props.skipIf) return null;
  const ctx = React.useContext(SmithersContext);
  const prefix = props.id ?? "runbook";
  const onDeny = props.onDeny ?? "fail";
  const children = [];
  let previousStepId;
  for (let i = 0; i < props.steps.length; i++) {
    const step = props.steps[i];
    const stepId = `${prefix}-${step.id}`;
    const agent = step.agent ?? props.defaultAgent;
    const output = step.output ?? props.stepOutput;
    const label = step.label ?? step.id;
    // Build needs: each step depends on the previous step's completion
    const needs = previousStepId ? { previousStep: previousStepId } : undefined;
    if (step.risk === "safe") {
      // Safe: plain Task, auto-executes
      children.push(
        React.createElement(Task, {
          key: stepId,
          id: stepId,
          output,
          agent,
          needs,
          label: `[safe] ${label}`,
          children: step.command ?? `Execute step: ${label}`,
        }),
      );
      previousStepId = stepId;
    } else {
      // Risky or critical: Approval gate then Task
      const approvalId = `${stepId}-approval`;
      const approvalOutput = `${approvalId}-decision`;
      const shouldGateOnDecision = onDeny === "skip" && Boolean(ctx);
      const decision = ctx?.outputMaybe(approvalOutput, { nodeId: approvalId });
      const deniedAndSkipping =
        shouldGateOnDecision &&
        decision != null &&
        typeof decision === "object" &&
        /** @type {Record<string, unknown>} */ (decision).approved === false;
      const isCritical = step.risk === "critical";
      const approvalTitle =
        props.approvalRequest?.title ?? `Approve ${isCritical ? "CRITICAL" : "risky"} step: ${label}`;
      const approvalSummary =
        props.approvalRequest?.summary ??
        (isCritical
          ? `CRITICAL step requires elevated approval. Command: ${step.command ?? label}`
          : `Risky step requires approval before execution. Command: ${step.command ?? label}`);
      const approvalMeta = {
        stepId: step.id,
        risk: step.risk,
        ...props.approvalRequest?.metadata,
      };
      if (isCritical) {
        approvalMeta.elevated = true;
      }
      children.push(
        React.createElement(Approval, {
          key: approvalId,
          id: approvalId,
          output: approvalOutput,
          request: {
            title: approvalTitle,
            summary: approvalSummary,
            metadata: approvalMeta,
          },
          onDeny,
          needs,
          label: `Approve: ${label}`,
        }),
      );
      if (!deniedAndSkipping) {
        children.push(
          React.createElement(Task, {
            key: stepId,
            id: stepId,
            output,
            agent,
            deps: shouldGateOnDecision ? { approval: approvalOutput } : undefined,
            needs: { approval: approvalId },
            label: `[${step.risk}] ${label}`,
            children: step.command ?? `Execute step: ${label}`,
          }),
        );
      }
      previousStepId = deniedAndSkipping ? approvalId : stepId;
    }
  }
  return React.createElement(Sequence, null, ...children);
}

// @smithers-type-exports-begin
/** @typedef {import("./OutputSnapshot.ts").OutputSnapshot} OutputSnapshot */
/** @typedef {import("./SmithersCtxOptions.ts").SmithersCtxOptions} SmithersCtxOptions */
// @smithers-type-exports-end

import React from "react";
import { SmithersError } from "@smthrs/errors/SmithersError";
export { SmithersCtx } from "@smthrs/driver/SmithersCtx";
/** @type {React.Context<SmithersCtx<any> | null>} */
export const SmithersContext = React.createContext(null);
SmithersContext.displayName = "SmithersContext";
/**
 * @template Schema
 * @returns {{ SmithersContext: React.Context<SmithersCtx<Schema> | null>, useCtx: () => SmithersCtx<Schema> }}
 */
export function createSmithersContext() {
  /** @type {React.Context<SmithersCtx<Schema> | null>} */
  const Context = React.createContext(null);
  Context.displayName = "SmithersContext";
  /**
   * @returns {SmithersCtx<Schema>}
   */
  function useCtx() {
    const ctx = React.useContext(Context);
    if (!ctx) {
      throw new SmithersError(
        "CONTEXT_OUTSIDE_WORKFLOW",
        "useCtx() must be called inside a <Workflow> created by createSmithers()",
      );
    }
    return ctx;
  }
  return { SmithersContext: Context, useCtx };
}

import React from "react";
/** @typedef {import("./SequenceProps.ts").SequenceProps} SequenceProps */

/**
 * @param {SequenceProps} props
 */
export function Sequence(props) {
  if (props.skipIf) return null;
  // Sequence carries only a display label; pass a sanitized bag (align with
  // the sanitizing structural components) so control props don't leak through.
  // `label` names the phase group in run views (graph, the Claude /workflows
  // mirror) and is preserved in the persisted frame XML.
  const next = {
    ...(props.label === undefined ? {} : { label: props.label }),
    ...(props.failurePolicy === undefined ? {} : { failurePolicy: props.failurePolicy }),
  };
  return React.createElement("smithers:sequence", next, props.children);
}

// @smithers-type-exports-begin
/**
 * @template D
 * @typedef {import("./InferDeps.ts").InferDeps<D>} InferDeps
 */
/** @typedef {import("./OutputTarget.ts").OutputTarget} OutputTarget */
// @smithers-type-exports-end

import { applyCliToolAllowlist } from "./cliToolAllowlist.js";
import { createTaskComponent } from "./taskCore.js";

export { renderPromptToText } from "./taskCore.js";

/**
 * The Node/CLI-agent-aware `Task`. Every render-path behavior (deps
 * resolution, agent-chain assembly, MDX prompt rendering, static/compute/agent
 * branching) lives in `taskCore.js`; this file only supplies the CLI-agent
 * tool-allowlist enforcement step (`applyCliToolAllowlist`, which statically
 * imports `ClaudeCodeAgent`/`PiAgent`/`GeminiAgent`/`AntigravityAgent` — see
 * `cliToolAllowlist.js`). `Task.browser.js` builds the same component with a
 * no-op allowlist step instead, so it never pulls those Node-only
 * (`node:child_process`-backed) classes into a browser bundle.
 */
export const Task = createTaskComponent({ applyCliToolAllowlist });

// @smithers-type-exports-begin
/** @typedef {import("./ApprovalDecision.ts").ApprovalDecision} ApprovalDecision */
/** @typedef {import("./ApprovalRanking.ts").ApprovalRanking} ApprovalRanking */
/** @typedef {import("./ApprovalRequest.ts").ApprovalRequest} ApprovalRequest */
/** @typedef {import("./ApprovalSelection.ts").ApprovalSelection} ApprovalSelection */
// @smithers-type-exports-end

import React from "react";
import { z } from "zod";
import { SmithersContext } from "@smthrs/react-reconciler/context";
import { getTaskRuntime } from "@smthrs/driver/task-runtime";
import { SmithersDb } from "@smthrs/db/adapter";
import { SmithersError } from "@smthrs/errors/SmithersError";
/** @typedef {import("./ApprovalAutoApprove.ts").ApprovalAutoApprove} ApprovalAutoApprove */
/** @typedef {import("./ApprovalMode.ts").ApprovalMode} ApprovalMode */
/** @typedef {import("./ApprovalOption.ts").ApprovalOption} ApprovalOption */
/**
 * @template Row, Output
 * @typedef {import("./ApprovalProps.ts").ApprovalProps<Row, Output>} ApprovalProps
 */

export const approvalDecisionSchema = z.object({
  approved: z.boolean(),
  // `note` is omitted entirely when no note was provided, so the default
  // decision schema must accept an absent key (optional) as well as the
  // legacy null/string shapes.
  note: z.string().nullable().optional(),
  decidedBy: z.string().nullable(),
  decidedAt: z.string().datetime().nullable(),
});
export const approvalSelectionSchema = z.object({
  selected: z.string(),
  notes: z.string().nullable(),
});
export const approvalRankingSchema = z.object({
  ranked: z.array(z.string()),
  notes: z.string().nullable(),
});
/**
 * @param {unknown} value
 * @returns {value is import("zod").ZodObject<import("zod").ZodRawShape>}
 */
function isZodObject(value) {
  return Boolean(value && typeof value === "object" && "shape" in value);
}
/**
 * @template T
 * @param {unknown} value
 * @returns {T | null}
 */
function parseJson(value) {
  if (typeof value !== "string" || value.length === 0) {
    return null;
  }
  try {
    return JSON.parse(value);
  } catch {
    return null;
  }
}
/**
 * @param {ApprovalMode} mode
 * @returns {import("zod").ZodObject<import("zod").ZodRawShape>}
 */
function defaultSchemaForMode(mode) {
  switch (mode) {
    case "select":
      return approvalSelectionSchema;
    case "rank":
      return approvalRankingSchema;
    default:
      return approvalDecisionSchema;
  }
}
/**
 * @param {{ status?: string | null; note?: string | null; decidedBy?: string | null; decidedAtMs?: number | null } | undefined | null} approval
 * @param {import("zod").ZodObject<import("zod").ZodRawShape>} outputSchema
 * @returns {Record<string, unknown>}
 */
function buildDecisionPayload(approval, outputSchema) {
  const base = {
    approved: approval?.status === "approved",
    decidedBy: approval?.decidedBy ?? null,
    decidedAt: approval?.decidedAtMs != null ? new Date(approval.decidedAtMs).toISOString() : null,
  };
  if (typeof approval?.note === "string") {
    return { ...base, note: approval.note };
  }
  if (outputSchema.safeParse(base).success) {
    return base;
  }
  return { ...base, note: null };
}
/**
 * @param {ApprovalMode | undefined} mode
 * @returns {"select" | "rank" | "decision"}
 */
function normalizeMode(mode) {
  switch (mode) {
    case "select":
      return "select";
    case "rank":
      return "rank";
    default:
      return "decision";
  }
}
/**
 * @param {ApprovalOption[] | undefined} options
 * @returns {ApprovalOption[] | undefined}
 */
function normalizeOptions(options) {
  return options?.map((option) => ({
    key: option.key,
    label: option.label,
    ...(option.summary ? { summary: option.summary } : {}),
    ...(option.metadata ? { metadata: option.metadata } : {}),
  }));
}
/**
 * @param {unknown} value
 * @param {"allowedScopes" | "allowedUsers"} field
 * @param {string} id
 * @returns {string[] | undefined}
 */
function validateApprovalRestriction(value, field, id) {
  if (value === undefined) {
    return undefined;
  }
  if (
    !Array.isArray(value) ||
    Array.from(value).some((entry) => typeof entry !== "string" || entry.trim().length === 0)
  ) {
    throw new SmithersError("INVALID_INPUT", `Approval ${id} ${field} must be an array of non-empty strings.`);
  }
  return value;
}
/**
 * @param {ApprovalAutoApprove[keyof ApprovalAutoApprove]} callback
 * @param {import("@smthrs/driver").SmithersCtx<unknown> | null} ctx
 * @returns {boolean | undefined}
 */
function evaluateBooleanCallback(callback, ctx) {
  if (typeof callback !== "function") {
    return undefined;
  }
  return Boolean(/** @type {(ctx: import("@smthrs/driver").SmithersCtx<unknown> | null) => boolean} */ (callback)(ctx));
}
/**
 * @template Row
 * @param {ApprovalProps<Row>} props
 * @returns {React.ReactElement | null}
 */
export function Approval(props) {
  if (props.skipIf) return null;
  const smithersContext = props.smithersContext ?? SmithersContext;
  const ctx = React.useContext(smithersContext);
  const mode = props.mode ?? "approve";
  const approvalMode = normalizeMode(mode);
  const options = normalizeOptions(props.options);
  const allowedScopes = validateApprovalRestriction(props.allowedScopes, "allowedScopes", props.id);
  const allowedUsers = validateApprovalRestriction(props.allowedUsers, "allowedUsers", props.id);
  const outputSchema = props.outputSchema ?? (isZodObject(props.output) ? props.output : defaultSchemaForMode(mode));
  if ((mode === "select" || mode === "rank") && (!options || options.length === 0)) {
    throw new SmithersError("APPROVAL_OPTIONS_REQUIRED", `Approval ${props.id} requires options when mode="${mode}".`);
  }
  const conditionMet = props.autoApprove ? evaluateBooleanCallback(props.autoApprove.condition, ctx) : undefined;
  const revertOnMet = props.autoApprove ? evaluateBooleanCallback(props.autoApprove.revertOn, ctx) : undefined;
  const autoApprove = props.autoApprove
    ? {
        ...(typeof props.autoApprove.after === "number" ? { after: props.autoApprove.after } : {}),
        audit: props.autoApprove.audit !== false,
        ...(conditionMet !== undefined ? { conditionMet } : {}),
        ...(revertOnMet !== undefined ? { revertOnMet } : {}),
      }
    : undefined;
  const requestMeta = {
    requestTitle: props.request.title,
    ...(props.request.summary ? { requestSummary: props.request.summary } : {}),
    ...(options ? { approvalOptions: options } : {}),
    ...(allowedScopes?.length ? { approvalAllowedScopes: allowedScopes } : {}),
    ...(allowedUsers?.length ? { approvalAllowedUsers: allowedUsers } : {}),
    ...(autoApprove ? { approvalAutoApprove: autoApprove } : {}),
    ...props.request.metadata,
    ...props.meta,
  };
  /**
   * @returns {Promise<Row>}
   */
  const computeDecision = async () => {
    const runtime = getTaskRuntime();
    if (!runtime) {
      throw new SmithersError(
        "APPROVAL_OUTSIDE_TASK",
        "Approval decisions can only be resolved while a Smithers task is executing.",
      );
    }
    const adapter = new SmithersDb(runtime.db);
    const approval = await adapter.getApproval(runtime.runId, props.id, runtime.iteration);
    const decision = parseJson(approval?.decisionJson);
    if (approvalMode === "select") {
      return {
        selected: typeof decision?.selected === "string" ? decision.selected : "",
        notes: typeof decision?.notes === "string" ? decision.notes : (approval?.note ?? null),
      };
    }
    if (approvalMode === "rank") {
      return {
        ranked: Array.isArray(decision?.ranked) ? decision.ranked.filter((value) => typeof value === "string") : [],
        notes: typeof decision?.notes === "string" ? decision.notes : (approval?.note ?? null),
      };
    }
    return buildDecisionPayload(approval, outputSchema);
  };
  return React.createElement("smithers:task", {
    id: props.id,
    output: props.output,
    outputSchema,
    dependsOn: props.dependsOn,
    needs: props.needs,
    ...(Object.hasOwn(props, "bind") ? { bind: props.bind } : {}),
    needsApproval: true,
    waitAsync: props.async === true,
    approvalMode,
    approvalOnDeny: props.onDeny ?? "fail",
    approvalOptions: options,
    approvalAllowedScopes: allowedScopes,
    approvalAllowedUsers: allowedUsers,
    approvalAutoApprove: autoApprove,
    timeoutMs: props.timeoutMs,
    heartbeatTimeoutMs: props.heartbeatTimeoutMs,
    heartbeatTimeout: props.heartbeatTimeout,
    retries: props.retries,
    retryPolicy: props.retryPolicy,
    continueOnFail: props.continueOnFail,
    cache: props.cache,
    label: props.label ?? props.request.title,
    meta: Object.keys(requestMeta).length > 0 ? requestMeta : undefined,
    __smithersKind: "compute",
    __smithersComputeFn: computeDecision,
  });
}

import type { AgentLike } from "@smthrs/agents/AgentLike";
import type { ApprovalRequest } from "./ApprovalRequest.ts";
import type { RunbookStep } from "./RunbookStep.ts";
import type { OutputTarget } from "./OutputTarget.ts";

export type RunbookProps = {
  id?: string;
  /** Ordered steps to execute. */
  steps: RunbookStep[];
  /** Default agent for steps that don't specify one. */
  defaultAgent?: AgentLike;
  /** Default output schema for step results. */
  stepOutput: OutputTarget;
  /** Template for approval requests on risky/critical steps. */
  approvalRequest?: Partial<ApprovalRequest>;
  /** Behavior when a risky/critical step is denied: "fail" (default) or "skip". */
  onDeny?: "fail" | "skip";
  skipIf?: boolean;
};

import type { AgentLike } from "@smthrs/agents/AgentLike";
import type { OutputTarget } from "./OutputTarget.ts";

export type RunbookStep = {
  /** Unique step identifier. */
  id: string;
  /** Agent for this step (falls back to `defaultAgent`). */
  agent?: AgentLike;
  /** Shell command or instruction for the step. */
  command?: string;
  /** Risk classification: safe auto-executes, risky/critical require approval. */
  risk: "safe" | "risky" | "critical";
  /** Human-readable label for the step. */
  label?: string;
  /** Per-step output schema override. */
  output?: OutputTarget;
};