@smithers-orchestrator/components 0.22.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithers-orchestrator/components",
-  "version": "0.22.0",
+  "version": "0.24.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/db": "0.22.0",
-    "@smithers-orchestrator/agents": "0.22.0",
-    "@smithers-orchestrator/errors": "0.22.0",
-    "@smithers-orchestrator/driver": "0.22.0",
-    "@smithers-orchestrator/memory": "0.22.0",
-    "@smithers-orchestrator/graph": "0.22.0",
-    "@smithers-orchestrator/observability": "0.22.0",
-    "@smithers-orchestrator/react-reconciler": "0.22.0",
-    "@smithers-orchestrator/scheduler": "0.22.0"
+    "@smithers-orchestrator/agents": "0.24.0",
+    "@smithers-orchestrator/db": "0.24.0",
+    "@smithers-orchestrator/driver": "0.24.0",
+    "@smithers-orchestrator/errors": "0.24.0",
+    "@smithers-orchestrator/graph": "0.24.0",
+    "@smithers-orchestrator/memory": "0.24.0",
+    "@smithers-orchestrator/scheduler": "0.24.0",
+    "@smithers-orchestrator/react-reconciler": "0.24.0",
+    "@smithers-orchestrator/observability": "0.24.0"
   },
   "devDependencies": {
     "@tanstack/react-query": "^5.99.1",

package/src/aspects/AspectContext.js

@@ -10,7 +10,7 @@
 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.
+ * Budget configuration is declarative metadata and is not enforced yet.
  * @type {React.Context<AspectContextValue | null>}
  */
 export const AspectContext = React.createContext(/** @type {AspectContextValue | null} */ (null));

package/src/aspects/CostBudgetConfig.ts

@@ -1,9 +1,11 @@
 /**
  * Cost budget configuration for Aspects.
+ *
+ * Runtime enforcement is not implemented yet; this is declarative metadata.
  */
 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". */
+	/** Requested future behavior when the budget is exceeded. Default: "fail". */
 	onExceeded?: "fail" | "warn" | "skip-remaining";
 };

package/src/aspects/LatencySloConfig.ts

@@ -1,11 +1,13 @@
 /**
  * Latency SLO configuration for Aspects.
+ *
+ * Runtime enforcement is not implemented yet; this is declarative metadata.
  */
 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". */
+	/** Requested future behavior when the SLO is exceeded. Default: "fail". */
 	onExceeded?: "fail" | "warn";
 };

package/src/aspects/TokenBudgetConfig.ts

@@ -1,11 +1,13 @@
 /**
  * Token budget configuration for Aspects.
+ *
+ * Runtime enforcement is not implemented yet; this is declarative metadata.
  */
 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". */
+	/** Requested future behavior when the budget is exceeded. Default: "fail". */
 	onExceeded?: "fail" | "warn" | "skip-remaining";
 };

package/src/components/Aspects.js

@@ -9,7 +9,8 @@ import { AspectContext, createAccumulator, } from "../aspects/AspectContext.js";
  *
  * 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.
