@framers/agentos 0.15.63 → 0.15.65

package/dist/api/runtime/agencyLaunch/runtimeSeat.js

@@ -0,0 +1,277 @@
+/**
+ * @file runtimeSeat.ts
+ * A seat of a team a GMI launched on the full runtime: a roster member over the one GMI the GMIManager built for it
+ * (`createAgencySeat`). Each call runs one turn of that GMI under the call's stop, in the seat session, as the parent
+ * turn's user and organization, with the launch frame in its metadata; the seat's calls run one at a time. A failed
+ * turn rejects with its error's name and code alone, as a gmi() seat's does, the error itself going to the launch's
+ * `logError`. Each call that ran a turn is reported to `onCall` when it ends (the agency registry's seat history).
+ * Each call hands the seat's tool view the approval gate the child agency passes with it, which the view asks on each
+ * of the call's tool calls.
+ * @internal
+ */
+import { randomUUID } from 'node:crypto';
+import { GMIInteractionType, GMIOutputChunkType, } from '../../../cognition/substrate/IGMI.js';
+import { GMIError, GMIErrorCode } from '../../../core/utils/errors.js';
+import { composeReceivedGate } from '../approval-gate.js';
+import { TurnLock } from '../gmiSession.js';
+import { SEAT_SUMMARY_CHARS } from './types.js';
+/** A turn's usage, from its output. */
+function usageOf(output) {
+    const usage = output?.usage;
+    const num = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : 0);
+    const cost = usage?.totalCostUSD;
+    return {
+        promptTokens: num(usage?.promptTokens),
+        completionTokens: num(usage?.completionTokens),
+        totalTokens: num(usage?.totalTokens),
+        ...(typeof cost === 'number' && Number.isFinite(cost) ? { costUSD: cost } : {}),
+    };
+}
+/**
+ * The error a seat rejects with: the original's name and code alone, the rule sessionSeat()'s seats follow. A
+ * provider's or a handler's message can carry a URL or a credential, and a hierarchical manager's delegate tool hands
+ * a seat's rejection to the manager's model.
+ */
+function seatError(name, code) {
+    const error = new Error(code ? `${name} (${code})` : name);
+    error.name = name;
+    if (code)
+        error.code = code;
+    return error;
+}
+/**
+ * The error a failed turn reported, whole, for the launch's `logError`: its ERROR chunk's details (a GMIError's plain
+ * form: name, message, code, details, stack), else its output's error.
+ */
+function turnError(details, output, content) {
+    const text = (key) => {
+        const value = details?.[key];
+        return typeof value === 'string' ? value : undefined;
+    };
+    const code = text('code') ?? output?.code ?? GMIErrorCode.GMI_PROCESSING_ERROR;
+    const message = text('message') ?? output?.message ?? (typeof content === 'string' ? content : 'The turn failed.');
+    const error = new GMIError(message, code, output?.details ?? details?.details);
+    const name = text('name');
+    if (name)
+        error.name = name;
+    const stack = text('stack');
+    if (stack)
+        error.stack = stack;
+    return error;
+}
+/** The code of a thrown error, when it carries a string or numeric one. */
+function codeOf(error) {
+    const code = error?.code;
+    return typeof code === 'string' ? code : typeof code === 'number' ? String(code) : undefined;
+}
+/**
+ * @param options - The seat's GMI, persona, session, user, organization, frame and record fields.
+ * @returns A roster member for the launch's child agency.
+ */
+export function runtimeSeat(options) {
+    const record = {
+        role: options.role,
+        form: options.form,
+        ...(options.memberRef ? { member: options.memberRef } : {}),
+        status: 'not_run',
+        calls: 0,
+        summary: '',
+        usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+    };
+    const lock = new TurnLock();
+    let closed = false;
+    let closing;
+    /** The seat's calls in flight, a call waiting for the seat's earlier turn among them. */
+    let running = 0;
+    /** A persistent member's input, after its role and brief; a temporary seat's instructions are its persona. */
+    const framed = (input) => {
+        if (options.form !== 'persistent')
+            return input;
+        const brief = options.brief?.trim();
+        return `Your role in this team: ${options.role}.${brief ? ` ${brief}` : ''}\n\n${input}`;
+    };
+    /** Adds a turn's usage to the record: a turn that failed after billed steps included. */
+    const addUsage = (usage) => {
+        record.usage.promptTokens += usage.promptTokens;
+        record.usage.completionTokens += usage.completionTokens;
+        record.usage.totalTokens += usage.totalTokens;
+        if (usage.costUSD !== undefined)
+            record.usage.costUSD = (record.usage.costUSD ?? 0) + usage.costUSD;
+    };
+    /**
+     * Hands `onCall` a copy of the record as the call that ran a turn left it, before the seat's next turn can change it.
+     * A function that throws changes nothing about the call.
+     */
+    const reportCall = () => {
+        if (!options.onCall)
+            return;
+        try {
+            options.onCall({ ...record, usage: { ...record.usage }, ...(record.error ? { error: { ...record.error } } : {}) });
+        }
+        catch (error) {
+            options.logError(error, 'launch_agency record');
+        }
+    };
+    /** Records a failed call and returns the error the seat rejects with: the failure's name and code, never its message. */
+    const failed = (error, signal) => {
+        const name = error instanceof Error ? error.name : 'Error';
+        const code = codeOf(error);
+        record.status = signal?.aborted === true || options.cutWhen() ? 'cut' : 'failed';
+        record.error = { name, ...(code ? { code } : {}) };
+        options.logError(error, `seat ${options.role}`);
+        return seatError(name, code);
+    };
+    /** One turn of the seat's GMI, under the call's stop. */
+    const runTurn = async (prompt, signal) => {
+        const calls = new Map();
+        let output;
+        let failure;
+        let lastStep;
+        let streamed = '';
+        try {
+            const turn = options.gmi.processTurnStream({
+                interactionId: `turn-${randomUUID()}`,
+                userId: options.userId,
+                sessionId: options.seatSessionId,
+                type: GMIInteractionType.TEXT,
+                content: framed(prompt),
+                metadata: {
+                    ...(signal ? { options: { abortSignal: signal } } : {}),
+                    agencyLaunch: options.frame,
+                    agencyId: options.frame.launchId,
+                    roleId: options.role,
+                    ...(options.organizationId ? { organizationId: options.organizationId } : {}),
+                    ...(options.toolCallGate ? { toolCallGate: options.toolCallGate } : {}),
+                },
+            });
+            for (;;) {
+                const next = await turn.next();
+                if (next.done) {
+                    output = next.value;
+                    break;
+                }
+                const chunk = next.value;
+                if (chunk.type === GMIOutputChunkType.TEXT_DELTA && typeof chunk.content === 'string') {
+                    streamed += chunk.content;
+                }
+                else if (chunk.type === GMIOutputChunkType.STEP_FINISHED) {
+                    lastStep = chunk.content;
+                }
+                else if (chunk.type === GMIOutputChunkType.TOOL_CALL_REQUEST && Array.isArray(chunk.content)) {
+                    for (const call of chunk.content)
+                        calls.set(call.id, { name: call.name, args: call.arguments });
+                }
+                else if (chunk.type === GMIOutputChunkType.TOOL_RESULT) {
+                    const result = chunk.content;
+                    const call = calls.get(result.toolCallId);
+                    // A tool's error stays out of the record: its message can carry what the seat's model must not echo.
+                    if (call && result.isError)
+                        call.error = 'the tool failed';
+                    else if (call)
+                        call.result = result.result;
+                }
+                else if (chunk.type === GMIOutputChunkType.ERROR) {
+                    failure = { details: chunk.errorDetails, content: chunk.content };
+                }
+            }
+        }
+        catch (thrown) {
+            throw failed(thrown, signal);
+        }
+        // A failed turn does not throw: it yields an ERROR chunk and returns its error with the usage of the steps it made.
+        if (failure || output?.error) {
+            addUsage(usageOf(output));
+            throw failed(turnError(failure?.details, output?.error, failure?.content), signal);
+        }
+        const text = output?.responseText ?? streamed;
+        const usage = usageOf(output);
+        addUsage(usage);
+        record.status = 'completed';
+        delete record.error;
+        record.summary = text.length > SEAT_SUMMARY_CHARS ? text.slice(0, SEAT_SUMMARY_CHARS) : text;
+        const persona = options.gmi.getPersona();
+        return {
+            provider: lastStep?.providerId ?? persona.defaultProviderId ?? '',
+            model: lastStep?.modelId ?? persona.defaultModelId ?? '',
+            text,
+            usage,
+            toolCalls: [...calls.values()],
+            finishReason: lastStep?.finishReason === 'length' ? 'length' : 'stop',
+        };
+    };
+    const handle = {
+        seatId: options.seatSessionId,
+        gmiId: options.gmi.gmiId,
+        personaId: options.personaId,
+        ...(options.description ? { description: options.description } : {}),
+        ...(options.dependsOn ? { dependsOn: [...options.dependsOn] } : {}),
+        async generate(prompt, opts) {
+            if (closed)
+                throw new Error('seat closed');
+            record.calls += 1;
+            running += 1;
+            try {
+                // A GMI runs one turn at a time (GMI.ensureReady): a manager that delegates twice at once waits here.
+                const release = await lock.acquire();
+                let ranTurn = false;
+                try {
+                    if (closed) {
+                        // The launch closed the seat while this call waited for its earlier turn: the call is cut, and runs nothing.
+                        record.status = 'cut';
+                        delete record.error;
+                        throw new Error('seat closed');
+                    }
+                    ranTurn = true;
+                    // The child agency passes its gate with each call (a value that is not a function refuses every tool): the
+                    // view asks it on each of this call's tool calls. It is set once the call holds the seat's lock, so a call
+                    // waiting for an earlier turn neither replaces nor clears that turn's gate.
+                    options.setGate?.(composeReceivedGate(opts?.__approvalGate));
+                    return await runTurn(prompt, opts?.abortSignal);
+                }
+                finally {
+                    options.setGate?.(undefined);
+                    // The registry's seat history hears of every call that ran a turn, answered or not.
+                    if (ranTurn)
+                        reportCall();
+                    release();
+                }
+            }
+            finally {
+                running -= 1;
+            }
+        },
+        stream() {
+            throw new Error('a seat of a launched team runs through generate()');
+        },
+        session() {
+            throw new Error('a seat runs one session; call generate()');
+        },
+        async usage() {
+            return { ...record.usage };
+        },
+        close() {
+            closing ?? (closing = (async () => {
+                closed = true;
+                // A turn still running (a tool past the deadline) ends first; then the GMI goes.
+                const release = await lock.acquire();
+                try {
+                    await options.release();
+                }
+                finally {
+                    release();
+                }
+            })());
+            return closing;
+        },
+        record() {
+            // A turn still running once the launch has stopped (its deadline, its parent's stop, its budget) is cut, whatever
+            // the seat's earlier turns came to: the launch reports without that turn's answer, and without the error an
+            // earlier turn failed with, which did not end this one.
+            const cut = running > 0 && options.cutWhen();
+            const { error, ...withoutError } = record;
+            return { ...withoutError, ...(cut ? { status: 'cut' } : {}), usage: { ...record.usage }, ...(error && !cut ? { error: { ...error } } : {}) };
+        },
+    };
+    return handle;
+}
+//# sourceMappingURL=runtimeSeat.js.map

