@reactive-agents/compose 0.11.0

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+import { Harness } from '@reactive-agents/core';
+
+interface BudgetLimitOptions {
+    maxTokens?: number;
+    maxCostUSD?: number;
+    /** Per-token cost in USD. Default: 0.000001 (rough frontier estimate). */
+    costPerToken?: number;
+    onTrigger?: 'stop' | 'terminate';
+}
+declare function budgetLimit(options: BudgetLimitOptions): (harness: Harness) => void;
+
+interface TimeoutAfterOptions {
+    wallClock: string | number;
+    onTrigger?: 'stop' | 'terminate';
+}
+declare function timeoutAfter(options: TimeoutAfterOptions): (harness: Harness) => void;
+
+interface MaxIterationsOptions {
+    max: number;
+    onTrigger?: 'stop' | 'terminate';
+}
+declare function maxIterations(options: number | MaxIterationsOptions): (harness: Harness) => void;
+
+interface RequireApprovalForOptions {
+    tools: string[];
+    approver: (ctx: {
+        toolName: string;
+        iteration: number;
+    }) => boolean;
+    onDeny?: 'stop' | 'terminate';
+}
+declare function requireApprovalFor(options: RequireApprovalForOptions): (harness: Harness) => void;
+
+interface WatchdogOptions {
+    noProgressFor: string | number;
+    progressSignal?: 'observation.tool-result';
+    onTrigger?: 'stop' | 'terminate';
+}
+declare function watchdog(options: WatchdogOptions): (harness: Harness) => void;
+
+interface ConfidenceFloorOptions {
+    verifier: number;
+    minSteps?: number;
+    earlyExit?: boolean;
+}
+declare function confidenceFloor(options: ConfidenceFloorOptions): (harness: Harness) => void;
+
+declare const KILLSWITCH_NAMES: readonly ["budgetLimit", "timeoutAfter", "maxIterations", "requireApprovalFor", "watchdog", "confidenceFloor"];
+type KillswitchName = typeof KILLSWITCH_NAMES[number];
+declare const killswitches: {
+    readonly list: () => readonly KillswitchName[];
+};
+
+export { type BudgetLimitOptions, type ConfidenceFloorOptions, type MaxIterationsOptions, type RequireApprovalForOptions, type TimeoutAfterOptions, type WatchdogOptions, budgetLimit, confidenceFloor, killswitches, maxIterations, requireApprovalFor, timeoutAfter, watchdog };

package/dist/index.js

