octoflow-core 1.0.0

package/dist/runtime/orchestration/run/task-batch.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/runtime/orchestration/run/task-batch.ts"],
+  "sourcesContent": ["import { assertNever } from '../../../utils/assert-never.js';\nimport { composeSignals } from '../../../utils/signals.js';\nimport { buildLoopResult, runLoopStream } from './loop-engine.js';\nimport {\n  buildFailedResult,\n  buildWaves,\n  resolveIsolationStrategy,\n  topologicalSort,\n  validateDependencies,\n} from './task-batch-graph.js';\nimport {\n  buildTaskBranchInfo,\n  isTaskOutcomeFailure,\n  normalizeConcurrency,\n  runWaveWithConcurrency,\n} from './task-batch-helpers.js';\nimport { resolveTaskItems } from './task-batch-sources.js';\nimport type {\n  BridgeLoopResult,\n  BridgeTaskResult,\n  IsolationHandle,\n  LoopConfig,\n  LoopExecutor,\n  RunBatchResult,\n  RunEvent,\n  TaskBranchInfo,\n  TaskConfig,\n  TaskItem,\n  TerminationReason,\n} from './types.js';\n\nconst DEFAULT_MAX_TASKS = 100;\n\nexport interface BatchOptions {\n  signal?: AbortSignal;\n}\n\nexport async function* runTaskBatchStream(\n  executor: LoopExecutor,\n  taskConfig: TaskConfig,\n  loopConfig: LoopConfig,\n  baseContextId: string,\n  options?: BatchOptions\n): AsyncGenerator<RunEvent> {\n  const maxTasks = taskConfig.maxTasks ?? DEFAULT_MAX_TASKS;\n  const items = await resolveTaskItems(\n    taskConfig.source,\n    options?.signal,\n    maxTasks\n  );\n  validateDependencies(items);\n  const sorted = topologicalSort(items);\n\n  if (sorted.length > maxTasks) {\n    yield {\n      kind: 'task-batch-truncated',\n      source: 'task-batch',\n      totalItems: sorted.length,\n      maxTasks,\n    };\n  }\n  const tasksToRun = sorted.slice(0, maxTasks);\n  const strategy = resolveIsolationStrategy(taskConfig);\n  const failFast = taskConfig.failFast ?? false;\n  const skipOnUpstream = taskConfig.skipOnUpstreamFailure ?? true;\n  const concurrency = normalizeConcurrency(taskConfig.concurrency);\n\n  if (concurrency > 1 && taskConfig.isolation === 'branch') {\n    throw new Error(\n      'concurrency > 1 is not supported with branch isolation. ' +\n        'Use isolation: \"context\" (separate contextId per task) or isolation: \"none\" for parallel tasks, ' +\n        'or run tasks sequentially with concurrency: 1.'\n    );\n  }\n\n  let completedTasks = 0;\n  let failedTasks = 0;\n  const failedIds = new Set<string>();\n  const executedIds = new Set<string>();\n  const waves = buildWaves(tasksToRun);\n\n  for (const wave of waves) {\n    if (options?.signal?.aborted) break;\n    if (failFast && failedTasks > 0) break;\n\n    const failedAtWaveStart = failedIds.size;\n    yield* runWaveWithConcurrency(\n      wave,\n      concurrency,\n      async function* ({ task, originalIndex }) {\n        if (options?.signal?.aborted) return;\n        if (failFast && failedIds.size > failedAtWaveStart) return;\n\n        executedIds.add(task.id);\n        yield* runSingleTask(\n          executor,\n          task,\n          originalIndex,\n          baseContextId,\n          loopConfig,\n          strategy,\n          taskConfig,\n          skipOnUpstream,\n          failedIds,\n          options?.signal\n        );\n      }\n    );\n\n    for (const { task } of wave) {\n      if (!executedIds.has(task.id)) continue;\n      if (failedIds.has(task.id)) {\n        failedTasks++;\n      } else {\n        completedTasks++;\n      }\n    }\n  }\n\n  yield {\n    kind: 'task-batch-complete',\n    source: 'task-batch',\n    totalTasks: tasksToRun.length,\n    completedTasks,\n    failedTasks,\n  };\n}\n\nasync function* runSingleTask(\n  executor: LoopExecutor,\n  task: TaskItem,\n  index: number,\n  baseContextId: string,\n  loopConfig: LoopConfig,\n  strategy: {\n    before: (t: TaskItem, i: number, ctx: string) => Promise<IsolationHandle>;\n    after: (h: IsolationHandle, r: BridgeLoopResult) => Promise<void>;\n    cleanup: (h: IsolationHandle, err?: Error) => Promise<void>;\n  },\n  taskConfig: TaskConfig,\n  skipOnUpstream: boolean,\n  failedIds: Set<string>,\n  signal?: AbortSignal\n): AsyncGenerator<RunEvent> {\n  if (skipOnUpstream && task.dependsOn?.some((d) => failedIds.has(d))) {\n    yield {\n      kind: 'task-start',\n      source: 'task-batch',\n      task: task.message,\n      index,\n    };\n    yield {\n      kind: 'task-failed',\n      source: 'task-batch',\n      task: task.message,\n      index,\n      error: 'skipped: upstream dependency failed',\n    };\n    failedIds.add(task.id);\n    return;\n  }\n\n  yield { kind: 'task-start', source: 'task-batch', task: task.message, index };\n  await taskConfig.onTaskStart?.(task.message, index);\n\n  let handle: IsolationHandle = { contextId: baseContextId };\n  let cleanupError: Error | undefined;\n  let branch: TaskBranchInfo | undefined;\n\n  try {\n    handle = await strategy.before(task, index, baseContextId);\n\n    const perTaskConfig: LoopConfig = signal\n      ? {\n          ...loopConfig,\n          signal: loopConfig.signal\n            ? composeSignals(signal, loopConfig.signal)\n            : signal,\n        }\n      : loopConfig;\n\n    let lastResult: BridgeTaskResult | undefined;\n    let finalReason: TerminationReason = 'cancelled';\n    let finalIterations = 0;\n    let finalElapsedMs = 0;\n    let finalCost: number | undefined;\n    let finalOutcomeClass: BridgeLoopResult['outcomeClass'];\n    const startTime = Date.now();\n\n    const wrappedExecutor: LoopExecutor = async (msg, ctx, iteration) => {\n      const result = await executor(msg, ctx, iteration);\n      lastResult = result;\n      return result;\n    };\n\n    for await (const event of runLoopStream(\n      wrappedExecutor,\n      task.message,\n      handle.contextId,\n      perTaskConfig\n    )) {\n      yield event;\n      if (event.kind === 'loop-terminated') {\n        finalReason = event.reason;\n        finalIterations = event.totalIterations;\n        finalElapsedMs = event.totalElapsedMs;\n        finalCost = event.totalCost;\n        finalOutcomeClass = event.outcomeClass;\n      }\n    }\n\n    const result = buildLoopResult(\n      lastResult,\n      finalReason,\n      finalIterations,\n      finalElapsedMs || Date.now() - startTime,\n      handle.contextId,\n      finalCost,\n      finalOutcomeClass\n    );\n    const taskFailed = isTaskOutcomeFailure(result);\n\n    if (taskFailed) {\n      failedIds.add(task.id);\n      cleanupError = new Error(`Task terminated: ${result.terminationReason}`);\n      branch = await buildTaskBranchInfo(handle);\n      yield {\n        kind: 'task-failed',\n        source: 'task-batch',\n        task: task.message,\n        index,\n        error: `loop failed: ${result.terminationReason}`,\n        branch,\n      };\n    } else {\n      await strategy.after(handle, result);\n      await taskConfig.onTaskComplete?.(task.message, index, result);\n      branch = await buildTaskBranchInfo(handle);\n      yield {\n        kind: 'task-complete',\n        source: 'task-batch',\n        task: task.message,\n        index,\n        result,\n        branch,\n      };\n    }\n  } catch (err) {\n    cleanupError = err instanceof Error ? err : new Error(String(err));\n    failedIds.add(task.id);\n    branch ??= await buildTaskBranchInfo(handle);\n    yield {\n      kind: 'task-failed',\n      source: 'task-batch',\n      task: task.message,\n      index,\n      error: cleanupError.message,\n      branch,\n    };\n  } finally {\n    try {\n      await strategy.cleanup(handle, cleanupError);\n    } catch {\n      // cleanup is best-effort \u2014 preserve the original task failure\n    }\n  }\n}\n\nexport async function runTaskBatch(\n  executor: LoopExecutor,\n  taskConfig: TaskConfig,\n  loopConfig: LoopConfig,\n  baseContextId: string,\n  options?: BatchOptions\n): Promise<RunBatchResult<BridgeLoopResult>> {\n  const startTime = Date.now();\n  const taskResults: RunBatchResult<BridgeLoopResult>['taskResults'] = [];\n  let totalTasks = 0;\n  let completedTasks = 0;\n  let failedTasks = 0;\n\n  for await (const event of runTaskBatchStream(\n    executor,\n    taskConfig,\n    loopConfig,\n    baseContextId,\n    options\n  )) {\n    switch (event.kind) {\n      case 'task-start':\n        break;\n      case 'task-complete':\n        taskResults.push({\n          task: event.task,\n          index: event.index,\n          result: event.result as BridgeLoopResult,\n          branch: event.branch,\n        });\n        break;\n      case 'task-failed':\n        taskResults.push({\n          task: event.task,\n          index: event.index,\n          result: buildFailedResult(baseContextId),\n          error: event.error,\n          branch: event.branch,\n        });\n        break;\n      case 'task-batch-complete':\n        totalTasks = event.totalTasks;\n        completedTasks = event.completedTasks;\n        failedTasks = event.failedTasks;\n        break;\n      case 'task-batch-truncated':\n        break;\n      case 'flow-step-start':\n      case 'flow-step-complete':\n      case 'flow-terminated':\n      case 'loop-iteration':\n      case 'loop-paused':\n      case 'loop-terminated':\n        // Accumulator loop only tracks task-scoped events; nested pack/flow/loop\n        // events are surfaced by the stream consumer, not aggregated here.\n        break;\n      default:\n        assertNever(event, 'runTaskBatch event accumulator');\n    }\n  }\n\n  return {\n    kind: 'batch',\n    taskResults,\n    totalTasks,\n    completedTasks,\n    failedTasks,\n    totalElapsedMs: Date.now() - startTime,\n  };\n}\n"],
+  "mappings": "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",
+  "names": ["result"]
+}

