@smithers-orchestrator/components 0.16.0

package/src/components/Signal.js

@@ -0,0 +1,48 @@
+import React from "react";
+import { z } from "zod";
+import { SmithersContext } from "@smithers-orchestrator/react-reconciler/context";
+import { stripAutoColumns } from "@smithers-orchestrator/db/react-output";
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+import { WaitForEvent } from "./WaitForEvent.js";
+/**
+ * @template Schema
+ * @typedef {import("./SignalProps.ts").SignalProps<Schema>} SignalProps
+ */
+
+/**
+ * @template Schema
+ * @param {SignalProps<Schema>} props
+ */
+export function Signal(props) {
+    if (props.skipIf)
+        return null;
+    const smithersContext = props.smithersContext ?? SmithersContext;
+    const ctx = React.useContext(smithersContext);
+    const waitNode = React.createElement(WaitForEvent, {
+        id: props.id,
+        key: props.key,
+        event: props.id,
+        correlationId: props.correlationId,
+        output: props.schema,
+        outputSchema: props.schema,
+        timeoutMs: props.timeoutMs,
+        onTimeout: props.onTimeout,
+        async: props.async,
+        dependsOn: props.dependsOn,
+        needs: props.needs,
+        label: props.label ?? `signal:${props.id}`,
+        meta: props.meta,
+    });
+    if (!props.children) {
+        return waitNode;
+    }
+    if (!ctx) {
+        throw new SmithersError("CONTEXT_OUTSIDE_WORKFLOW", "Signal children require a workflow context. Build the workflow with createSmithers().");
+    }
+    const signalRow = ctx.outputMaybe(props.schema, { nodeId: props.id });
+    if (signalRow === undefined) {
+        return waitNode;
+    }
+    const signalData = props.schema.parse(stripAutoColumns(signalRow));
+    return React.createElement(React.Fragment, null, waitNode, props.children(signalData));
+}

package/src/components/SignalProps.ts

@@ -0,0 +1,21 @@
+import type React from "react";
+import type { z } from "zod";
+import type { SmithersCtx } from "@smithers-orchestrator/driver";
+
+export type SignalProps<Schema extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>> = {
+	id: string;
+	schema: Schema;
+	correlationId?: string;
+	timeoutMs?: number;
+	onTimeout?: "fail" | "skip" | "continue";
+	/** Do not block unrelated downstream flow while waiting for the signal. */
+	async?: boolean;
+	skipIf?: boolean;
+	dependsOn?: string[];
+	needs?: Record<string, string>;
+	label?: string;
+	meta?: Record<string, unknown>;
+	key?: string;
+	children?: (data: z.infer<Schema>) => React.ReactNode;
+	smithersContext?: React.Context<SmithersCtx<unknown> | null>;
+};

package/src/components/SourceDef.ts

@@ -0,0 +1,12 @@
+import type React from "react";
+import type { AgentLike } from "@smithers-orchestrator/agents/AgentLike";
+import type { OutputTarget } from "./OutputTarget.ts";
+
+export type SourceDef = {
+	agent: AgentLike;
+	/** Prompt for this source. A string or ReactNode. */
+	prompt?: string;
+	/** Output schema for this specific source. Overrides `gatherOutput`. */
+	output?: OutputTarget;
+	children?: React.ReactNode;
+};

package/src/components/Subflow.js

@@ -0,0 +1,32 @@
+import React from "react";
+/** @typedef {import("./SubflowProps.ts").SubflowProps} SubflowProps */
+
+/**
+ * @param {SubflowProps} props
+ */
+export function Subflow(props) {
+    if (props.skipIf)
+        return null;
+    return React.createElement("smithers:subflow", {
+        id: props.id,
+        key: props.key,
+        workflow: props.workflow,
+        input: props.input,
+        mode: props.mode ?? "childRun",
+        output: props.output,
+        timeoutMs: props.timeoutMs,
+        heartbeatTimeoutMs: props.heartbeatTimeoutMs,
+        heartbeatTimeout: props.heartbeatTimeout,
+        retries: props.retries,
+        retryPolicy: props.retryPolicy,
+        continueOnFail: props.continueOnFail,
+        cache: props.cache,
+        dependsOn: props.dependsOn,
+        needs: props.needs,
+        label: props.label ?? props.id,
+        meta: props.meta,
+        __smithersSubflowWorkflow: props.workflow,
+        __smithersSubflowInput: props.input,
+        __smithersSubflowMode: props.mode ?? "childRun",
+    });
+}