package/dist/api/runtime/agencyLaunch/runtimeSeat.js.map

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

package/dist/api/runtime/agencyLaunch/seatToolView.d.ts

@@ -0,0 +1,11 @@
+import type { IToolOrchestrator } from '../../../core/tools/IToolOrchestrator.js';
+import { type ApprovalGateFn } from '../approval-gate.js';
+/**
+ * @param base - The runtime's shared tool orchestrator.
+ * @param names - The seat's tool names.
+ * @param gateOf - The approval gate of the call the seat serves, read at each tool call: the one the child agency
+ *   passes with that call; undefined between calls and for a team that has none.
+ * @returns The seat's orchestrator.
+ */
+export declare function seatToolView(base: IToolOrchestrator, names: ReadonlySet<string>, gateOf?: () => ApprovalGateFn | undefined): IToolOrchestrator;
+//# sourceMappingURL=seatToolView.d.ts.map

package/dist/api/runtime/agencyLaunch/seatToolView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seatToolView.d.ts","sourceRoot":"","sources":["../../../../src/api/runtime/agencyLaunch/seatToolView.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0CAA0C,CAAC;AAClF,OAAO,EAAqC,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAO7F;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,iBAAiB,EACvB,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,EAC1B,MAAM,GAAE,MAAM,cAAc,GAAG,SAA2B,GACzD,iBAAiB,CAwDnB"}

