@smithers-orchestrator/graph 0.23.0 → 0.24.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithers-orchestrator/graph",
-  "version": "0.23.0",
+  "version": "0.24.2",
   "description": "Framework-neutral Smithers workflow graph model and extraction helpers",
   "type": "module",
   "sideEffects": false,
@@ -22,7 +22,7 @@
   "dependencies": {
     "drizzle-orm": "^0.45.2",
     "zod": "^4.3.6",
-    "@smithers-orchestrator/errors": "0.23.0"
+    "@smithers-orchestrator/errors": "0.24.2"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/TaskAspects.ts

@@ -0,0 +1 @@
+export type { TaskAspects } from "./types";

package/src/dom/extract.js

@@ -4,10 +4,10 @@
 // @smithers-type-exports-end
 
 import { resolveStableId } from "@smithers-orchestrator/graph/utils/tree-ids";
-import { isAbsolute, resolve as resolvePath } from "node:path";
 import { getTableName } from "drizzle-orm";
 import { DEFAULT_MERGE_QUEUE_CONCURRENCY, WORKTREE_EMPTY_PATH_ERROR, } from "@smithers-orchestrator/graph/constants";
 import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+import { resolveWorktreePath } from "@smithers-orchestrator/graph/worktree-path";
 
 /** @typedef {import("../ExtractOptions.ts").ExtractOptions} ExtractOptions */
 /** @typedef {import("../ExtractResult.ts").ExtractResult} ExtractResult */
@@ -251,13 +251,7 @@ export function extractFromHost(root, opts) {
             if (!pathVal) {
                 throw new SmithersError("WORKTREE_EMPTY_PATH", WORKTREE_EMPTY_PATH_ERROR);
             }
-            const baseRoot = opts?.baseRootDir;
-            const base = typeof baseRoot === "string" && baseRoot.length > 0
-                ? baseRoot
-                : process.cwd();
-            const normPath = isAbsolute(pathVal)
-                ? resolvePath(pathVal)
-                : resolvePath(base, pathVal);
+            const normPath = resolveWorktreePath(pathVal, { baseRootDir: opts?.baseRootDir });
             const branch = node.rawProps?.branch ? String(node.rawProps.branch) : undefined;
             const baseBranch = node.rawProps?.baseBranch ? String(node.rawProps.baseBranch) : undefined;
             nextWorktreeStack = [...worktreeStack, { id, path: normPath, branch, baseBranch }];
@@ -464,6 +458,7 @@ export function extractFromHost(root, opts) {
                         config: {
                             image: raw.image,
                             env: raw.env,
+                            egress: raw.egress,
                             ports: raw.ports,
                             volumes: raw.volumes,
                             memoryLimit: raw.memoryLimit,
@@ -488,6 +483,7 @@ export function extractFromHost(root, opts) {
                     __sandboxConfig: {
                         image: raw.image,
                         env: raw.env,
+                        egress: raw.egress,
                         ports: raw.ports,
                         volumes: raw.volumes,
                         memoryLimit: raw.memoryLimit,

package/src/extract.js

@@ -1,7 +1,7 @@
-import { isAbsolute, resolve as resolvePath } from "node:path";
 import { getTableName } from "drizzle-orm";
 import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
 import { validateForkSources } from "./validateForkSources.js";
+import { resolveWorktreePath } from "./worktree-path.js";
 /** @typedef {import("./TaskDescriptor.ts").TaskDescriptor} TaskDescriptor */
 /** @typedef {import("./XmlNode.ts").XmlNode} XmlNode */
 /** @typedef {import("./ExtractOptions.ts").ExtractOptions} ExtractOptions */
@@ -248,6 +248,49 @@ function approvalAutoApprove(value) {
             : {}),
     };
 }
+/**
+ * Normalize the `__aspects` element prop attached by `<Task>` into the
+ * `TaskAspects` budget metadata the engine enforces. Only the budget configs
+ * are kept; the render-time accumulator and tracking flags are dropped (the
+ * engine keeps its own durable per-run accumulator and budgets enforce
+ * regardless of tracking).
+ *
+ * @param {unknown} value
+ * @returns {import("./types").TaskAspects | undefined}
+ */
+function aspects(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    const raw = /** @type {Record<string, unknown>} */ (value);
+    /** @type {import("./types").TaskAspects} */
+    const out = {};
+    const token = raw.tokenBudget;
+    if (token && typeof token === "object" && !Array.isArray(token) &&
+        typeof (/** @type {Record<string, unknown>} */ (token).max) === "number") {
+        const t = /** @type {Record<string, unknown>} */ (token);
+        out.tokenBudget = {
+            max: /** @type {number} */ (t.max),
+            ...(typeof t.perTask === "number" ? { perTask: t.perTask } : {}),
+            ...(t.onExceeded === "warn" || t.onExceeded === "skip-remaining" || t.onExceeded === "fail"
+                ? { onExceeded: /** @type {"fail" | "warn" | "skip-remaining"} */ (t.onExceeded) }
+                : {}),
+        };
+    }
+    const latency = raw.latencySlo;
+    if (latency && typeof latency === "object" && !Array.isArray(latency) &&
+        typeof (/** @type {Record<string, unknown>} */ (latency).maxMs) === "number") {
+        const l = /** @type {Record<string, unknown>} */ (latency);
+        out.latencySlo = {
+            maxMs: /** @type {number} */ (l.maxMs),
+            ...(typeof l.perTask === "number" ? { perTask: l.perTask } : {}),
+            ...(l.onExceeded === "warn" || l.onExceeded === "fail"
+                ? { onExceeded: /** @type {"fail" | "warn"} */ (l.onExceeded) }
+                : {}),
+        };
+    }
+    return out.tokenBudget || out.latencySlo ? out : undefined;
+}
 /**
  * @param {"parallel" | "merge-queue"} tag
  * @param {Record<string, unknown>} raw
@@ -364,14 +407,11 @@ export function extractGraph(root, opts) {
             if (!pathVal) {
                 throw new SmithersError("WORKTREE_EMPTY_PATH", WORKTREE_EMPTY_PATH_ERROR);
             }
-            const base = typeof opts?.baseRootDir === "string" && opts.baseRootDir.length > 0
-                ? opts.baseRootDir
-                : process.cwd();
             nextWorktreeStack = [
                 ...ctx.worktreeStack,
                 {
                     id,
-                    path: isAbsolute(pathVal) ? resolvePath(pathVal) : resolvePath(base, pathVal),
+                    path: resolveWorktreePath(pathVal, opts),
                     ...(raw.branch ? { branch: String(raw.branch) } : {}),
                     ...(raw.baseBranch ? { baseBranch: String(raw.baseBranch) } : {}),
                 },
@@ -463,6 +503,7 @@ export function extractGraph(root, opts) {
                     __sandboxConfig: {
                         image: raw.image,
                         env: raw.env,
+                        egress: raw.egress,
                         ports: raw.ports,
                         volumes: raw.volumes,
                         memoryLimit: raw.memoryLimit,
@@ -630,6 +671,7 @@ export function extractGraph(root, opts) {
                 memoryConfig: raw.memory && typeof raw.memory === "object" && !Array.isArray(raw.memory)
                     ? raw.memory
                     : undefined,
+                aspects: aspects(raw.__aspects),
             });
         }
         let elementIndex = 0;

package/src/index.d.ts

@@ -26,9 +26,6 @@ type HostText$1 = {
 type RetryPolicy$1 = {
     backoff?: "fixed" | "linear" | "exponential";
     initialDelayMs?: number;
-    maxDelayMs?: number;
-    multiplier?: number;
-    jitter?: boolean;
 };
 type CachePolicy$1<Ctx = unknown> = {
     by?: (ctx: Ctx) => unknown;
@@ -112,6 +109,18 @@ type ApprovalOption$1 = {
     summary?: string;
     metadata?: Record<string, unknown>;
 };
+type TaskAspects$1 = {
+    tokenBudget?: {
+        max: number;
+        perTask?: number;
+        onExceeded?: "fail" | "warn" | "skip-remaining";
+    };
+    latencySlo?: {
+        maxMs: number;
+        perTask?: number;
+        onExceeded?: "fail" | "warn";
+    };
+};
 type TaskDescriptor$1 = {
     nodeId: string;
     ordinal: number;
@@ -159,6 +168,7 @@ type TaskDescriptor$1 = {
     meta?: Record<string, unknown>;
     scorers?: ScorersMap$1;
     memoryConfig?: TaskMemoryConfig$1;
+    aspects?: TaskAspects$1;
 };
 type WorkflowGraph$2 = {
     readonly xml: XmlNode$1 | null;
@@ -192,6 +202,16 @@ declare function extractGraph(root: HostNode$1 | null, opts?: ExtractOptions$1):
  * @returns {WorkflowGraph}
  */
 declare function extractFromHost(root: HostNode$1 | null, opts?: ExtractOptions$1): WorkflowGraph$1;
+/**
+ * Resolve a <Worktree path> prop exactly the way graph extraction resolves it.
+ *
+ * @param {unknown} path
+ * @param {{ baseRootDir?: string }} [opts]
+ * @returns {string}
+ */
+declare function resolveWorktreePath(path: unknown, opts?: {
+    baseRootDir?: string;
+}): string;
 type ExtractOptions$1 = ExtractOptions$2;
 type HostNode$1 = HostNode$2;
 type WorkflowGraph$1 = WorkflowGraph$2;
@@ -215,6 +235,7 @@ type ScorerBinding = ScorerBinding$1;
 type ScorerFn = ScorerFn$1;
 type ScorerInput = ScorerInput$1;
 type ScorersMap = ScorersMap$1;
+type TaskAspects = TaskAspects$1;
 type TaskDescriptor = TaskDescriptor$1;
 type TaskMemoryConfig = TaskMemoryConfig$1;
 type WorkflowGraph = WorkflowGraph$2;
@@ -222,4 +243,4 @@ type XmlElement = XmlElement$1;
 type XmlNode = XmlNode$1;
 type XmlText = XmlText$1;
 
-export { type AgentLike, type ApprovalOption, type CachePolicy, type ExtractGraph, type ExtractOptions, type GraphSnapshot, type HostElement, type HostNode, type HostText, type MemoryNamespace, type MemoryNamespaceKind, type RetryPolicy, type SamplingConfig, type ScoreResult, type Scorer, type ScorerBinding, type ScorerFn, type ScorerInput, type ScorersMap, type TaskDescriptor, type TaskMemoryConfig, type WorkflowGraph, type XmlElement, type XmlNode, type XmlText, extractFromHost, extractGraph };
+export { type AgentLike, type ApprovalOption, type CachePolicy, type ExtractGraph, type ExtractOptions, type GraphSnapshot, type HostElement, type HostNode, type HostText, type MemoryNamespace, type MemoryNamespaceKind, type RetryPolicy, type SamplingConfig, type ScoreResult, type Scorer, type ScorerBinding, type ScorerFn, type ScorerInput, type ScorersMap, type TaskAspects, type TaskDescriptor, type TaskMemoryConfig, type WorkflowGraph, type XmlElement, type XmlNode, type XmlText, extractFromHost, extractGraph, resolveWorktreePath };

package/src/index.js

@@ -30,3 +30,4 @@
 // @smithers-type-exports-end
 
 export * from "./extract.js";
+export * from "./worktree-path.js";

package/src/types.ts

@@ -32,9 +32,6 @@ export type HostText = {
 export type RetryPolicy = {
   backoff?: "fixed" | "linear" | "exponential";
   initialDelayMs?: number;
-  maxDelayMs?: number;
-  multiplier?: number;
-  jitter?: boolean;
 };
 
 export type CachePolicy<Ctx = unknown> = {
@@ -126,6 +123,26 @@ export type ApprovalOption = {
   metadata?: Record<string, unknown>;
 };
 
+/**
+ * Resolved `<Aspects>` budget configuration that applies to a task, extracted
+ * from the `__aspects` element prop. The engine reads this at task-dispatch
+ * time to enforce per-run token and latency budgets. The render-time
+ * accumulator carried alongside the budgets in the component tree is dropped
+ * here; the engine keeps its own durable accumulator.
+ */
+export type TaskAspects = {
+  tokenBudget?: {
+    max: number;
+    perTask?: number;
+    onExceeded?: "fail" | "warn" | "skip-remaining";
+  };
+  latencySlo?: {
+    maxMs: number;
+    perTask?: number;
+    onExceeded?: "fail" | "warn";
+  };
+};
+
 export type TaskDescriptor = {
   nodeId: string;
   ordinal: number;
@@ -176,6 +193,8 @@ export type TaskDescriptor = {
   scorers?: ScorersMap;
 
   memoryConfig?: TaskMemoryConfig;
+  /** Resolved `<Aspects>` budget configuration enforced by the engine at dispatch. */
+  aspects?: TaskAspects;
 };
 
 export type WorkflowGraph = {

package/src/worktree-path.js

@@ -0,0 +1,24 @@
+import { isAbsolute, resolve } from "node:path";
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+import { WORKTREE_EMPTY_PATH_ERROR } from "./constants.js";
+
+/**
+ * Resolve a <Worktree path> prop exactly the way graph extraction resolves it.
+ *
+ * @param {unknown} path
+ * @param {{ baseRootDir?: string }} [opts]
+ * @returns {string}
+ */
+export function resolveWorktreePath(path, opts) {
+    const pathVal = String(path ?? "").trim();
+    if (!pathVal) {
+        throw new SmithersError("WORKTREE_EMPTY_PATH", WORKTREE_EMPTY_PATH_ERROR);
+    }
+    if (isAbsolute(pathVal)) {
+        return resolve(pathVal);
+    }
+    const base = typeof opts?.baseRootDir === "string" && opts.baseRootDir.length > 0
+        ? opts.baseRootDir
+        : process.cwd();
+    return resolve(base, pathVal);
+}