package/dist/runtime/orchestration/run/types.d.ts

@@ -0,0 +1,250 @@
+import type { BridgeSendMessageParams } from '../../../domain/bridge-api.js';
+import type { FabricAccessor, FabricContextInjection } from '../../bridge/fabric-types.js';
+import type { BridgeLoopResult, BridgeTaskResult, FlowTerminationReason, LoopResultFields, StepOutput, TaskBranchInfo, TerminationReason } from './event-types.js';
+export type { BridgeLoopResult, BridgeTaskResult, FlowTerminationReason, LoopOutcomeClass, LoopResultFields, RunEvent, StepOutput, TaskBranchInfo, TerminationReason, } from './event-types.js';
+export interface StepInput {
+    message: string;
+    previousResults: Record<string, StepOutput>;
+    iteration: number;
+    fabric?: FabricAccessor;
+}
+export interface FlowStepInputContext {
+    originalMessage: string;
+    previousResults: Record<string, StepOutput>;
+    iteration: number;
+    step: string;
+    fabric?: FabricAccessor;
+}
+export interface LoopConfig {
+    completionPromise?: string;
+    completionPromiseMode?: 'exact' | 'includes';
+    completionConfirmations?: number;
+    maxIterations?: number;
+    maxRuntimeMs?: number;
+    maxCostUsd?: number;
+    maxConsecutiveFailures?: number;
+    staleDetection?: boolean;
+    progressMetric?: (ctx: LoopContext) => number | Promise<number>;
+    progressStaleThreshold?: number;
+    progressDirection?: 'lower-is-better' | 'higher-is-better';
+    iterationTimeoutMs?: number;
+    continuous?: boolean;
+    stopWhen?: (ctx: LoopContext) => boolean | Promise<boolean>;
+    cooldownMs?: number;
+    onIteration?: (ctx: LoopContext) => void | Promise<void>;
+    onIterationResult?: (ctx: LoopContext) => string | false | void | Promise<string | false | void>;
+    onTermination?: (reason: TerminationReason) => void | Promise<void>;
+    signal?: AbortSignal;
+    gate?: (ctx: LoopContext) => 'continue' | 'pause' | Promise<'continue' | 'pause'>;
+}
+export interface LoopContext {
+    iteration: number;
+    elapsedMs: number;
+    lastResult?: StepOutput;
+    cumulativeCost?: number;
+    consecutiveFailures: number;
+    lastOutputSignatures: string[];
+    progressMetric?: number;
+    progressStaleCount: number;
+    contextId: string;
+}
+export interface SerializedLoopConfig {
+    maxIterations?: number;
+    completionPromise?: string;
+    completionPromiseMode?: 'exact' | 'includes';
+    completionConfirmations?: number;
+    maxRuntimeMs?: number;
+    maxConsecutiveFailures?: number;
+    staleDetection?: boolean;
+    continuous?: boolean;
+    cooldownMs?: number;
+}
+export interface SerializedTaskConfig {
+    source?: {
+        type: 'message';
+        message: string;
+    } | {
+        type: 'file';
+        path: string;
+        format?: 'markdown' | 'yaml' | 'json';
+    } | {
+        type: 'list';
+        tasks: TaskItem[];
+    } | {
+        type: 'cron';
+        schedule: string;
+        message: string;
+        maxEmissions?: number;
+    };
+    isolation?: 'none' | 'context' | 'branch';
+    maxTasks?: number;
+    failFast?: boolean;
+    skipOnUpstreamFailure?: boolean;
+    concurrency?: number;
+    automation?: {
+        autoCommit?: boolean;
+        branchPerTask?: boolean;
+        commitMessage?: string;
+        branchPrefix?: string;
+        keepBranchOnFailure?: boolean;
+        baseBranch?: string;
+    };
+}
+export interface PackLoopResult extends BridgeLoopResult {
+    rounds?: Array<{
+        round: number;
+        leaderReasoning: string;
+        delegations: unknown[];
+        workerResults: unknown[];
+    }>;
+    delegationRounds: number;
+}
+export interface RunBatchResult<T extends LoopResultFields> {
+    kind: 'batch';
+    taskResults: Array<{
+        task: string;
+        index: number;
+        result: T;
+        branch?: TaskBranchInfo;
+        error?: string;
+        skipped?: boolean;
+    }>;
+    totalTasks: number;
+    completedTasks: number;
+    failedTasks: number;
+    totalElapsedMs: number;
+}
+export type BridgeRunResult = BridgeLoopResult | FlowRunResult | RunBatchResult<BridgeLoopResult>;
+export type PackRunResult = PackLoopResult | FlowRunResult | RunBatchResult<PackLoopResult>;
+export interface BridgeRunParams extends Omit<BridgeSendMessageParams, 'message'> {
+    message?: BridgeSendMessageParams['message'];
+    loop?: LoopConfig;
+    flow?: FlowConfig;
+    tasks?: TaskConfig;
+}
+export interface PackRunParams {
+    message?: BridgeSendMessageParams['message'];
+    contextId?: string;
+    loop?: LoopConfig;
+    flow?: FlowConfig;
+    tasks?: TaskConfig;
+}
+export type BridgeSessionRunParams = Omit<BridgeRunParams, 'contextId'>;
+export type PackSessionRunParams = Omit<PackRunParams, 'contextId'>;
+export interface FlowStep {
+    worker?: string;
+    fn?: (input: StepInput) => Promise<StepOutput> | StepOutput;
+    leader?: boolean;
+    timeoutMs?: number;
+    input?: (context: FlowStepInputContext) => string;
+}
+export interface FlowEdge {
+    from: string;
+    to: string | ((result: StepOutput, context: FlowContext) => string | string[]);
+}
+export interface FlowConfig {
+    steps: Record<string, FlowStep>;
+    edges: FlowEdge[];
+    maxIterations?: number;
+    onStepComplete?: (step: string, result: StepOutput) => void | Promise<void>;
+    /**
+     * Called when the flow emits a diagnostic warning (e.g. context truncation).
+     * Callers may forward this to a `bridge:warn` event or a logger.
+     */
+    onWarn?: (code: string, message: string) => void;
+    /**
+     * Merge results from parallel terminal steps into a single `lastResult`.
+     * Called when multiple steps point to END in the same parallel batch.
+     */
+    mergeResults?: (results: Record<string, StepOutput>) => StepOutput;
+    /** Configures which fabric channels are injected into LLM step messages. Opt-in only. */
+    fabricInjection?: FabricContextInjection;
+    execution?: {
+        branchMode?: 'sequential' | 'parallel';
+        maxPreviousResultChars?: number;
+        maxTotalInputChars?: number;
+        /**
+         * Only include the N most-recent step results in context messages.
+         * Default: include all previous step results.
+         */
+        maxContextSteps?: number;
+        /**
+         * When `branchMode` is `'parallel'`, controls whether the flow throws on
+         * the first step failure (`true`, default) or continues running remaining
+         * steps and only throws after all have settled (`false`).
+         */
+        failFast?: boolean;
+    };
+}
+export interface FlowContext {
+    stepResults: Record<string, StepOutput>;
+    iteration: number;
+    contextId: string;
+    fabric?: FabricAccessor;
+}
+export interface FlowRunResult extends StepOutput {
+    kind: 'flow';
+    terminationReason: FlowTerminationReason;
+    completedSteps: string[];
+    totalIterations: number;
+}
+export interface IsolationHandle {
+    contextId: string;
+    [key: string]: unknown;
+}
+export interface IsolationStrategy {
+    before(task: TaskItem, index: number, baseContextId: string): Promise<IsolationHandle>;
+    after(handle: IsolationHandle, result: BridgeLoopResult): Promise<void>;
+    cleanup(handle: IsolationHandle, error?: Error): Promise<void>;
+}
+export type TaskSource = {
+    type: 'message';
+    message: string;
+} | {
+    type: 'file';
+    path: string;
+    format?: 'markdown' | 'yaml' | 'json';
+} | {
+    type: 'custom';
+    next: () => Promise<{
+        message: string;
+    } | null>;
+} | {
+    type: 'list';
+    tasks: TaskItem[];
+} | {
+    type: 'cron';
+    schedule: string;
+    message: string | ((tick: number) => string);
+    maxEmissions?: number;
+};
+export interface TaskItem {
+    id: string;
+    message: string;
+    dependsOn?: string[];
+    priority?: number;
+}
+export interface TaskAutomation {
+    autoCommit?: boolean;
+    branchPerTask?: boolean;
+    commitMessage?: string | ((task: string) => string);
+    branchPrefix?: string;
+    keepBranchOnFailure?: boolean;
+    baseBranch?: string;
+}
+export interface TaskConfig {
+    source: TaskSource;
+    isolation?: IsolationStrategy | 'none' | 'context' | 'branch';
+    automation?: TaskAutomation;
+    maxTasks?: number;
+    failFast?: boolean;
+    skipOnUpstreamFailure?: boolean;
+    concurrency?: number;
+    onTaskStart?: (task: string, index: number) => void | Promise<void>;
+    onTaskComplete?: (task: string, index: number, result: BridgeLoopResult | PackLoopResult) => void | Promise<void>;
+}
+export type StepDispatcher = (step: FlowStep, message: string, contextId: string, 
+/** Optional abort signal forwarded from a step timeout. */
+signal?: AbortSignal) => Promise<StepOutput>;
+export type LoopExecutor = (message: string, contextId: string, iteration: number) => Promise<BridgeTaskResult>;
+//# sourceMappingURL=types.d.ts.map

