@sisu-ai/mw-orchestration 0.2.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,85 @@
+# @sisu-ai/mw-orchestration
+
+Orchestration middleware for delegated multi-agent execution in Sisu.
+
+## Install
+
+```bash
+pnpm add @sisu-ai/mw-orchestration
+```
+
+## What it does
+
+- Constrains orchestrator control actions to `delegateTask` and `finish`
+- Delegates child work using a strict 4-tuple (`instruction`, `context`, `tools`, `model`)
+- Tracks runtime state in `ctx.state.orchestration`
+- Supports pluggable child executors (built-in inline executor included)
+- Emits explicit orchestration events for tracing/observability
+
+## Policy hooks and self-correction
+
+The middleware supports pluggable policy hooks so behavior can be hardened without example-specific logic:
+
+- `normalizeDelegationInput(raw, ctx)`
+- `validateDelegation(input, ctx)`
+- `resolveToolScope(input, ctx)`
+- `modelResolver(modelRef, ctx)`
+
+Delegation failures use a structured error contract (`code`, `message`, `hint`, `details`) so models can self-correct on the next `delegateTask` call.
+
+## Flow
+
+```mermaid
+flowchart TD
+  U[User Task] --> O[Orchestrator Middleware]
+  O -->|delegateTask| C[Child Executor]
+  C --> CC[Scoped Child Context\n instruction + context + tools + model]
+  CC --> R[DelegationResult]
+  R --> O
+  O -->|finish| A[Final Assistant Answer]
+```
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant P as Parent Orchestrator
+  participant M as Parent Model
+  participant E as Child Executor
+  participant CM as Child Model
+  participant T as Scoped Tools
+
+  P->>M: generate(messages, control tools)
+  M-->>P: assistant tool_call(delegateTask)
+  P->>E: execute(request 4-tuple)
+  E->>CM: generate(child messages, scoped tools)
+  CM-->>E: tool_call(s)
+  E->>T: invoke allowed tools only
+  T-->>E: tool results
+  E-->>P: DelegationResult(status, output, telemetry, trace)
+  P->>M: continue with tool message(result)
+  M-->>P: tool_call(finish)
+  P-->>P: append final assistant answer
+```
+
+## Usage
+
+```ts
+import { Agent } from "@sisu-ai/core";
+import { orchestration } from "@sisu-ai/mw-orchestration";
+
+const app = new Agent()
+  .use(
+    orchestration({
+      allowedModels: ["gpt-4o-mini"],
+      maxDelegations: 6,
+      defaultTimeoutMs: 30_000,
+    }),
+  );
+```
+
+## Integration notes
+
+- Use with `@sisu-ai/mw-register-tools` to expose parent tool registry for child scoping.
+- Child executions are compatible with `@sisu-ai/mw-tool-calling` style tool semantics.
+- Usage rollup can consume metrics written by `@sisu-ai/mw-usage-tracker`.
+- Traces can be viewed with `@sisu-ai/mw-trace-viewer` using parent-child run linkage in orchestration state.

package/dist/index.d.ts

@@ -0,0 +1,153 @@
+import { type Ctx, type LLM, type Middleware, type Usage } from "@sisu-ai/core";
+export type DelegationStatus = "ok" | "error" | "cancelled" | "timeout";
+export type DelegationContext = {
+    messages?: Array<{
+        role: "system" | "user" | "assistant" | "tool";
+        content: string;
+    }>;
+    memoryKeys?: string[];
+    artifacts?: Array<{
+        type: string;
+        value: string;
+    }>;
+};
+export type DelegationToolScope = {
+    allow: string[];
+};
+export type DelegationModelRef = {
+    name: string;
+    provider?: "openai" | "anthropic" | "ollama" | string;
+    opts?: Record<string, unknown>;
+};
+export type DelegateTaskInput = {
+    instruction: string;
+    context: DelegationContext;
+    tools: DelegationToolScope;
+    model?: DelegationModelRef;
+    metadata?: Record<string, unknown>;
+};
+export type DelegateTaskOptions = {
+    timeoutMs?: number;
+    maxChildTurns?: number;
+    idempotencyKey?: string;
+};
+export type ChildExecutionRequest = {
+    delegationId: string;
+    input: DelegateTaskInput;
+    options?: DelegateTaskOptions;
+};
+export interface DelegationResult {
+    delegationId: string;
+    status: DelegationStatus;
+    output?: {
+        summary: string;
+        answer?: string;
+        artifacts?: Array<{
+            type: string;
+            value: string;
+        }>;
+        citations?: string[];
+    };
+    telemetry: {
+        startedAt: string;
+        endedAt: string;
+        durationMs: number;
+        model: string;
+        toolsAllowed: string[];
+        toolsUsed: string[];
+        usage?: Usage;
+    };
+    trace: {
+        runId: string;
+        parentRunId: string;
+        file?: string;
+    };
+    error?: {
+        name: string;
+        message: string;
+        code?: string;
+        retryable?: boolean;
+        hint?: string;
+        details?: Record<string, unknown>;
+    };
+}
+export type DelegationValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+    retryable?: boolean;
+    hint?: string;
+    details?: Record<string, unknown>;
+};
+export interface OrchestrationState {
+    version: 1;
+    runId: string;
+    depth: number;
+    maxDepth: number;
+    status: "running" | "finished" | "aborted" | "error";
+    steps: Array<{
+        stepId: string;
+        type: "delegate" | "finish";
+        startedAt: string;
+        endedAt?: string;
+        status: "ok" | "error" | "cancelled" | "timeout";
+        delegationId?: string;
+    }>;
+    children: Record<string, {
+        delegationId: string;
+        parentRunId: string;
+        instruction: string;
+        toolScope: string[];
+        model: string;
+        status: "running" | "ok" | "error" | "cancelled" | "timeout";
+        usage?: Usage;
+        trace?: {
+            runId: string;
+            file?: string;
+        };
+        error?: {
+            message: string;
+            code?: string;
+            retryable?: boolean;
+            hint?: string;
+        };
+    }>;
+    totals: {
+        delegations: number;
+        succeeded: number;
+        failed: number;
+        durationMs: number;
+        promptTokens?: number;
+        completionTokens?: number;
+        totalTokens?: number;
+        costUSD?: number;
+    };
+    policy: {
+        allowParallel: boolean;
+        defaultTimeoutMs: number;
+        allowedModels: string[];
+    };
+}
+export type ChildExecutor = (request: ChildExecutionRequest, parentCtx: Ctx) => Promise<DelegationResult>;
+export interface OrchestrationOptions {
+    allowedModels?: string[];
+    maxDepth?: number;
+    maxDelegations?: number;
+    defaultTimeoutMs?: number;
+    maxChildTurns?: number;
+    maxCorrectionRetries?: number;
+    childExecutor?: ChildExecutor;
+    modelResolver?: (modelRef: DelegationModelRef, parentCtx: Ctx) => LLM;
+    normalizeDelegationInput?: (rawInput: unknown, ctx: Ctx) => unknown;
+    validateDelegation?: (input: DelegateTaskInput, ctx: Ctx) => DelegationValidationResult;
+    resolveToolScope?: (input: DelegateTaskInput, ctx: Ctx) => string[];
+}
+export declare const orchestration: (opts?: OrchestrationOptions) => Middleware;
+export declare function createInlineChildExecutor(opts: {
+    defaultTimeoutMs: number;
+    maxChildTurns: number;
+    allowedModels: string[];
+    modelResolver?: (modelRef: DelegationModelRef, parentCtx: Ctx) => LLM;
+}): ChildExecutor;

package/dist/index.js

@@ -0,0 +1,573 @@
+import { randomUUID } from "crypto";
+import { NullStream, SimpleTools, } from "@sisu-ai/core";
+import { z } from "zod";
+const delegateTaskSchema = z.object({
+    instruction: z.string().min(1),
+    context: z
+        .object({
+        messages: z
+            .array(z.object({
+            role: z.enum(["system", "user", "assistant", "tool"]),
+            content: z.string(),
+        }))
+            .optional(),
+        memoryKeys: z.array(z.string()).optional(),
+        artifacts: z
+            .array(z.object({ type: z.string(), value: z.string() }))
+            .optional(),
+    })
+        .default({}),
+    tools: z.object({ allow: z.array(z.string()).min(1) }),
+    model: z.object({
+        name: z.string().min(1),
+        provider: z.string().optional(),
+        opts: z.record(z.string(), z.unknown()).optional(),
+    }).optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+});
+const finishSchema = z.object({
+    answer: z.string().min(1),
+    confidence: z.number().min(0).max(1).optional(),
+    notes: z.string().optional(),
+});
+export const orchestration = (opts = {}) => {
+    const maxDepth = opts.maxDepth ?? 1;
+    const maxDelegations = opts.maxDelegations ?? 8;
+    const defaultTimeoutMs = opts.defaultTimeoutMs ?? 30_000;
+    const maxChildTurns = opts.maxChildTurns ?? 8;
+    const maxCorrectionRetries = opts.maxCorrectionRetries ?? 2;
+    return async (ctx, next) => {
+        await next();
+        const state = ensureState(ctx, {
+            maxDepth,
+            defaultTimeoutMs,
+            allowedModels: opts.allowedModels ?? [],
+        });
+        const runStartedAt = Date.now();
+        if (state.depth > state.maxDepth) {
+            throw new Error(`[orchestration] depth ${state.depth} exceeds maxDepth ${state.maxDepth}`);
+        }
+        const childExecutor = opts.childExecutor ??
+            createInlineChildExecutor({
+                defaultTimeoutMs,
+                maxChildTurns,
+                allowedModels: opts.allowedModels ?? [],
+                modelResolver: opts.modelResolver,
+            });
+        let delegations = 0;
+        let correctionRetries = 0;
+        while (!ctx.signal.aborted) {
+            if (delegations > maxDelegations) {
+                throw new Error(`[orchestration] max delegations reached (${maxDelegations})`);
+            }
+            const out = await ctx.model.generate(ctx.messages, {
+                signal: ctx.signal,
+                toolChoice: "auto",
+                tools: [delegateControlTool, finishControlTool],
+                parallelToolCalls: false,
+            });
+            const msg = out.message;
+            const calls = Array.isArray(msg.tool_calls) ? msg.tool_calls : [];
+            if (calls.length === 0) {
+                ctx.messages.push(msg);
+                state.status = "finished";
+                state.totals.durationMs = Date.now() - runStartedAt;
+                return;
+            }
+            ctx.messages.push(msg);
+            for (const call of calls) {
+                if (call.name === "delegateTask") {
+                    delegations += 1;
+                    const stepId = randomUUID();
+                    const stepStart = new Date().toISOString();
+                    state.steps.push({
+                        stepId,
+                        type: "delegate",
+                        startedAt: stepStart,
+                        status: "ok",
+                        delegationId: call.id,
+                    });
+                    ctx.log.info?.("[orchestration] delegate.start", {
+                        stepId,
+                        delegationId: call.id,
+                    });
+                    const result = await runDelegation(call, ctx, state, childExecutor, defaultTimeoutMs, maxChildTurns, opts);
+                    const step = state.steps[state.steps.length - 1];
+                    step.status = result.status;
+                    step.endedAt = new Date().toISOString();
+                    if (result.status === "ok") {
+                        state.totals.succeeded += 1;
+                    }
+                    else {
+                        state.totals.failed += 1;
+                    }
+                    state.totals.delegations += 1;
+                    aggregateUsage(state, result.telemetry.usage);
+                    state.children[result.delegationId] = {
+                        delegationId: result.delegationId,
+                        parentRunId: result.trace.parentRunId,
+                        instruction: readInstructionFromArgs(call.arguments) ?? "delegated task",
+                        toolScope: result.telemetry.toolsAllowed,
+                        model: result.telemetry.model,
+                        status: result.status,
+                        usage: result.telemetry.usage,
+                        trace: { runId: result.trace.runId, file: result.trace.file },
+                        error: result.error
+                            ? {
+                                message: result.error.message,
+                                code: result.error.code,
+                                retryable: result.error.retryable,
+                                hint: result.error.hint,
+                            }
+                            : undefined,
+                    };
+                    if (result.status === "error" && result.error?.retryable) {
+                        correctionRetries += 1;
+                        if (correctionRetries > maxCorrectionRetries) {
+                            throw new Error(`[orchestration] correction retries exceeded (${maxCorrectionRetries})`);
+                        }
+                    }
+                    else {
+                        correctionRetries = 0;
+                    }
+                    ctx.log.info?.("[orchestration] delegate.result", {
+                        stepId,
+                        delegationId: result.delegationId,
+                        status: result.status,
+                        error: result.error?.message,
+                    });
+                    const toolMessage = {
+                        role: "tool",
+                        content: JSON.stringify(result),
+                        ...(call.id ? { tool_call_id: call.id } : { name: call.name }),
+                    };
+                    ctx.messages.push(toolMessage);
+                    continue;
+                }
+                if (call.name === "finish") {
+                    const parsed = finishSchema.parse(call.arguments);
+                    const stepId = randomUUID();
+                    state.steps.push({
+                        stepId,
+                        type: "finish",
+                        startedAt: new Date().toISOString(),
+                        endedAt: new Date().toISOString(),
+                        status: "ok",
+                    });
+                    ctx.log.info?.("[orchestration] finish", {
+                        stepId,
+                        confidence: parsed.confidence,
+                    });
+                    ctx.messages.push({ role: "assistant", content: parsed.answer });
+                    state.status = "finished";
+                    state.totals.durationMs = Date.now() - runStartedAt;
+                    return;
+                }
+                throw new Error(`[orchestration] unsupported control tool call: ${call.name}`);
+            }
+        }
+        state.status = "aborted";
+    };
+};
+const delegateControlTool = {
+    name: "delegateTask",
+    description: "Delegate specialized execution with a 4-tuple: instruction, context, tools, model",
+    schema: delegateTaskSchema,
+    handler: async () => ({ ok: true }),
+};
+const finishControlTool = {
+    name: "finish",
+    description: "Finish orchestration and return final answer",
+    schema: finishSchema,
+    handler: async () => ({ ok: true }),
+};
+async function runDelegation(call, ctx, state, childExecutor, defaultTimeoutMs, maxChildTurns, opts) {
+    const delegationId = call.id || randomUUID();
+    const normalized = (opts.normalizeDelegationInput ?? normalizeDelegationInput)(call.arguments, ctx);
+    const parsed = delegateTaskSchema.safeParse(normalized);
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((issue) => ({
+            path: issue.path.join("."),
+            code: issue.code,
+            message: issue.message,
+        }));
+        return buildErrorResult(delegationId, state.runId, {
+            name: "DelegationValidationError",
+            code: "SCHEMA_INVALID",
+            message: parsed.error.message,
+            retryable: true,
+            hint: "Use delegateTask arguments as { instruction, context?: { messages?: [] }, tools: { allow: string[] }, model?: { name: string } }",
+            details: { issues },
+        });
+    }
+    const input = parsed.data;
+    if (!input.model) {
+        input.model = { name: ctx.model.name };
+    }
+    input.tools.allow =
+        opts.resolveToolScope?.(input, ctx) ?? input.tools.allow;
+    const policy = opts.validateDelegation?.(input, ctx) ?? defaultValidateDelegation(input, ctx);
+    if (!policy.ok) {
+        return buildErrorResult(delegationId, state.runId, {
+            name: "DelegationPolicyError",
+            code: policy.code,
+            message: policy.message,
+            retryable: policy.retryable ?? true,
+            hint: policy.hint,
+            details: policy.details,
+        });
+    }
+    const request = {
+        delegationId,
+        input,
+        options: {
+            timeoutMs: defaultTimeoutMs,
+            maxChildTurns,
+        },
+    };
+    try {
+        return await childExecutor(request, ctx);
+    }
+    catch (error) {
+        const err = error;
+        return buildErrorResult(delegationId, state.runId, {
+            name: err.name || "DelegationExecutionError",
+            code: "EXECUTOR_FAILED",
+            message: err.message,
+            retryable: false,
+            details: { model: input.model?.name, tools: input.tools.allow },
+        });
+    }
+}
+export function createInlineChildExecutor(opts) {
+    return async (request, parentCtx) => {
+        const startedAt = new Date();
+        const parentState = ensureState(parentCtx, {
+            maxDepth: 1,
+            defaultTimeoutMs: opts.defaultTimeoutMs,
+            allowedModels: opts.allowedModels,
+        });
+        const input = request.input;
+        validateScope(parentCtx, input, opts.allowedModels);
+        const modelRef = input.model ?? { name: parentCtx.model.name };
+        input.model = modelRef;
+        const model = opts.modelResolver?.(modelRef, parentCtx) ?? resolveModel(modelRef, parentCtx);
+        const childRunId = randomUUID();
+        const parentRunId = parentState.runId;
+        const timeoutMs = request.options?.timeoutMs ?? opts.defaultTimeoutMs;
+        const childSignal = withTimeoutSignal(parentCtx.signal, timeoutMs);
+        const childCtx = buildChildCtx(parentCtx, {
+            model,
+            signal: childSignal,
+            runId: childRunId,
+            parentRunId,
+            input,
+        });
+        const run = await executeChild(childCtx, request.options?.maxChildTurns ?? opts.maxChildTurns);
+        const endedAt = new Date();
+        const usage = getUsage(childCtx);
+        const durationMs = endedAt.getTime() - startedAt.getTime();
+        const abortReason = childSignal.aborted ? String(childSignal.reason ?? "") : "";
+        const status = childSignal.aborted
+            ? abortReason.includes("timed out")
+                ? "timeout"
+                : "cancelled"
+            : "ok";
+        return {
+            delegationId: request.delegationId,
+            status,
+            output: {
+                summary: run.summary,
+                answer: run.answer,
+            },
+            telemetry: {
+                startedAt: startedAt.toISOString(),
+                endedAt: endedAt.toISOString(),
+                durationMs,
+                model: model.name,
+                toolsAllowed: input.tools.allow,
+                toolsUsed: Array.from(run.toolsUsed),
+                usage,
+            },
+            trace: {
+                runId: childRunId,
+                parentRunId,
+            },
+        };
+    };
+}
+function normalizeDelegationInput(rawInput, _ctx) {
+    if (!rawInput || typeof rawInput !== "object")
+        return rawInput;
+    const input = { ...rawInput };
+    if (!input.context || typeof input.context !== "object") {
+        input.context = {};
+    }
+    const tools = input.tools;
+    if (typeof tools === "string") {
+        input.tools = { allow: [tools] };
+    }
+    else if (Array.isArray(tools)) {
+        input.tools = {
+            allow: tools.filter((tool) => typeof tool === "string"),
+        };
+    }
+    else if (tools && typeof tools === "object") {
+        const scope = tools;
+        if (typeof scope.allow === "string") {
+            input.tools = { allow: [scope.allow] };
+        }
+    }
+    if (typeof input.model === "string") {
+        input.model = { name: input.model };
+    }
+    return input;
+}
+function defaultValidateDelegation(input, ctx) {
+    if (!Array.isArray(input.tools.allow) || input.tools.allow.length === 0) {
+        return {
+            ok: false,
+            code: "TOOLS_INVALID",
+            message: "Delegation requires at least one allowed tool.",
+            retryable: true,
+            hint: "Set tools.allow to a non-empty string array.",
+        };
+    }
+    for (const toolName of input.tools.allow) {
+        if (!ctx.tools.get(toolName)) {
+            return {
+                ok: false,
+                code: "TOOLS_NOT_ALLOWED",
+                message: `Unknown tool '${toolName}' in delegation scope.`,
+                retryable: true,
+                hint: "Use only tools registered in the parent context.",
+                details: {
+                    toolName,
+                    availableTools: ctx.tools.list().map((tool) => tool.name),
+                },
+            };
+        }
+    }
+    return { ok: true };
+}
+function buildErrorResult(delegationId, parentRunId, error) {
+    return {
+        delegationId,
+        status: "error",
+        telemetry: {
+            startedAt: new Date().toISOString(),
+            endedAt: new Date().toISOString(),
+            durationMs: 0,
+            model: "unknown",
+            toolsAllowed: [],
+            toolsUsed: [],
+        },
+        trace: {
+            runId: randomUUID(),
+            parentRunId,
+        },
+        error,
+    };
+}
+function ensureState(ctx, defaults) {
+    const existing = ctx.state.orchestration;
+    if (existing)
+        return existing;
+    const state = {
+        version: 1,
+        runId: randomUUID(),
+        depth: 0,
+        maxDepth: defaults.maxDepth,
+        status: "running",
+        steps: [],
+        children: {},
+        totals: {
+            delegations: 0,
+            succeeded: 0,
+            failed: 0,
+            durationMs: 0,
+            promptTokens: 0,
+            completionTokens: 0,
+            totalTokens: 0,
+            costUSD: 0,
+        },
+        policy: {
+            allowParallel: false,
+            defaultTimeoutMs: defaults.defaultTimeoutMs,
+            allowedModels: defaults.allowedModels,
+        },
+    };
+    ctx.state.orchestration = state;
+    return state;
+}
+function validateScope(parentCtx, input, allowedModels) {
+    const modelName = input.model?.name ?? parentCtx.model.name;
+    if (allowedModels.length > 0 && !isModelAllowed(modelName, allowedModels)) {
+        throw new Error(`[orchestration] model '${modelName}' is not allowed`);
+    }
+    for (const toolName of input.tools.allow) {
+        if (!parentCtx.tools.get(toolName)) {
+            throw new Error(`[orchestration] unknown delegated tool '${toolName}'`);
+        }
+    }
+}
+function resolveModel(modelRef, parentCtx) {
+    if (modelRef.name && parentCtx.model.name !== modelRef.name) {
+        throw new Error(`[orchestration] unable to resolve model '${modelRef.name}' without modelResolver`);
+    }
+    return parentCtx.model;
+}
+function buildChildCtx(parentCtx, opts) {
+    const tools = new SimpleTools();
+    for (const name of opts.input.tools.allow) {
+        const tool = parentCtx.tools.get(name);
+        if (tool)
+            tools.register(tool);
+    }
+    const baseMessages = (opts.input.context.messages ?? []).map((m) => ({ role: m.role, content: m.content }));
+    baseMessages.push({ role: "user", content: opts.input.instruction });
+    const childState = {
+        ...parentCtx.state,
+        orchestration: {
+            ...parentCtx.state.orchestration,
+            runId: opts.runId,
+            depth: Number(parentCtx.state.orchestration
+                ?.depth ?? 0) + 1,
+            parentRunId: opts.parentRunId,
+        },
+    };
+    return {
+        input: opts.input.instruction,
+        messages: baseMessages,
+        model: opts.model,
+        tools,
+        memory: parentCtx.memory,
+        stream: new NullStream(),
+        state: childState,
+        signal: opts.signal,
+        log: parentCtx.log,
+    };
+}
+async function executeChild(childCtx, maxChildTurns) {
+    const toolsUsed = new Set();
+    for (let turn = 0; turn < maxChildTurns; turn++) {
+        if (childCtx.signal.aborted)
+            break;
+        const out = await childCtx.model.generate(childCtx.messages, {
+            signal: childCtx.signal,
+            toolChoice: "auto",
+            tools: childCtx.tools.list(),
+            parallelToolCalls: false,
+        });
+        const msg = out.message;
+        const calls = Array.isArray(msg.tool_calls) ? msg.tool_calls : [];
+        if (calls.length === 0) {
+            childCtx.messages.push(msg);
+            const answer = typeof msg.content === "string" ? msg.content : "";
+            return { answer, summary: answer.slice(0, 400), toolsUsed };
+        }
+        childCtx.messages.push(msg);
+        for (const call of calls) {
+            const tool = childCtx.tools.get(call.name);
+            if (!tool) {
+                throw new Error(`[orchestration] child unknown tool '${call.name}'`);
+            }
+            toolsUsed.add(call.name);
+            const parsedArgs = tool.schema && hasParse(tool.schema)
+                ? tool.schema.parse(call.arguments)
+                : call.arguments;
+            const toolCtx = {
+                memory: childCtx.memory,
+                signal: childCtx.signal,
+                log: childCtx.log,
+                model: childCtx.model,
+                deps: childCtx.state.toolDeps,
+            };
+            const result = await tool.handler(parsedArgs, toolCtx);
+            const toolMessage = {
+                role: "tool",
+                content: JSON.stringify(result),
+                ...(call.id ? { tool_call_id: call.id } : { name: call.name }),
+            };
+            childCtx.messages.push(toolMessage);
+        }
+    }
+    const answer = "";
+    return { answer, summary: answer, toolsUsed };
+}
+function hasParse(value) {
+    return Boolean(value &&
+        typeof value === "object" &&
+        "parse" in value &&
+        typeof value.parse === "function");
+}
+function getUsage(ctx) {
+    const usage = ctx.state.usage;
+    if (!usage)
+        return undefined;
+    return {
+        promptTokens: usage.promptTokens,
+        completionTokens: usage.completionTokens,
+        totalTokens: usage.totalTokens,
+        costUSD: usage.costUSD,
+    };
+}
+function aggregateUsage(state, usage) {
+    if (!usage)
+        return;
+    state.totals.promptTokens =
+        Number(state.totals.promptTokens ?? 0) + Number(usage.promptTokens ?? 0);
+    state.totals.completionTokens =
+        Number(state.totals.completionTokens ?? 0) +
+            Number(usage.completionTokens ?? 0);
+    state.totals.totalTokens =
+        Number(state.totals.totalTokens ?? 0) + Number(usage.totalTokens ?? 0);
+    state.totals.costUSD =
+        Number(state.totals.costUSD ?? 0) + Number(usage.costUSD ?? 0);
+}
+function withTimeoutSignal(signal, timeoutMs) {
+    if (timeoutMs <= 0)
+        return signal;
+    const ac = new AbortController();
+    const onParentAbort = () => ac.abort(signal.reason);
+    signal.addEventListener("abort", onParentAbort, { once: true });
+    const timer = setTimeout(() => {
+        ac.abort(new Error("Delegation timed out"));
+    }, timeoutMs);
+    ac.signal.addEventListener("abort", () => {
+        clearTimeout(timer);
+        signal.removeEventListener("abort", onParentAbort);
+    }, { once: true });
+    if (signal.aborted)
+        ac.abort(signal.reason);
+    return ac.signal;
+}
+function readInstructionFromArgs(args) {
+    if (!args || typeof args !== "object")
+        return undefined;
+    const instruction = args.instruction;
+    return typeof instruction === "string" ? instruction : undefined;
+}
+function isModelAllowed(modelName, allowedModels) {
+    if (allowedModels.includes(modelName))
+        return true;
+    const normalizedRequested = normalizeModelName(modelName);
+    return allowedModels.some((allowed) => {
+        if (allowed === modelName)
+            return true;
+        const normalizedAllowed = normalizeModelName(allowed);
+        return normalizedAllowed === normalizedRequested;
+    });
+}
+function normalizeModelName(modelName) {
+    const trimmed = modelName.trim();
+    if (!trimmed)
+        return trimmed;
+    const slashIdx = trimmed.lastIndexOf("/");
+    const colonIdx = trimmed.lastIndexOf(":");
+    const splitIdx = Math.max(slashIdx, colonIdx);
+    if (splitIdx >= 0 && splitIdx < trimmed.length - 1) {
+        return trimmed.slice(splitIdx + 1);
+    }
+    return trimmed;
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@sisu-ai/mw-orchestration",
+  "version": "0.2.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/finger-gun/sisu",
+    "directory": "packages/middleware/orchestration"
+  },
+  "homepage": "https://github.com/finger-gun/sisu#readme",
+  "bugs": {
+    "url": "https://github.com/finger-gun/sisu/issues"
+  },
+  "dependencies": {
+    "zod": "^3.23.8"
+  },
+  "peerDependencies": {
+    "@sisu-ai/core": "2.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.1",
+    "vitest": "^3.2.4",
+    "@sisu-ai/core": "2.3.1"
+  },
+  "keywords": [
+    "sisu",
+    "ai",
+    "ai-agent",
+    "agentic",
+    "middleware",
+    "orchestration"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "rm -rf dist",
+    "lint": "eslint src --ext .ts,.js",
+    "lint:fix": "eslint src --ext .ts,.js --fix",
+    "typecheck": "tsc --noEmit"
+  }
+}