aec-agent 1.0.3 → 1.0.4

package/dist/components/multi-agent-orchestration/agent/subagent-manager/semaphore.js

@@ -0,0 +1,56 @@
+/**
+ * A-105: at most `size` holders at once, waiters served in arrival order. A waiter whose
+ * signal aborts leaves the queue (acquire resolves null), so a stopped parent turn never
+ * starts a queued child.
+ */
+export class Semaphore {
+    size;
+    holders = 0;
+    waiters = [];
+    constructor(size) {
+        this.size = size;
+    }
+    /** Holders plus waiters. */
+    get busy() {
+        return this.holders + this.waiters.length;
+    }
+    acquire(signal) {
+        if (signal?.aborted)
+            return Promise.resolve(null);
+        if (this.holders < this.size) {
+            this.holders++;
+            return Promise.resolve(this.slot());
+        }
+        return new Promise((resolve) => {
+            const waiter = {
+                grant: () => {
+                    signal?.removeEventListener("abort", onAbort);
+                    this.holders++;
+                    resolve(this.slot());
+                },
+                cancel: () => resolve(null),
+            };
+            const onAbort = () => {
+                const i = this.waiters.indexOf(waiter);
+                if (i !== -1)
+                    this.waiters.splice(i, 1);
+                waiter.cancel();
+            };
+            signal?.addEventListener("abort", onAbort, { once: true });
+            this.waiters.push(waiter);
+        });
+    }
+    slot() {
+        let released = false;
+        return {
+            release: () => {
+                if (released)
+                    return;
+                released = true;
+                this.holders--;
+                this.waiters.shift()?.grant();
+            },
+        };
+    }
+}
+//# sourceMappingURL=semaphore.js.map

package/dist/components/multi-agent-orchestration/agent/subagent-manager/semaphore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semaphore.js","sourceRoot":"","sources":["../../../../../src/components/multi-agent-orchestration/agent/subagent-manager/semaphore.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,OAAO,SAAS;IAIS,IAAI;IAHzB,OAAO,GAAG,CAAC,CAAC;IACZ,OAAO,GAAqD,EAAE,CAAC;IAEvE,YAA6B,IAAY;oBAAZ,IAAI;IAAW,CAAC;IAE7C,4BAA4B;IAC5B,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;IAC5C,CAAC;IAED,OAAO,CAAC,MAAoB;QAC1B,IAAI,MAAM,EAAE,OAAO;YAAE,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAClD,IAAI,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;YAC7B,IAAI,CAAC,OAAO,EAAE,CAAC;YACf,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QACtC,CAAC;QACD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YAC7B,MAAM,MAAM,GAAG;gBACb,KAAK,EAAE,GAAG,EAAE;oBACV,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;oBAC9C,IAAI,CAAC,OAAO,EAAE,CAAC;oBACf,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;gBACvB,CAAC;gBACD,MAAM,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;aAC5B,CAAC;YACF,MAAM,OAAO,GAAG,GAAS,EAAE;gBACzB,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;gBACvC,IAAI,CAAC,KAAK,CAAC,CAAC;oBAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;gBACxC,MAAM,CAAC,MAAM,EAAE,CAAC;YAClB,CAAC,CAAC;YACF,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC3D,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC5B,CAAC,CAAC,CAAC;IACL,CAAC;IAEO,IAAI;QACV,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,OAAO;YACL,OAAO,EAAE,GAAG,EAAE;gBACZ,IAAI,QAAQ;oBAAE,OAAO;gBACrB,QAAQ,GAAG,IAAI,CAAC;gBAChB,IAAI,CAAC,OAAO,EAAE,CAAC;gBACf,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,CAAC;YAChC,CAAC;SACF,CAAC;IACJ,CAAC;CACF"}

package/dist/components/multi-agent-orchestration/agent/subagent-manager/subagent-manager.d.ts