package/dist/runtime/orchestration/run/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/runtime/orchestration/run/types.ts"],"names":[],"mappings":"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"}

package/dist/runtime/orchestration/run/types.js

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

package/dist/runtime/orchestration/run/types.js.map

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

package/dist/runtime/orchestration/subagent/subagent-action-types.d.ts

@@ -0,0 +1,94 @@
+import type { AgentRegistry } from '../../../adapters/agents/registry/loader.js';
+import type { AgentLineage } from '../../../adapters/agents/registry/types.js';
+import type { BridgeSubscriptionEvent } from '../../../domain/bridge-api.js';
+import type { Artifact, Message } from '../../../domain/core-task.js';
+import type { BridgePort } from '../../bridge/bridge-port.js';
+import type { ForkInheritOptions, SpawnOptions } from '../pack/coordination-types.js';
+/** Result object delivered back to the parent LLM when a subagent call completes. */
+export interface SubagentInvocationResult {
+    /** Subagent's final message text, after any `toModelOutput` transform. */
+    readonly text: string;
+    /** Registered `subagent_role` that was spawned. */
+    readonly subagentRole: string;
+    /** Child context id (useful for tracing / debugging). */
+    readonly contextId: string;
+    /** Structured artifacts produced by the child, if any. */
+    readonly artifacts?: Artifact[];
+}
+export interface SpawnAgentResult {
+    lineage: AgentLineage;
+    bridge: BridgePort;
+    contextId: string;
+    background: boolean;
+    inheritedHistory?: Message[];
+}
+/** Test seam — type of the pack-level `spawnAgent`. @internal */
+export type SpawnAgent = (parentLineage: AgentLineage, parentContextId: string, options: SpawnOptions) => Promise<SpawnAgentResult>;
+export interface CreateSubagentActionOptions {
+    /** Registry used to resolve `subagent_role` to an agent definition. */
+    readonly registry: AgentRegistry;
+    /**
+     * The parent bridge. Event emissions (`subagent:start`/`:stop`) target its
+     * event bus; lineage bookkeeping is rooted here when `parentLineage` is not
+     * supplied.
+     */
+    readonly parentBridge: BridgePort;
+    /**
+     * Lineage of the calling agent. When omitted, a fresh root lineage is
+     * minted - meaning every call is treated as depth-0 spawning depth-1.
+     */
+    readonly parentLineage?: AgentLineage;
+    /**
+     * Maximum lineage depth a spawn is allowed to reach. Default: `1` - one
+     * level of children, no grandchildren.
+     */
+    readonly maxDepth?: number;
+    /** Maximum concurrent in-flight subagent invocations on this action instance. */
+    readonly maxConcurrent?: number;
+    /** Per-invocation wall-clock timeout in ms. Default: `300_000` (5 min). */
+    readonly timeoutMs?: number;
+    /** Restrict `subagent_role` to this whitelist. */
+    readonly allowedRoles?: readonly string[];
+    /** Optional tool name override - defaults to `'task'`. */
+    readonly name?: string;
+    /**
+     * Inheritance contract for spawned subagents. Runtime, plugins, and
+     * guardrails default to inherited; history remains isolated unless enabled.
+     */
+    readonly inherit?: ForkInheritOptions;
+    /**
+     * Optional transform applied to the child's final output.
+     * Receives the full artifact list alongside text so callers can route
+     * structured child output back to the parent.
+     */
+    readonly toModelOutput?: (result: {
+        text: string;
+        taskId: string;
+        artifacts?: Artifact[];
+    }) => string;
+    /**
+     * Optional callback invoked for each streaming event from the child bridge.
+     * When provided, `stream()` is used instead of `sendMessage`, enabling
+     * progress visibility for long-running subagents.
+     */
+    readonly onChildEvent?: (subagentRole: string, event: BridgeSubscriptionEvent) => void;
+    /** Internal test seam. Prefer leaving this unset. @internal */
+    readonly _spawn?: SpawnAgent;
+}
+/** Shape of the `subagents` field on BridgeOptions. */
+export interface SubagentsBridgeOptions {
+    readonly registry?: AgentRegistry;
+    readonly maxDepth?: number;
+    readonly maxConcurrent?: number;
+    readonly timeoutMs?: number;
+    readonly allowedRoles?: readonly string[];
+    readonly name?: string;
+    readonly inherit?: ForkInheritOptions;
+    readonly toModelOutput?: (result: {
+        text: string;
+        taskId: string;
+        artifacts?: Artifact[];
+    }) => string;
+    readonly onChildEvent?: (subagentRole: string, event: BridgeSubscriptionEvent) => void;
+}
+//# sourceMappingURL=subagent-action-types.d.ts.map