package/dist/api/runtime/agencyLaunch/seatToolView.js

@@ -0,0 +1,69 @@
+import { APPROVAL_GRANTED, askApprovalGate } from '../approval-gate.js';
+import { withMembers } from '../withMembers.js';
+/** Why a call outside the seat's names was not run, as the model reads it. */
+const NOT_IN_SEAT = 'not available in this seat';
+/**
+ * @param base - The runtime's shared tool orchestrator.
+ * @param names - The seat's tool names.
+ * @param gateOf - The approval gate of the call the seat serves, read at each tool call: the one the child agency
+ *   passes with that call; undefined between calls and for a team that has none.
+ * @returns The seat's orchestrator.
+ */
+export function seatToolView(base, names, gateOf = () => undefined) {
+    const visible = (tools) => tools.filter((tool) => names.has(tool.name));
+    const processToolCall = async (details) => {
+        const req = details.toolCallRequest;
+        if (!names.has(req.name)) {
+            return {
+                toolCallId: req.id,
+                toolName: req.name,
+                output: { skipped: true, reason: NOT_IN_SEAT },
+                isError: true,
+                errorDetails: { message: `Skipped: ${NOT_IN_SEAT}`, code: 'TOOL_NOT_IN_SEAT' },
+            };
+        }
+        // The gate of the call the seat serves, after the name filter, about a tool the orchestrator has: anything but the
+        // exact approval skips the tool, and the model is told why. A tool the orchestrator does not have is reported by it
+        // without asking anyone, and so is a call whose stop has come: the orchestrator refuses it (STEP_ABORTED). The view
+        // does not see the step of the GMI's tool loop, so the request names step 0.
+        const gate = gateOf();
+        const current = gate ? await base.getTool(req.name) : undefined;
+        let bound;
+        if (gate && current && !details.signal?.aborted) {
+            const verdict = await askApprovalGate(gate, { name: req.name, args: req.arguments ?? {}, id: req.id, step: 0 });
+            if (verdict !== APPROVAL_GRANTED) {
+                return {
+                    toolCallId: req.id,
+                    toolName: req.name,
+                    output: { skipped: true, reason: verdict.reason },
+                    isError: true,
+                    errorDetails: { message: `Skipped: ${verdict.reason}` },
+                };
+            }
+            // The approval is for the registration the gate was asked about. A composed step arrives with the instance its
+            // pipeline checked already.
+            if (!details.tool)
+                bound = current;
+        }
+        const callerTurn = {
+            ...(details.callerTurn ?? {}),
+            toolNames: names,
+            ...(gate ? { approvalGate: gate } : {}),
+            dispatch: processToolCall,
+        };
+        // The orchestrator checks and runs the bound instance alone, and refuses the call (STEP_REPLACED) when another
+        // registration took the name while the approval was pending.
+        return base.processToolCall({ ...details, ...(bound ? { tool: bound } : {}), callerTurn });
+    };
+    return withMembers(base, {
+        processToolCall,
+        listAvailableTools: async (context) => visible(await base.listAvailableTools(context)),
+        // The base's listDiscoveredTools calls its own listAvailableTools, which this view does not reach.
+        ...(typeof base.listDiscoveredTools === 'function'
+            ? {
+                listDiscoveredTools: async (...args) => visible(await base.listDiscoveredTools(...args)),
+            }
+            : {}),
+    });
+}
+//# sourceMappingURL=seatToolView.js.map

