@smithers-orchestrator/components 0.24.2 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithers-orchestrator/components",
-  "version": "0.24.2",
+  "version": "0.25.0",
   "description": "React components for Smithers workflows",
   "type": "module",
   "sideEffects": false,
@@ -24,15 +24,15 @@
     "react": "^19.2.5",
     "react-dom": "^19.2.5",
     "zod": "^4.3.6",
-    "@smithers-orchestrator/agents": "0.24.2",
-    "@smithers-orchestrator/db": "0.24.2",
-    "@smithers-orchestrator/graph": "0.24.2",
-    "@smithers-orchestrator/errors": "0.24.2",
-    "@smithers-orchestrator/driver": "0.24.2",
-    "@smithers-orchestrator/observability": "0.24.2",
-    "@smithers-orchestrator/react-reconciler": "0.24.2",
-    "@smithers-orchestrator/scheduler": "0.24.2",
-    "@smithers-orchestrator/memory": "0.24.2"
+    "@smithers-orchestrator/agents": "0.25.0",
+    "@smithers-orchestrator/driver": "0.25.0",
+    "@smithers-orchestrator/db": "0.25.0",
+    "@smithers-orchestrator/errors": "0.25.0",
+    "@smithers-orchestrator/memory": "0.25.0",
+    "@smithers-orchestrator/scheduler": "0.25.0",
+    "@smithers-orchestrator/observability": "0.25.0",
+    "@smithers-orchestrator/graph": "0.25.0",
+    "@smithers-orchestrator/react-reconciler": "0.25.0"
   },
   "devDependencies": {
     "@tanstack/react-query": "^5.99.1",

package/src/components/Approval.js

@@ -21,7 +21,10 @@ import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
 
 export const approvalDecisionSchema = z.object({
     approved: z.boolean(),
-    note: z.string().nullable(),
+    // `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(),
 });
@@ -70,6 +73,25 @@ function defaultSchemaForMode(mode) {
             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"}
@@ -120,6 +142,8 @@ export function Approval(props) {
     const mode = props.mode ?? "approve";
     const approvalMode = normalizeMode(mode);
     const options = normalizeOptions(props.options);
+    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}".`);
     }
@@ -175,19 +199,13 @@ export function Approval(props) {
                     : approval?.note ?? null,
             };
         }