package/src/components/SubflowProps.ts

@@ -0,0 +1,33 @@
+import type React from "react";
+import type { CachePolicy } from "@smithers-orchestrator/scheduler/CachePolicy";
+import type { RetryPolicy } from "@smithers-orchestrator/scheduler/RetryPolicy";
+import type { SmithersWorkflow } from "../SmithersWorkflow.ts";
+import type { OutputTarget } from "./OutputTarget.ts";
+
+export type SubflowProps = {
+	id: string;
+	/** The child workflow definition. */
+	workflow: SmithersWorkflow<unknown>;
+	/** Input to pass to the child workflow. */
+	input?: unknown;
+	/** `"childRun"` gets its own DB row/run; `"inline"` embeds in parent. */
+	mode?: "childRun" | "inline";
+	/** Where to store the subflow's result. */
+	output: OutputTarget;
+	skipIf?: boolean;
+	timeoutMs?: number;
+	heartbeatTimeoutMs?: number;
+	heartbeatTimeout?: number;
+	retries?: number;
+	retryPolicy?: RetryPolicy;
+	continueOnFail?: boolean;
+	cache?: CachePolicy;
+	/** Explicit dependency on other task node IDs. */
+	dependsOn?: string[];
+	/** Named dependencies on other tasks. Keys become context keys, values are task node IDs. */
+	needs?: Record<string, string>;
+	label?: string;
+	meta?: Record<string, unknown>;
+	key?: string;
+	children?: React.ReactNode;
+};

package/src/components/SuperSmithers.js