package/dist/api/runtime/agencyLaunch/seatToolView.js.map

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

package/dist/api/runtime/agencyLaunch/types.d.ts

@@ -1,21 +1,30 @@
 /**
  * @file types.ts
  * The types and bounds of teams a GMI launches from a turn (`launch_agency`), and of the seats such a team and
- * `sessionSeat()` build. The package root and `src/api` export {@link LAUNCH_AGENCY_TOOL_NAME}, `sessionSeat()` and
- * the types of the `agencies` option, the tool's arguments and result and a seat; the launch registry, the engine
- * (`runLaunch`) and the tool factory (`createGmiLaunchTool`) stay internal.
+ * `sessionSeat()` build, with the tool's schema and description, which both surfaces offer. The package root and
+ * `src/api` export {@link LAUNCH_AGENCY_TOOL_NAME}, `sessionSeat()` and the types of the `agencies` options, a launch
+ * tree's limits, the tool's arguments and result, a seat, the frame a seat's turns carry, the turn a tool call came
+ * from, a tool hook and a launched team's registry record (`./index.ts` gathers them); neither exports the launch
+ * registry, the engine (`runLaunch`) or the tool factories (`createGmiLaunchTool`, `createRuntimeLaunchTool`).
  */
 import type { AgentOptions } from '../../agent.js';
 import type { Agent, AgencyStrategy, HitlConfig } from '../../types.js';
 import type { ApprovalGateFn } from '../approval-gate.js';
 import type { SpendBudget } from '../spendBudget.js';