package/dist/runtime/orchestration/subagent/subagent-action-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-action-types.d.ts","sourceRoot":"","sources":["../../../../src/runtime/orchestration/subagent/subagent-action-types.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1 @@
+//# sourceMappingURL=subagent-action-types.js.map

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

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

package/dist/runtime/orchestration/subagent/subagent-action.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `createSubagentAction` — the LLM-callable `task` subagent tool.
+ *
+ * Exposes an {@link ActionDefinition} that, when invoked by the model, spawns
+ * a child {@link BridgePort} via {@link spawnAgent} with a fresh context and
+ * a scoped tool surface (resolved from the {@link AgentRegistry}).
+ *
+ * Safety rails (enforced in this order per call):
+ *   1. `subagent_role` must exist in the registry AND pass `allowedRoles`.
+ *   2. `maxDepth` — reject if the spawn would exceed the configured depth.
+ *   3. `maxConcurrent` — reject if the action is already at its in-flight cap.
+ *   4. `timeoutMs` — wall-clock cap on `child.sendMessage`.
+ *
+ * Events (additive to the existing Pack-emitted pair):
+ *   * `subagent:start` — carries `subagentRole`, `depth`, and
+ *     `parentToolUseId` when the caller supplies a `toolUseId` in metadata.
+ *   * `subagent:stop`  — same fields plus `status` (`'completed' | 'failed'`).
+ *
+ * This factory is **opt-in**: not included in `loadBuiltinActions`. Callers
+ * must register it explicitly (or via the `subagentTools()` preset in
+ * `octoflow-tools`).
+ */
+import type { ActionDefinition } from '../../../actions/types.js';
+import type { CreateSubagentActionOptions } from './subagent-action-types.js';
+export type { CreateSubagentActionOptions, SubagentInvocationResult, SubagentsBridgeOptions, } from './subagent-action-types.js';
+export declare function createSubagentAction(opts: CreateSubagentActionOptions): ActionDefinition;
+//# sourceMappingURL=subagent-action.d.ts.map

package/dist/runtime/orchestration/subagent/subagent-action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-action.d.ts","sourceRoot":"","sources":["../../../../src/runtime/orchestration/subagent/subagent-action.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAkBlE,OAAO,KAAK,EACV,2BAA2B,EAG5B,MAAM,4BAA4B,CAAC;AAEpC,YAAY,EACV,2BAA2B,EAC3B,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,4BAA4B,CAAC;AA8CpC,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,2BAA2B,GAChC,gBAAgB,CA0NlB"}