+ * without modifying individual tasks. Runtime budget enforcement is not
+ * implemented yet.
  *
  * ```tsx
  * <Aspects tokenBudget={{ max: 100_000, perTask: 20_000, onExceeded: "warn" }}>

package/src/components/AspectsProps.ts

@@ -5,11 +5,11 @@ 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. */
+	/** Token budget metadata. Runtime enforcement is not implemented yet. */
 	tokenBudget?: TokenBudgetConfig;
-	/** Latency SLO — max total latency, optional per-task limit, and exceeded behavior. */
+	/** Latency SLO metadata. Runtime enforcement is not implemented yet. */
 	latencySlo?: LatencySloConfig;
-	/** Cost budget — max total USD, and exceeded behavior. */
+	/** Cost budget metadata. Runtime enforcement is not implemented yet. */
 	costBudget?: CostBudgetConfig;
 	/** Which metrics to track. Defaults to all enabled. */
 	tracking?: TrackingConfig;

package/src/components/DriftDetector.js

@@ -1,10 +1,34 @@
 import React from "react";
+import { SmithersContext } from "@smithers-orchestrator/react-reconciler/context";
 import { Task } from "./Task.js";
 import { Sequence } from "./Sequence.js";
 import { Branch } from "./Branch.js";
 import { Loop } from "./Ralph.js";
 /** @typedef {import("./DriftDetectorProps.ts").DriftDetectorProps} DriftDetectorProps */
 
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * @param {unknown} comparison
+ * @param {((comparison: unknown) => boolean) | undefined} alertIf
+ * @returns {boolean}
+ */
+function shouldAlert(comparison, alertIf) {
+    if (comparison == null) {
+        return false;
+    }
+    if (alertIf) {
+        return Boolean(alertIf(comparison));
+    }
+    return isRecord(comparison) && comparison.drifted === true;
+}
+
 /**
  * @param {DriftDetectorProps} props
  */
@@ -12,9 +36,9 @@ export function DriftDetector(props) {
     if (props.skipIf)
         return null;
     const prefix = props.id ?? "drift";
-    // Determine if drift was detected from comparison output.
-    // At render time, comparison may not exist yet, so default to false.
-    const drifted = false; // Resolved at runtime via reactive re-render
+    const ctx = React.useContext(SmithersContext);
+    const comparison = ctx?.outputMaybe(props.compareOutput, { nodeId: `${prefix}-compare` });
+    const drifted = shouldAlert(comparison, props.alertIf);
     const captureTask = React.createElement(Task, {
         id: `${prefix}-capture`,
         output: props.captureOutput,

package/src/components/DriftDetectorProps.ts

@@ -15,13 +15,14 @@ export type DriftDetectorProps = {
 	compareOutput: OutputTarget;
 	/** Static baseline data, or a function/agent that fetches it. */
 	baseline: unknown;
-	/** Condition function that determines whether to fire the alert. If omitted, uses the `drifted` field from comparison output. */
+	/** Condition function that determines whether to fire the alert. If omitted, uses `comparison.drifted === true`. */
 	alertIf?: (comparison: unknown) => boolean;
 	/** Element to render when drift is detected (e.g. a Task that sends a notification). */
 	alert?: React.ReactElement;
 	/** If set, wraps the detector in a Loop for periodic polling. */
 	poll?: {
-		intervalMs: number;
+		/** Reserved for future delayed polling; maxPolls currently controls Loop iterations. */
+		intervalMs?: number;
 		maxPolls?: number;
 	};
 	/** Skip the entire component. */

package/src/components/Sandbox.js

@@ -1,5 +1,6 @@
 // @smithers-type-exports-begin
 /** @typedef {import("./SandboxRuntime.ts").SandboxRuntime} SandboxRuntime */
+/** @typedef {import("./SandboxEgressConfig.ts").SandboxEgressConfig} SandboxEgressConfig */
 /** @typedef {import("./SandboxVolumeMount.ts").SandboxVolumeMount} SandboxVolumeMount */
 /** @typedef {import("./SandboxWorkspaceSpec.ts").SandboxWorkspaceSpec} SandboxWorkspaceSpec */
 // @smithers-type-exports-end
@@ -25,6 +26,7 @@ export function Sandbox(props) {
         allowNested: props.allowNested,
         image: props.image,
         env: props.env,
+        egress: props.egress,
         ports: props.ports,
         volumes: props.volumes,
         memoryLimit: props.memoryLimit,

package/src/components/SandboxEgressConfig.ts

@@ -0,0 +1,9 @@
+export type SandboxEgressConfig = {
+	env?: Record<string, string>;
+	httpProxy?: string;
+	httpsProxy?: string;
+	noProxy?: string | string[];
+	caCertPem?: string;
+	caCertPath?: string;
+	secretBindings?: Record<string, string>;
+};

package/src/components/SandboxProps.ts

@@ -6,6 +6,7 @@ import type { OutputTarget } from "./OutputTarget.ts";
 import type { SandboxRuntime } from "./SandboxRuntime.ts";
 import type { SandboxVolumeMount } from "./SandboxVolumeMount.ts";
 import type { SandboxWorkspaceSpec } from "./SandboxWorkspaceSpec.ts";
+import type { SandboxEgressConfig } from "./SandboxEgressConfig.ts";
 
 export type SandboxProps = {
 	id: string;
@@ -25,6 +26,7 @@ export type SandboxProps = {
 	allowNested?: boolean;
 	image?: string;
 	env?: Record<string, string>;
+	egress?: SandboxEgressConfig;
 	ports?: Array<{
 		host: number;
 		container: number;

package/src/components/Task.js

@@ -215,11 +215,16 @@ export function Task(props) {
     const resolvedDeps = deps ? resolveDeps(ctx, deps, rest.needs) : undefined;
     if (deps && resolvedDeps == null) {
         // Deps not yet available — component defers until upstream tasks complete.
-        // This is normal reactive behavior; the task will re-render once deps are ready.
+        // This is normal reactive behavior; the task will re-render once deps are
+        // ready. Record the deferral so the engine can distinguish a transient wait
+        // from a permanent one: a deferral that survives to quiescence means a
+        // dependency that can never resolve (e.g. a deps key that maps to a node id
+        // no task produces), which would otherwise be a silent skip.
+        ctx?.recordDeferredDep?.(props.id, depNodeIds ?? []);
         return null;
     }
-    // Build aspect metadata to attach to the task element so the engine can
-    // enforce budgets and tracking at execution time.
+    // Build aspect metadata to attach to the task element. Budget metadata is
+    // declarative only until runtime enforcement is implemented.
     const aspectMeta = aspectCtx ? buildAspectMeta(aspectCtx) : undefined;
     const agentChain = Array.isArray(agent)
         ? fallbackAgent
@@ -282,8 +287,8 @@ export function Task(props) {
 }
 /**
  * Build the __aspects metadata object from the current AspectContext.
- * This is attached to the smithers:task element props so the engine
- * can read budgets and tracking config at execution time.
+ * This is attached to the smithers:task element props. Budget metadata is not
+ * enforced by the runtime yet.
  * @param {{
  *     tokenBudget?: unknown;
  *     latencySlo?: unknown;

package/src/components/index.js

@@ -51,6 +51,7 @@
 /** @typedef {import("./SagaProps.ts").SagaProps} SagaProps */
 /** @typedef {import("./SagaStepDef.ts").SagaStepDef} SagaStepDef */
 /** @typedef {import("./SagaStepProps.ts").SagaStepProps} SagaStepProps */
+/** @typedef {import("./SandboxEgressConfig.ts").SandboxEgressConfig} SandboxEgressConfig */
 /** @typedef {import("./SandboxProps.ts").SandboxProps} SandboxProps */
 /** @typedef {import("./SandboxRuntime.ts").SandboxRuntime} SandboxRuntime */
 /** @typedef {import("./SandboxVolumeMount.ts").SandboxVolumeMount} SandboxVolumeMount */

package/src/index.d.ts

@@ -135,6 +135,14 @@ type TaskProps$2<Row, Output extends OutputTarget$1 = OutputTarget$1, D extends
     needs?: Record<string, string>;
     /** Render-time typed dependencies. Keys resolve from task ids of the same name, or from matching `needs` entries. */
     deps?: D;
+    /**
+     * Start this agent task from a copy of another task's final agent session context.
+     * The fork source becomes an implicit dependency: this task waits for it to complete,
+     * then copies its conversation snapshot into a fresh, independent session and submits
+     * its own prompt. The source is never mutated. Inside a `<Loop>`, resolves to the
+     * latest completed snapshot for that task id. Requires an agent task.
+     */
+    fork?: string;
     skipIf?: boolean;
     needsApproval?: boolean;
     /** When paired with `needsApproval`, do not block unrelated downstream flow while the approval is pending. */
@@ -309,6 +317,16 @@ type SandboxVolumeMount$1 = {
 
 type SandboxRuntime$1 = "bubblewrap" | "docker" | "codeplane";
 
+type SandboxEgressConfig$1 = {
+    env?: Record<string, string>;
+    httpProxy?: string;
+    httpsProxy?: string;
+    noProxy?: string | string[];
+    caCertPem?: string;
+    caCertPath?: string;
+    secretBindings?: Record<string, string>;
+};
+
 type SandboxProps$2 = {
     id: string;
     /** Child workflow definition. If omitted, createSmithers-bound Sandbox wrappers may provide one. */
@@ -327,6 +345,7 @@ type SandboxProps$2 = {
     allowNested?: boolean;
     image?: string;
     env?: Record<string, string>;
+    egress?: SandboxEgressConfig$1;
     ports?: Array<{
         host: number;
         container: number;
@@ -645,13 +664,14 @@ type DriftDetectorProps$2 = {
     compareOutput: OutputTarget$1;
     /** Static baseline data, or a function/agent that fetches it. */
     baseline: unknown;
-    /** Condition function that determines whether to fire the alert. If omitted, uses the `drifted` field from comparison output. */
+    /** Condition function that determines whether to fire the alert. If omitted, uses `comparison.drifted === true`. */
     alertIf?: (comparison: unknown) => boolean;
     /** Element to render when drift is detected (e.g. a Task that sends a notification). */
     alert?: React.ReactElement;
     /** If set, wraps the detector in a Loop for periodic polling. */
     poll?: {
-        intervalMs: number;
+        /** Reserved for future delayed polling; maxPolls currently controls Loop iterations. */
+        intervalMs?: number;
         maxPolls?: number;
     };
     /** Skip the entire component. */
@@ -779,35 +799,41 @@ type BranchProps$2 = {
 
 /**
  * Token budget configuration for Aspects.
+ *
+ * Runtime enforcement is not implemented yet; this is declarative metadata.
  */
 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". */
+    /** Requested future behavior when the budget is exceeded. Default: "fail". */
     onExceeded?: "fail" | "warn" | "skip-remaining";
 };
 
 /**
  * Latency SLO configuration for Aspects.
+ *
+ * Runtime enforcement is not implemented yet; this is declarative metadata.
  */
 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". */
+    /** Requested future behavior when the SLO is exceeded. Default: "fail". */
     onExceeded?: "fail" | "warn";
 };
 
 /**
  * Cost budget configuration for Aspects.
+ *
+ * Runtime enforcement is not implemented yet; this is declarative metadata.
  */
 type CostBudgetConfig = {
     /** Maximum total cost in USD across all tasks within the Aspects scope. */
     maxUsd: number;
-    /** Behavior when the budget is exceeded. Default: "fail". */
+    /** Requested future behavior when the budget is exceeded. Default: "fail". */
     onExceeded?: "fail" | "warn" | "skip-remaining";
 };
 
@@ -824,11 +850,11 @@ type TrackingConfig = {
 };
 
 type AspectsProps$2 = {
-    /** Token budget — max total tokens, optional per-task limit, and exceeded behavior. */
+    /** Token budget metadata. Runtime enforcement is not implemented yet. */
     tokenBudget?: TokenBudgetConfig;
-    /** Latency SLO — max total latency, optional per-task limit, and exceeded behavior. */
+    /** Latency SLO metadata. Runtime enforcement is not implemented yet. */
     latencySlo?: LatencySloConfig;
-    /** Cost budget — max total USD, and exceeded behavior. */
+    /** Cost budget metadata. Runtime enforcement is not implemented yet. */
     costBudget?: CostBudgetConfig;
     /** Which metrics to track. Defaults to all enabled. */
     tracking?: TrackingConfig;
@@ -1394,7 +1420,8 @@ type AspectContextValue = {
  *
  * 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.
+ * without modifying individual tasks. Runtime budget enforcement is not
+ * implemented yet.
  *
  * ```tsx
  * <Aspects tokenBudget={{ max: 100_000, perTask: 20_000, onExceeded: "warn" }}>