+import type { GMIToolCallGate } from '../../../cognition/substrate/IGMI.js';
+import type { JSONSchemaObject } from '../../../core/tools/ITool.js';
 import type { IToolOrchestrator } from '../../../core/tools/IToolOrchestrator.js';
 export type { SeatMetadata } from '../../types.js';
 /** The tool's name on every surface. */
 export declare const LAUNCH_AGENCY_TOOL_NAME = "launch_agency";
 /** The six strategies a launch offers: the tool's input schema lists them and the engine accepts them. */
 export declare const LAUNCH_STRATEGIES: readonly ["sequential", "parallel", "debate", "review-loop", "hierarchical", "graph"];
-/** The capability a full-runtime persona's grant would name for the tool. No code reads it: gmi() is the one surface that registers `launch_agency`. */
+/**
+ * The capability the full runtime's `launch_agency` requires (`requiredCapabilities`): only a persona whose
+ * `allowedCapabilities` names it lists and calls the tool, while the runtime checks capabilities strictly (its
+ * `toolPermissionManagerConfig.strictCapabilityChecking`, on by default). gmi() registers the tool for its agent alone
+ * and checks no capability.
+ */
 export declare const LAUNCH_CAPABILITY = "agency:launch";
 /** The five self-modification tools, which a seat never gets. */
 export declare const SELF_MODIFICATION_TOOLS: readonly ["forge_tool", "create_workflow", "manage_skills", "self_evaluate", "adapt_personality"];
@@ -31,7 +40,10 @@ export declare const LAUNCH_SETTLE_GRACE_MS = 5000;
 export declare const LAUNCH_TEXT_CHARS = 16000;
 /** The longest seat summary a launch returns. */
 export declare const SEAT_SUMMARY_CHARS = 1000;
-/** The prompt's allowance in the smallest launch: a child's token cap must cover it plus one call's output estimate. */
+/**
+ * The prompt's allowance in the smallest launch: a child's token cap must cover it plus the output estimate of one call,
+ * the largest a seat of the team makes.
+ */
 export declare const MIN_LAUNCH_TOKENS = 2000;
 /** The longest role: `delegate_to_<role>` stays within the 64 characters OpenAI allows a function name. */
 export declare const MAX_ROLE_CHARS = 52;
