@namzu/sdk 46.0.0 → 48.1.0

package/dist/agents/examples/PipelineAgent.js

@@ -0,0 +1,242 @@
+/**
+ * A developer-authored step list, and deliberately not a model-authored
+ * one.
+ *
+ * The proposal this answers is a model that emits an orchestration SCRIPT --
+ * `agent()`, `parallel()`, `pipeline()` as globals -- executed in an
+ * isolate, so that control flow between steps costs no model turns.
+ *
+ * The saving is real and this class already realises most of it: the steps
+ * below run with zero model turns between them, and `SupervisorAgent`
+ * delegates without one. What a script would add is orchestration a
+ * developer did not anticipate, invented at runtime -- which is also the
+ * case where a wrong one is hardest to review before it runs.
+ *
+ * The blocking question is the trust boundary, not the value. `bash` from
+ * a model is mediated by `packages/sandbox` because code from a model is
+ * untrusted; a model-authored script is the same input through another
+ * door, and a strictly more powerful one, since it can call back into the
+ * agent surface. Running it in-process would leave the kernel's one clear
+ * confinement boundary covering the weaker case and not the stronger. So
+ * an isolate is mandatory rather than an optimisation, and the capability
+ * costs a second execution surface to secure, audit and version.
+ *
+ * That is the bar a reopen has to clear.
+ */
+import { withTokenBudget } from '../../provider/token-budget.js';
+import { ZERO_COST } from '../../utils/cost.js';
+import { toErrorMessage } from '../../utils/error.js';
+import { generateMessageId } from '../../utils/id.js';
+import { AbstractAgent } from '../AbstractAgent.js';
+import { resolveAgentBudget } from '../budget.js';
+/** @deprecated Example of developer-authored fixed-step orchestration. */
+export class PipelineAgent extends AbstractAgent {
+    type = 'pipeline';
+    constructor(metadata, log) {
+        super({
+            ...metadata,
+            type: 'pipeline',
+            capabilities: {
+                supportsTools: false,
+                supportsStreaming: false,
+                supportsConcurrency: false,
+                supportsSubAgents: false,
+            },
+        }, log);
+    }
+    /**
+     * One turn at a time per instance.
+     *
+     * `abortController` and `currentSessionId` are instance state, so two
+     * overlapping turns share one abort controller — cancelling either kills
+     * both — and the second clobbers the first's session, so a later
+     * `cancel()` cancels the wrong children. Neither failure announces itself.
+     * A host that wants parallelism constructs a second instance.
+     */
+    async run(input, config, listener) {
+        return await this.underIdempotencyKey(config.idempotencyKey, () => this.underInvocationLock(() => this.runExclusive(input, config, listener)));
+    }
+    async runExclusive(input, config, listener) {
+        if (config.sandbox) {
+            throw new Error('PipelineAgent cannot enforce a turn-level sandbox around developer-authored step callbacks. Configure confinement inside each step or use a tool-running agent.');
+        }
+        const startTime = Date.now();
+        const sessionId = this.resolveSessionId(config.sessionId);
+        const turnId = this.createTurnId();
+        this.bindTurn(sessionId, turnId, config.logger);
+        const budget = await resolveAgentBudget(input, config, { sessionId, turnId });
+        const settlement = (status, iterations) => ({
+            status,
+            iterations,
+            usage: budget.ownUsage,
+            cost: { ...ZERO_COST, unpricedTokens: budget.ownTokens },
+            durationMs: Date.now() - startTime,
+            resultSource: 'model',
+            abandonedTaskIds: [],
+            abandonedJobIds: [],
+        });
+        const provider = config.provider ? withTokenBudget(config.provider, budget) : undefined;
+        try {
+            const stepResults = [];
+            const previousResults = new Map();
+            let completedSteps = 0;
+            await this.emitEvent(turnStarted(sessionId, turnId, config, budget), listener);
+            let currentInput = input.messages
+                .filter((m) => m.role === 'user')
+                .map((m) => m.content)
+                .filter((c) => c !== null)
+                .join('\n');
+            for (let i = 0; i < config.steps.length; i++) {
+                const step = config.steps[i];
+                if (!step)
+                    throw new Error(`Pipeline step at index ${i} is undefined`);
+                const stepStart = Date.now();
+                if (this.abortController.signal.aborted) {
+                    stepResults.push({
+                        stepName: step.name,
+                        status: 'skipped',
+                        durationMs: 0,
+                    });
+                    continue;
+                }
+                await this.emitEvent({ type: 'iteration_started', sessionId, turnId, iteration: i + 1 }, listener);
+                const context = {
+                    sessionId,
+                    turnId,
+                    stepIndex: i,
+                    totalSteps: config.steps.length,
+                    previousResults,
+                    provider,
+                    budget,
+                    signal: this.abortController.signal,
+                    env: config.env ?? {},
+                };
+                try {
+                    if (step.validate && !step.validate(currentInput)) {
+                        throw new Error(`Validation failed for step "${step.name}"`);
+                    }
+                    const output = await step.execute(currentInput, context);
+                    previousResults.set(step.name, output);
+                    currentInput = output;
+                    completedSteps++;
+                    stepResults.push({
+                        stepName: step.name,
+                        status: 'completed',
+                        output,
+                        durationMs: Date.now() - stepStart,
+                    });
+                }
+                catch (err) {
+                    const errorMsg = toErrorMessage(err);
+                    stepResults.push({
+                        stepName: step.name,
+                        status: 'failed',
+                        error: errorMsg,
+                        durationMs: Date.now() - stepStart,
+                    });
+                    if (step.rollback) {
+                        try {
+                            await step.rollback(currentInput, context);
+                        }
+                        catch (rollbackErr) {
+                            this.log.error('Rollback failed for a step', {
+                                'namzu.pipeline.step_name': step.name,
+                                'exception.message': toErrorMessage(rollbackErr),
+                            });
+                        }
+                    }
+                    if (!config.continueOnError) {
+                        await this.emitEvent({
+                            type: 'turn_failed',
+                            sessionId,
+                            turnId,
+                            error: errorMsg,
+                            budget: budget.summary(),
+                            settlement: settlement('failed', i + 1),
+                        }, listener);
+                        return {
+                            sessionId,
+                            turnId,
+                            status: 'failed',
+                            stopReason: 'error',
+                            usage: budget.ownUsage,
+                            budget: budget.summary(),
+                            cost: { ...ZERO_COST, unpricedTokens: budget.ownTokens },
+                            iterations: i + 1,
+                            durationMs: Date.now() - startTime,
+                            messages: input.messages,
+                            lastError: errorMsg,
+                            stepResults,
+                            completedSteps,
+                            totalSteps: config.steps.length,
+                        };
+                    }
+                }
+            }
+            const finalStatus = completedSteps === config.steps.length ? 'completed' : 'failed';
+            const lastOutput = stepResults[stepResults.length - 1]?.output;
+            const result = typeof lastOutput === 'string' ? lastOutput : JSON.stringify(lastOutput);
+            // A pipeline that finished with failed steps (under `continueOnError`)
+            // did not complete its turn, so it settles as `turn_failed`: the
+            // terminal verdict is the event type (spec §2.10).
+            await this.emitEvent(finalStatus === 'completed'
+                ? {
+                    type: 'turn_completed',
+                    sessionId,
+                    turnId,
+                    budget: budget.summary(),
+                    result,
+                    stopReason: 'end_turn',
+                    settlement: settlement('completed', config.steps.length),
+                }
+                : {
+                    type: 'turn_failed',
+                    sessionId,
+                    turnId,
+                    budget: budget.summary(),
+                    error: `${config.steps.length - completedSteps} of ${config.steps.length} pipeline steps failed`,
+                    settlement: settlement('failed', config.steps.length),
+                }, listener);
+            return {
+                sessionId,
+                turnId,
+                status: finalStatus,
+                stopReason: 'end_turn',
+                usage: budget.ownUsage,
+                budget: budget.summary(),
+                cost: { ...ZERO_COST, unpricedTokens: budget.ownTokens },
+                iterations: config.steps.length,
+                durationMs: Date.now() - startTime,
+                messages: input.messages,
+                result,
+                stepResults,
+                completedSteps,
+                totalSteps: config.steps.length,
+            };
+        }
+        finally {
+            budget.settle();
+            await budget.flush();
+        }
+    }
+}
+/**
+ * The turn a pipeline runs, announced the way `query()` announces one. The
+ * user message id names the input the steps were handed; nothing is written
+ * to a session log, because the steps are callbacks, not model calls.
+ */
+function turnStarted(sessionId, turnId, config, budget) {
+    return {
+        type: 'turn_started',
+        sessionId,
+        turnId,
+        userMessageId: generateMessageId(),
+        config: {
+            model: config.model,
+            tokenBudget: config.tokenBudget,
+            timeoutMs: config.timeoutMs,
+        },
+        ...(budget.binding ? { budget: budget.binding } : {}),
+    };
+}
+//# sourceMappingURL=PipelineAgent.js.map