@@ -0,0 +1,102 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./SuperSmithersProps.ts").SuperSmithersProps} SuperSmithersProps */
+// @smithers-type-exports-end
+
+import React from "react";
+/**
+ * SuperSmithers — a workflow wrapper that reads and modifies source code
+ * to intervene via hot reload. Takes a markdown strategy doc and an agent
+ * that decides what to change.
+ *
+ * Only meaningful in hot-reload mode: the agent reads source files, proposes
+ * modifications, and (unless `dryRun` is set) writes them to disk, triggering
+ * the hot reload system to pick up the changes.
+ *
+ * Internally expands to a sequence of tasks:
+ * 1. Agent reads the strategy doc and target files
+ * 2. Agent proposes modifications
+ * 3. (If not dryRun) Compute task writes modifications to disk
+ * 4. Agent generates a report of what changed
+ *
+ * ```tsx
+ * <SuperSmithers
+ *   id="refactor"
+ *   strategy={strategyMd}
+ *   agent={codeAgent}
+ *   targetFiles={["src/**\/*.ts"]}
+ *   reportOutput={outputs.report}
+ * />
+ * ```
+ * @param {SuperSmithersProps} props
+ */
+export function SuperSmithers(props) {
+    const { id: idPrefix, strategy, agent, targetFiles, reportOutput, dryRun, skipIf, } = props;
+    if (skipIf)
+        return null;
+    const prefix = idPrefix ?? "super-smithers";
+    // Task 1: Read strategy and target files
+    const readTaskId = `${prefix}-read`;
+    const readOutput = reportOutput ?? "super-smithers-read";
+    const strategyText = typeof strategy === "string" ? strategy : undefined;
+    const strategyElement = typeof strategy !== "string" ? strategy : undefined;
+    const readPrompt = strategyText
+        ? `You are a code intervention agent.\n\n## Strategy\n\n${strategyText}\n\n## Target Files\n\n${targetFiles?.length ? targetFiles.join(", ") : "All files in the project"}\n\nRead the target files and understand the codebase. Identify what changes are needed according to the strategy.`
+        : undefined;
+    const readChildren = strategyElement
+        ? React.createElement(React.Fragment, null, strategyElement, React.createElement("p", null, `Target files: ${targetFiles?.length ? targetFiles.join(", ") : "All files in the project"}`))
+        : readPrompt;
+    const readTask = React.createElement("smithers:task", {
+        id: readTaskId,
+        output: readOutput,
+        agent,
+        __smithersKind: "agent",
+    }, readChildren);
+    // Task 2: Propose modifications
+    const proposeTaskId = `${prefix}-propose`;
+    const proposeOutput = reportOutput ?? "super-smithers-propose";
+    const proposeTask = React.createElement("smithers:task", {
+        id: proposeTaskId,
+        output: proposeOutput,
+        agent,
+        dependsOn: [readTaskId],
+        __smithersKind: "agent",
+    }, "Based on your analysis, propose specific code modifications. " +
+        "For each file, provide the exact changes needed as a list of edits. " +
+        "Include the file path, the original code, and the replacement code for each change. " +
+        (dryRun ? "This is a DRY RUN — do not apply changes, only report them." : ""));
+    // Task 3: Apply modifications (only if not dryRun)
+    const applyTaskId = `${prefix}-apply`;
+    const applyOutput = reportOutput ?? "super-smithers-apply";
+    const applyTask = !dryRun
+        ? React.createElement("smithers:task", {
+            id: applyTaskId,
+            output: applyOutput,
+            dependsOn: [proposeTaskId],
+            __smithersKind: "compute",
+            __smithersComputeFn: async () => {
+                // The compute function has access to the proposed modifications
+                // from the previous task via the engine context. The actual file
+                // writes trigger the hot reload system.
+                return { applied: true };
+            },
+        }, null)
+        : null;
+    // Task 4: Generate report
+    const reportTaskId = `${prefix}-report`;
+    const finalOutput = reportOutput ?? "super-smithers-report";
+    const reportTask = React.createElement("smithers:task", {
+        id: reportTaskId,
+        output: finalOutput,
+        agent,
+        dependsOn: dryRun ? [proposeTaskId] : [applyTaskId],
+        __smithersKind: "agent",
+    }, `Generate a summary report of the intervention. ` +
+        `Describe what was analyzed, what changes were ${dryRun ? "proposed (dry run)" : "applied"}, ` +
+        `and any observations or warnings.`);
+    // Wrap all tasks in a sequence
+    const sequenceChildren = [readTask, proposeTask];
+    if (applyTask)
+        sequenceChildren.push(applyTask);
+    sequenceChildren.push(reportTask);
+    return React.createElement("smithers:sequence", { id: prefix }, ...sequenceChildren);
+}

package/src/components/SuperSmithersProps.ts

@@ -0,0 +1,20 @@
+import type React from "react";
+import type { AgentLike } from "@smithers-orchestrator/agents/AgentLike";
+import type { OutputTarget } from "./OutputTarget.ts";
+
+export type SuperSmithersProps = {
+	/** Optional ID prefix for all generated task IDs. */
+	id?: string;
+	/** Markdown string or MDX component describing the intervention strategy. */
+	strategy: string | React.ReactElement;
+	/** Agent that reads code and decides modifications. */
+	agent: AgentLike;
+	/** Glob patterns of files the agent can modify. */
+	targetFiles?: string[];
+	/** Output schema for the intervention report (Zod object). */
+	reportOutput?: OutputTarget;
+	/** If true, reports changes without applying them. */
+	dryRun?: boolean;
+	/** Standard skip predicate. */
+	skipIf?: boolean;
+};

package/src/components/Supervisor.js