@@ -43,7 +55,18 @@ export interface AgencyLaunchOptions {
      * Registers `launch_agency` on the agent's tool table. Default false. On gmi(), a launched team's manager, synthesizers
      * and temporary seats run on the provider and model the agent's first call resolved: those its options name, else the
      * environment's pair at that call, whatever the environment names later. A call that names its own provider or model
-     * runs on that pair alone; a team it launches runs on the agent's.
+     * runs on that pair alone; a team it launches runs on the agent's. A temporary seat also takes the agent's other route
+     * and completion settings, its `onBeforeGeneration` and `onAfterGeneration` hooks and, of its controls,
+     * `controls.maxDurationMs` alone: a cap the agent's calls take from `controls.maxTotalTokens` does not reach a seat's
+     * calls, which the launch's budget bounds. Every seat's tool calls run the `onBeforeToolExecution` hooks of the turn
+     * that launched the team, a member's before its own. The manager and synthesizers, which agency() builds on agent(),
+     * take that pair with the agent's key and base URL alone: none of its hooks and no request timeout reach their calls,
+     * which the launch's deadline and budget bound. A seat whose call fails rejects with its error's name and code alone,
+     * so a provider's or a handler's message reaches no model of the team and not the result; the error itself goes to
+     * the agent's `on.error`, under `launch_agency seat <role>` (the console without one), as do the launch's other
+     * failures, a failed run apart: the team reports its run once, under `launch:<agencyId>`, with the error it rejected
+     * with. A seat's name holds its role and not its team, so two teams' seats of one role report under one name. A
+     * callback that throws or rejects fails no launch.
      */
     launch?: boolean;
     /** The deepest team level a launch tree reaches: an integer from 1 to 4, default 2. */
@@ -66,14 +89,54 @@ export interface AgencyLaunchOptions {
     defaultDeadlineMs?: number;
     /** The longest deadline a launch may name, in ms: from 1,000 to 3,600,000, default 600,000. */
     maxDeadlineMs?: number;
-    /** gmi() only: the persistent members a launch may seat by agentKey, each a gmi() handle. */
+    /**
+     * gmi() only: the persistent members a launch may seat by agentKey, each a gmi() handle. The record is read once,
+     * when the agent is built: a member put in it afterwards, under a new key or an old one, is never seated.
+     */
     members?: Record<string, Agent>;
-    /** The approval policy every launched team runs under after the gate the launching turn carries; applied at a root launch and inherited below it. */
+    /**
+     * The approval policy of the team a root launch builds, asked after the gate the launching turn carries. A nested
+     * launch passes that team's gate on, so `beforeTool` covers the seats of every team below it, each tool call asked
+     * once. `beforeAgent` and `beforeReturn` are asked in the root team alone: no nested team's seat or answer waits
+     * for them.
+     */
     hitl?: HitlConfig;
 }
-/** The bounds of a launch on the full runtime, with the route of its coordinator. AgentOSConfig takes no `agencies` option: gmi() is the one surface that registers `launch_agency`. */
-export interface RuntimeAgencyLaunchOptions extends Omit<AgencyLaunchOptions, 'members'> {
-    /** The route of a launched team's manager and synthesizers (they call generateText). Default: the parent persona's provider and model, with the key and base URL of the runtime's entry for that provider. */
+/**
+ * `AgentOSConfig.agencies`: whether the full runtime registers `launch_agency`, and every launch's bounds. `launch: true`
+ * registers the tool, which requires {@link LAUNCH_CAPABILITY}, so only a persona granted it lists and calls it. A
+ * seat is a GMI of the runtime's GMIManager: a registered persona a launch names by `personaId` (in place of
+ * `agentKey`), or a persona made for a temporary seat from the calling GMI's (its route, completion options,
+ * capabilities and hard limits, with the seat's instructions as its prompt). Every seat runs through a view of the
+ * runtime's tools that lists and runs its allowlist alone, as the parent turn's user and organization, with no
+ * cognitive memory, no retrieval and no learner.
+ */
+export interface RuntimeAgencyLaunchOptions extends Omit<AgencyLaunchOptions, 'members' | 'launch'> {
+    /**
+     * Registers `launch_agency` among the runtime's config tools, for the personas granted `agency:launch`: a config tool
+     * of the host's own by that name then fails initialization. Default false. A seat whose call fails rejects with its
+     * error's name and code alone, so a provider's or a handler's message reaches no model of the team and not the
+     * result; the error itself goes to the runtime's logger (the one `AgentOS.create` takes, else its own), at warn,
+     * under `launch_agency seat <role>`, as do the launch's other failures (a failed run under `launch_agency run`). A
+     * logger that throws fails no launch. The output guardrails that judge the launching turn's tool calls
+     * (`config.evaluateToolCalls`) judge each call of every seat, a nested team's included, before it runs, beside the
+     * sources the launching turn retrieved, and a call they block is refused as the launching turn's would be. The usage
+     * the runtime's spend meter (`spendMeter`) records for the launching turn is that turn's own model calls: a team's
+     * calls are its seats' GMIs' and its coordinator's, which the launch's result reports (`usage`, `coordinatorUsage`).
+     */
+    launch?: boolean;
+    /**
+     * The route of a launched team's manager and synthesizers (they call generateText). Default: the provider and model of
+     * the persona of the GMI that launched the team, else the GMIs' defaults
+     * (`gmiManagerConfig.defaultGMIBaseConfigDefaults`); when neither names a provider, the one the runtime's provider
+     * manager serves that model from, as for the GMI itself. A route that names neither `apiKey` nor `baseUrl` takes the
+     * key of the entry in `modelProviderManagerConfig.providers` the runtime serves its provider from (the last enabled one
+     * whose provider started), and sends it where the runtime's provider sends it: to that entry's base URL, else to the
+     * provider's own endpoint, never to a base URL a global default or an environment variable names. An entry with a base
+     * URL and no key gives its base URL alone to an Ollama route only. What the route takes nothing for, generateText
+     * resolves for the provider, key and base URL together, as for any call that names neither. A route that names either
+     * keeps what it names and takes nothing of the entry.
+     */
     coordinator?: {
         provider: string;
         model: string;
@@ -116,6 +179,13 @@ export interface CallerTurnContext {
     toolHooks?: readonly ToolCallHook[];
     /** The processToolCall of the view that made the call; the step gate runs each step of a composed tool through it. */
     dispatch?: IToolOrchestrator['processToolCall'];
+    /**
+     * The full runtime: the gate the turn's output guardrails that judge tool calls (`config.evaluateToolCalls`) ask
+     * before each call of the turn's own tool round. A GMI whose turn has one passes it with every call it makes, asked
+     * beside the sources the turn retrieved, and a team a call launches gives it to each of its seats' turns, so a seat's
+     * calls are judged as the launching turn's are, beside what that turn read.
+     */
+    toolCallGate?: GMIToolCallGate;
 }
 /** One seat a launch names: exactly one of `instructions`, `agentKey` (gmi()) or `personaId` (the full runtime). */
 export type LaunchSeatSpec = {
@@ -172,9 +242,12 @@ export type LaunchStatus = 'completed' | 'timed_out' | 'budget_exhausted' | 'can
  *   or a composed tool one of whose steps its allowlist leaves out.
  * - `seat_form_unsupported`: a seat form the surface does not run (`personaId` on gmi(), `agentKey` on the full runtime).
  * - `unknown_member`: a seat names a member the surface does not have.
- * - `member_unavailable`: a member could not be seated.
+ * - `member_unavailable`: a seat could not be built: a member that cannot take a seat (on the full runtime, a persona
+ *   the user's tier or strict validation refuses), or the agent or GMI made for a temporary seat.
  * - `duplicate_member`: two seats name one member.
- * - `budget_unavailable`: the launch's token cap cannot cover one call, or it has no dollars left.
+ * - `budget_unavailable`: the launch's token cap cannot cover one call of the seat whose calls are largest
+ *   (`MIN_LAUNCH_TOKENS` for the prompt and that seat's output estimate, on the route its calls run on), or it has no
+ *   dollars left.
  * - `parent_launch_closed`: the team the calling seat sits in is closing or gone.
  */
 export type LaunchRefusalCode = 'invalid_arguments' | 'depth_exceeded' | 'too_many_seats' | 'concurrency_exceeded' | 'unknown_tool' | 'tool_not_allowed' | 'seat_form_unsupported' | 'unknown_member' | 'member_unavailable' | 'duplicate_member' | 'budget_unavailable' | 'parent_launch_closed';
@@ -272,14 +345,29 @@ export interface LaunchRecordMetadata {
     /** The goal's first 200 characters. */
     goalPreview: string;
     startedAt: string;
+    /**
+     * 'running' while the team runs; 'closing' once the launch has returned while a seat, or a launch its seats started,
+     * still holds a GMI; the launch's own status, merged with `closedAt` and `usage` just before the entry is removed.
+     */
     status: 'running' | 'closing' | LaunchStatus;
+    /** When the launch returned its result. */
     closedAt?: string;
+    /** The seats' usage, as the launch's result reports it. */
     usage?: LaunchUsage;
 }
 /** Whether `value` is a handle gmi() built (the non-enumerable mark gmi() sets). */
 export declare function isGmiHandle(value: unknown): value is Agent;
 /** The options a gmi() handle was built with, or undefined for any other value. */
 export declare function gmiOptionsOf(value: unknown): AgentOptions | undefined;
+/**
+ * Reads the provider and model a gmi() handle's persona resolved (the pair its options name, else the environment's at
+ * its first build), or undefined for any other value. The read builds the agent's shared state, as its first session
+ * does.
+ */
+export declare function gmiRouteOf(value: unknown): (() => Promise<{
+    provider?: string;
+    model?: string;
+}>) | undefined;
 /**
  * Applies the defaults of `agencies` and checks every bound, at construction (`gmi()`, `AgentOS.initialize`).
  *
@@ -291,6 +379,31 @@ export declare function gmiOptionsOf(value: unknown): AgentOptions | undefined;
  * @throws {AgencyConfigError} For `hitl` approvals with no handler, the rule `agency()` applies.
  */
 export declare function resolveLaunchLimits(options: AgencyLaunchOptions | RuntimeAgencyLaunchOptions): LaunchLimits;
+/**
+ * The persistent members a surface's `launch_agency` seats as themselves: gmi()'s `agencies.members` by `agentKey`, or
+ * the full runtime's registered personas by `personaId`.
+ */
+export type LaunchMemberForm = {
+    field: 'agentKey';
+    keys: readonly string[];
+} | {
+    field: 'personaId';
+};
+/**
+ * The input schema `launch_agency` offers the model. Counts, unknown keys and the forms' rules are the engine's
+ * (`validateLaunchArgs`), with its codes.
+ *
+ * @param limits - The tree's limits: the seat count and the deadlines the schema states.
+ * @param members - The members the surface seats as themselves; none, and the schema offers instructions alone.
+ */
+export declare function launchAgencyInputSchema(limits: LaunchLimits, members?: LaunchMemberForm): JSONSchemaObject;
+/**
+ * What the model reads about `launch_agency`.
+ *
+ * @param limits - The tree's limits: the seat count the description states.
+ * @param members - The members the surface seats as themselves; none, and every seat is an agent made for the team.
+ */
+export declare function launchAgencyDescription(limits: LaunchLimits, members?: LaunchMemberForm): string;
 /** A tool as the seat rules read it: its name and, for a composed tool, the tools its steps call. */
 export interface SeatToolLike {
     readonly name: string;