-        return {
-            approved: approval?.status === "approved",
-            note: approval?.note ?? null,
-            decidedBy: approval?.decidedBy ?? null,
-            decidedAt: approval?.decidedAtMs != null ? new Date(approval.decidedAtMs).toISOString() : null,
-        };
+        return buildDecisionPayload(approval, outputSchema);
     };
     return React.createElement("smithers:task", {
         id: props.id,
         key: props.key,
         output: props.output,
-        outputSchema: props.outputSchema ??
-            (isZodObject(props.output) ? props.output : defaultSchemaForMode(mode)),
+        outputSchema,
         dependsOn: props.dependsOn,
         needs: props.needs,
         needsApproval: true,

package/src/components/Branch.js

@@ -1,12 +1,24 @@
 import React from "react";
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
 /** @typedef {import("./BranchProps.ts").BranchProps} BranchProps */
 
 /**
  * @param {BranchProps} props
  */
 export function Branch(props) {
+    // <Branch> resolves its subtree from the `then`/`else` props; any JSX children
+    // would be silently dropped, removing those tasks from the graph with no
+    // feedback. Fail fast instead. (Checked before skipIf so a stray-children
+    // mistake still surfaces even on a skipped branch.)
+    if (props.children !== undefined && props.children !== null) {
+        throw new SmithersError("INVALID_INPUT", `<Branch> does not take children. Use the "then" and "else" props instead, e.g. ` +
+            `<Branch if={cond} then={<Task .../>} else={<Task .../>} />. ` +
+            `Children passed to <Branch> are silently ignored and would drop those tasks from the graph.`);
+    }
     if (props.skipIf)
         return null;
     const chosen = props.if ? props.then : (props.else ?? null);
-    return React.createElement("smithers:branch", props, chosen);
+    // The branch is resolved to `chosen` at render time, so the host element
+    // carries no props of its own (align with the sanitizing structural components).
+    return React.createElement("smithers:branch", {}, chosen);
 }

package/src/components/BranchProps.ts

@@ -5,4 +5,10 @@ export type BranchProps = {
 	then: React.ReactElement;
 	else?: React.ReactElement | null;
 	skipIf?: boolean;
+	/**
+	 * `<Branch>` resolves its subtree from `then`/`else`; it takes no children.
+	 * Typed as `never` so passing JSX children is a compile-time error (the
+	 * runtime also throws — children would otherwise be silently dropped).
+	 */
+	children?: never;
 };

package/src/components/Panel.js

@@ -56,7 +56,7 @@ export function Panel(props) {
         ? `\n\nStrategy: VOTE. Count how many panelists agree. ${minAgree ? `Minimum agreement required: ${minAgree}.` : ""}`
         : strategy === "consensus"
             ? `\n\nStrategy: CONSENSUS. All panelists must converge. ${minAgree ? `Minimum agreement required: ${minAgree}.` : ""}`
-            : `\n\nStrategy: SYNTHESIZE. Combine all panelist outputs into a single coherent result.`;
+            : `\n\nStrategy: SYNTHESIZE. Combine all panelist outputs into a single coherent result. Preserve each panelist's concrete, grounded findings verbatim (specific file paths, line numbers, identifiers, prior-PR references, and what already exists); reconcile disagreements with evidence. Do not over-generalize, drop specifics, or change the scope the panelists analyzed.`;
     const moderatorChildren = `Synthesize the following panelist outputs.${strategyPrompt}`;
     const moderatorTask = React.createElement(Task, {
         id: `${prefix}-moderator`,

package/src/components/Ralph.js

@@ -11,7 +11,16 @@ import React from "react";
 export function Loop(props) {
     if (props.skipIf)
         return null;
-    return React.createElement("smithers:ralph", props, props.children);
+    // Sanitize to the loop's host props (align with other structural components);
+    // key/skipIf are React/control props and children are passed separately.
+    const next = {
+        id: props.id,
+        until: props.until,
+        maxIterations: props.maxIterations,
+        onMaxReached: props.onMaxReached,
+        continueAsNewEvery: props.continueAsNewEvery,
+    };
+    return React.createElement("smithers:ralph", next, props.children);
 }
 /** @deprecated Use `Loop` instead. */
 export const Ralph = Loop;

package/src/components/Saga.js

@@ -4,14 +4,18 @@
 // @smithers-type-exports-end
 
 import React from "react";
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
 import { forceContinueOnFail } from "./control-flow-utils.js";
 /** @typedef {import("./SagaStepProps.ts").SagaStepProps} SagaStepProps */
 
 /**
+ * Declarative marker for a Saga step. Exported as a value so `import { SagaStep }`
+ * works; also available as `<Saga.Step>`.
+ *
  * @param {SagaStepProps} _props
  * @returns {React.ReactElement | null}
  */
-function SagaStep(_props) {
+export function SagaStep(_props) {
     // SagaStep is a declarative marker — the Saga component reads its props
     // directly from the children array. It does not render on its own.
     return null;
@@ -39,7 +43,8 @@ export function Saga(props) {
         const childArr = React.Children.toArray(children);
         for (const child of childArr) {
             if (React.isValidElement(child) &&
-                (child.type === SagaStep || child.type.__isSagaStep)) {
+                (child.type === SagaStep ||
+                    (typeof child.type === "function" && child.type.__isSagaStep))) {
                 const stepProps = child.props;
                 resolvedSteps.push({
                     id: stepProps.id,
@@ -62,9 +67,15 @@ export function Saga(props) {
     const actionChildren = resolvedSteps.map((step) => React.cloneElement(forceContinueOnFail(step.action), {
         key: `saga-action-${step.id}`,
     }));
-    const compensationChildren = resolvedSteps.map((step) => React.cloneElement(step.compensation, {
-        key: `saga-compensation-${step.id}`,
-    }));
+    const compensationChildren = resolvedSteps.map((step) => {
+        if (!React.isValidElement(step.compensation)) {
+            throw new SmithersError("INVALID_INPUT", `<Saga id="${id}"> step "${step.id}" has an invalid compensation. Each step needs a single ` +
+                `element (e.g. a <Task/>) that undoes its action; a missing or inert compensation leaves dirty state on rollback.`);
+        }
+        return React.cloneElement(step.compensation, {
+            key: `saga-compensation-${step.id}`,
+        });
+    });
     // Store compensation elements on the host props for the engine.
     sagaProps.__sagaCompensations = resolvedSteps.reduce((acc, step) => {
         acc[step.id] = step.compensation;

package/src/components/Sequence.js

@@ -7,5 +7,7 @@ import React from "react";
 export function Sequence(props) {
     if (props.skipIf)
         return null;
-    return React.createElement("smithers:sequence", props, props.children);
+    // Sequence carries no host props of its own; pass an empty bag (align with
+    // the sanitizing structural components) so control props don't leak through.
+    return React.createElement("smithers:sequence", {}, props.children);
 }

package/src/components/Sidecar.js

@@ -0,0 +1,68 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./SidecarProps.ts").SidecarProps} SidecarProps */
+// @smithers-type-exports-end
+
+import React from "react";
+import { Parallel } from "./Parallel.js";
+import { Task } from "./Task.js";
+
+/**
+ * Runs a primary task and a cheap shadow task over the same prompt.
+ *
+ * The primary task keeps the component id so downstream `needs` can consume it.
+ * The sidecar task is continue-on-fail and writes its own scorer rows.
+ *
+ * @param {SidecarProps} props
+ */
+export function Sidecar(props) {
+	if (props.skipIf) return null;
+	const {
+		id = "sidecar",
+		agent,
+		sidecar,
+		output,
+		sidecarOutput,
+		scorers,
+		prompt,
+		input,
+		maxConcurrency,
+		groundTruth,
+		context,
+		primaryLabel,
+		sidecarLabel,
+		children,
+	} = props;
+	const promptNode = prompt ?? input ?? children;
+	const shadowId = `${id}-sidecar`;
+	return React.createElement(
+		Parallel,
+		{ id: `${id}-parallel`, maxConcurrency },
+		React.createElement(
+			Task,
+			{
+				id,
+				output,
+				agent,
+				scorers,
+				groundTruth,
+				context,
+				label: primaryLabel,
+			},
+			promptNode,
+		),
+		React.createElement(
+			Task,
+			{
+				id: shadowId,
+				output: sidecarOutput ?? output,
+				agent: sidecar,
+				continueOnFail: true,
+				scorers,
+				groundTruth,
+				context,
+				label: sidecarLabel,
+			},
+			promptNode,
+		),
+	);
+}

package/src/components/SidecarDelta.ts

@@ -0,0 +1,6 @@
+export type SidecarDelta = {
+	primaryScore: number | null;
+	sidecarScore: number | null;
+	delta: number | null;
+	cheaperWins: boolean;
+};

package/src/components/SidecarProps.ts

@@ -0,0 +1,22 @@
+import type React from "react";
+import type { AgentLike } from "@smithers-orchestrator/agents/AgentLike";
+import type { ScorersMap } from "@smithers-orchestrator/graph/types";
+import type { OutputTarget } from "./OutputTarget.ts";
+
+export type SidecarProps = {
+	id?: string;
+	agent: AgentLike;
+	sidecar: AgentLike;
+	output: OutputTarget;
+	sidecarOutput?: OutputTarget;
+	scorers?: ScorersMap;
+	prompt?: string | React.ReactNode;
+	input?: string | React.ReactNode;
+	maxConcurrency?: number;
+	groundTruth?: unknown;
+	context?: unknown;
+	primaryLabel?: string;
+	sidecarLabel?: string;
+	skipIf?: boolean;
+	children?: string | React.ReactNode;
+};

package/src/components/SuperSmithers.js

@@ -14,8 +14,8 @@ import React from "react";
  *
  * 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
+ * 2. (If not dryRun) Agent applies the modifications directly to disk
+ * 3. A compute marker records the apply and triggers the hot-reload system
  * 4. Agent generates a report of what changed
  *
  * ```tsx
@@ -36,7 +36,7 @@ export function SuperSmithers(props) {
     const prefix = idPrefix ?? "super-smithers";
     // Task 1: Read strategy and target files
     const readTaskId = `${prefix}-read`;
-    const readOutput = reportOutput ?? "super-smithers-read";
+    const readOutput = "super-smithers-read";
     const strategyText = typeof strategy === "string" ? strategy : undefined;
     const strategyElement = typeof strategy !== "string" ? strategy : undefined;
     const readPrompt = strategyText
@@ -51,22 +51,26 @@ export function SuperSmithers(props) {
         agent,
         __smithersKind: "agent",
     }, readChildren);
-    // Task 2: Propose modifications
+    // Task 2: Apply the modifications (or, in a dry run, propose them only)
     const proposeTaskId = `${prefix}-propose`;
-    const proposeOutput = reportOutput ?? "super-smithers-propose";
+    const proposeOutput = "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)
+    }, dryRun
+        ? "Based on your analysis, propose specific code modifications. This is a DRY RUN — do NOT modify any files. " +
+            "For each file, provide the exact changes needed as a list of edits: the file path, the original code, and the replacement code."
+        : "Based on your analysis, apply the necessary code modifications directly to the target files using your file-editing tools. " +
+            "Make each edit on disk now. After applying them, list each file you changed with a short description of the change.");
+    // Task 3: Sync marker after the apply agent has written its edits (skipped on
+    // dry runs). The edits themselves are made by the agent in Task 2; this compute
+    // step is a dependency barrier so the report below only runs once the apply
+    // task has settled (and its settled write triggers the hot-reload system).
     const applyTaskId = `${prefix}-apply`;
-    const applyOutput = reportOutput ?? "super-smithers-apply";
+    const applyOutput = "super-smithers-apply";
     const applyTask = !dryRun
         ? React.createElement("smithers:task", {
             id: applyTaskId,
@@ -74,9 +78,6 @@ export function SuperSmithers(props) {
             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)

package/src/components/TaskProps.ts

@@ -54,6 +54,10 @@ export type TaskProps<Row, Output extends OutputTarget = OutputTarget, D extends
 	cache?: CachePolicy;
 	/** Optional scorers to evaluate this task's output after completion. */
 	scorers?: ScorersMap;
+	/** Expected output supplied to scorers that compare against a reference answer. */
+	groundTruth?: unknown;
+	/** Additional source context supplied to scorers such as faithfulnessScorer. */
+	context?: unknown;
 	/** Optional cross-run memory configuration. */
 	memory?: TaskMemoryConfig;
 	/** Request an immediate hijack handoff as soon as the task starts running. */

package/src/components/Workflow.js

@@ -6,5 +6,8 @@ import React from "react";
  * @returns {React.DOMElement<WorkflowProps, Element>}
  */
 export function Workflow(props) {
-    return React.createElement("smithers:workflow", props, props.children);
+    // Sanitize host props (align with other structural components): pass only the
+    // fields the host element carries, not the React children/control props.
+    const next = { name: props.name, cache: props.cache };
+    return React.createElement("smithers:workflow", next, props.children);
 }

package/src/components/computeSidecarDelta.ts

@@ -0,0 +1,57 @@
+import type { SidecarDelta } from "./SidecarDelta.ts";
+
+type RowLike = {
+	nodeId?: string;
+	node_id?: string;
+	scorerId?: string;
+	scorer_id?: string;
+	score?: number;
+	scoredAtMs?: number;
+	scored_at_ms?: number;
+} & Record<string, unknown>;
+
+type ComputeSidecarDeltaOptions = {
+	primaryNodeId: string;
+	sidecarNodeId: string;
+	scorerId?: string;
+};
+
+function getNodeId(row: RowLike): string | undefined {
+	return typeof row.nodeId === "string" ? row.nodeId : typeof row.node_id === "string" ? row.node_id : undefined;
+}
+
+function getScorerId(row: RowLike): string | undefined {
+	return typeof row.scorerId === "string"
+		? row.scorerId
+		: typeof row.scorer_id === "string"
+			? row.scorer_id
+			: undefined;
+}
+
+function getScoredAtMs(row: RowLike): number {
+	const value = row.scoredAtMs ?? row.scored_at_ms;
+	return typeof value === "number" ? value : 0;
+}
+
+function getScore(row: RowLike | undefined): number | null {
+	return typeof row?.score === "number" ? row.score : null;
+}
+
+function latestMatching(rows: RowLike[], nodeId: string, scorerId?: string): RowLike | undefined {
+	return rows
+		.filter((row) => getNodeId(row) === nodeId && (!scorerId || getScorerId(row) === scorerId))
+		.sort((a, b) => getScoredAtMs(b) - getScoredAtMs(a))[0];
+}
+
+export function computeSidecarDelta(rows: RowLike[], opts: ComputeSidecarDeltaOptions): SidecarDelta {
+	const primaryScore = getScore(latestMatching(rows, opts.primaryNodeId, opts.scorerId));
+	const sidecarScore = getScore(latestMatching(rows, opts.sidecarNodeId, opts.scorerId));
+	const delta =
+		primaryScore == null || sidecarScore == null ? null : Number((primaryScore - sidecarScore).toFixed(12));
+	return {
+		primaryScore,
+		sidecarScore,
+		delta,
+		cheaperWins: primaryScore != null && sidecarScore != null && sidecarScore >= primaryScore,
+	};
+}

package/src/components/index.js

@@ -59,6 +59,8 @@
 /** @typedef {import("./ScanFixVerifyProps.ts").ScanFixVerifyProps} ScanFixVerifyProps */
 /** @typedef {import("@smithers-orchestrator/graph/types").ScorersMap} ScorersMap */
 /** @typedef {import("./SequenceProps.ts").SequenceProps} SequenceProps */
+/** @typedef {import("./SidecarDelta.ts").SidecarDelta} SidecarDelta */
+/** @typedef {import("./SidecarProps.ts").SidecarProps} SidecarProps */
 /**
  * @template Schema
  * @typedef {import("./SignalProps.ts").SignalProps<Schema>} SignalProps
@@ -108,6 +110,8 @@ export { ScanFixVerify } from "./ScanFixVerify.js";
 export { Poller } from "./Poller.js";
 export { Supervisor } from "./Supervisor.js";
 export { Runbook } from "./Runbook.js";
+export { Sidecar } from "./Sidecar.js";
+export { computeSidecarDelta } from "./computeSidecarDelta.ts";
 // --- Engine-Backed Primitives ---
 export { Subflow } from "./Subflow.js";
 export { Sandbox } from "./Sandbox.js";
@@ -115,7 +119,7 @@ export { WaitForEvent } from "./WaitForEvent.js";
 export { Signal } from "./Signal.js";
 export { Timer } from "./Timer.js";
 export { HumanTask } from "./HumanTask.js";
-export { Saga } from "./Saga.js";
+export { Saga, SagaStep } from "./Saga.js";
 export { TryCatchFinally } from "./TryCatchFinally.js";
 // --- Core Enhancements ---
 export { Aspects } from "./Aspects.js";