@smithers-orchestrator/components 0.16.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 William Cory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@smithers-orchestrator/components",
+  "version": "0.16.0",
+  "description": "React components for Smithers workflows",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./*": {
+      "types": "./src/index.d.ts",
+      "import": "./src/*.js",
+      "default": "./src/*.js"
+    }
+  },
+  "files": [
+    "src/"
+  ],
+  "dependencies": {
+    "bippy": "^0.5.32",
+    "react": "^18.3.0 || ^19.0.0",
+    "react-dom": "^18.3.0 || ^19.0.0",
+    "zod": "^4.3.6",
+    "@smithers-orchestrator/agents": "0.16.0",
+    "@smithers-orchestrator/db": "0.16.0",
+    "@smithers-orchestrator/driver": "0.16.0",
+    "@smithers-orchestrator/errors": "0.16.0",
+    "@smithers-orchestrator/memory": "0.16.0",
+    "@smithers-orchestrator/graph": "0.16.0",
+    "@smithers-orchestrator/react-reconciler": "0.16.0",
+    "@smithers-orchestrator/observability": "0.16.0",
+    "@smithers-orchestrator/scheduler": "0.16.0",
+    "@smithers-orchestrator/scorers": "0.16.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "~5.9.3"
+  },
+  "scripts": {
+    "test": "bun test tests",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "tsup --dts-only"
+  }
+}

package/src/SmithersWorkflow.ts

@@ -0,0 +1 @@
+export type { WorkflowDefinition as SmithersWorkflow } from "@smithers-orchestrator/driver/WorkflowDefinition";

package/src/aspects/AspectAccumulator.ts

@@ -0,0 +1,9 @@
+/**
+ * Runtime accumulator for tracked metrics within an Aspects scope.
+ */
+export type AspectAccumulator = {
+	totalTokens: number;
+	totalLatencyMs: number;
+	totalCostUsd: number;
+	taskCount: number;
+};

package/src/aspects/AspectContext.js

@@ -0,0 +1,29 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./AspectAccumulator.ts").AspectAccumulator} AspectAccumulator */
+/** @typedef {import("./AspectContextValue.ts").AspectContextValue} AspectContextValue */
+/** @typedef {import("./CostBudgetConfig.ts").CostBudgetConfig} CostBudgetConfig */
+/** @typedef {import("./LatencySloConfig.ts").LatencySloConfig} LatencySloConfig */
+/** @typedef {import("./TokenBudgetConfig.ts").TokenBudgetConfig} TokenBudgetConfig */
+/** @typedef {import("./TrackingConfig.ts").TrackingConfig} TrackingConfig */
+// @smithers-type-exports-end
+
+import React from "react";
+/**
+ * React context that propagates Aspects configuration down the component tree.
+ * Tasks read from this context to enforce budgets and track metrics.
+ * @type {React.Context<AspectContextValue | null>}
+ */
+export const AspectContext = React.createContext(/** @type {AspectContextValue | null} */ (null));
+AspectContext.displayName = "AspectContext";
+/**
+ * Create a fresh accumulator with zeroed counters.
+ * @returns {AspectAccumulator}
+ */
+export function createAccumulator() {
+    return {
+        totalTokens: 0,
+        totalLatencyMs: 0,
+        totalCostUsd: 0,
+        taskCount: 0,
+    };
+}

package/src/aspects/AspectContextValue.ts

@@ -0,0 +1,16 @@
+import type { TokenBudgetConfig } from "./TokenBudgetConfig.ts";
+import type { LatencySloConfig } from "./LatencySloConfig.ts";
+import type { CostBudgetConfig } from "./CostBudgetConfig.ts";
+import type { TrackingConfig } from "./TrackingConfig.ts";
+import type { AspectAccumulator } from "./AspectAccumulator.ts";
+
+/**
+ * The value provided by AspectContext to descendant components.
+ */
+export type AspectContextValue = {
+	tokenBudget?: TokenBudgetConfig;
+	latencySlo?: LatencySloConfig;
+	costBudget?: CostBudgetConfig;
+	tracking: TrackingConfig;
+	accumulator: AspectAccumulator;
+};

