@alvin0/ai-agent-sdk-core 0.1.0

package/dist/agent/team/managed.d.ts

@@ -0,0 +1,527 @@
+import { ToolDefinition } from "../tool/definition.js";
+import { HistoryEntry, HistorySnapshot } from "../history/types.js";
+import { ToolCatalog } from "../tool/registry.js";
+import { ModelRegistry } from "../../runtime/registry.js";
+import { AgentRunEvent } from "../mode/run-agent.js";
+import { DefinedAgent } from "../define/definition.js";
+import { AgentInput, AgentInvocationOptions, AgentResponse, AgentSessionOptions } from "../define/session/types.js";
+import { AgentSession } from "../define/session.js";
+import { AgentTeamOptions } from "./types.js";
+import { AgentTeam } from "./team.js";
+//#region src/agent/team/managed.d.ts
+type DetachedSessionOptions = Omit<AgentSessionOptions, 'registry' | 'team' | 'tools'>;
+/**
+ * Default bound on getting one worker RUNNING, overridable per harness with
+ * {@link ManagedAgentTeamOptions.spawnTimeoutMs}.
+ *
+ * Not the worker's deadline — that is `workerTimeoutMs`. This bounds only the
+ * setup, so a lead cannot be held for minutes by a call that no longer waits
+ * for any work.
+ */
+declare const DEFAULT_SPAWN_SETUP_TIMEOUT_MS = 30000;
+/** Default bound on stopping one worker; see {@link ManagedAgentTeamOptions.closeTimeoutMs}. */
+declare const DEFAULT_WORKER_CLOSE_TIMEOUT_MS = 30000;
+/**
+ * How much of the lead's conversation a new worker starts from.
+ *
+ * `fresh` is one task and nothing else. `fork` copies the lead's completed
+ * conversation so far, so the worker begins already knowing what the lead
+ * learned — the state of the workspace, the decisions taken, what the other
+ * workers were given.
+ *
+ * The distinction exists because its absence is expensive in a specific way.
+ * With only a task string, every worker re-derives the same context from
+ * scratch: three workers spawned into an empty repository each listed the
+ * directory, each concluded independently that nothing was there, and each
+ * decided on its own to scaffold it. Both reference implementations offer the
+ * same choice — Codex as `fork_context`/`fork_turns`, the DeepSeek harness as
+ * `context: 'fresh' | 'fork'`, whose naming this follows.
+ */
+type ManagedAgentSpawnContext = 'fresh' | 'fork';
+/**
+ * A worker kind the host declares up front.
+ *
+ * Without a declared set, `specialty` is free text the model invents at the
+ * moment it spawns: the harness is handed `"Code review, accessibility,
+ * security và quality audit"` and can make nothing of it — not that the role
+ * reads rather than writes, not that it needs code to exist first. So it
+ * cannot help order the work, and the lead is left inventing both the role and
+ * its place in the plan in the same breath.
+ *
+ * Declaring roles turns that into a choice from a list the host wrote, with
+ * `whenToUse` stating the precondition in the spawn schema where the lead
+ * reads it. Codex does the same thing with `agent_type` and its role registry.
+ */
+interface ManagedAgentRole {
+  /** Referred to by `spawn_agent`; the enum the lead chooses from. */
+  readonly name: string;
+  /** What this role is for. Shown to the lead in the spawn tool schema. */
+  readonly description: string;
+  /** When choosing it is correct — and when it is premature. */
+  readonly whenToUse?: string;
+  /** Added to the worker's own instructions; defaults to `description`. */
+  readonly instructions?: string;
+}
+/** What to do about two workers that would write the same files at once. */
+type WriteScopeConflictPolicy = 'reject' | 'warn' | 'off';
+interface ManagedAgentSpawnRequest {
+  /** Optional stable team address; generated as worker_N when omitted. */
+  readonly name?: string;
+  readonly task: string;
+  /** Short specialization added to the generated worker's instructions. */
+  readonly specialty?: string;
+  /**
+   * Context the worker starts from; defaults to
+   * {@link ManagedAgentTeamOptions.defaultSpawnContext}.
+   */
+  readonly context?: ManagedAgentSpawnContext;
+  /** One of {@link ManagedAgentTeamOptions.roles}, when the host declared any. */
+  readonly role?: string;
+  /**
+   * Workers that must finish before this one starts.
+   *
+   * The harness holds it back until every one of them has settled, and then
+   * gives it what they produced. This is the difference between dividing
+   * agents and dividing work: a lead can spawn the whole plan in one step —
+   * which is what it wants to do — and the ORDER is still respected, because
+   * ordering is no longer something the model has to remember to enforce by
+   * spawning late.
+   *
+   * A dependency that fails still releases its dependents, and they are told
+   * it failed. Waiting only for success turns one broken worker into a
+   * permanently stalled plan.
+   */
+  readonly dependsOn?: readonly string[];
+  /**
+   * Files and directories this worker may write, workspace-relative.
+   *
+   * Declared so the harness can refuse a division that cannot work. Two
+   * workers given overlapping scopes with no ordering between them will both
+   * write those files, and the later write erases the earlier one — observed
+   * as a UI worker announcing it would put its logic in the very page
+   * component the logic worker had been assigned.
+   */
+  readonly writes?: readonly string[];
+}
+interface ResolvedManagedAgentSpawnRequest extends ManagedAgentSpawnRequest {
+  readonly name: string;
+  readonly context: ManagedAgentSpawnContext;
+  readonly dependsOn: readonly string[];
+  readonly writes: readonly string[];
+}
+interface ManagedAgentWorkerResult {
+  readonly worker: string;
+  readonly agentId: string;
+  readonly conversationId: string;
+  readonly text: string;
+  readonly succeeded: boolean;
+}
+/**
+ * Where a generated worker is in its life.
+ *
+ * `completed` and `failed` are final but NOT gone: a finished worker stays
+ * addressable and keeps occupying a `maxWorkers` slot until it is closed, so
+ * a lead that spawns without closing runs out of workers rather than silently
+ * accumulating them.
+ */
+type ManagedAgentWorkerStatus = 'pending' | 'running' | 'completed' | 'failed' | 'closed';
+interface ManagedAgentWorker {
+  readonly name: string;
+  readonly agentId: string;
+  readonly conversationId: string;
+  readonly task: string;
+  readonly specialty?: string;
+  /** Context this worker was started from. */
+  readonly context: ManagedAgentSpawnContext;
+  readonly role?: string;
+  /** Workers that had to settle before this one could start. */
+  readonly dependsOn: readonly string[];
+  /** Files this worker declared it would write. */
+  readonly writes: readonly string[];
+  readonly status: ManagedAgentWorkerStatus;
+  /** Non-fatal problems with the division of work, e.g. an accepted overlap. */
+  readonly warnings?: readonly string[];
+  readonly result?: ManagedAgentWorkerResult;
+  readonly error?: string;
+}
+interface ManagedAgentTeamOptions {
+  readonly registry: ModelRegistry;
+  readonly lead: DefinedAgent;
+  readonly leadName?: string;
+  readonly leadDescription?: string;
+  readonly team?: AgentTeam | AgentTeamOptions;
+  readonly maxWorkers?: number;
+  /** Maximum UTF-8 worker task bytes. Defaults to 64 KiB. */
+  readonly maxTaskBytes?: number;
+  /** Maximum UTF-8 specialty bytes. Defaults to 8 KiB. */
+  readonly maxSpecialtyBytes?: number;
+  /**
+   * Context a `spawn_agent` call starts a worker from when it does not say.
+   * Defaults to `'fresh'`.
+   *
+   * `'fresh'` is the default because forking is not free: the worker pays for
+   * the lead's whole conversation in input tokens on every round it runs, and
+   * a worker whose task genuinely stands alone gains nothing for it. A host
+   * that knows its workers always operate on the lead's workspace — and so
+   * would otherwise watch each of them rediscover it — should set `'fork'`
+   * here rather than hope the lead remembers to ask.
+   */
+  readonly defaultSpawnContext?: ManagedAgentSpawnContext;
+  /**
+   * Worker kinds the lead may choose from, with what each is for.
+   *
+   * Declaring them replaces free-text `specialty` with an enum, and puts each
+   * role's `whenToUse` in the spawn schema — the one place the lead is certain
+   * to read before choosing. Leave it unset and `specialty` behaves as before.
+   */
+  readonly roles?: readonly ManagedAgentRole[];
+  /**
+   * What to do when a spawn declares `writes` overlapping a worker that would
+   * run at the same time. Defaults to `'reject'`.
+   *
+   * Rejecting is the default because the alternative is silent data loss: both
+   * workers write the file and the later write wins. The refusal names the
+   * conflicting worker and the overlap, so the lead's available fix — add it
+   * to `dependsOn`, or narrow the scope — is visible in the error itself.
+   * `'warn'` records it on the worker instead and lets it run; `'off'` skips
+   * the check.
+   */
+  readonly writeScopePolicy?: WriteScopeConflictPolicy;
+  /**
+   * Cap on how much of a dependency's result is handed to its dependents.
+   * Defaults to 8 KiB per dependency.
+   */
+  readonly maxDependencyReportBytes?: number;
+  /** End-to-end deadline for one generated worker. Defaults to 10 minutes. */
+  readonly workerTimeoutMs?: number;
+  /** Maximum wait per worker event observer callback. Defaults to 1 second. */
+  readonly observerTimeoutMs?: number;
+  /**
+   * How long closing one worker waits for it to stop.
+   * Defaults to {@link DEFAULT_WORKER_CLOSE_TIMEOUT_MS}.
+   *
+   * After that its slot is freed regardless. A worker that ignores its
+   * cancellation must not be able to hold the harness at its cap forever.
+   */
+  readonly closeTimeoutMs?: number;
+  /**
+   * How long the lead's turn is held open waiting for a worker to report,
+   * before the lead is asked again. Defaults to {@link DEFAULT_HOLD_WAIT_MS}.
+   *
+   * Zero-length would be a spin: the lead answers, is told its workers are
+   * still running, answers again, and burns its budget before any result
+   * arrives. Codex blocks the parent inside its `wait_agent` tool for the same
+   * reason.
+   */
+  readonly holdWaitMs?: number;
+  /** Allow model-invoked close_agent to cancel unfinished work (default true).
+   * Host closeWorker, disposal and user cancellation are always available. */
+  readonly allowModelWorkerCancellation?: boolean;
+  /**
+   * How long `spawn_agent` may take to get a worker running.
+   * Defaults to {@link DEFAULT_SPAWN_SETUP_TIMEOUT_MS}.
+   *
+   * Only the setup: the worker's own deadline is `workerTimeoutMs`, and how
+   * long the lead may WAIT for it is the team's `waitTimeoutMs` — pass it
+   * through `team: { waitTimeoutMs }` when building the harness.
+   */
+  readonly spawnTimeoutMs?: number;
+  /** Defaults to cloning the lead definition under the generated worker id. */
+  readonly workerTemplate?: DefinedAgent;
+  readonly workerFactory?: (request: ResolvedManagedAgentSpawnRequest) => DefinedAgent | Promise<DefinedAgent>;
+  readonly leadSessionOptions?: DetachedSessionOptions & {
+    readonly tools?: ToolCatalog | readonly ToolDefinition<any>[];
+  };
+  readonly workerSessionOptions?: DetachedSessionOptions & {
+    readonly tools?: ToolCatalog | readonly ToolDefinition<any>[];
+  };
+  /** Per-worker runtime dependencies for least-privilege tools and workspace policy. */
+  readonly workerSessionOptionsFactory?: (request: ResolvedManagedAgentSpawnRequest) => (DetachedSessionOptions & {
+    readonly tools?: ToolCatalog | readonly ToolDefinition<any>[];
+  }) | Promise<DetachedSessionOptions & {
+    readonly tools?: ToolCatalog | readonly ToolDefinition<any>[];
+  }>;
+  /** Observe every generated worker's model, tool, trace, and compaction events. */
+  readonly onWorkerEvent?: (worker: string, event: AgentRunEvent) => void | Promise<void>;
+}
+/**
+ * A dynamic harness whose lead can create specialized workers with spawn_agent.
+ *
+ * `spawn_agent` blocks the lead for as long as its worker runs, so it declares
+ * that blocking to the team as a wait edge. Cycle detection is only as good as
+ * the graph it can see: an unrecorded edge does not merely go unchecked, it
+ * lets the cycle it completes through, and a worker waiting for the lead that
+ * is waiting for it deadlocks both until a timeout.
+ *
+ * Each worker is a real connected AgentSession and remains addressable afterward.
+ */
+declare class ManagedAgentTeam {
+  readonly team: AgentTeam;
+  readonly lead: AgentSession;
+  readonly leadName: string;
+  private readonly options;
+  private readonly maxWorkers;
+  private readonly maxTaskBytes;
+  private readonly maxSpecialtyBytes;
+  private readonly workerTimeoutMs;
+  private readonly observerTimeoutMs;
+  private readonly closeTimeoutMs;
+  private readonly holdWaitMs;
+  private readonly spawnTimeoutMs;
+  private readonly workerRuntimes;
+  private readonly reservedNames;
+  private workerSequence;
+  private readonly maxDependencyReportBytes;
+  private readonly roles;
+  constructor(options: ManagedAgentTeamOptions);
+  /**
+   * Hold the lead's turn open while a worker of its is unfinished.
+   *
+   * This is Codex's shape, arrived at from the other side: there the parent
+   * stays inside its turn and loops on its wait tool until it has what it
+   * needs. A lead that concludes while its workers are still running answers
+   * from nothing — and once the turn is over, the reports that arrive
+   * afterwards have no turn left to be read in, so the work stops with no
+   * synthesis at all.
+   *
+   * `runTurn` re-runs a turn whose `onTurnEnd` hook appended history, so
+   * saying so is enough to send the lead round again. Its own step and turn
+   * budgets bound this, and `canContinue` leaves an aborted or exhausted turn
+   * free to end.
+   * @param host - Hooks the host supplied; theirs run first and are kept.
+   * @returns The hooks to give the lead's session.
+   */
+  private leadHooks;
+  /** Run the lead. It decides whether and how many workers to create. */
+  run(input: AgentInput, invocation?: AgentInvocationOptions): Promise<AgentResponse>;
+  /**
+   * Add a message to the lead's context, and make sure something reads it.
+   *
+   * Injection alone is enough only while the lead is mid-turn: its next model
+   * round rebuilds the request from history and picks the message up. Once the
+   * lead has answered and is only waiting on its workers, an injected message
+   * sits in history with nothing scheduled to read it — which is what happened
+   * to a user who typed a correction while the researchers were still running
+   * and never got an answer to it. Idle, the lead is scheduled one turn.
+   * @param text - What the user said.
+   * @returns True; the message is always accepted.
+   */
+  steer(text: string): boolean;
+  /** Host-side equivalent of the model's spawn_agent tool. */
+  /**
+   * Create a worker and start it, WITHOUT waiting for it.
+   *
+   * Returns as soon as the worker is running. Use {@link awaitWorker} for its
+   * result, {@link workers} for its status, or let the worker's completion
+   * notification reach the lead on its own.
+   * @param request - Task, and optionally a name and a specialty.
+   * @param signal - Cancels the setup, not the worker's run.
+   * @returns The worker, in its `running` state.
+   */
+  spawn(request: ManagedAgentSpawnRequest, signal?: AbortSignal): Promise<ManagedAgentWorker>;
+  /**
+   * Put a worker on the model, at last.
+   *
+   * Separate from `spawn` because a worker with dependencies is created now and
+   * started later; the two used to be the same moment.
+   */
+  private beginWorker;
+  /**
+   * The `role` parameter, when the host declared any roles.
+   *
+   * Each role's purpose and precondition go in the description, which is where
+   * Codex puts its role registry too: the lead is choosing a role at the
+   * moment it reads this, so this is the only place the guidance can arrive in
+   * time to change the choice.
+   * @returns A one-property object to spread, or nothing.
+   */
+  private roleSchema;
+  /** Resolve a declared role name, or say which ones exist. */
+  private requireRole;
+  /**
+   * Check the named dependencies and return them deduplicated.
+   *
+   * A dependency can only name a worker that already exists, and a new worker
+   * is not yet nameable by anything, so the graph cannot contain a cycle by
+   * construction — no cycle check is needed here, and a `dependsOn` that could
+   * name a future worker would need one.
+   */
+  private resolveDependencies;
+  /**
+   * Judge a new worker's write scopes against the ones already in flight.
+   *
+   * Only workers that could run AT THE SAME TIME conflict. One that this
+   * worker depends on, directly or through others, writes its files before
+   * this one begins, so sharing a scope with it is ordinary sequential work —
+   * and is in fact the fix the refusal points at.
+   * @param request - The resolved spawn request.
+   * @returns Warnings to record; throws instead under the `reject` policy.
+   */
+  private checkWriteScopes;
+  /**
+   * Say what actually happened to a worker, in words the lead can act on.
+   *
+   * A raw abort reads "The operation was aborted due to timeout", which tells
+   * the lead nothing about WHOSE timeout or whether re-delegating would help.
+   * Codex reports a status the parent can branch on; the DeepSeek harness
+   * records a blocker code with an explanation. This is the same idea at the
+   * size this harness needs.
+   * @param error - Whatever ended the run.
+   * @returns The explanation to record and report.
+   */
+  private describeWorkerFailure;
+  /** The one explanation an expired worker deadline deserves. */
+  private deadlineFailure;
+  /**
+   * Block until a worker reports, or the hold deadline passes.
+   *
+   * Bounded on purpose. An unbounded wait would hand the whole run's liveness to
+   * the slowest worker and, since this runs inside a turn hook, would be cut off
+   * by the hook timeout rather than by anything that understands the work. When
+   * it expires the lead gets its turn back and decides for itself — wait again
+   * with `wait_agents`, close one, or answer with what it has.
+   * @param outstanding - Workers that have not settled.
+   */
+  private awaitWorkerNews;
+  /** Every worker reachable through `dependsOn`, transitively. */
+  private ancestorsOf;
+  /** Whether every named worker has reached a final state. */
+  private dependenciesSettled;
+  /**
+   * Start whatever was waiting on the worker that just settled.
+   *
+   * Dependents are released when their dependencies SETTLE, not when they
+   * succeed. Requiring success would let one failed worker strand every step
+   * planned after it, and a plan that stalls silently is worse than one whose
+   * later stages are told the earlier ones broke — which is exactly what they
+   * are told: each dependent starts with what its dependencies produced.
+   */
+  private releaseDependents;
+  /** What the dependencies produced, as context for a dependent about to start. */
+  private dependencyReport;
+  /**
+   * Watch a detached worker run to its end and report it.
+   *
+   * Never rejects: the run has no awaiting caller, so a throw here would be an
+   * unhandled rejection. Failures are recorded on the runtime and told to the
+   * lead instead, which is the same shape `AgentTeam.runWakeLoop` uses for the
+   * other kind of un-awaited member run.
+   */
+  private followWorker;
+  /**
+   * Tell the lead what one of its workers did.
+   *
+   * Quiet WHILE THE LEAD IS STILL IN ITS TURN: the report appends to history
+   * and the next model round rebuilds its request from history, so the lead
+   * reads it without an extra turn being scheduled. Holding that turn open is
+   * {@link leadHooks}'s job.
+   *
+   * A wake-up once the lead has gone idle, because then nothing else will ever
+   * read the report. The hold cannot cover every case — a turn that ended on
+   * its step budget, or on an error, is not eligible to continue, and a worker
+   * that outlives the run reports into a conversation with no turn left. That
+   * is the failure this exists for: the transcript ends on a worker's own
+   * output, and the synthesis the lead was there to write never happens. One
+   * more turn is the point, not a duplicate answer.
+   */
+  private notifyLead;
+  /**
+   * Quiet into an open turn, a wake-up into an idle conversation.
+   * @param worker - The worker whose report is being delivered.
+   * @returns The delivery the report needs to actually be read.
+   */
+  private deliveryFor;
+  /** Set when a worker report was delivered quietly and no round has read it. */
+  private unreadReports;
+  /**
+   * Wait until no worker is outstanding and the lead has nothing left to do.
+   *
+   * The roster cannot answer this on its own. A worker's last event fires
+   * before its run resolves, and its completion report — the thing that wakes
+   * the lead — is delivered after that. For the moment in between, every member
+   * looks idle: a caller watching the roster sees a finished team and stops
+   * listening, exactly as the synthesis is about to be written. Waiting here
+   * covers that gap, because a worker's `settled` resolves only once its report
+   * has been delivered.
+   * @param signal - Gives up waiting; the work itself is not cancelled.
+   */
+  whenQuiet(signal?: AbortSignal): Promise<void>;
+  /** Current detached worker lifecycle view. */
+  workers(): readonly ManagedAgentWorker[];
+  private workerView;
+  /**
+   * Wait for one worker to finish, for at most `timeoutMs`.
+   *
+   * Bounded on purpose. An unbounded wait is how a host loses the ability to
+   * tell a slow worker from a stuck one; a caller that gets `undefined` back
+   * still holds every other option.
+   * @param name - Worker address.
+   * @param options - Budget, default {@link DEFAULT_WAIT_TIMEOUT_MS}, and a signal.
+   * @returns Its result, or undefined if it had not finished in time.
+   */
+  awaitWorker(name: string, options?: {
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+  }): Promise<ManagedAgentWorkerResult | undefined>;
+  /**
+   * Stop a worker and give up its slot.
+   *
+   * This is the stopping point a delegated agent otherwise lacks. A worker that
+   * has already finished is still occupying a `maxWorkers` slot, so closing is
+   * how a lead makes room for the next one.
+   * @param name - Worker address.
+   * @param reason - Cancellation reason for a worker still running.
+   * @returns The status it held before being closed.
+   */
+  closeWorker(name: string, reason?: unknown): Promise<ManagedAgentWorkerStatus>;
+  /**
+   * Stop every worker this harness started.
+   *
+   * Workers outlive the lead's turn by design, so something has to end them:
+   * without this a detached run would keep calling the model after the host had
+   * moved on. Disposing the underlying `AgentTeam` is left to whoever owns it.
+   * @param reason - Cancellation reason handed to each worker.
+   */
+  dispose(reason?: unknown): Promise<void>;
+  /** Remove one idle generated worker from the harness and shared roster. */
+  removeWorker(name: string): void;
+  private controlTools;
+  /**
+   * Build the history a `fork` worker starts from.
+   *
+   * Limits come from the WORKER's session options, not the lead's: this is the
+   * worker's own history from here on, and it is the worker's configured
+   * ceiling that has to hold it.
+   * @returns The lead's completed conversation as a fresh history.
+   */
+  private forkLeadHistory;
+  private workerDefinition;
+  private nextWorkerName;
+  private observeWorkerEvent;
+}
+declare function createManagedAgentTeam(options: ManagedAgentTeamOptions): ManagedAgentTeam;
+/**
+ * Copy the lead's conversation up to the last point it was complete.
+ *
+ * The lead is INSIDE a turn when it calls `spawn_agent`: the assistant message
+ * carrying that very call is already in history, and its result cannot be,
+ * because producing it is what this code is doing. Handing that tail to a
+ * worker gives it a conversation ending in an unanswered tool call — which
+ * providers reject, and which would turn a context optimisation into a spawn
+ * that fails outright.
+ *
+ * So the fork is cut at the last position where no tool call was outstanding.
+ * That is also the honest boundary in meaning: work still in flight is not yet
+ * something the lead knows. The DeepSeek harness names the same rule a
+ * "completed-turn prefix".
+ *
+ * A prefix is safe to hydrate as a history in its own right: `replace` surface
+ * ops and compaction records only ever reference earlier entries, so cutting
+ * from the end cannot orphan a reference.
+ * @param snapshot - The lead's history, taken mid-turn.
+ * @returns Entries up to that boundary; empty when nothing has completed.
+ */
+declare function completedHistoryPrefix(snapshot: HistorySnapshot): readonly HistoryEntry[];
+//#endregion
+export { DEFAULT_SPAWN_SETUP_TIMEOUT_MS, DEFAULT_WORKER_CLOSE_TIMEOUT_MS, ManagedAgentRole, ManagedAgentSpawnContext, ManagedAgentSpawnRequest, ManagedAgentTeam, ManagedAgentTeamOptions, ManagedAgentWorker, ManagedAgentWorkerResult, ManagedAgentWorkerStatus, ResolvedManagedAgentSpawnRequest, WriteScopeConflictPolicy, completedHistoryPrefix, createManagedAgentTeam };
+//# sourceMappingURL=managed.d.ts.map