@@ -0,0 +1,128 @@
+import type { Session } from "../../../../kernel/types.js";
+import type { EventBus } from "../../../event-handler/types.js";
+import type { InteractionHandler, ToolDefinition } from "../../../tool-hub/types.js";
+import type { SessionStore } from "../../../persistence-hub/types/session-store.js";
+import type { MessageStore } from "../../../persistence-hub/types/message-store.js";
+import type { SubagentRunStore } from "../../../persistence-hub/types/subagent-run-store.js";
+import type { AgentProfile } from "../types.js";
+import type { SubagentHub } from "../../../subagent-hub/subagent-hub.js";
+import { type ChildLoopDeps } from "./child-loop.js";
+import { describeResult } from "./brief.js";
+import { type AgentSubagents, type SubagentChildSide, type SubagentHost, type SubagentRequest, type SubagentResult, type SubagentRun, type SubagentRunner, type SubagentSpawnContext, type SubagentSpawnScope, type SubagentTargetInfo } from "./types.js";
+export interface SubagentManagerDeps {
+    agentId: string;
+    /** Read on every call, so a profile update (new allowlist, limits) applies to the next spawn. */
+    getProfile: () => AgentProfile;
+    eventBus: EventBus;
+    getStore: () => SubagentRunStore;
+    getSessions: () => SessionStore;
+    getMessages: () => MessageStore;
+    /** The agents a child can be (AgentCore.agents). Absent = no subagents. */
+    getHost: () => SubagentHost | undefined;
+    /** The host's runner (AgentCore.useSubagentRunner); absent = the child agent's own chat(). */
+    getRunner: () => SubagentRunner | undefined;
+    /** Whether this agent has the spawn_subagent tool (its index is shown only then). */
+    hasSpawnTool: () => boolean;
+    /** The library of subagent types (AgentCore.subagentHub). Absent = no subagent types. */
+    getHub: () => SubagentHub | undefined;
+    /** What a subagent type's short-lived loop borrows from this agent (model, tools, sandbox). */
+    childLoop: ChildLoopDeps;
+    /** This agent's channel to the user in one of its sessions — used when the spawn context has none. */
+    interactionFor: (sessionId: string) => InteractionHandler | undefined;
+    /**
+     * A-106: the spawn scope of one of this agent's sessions (a group lead's session while it
+     * leads a group turn), read on every call. Absent or undefined = the profile's config.
+     */
+    getScope?: (sessionId: string) => SubagentSpawnScope | undefined;
+}
+/**
+ * SubagentManager (A-105) — owns everything about subagents for one agent:
+ *
+ *  - as a PARENT: spawn() validates the brief and target, takes a slot of the turn's
+ *    semaphore, creates the child's session, runs the child turn through the host's runner
+ *    (or the child's chat()), enforces the turn's shared budget and the child's deadline,
+ *    and records the run (PersistenceHub.subagentRuns) and its lifecycle events;
+ *    Design revision: the target is a subagent TYPE (a short-lived loop inside this agent,
+ *    child-loop.ts, in a side-branch session of this agent) or an existing AGENT;
+ *  - as a CHILD (subagentSide): knows which of its sessions are child runs, routes their
+ *    approvals to the parent's channel to the user, refuses their questions, scopes their
+ *    tools (read-only by default) and holds the single writer slot.
+ *
+ * It hears the child's model responses, tool calls and max-iterations events on the bus to
+ * account tokens and tool calls while the child runs.
+ */
+export declare class SubagentManager implements AgentSubagents {
+    private deps;
+    private budgets;
+    private active;
+    private byChildSession;
+    private unsubscribes;
+    private disposed;
+    private bindings;
+    private writerRunId;
+    /** The child-side half, used by the parent's SubagentManager through SubagentTarget.subagentSide. */
+    readonly subagentSide: SubagentChildSide;
+    constructor(deps: SubagentManagerDeps);
+    get running(): number;
+    targets(sessionId?: string): Promise<SubagentTargetInfo[]>;
+    list(parentSessionId: string): Promise<SubagentRun[]>;
+    get(runId: string): Promise<SubagentRun | null>;
+    stop(runId: string): boolean;
+    spawn(request: SubagentRequest, context: SubagentSpawnContext): Promise<SubagentResult>;
+    /** A-106: the session's grants — spawn_subagent for a scoped session that asks for it. */
+    grantedTools(sessionId: string): readonly string[];
+    /** A-106: spawn_subagent runs without asking in a scoped session that the user set up for it. */
+    preApproved(sessionId: string, toolName: string): boolean;
+    /** The profile's config, or (A-106) the scope's targets and limits over it. */
+    private configFor;
+    /** Stop every running child and stop listening. Runs in progress record themselves as cancelled. */
+    dispose(): void;
+    private runChild;
+    /** Default runner (no host runner): the turn itself — the child agent's chat(), or the type's loop. */
+    private defaultRunner;
+    private statusOf;
+    /** The child's last non-empty reply in its session — what a partial run hands back. */
+    private lastReport;
+    private finish;
+    /** A run that ended before its child turn started. */
+    private finishUnstarted;
+    private save;
+    /** A stored record, with the live token and tool-call counts while it runs here. */
+    private live;
+    /** V1 nesting depth is 1: a session that is itself a child run cannot delegate. */
+    private refuseNested;
+    /**
+     * The target `ref` names: an enabled subagent type (by name) first, then an allowed running
+     * agent (by id or name). Throws SubagentError for anything that can't run.
+     */
+    private resolveTarget;
+    /** The child's channel to the user: approvals go to the parent's (shown in the parent's chat), questions are refused. */
+    private childInteraction;
+    private budgetFor;
+    /** Why no further child may start in this turn, or undefined. `started`: the run already counts in `launched`. */
+    private budgetRefusal;
+    private addUsage;
+    /** Over the turn's token or tool-call budget: stop every running child of the turn. */
+    private enforceBudget;
+    private abort;
+    private dropIdleBudgets;
+    /** Budgets of turns that never reported their end (a tool job's call) go once idle long enough. */
+    private pruneBudgets;
+    /** A child session's channel to the user (the parent's, for approvals only); undefined for other sessions. */
+    interactionFor(sessionId: string): InteractionHandler | undefined;
+    /**
+     * A-135: the parent session of a child run's session, whose approval mode the child uses
+     * (its approvals are asked there); undefined for other sessions.
+     */
+    parentSessionOf(sessionId: string): string | undefined;
+    /** A child session's tool scope (read-only by default); undefined for other sessions. */
+    toolScope(sessionId: string): ((definition: ToolDefinition) => boolean) | undefined;
+    /**
+     * <available_subagents> for the system prompt: the subagent types and agents this one may
+     * delegate to. None in a child run's session, or when the agent lacks spawn_subagent.
+     */
+    buildIndex(session: Session): Promise<string | null>;
+}
+/** spawn_subagent's text for a finished run. Re-exported for the tool. */
+export { describeResult };
+//# sourceMappingURL=subagent-manager.d.ts.map

package/dist/components/multi-agent-orchestration/agent/subagent-manager/subagent-manager.d.ts.map

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