package/src/aspects/CostBudgetConfig.ts

@@ -0,0 +1,9 @@
+/**
+ * Cost budget configuration for Aspects.
+ */
+export type CostBudgetConfig = {
+	/** Maximum total cost in USD across all tasks within the Aspects scope. */
+	maxUsd: number;
+	/** Behavior when the budget is exceeded. Default: "fail". */
+	onExceeded?: "fail" | "warn" | "skip-remaining";
+};

package/src/aspects/LatencySloConfig.ts

@@ -0,0 +1,11 @@
+/**
+ * Latency SLO configuration for Aspects.
+ */
+export type LatencySloConfig = {
+	/** Maximum total latency in milliseconds across all tasks. */
+	maxMs: number;
+	/** Optional per-task latency limit in milliseconds. */
+	perTask?: number;
+	/** Behavior when the SLO is exceeded. Default: "fail". */
+	onExceeded?: "fail" | "warn";
+};

package/src/aspects/TokenBudgetConfig.ts

@@ -0,0 +1,11 @@
+/**
+ * Token budget configuration for Aspects.
+ */
+export type TokenBudgetConfig = {
+	/** Maximum total tokens across all tasks within the Aspects scope. */
+	max: number;
+	/** Optional per-task token limit. */
+	perTask?: number;
+	/** Behavior when the budget is exceeded. Default: "fail". */
+	onExceeded?: "fail" | "warn" | "skip-remaining";
+};

package/src/aspects/TrackingConfig.ts

@@ -0,0 +1,11 @@
+/**
+ * Tracking configuration — which metrics to track.
+ */
+export type TrackingConfig = {
+	/** Track token usage. Default: true. */
+	tokens?: boolean;
+	/** Track latency. Default: true. */
+	latency?: boolean;
+	/** Track cost. Default: true. */
+	cost?: boolean;
+};

package/src/aspects/index.js

@@ -0,0 +1,10 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./AspectAccumulator.ts").AspectAccumulator} AspectAccumulator */
+/** @typedef {import("./AspectContextValue.ts").AspectContextValue} AspectContextValue */
+/** @typedef {import("./CostBudgetConfig.ts").CostBudgetConfig} CostBudgetConfig */
+/** @typedef {import("./LatencySloConfig.ts").LatencySloConfig} LatencySloConfig */
+/** @typedef {import("./TokenBudgetConfig.ts").TokenBudgetConfig} TokenBudgetConfig */
+/** @typedef {import("./TrackingConfig.ts").TrackingConfig} TrackingConfig */
+// @smithers-type-exports-end
+
+export { AspectContext, createAccumulator, } from "./AspectContext.js";

package/src/components/Approval.js