package/dist/agents/examples/PipelineAgent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PipelineAgent.js","sourceRoot":"","sources":["../../../src/agents/examples/PipelineAgent.ts"],"names":[],"mappings":"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"}

package/dist/agents/examples/RouterAgent.d.ts

@@ -0,0 +1,22 @@
+import type { AgentInput, AgentMetadata, RouterAgentConfig, RouterAgentResult } from '../../types/agent/index.js';
+import type { SessionEventListener } from '../../types/session/events.js';
+import type { Logger } from '../../utils/logger.js';
+import { AbstractAgent } from '../AbstractAgent.js';
+/** @deprecated Example of developer-authored routing. */
+export declare class RouterAgent extends AbstractAgent<RouterAgentConfig, RouterAgentResult> {
+    readonly type: "router";
+    constructor(metadata: Omit<AgentMetadata, 'type' | 'capabilities'>, log?: Logger);
+    /**
+     * One turn at a time per instance.
+     *
+     * `abortController` and `currentSessionId` are instance state, so two
+     * overlapping turns share one abort controller — cancelling either kills
+     * both — and the second clobbers the first's session, so a later
+     * `cancel()` cancels the wrong children. Neither failure announces itself.
+     * A host that wants parallelism constructs a second instance.
+     */
+    run(input: AgentInput, config: RouterAgentConfig, listener?: SessionEventListener): Promise<RouterAgentResult>;
+    private runExclusive;
+    private route;
+}
+//# sourceMappingURL=RouterAgent.d.ts.map

