octoflow-core 1.0.0

package/dist/runtime/orchestration/subagent/subagent-action.js

@@ -0,0 +1,303 @@
+import { defineAction } from "../../../actions/define.js";
+import { createRootLineage } from "../../../adapters/agents/registry/types.js";
+import { isTerminalTaskState } from "../../../adapters/data/task-store/index.js";
+import {
+  AgentTimeoutError,
+  SubagentConcurrencyLimitError,
+  SubagentDepthExceededError,
+  SubagentRoleNotFoundError
+} from "../../../domain/errors/index.js";
+import { extractText } from "../../../utils/extract-text.js";
+import { closeBridgePort } from "../../bridge/bridge-port.js";
+import { spawnAgent } from "../pack/coordination.js";
+const DEFAULT_MAX_DEPTH = 1;
+const DEFAULT_MAX_CONCURRENT = 5;
+const DEFAULT_TIMEOUT_MS = 3e5;
+const DEFAULT_NAME = "task";
+const bridgeSemaphores = /* @__PURE__ */ new WeakMap();
+function getBridgeSemaphore(bridge) {
+  let sem = bridgeSemaphores.get(bridge);
+  if (!sem) {
+    sem = { inFlight: 0 };
+    bridgeSemaphores.set(bridge, sem);
+  }
+  return sem;
+}
+function resolveDefinitionRunOptions(definition) {
+  const allowedTools = definition.tools === "*" ? void 0 : definition.tools.filter(
+    (name) => !(definition.disallowedTools?.includes(name) ?? false)
+  );
+  const model = definition.model && definition.model !== "inherit" && definition.model !== "fast" ? definition.model : void 0;
+  return {
+    ...model ? { model } : {},
+    ...definition.effort ? { effort: definition.effort } : {},
+    ...allowedTools ? { allowedTools } : {},
+    ...definition.disallowedTools?.length ? { disallowedTools: definition.disallowedTools } : {}
+  };
+}
+function createSubagentAction(opts) {
+  const {
+    registry,
+    parentBridge,
+    parentLineage,
+    maxDepth = DEFAULT_MAX_DEPTH,
+    maxConcurrent = DEFAULT_MAX_CONCURRENT,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    allowedRoles,
+    name = DEFAULT_NAME,
+    inherit,
+    toModelOutput,
+    onChildEvent,
+    _spawn = spawnAgent
+  } = opts;
+  if (!registry) {
+    throw new Error("[octoflow] createSubagentAction: `registry` is required");
+  }
+  if (!parentBridge) {
+    throw new Error(
+      "[octoflow] createSubagentAction: `parentBridge` is required"
+    );
+  }
+  if (maxDepth < 1) {
+    throw new Error("[octoflow] createSubagentAction: `maxDepth` must be >= 1");
+  }
+  if (maxConcurrent < 1) {
+    throw new Error(
+      "[octoflow] createSubagentAction: `maxConcurrent` must be >= 1"
+    );
+  }
+  const availableRoles = resolveAvailableRoles(registry, allowedRoles);
+  const inheritsHistory = Boolean(inherit?.history);
+  const description = buildToolDescription(availableRoles, inheritsHistory);
+  const parameters = buildToolParameters(availableRoles, inheritsHistory);
+  return defineAction({
+    name,
+    description,
+    parameters,
+    tags: ["subagent", "builtin"],
+    execute: async (args, _ctx) => {
+      const subagentRole = requireString(
+        args["subagent_role"],
+        "subagent_role"
+      );
+      const prompt = requireString(args["prompt"], "prompt");
+      const definition = registry.get(subagentRole);
+      if (!definition || !availableRoles.includes(subagentRole)) {
+        throw new SubagentRoleNotFoundError(subagentRole, availableRoles);
+      }
+      const executionBridge = asBridgePort(_ctx.bridge) ?? parentBridge;
+      const effectiveParent = executionBridge.lineage ?? parentLineage ?? createRootLineage("root");
+      const childDepth = effectiveParent.depth + 1;
+      if (childDepth > maxDepth) {
+        throw new SubagentDepthExceededError(childDepth, maxDepth);
+      }
+      const sem = getBridgeSemaphore(executionBridge);
+      if (sem.inFlight >= maxConcurrent) {
+        throw new SubagentConcurrencyLimitError(sem.inFlight, maxConcurrent);
+      }
+      sem.inFlight += 1;
+      const parentToolUseId = readToolUseId(args);
+      const spawnOpts = {
+        agentName: definition.role,
+        agentDefinition: definition,
+        inherit: { runtime: true, plugins: true, guardrails: true, ...inherit },
+        parentBridge: executionBridge,
+        ..._ctx.tenant !== void 0 ? { tenant: _ctx.tenant } : {}
+      };
+      let spawned;
+      let status = "completed";
+      const startedAt = Date.now();
+      try {
+        spawned = await _spawn(effectiveParent, _ctx.contextId, spawnOpts);
+        await executionBridge.events.emit("subagent:start", {
+          taskId: _ctx.taskId,
+          contextId: spawned.contextId,
+          backend: "subagent",
+          agentName: definition.role,
+          backendType: "api",
+          remote: false,
+          subagentRole,
+          depth: spawned.lineage.depth,
+          ...parentToolUseId ? { parentToolUseId } : {}
+        });
+        const sendParams = {
+          ...resolveDefinitionRunOptions(definition),
+          contextId: spawned.contextId,
+          ...spawned.inheritedHistory?.length ? { structuredHistory: spawned.inheritedHistory } : {},
+          message: {
+            kind: "message",
+            messageId: crypto.randomUUID(),
+            role: "user",
+            parts: [{ kind: "text", text: prompt }]
+          }
+        };
+        let rawText = "";
+        let taskId = "";
+        let artifacts;
+        if (onChildEvent) {
+          await runWithTimeout(
+            (async () => {
+              for await (const event of spawned.bridge.stream(sendParams)) {
+                onChildEvent(subagentRole, event);
+                await executionBridge.events.emit("subagent:event", {
+                  subagentRole,
+                  depth: spawned.lineage.depth,
+                  event
+                });
+                if (event.kind === "artifact-update") {
+                  const existing = artifacts ?? [];
+                  const idx = existing.findIndex(
+                    (a) => a.artifactId === event.event.artifact.artifactId
+                  );
+                  if (idx >= 0) {
+                    existing[idx] = event.event.artifact;
+                  } else {
+                    existing.push(event.event.artifact);
+                  }
+                  artifacts = existing;
+                } else if (event.kind === "task") {
+                  taskId = event.task.id;
+                  if (event.task.artifacts?.length) {
+                    artifacts = event.task.artifacts;
+                  }
+                } else if (event.kind === "status-update") {
+                  taskId = event.event.taskId;
+                  if (isTerminalTaskState(event.event.status.state)) {
+                    const msg = event.event.status.message;
+                    if (msg) {
+                      rawText = msg.parts.filter(
+                        (p) => p.kind === "text"
+                      ).map((p) => p.text).join("");
+                    }
+                    break;
+                  }
+                }
+              }
+            })(),
+            timeoutMs
+          );
+        } else {
+          const result = await runWithTimeout(
+            spawned.bridge.sendMessage(sendParams),
+            timeoutMs
+          );
+          rawText = extractText(result);
+          taskId = result.kind === "task" ? result.taskId : "";
+          if (result.kind === "task" && result.task.artifacts?.length) {
+            artifacts = result.task.artifacts;
+          }
+        }
+        const text = toModelOutput ? toModelOutput({ text: rawText, taskId, artifacts }) : rawText;
+        const invocation = {
+          text,
+          subagentRole,
+          contextId: spawned.contextId,
+          ...artifacts?.length ? { artifacts } : {}
+        };
+        return invocation;
+      } catch (err) {
+        status = "failed";
+        throw err;
+      } finally {
+        sem.inFlight -= 1;
+        if (spawned) {
+          try {
+            await executionBridge.events.emit("subagent:stop", {
+              taskId: _ctx.taskId,
+              contextId: spawned.contextId,
+              backend: "subagent",
+              agentName: definition.role,
+              backendType: "api",
+              remote: false,
+              status,
+              subagentRole,
+              depth: spawned.lineage.depth,
+              durationMs: Date.now() - startedAt,
+              ...parentToolUseId ? { parentToolUseId } : {}
+            });
+          } catch {
+          }
+          try {
+            await closeBridgePort(spawned.bridge);
+          } catch {
+          }
+        }
+      }
+    }
+  });
+}
+function asBridgePort(value) {
+  const candidate = value;
+  return candidate && typeof candidate.sendMessage === "function" && typeof candidate.stream === "function" && typeof candidate.destroy === "function" && candidate.events ? candidate : void 0;
+}
+function resolveAvailableRoles(registry, whitelist) {
+  const all = registry.agents.map((a) => a.role);
+  if (!whitelist) return Array.from(new Set(all));
+  const set = new Set(whitelist);
+  return all.filter((t) => set.has(t));
+}
+function buildToolDescription(roles, inheritsHistory) {
+  const list = roles.length ? roles.join(", ") : "(none registered)";
+  return [
+    "Launch a subagent to handle a complex, multi-step task in an isolated context window.",
+    `Available subagent roles: ${list}.`,
+    "Scale by complexity: use 1 subagent for focused work, 2\u20134 for independent parallel comparisons, 10+ for large research tasks with a clear division of labor.",
+    "Launch multiple subagents in parallel whenever tasks are independent.",
+    inheritsHistory ? "The subagent sees the prompt plus a bounded snapshot of recent parent history." : "The subagent does not see the parent conversation \u2014 include all context in `prompt`."
+  ].join(" ");
+}
+function buildToolParameters(roles, inheritsHistory) {
+  const roleSchema = {
+    type: "string",
+    description: "Which registered subagent role to spawn. Must be one of the available roles."
+  };
+  if (roles.length > 0) {
+    roleSchema["enum"] = [...roles];
+  }
+  return {
+    type: "object",
+    properties: {
+      subagent_role: roleSchema,
+      description: {
+        type: "string",
+        description: "Short (3\u20135 word) summary shown in UI while the subagent runs."
+      },
+      prompt: {
+        type: "string",
+        description: inheritsHistory ? "Full task description for the subagent. Recent parent history is seeded separately, but the prompt should still state the task clearly." : "Full task description for the subagent. Include all context \u2014 the subagent sees none of the parent conversation."
+      }
+    },
+    required: ["subagent_role", "prompt"]
+  };
+}
+function requireString(value, field) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`[octoflow] task: \`${field}\` must be a non-empty string`);
+  }
+  return value;
+}
+function readToolUseId(args) {
+  const raw = args["_parentToolUseId"] ?? args["toolUseId"];
+  return typeof raw === "string" && raw.length > 0 ? raw : void 0;
+}
+async function runWithTimeout(promise, timeoutMs) {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return promise;
+  let timer;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_, reject) => {
+        timer = setTimeout(
+          () => reject(new AgentTimeoutError(timeoutMs)),
+          timeoutMs
+        );
+      })
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+export {
+  createSubagentAction
+};
+//# sourceMappingURL=subagent-action.js.map