@@ -1508,6 +1535,7 @@ type RunbookStep = RunbookStep$1;
 type SagaProps = SagaProps$2;
 type SagaStepDef = SagaStepDef$1;
 type SagaStepProps = SagaStepProps$2;
+type SandboxEgressConfig = SandboxEgressConfig$1;
 type SandboxProps = SandboxProps$2;
 type SandboxRuntime = SandboxRuntime$1;
 type SandboxVolumeMount = SandboxVolumeMount$1;
@@ -1591,4 +1619,4 @@ type XmlElement = _smithers_graph.XmlElement;
 type XmlNode = _smithers_graph.XmlNode;
 type XmlText = _smithers_graph.XmlText;
 
-export { Approval, type ApprovalAutoApprove, type ApprovalDecision, ApprovalGate, type ApprovalGateProps, type ApprovalMode, type ApprovalOption, type ApprovalProps, type ApprovalRanking, type ApprovalRequest, type ApprovalSelection, Aspects, type AspectsProps, Branch, type BranchProps, type CachePolicy, type CategoryConfig, type CheckConfig, CheckSuite, type CheckSuiteProps, ClassifyAndRoute, type ClassifyAndRouteProps, type ColumnDef, ContentPipeline, type ContentPipelineProps, type ContentPipelineStage, ContinueAsNew, type ContinueAsNewProps, Debate, type DebateProps, type DecisionRule, DecisionTable, type DecisionTableProps, type DepsSpec, DriftDetector, type DriftDetectorProps, type EngineDecision, EscalationChain, type EscalationChainProps, type EscalationLevel, type ExtractOptions, GatherAndSynthesize, type GatherAndSynthesizeProps, type HostElement, type HostNode, type HostText, HumanTask, type HumanTaskProps, type InferDeps, type InferOutputEntry, type InferRow, Kanban, type KanbanProps, Loop, type LoopProps, MergeQueue, type MergeQueueProps, Optimizer, type OptimizerProps, type OutputAccessor, type OutputKey, type OutputTarget, Panel, type PanelProps, type PanelistConfig, Parallel, type ParallelProps, Poller, type PollerProps, Ralph, type RalphProps, type RenderContext, type RetryPolicy, ReviewLoop, type ReviewLoopProps, type RunAuthContext, type RunOptions, type RunResult, Runbook, type RunbookProps, type RunbookStep, Saga, type SagaProps, type SagaStepDef, type SagaStepProps, Sandbox, type SandboxProps, type SandboxRuntime, type SandboxVolumeMount, type SandboxWorkspaceSpec, ScanFixVerify, type ScanFixVerifyProps, type SchemaRegistryEntry, type ScorersMap, Sequence, type SequenceProps, Signal, type SignalProps, type SmithersAlertLabels, type SmithersAlertPolicy, type SmithersAlertPolicyDefaults, type SmithersAlertPolicyRule, type SmithersAlertReaction, type SmithersAlertReactionKind, type SmithersAlertReactionRef, type SmithersAlertSeverity, type SmithersCtx, type SmithersErrorCode, type SmithersWorkflow, type SmithersWorkflowDriverOptions, type SmithersWorkflowOptions, type SourceDef, Subflow, type SubflowProps, SuperSmithers, type SuperSmithersProps, Supervisor, type SupervisorProps, Task, type TaskDescriptor, type TaskProps, Timer, type TimerProps, TryCatchFinally, type TryCatchFinallyProps, WaitForEvent, type WaitForEventProps, type WaitReason, Workflow, type WorkflowGraph, type WorkflowProps, type WorkflowRuntime, type WorkflowSession, Worktree, type WorktreeProps, type XmlElement, type XmlNode, type XmlText, approvalDecisionSchema, approvalRankingSchema, approvalSelectionSchema, continueAsNew, markdownComponents, renderMdx, zodSchemaToJsonExample };
+export { Approval, type ApprovalAutoApprove, type ApprovalDecision, ApprovalGate, type ApprovalGateProps, type ApprovalMode, type ApprovalOption, type ApprovalProps, type ApprovalRanking, type ApprovalRequest, type ApprovalSelection, Aspects, type AspectsProps, Branch, type BranchProps, type CachePolicy, type CategoryConfig, type CheckConfig, CheckSuite, type CheckSuiteProps, ClassifyAndRoute, type ClassifyAndRouteProps, type ColumnDef, ContentPipeline, type ContentPipelineProps, type ContentPipelineStage, ContinueAsNew, type ContinueAsNewProps, Debate, type DebateProps, type DecisionRule, DecisionTable, type DecisionTableProps, type DepsSpec, DriftDetector, type DriftDetectorProps, type EngineDecision, EscalationChain, type EscalationChainProps, type EscalationLevel, type ExtractOptions, GatherAndSynthesize, type GatherAndSynthesizeProps, type HostElement, type HostNode, type HostText, HumanTask, type HumanTaskProps, type InferDeps, type InferOutputEntry, type InferRow, Kanban, type KanbanProps, Loop, type LoopProps, MergeQueue, type MergeQueueProps, Optimizer, type OptimizerProps, type OutputAccessor, type OutputKey, type OutputTarget, Panel, type PanelProps, type PanelistConfig, Parallel, type ParallelProps, Poller, type PollerProps, Ralph, type RalphProps, type RenderContext, type RetryPolicy, ReviewLoop, type ReviewLoopProps, type RunAuthContext, type RunOptions, type RunResult, Runbook, type RunbookProps, type RunbookStep, Saga, type SagaProps, type SagaStepDef, type SagaStepProps, Sandbox, type SandboxEgressConfig, type SandboxProps, type SandboxRuntime, type SandboxVolumeMount, type SandboxWorkspaceSpec, ScanFixVerify, type ScanFixVerifyProps, type SchemaRegistryEntry, type ScorersMap, Sequence, type SequenceProps, Signal, type SignalProps, type SmithersAlertLabels, type SmithersAlertPolicy, type SmithersAlertPolicyDefaults, type SmithersAlertPolicyRule, type SmithersAlertReaction, type SmithersAlertReactionKind, type SmithersAlertReactionRef, type SmithersAlertSeverity, type SmithersCtx, type SmithersErrorCode, type SmithersWorkflow, type SmithersWorkflowDriverOptions, type SmithersWorkflowOptions, type SourceDef, Subflow, type SubflowProps, SuperSmithers, type SuperSmithersProps, Supervisor, type SupervisorProps, Task, type TaskDescriptor, type TaskProps, Timer, type TimerProps, TryCatchFinally, type TryCatchFinallyProps, WaitForEvent, type WaitForEventProps, type WaitReason, Workflow, type WorkflowGraph, type WorkflowProps, type WorkflowRuntime, type WorkflowSession, Worktree, type WorktreeProps, type XmlElement, type XmlNode, type XmlText, approvalDecisionSchema, approvalRankingSchema, approvalSelectionSchema, continueAsNew, markdownComponents, renderMdx, zodSchemaToJsonExample };