package/dist/agents/examples/RouterAgent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RouterAgent.d.ts","sourceRoot":"","sources":["../../../src/agents/examples/RouterAgent.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACX,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EAEjB,MAAM,4BAA4B,CAAA;AAKnC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAA;AAEzE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAA;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAGnD,yDAAyD;AACzD,qBAAa,WAAY,SAAQ,aAAa,CAAC,iBAAiB,EAAE,iBAAiB,CAAC;IACnF,QAAQ,CAAC,IAAI,EAAG,QAAQ,CAAS;gBAErB,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,cAAc,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM;IAgBhF;;;;;;;;OAQG;IACG,GAAG,CACR,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,iBAAiB,EACzB,QAAQ,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,iBAAiB,CAAC;YAMf,YAAY;YA2HZ,KAAK;CAwJnB"}

package/dist/agents/examples/RouterAgent.js

@@ -0,0 +1,268 @@
+import { EMPTY_TOKEN_USAGE } from '../../constants/limits.js';
+import { collectChatCompletion } from '../../provider/collect-chat-completion.js';
+import { resolveStreamIdleTimeoutMs, withStreamIdleTimeout } from '../../provider/idle-timeout.js';
+import { withTokenBudget } from '../../provider/token-budget.js';
+import { FallbackResolver } from '../../runtime/decision/fallback.js';
+import { DecisionParser } from '../../runtime/decision/parser.js';
+import { accumulateTokenUsage } from '../../types/common/index.js';
+import { deriveChildState } from '../../types/invocation/index.js';
+import { createSystemMessage, createUserMessage } from '../../types/message/index.js';
+import { ZERO_COST } from '../../utils/cost.js';
+import { AbstractAgent } from '../AbstractAgent.js';
+import { resolveAgentBudget } from '../budget.js';
+/** @deprecated Example of developer-authored routing. */
+export class RouterAgent extends AbstractAgent {
+    type = 'router';
+    constructor(metadata, log) {
+        super({
+            ...metadata,
+            type: 'router',
+            capabilities: {
+                supportsTools: false,
+                supportsStreaming: true,
+                supportsConcurrency: false,
+                supportsSubAgents: true,
+            },
+        }, log);
+    }
+    /**
+     * One turn at a time per instance.
+     *
+     * `abortController` and `currentSessionId` are instance state, so two
+     * overlapping turns share one abort controller — cancelling either kills
+     * both — and the second clobbers the first's session, so a later
+     * `cancel()` cancels the wrong children. Neither failure announces itself.
+     * A host that wants parallelism constructs a second instance.
+     */
+    async run(input, config, listener) {
+        return await this.underIdempotencyKey(config.idempotencyKey, () => this.underInvocationLock(() => this.runExclusive(input, config, listener)));
+    }
+    async runExclusive(input, config, listener) {
+        // Resolve before a turn id/event exists, matching query(): malformed
+        // liveness policy is a caller config error, not a failed model turn.
+        const streamIdleTimeoutMs = resolveStreamIdleTimeoutMs(config.streamIdleTimeoutMs);
+        const signal = input.signal
+            ? AbortSignal.any([input.signal, this.abortController.signal])
+            : this.abortController.signal;
+        const startTime = Date.now();
+        const sessionId = this.resolveSessionId(config.sessionId);
+        const turnId = this.createTurnId();
+        this.bindTurn(sessionId, turnId, config.logger);
+        const budget = await resolveAgentBudget(input, config, { sessionId, turnId });
+        const budgetConfig = { ...config, budget };
+        // No lifecycle events of its own. A `turn_*` event names a turn in a
+        // session log, and routing writes none: the delegate below runs the
+        // session's turn and emits its lifecycle, and the listener receives
+        // exactly that turn rather than a synthetic one wrapped around it.
+        try {
+            const decision = await this.route(input, budgetConfig, streamIdleTimeoutMs, signal);
+            let targetRoute = config.routes.find((r) => r.agentId === decision.agentId);
+            if (!targetRoute) {
+                const fallback = config.fallbackAgentId
+                    ? config.routes.find((r) => r.agentId === config.fallbackAgentId)
+                    : undefined;
+                if (!fallback) {
+                    const errorMsg = `No route found for "${decision.agentId}"`;
+                    return {
+                        sessionId,
+                        turnId,
+                        status: 'failed',
+                        stopReason: 'error',
+                        usage: budget.ownUsage,
+                        budget: budget.summary(),
+                        cost: { ...ZERO_COST, unpricedTokens: budget.ownTokens },
+                        iterations: 1,
+                        durationMs: Date.now() - startTime,
+                        messages: input.messages,
+                        lastError: errorMsg,
+                        selectedRoute: decision.agentId,
+                        routingDecision: decision,
+                        delegateResult: {
+                            sessionId,
+                            turnId,
+                            status: 'failed',
+                            usage: { ...EMPTY_TOKEN_USAGE },
+                            cost: { ...ZERO_COST },
+                            iterations: 0,
+                            durationMs: 0,
+                            messages: [],
+                        },
+                    };
+                }
+                decision.agentId = fallback.agentId;
+                targetRoute = fallback;
+            }
+            if (!config.invocationState) {
+                throw new Error('RouterAgent requires invocationState with tenantId in config (session-hierarchy.md §12.1).');
+            }
+            const childInvocationState = deriveChildState(config.invocationState, this.metadata.id);
+            const allocation = Number.isFinite(budget.remaining)
+                ? Math.floor(budget.remaining)
+                : config.tokenBudget || 200_000;
+            const childBudget = budget.reserve(allocation);
+            await childBudget.flush();
+            let delegateResult;
+            try {
+                delegateResult = await targetRoute.agent.run(input, {
+                    ...config,
+                    budget: childBudget,
+                    tokenBudget: allocation,
+                    // The same session: the delegate runs this session's turn,
+                    // it is not a child session of it.
+                    sessionId,
+                    depth: (config.depth ?? 0) + 1,
+                    invocationState: childInvocationState,
+                }, listener);
+                childBudget.bindTurn(delegateResult.sessionId, delegateResult.turnId);
+                childBudget.settle(delegateResult.usage.totalTokens);
+            }
+            finally {
+                // A thrown custom delegate supplies no final usage receipt.
+                // Its reservation stays held until an authoritative settlement.
+                await childBudget.flush();
+            }
+            return {
+                sessionId,
+                turnId: delegateResult.turnId,
+                status: delegateResult.status,
+                stopReason: delegateResult.stopReason,
+                usage: budget.ownUsage,
+                budget: budget.summary(),
+                cost: { ...ZERO_COST, unpricedTokens: budget.ownTokens },
+                iterations: delegateResult.iterations + 1,
+                durationMs: Date.now() - startTime,
+                messages: delegateResult.messages,
+                result: delegateResult.result,
+                lastError: delegateResult.lastError,
+                selectedRoute: decision.agentId,
+                routingDecision: decision,
+                delegateResult,
+            };
+        }
+        finally {
+            budget.settle();
+            await budget.flush();
+        }
+    }
+    async route(input, config, streamIdleTimeoutMs, signal) {
+        // `this.log`, not a fresh `getRootLogger()` child — bound by `bindTurn`
+        // in `runExclusive` before this is called, so a routing warning below
+        // carries the SAME `namzu.turn.id` as the turn it is routing. The old
+        // independent construction here is the exact bug LOG-10's acceptance
+        // criterion names: a route() log line with no id at all.
+        const log = this.log;
+        const validAgentIds = config.routes.map((r) => r.agentId);
+        const fallbackAgentId = config.fallbackAgentId ?? config.routes[0]?.agentId ?? '';
+        const minConfidence = config.minConfidence ?? 0;
+        const maxRetries = config.maxRoutingRetries ?? 1;
+        const parser = new DecisionParser({
+            validAgentIds,
+            minConfidence,
+            maxRetries,
+            fallbackAgentId,
+        }, log);
+        const fallbackStrategies = [];
+        const patternMap = new Map();
+        for (const route of config.routes) {
+            if (route.matchPatterns && route.matchPatterns.length > 0) {
+                patternMap.set(route.agentId, route.matchPatterns);
+            }
+        }
+        if (patternMap.size > 0) {
+            fallbackStrategies.push({ type: 'pattern_match', patterns: patternMap });
+        }
+        if (config.fallbackAgentId) {
+            fallbackStrategies.push({
+                type: 'fixed',
+                agentId: config.fallbackAgentId,
+            });
+        }
+        fallbackStrategies.push({ type: 'first_route' });
+        const fallbackResolver = new FallbackResolver(fallbackStrategies, log);
+        const routeDescriptions = config.routes
+            .map((r) => `- ${r.agentId}: ${r.description}`)
+            .join('\n');
+        const prompt = config.routingPrompt ??
+            `Given the user's request, select the most appropriate agent.\n\nAvailable agents:\n${routeDescriptions}\n\nRespond with JSON only: { "agentId": "<id>", "confidence": <0-1>, "reasoning": "<why>" }`;
+        const userContent = input.messages
+            .filter((m) => m.role === 'user')
+            .map((m) => m.content)
+            .filter((c) => c !== null)
+            .join('\n');
+        // Every routing attempt is a billed model call; a fallback after
+        // three failed parses still cost three calls.
+        let routingUsage = { ...EMPTY_TOKEN_USAGE };
+        const routingProvider = withStreamIdleTimeout(config.budget ? withTokenBudget(config.provider, config.budget) : config.provider, {
+            idleTimeoutMs: streamIdleTimeoutMs,
+            log,
+        });
+        for (let attempt = 0; attempt < maxRetries; attempt++) {
+            try {
+                const response = await collectChatCompletion(routingProvider.chatStream({
+                    model: config.model,
+                    messages: [createSystemMessage(prompt), createUserMessage(userContent)],
+                    temperature: 0,
+                    maxTokens: 200,
+                    signal,
+                }));
+                routingUsage = accumulateTokenUsage(routingUsage, response.usage);
+                const parseResult = parser.parse(response.message.content);
+                if (parseResult.ok && parseResult.source === 'parsed') {
+                    return {
+                        agentId: parseResult.decision.agentId,
+                        confidence: parseResult.decision.confidence,
+                        reasoning: parseResult.decision.reasoning,
+                        routingSource: 'provider',
+                        usage: routingUsage,
+                    };
+                }
+                if (parseResult.ok && parseResult.source === 'fallback') {
+                    log.warn('Routing attempt fell back', {
+                        'namzu.router.attempt': attempt + 1,
+                        'namzu.agents.reason': parseResult.reason,
+                        'namzu.agents.decision': parseResult.decision,
+                    });
+                    if (attempt === maxRetries - 1) {
+                        return {
+                            agentId: parseResult.decision.agentId,
+                            confidence: parseResult.decision.confidence,
+                            reasoning: parseResult.decision.reasoning,
+                            routingSource: 'fallback',
+                            usage: routingUsage,
+                        };
+                    }
+                    continue;
+                }
+                if (!parseResult.ok) {
+                    log.warn('Routing attempt failed to parse', {
+                        'namzu.router.attempt': attempt + 1,
+                        'exception.message': parseResult.error,
+                    });
+                    if (attempt === maxRetries - 1) {
+                        break;
+                    }
+                }
+            }
+            catch (err) {
+                // Provider-idle expiry aborts only the wrapper's private transport
+                // and is eligible for the router's declared fallback. A caller or
+                // agent cancellation owns this fused signal and must not be
+                // reinterpreted as permission to start a delegate.
+                if (signal.aborted)
+                    throw signal.reason;
+                log.warn('Routing LLM call failed', {
+                    'namzu.router.attempt': attempt + 1,
+                    'exception.message': String(err),
+                });
+                if (attempt === maxRetries - 1) {
+                    break;
+                }
+            }
+        }
+        return {
+            ...fallbackResolver.resolve(userContent, validAgentIds),
+            usage: routingUsage,
+        };
+    }
+}
+//# sourceMappingURL=RouterAgent.js.map