@@ -0,0 +1,86 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./SupervisorProps.ts").SupervisorProps} SupervisorProps */
+// @smithers-type-exports-end
+
+import React from "react";
+import { Sequence } from "./Sequence.js";
+import { Task } from "./Task.js";
+import { Parallel } from "./Parallel.js";
+import { Loop } from "./Ralph.js";
+import { Worktree } from "./Worktree.js";
+/**
+ * <Supervisor> — Boss plans, delegates to parallel workers, reviews, re-delegates failures.
+ *
+ * Composes: Sequence → [plan Task, Loop(until allDone) [Parallel worker Tasks, review Task], final Task]
+ * @param {SupervisorProps} props
+ */
+export function Supervisor(props) {
+    if (props.skipIf)
+        return null;
+    const prefix = props.id ?? "supervisor";
+    const maxIterations = props.maxIterations ?? 3;
+    const maxConcurrency = props.maxConcurrency ?? 5;
+    const useWorktrees = props.useWorktrees ?? false;
+    const workerNames = Object.keys(props.workers);
+    // Build a worker Task element for each worker type.
+    // At render time the runtime resolves which tasks are active based on
+    // the plan output; here we declare one slot per worker type.
+    const workerElements = workerNames.map((workerType) => {
+        const workerId = `${prefix}-worker-${workerType}`;
+        const workerTask = React.createElement(Task, {
+            key: workerId,
+            id: workerId,
+            output: props.workerOutput,
+            agent: props.workers[workerType],
+            continueOnFail: true,
+            needs: { plan: `${prefix}-plan` },
+            label: `Worker: ${workerType}`,
+            children: `Execute tasks assigned to worker type "${workerType}". Refer to the plan for your specific instructions.`,
+        });
+        if (useWorktrees) {
+            return React.createElement(Worktree, {
+                key: workerId,
+                path: `.worktrees/${workerId}`,
+                branch: `worker/${workerId}`,
+            }, workerTask);
+        }
+        return workerTask;
+    });
+    // Parallel worker execution
+    const parallelWorkers = React.createElement(Parallel, { maxConcurrency }, ...workerElements);
+    // Boss review Task
+    const reviewTask = React.createElement(Task, {
+        id: `${prefix}-review`,
+        output: props.reviewOutput,
+        agent: props.boss,
+        needs: { plan: `${prefix}-plan` },
+        label: "Supervisor review",
+        children: "Review worker results. Set allDone to true if all tasks are satisfactory. List retriable task IDs in retriable[] if any need re-doing.",
+    });
+    // Loop body: parallel workers then review
+    const loopBody = React.createElement(Sequence, null, parallelWorkers, reviewTask);
+    // Loop: repeat until boss says allDone (runtime resolves `until` reactively)
+    const delegateLoop = React.createElement(Loop, {
+        id: `${prefix}-loop`,
+        until: false, // runtime re-evaluates reactively based on review output
+        maxIterations,
+        onMaxReached: "return-last",
+    }, loopBody);
+    // Boss plan Task
+    const planTask = React.createElement(Task, {
+        id: `${prefix}-plan`,
+        output: props.planOutput,
+        agent: props.boss,
+        label: "Supervisor plan",
+        children: props.children,
+    });
+    // Final summary Task
+    const finalTask = React.createElement(Task, {
+        id: `${prefix}-final`,
+        output: props.finalOutput,
+        needs: { review: `${prefix}-review`, plan: `${prefix}-plan` },
+        label: "Supervisor summary",
+        children: "Summarize the overall results from all delegation cycles.",
+    });
+    return React.createElement(Sequence, null, planTask, delegateLoop, finalTask);
+}

package/src/components/SupervisorProps.ts

@@ -0,0 +1,28 @@
+import type React from "react";
+import type { AgentLike } from "@smithers-orchestrator/agents/AgentLike";
+import type { OutputTarget } from "./OutputTarget.ts";
+
+export type SupervisorProps = {
+	id?: string;
+	/** Agent that plans, delegates, and reviews worker results. */
+	boss: AgentLike;
+	/** Map of worker type names to agents (e.g., { coder, tester, docs }). */
+	workers: Record<string, AgentLike>;
+	/** Output schema for the boss's plan. Must include `tasks: Array<{ id, workerType, instructions }>`. */
+	planOutput: OutputTarget;
+	/** Output schema for individual worker results. */
+	workerOutput: OutputTarget;
+	/** Output schema for the boss's review. Must include `allDone: boolean` and `retriable: string[]`. */
+	reviewOutput: OutputTarget;
+	/** Output schema for the final summary. */
+	finalOutput: OutputTarget;
+	/** Max delegate-review cycles (default 3). */
+	maxIterations?: number;
+	/** Max parallel workers (default 5). */
+	maxConcurrency?: number;
+	/** Whether each worker gets its own git worktree (default false). */
+	useWorktrees?: boolean;
+	skipIf?: boolean;
+	/** Goal/prompt for the boss agent. */
+	children: string | React.ReactNode;
+};