package/dist/agent/team/managed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"managed.d.ts","names":[],"sources":["../../../src/agent/team/managed.ts"],"mappings":";;;;;;;;;;;KAuBK,yBAAyB,KAAK;;;;;;;;;cAUtB;;cAGA;;;;;;;;;;;;;;;;;KA6ED;;;;;;;;;;;;;;;UAgBK;;WAEN;;WAEA;;WAEA;;WAEA;;;KAIC;UAEK;;WAEN;WACA;;WAEA;;;;;WAKA,UAAU;;WAEV;;;;;;;;;;;;;;;WAeA;;;;;;;;;;WAUA;;UAGM,yCAAyC;WAC/C;WACA,SAAS;WACT;WACA;;UAGM;WACN;WACA;WACA;WACA;WACA;;;;;;;;;;KAWC;UAGK;WACN;WACA;WACA;WACA;WACA;;WAEA,SAAS;WACT;;WAEA;;WAEA;WACA,QAAQ;;WAER;WACA,SAAS;WACT;;UAGM;WACN,UAAU;WACV,MAAM;WACN;WACA;WACA,OAAO,YAAY;WACnB;;WAEA;;WAEA;;;;;;;;;;;;WAYA,sBAAsB;;;;;;;;WAQtB,iBAAiB;;;;;;;;;;;;WAYjB,mBAAmB;;;;;WAKnB;;WAEA;;WAEA;;;;;;;;WAQA;;;;;;;;;;WAUA;;;WAGA;;;;;;;;;WASA;;WAEA,iBAAiB;WACjB,iBACP,SAAS,qCACN,eAAe,QAAQ;WACnB,qBAAqB;aAAoC,QAAQ,uBAAuB;;WACxF,uBAAuB;aAAoC,QAAQ,uBAAuB;;;WAE1F,+BACP,SAAS,sCACL;aAAoC,QAAQ,uBAAuB;OACrE,QAAQ;aAAoC,QAAQ,uBAAuB;;;WAEtE,iBACP,gBACA,OAAO,yBACG;;;;;;;;;;;;;cAsED;WACF,MAAM;WACN,MAAM;WACN;mBACQ;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;mBACA;UACT;mBACS;mBACA;EAEjB,YAAY,SAAS;;;;;;;;;;;;;;;;;;UAyDb;;EA6DR,IAAI,OAAO,YAAY,aAAY,yBAA8B,QAAQ;;;;;;;;;;;;;EAgBzE,MAAM;;;;;;;;;;;;EAsBA,MACJ,SAAS,0BACT,SAAS,cACR,QAAQ;;;;;;;UAwHH;;;;;;;;;;UA2CA;;UAeA;;;;;;;;;UAqBA;;;;;;;;;;;UAsBA;;;;;;;;;;;;UAwCA;;UASA;;;;;;;;;;;UAeM;;UAgBN;;UAWA;;;;;;;;;;UAiBM;;UAyBN;;;;;;;;;UA2BM;;;;;;;;;;;;;;;;;UAgFA;;;;;;UAwBN;;UAWA;;;;;;;;;;;;;EAcF,UAAU,SAAS,cAAc;;EAcvC,oBAAoB;UAIZ;;;;;;;;;;;EA4BF,YACJ,cACA;aAAoB;aAA6B,SAAS;MACzD,QAAQ;;;;;;;;;;;EA4BL,YACJ,cACA,mBACC,QAAQ;;;;;;;;;EAmDL,QAAQ,mBAA6D;;EAM3E,aAAa;UAWL;;;;;;;;;UAyHA;UAQM;UAmBN;UAQM;;iBAMA,uBAAuB,SAAS,0BAA0B;;;;;;;;;;;;;;;;;;;;;;iBAuF1D,uBACd,UAAU,2BACA"}