package/dist/agents/examples/RouterAgent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RouterAgent.js","sourceRoot":"","sources":["../../../src/agents/examples/RouterAgent.ts"],"names":[],"mappings":"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"}

package/dist/agents/examples/SupervisorAgent.d.ts

@@ -0,0 +1,45 @@
+import type { AgentInput, AgentMetadata, AgentTaskResult, SupervisorAgentConfig, SupervisorAgentResult } from '../../types/agent/index.js';
+import type { TaskHandle } from '../../types/agent/scheduler.js';
+import type { SessionId, TurnId } from '../../types/ids/index.js';
+import type { SessionEventListener } from '../../types/session/events.js';
+import type { Logger } from '../../utils/logger.js';
+import { AbstractAgent } from '../AbstractAgent.js';
+/**
+ * Build the authoritative per-task ledger from the gateway's task handles.
+ *
+ * A handle carries a `result` only when its worker actually produced one. A
+ * handle with NO result never produced a verifiable outcome, so it MUST NOT be
+ * synthesized as a success: the synthesized status is always the terminal
+ * `'failed'`, regardless of the handle's reported `state` (which may itself be
+ * `'completed'`).
+ *
+ * The earlier implementation cast `handle.state` onto the synthesized result's
+ * status, letting a worker that ended without a result count toward
+ * `completedTasks`. That produced fabricated "done" workers with empty outputs
+ * (observed in a live supervised session): the supervisor reported "3 workers done, 40KB
+ * reports" when the workers never started. Real workers (those with a present
+ * `result`) are unaffected — their `result` is preserved verbatim.
+ */
+export declare function synthesizeTaskResults(taskHandles: readonly TaskHandle[], turn: {
+    readonly sessionId: SessionId;
+    readonly turnId: TurnId;
+}, now?: number): AgentTaskResult[];
+/** Count only the task results that genuinely completed. */
+export declare function countCompletedTasks(taskResults: readonly AgentTaskResult[]): number;
+/** @deprecated Example of supervised delegation; hosts can compose their own agent. */
+export declare class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, SupervisorAgentResult> {
+    readonly type: "supervisor";
+    constructor(metadata: Omit<AgentMetadata, 'type' | 'capabilities'>, log?: Logger);
+    /**
+     * One turn at a time per instance.
+     *
+     * `abortController` and `currentSessionId` are instance state, so two
+     * overlapping turns share one abort controller — cancelling either kills
+     * both — and the second clobbers the first's session, so a later
+     * `cancel()` cancels the wrong children. Neither failure announces itself.
+     * A host that wants parallelism constructs a second instance.
+     */
+    run(input: AgentInput, config: SupervisorAgentConfig, listener?: SessionEventListener): Promise<SupervisorAgentResult>;
+    private runExclusive;
+}
+//# sourceMappingURL=SupervisorAgent.d.ts.map