@@ -0,0 +1,211 @@
+// @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 "@smithers-orchestrator/react-reconciler/context";
+import { getTaskRuntime } from "@smithers-orchestrator/driver/task-runtime";
+import { SmithersDb } from "@smithers-orchestrator/db/adapter";
+import { SmithersError } from "@smithers-orchestrator/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: z.string().nullable(),
+    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 {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 {ApprovalAutoApprove[keyof ApprovalAutoApprove]} callback
+ * @param {import("@smithers-orchestrator/driver").SmithersCtx<unknown> | null} ctx
+ * @returns {boolean | undefined}
+ */
+function evaluateBooleanCallback(callback, ctx) {
+    if (typeof callback !== "function") {
+        return undefined;
+    }
+    return Boolean(/** @type {(ctx: import("@smithers-orchestrator/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);
+    if ((mode === "select" || mode === "rank") && (!options || options.length === 0)) {
+        throw new SmithersError("APPROVAL_OPTIONS_REQUIRED", `Approval ${props.id} requires options when mode="${mode}".`);
+    }
+    const autoApprove = props.autoApprove
+        ? {
+            ...(typeof props.autoApprove.after === "number" ? { after: props.autoApprove.after } : {}),
+            audit: props.autoApprove.audit !== false,
+            ...(evaluateBooleanCallback(props.autoApprove.condition, ctx) !== undefined
+                ? { conditionMet: evaluateBooleanCallback(props.autoApprove.condition, ctx) }
+                : {}),
+            ...(evaluateBooleanCallback(props.autoApprove.revertOn, ctx) !== undefined
+                ? { revertOnMet: evaluateBooleanCallback(props.autoApprove.revertOn, ctx) }
+                : {}),
+        }
+        : undefined;
+    const requestMeta = {
+        ...(props.request.summary ? { requestSummary: props.request.summary } : {}),
+        ...(options ? { approvalOptions: options } : {}),
+        ...(props.allowedScopes?.length ? { approvalAllowedScopes: props.allowedScopes } : {}),
+        ...(props.allowedUsers?.length ? { approvalAllowedUsers: props.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 {
+            approved: approval?.status === "approved",
+            note: approval?.note ?? null,
+            decidedBy: approval?.decidedBy ?? null,
+            decidedAt: null,
+        };
+    };
+    return React.createElement("smithers:task", {
+        id: props.id,
+        key: props.key,
+        output: props.output,
+        outputSchema: props.outputSchema ??
+            (isZodObject(props.output) ? props.output : defaultSchemaForMode(mode)),
+        dependsOn: props.dependsOn,
+        needs: props.needs,
+        needsApproval: true,
+        waitAsync: props.async === true,
+        approvalMode,
+        approvalOnDeny: props.onDeny,
+        approvalOptions: options,
+        approvalAllowedScopes: props.allowedScopes,
+        approvalAllowedUsers: props.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,
+    });
+}

package/src/components/ApprovalAutoApprove.ts

@@ -0,0 +1,8 @@
+import type { SmithersCtx } from "@smithers-orchestrator/driver";
+
+export type ApprovalAutoApprove = {
+	after?: number;
+	condition?: ((ctx: SmithersCtx<unknown> | null) => boolean) | (() => boolean);
+	audit?: boolean;
+	revertOn?: ((ctx: SmithersCtx<unknown> | null) => boolean) | (() => boolean);
+};

package/src/components/ApprovalDecision.ts

@@ -0,0 +1,4 @@
+import type { z } from "zod";
+import type { approvalDecisionSchema } from "./Approval.js";
+
+export type ApprovalDecision = z.infer<typeof approvalDecisionSchema>;

package/src/components/ApprovalGate.js

@@ -0,0 +1,45 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./ApprovalGateProps.ts").ApprovalGateProps} ApprovalGateProps */
+// @smithers-type-exports-end
+
+import React from "react";
+import { Branch } from "./Branch.js";
+import { Approval } from "./Approval.js";
+import { Task } from "./Task.js";
+/**
+ * Conditional approval gate. Requires human approval only when `when` is true;
+ * otherwise auto-approves with a static `{ approved: true }` decision.
+ *
+ * Composes Branch + Approval + Task internally.
+ * @param {ApprovalGateProps} props
+ */
+export function ApprovalGate(props) {
+    if (props.skipIf)
+        return null;
+    return React.createElement(Branch, {
+        if: props.when,
+        then: React.createElement(Approval, {
+            id: props.id,
+            output: props.output,
+            request: props.request,
+            onDeny: props.onDeny,
+            timeoutMs: props.timeoutMs,
+            heartbeatTimeoutMs: props.heartbeatTimeoutMs,
+            heartbeatTimeout: props.heartbeatTimeout,
+            retries: props.retries,
+            retryPolicy: props.retryPolicy,
+            continueOnFail: props.continueOnFail,
+        }),
+        else: React.createElement(Task, {
+            id: props.id,
+            output: props.output,
+            label: `${props.request.title} (auto-approved)`,
+            children: {
+                approved: true,
+                note: "auto-approved",
+                decidedBy: null,
+                decidedAt: null,
+            },
+        }),
+    });
+}

package/src/components/ApprovalGateProps.ts

@@ -0,0 +1,22 @@
+import type { ApprovalRequest } from "./ApprovalRequest.ts";
+import type { RetryPolicy } from "@smithers-orchestrator/scheduler/RetryPolicy";
+import type { OutputTarget } from "./OutputTarget.ts";
+
+export type ApprovalGateProps = {
+	id: string;
+	/** Where to persist the approval decision. */
+	output: OutputTarget;
+	/** Human-facing approval request. */
+	request: ApprovalRequest;
+	/** When `true`, approval is required. When `false`, auto-approves. */
+	when: boolean;
+	/** Behavior after denial. */
+	onDeny?: "fail" | "continue" | "skip";
+	skipIf?: boolean;
+	timeoutMs?: number;
+	heartbeatTimeoutMs?: number;
+	heartbeatTimeout?: number;
+	retries?: number;
+	retryPolicy?: RetryPolicy;
+	continueOnFail?: boolean;
+};

package/src/components/ApprovalMode.ts

@@ -0,0 +1 @@
+export type ApprovalMode = "approve" | "select" | "rank";

package/src/components/ApprovalOption.ts

@@ -0,0 +1,6 @@
+export type ApprovalOption = {
+	key: string;
+	label: string;
+	summary?: string;
+	metadata?: Record<string, unknown>;
+};

package/src/components/ApprovalProps.ts

@@ -0,0 +1,42 @@
+import type React from "react";
+import type { z } from "zod";
+import type { SmithersCtx } from "@smithers-orchestrator/driver";
+import type { ApprovalMode } from "./ApprovalMode.ts";
+import type { ApprovalOption } from "./ApprovalOption.ts";
+import type { ApprovalRequest } from "./ApprovalRequest.ts";
+import type { ApprovalAutoApprove } from "./ApprovalAutoApprove.ts";
+import type { ApprovalDecision } from "./ApprovalDecision.ts";
+import type { OutputTarget } from "./OutputTarget.ts";
+
+export type ApprovalProps<Row = ApprovalDecision, Output extends OutputTarget = OutputTarget> = {
+	id: string;
+	mode?: ApprovalMode;
+	options?: ApprovalOption[];
+	/** Where to persist the approval decision. Pass a Zod schema from `outputs` (recommended), a Drizzle table, or a string key. */
+	output: Output;
+	outputSchema?: z.ZodObject<z.ZodRawShape>;
+	request: ApprovalRequest;
+	onDeny?: "fail" | "continue" | "skip";
+	allowedScopes?: string[];
+	allowedUsers?: string[];
+	autoApprove?: ApprovalAutoApprove;
+	/** Do not block unrelated downstream flow while this approval is pending. */
+	async?: boolean;
+	/** 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>;
+	skipIf?: boolean;
+	timeoutMs?: number;
+	heartbeatTimeoutMs?: number;
+	heartbeatTimeout?: number;
+	retries?: number;
+	retryPolicy?: import("@smithers-orchestrator/scheduler/RetryPolicy").RetryPolicy;
+	continueOnFail?: boolean;
+	cache?: import("@smithers-orchestrator/scheduler/CachePolicy").CachePolicy;
+	label?: string;
+	meta?: Record<string, unknown>;
+	key?: string;
+	children?: React.ReactNode;
+	smithersContext?: React.Context<SmithersCtx<unknown> | null>;
+};

package/src/components/ApprovalRanking.ts

@@ -0,0 +1,4 @@
+import type { z } from "zod";
+import type { approvalRankingSchema } from "./Approval.js";
+
+export type ApprovalRanking = z.infer<typeof approvalRankingSchema>;

package/src/components/ApprovalRequest.ts

@@ -0,0 +1,5 @@
+export type ApprovalRequest = {
+	title: string;
+	summary?: string;
+	metadata?: Record<string, unknown>;
+};

package/src/components/ApprovalSelection.ts

@@ -0,0 +1,4 @@
+import type { z } from "zod";
+import type { approvalSelectionSchema } from "./Approval.js";
+
+export type ApprovalSelection = z.infer<typeof approvalSelectionSchema>;

package/src/components/Aspects.js

@@ -0,0 +1,39 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./AspectsProps.ts").AspectsProps} AspectsProps */
+// @smithers-type-exports-end
+
+import React from "react";
+import { AspectContext, createAccumulator, } from "../aspects/AspectContext.js";
+/**
+ * Aspects — declarative cross-cutting concerns for workflow scopes.
+ *
+ * Wraps a section of the workflow tree and propagates token budgets,
+ * latency SLOs, and cost budgets to all descendant Task components
+ * without modifying individual tasks.
+ *
+ * ```tsx
+ * <Aspects tokenBudget={{ max: 100_000, perTask: 20_000, onExceeded: "warn" }}>
+ *   <Task id="step1" ...>...</Task>
+ *   <Task id="step2" ...>...</Task>
+ * </Aspects>
+ * ```
+ * @param {AspectsProps} props
+ */
+export function Aspects(props) {
+    const { tokenBudget, latencySlo, costBudget, tracking, children } = props;
+    // Merge with parent context if nested
+    const parentCtx = React.useContext(AspectContext);
+    const resolvedTracking = {
+        tokens: tracking?.tokens ?? parentCtx?.tracking?.tokens ?? true,
+        latency: tracking?.latency ?? parentCtx?.tracking?.latency ?? true,
+        cost: tracking?.cost ?? parentCtx?.tracking?.cost ?? true,
+    };
+    const value = {
+        tokenBudget: tokenBudget ?? parentCtx?.tokenBudget,
+        latencySlo: latencySlo ?? parentCtx?.latencySlo,
+        costBudget: costBudget ?? parentCtx?.costBudget,
+        tracking: resolvedTracking,
+        accumulator: parentCtx?.accumulator ?? createAccumulator(),
+    };
+    return React.createElement(AspectContext.Provider, { value }, children);
+}

package/src/components/AspectsProps.ts

@@ -0,0 +1,18 @@
+import type React from "react";
+import type { TokenBudgetConfig } from "../aspects/TokenBudgetConfig.ts";
+import type { LatencySloConfig } from "../aspects/LatencySloConfig.ts";
+import type { CostBudgetConfig } from "../aspects/CostBudgetConfig.ts";
+import type { TrackingConfig } from "../aspects/TrackingConfig.ts";
+
+export type AspectsProps = {
+	/** Token budget — max total tokens, optional per-task limit, and exceeded behavior. */
+	tokenBudget?: TokenBudgetConfig;
+	/** Latency SLO — max total latency, optional per-task limit, and exceeded behavior. */
+	latencySlo?: LatencySloConfig;
+	/** Cost budget — max total USD, and exceeded behavior. */
+	costBudget?: CostBudgetConfig;
+	/** Which metrics to track. Defaults to all enabled. */
+	tracking?: TrackingConfig;
+	/** Workflow content these aspects apply to. */
+	children?: React.ReactNode;
+};

package/src/components/Branch.js

@@ -0,0 +1,12 @@
+import React from "react";
+/** @typedef {import("./BranchProps.ts").BranchProps} BranchProps */
+
+/**
+ * @param {BranchProps} props
+ */
+export function Branch(props) {
+    if (props.skipIf)
+        return null;
+    const chosen = props.if ? props.then : (props.else ?? null);
+    return React.createElement("smithers:branch", props, chosen);
+}

package/src/components/BranchProps.ts

@@ -0,0 +1,8 @@
+import type React from "react";
+
+export type BranchProps = {
+	if: boolean;
+	then: React.ReactElement;
+	else?: React.ReactElement | null;
+	skipIf?: boolean;
+};

package/src/components/CategoryConfig.ts

@@ -0,0 +1,10 @@
+import type { AgentLike } from "@smithers-orchestrator/agents/AgentLike";
+import type { OutputTarget } from "./OutputTarget.ts";
+
+export type CategoryConfig = {
+	agent: AgentLike;
+	/** Output schema for this category's route handler. Overrides `routeOutput`. */
+	output?: OutputTarget;
+	/** Optional prompt for the route handler. Receives the classified item. */
+	prompt?: (item: unknown) => string;
+};

package/src/components/CheckConfig.ts

@@ -0,0 +1,8 @@
+import type { AgentLike } from "@smithers-orchestrator/agents/AgentLike";
+
+export type CheckConfig = {
+	id: string;
+	agent?: AgentLike;
+	command?: string;
+	label?: string;
+};