package/dist/runtime/orchestration/subagent/subagent-action.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/runtime/orchestration/subagent/subagent-action.ts"],
+  "sourcesContent": ["/**\n * `createSubagentAction` \u2014 the LLM-callable `task` subagent tool.\n *\n * Exposes an {@link ActionDefinition} that, when invoked by the model, spawns\n * a child {@link BridgePort} via {@link spawnAgent} with a fresh context and\n * a scoped tool surface (resolved from the {@link AgentRegistry}).\n *\n * Safety rails (enforced in this order per call):\n *   1. `subagent_role` must exist in the registry AND pass `allowedRoles`.\n *   2. `maxDepth` \u2014 reject if the spawn would exceed the configured depth.\n *   3. `maxConcurrent` \u2014 reject if the action is already at its in-flight cap.\n *   4. `timeoutMs` \u2014 wall-clock cap on `child.sendMessage`.\n *\n * Events (additive to the existing Pack-emitted pair):\n *   * `subagent:start` \u2014 carries `subagentRole`, `depth`, and\n *     `parentToolUseId` when the caller supplies a `toolUseId` in metadata.\n *   * `subagent:stop`  \u2014 same fields plus `status` (`'completed' | 'failed'`).\n *\n * This factory is **opt-in**: not included in `loadBuiltinActions`. Callers\n * must register it explicitly (or via the `subagentTools()` preset in\n * `octoflow-tools`).\n */\n\nimport type { BridgeActionPort } from '../../../actions/bridge-action-port.js';\nimport { defineAction } from '../../../actions/define.js';\nimport type { ActionDefinition } from '../../../actions/types.js';\nimport type { AgentRegistry } from '../../../adapters/agents/registry/loader.js';\nimport type { AgentDefinition } from '../../../adapters/agents/registry/types.js';\nimport { createRootLineage } from '../../../adapters/agents/registry/types.js';\nimport { isTerminalTaskState } from '../../../adapters/data/task-store/index.js';\nimport type { BridgeSendMessageParams } from '../../../domain/bridge-api.js';\nimport type { Artifact } from '../../../domain/core-task.js';\nimport {\n  AgentTimeoutError,\n  SubagentConcurrencyLimitError,\n  SubagentDepthExceededError,\n  SubagentRoleNotFoundError,\n} from '../../../domain/errors/index.js';\nimport { extractText } from '../../../utils/extract-text.js';\nimport type { BridgePort } from '../../bridge/bridge-port.js';\nimport { closeBridgePort } from '../../bridge/bridge-port.js';\nimport { spawnAgent } from '../pack/coordination.js';\nimport type { SpawnOptions } from '../pack/coordination-types.js';\nimport type {\n  CreateSubagentActionOptions,\n  SpawnAgent,\n  SubagentInvocationResult,\n} from './subagent-action-types.js';\n\nexport type {\n  CreateSubagentActionOptions,\n  SubagentInvocationResult,\n  SubagentsBridgeOptions,\n} from './subagent-action-types.js';\n\nconst DEFAULT_MAX_DEPTH = 1;\nconst DEFAULT_MAX_CONCURRENT = 5;\nconst DEFAULT_TIMEOUT_MS = 300_000;\nconst DEFAULT_NAME = 'task';\n\n// Shared semaphore per parentBridge so all actions registered on the same\n// bridge count against a single concurrency budget.\nconst bridgeSemaphores = new WeakMap<BridgePort, { inFlight: number }>();\n\nfunction getBridgeSemaphore(bridge: BridgePort): { inFlight: number } {\n  let sem = bridgeSemaphores.get(bridge);\n  if (!sem) {\n    sem = { inFlight: 0 };\n    bridgeSemaphores.set(bridge, sem);\n  }\n  return sem;\n}\n\nfunction resolveDefinitionRunOptions(\n  definition: AgentDefinition\n): Partial<BridgeSendMessageParams> {\n  const allowedTools =\n    definition.tools === '*'\n      ? undefined\n      : definition.tools.filter(\n          (name) => !(definition.disallowedTools?.includes(name) ?? false)\n        );\n  const model =\n    definition.model &&\n    definition.model !== 'inherit' &&\n    definition.model !== 'fast'\n      ? definition.model\n      : undefined;\n\n  return {\n    ...(model ? { model } : {}),\n    ...(definition.effort ? { effort: definition.effort } : {}),\n    ...(allowedTools ? { allowedTools } : {}),\n    ...(definition.disallowedTools?.length\n      ? { disallowedTools: definition.disallowedTools }\n      : {}),\n  };\n}\n\nexport function createSubagentAction(\n  opts: CreateSubagentActionOptions\n): ActionDefinition {\n  const {\n    registry,\n    parentBridge,\n    parentLineage,\n    maxDepth = DEFAULT_MAX_DEPTH,\n    maxConcurrent = DEFAULT_MAX_CONCURRENT,\n    timeoutMs = DEFAULT_TIMEOUT_MS,\n    allowedRoles,\n    name = DEFAULT_NAME,\n    inherit,\n    toModelOutput,\n    onChildEvent,\n    _spawn = spawnAgent,\n  } = opts;\n\n  if (!registry) {\n    throw new Error('[octoflow] createSubagentAction: `registry` is required');\n  }\n  if (!parentBridge) {\n    throw new Error(\n      '[octoflow] createSubagentAction: `parentBridge` is required'\n    );\n  }\n  if (maxDepth < 1) {\n    throw new Error('[octoflow] createSubagentAction: `maxDepth` must be >= 1');\n  }\n  if (maxConcurrent < 1) {\n    throw new Error(\n      '[octoflow] createSubagentAction: `maxConcurrent` must be >= 1'\n    );\n  }\n\n  const availableRoles = resolveAvailableRoles(registry, allowedRoles);\n  const inheritsHistory = Boolean(inherit?.history);\n  const description = buildToolDescription(availableRoles, inheritsHistory);\n  const parameters = buildToolParameters(availableRoles, inheritsHistory);\n\n  return defineAction({\n    name,\n    description,\n    parameters,\n    tags: ['subagent', 'builtin'],\n    execute: async (args, _ctx) => {\n      const subagentRole = requireString(\n        args['subagent_role'],\n        'subagent_role'\n      );\n      const prompt = requireString(args['prompt'], 'prompt');\n\n      // Resolve + whitelist check.\n      const definition = registry.get(subagentRole);\n      if (!definition || !availableRoles.includes(subagentRole)) {\n        throw new SubagentRoleNotFoundError(subagentRole, availableRoles);\n      }\n\n      const executionBridge = asBridgePort(_ctx.bridge) ?? parentBridge;\n      const effectiveParent =\n        executionBridge.lineage ?? parentLineage ?? createRootLineage('root');\n      const childDepth = effectiveParent.depth + 1;\n      if (childDepth > maxDepth) {\n        throw new SubagentDepthExceededError(childDepth, maxDepth);\n      }\n\n      const sem = getBridgeSemaphore(executionBridge);\n      if (sem.inFlight >= maxConcurrent) {\n        throw new SubagentConcurrencyLimitError(sem.inFlight, maxConcurrent);\n      }\n      sem.inFlight += 1;\n\n      const parentToolUseId = readToolUseId(args);\n      const spawnOpts: SpawnOptions = {\n        agentName: definition.role,\n        agentDefinition: definition,\n        inherit: { runtime: true, plugins: true, guardrails: true, ...inherit },\n        parentBridge: executionBridge,\n        ...(_ctx.tenant !== undefined ? { tenant: _ctx.tenant } : {}),\n      };\n\n      let spawned: Awaited<ReturnType<SpawnAgent>> | undefined;\n      let status: 'completed' | 'failed' = 'completed';\n      const startedAt = Date.now();\n      try {\n        spawned = await _spawn(effectiveParent, _ctx.contextId, spawnOpts);\n\n        await executionBridge.events.emit('subagent:start', {\n          taskId: _ctx.taskId,\n          contextId: spawned.contextId,\n          backend: 'subagent',\n          agentName: definition.role,\n          backendType: 'api',\n          remote: false,\n          subagentRole,\n          depth: spawned.lineage.depth,\n          ...(parentToolUseId ? { parentToolUseId } : {}),\n        });\n\n        const sendParams: BridgeSendMessageParams = {\n          ...resolveDefinitionRunOptions(definition),\n          contextId: spawned.contextId,\n          ...(spawned.inheritedHistory?.length\n            ? { structuredHistory: spawned.inheritedHistory }\n            : {}),\n          message: {\n            kind: 'message',\n            messageId: crypto.randomUUID(),\n            role: 'user',\n            parts: [{ kind: 'text', text: prompt }],\n          },\n        };\n\n        let rawText = '';\n        let taskId = '';\n        let artifacts: Artifact[] | undefined;\n\n        if (onChildEvent) {\n          await runWithTimeout(\n            (async () => {\n              for await (const event of spawned.bridge.stream(sendParams)) {\n                onChildEvent(subagentRole, event);\n                await executionBridge.events.emit('subagent:event', {\n                  subagentRole,\n                  depth: spawned.lineage.depth,\n                  event,\n                });\n                if (event.kind === 'artifact-update') {\n                  const existing = artifacts ?? [];\n                  const idx = existing.findIndex(\n                    (a) => a.artifactId === event.event.artifact.artifactId\n                  );\n                  if (idx >= 0) {\n                    existing[idx] = event.event.artifact;\n                  } else {\n                    existing.push(event.event.artifact);\n                  }\n                  artifacts = existing;\n                } else if (event.kind === 'task') {\n                  taskId = event.task.id;\n                  if (event.task.artifacts?.length) {\n                    artifacts = event.task.artifacts;\n                  }\n                } else if (event.kind === 'status-update') {\n                  taskId = event.event.taskId;\n                  if (isTerminalTaskState(event.event.status.state)) {\n                    const msg = event.event.status.message;\n                    if (msg) {\n                      rawText = msg.parts\n                        .filter(\n                          (p): p is Extract<typeof p, { kind: 'text' }> =>\n                            p.kind === 'text'\n                        )\n                        .map((p) => p.text)\n                        .join('');\n                    }\n                    break;\n                  }\n                }\n              }\n            })(),\n            timeoutMs\n          );\n        } else {\n          const result = await runWithTimeout(\n            spawned.bridge.sendMessage(sendParams),\n            timeoutMs\n          );\n          rawText = extractText(result);\n          taskId = result.kind === 'task' ? result.taskId : '';\n          if (result.kind === 'task' && result.task.artifacts?.length) {\n            artifacts = result.task.artifacts;\n          }\n        }\n\n        const text = toModelOutput\n          ? toModelOutput({ text: rawText, taskId, artifacts })\n          : rawText;\n\n        const invocation: SubagentInvocationResult = {\n          text,\n          subagentRole,\n          contextId: spawned.contextId,\n          ...(artifacts?.length ? { artifacts } : {}),\n        };\n        return invocation;\n      } catch (err) {\n        status = 'failed';\n        throw err;\n      } finally {\n        sem.inFlight -= 1;\n        if (spawned) {\n          // Best-effort \u2014 emit stop before tearing down the child so\n          // observers always receive a matched start/stop pair.\n          try {\n            await executionBridge.events.emit('subagent:stop', {\n              taskId: _ctx.taskId,\n              contextId: spawned.contextId,\n              backend: 'subagent',\n              agentName: definition.role,\n              backendType: 'api',\n              remote: false,\n              status,\n              subagentRole,\n              depth: spawned.lineage.depth,\n              durationMs: Date.now() - startedAt,\n              ...(parentToolUseId ? { parentToolUseId } : {}),\n            });\n          } catch {\n            // Swallow emission failures \u2014 event bus is best-effort by contract.\n          }\n          try {\n            await closeBridgePort(spawned.bridge);\n          } catch {\n            // Swallow destroy errors \u2014 we don't want cleanup to mask the real cause.\n          }\n        }\n      }\n    },\n  });\n}\n\nfunction asBridgePort(value: BridgeActionPort): BridgePort | undefined {\n  const candidate = value as Partial<BridgePort>;\n  return candidate &&\n    typeof candidate.sendMessage === 'function' &&\n    typeof candidate.stream === 'function' &&\n    typeof candidate.destroy === 'function' &&\n    candidate.events\n    ? (candidate as BridgePort)\n    : undefined;\n}\n\nfunction resolveAvailableRoles(\n  registry: AgentRegistry,\n  whitelist?: readonly string[]\n): string[] {\n  const all = registry.agents.map((a) => a.role);\n  if (!whitelist) return Array.from(new Set(all));\n  const set = new Set(whitelist);\n  return all.filter((t) => set.has(t));\n}\n\nfunction buildToolDescription(\n  roles: readonly string[],\n  inheritsHistory: boolean\n): string {\n  const list = roles.length ? roles.join(', ') : '(none registered)';\n  return [\n    'Launch a subagent to handle a complex, multi-step task in an isolated context window.',\n    `Available subagent roles: ${list}.`,\n    'Scale by complexity: use 1 subagent for focused work, 2\u20134 for independent parallel comparisons, 10+ for large research tasks with a clear division of labor.',\n    'Launch multiple subagents in parallel whenever tasks are independent.',\n    inheritsHistory\n      ? 'The subagent sees the prompt plus a bounded snapshot of recent parent history.'\n      : 'The subagent does not see the parent conversation \u2014 include all context in `prompt`.',\n  ].join(' ');\n}\n\nfunction buildToolParameters(\n  roles: readonly string[],\n  inheritsHistory: boolean\n): Record<string, unknown> {\n  const roleSchema: Record<string, unknown> = {\n    type: 'string',\n    description:\n      'Which registered subagent role to spawn. Must be one of the available roles.',\n  };\n  // Surface the enum only when we have a bounded list \u2014 avoids shipping an\n  // empty `enum: []` which some providers (Anthropic) treat as a hard reject.\n  if (roles.length > 0) {\n    roleSchema['enum'] = [...roles];\n  }\n  return {\n    type: 'object',\n    properties: {\n      subagent_role: roleSchema,\n      description: {\n        type: 'string',\n        description:\n          'Short (3\u20135 word) summary shown in UI while the subagent runs.',\n      },\n      prompt: {\n        type: 'string',\n        description: inheritsHistory\n          ? 'Full task description for the subagent. Recent parent history is seeded separately, but the prompt should still state the task clearly.'\n          : 'Full task description for the subagent. Include all context \u2014 the subagent sees none of the parent conversation.',\n      },\n    },\n    required: ['subagent_role', 'prompt'],\n  };\n}\n\nfunction requireString(value: unknown, field: string): string {\n  if (typeof value !== 'string' || value.length === 0) {\n    throw new Error(`[octoflow] task: \\`${field}\\` must be a non-empty string`);\n  }\n  return value;\n}\n\nfunction readToolUseId(args: Record<string, unknown>): string | undefined {\n  const raw = args['_parentToolUseId'] ?? args['toolUseId'];\n  return typeof raw === 'string' && raw.length > 0 ? raw : undefined;\n}\n\nasync function runWithTimeout<T>(\n  promise: Promise<T>,\n  timeoutMs: number\n): Promise<T> {\n  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return promise;\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  try {\n    return await Promise.race<T>([\n      promise,\n      new Promise<T>((_, reject) => {\n        timer = setTimeout(\n          () => reject(new AgentTimeoutError(timeoutMs)),\n          timeoutMs\n        );\n      }),\n    ]);\n  } finally {\n    if (timer) clearTimeout(timer);\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/runtime/sessions/agent-skills-types.d.ts

@@ -0,0 +1,29 @@
+import type { AgentSkillMetadata } from '../../capabilities/skills/types.js';
+export interface AgentSkillsOptions {
+    /** Master toggle. Default `true` when `agentSkills` is present. */
+    enabled?: boolean;
+    /** Extra directories to scan beyond the vendor paths. */
+    additionalPaths?: string[];
+    /** Scan project-scope vendor paths (`<cwd>/...`). Default `true`. */
+    projectSkills?: boolean;
+    /** Scan user-scope vendor paths (`~/...`). Default `true`. */
+    userSkills?: boolean;
+    /** Skill names to skip. */
+    disabled?: string[];
+    /** Max skills rendered into the catalog. Default 50. */
+    maxCatalogSize?: number;
+    /** Max estimated tokens for protected skill bodies in history. Default 25000. */
+    maxProtectedTokens?: number;
+    /** Opt-in: symlink discovered skills into CLI vendor paths. Default false. */
+    symlinkIntoCliPaths?: boolean;
+    /** Working directory used for project-scope scans. Defaults to `process.cwd()`. */
+    workspace?: string;
+    /**
+     * Explicitly pre-loaded SKILL.md bundles, typically produced by
+     * `loadSkillBundle()` / `loadSkillBundles()`. These are merged with
+     * scanner-discovered skills; explicit bundles win on name collision.
+     * See. 6-to-9.5 §F7.
+     */
+    bundles?: AgentSkillMetadata[];
+}
+//# sourceMappingURL=agent-skills-types.d.ts.map

package/dist/runtime/sessions/agent-skills-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-skills-types.d.ts","sourceRoot":"","sources":["../../../src/runtime/sessions/agent-skills-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAE7E,MAAM,WAAW,kBAAkB;IACjC,mEAAmE;IACnE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yDAAyD;IACzD,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,qEAAqE;IACrE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,8DAA8D;IAC9D,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,wDAAwD;IACxD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iFAAiF;IACjF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,8EAA8E;IAC9E,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,mFAAmF;IACnF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,kBAAkB,EAAE,CAAC;CAChC"}

package/dist/runtime/sessions/agent-skills-types.js

@@ -0,0 +1 @@
+//# sourceMappingURL=agent-skills-types.js.map

package/dist/runtime/sessions/agent-skills-types.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/dist/runtime/sessions/bridge-aux-types.d.ts

@@ -0,0 +1,28 @@
+export interface BridgeSecurityOptions {
+    /**
+     * Disable the bash command denylist and default approval gate. Explicit,
+     * bridge-wide opt-in for trusted automation only. Each bash call will
+     * otherwise run without pre-execution safety checks.
+     */
+    dangerouslyDisableBashSecurity?: boolean;
+}
+export interface ContextEvictInfo {
+    contextId: string;
+    tenant?: string;
+    reason: 'lru' | 'ttl' | 'manual';
+    queueDepth: number;
+    createdAt: string;
+    evictedAt: string;
+}
+export interface CircuitBreakerOptions {
+    failureThreshold?: number;
+    cooldownMs?: number;
+    halfOpenProbes?: number;
+    windowMs?: number;
+}
+export interface BridgeApprovalOptions {
+    enabled?: boolean;
+    requireApproval?: string[];
+    approvalTimeoutMs?: number;
+}
+//# sourceMappingURL=bridge-aux-types.d.ts.map

package/dist/runtime/sessions/bridge-aux-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-aux-types.d.ts","sourceRoot":"","sources":["../../../src/runtime/sessions/bridge-aux-types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,8BAA8B,CAAC,EAAE,OAAO,CAAC;CAC1C;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,KAAK,GAAG,KAAK,GAAG,QAAQ,CAAC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B"}

package/dist/runtime/sessions/bridge-aux-types.js

@@ -0,0 +1 @@
+//# sourceMappingURL=bridge-aux-types.js.map

package/dist/runtime/sessions/bridge-aux-types.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}