package/dist/agents/examples/SupervisorAgent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SupervisorAgent.d.ts","sourceRoot":"","sources":["../../../src/agents/examples/SupervisorAgent.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACX,UAAU,EACV,aAAa,EACb,eAAe,EACf,qBAAqB,EACrB,qBAAqB,EACrB,MAAM,4BAA4B,CAAA;AACnC,OAAO,KAAK,EAAE,UAAU,EAAiB,MAAM,gCAAgC,CAAA;AAE/E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAA;AAGjE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAA;AAGzE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAA;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAInD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACpC,WAAW,EAAE,SAAS,UAAU,EAAE,EAClC,IAAI,EAAE;IAAE,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAChE,GAAG,GAAE,MAAmB,GACtB,eAAe,EAAE,CAenB;AAED,4DAA4D;AAC5D,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,SAAS,eAAe,EAAE,GAAG,MAAM,CAEnF;AAED,uFAAuF;AACvF,qBAAa,eAAgB,SAAQ,aAAa,CAAC,qBAAqB,EAAE,qBAAqB,CAAC;IAC/F,QAAQ,CAAC,IAAI,EAAG,YAAY,CAAS;gBAEzB,QAAQ,EAAE,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,cAAc,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM;IAgBhF;;;;;;;;OAQG;IACG,GAAG,CACR,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,qBAAqB,EAC7B,QAAQ,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,qBAAqB,CAAC;YAMnB,YAAY;CAuW1B"}