@@ -0,0 +1,151 @@
+// src/killswitches/budget-limit.ts
+function budgetLimit(options) {
+  const { maxTokens, maxCostUSD, costPerToken = 1e-6, onTrigger = "stop" } = options;
+  return (harness) => {
+    harness.before("think", (ctx) => {
+      const tokens = ctx.state.tokens ?? 0;
+      if (maxTokens !== void 0 && tokens >= maxTokens) {
+        return { abort: onTrigger, reason: `budget-limit:tokens:${tokens}/${maxTokens}` };
+      }
+      if (maxCostUSD !== void 0) {
+        const estimatedCost = tokens * costPerToken;
+        if (estimatedCost >= maxCostUSD) {
+          return { abort: onTrigger, reason: `budget-limit:cost:${estimatedCost.toFixed(4)}/${maxCostUSD}` };
+        }
+      }
+      return void 0;
+    });
+  };
+}
+
+// src/killswitches/timeout-after.ts
+function parseMs(wallClock) {
+  if (typeof wallClock === "number") return wallClock;
+  const match = wallClock.match(/^(\d+(?:\.\d+)?)(ms|s|m|h)$/);
+  if (!match) throw new Error(`Invalid wallClock: ${wallClock}`);
+  const [, n, unit] = match;
+  const multipliers = { ms: 1, s: 1e3, m: 6e4, h: 36e5 };
+  return parseFloat(n) * (multipliers[unit] ?? 1e3);
+}
+function timeoutAfter(options) {
+  const ms = parseMs(options.wallClock);
+  const onTrigger = options.onTrigger ?? "stop";
+  return (harness) => {
+    let timedOut = false;
+    let timer;
+    harness.before("bootstrap", () => {
+      timer = setTimeout(() => {
+        timedOut = true;
+      }, ms);
+    });
+    harness.before("think", () => {
+      if (timedOut) {
+        return { abort: onTrigger, reason: `timeout-after:${options.wallClock}` };
+      }
+      return void 0;
+    });
+    harness.after("complete", () => {
+      if (timer !== void 0) clearTimeout(timer);
+    });
+  };
+}
+
+// src/killswitches/max-iterations.ts
+function maxIterations(options) {
+  const max = typeof options === "number" ? options : options.max;
+  const onTrigger = typeof options === "number" ? "stop" : options.onTrigger ?? "stop";
+  return (harness) => {
+    harness.before("think", (ctx) => {
+      if (ctx.iteration >= max) {
+        return { abort: onTrigger, reason: `max-iterations:${max}` };
+      }
+      return void 0;
+    });
+  };
+}
+
+// src/killswitches/require-approval-for.ts
+function requireApprovalFor(options) {
+  const { tools, approver, onDeny = "stop" } = options;
+  const toolSet = new Set(tools);
+  return (harness) => {
+    harness.before("act", (ctx) => {
+      const pendingTools = ctx.state.pendingToolCalls ?? [];
+      for (const call of pendingTools) {
+        if (call.name && toolSet.has(call.name)) {
+          const approved = approver({ toolName: call.name, iteration: ctx.iteration });
+          if (!approved) {
+            return { abort: onDeny, reason: `require-approval-for:denied:${call.name}` };
+          }
+        }
+      }
+      return void 0;
+    });
+  };
+}
+
+// src/killswitches/watchdog.ts
+function parseMs2(s) {
+  const match = s.match(/^(\d+(?:\.\d+)?)(ms|s|m|h)$/);
+  if (!match) throw new Error(`Invalid duration: ${s}`);
+  const [, n, unit] = match;
+  const m = { ms: 1, s: 1e3, m: 6e4, h: 36e5 };
+  return parseFloat(n) * (m[unit] ?? 1e3);
+}
+function watchdog(options) {
+  const ms = typeof options.noProgressFor === "number" ? options.noProgressFor : parseMs2(options.noProgressFor);
+  const onTrigger = options.onTrigger ?? "stop";
+  return (harness) => {
+    let lastProgress = Date.now();
+    harness.tap("observation.tool-result", () => {
+      lastProgress = Date.now();
+    });
+    harness.before("think", () => {
+      const elapsed = Date.now() - lastProgress;
+      if (elapsed >= ms) {
+        return { abort: onTrigger, reason: `watchdog:no-progress-for:${elapsed}ms` };
+      }
+      return void 0;
+    });
+  };
+}
+
+// src/killswitches/confidence-floor.ts
+function confidenceFloor(options) {
+  const { verifier: threshold, minSteps = 1, earlyExit = true } = options;
+  return (harness) => {
+    if (!earlyExit) return;
+    harness.before("verify", (ctx) => {
+      const state = ctx.state;
+      const stepCount = state.steps?.length ?? 0;
+      const score = state.verifierScore ?? 0;
+      if (stepCount >= minSteps && score >= threshold) {
+        return { abort: "stop", reason: `confidence-floor:score:${score}>=${threshold}` };
+      }
+      return void 0;
+    });
+  };
+}
+
+// src/killswitches/registry.ts
+var KILLSWITCH_NAMES = [
+  "budgetLimit",
+  "timeoutAfter",
+  "maxIterations",
+  "requireApprovalFor",
+  "watchdog",
+  "confidenceFloor"
+];
+var killswitches = {
+  list: () => KILLSWITCH_NAMES
+};
+export {
+  budgetLimit,
+  confidenceFloor,
+  killswitches,
+  maxIterations,
+  requireApprovalFor,
+  timeoutAfter,
+  watchdog
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/killswitches/budget-limit.ts","../src/killswitches/timeout-after.ts","../src/killswitches/max-iterations.ts","../src/killswitches/require-approval-for.ts","../src/killswitches/watchdog.ts","../src/killswitches/confidence-floor.ts","../src/killswitches/registry.ts"],"sourcesContent":["import type { Harness } from '@reactive-agents/core';\n\nexport interface BudgetLimitOptions {\n  maxTokens?: number;\n  maxCostUSD?: number;\n  /** Per-token cost in USD. Default: 0.000001 (rough frontier estimate). */\n  costPerToken?: number;\n  onTrigger?: 'stop' | 'terminate';\n}\n\nexport function budgetLimit(options: BudgetLimitOptions): (harness: Harness) => void {\n  const { maxTokens, maxCostUSD, costPerToken = 0.000001, onTrigger = 'stop' } = options;\n  return (harness: Harness) => {\n    harness.before('think', (ctx) => {\n      const tokens = (ctx.state as { tokens?: number }).tokens ?? 0;\n      if (maxTokens !== undefined && tokens >= maxTokens) {\n        return { abort: onTrigger, reason: `budget-limit:tokens:${tokens}/${maxTokens}` };\n      }\n      if (maxCostUSD !== undefined) {\n        const estimatedCost = tokens * costPerToken;\n        if (estimatedCost >= maxCostUSD) {\n          return { abort: onTrigger, reason: `budget-limit:cost:${estimatedCost.toFixed(4)}/${maxCostUSD}` };\n        }\n      }\n      return undefined;\n    });\n  };\n}\n","import type { Harness } from '@reactive-agents/core';\n\nexport interface TimeoutAfterOptions {\n  wallClock: string | number;  // '60s' | '5m' | milliseconds\n  onTrigger?: 'stop' | 'terminate';\n}\n\nfunction parseMs(wallClock: string | number): number {\n  if (typeof wallClock === 'number') return wallClock;\n  const match = wallClock.match(/^(\\d+(?:\\.\\d+)?)(ms|s|m|h)$/);\n  if (!match) throw new Error(`Invalid wallClock: ${wallClock}`);\n  const [, n, unit] = match;\n  const multipliers: Record<string, number> = { ms: 1, s: 1000, m: 60_000, h: 3_600_000 };\n  return parseFloat(n!) * (multipliers[unit!] ?? 1000);\n}\n\nexport function timeoutAfter(options: TimeoutAfterOptions): (harness: Harness) => void {\n  const ms = parseMs(options.wallClock);\n  const onTrigger = options.onTrigger ?? 'stop';\n  return (harness: Harness) => {\n    let timedOut = false;\n    let timer: ReturnType<typeof setTimeout> | undefined;\n\n    harness.before('bootstrap', () => {\n      timer = setTimeout(() => { timedOut = true; }, ms);\n    });\n\n    harness.before('think', () => {\n      if (timedOut) {\n        return { abort: onTrigger, reason: `timeout-after:${options.wallClock}` };\n      }\n      return undefined;\n    });\n\n    harness.after('complete', () => {\n      if (timer !== undefined) clearTimeout(timer);\n    });\n  };\n}\n","import type { Harness } from '@reactive-agents/core';\n\nexport interface MaxIterationsOptions {\n  max: number;\n  onTrigger?: 'stop' | 'terminate';\n}\n\nexport function maxIterations(options: number | MaxIterationsOptions): (harness: Harness) => void {\n  const max = typeof options === 'number' ? options : options.max;\n  const onTrigger = typeof options === 'number' ? 'stop' : (options.onTrigger ?? 'stop');\n  return (harness: Harness) => {\n    harness.before('think', (ctx) => {\n      if (ctx.iteration >= max) {\n        return { abort: onTrigger, reason: `max-iterations:${max}` };\n      }\n      return undefined;\n    });\n  };\n}\n","import type { Harness } from '@reactive-agents/core';\n\nexport interface RequireApprovalForOptions {\n  tools: string[];\n  // Synchronous check: returns true if approved, false if denied.\n  // For async approvers, check externally before creating the killswitch.\n  approver: (ctx: { toolName: string; iteration: number }) => boolean;\n  onDeny?: 'stop' | 'terminate';\n}\n\nexport function requireApprovalFor(options: RequireApprovalForOptions): (harness: Harness) => void {\n  const { tools, approver, onDeny = 'stop' } = options;\n  const toolSet = new Set(tools);\n  return (harness: Harness) => {\n    harness.before('act', (ctx) => {\n      // ctx.state has pending tool calls — extract next tool name if available\n      const pendingTools = (ctx.state as { pendingToolCalls?: Array<{ name?: string }> })\n        .pendingToolCalls ?? [];\n      for (const call of pendingTools) {\n        if (call.name && toolSet.has(call.name)) {\n          const approved = approver({ toolName: call.name, iteration: ctx.iteration });\n          if (!approved) {\n            return { abort: onDeny, reason: `require-approval-for:denied:${call.name}` };\n          }\n        }\n      }\n      return undefined;\n    });\n  };\n}\n","import type { Harness } from '@reactive-agents/core';\n\nexport interface WatchdogOptions {\n  noProgressFor: string | number;  // '30s' | milliseconds\n  progressSignal?: 'observation.tool-result';  // currently only this tag in TagMap\n  onTrigger?: 'stop' | 'terminate';\n}\n\nfunction parseMs(s: string): number {\n  const match = s.match(/^(\\d+(?:\\.\\d+)?)(ms|s|m|h)$/);\n  if (!match) throw new Error(`Invalid duration: ${s}`);\n  const [, n, unit] = match;\n  const m: Record<string, number> = { ms: 1, s: 1000, m: 60_000, h: 3_600_000 };\n  return parseFloat(n!) * (m[unit!] ?? 1000);\n}\n\nexport function watchdog(options: WatchdogOptions): (harness: Harness) => void {\n  const ms = typeof options.noProgressFor === 'number'\n    ? options.noProgressFor\n    : parseMs(options.noProgressFor);\n  const onTrigger = options.onTrigger ?? 'stop';\n  return (harness: Harness) => {\n    let lastProgress = Date.now();\n\n    // Track progress via observation.tool-result events\n    harness.tap('observation.tool-result', () => {\n      lastProgress = Date.now();\n    });\n\n    harness.before('think', () => {\n      const elapsed = Date.now() - lastProgress;\n      if (elapsed >= ms) {\n        return { abort: onTrigger, reason: `watchdog:no-progress-for:${elapsed}ms` };\n      }\n      return undefined;\n    });\n  };\n}\n","import type { Harness } from '@reactive-agents/core';\n\nexport interface ConfidenceFloorOptions {\n  verifier: number;   // threshold 0–1\n  minSteps?: number;  // minimum steps before early exit allowed\n  earlyExit?: boolean;\n}\n\nexport function confidenceFloor(options: ConfidenceFloorOptions): (harness: Harness) => void {\n  const { verifier: threshold, minSteps = 1, earlyExit = true } = options;\n  return (harness: Harness) => {\n    if (!earlyExit) return;  // no-op if earlyExit disabled\n    harness.before('verify', (ctx) => {\n      const state = ctx.state as unknown as { steps?: unknown[]; verifierScore?: number };\n      const stepCount = (state.steps?.length ?? 0) as number;\n      const score = (state.verifierScore ?? 0) as number;\n      if (stepCount >= minSteps && score >= threshold) {\n        // Signal: confidence floor met — allow immediate completion\n        // This is a 'stop' (graceful done), not terminate\n        return { abort: 'stop', reason: `confidence-floor:score:${score}>=${threshold}` };\n      }\n      return undefined;\n    });\n  };\n}\n","const KILLSWITCH_NAMES = [\n  'budgetLimit',\n  'timeoutAfter',\n  'maxIterations',\n  'requireApprovalFor',\n  'watchdog',\n  'confidenceFloor',\n] as const;\n\nexport type KillswitchName = typeof KILLSWITCH_NAMES[number];\n\nexport const killswitches = {\n  list: (): readonly KillswitchName[] => KILLSWITCH_NAMES,\n} as const;\n"],"mappings":";AAUO,SAAS,YAAY,SAAyD;AACnF,QAAM,EAAE,WAAW,YAAY,eAAe,MAAU,YAAY,OAAO,IAAI;AAC/E,SAAO,CAAC,YAAqB;AAC3B,YAAQ,OAAO,SAAS,CAAC,QAAQ;AAC/B,YAAM,SAAU,IAAI,MAA8B,UAAU;AAC5D,UAAI,cAAc,UAAa,UAAU,WAAW;AAClD,eAAO,EAAE,OAAO,WAAW,QAAQ,uBAAuB,MAAM,IAAI,SAAS,GAAG;AAAA,MAClF;AACA,UAAI,eAAe,QAAW;AAC5B,cAAM,gBAAgB,SAAS;AAC/B,YAAI,iBAAiB,YAAY;AAC/B,iBAAO,EAAE,OAAO,WAAW,QAAQ,qBAAqB,cAAc,QAAQ,CAAC,CAAC,IAAI,UAAU,GAAG;AAAA,QACnG;AAAA,MACF;AACA,aAAO;AAAA,IACT,CAAC;AAAA,EACH;AACF;;;ACpBA,SAAS,QAAQ,WAAoC;AACnD,MAAI,OAAO,cAAc,SAAU,QAAO;AAC1C,QAAM,QAAQ,UAAU,MAAM,6BAA6B;AAC3D,MAAI,CAAC,MAAO,OAAM,IAAI,MAAM,sBAAsB,SAAS,EAAE;AAC7D,QAAM,CAAC,EAAE,GAAG,IAAI,IAAI;AACpB,QAAM,cAAsC,EAAE,IAAI,GAAG,GAAG,KAAM,GAAG,KAAQ,GAAG,KAAU;AACtF,SAAO,WAAW,CAAE,KAAK,YAAY,IAAK,KAAK;AACjD;AAEO,SAAS,aAAa,SAA0D;AACrF,QAAM,KAAK,QAAQ,QAAQ,SAAS;AACpC,QAAM,YAAY,QAAQ,aAAa;AACvC,SAAO,CAAC,YAAqB;AAC3B,QAAI,WAAW;AACf,QAAI;AAEJ,YAAQ,OAAO,aAAa,MAAM;AAChC,cAAQ,WAAW,MAAM;AAAE,mBAAW;AAAA,MAAM,GAAG,EAAE;AAAA,IACnD,CAAC;AAED,YAAQ,OAAO,SAAS,MAAM;AAC5B,UAAI,UAAU;AACZ,eAAO,EAAE,OAAO,WAAW,QAAQ,iBAAiB,QAAQ,SAAS,GAAG;AAAA,MAC1E;AACA,aAAO;AAAA,IACT,CAAC;AAED,YAAQ,MAAM,YAAY,MAAM;AAC9B,UAAI,UAAU,OAAW,cAAa,KAAK;AAAA,IAC7C,CAAC;AAAA,EACH;AACF;;;AC/BO,SAAS,cAAc,SAAoE;AAChG,QAAM,MAAM,OAAO,YAAY,WAAW,UAAU,QAAQ;AAC5D,QAAM,YAAY,OAAO,YAAY,WAAW,SAAU,QAAQ,aAAa;AAC/E,SAAO,CAAC,YAAqB;AAC3B,YAAQ,OAAO,SAAS,CAAC,QAAQ;AAC/B,UAAI,IAAI,aAAa,KAAK;AACxB,eAAO,EAAE,OAAO,WAAW,QAAQ,kBAAkB,GAAG,GAAG;AAAA,MAC7D;AACA,aAAO;AAAA,IACT,CAAC;AAAA,EACH;AACF;;;ACRO,SAAS,mBAAmB,SAAgE;AACjG,QAAM,EAAE,OAAO,UAAU,SAAS,OAAO,IAAI;AAC7C,QAAM,UAAU,IAAI,IAAI,KAAK;AAC7B,SAAO,CAAC,YAAqB;AAC3B,YAAQ,OAAO,OAAO,CAAC,QAAQ;AAE7B,YAAM,eAAgB,IAAI,MACvB,oBAAoB,CAAC;AACxB,iBAAW,QAAQ,cAAc;AAC/B,YAAI,KAAK,QAAQ,QAAQ,IAAI,KAAK,IAAI,GAAG;AACvC,gBAAM,WAAW,SAAS,EAAE,UAAU,KAAK,MAAM,WAAW,IAAI,UAAU,CAAC;AAC3E,cAAI,CAAC,UAAU;AACb,mBAAO,EAAE,OAAO,QAAQ,QAAQ,+BAA+B,KAAK,IAAI,GAAG;AAAA,UAC7E;AAAA,QACF;AAAA,MACF;AACA,aAAO;AAAA,IACT,CAAC;AAAA,EACH;AACF;;;ACrBA,SAASA,SAAQ,GAAmB;AAClC,QAAM,QAAQ,EAAE,MAAM,6BAA6B;AACnD,MAAI,CAAC,MAAO,OAAM,IAAI,MAAM,qBAAqB,CAAC,EAAE;AACpD,QAAM,CAAC,EAAE,GAAG,IAAI,IAAI;AACpB,QAAM,IAA4B,EAAE,IAAI,GAAG,GAAG,KAAM,GAAG,KAAQ,GAAG,KAAU;AAC5E,SAAO,WAAW,CAAE,KAAK,EAAE,IAAK,KAAK;AACvC;AAEO,SAAS,SAAS,SAAsD;AAC7E,QAAM,KAAK,OAAO,QAAQ,kBAAkB,WACxC,QAAQ,gBACRA,SAAQ,QAAQ,aAAa;AACjC,QAAM,YAAY,QAAQ,aAAa;AACvC,SAAO,CAAC,YAAqB;AAC3B,QAAI,eAAe,KAAK,IAAI;AAG5B,YAAQ,IAAI,2BAA2B,MAAM;AAC3C,qBAAe,KAAK,IAAI;AAAA,IAC1B,CAAC;AAED,YAAQ,OAAO,SAAS,MAAM;AAC5B,YAAM,UAAU,KAAK,IAAI,IAAI;AAC7B,UAAI,WAAW,IAAI;AACjB,eAAO,EAAE,OAAO,WAAW,QAAQ,4BAA4B,OAAO,KAAK;AAAA,MAC7E;AACA,aAAO;AAAA,IACT,CAAC;AAAA,EACH;AACF;;;AC7BO,SAAS,gBAAgB,SAA6D;AAC3F,QAAM,EAAE,UAAU,WAAW,WAAW,GAAG,YAAY,KAAK,IAAI;AAChE,SAAO,CAAC,YAAqB;AAC3B,QAAI,CAAC,UAAW;AAChB,YAAQ,OAAO,UAAU,CAAC,QAAQ;AAChC,YAAM,QAAQ,IAAI;AAClB,YAAM,YAAa,MAAM,OAAO,UAAU;AAC1C,YAAM,QAAS,MAAM,iBAAiB;AACtC,UAAI,aAAa,YAAY,SAAS,WAAW;AAG/C,eAAO,EAAE,OAAO,QAAQ,QAAQ,0BAA0B,KAAK,KAAK,SAAS,GAAG;AAAA,MAClF;AACA,aAAO;AAAA,IACT,CAAC;AAAA,EACH;AACF;;;ACxBA,IAAM,mBAAmB;AAAA,EACvB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAIO,IAAM,eAAe;AAAA,EAC1B,MAAM,MAAiC;AACzC;","names":["parseMs"]}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@reactive-agents/compose",
+  "version": "0.11.0",
+  "description": "Prebuilt killswitch compositions for reactive agents",
+  "type": "module",
+  "scripts": {
+    "build": "tsup --config ../../tsup.config.base.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test --reporter=dots",
+    "test:watch": "bun test --watch"
+  },
+  "dependencies": {
+    "@reactive-agents/core": "0.11.0"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3",
+    "bun-types": "latest"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tylerjrbuell/reactive-agents-ts.git",
+    "directory": "packages/compose"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "bun": "./dist/index.js",
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./killswitches": {
+      "bun": "./dist/killswitches/index.js",
+      "import": "./dist/killswitches/index.js",
+      "types": "./dist/killswitches/index.d.ts"
+    }
+  },
+  "homepage": "https://docs.reactiveagents.dev/",
+  "bugs": {
+    "url": "https://github.com/tylerjrbuell/reactive-agents-ts/issues"
+  }
+}