package/dist/agent/team/managed.js

@@ -0,0 +1,4 @@
+import{waitForSettlement as e}from"../../async/settlement.js";import{timeoutValue as t}from"../../platform/config.js";import{createTextMessage as n}from"../../message/message.js";import{defineTool as r}from"../tool/definition.js";import{ToolRegistry as i}from"../tool/registry.js";import{History as a}from"../history/history.js";import{cloneAgent as o}from"../define/definition.js";import"./common.js";import{AgentTeam as s}from"./team.js";const c=3e4,l=3e4,u=15e3,d=[`You lead a managed dynamic team. Delegation buys parallelism; it is not a way to distribute a task you have not yet understood.`,`PLAN BEFORE YOU DELEGATE. State briefly what the objective needs, which steps block the others, and which can run alongside them, and decide what you will do yourself right now. Only then spawn.`,`Do the blocking step yourself. If your very next action depends on a result, producing it locally is faster than delegating it and waiting for it.`,`Delegate work that runs alongside your own: concrete, bounded, self-contained, and worth a whole worker.`,"GIVE EACH WORKER A DISJOINT SET OF FILES TO WRITE. Declare them in `writes`, and say which in its task. Two workers building different features of one file will each write that file, and the later write erases the earlier one; a spawn that would do this is refused.",'A WORKER THAT ONLY READS DECLARES NOTHING: leave `writes` out. Do not invent a placeholder such as "none" or "/tmp/no-write" — that claims a real scope, and several readers sharing one stand-in are refused for colliding over a file none of them writes.',"EXPRESS ORDER WITH `dependsOn`, NOT BY SPAWNING LATE. A worker that reviews, integrates, or builds on another names it there: it is created now, held until that work settles, and then given what it produced. Spawn the whole plan in one step and let the order be enforced rather than remembered.","Do not delegate review, audit or verification against nothing. Either the thing to be reviewed already exists, or the reviewer `dependsOn` whoever is producing it. A reviewer started over an empty workspace produces a checklist, not a review.",`When the work does not exist yet, the first step is yours: establish its shape — scaffold, layout, shared types — and then delegate the independent pieces of it.`,`Choose each worker context deliberately: fork when it needs what you have already found out, fresh when its task genuinely stands alone. Given neither, every worker rediscovers the workspace for itself.`,`Call spawn_agent several times in one step for work that is genuinely independent, and once for work that is not.`,`spawn_agent does not return a result: workers run while you keep working, and each one reports back to you when it finishes.`,`After delegating, do useful non-overlapping work. Do not wait by reflex, and do not redo what you delegated.`,`Use wait_agents only when you need a result to continue. It returns within its timeout whether or not anyone finished, so read the reported status and decide again.`,`Read a finished worker result from list_agents, then call close_agent to release its slot.`,`A send_message update or accepted self-check is not the worker final report. Wait for its completed/failed status before normal closure. Use cancelRunning only when deliberately abandoning its unfinished work.`,`Never answer as if a worker had reported when it has not; say what is still outstanding instead.`,`Synthesize worker results yourself and remain responsible for the final answer.`].join(` `);var f=class{team;lead;leadName;options;maxWorkers;maxTaskBytes;maxSpecialtyBytes;workerTimeoutMs;observerTimeoutMs;closeTimeoutMs;holdWaitMs;spawnTimeoutMs;workerRuntimes=new Map;reservedNames=new Set;workerSequence=0;maxDependencyReportBytes;roles;constructor(e){if(this.options=e,this.maxWorkers=w(e.maxWorkers??7,`maxWorkers`),this.maxTaskBytes=w(e.maxTaskBytes??65536,`maxTaskBytes`),this.maxSpecialtyBytes=w(e.maxSpecialtyBytes??8192,`maxSpecialtyBytes`),this.workerTimeoutMs=t(e.workerTimeoutMs??6e5),this.observerTimeoutMs=t(e.observerTimeoutMs??1e3),this.closeTimeoutMs=t(e.closeTimeoutMs??3e4),this.holdWaitMs=t(e.holdWaitMs??15e3),this.spawnTimeoutMs=t(e.spawnTimeoutMs??3e4),this.maxDependencyReportBytes=w(e.maxDependencyReportBytes??8192,`maxDependencyReportBytes`),this.roles=new Map((e.roles??[]).map(e=>[e.name,e])),this.roles.size!==(e.roles??[]).length)throw Error(`managed agent roles contain a duplicate name`);this.team=e.team instanceof s?e.team:new s({...e.team,maxMembers:e.team?.maxMembers??this.maxWorkers+1}),this.leadName=x(e.leadName??e.lead.id),this.lead=e.lead.createSession({...e.leadSessionOptions,hooks:this.leadHooks(e.leadSessionOptions?.hooks),registry:e.registry,tools:m(e.leadSessionOptions?.tools,this.controlTools()),team:{team:this.team,name:this.leadName,role:`lead`,instructions:d,...e.leadDescription===void 0?{}:{description:e.leadDescription}}})}leadHooks(e){return{...e,beforeStep:async t=>(this.unreadReports=!1,await e?.beforeStep?.(t)??{kind:`proceed`}),onTurnEnd:async t=>{if(await e?.onTurnEnd?.(t),!t.canContinue){if(this.unreadReports){this.unreadReports=!1;try{this.team.wake(this.leadName)}catch{}}return}let n=[...this.workerRuntimes.values()].filter(e=>e.status===`running`||e.status===`pending`);if(n.length===0)return;await this.awaitWorkerNews(n);let r=[...this.workerRuntimes.values()].filter(e=>e.status===`running`||e.status===`pending`).map(e=>e.request.name);if(r.length===0){this.lead.inject(`Every worker has reported. Read their results and write the answer you owe the user; do not delegate again unless something is genuinely missing.`);return}this.lead.inject(`Not finished: ${r.join(`, `)} ${r.length===1?`is`:`are`} still running. Use wait_agents to wait for them and read their results, or close_agent with cancelRunning: true to give up on one. Do not present a conclusion that depends on work they have not reported yet.`)}}}run(e,t={}){return this.lead.run(e,t)}steer(e){this.lead.inject(e);try{this.team.notifySteer(this.leadName)}catch{}if(!this.lead.isRunning)try{this.team.wake(this.leadName)}catch{}return!0}async spawn(e,t){t?.throwIfAborted();let r={name:x(e.name??this.nextWorkerName()),task:C(e.task,`worker task`,this.maxTaskBytes),...e.specialty===void 0?{}:{specialty:C(e.specialty,`worker specialty`,this.maxSpecialtyBytes)},context:e.context??this.options.defaultSpawnContext??`fresh`,...e.role===void 0?{}:{role:this.requireRole(e.role)},dependsOn:this.resolveDependencies(e.dependsOn??[]),writes:[...new Set((e.writes??[]).map(j))]};if(this.workerRuntimes.size+this.reservedNames.size>=this.maxWorkers)throw Error(`managed agent team reached its ${this.maxWorkers}-worker limit`);if(this.reservedNames.has(r.name)||this.workerRuntimes.has(r.name)||this.team.members().some(e=>e.name===r.name))throw Error(`managed worker '${r.name}' already exists`);this.reservedNames.add(r.name);let i;try{let e=this.checkWriteScopes(r),a=D(t,AbortSignal.timeout(this.workerTimeoutMs)),o=await E(this.workerDefinition(r),a);a.throwIfAborted();let s=this.options.workerSessionOptionsFactory===void 0?void 0:await E(Promise.resolve(this.options.workerSessionOptionsFactory(r)),a);a.throwIfAborted();let c=o.createSession({...this.options.workerSessionOptions,...s,...r.context===`fork`?{history:this.forkLeadHistory()}:{},registry:this.options.registry,team:{team:this.team,name:r.name,role:`peer`,tools:`reporting`,instructions:[`You are a dynamically created worker reporting to '${this.leadName}'.`,`Complete the delegated task independently and return a concise evidence-backed result.`,`Do not broaden the task or attempt to become team lead.`,`Your result is delivered to '${this.leadName}' when you finish, so do not use send_message to report it; that tool is only for passing context to a DIFFERENT worker, never to yourself.`,`If you lack information, state what is missing in your result rather than waiting for an answer.`].join(` `),...r.specialty===void 0?{}:{description:r.specialty}}}),l=new AbortController,u;if(i={request:r,session:c,status:`pending`,leadDriven:this.lead.isRunning,closing:!1,deadline:void 0,controller:l,settled:new Promise(e=>{u=e}),markSettled:u,start:void 0,warnings:e,result:void 0,error:void 0},this.workerRuntimes.set(r.name,i),this.reservedNames.delete(r.name),await this.team.sendMessage({from:this.leadName,target:r.name,message:r.task,delivery:`quiet`,signal:a}),o.memory.autoCaptureObjective&&c.memory.captureOriginalObjective(n(r.task)),r.dependsOn.length>0&&!this.dependenciesSettled(r.dependsOn)){let e=new Promise(e=>{i.start=e});return this.team.markPending(r.name,e),this.workerView(i)}return this.beginWorker(i),this.workerView(i)}catch(e){throw i!==void 0&&(i.status=`failed`,i.error=T(e),i.start=void 0,i.markSettled()),e}finally{this.reservedNames.delete(r.name)}}beginWorker(e){let t=e.request.name;if(e.start?.(),e.start=void 0,this.team.markPending(t,void 0),e.status!==`pending`)return;e.status=`running`;let n=AbortSignal.timeout(this.workerTimeoutMs);e.deadline=n;let r=e.session.runPending({signal:D(e.controller.signal,n),...this.options.onWorkerEvent===void 0?{}:{onEvent:e=>this.observeWorkerEvent(t,e)}});this.followWorker(e,r)}roleSchema(){if(this.roles.size===0)return{};let e=[...this.roles.values()].map(e=>`- ${e.name}: ${e.description}`+(e.whenToUse===void 0?``:` Use when: ${e.whenToUse}`));return{role:{type:`string`,enum:[...this.roles.keys()],description:`Which kind of worker this is.\n${e.join(`
+`)}`}}}requireRole(e){let t=S(e,`worker role`);if(this.roles.size===0)throw Error(`this managed team declares no roles, so spawn_agent takes no role`);if(!this.roles.has(t))throw Error(`unknown worker role '${t}'; declared roles are ${[...this.roles.keys()].join(`, `)}`);return t}resolveDependencies(e){return[...new Set(e.map(e=>{let t=x(e);if(!this.workerRuntimes.has(t))throw Error(`unknown dependency '${t}'; a worker can only depend on one that already exists`);return t}))]}checkWriteScopes(e){let t=this.options.writeScopePolicy??`reject`;if(t===`off`||e.writes.length===0)return[];let n=this.ancestorsOf(e.dependsOn),r=[];for(let i of this.workerRuntimes.values()){if(i.status!==`pending`&&i.status!==`running`||n.has(i.request.name))continue;let a=e.writes.filter(e=>i.request.writes.some(t=>M(e,t)));if(a.length===0)continue;let o=`'${i.request.name}' also writes ${a.join(`, `)}`;if(t===`reject`)throw Error(`worker '${e.name}' would write files another running worker writes: ${o}. Add '${i.request.name}' to dependsOn so it runs after, or narrow the scopes — or omit writes entirely if this worker only reads.`);r.push(o)}return r}describeWorkerFailure(e,t){if(t?.deadline?.aborted===!0)return this.deadlineFailure();let n=e?.name;return n===`TimeoutError`?this.deadlineFailure():n===`AbortError`?`its work was cancelled before it finished`:T(e)}deadlineFailure(){return`it ran past its ${String(this.workerTimeoutMs)}ms deadline without finishing. Narrow the task, or split it, before delegating it again`}async awaitWorkerNews(e){let t,n=new Promise(e=>{t=setTimeout(e,this.holdWaitMs),t.unref?.()});try{await Promise.race([...e.map(e=>e.settled),n])}finally{t!==void 0&&clearTimeout(t)}}ancestorsOf(e,t=new Set){for(let n of e){if(t.has(n))continue;t.add(n);let e=this.workerRuntimes.get(n);e!==void 0&&this.ancestorsOf(e.request.dependsOn,t)}return t}dependenciesSettled(e){return e.every(e=>{let t=this.workerRuntimes.get(e);return t===void 0||k.has(t.status)})}async releaseDependents(e){let t=[...this.workerRuntimes.values()].filter(t=>t.status===`pending`&&t.request.dependsOn.includes(e)&&this.dependenciesSettled(t.request.dependsOn));for(let e of t){let t=this.dependencyReport(e.request.dependsOn);if(t!==void 0)try{await this.team.sendMessage({from:this.leadName,target:e.request.name,message:t,delivery:`quiet`})}catch{}this.beginWorker(e)}}dependencyReport(e){let t=e.map(e=>{let t=this.workerRuntimes.get(e);if(t===void 0)return`- ${e}: closed before reporting.`;if(t.error!==void 0){let n=t.result?.text;return`- ${e} FAILED: ${t.error}`+(n?`\nPartial findings (not a completed task): ${N(n,this.maxDependencyReportBytes)}`:``)}return`- ${e} finished: ${N(t.result?.text??``,this.maxDependencyReportBytes)}`});if(t.length!==0)return[`Work you depend on has finished. Its results follow; build on them rather than redoing them.`,...t].join(`
+`)}async followWorker(e,t){let n=e.request.name;try{let r=await t;if(e.status!==`closed`&&!e.closing){let t=e.deadline?.aborted===!0?this.deadlineFailure():A(r);t===void 0?(e.status=`completed`,e.result=Object.freeze({worker:n,agentId:e.session.definition.id,conversationId:e.session.conversationId,text:r.text,succeeded:r.outcome.completed}),this.team.recordOutcome(n,{kind:`completed`,text:r.text}),await this.notifyLead(n,`finished: ${r.text}`)):(e.status=`failed`,e.error=t,r.text.trim()!==``&&(e.result=Object.freeze({worker:n,agentId:e.session.definition.id,conversationId:e.session.conversationId,text:r.text,succeeded:!1})),this.team.recordOutcome(n,{kind:`failed`,message:t}),await this.notifyLead(n,`failed: ${t}`+(e.result===void 0?``:`\nPartial findings (not a completed task): ${e.result.text}`)))}}catch(t){e.status!==`closed`&&!e.closing&&(e.status=`failed`,e.error=this.describeWorkerFailure(t,e),this.team.recordOutcome(n,{kind:`failed`,message:e.error}),await this.notifyLead(n,`failed: ${e.error}`))}finally{e.markSettled(),await this.releaseDependents(n)}}async notifyLead(e,t){let n=this.deliveryFor(e);n===`quiet`&&(this.unreadReports=!0);try{await this.team.sendMessage({from:e,target:this.leadName,message:`Worker '${e}' ${t}`,delivery:n})}catch{}}deliveryFor(e){return this.lead.isRunning||this.workerRuntimes.get(e)?.leadDriven!==!0?`quiet`:`wakeup`}unreadReports=!1;async whenQuiet(e){for(;;){e?.throwIfAborted();let t=[...this.workerRuntimes.values()].filter(e=>e.status===`pending`||e.status===`running`);if(t.length>0&&await Promise.all(t.map(e=>e.settled)),await this.team.whenIdle(this.leadName,e),![...this.workerRuntimes.values()].some(e=>e.status===`pending`||e.status===`running`))return}}workers(){return Object.freeze([...this.workerRuntimes.values()].map(e=>this.workerView(e)))}workerView(e){return Object.freeze({name:e.request.name,agentId:e.session.definition.id,conversationId:e.session.conversationId,task:e.request.task,status:e.status,context:e.request.context,dependsOn:e.request.dependsOn,writes:e.request.writes,...e.request.role===void 0?{}:{role:e.request.role},...e.warnings.length===0?{}:{warnings:e.warnings},...e.request.specialty===void 0?{}:{specialty:e.request.specialty},...e.result===void 0?{}:{result:e.result},...e.error===void 0?{}:{error:e.error}})}async awaitWorker(e,n={}){let r=x(e),i=this.workerRuntimes.get(r);if(i===void 0)throw Error(`unknown managed worker '${r}'`);let a=t(n.timeoutMs??3e4),o,s=new Promise(e=>{o=setTimeout(e,a)});try{await Promise.race([i.settled,s])}finally{clearTimeout(o)}return n.signal?.throwIfAborted(),i.result}async closeWorker(t,n=Error(`managed worker closed`)){let r=x(t),i=this.workerRuntimes.get(r);if(i===void 0)throw Error(`unknown managed worker '${r}'`);let a=i.status;i.closing=!0,i.controller.abort(n);try{await this.team.cancel(r,n)}catch{}a===`pending`?(i.status=`closed`,i.start=void 0,this.team.markPending(r,void 0),i.markSettled()):(await e(i.settled,this.closeTimeoutMs),i.status=`closed`),this.workerRuntimes.delete(r);try{this.team.detach(r)}catch{}return await this.releaseDependents(r),a}async dispose(e=Error(`managed agent team disposed`)){let t=[...this.workerRuntimes.keys()];await Promise.allSettled(t.map(t=>this.closeWorker(t,e)))}removeWorker(e){let t=x(e),n=this.workerRuntimes.get(t);if(n===void 0)throw Error(`unknown managed worker '${t}'`);if(n.status===`running`||n.session.isRunning)throw Error(`cannot remove running managed worker '${t}'`);this.team.detach(t),this.workerRuntimes.delete(t)}controlTools(){return Object.freeze([r({name:`spawn_agent`,description:[`Create a connected specialist worker and start one task on it.`,`Returns as soon as the worker is running, WITHOUT its result: keep working,`,`and you will be told when it finishes. Use wait_agents to pause for it,`,`list_agents to read its status and result, and close_agent when done with it.`,`Before the first call, plan: name the step that blocks the others and do that`,`one yourself. Then spawn the rest of the plan in one step: declare each`,"worker's `writes` so two never write the same file, and use `dependsOn` for",`anything that must follow another worker rather than waiting to spawn it.`].join(` `),parameters:{type:`object`,properties:{name:{type:`string`,description:`Optional unique worker address; omitted generates worker_N.`},task:{type:`string`,description:`Concrete bounded task assigned to the worker. State which files it owns and may write, so two workers never write the same one.`},specialty:{type:`string`,description:`Optional worker role or domain specialization.`},context:{type:`string`,enum:[`fresh`,`fork`],description:`fresh starts the worker from its task alone; fork also gives it your conversation so far, so it does not have to rediscover what you already established. Prefer fork when the task depends on findings of yours.`},dependsOn:{type:`array`,items:{type:`string`},description:`Names of workers that must finish before this one starts. The worker is created now and held until they do, then given what they produced — so spawn the whole plan at once and express the ORDER here rather than by spawning later. Use it for anything that reviews, integrates or builds on another worker.`},writes:{type:`array`,items:{type:`string`},description:`Files and directories this worker may write, workspace-relative. A spawn that would write what another worker running at the same time writes is refused, because both would write it and the later write wins. Declare them and the conflict is caught before any work is lost. OMIT this entirely for a worker that only reads — a stand-in path such as "none" or "/tmp/no-write" claims a real scope, and several readers sharing that stand-in collide with each other over a file none of them will ever write.`},...this.roleSchema()},required:[`task`],additionalProperties:!1},parse:g,execute:async(e,t)=>O(await this.spawn(e,t.signal)),timeoutMs:this.spawnTimeoutMs,isConcurrencySafe:()=>!0}),r({name:`close_agent`,budgetExempt:!0,description:[`Close a worker you no longer need and free its slot.`,`A finished worker still occupies one until closed, so close it once you have read its result.`,`A running or pending worker is kept alive by default so it can finish its final report.`,this.options.allowModelWorkerCancellation===!1?`The host requires worker reports: you cannot cancel unfinished workers. Wait for their result.`:`Set cancelRunning: true only to deliberately abandon unfinished work and cancel it.`,`Returns the status it held before closing.`].join(` `),parameters:{type:`object`,properties:{name:{type:`string`,description:`Worker address returned by spawn_agent.`},cancelRunning:{type:`boolean`,description:`Explicitly cancel an unfinished worker. Defaults to false.`}},required:[`name`],additionalProperties:!1},parse:h,execute:async({name:e,cancelRunning:t})=>{let n=this.workerRuntimes.get(e);return n!==void 0&&(!t||this.options.allowModelWorkerCancellation===!1)&&(n.status===`pending`||n.status===`running`||n.session.isRunning)?O({worker:e,closed:!1,status:n.status===`pending`?`pending`:`running`,instruction:`The worker has not finished its final report. Use wait_agents and read its completed result before closing.`+(this.options.allowModelWorkerCancellation===!1?` Model cancellation is disabled by the host.`:` To deliberately abandon this work, call close_agent with cancelRunning: true.`)}):O({worker:e,closed:!0,previousStatus:await this.closeWorker(e)})},timeoutMs:this.workerTimeoutMs})])}forkLeadHistory(){let e=y(this.lead.snapshot().history);return a.fromSnapshot({version:1,entries:e},this.options.workerSessionOptions?.historyLimits??{})}async workerDefinition(e){if(this.options.workerFactory!==void 0)return this.options.workerFactory(e);let t=this.options.workerTemplate??this.options.lead,n=e.role===void 0?void 0:this.roles.get(e.role),r=n===void 0?``:` You are the '${n.name}' worker. ${n.instructions??n.description}`,i=e.specialty===void 0?``:` Your specialization is: ${e.specialty}.`;return o(t,{id:e.name,name:e.name,instructions:`${t.instructions}\n\nYou are dynamically assigned worker '${e.name}'.${r}${i}`})}nextWorkerName(){for(;;){let e=`worker_${++this.workerSequence}`;if(!this.reservedNames.has(e)&&!this.workerRuntimes.has(e)&&!this.team.members().some(t=>t.name===e))return e}}async observeWorkerEvent(t,n){let r=Promise.resolve().then(()=>this.options.onWorkerEvent?.(t,n));await e(r,this.observerTimeoutMs)}};function p(e){return new f(e)}function m(e,t){let n=new i;if(e!==void 0){let t=`names`in e?e.names().map(t=>e.get(t)).filter(e=>e!==void 0):e;for(let e of t)n.register(e)}for(let e of t)n.register(e);return n}function h(e){let t=b(e,`close_agent arguments`);if(Object.keys(t).some(e=>e!==`name`&&e!==`cancelRunning`))throw TypeError(`close_agent arguments contain unknown fields`);if(t.cancelRunning!==void 0&&typeof t.cancelRunning!=`boolean`)throw TypeError(`close_agent cancelRunning must be a boolean`);return{name:x(t.name),cancelRunning:t.cancelRunning===!0}}function g(e){let t=b(e,`spawn_agent arguments`),n=new Set([`name`,`task`,`specialty`,`context`,`role`,`dependsOn`,`writes`]);if(Object.keys(t).some(e=>!n.has(e)))throw TypeError(`spawn_agent arguments contain unknown fields`);return{task:S(t.task,`worker task`),...t.name===void 0?{}:{name:x(t.name)},...t.specialty===void 0?{}:{specialty:S(t.specialty,`worker specialty`)},...t.context===void 0?{}:{context:v(t.context)},...t.role===void 0?{}:{role:S(t.role,`worker role`)},...t.dependsOn===void 0?{}:{dependsOn:_(t.dependsOn,`dependsOn`)},...t.writes===void 0?{}:{writes:_(t.writes,`writes`)}}}function _(e,t){if(!Array.isArray(e))throw TypeError(`${t} must be an array of strings`);return e.map(e=>S(e,`${t} entry`))}function v(e){if(e!==`fresh`&&e!==`fork`)throw TypeError(`worker context must be 'fresh' or 'fork'`);return e}function y(e){let t=new Set,n=0;return e.entries.forEach((e,r)=>{let i=e.event;if(i.kind===`tool-call`)t.add(i.callId);else if(i.kind===`tool-result`)t.delete(i.callId);else if(i.kind===`assistant`)for(let e of i.message.content)e.type===`tool-call`&&t.add(e.id);t.size===0&&(i.kind!==`assistant`||i.interrupted!==!0)&&(n=r+1)}),e.entries.slice(0,n)}function b(e,t){if(typeof e!=`object`||!e||Array.isArray(e))throw TypeError(`${t} must be an object`);return e}function x(e){let t=S(e,`managed agent name`);if(!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(t))throw TypeError(`managed agent name must start with a letter and contain only letters, digits, _ or -`);if(t.length>128)throw TypeError(`managed agent name must not exceed 128 characters`);return t}function S(e,t){if(typeof e!=`string`||e.trim().length===0)throw TypeError(`${t} must be a non-empty string`);return e}function C(e,t,n){let r=S(e,t);if(new TextEncoder().encode(r).byteLength>n)throw TypeError(`${t} exceeds the ${n}-byte limit`);return r}function w(e,t){if(!Number.isSafeInteger(e)||e<1)throw TypeError(`${t} must be a positive integer`);return e}function T(e){return e instanceof Error?e.message:String(e)}async function E(e,t){if(t.aborted)throw t.reason??Error(`managed worker aborted`);return await new Promise((n,r)=>{let i=()=>{t.removeEventListener(`abort`,i),r(t.reason??Error(`managed worker aborted`))};t.addEventListener(`abort`,i,{once:!0}),e.then(e=>{t.removeEventListener(`abort`,i),n(e)},e=>{t.removeEventListener(`abort`,i),r(e)})})}function D(...e){let t=e.filter(e=>e!==void 0);return t.length===1?t[0]:AbortSignal.any(t)}function O(e){return e}const k=new Set([`completed`,`failed`,`closed`]);function A(e){let t=e.outcome.reason;if(t.kind===`error`)return t.failure.message;if(t.kind===`max-tokens`)return`the model stopped at its output limit`;if(t.kind===`usage-unavailable`)return`the provider reported no usage for a billed call`;if(t.kind===`aborted`)return`the run was aborted`;if(t.kind===`budget-exhausted`&&!e.outcome.completed)return`the run stopped at its ${t.budget} limit before completing the task`;if(e.text.trim()===``)return`it produced no answer`}function j(e){let t=S(e,`worker write scope`).trim().split(`\\`).join(`/`).replace(/^\.?\/+/,``).replace(/\/+$/,``);if(t.length===0||t===`.`)throw TypeError(`a worker write scope must name a file or directory, not the whole workspace`);return t}function M(e,t){return e===t||e.startsWith(`${t}/`)||t.startsWith(`${e}/`)}function N(e,t){let n=new TextEncoder().encode(e);return n.byteLength<=t?e:`${new TextDecoder(`utf-8`,{fatal:!1}).decode(n.subarray(0,t)).replace(/�$/,``)}… (truncated)`}export{u as DEFAULT_HOLD_WAIT_MS,c as DEFAULT_SPAWN_SETUP_TIMEOUT_MS,l as DEFAULT_WORKER_CLOSE_TIMEOUT_MS,f as ManagedAgentTeam,y as completedHistoryPrefix,p as createManagedAgentTeam};
+//# sourceMappingURL=managed.js.map