@lotagate/cli 0.1.20 → 0.1.22

package/dist/application/formatting/compact-table.d.ts

@@ -0,0 +1,22 @@
+export interface CompactTableRow {
+    readonly name: string;
+    readonly status: string;
+    readonly detail?: string;
+    readonly values?: Readonly<Record<string, string>>;
+}
+export interface CompactTableColumn {
+    readonly key: string;
+    readonly header: string;
+    readonly width?: number;
+    readonly minWidth?: number;
+    readonly maxWidth?: number;
+}
+export interface CompactTableOptions {
+    readonly empty?: string;
+    readonly maxWidth?: number;
+    readonly nameWidth?: number;
+    readonly statusWidth?: number;
+    readonly columns?: readonly CompactTableColumn[];
+}
+/** Formats operational command output as a compact, terminal-safe table. */
+export declare function formatCompactTable(rows: readonly CompactTableRow[], options?: CompactTableOptions): string;

package/dist/application/formatting/compact-table.js

@@ -0,0 +1,49 @@
+/** Formats operational command output as a compact, terminal-safe table. */
+export function formatCompactTable(rows, options = {}) {
+    if (rows.length === 0)
+        return options.empty ?? 'No items.';
+    const maxWidth = Math.max(48, options.maxWidth ?? 100);
+    const columns = options.columns ?? defaultColumns(options);
+    const values = rows.map((row) => columns.map((column) => columnValue(row, column.key)));
+    const widths = constrainWidths(columns, values, maxWidth);
+    const header = columns.map((column, index) => formatCell(column.header, widths[index], index, columns.length)).join('  ');
+    const lines = values.map((row) => row.map((value, index) => formatCell(value, widths[index], index, columns.length)).join('  '));
+    return [header, ...lines].join('\n');
+}
+function defaultColumns(options) {
+    return [
+        { key: 'name', header: 'Name', minWidth: 4, maxWidth: options.nameWidth ?? 28 },
+        { key: 'status', header: 'Status', minWidth: 6, maxWidth: options.statusWidth ?? 16 },
+        { key: 'detail', header: 'Detail', minWidth: 12 },
+    ];
+}
+function columnValue(row, key) {
+    if (key === 'name')
+        return row.name;
+    if (key === 'status')
+        return row.status;
+    if (key === 'detail')
+        return row.detail ?? '';
+    return row.values?.[key] ?? '';
+}
+function constrainWidths(columns, values, maxWidth) {
+    const widths = columns.map((column, index) => {
+        const contentWidth = Math.max(column.header.length, ...values.map((row) => row[index]?.length ?? 0));
+        const preferred = column.width ?? contentWidth;
+        return Math.max(column.minWidth ?? 4, Math.min(preferred, column.maxWidth ?? Number.POSITIVE_INFINITY));
+    });
+    let overflow = widths.reduce((total, width) => total + width, 0) + (columns.length - 1) * 2 - maxWidth;
+    for (let index = widths.length - 1; index >= 0 && overflow > 0; index -= 1) {
+        const minimum = columns[index]?.minWidth ?? 4;
+        const reduction = Math.min(overflow, widths[index] - minimum);
+        widths[index] = widths[index] - reduction;
+        overflow -= reduction;
+    }
+    return widths;
+}
+function formatCell(value, width, index, columnCount) {
+    const truncated = truncate(value, width);
+    return index === columnCount - 1 ? truncated : pad(truncated, width);
+}
+function pad(value, width) { return value.padEnd(width, ' '); }
+function truncate(value, width) { return value.length <= width ? value : `${value.slice(0, Math.max(0, width - 3))}...`; }

package/dist/application/media/video-operation-poller.d.ts

@@ -0,0 +1,5 @@
+import type { MediaExecutionPolicy } from '../../domain/media/media-execution-policy.js';
+import type { VideoOperation } from '../../domain/media/media-contract.js';
+import type { MediaGatewayClient } from '../../ports/media-gateway-client.js';
+/** Foreground gateway polling. The gateway owns provider polling. */
+export declare function waitForVideoOperation(client: MediaGatewayClient, id: string, policy: Pick<MediaExecutionPolicy, 'videoPollIntervalMs' | 'videoWaitTimeoutMs'>, signal: AbortSignal): Promise<VideoOperation>;

package/dist/application/media/video-operation-poller.js

@@ -0,0 +1,42 @@
+import { CliError } from '../../domain/errors/cli-error.js';
+import { CLI_ERROR_CODES } from '../../domain/errors/error-codes.js';
+/** Foreground gateway polling. The gateway owns provider polling. */
+export async function waitForVideoOperation(client, id, policy, signal) {
+    const deadline = Date.now() + policy.videoWaitTimeoutMs;
+    while (Date.now() < deadline) {
+        await abortableSleep(policy.videoPollIntervalMs, signal);
+        const operation = await client.getVideoOperation(id, { signal });
+        if (operation.done || operation.errorMessage !== undefined)
+            return operation;
+    }
+    throw new CliError('MEDIA_VIDEO_WAIT_TIMEOUT', `Timed out waiting for video operation: ${id}`, {
+        category: 'media',
+        retryable: true,
+        userMessage: `Video is still processing. Use \`video status ${id}\` or \`video download ${id}\` later.`,
+    });
+}
+function abortableSleep(milliseconds, signal) {
+    if (signal.aborted)
+        return Promise.reject(interrupted(signal.reason));
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(onComplete, milliseconds);
+        const onAbort = () => {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', onAbort);
+            reject(interrupted(signal.reason));
+        };
+        function onComplete() {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+function interrupted(cause) {
+    return new CliError(CLI_ERROR_CODES.INTERRUPTED, 'Media command interrupted.', {
+        category: 'media',
+        userMessage: 'Media command interrupted.',
+        retryable: true,
+        cause,
+    });
+}

package/dist/application/model/cached-model-catalog.d.ts

@@ -0,0 +1,13 @@
+import type { CacheStore } from '../../ports/cache-store.js';
+import type { ModelCatalogAdapter } from '../../infrastructure/sdk/model-catalog-adapter.js';
+type ModelCatalog = Awaited<ReturnType<ModelCatalogAdapter['listModels']>>;
+export declare class CachedModelCatalog {
+    private readonly source;
+    private readonly cache;
+    private readonly cacheKey;
+    private readonly ttlMs;
+    constructor(source: ModelCatalogAdapter, cache: CacheStore, cacheKey: string, ttlMs: number);
+    listModels(forceRefresh?: boolean): Promise<ModelCatalog>;
+}
+export declare function modelCatalogCacheKey(profileName: string, baseUrl: string): string;
+export {};

package/dist/application/model/cached-model-catalog.js

@@ -0,0 +1,31 @@
+export class CachedModelCatalog {
+    source;
+    cache;
+    cacheKey;
+    ttlMs;
+    constructor(source, cache, cacheKey, ttlMs) {
+        this.source = source;
+        this.cache = cache;
+        this.cacheKey = cacheKey;
+        this.ttlMs = ttlMs;
+    }
+    async listModels(forceRefresh = false) {
+        if (!forceRefresh) {
+            const cached = await this.cache.get('model-catalog', this.cacheKey);
+            if (cached !== undefined && isModelCatalog(cached))
+                return cached;
+        }
+        const fresh = await this.source.listModels();
+        await this.cache.set('model-catalog', this.cacheKey, fresh, { ttlMs: this.ttlMs }).catch(() => undefined);
+        return fresh;
+    }
+}
+export function modelCatalogCacheKey(profileName, baseUrl) {
+    return `${profileName}\0${baseUrl}`;
+}
+function isModelCatalog(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const data = value.data;
+    return Array.isArray(data) && data.every((item) => typeof item === 'object' && item !== null && typeof item.id === 'string');
+}

package/dist/application/model/initial-model-selection.d.ts

@@ -0,0 +1,10 @@
+export interface ModelCandidate {
+    readonly id: string;
+}
+export interface ModelCatalogSource {
+    list(): Promise<{
+        readonly data: readonly ModelCandidate[];
+    }>;
+}
+/** Selects the server-provided first catalog entry without embedding model ids in the CLI. */
+export declare function selectInitialModel(currentModel: string | null, catalog: ModelCatalogSource, persist: (model: string) => Promise<void>): Promise<string | null>;

package/dist/application/model/initial-model-selection.js

@@ -0,0 +1,11 @@
+/** Selects the server-provided first catalog entry without embedding model ids in the CLI. */
+export async function selectInitialModel(currentModel, catalog, persist) {
+    if (currentModel !== null && currentModel.trim().length > 0)
+        return currentModel;
+    const response = await catalog.list();
+    const first = response.data[0]?.id.trim();
+    if (first === undefined || first.length === 0)
+        return null;
+    await persist(first);
+    return first;
+}

package/dist/application/model/model-catalog-service.d.ts

@@ -0,0 +1,6 @@
+import type { CliRuntime } from '../../bootstrap/runtime-factory.js';
+/** Loads the cached selectable model catalogue for all CLI capabilities. */
+export declare function loadModelCatalog(runtime: CliRuntime, cwd: string, forceRefresh?: boolean): Promise<{
+    data: import("@lotagate/sdk").ModelSummary[];
+    object: "list" | string;
+}>;

package/dist/application/model/model-catalog-service.js

@@ -0,0 +1,13 @@
+import { AuthenticationService } from '../auth/authentication-service.js';
+import { createLotaGateClient } from '../../infrastructure/sdk/lotagate-client-factory.js';
+import { ModelCatalogAdapter } from '../../infrastructure/sdk/model-catalog-adapter.js';
+import { loadExecutionConfig } from '../config/execution-config.js';
+import { CachedModelCatalog, modelCatalogCacheKey } from './cached-model-catalog.js';
+/** Loads the cached selectable model catalogue for all CLI capabilities. */
+export async function loadModelCatalog(runtime, cwd, forceRefresh = false) {
+    const loaded = await loadExecutionConfig(runtime, cwd);
+    const profileName = loaded.config.profile ?? AuthenticationService.defaultProfileName();
+    const credential = await runtime.auth.requireCredential(profileName);
+    const catalog = new CachedModelCatalog(new ModelCatalogAdapter(createLotaGateClient(credential.profile, credential.apiKey)), runtime.cache, modelCatalogCacheKey(credential.profile.name, credential.profile.baseUrl), runtime.cachePolicy.modelCatalogTtlMs);
+    return catalog.listModels(forceRefresh);
+}

package/dist/application/model/model-context-window.d.ts

@@ -0,0 +1,3 @@
+import type { CliRuntime } from '../../bootstrap/runtime-factory.js';
+/** Resolves the catalog-provided context window without coupling callers to SDK details. */
+export declare function resolveModelContextWindow(runtime: CliRuntime, model: string | null, profileName?: string | null): Promise<number | undefined>;

package/dist/application/model/model-context-window.js

@@ -0,0 +1,23 @@
+import { AuthenticationService } from '../auth/authentication-service.js';
+import { CachedModelCatalog, modelCatalogCacheKey } from './cached-model-catalog.js';
+import { createLotaGateClient } from '../../infrastructure/sdk/lotagate-client-factory.js';
+import { getModelContextWindow, ModelCatalogAdapter } from '../../infrastructure/sdk/model-catalog-adapter.js';
+/** Resolves the catalog-provided context window without coupling callers to SDK details. */
+export async function resolveModelContextWindow(runtime, model, profileName) {
+    if (model === null || model.trim().length === 0)
+        return undefined;
+    const profile = profileName ?? AuthenticationService.defaultProfileName();
+    const credential = await runtime.credentialStore.get(profile);
+    if (credential === undefined)
+        return undefined;
+    try {
+        const catalog = new CachedModelCatalog(new ModelCatalogAdapter(createLotaGateClient(credential.profile, credential.apiKey)), runtime.cache, modelCatalogCacheKey(credential.profile.name, credential.profile.baseUrl), runtime.cachePolicy.modelCatalogTtlMs);
+        const response = await catalog.listModels();
+        const selected = response.data.find((candidate) => candidate.id === model);
+        return selected === undefined ? undefined : getModelContextWindow(selected);
+    }
+    catch (error) {
+        runtime.logger.debug('Unable to load model context window.', { model, reason: error instanceof Error ? error.message : String(error) });
+        return undefined;
+    }
+}

package/dist/application/orchestration/cli-subagent-service.d.ts

@@ -0,0 +1,70 @@
+import { type AgentEvent, type AgentRunRequest, type ToolExecutionContext } from '@lotagate/agent-sdk';
+import type { CliRuntime } from '../../bootstrap/runtime-factory.js';
+import type { SubagentMode, SubagentRequest, SubagentResult } from '../../domain/orchestration/subagent.js';
+import type { AgentTask } from '../../domain/orchestration/task.js';
+import type { SubagentLastAction, SubagentLifecycleObserver } from '../../ports/subagent-lifecycle.js';
+import type { ModelCallSummary } from '../../ports/model-diagnostics.js';
+export interface PreparedSubagent {
+    readonly initialize: () => Promise<unknown>;
+    readonly run: (request: AgentRunRequest) => AsyncIterable<AgentEvent>;
+    readonly close: () => Promise<void>;
+}
+export interface CliSubagentServiceOptions {
+    readonly runtime: CliRuntime;
+    readonly cwd: string;
+    readonly model: string;
+    readonly allowedModels?: readonly string[];
+    readonly createAgent: (input: {
+        task: AgentTask;
+        displayName: string;
+        model: string;
+        mode: SubagentMode;
+        writeScope?: readonly string[];
+        onAction?: (action: SubagentLastAction) => void;
+        onUsage?: (summary: ModelCallSummary) => void;
+    }) => Promise<PreparedSubagent>;
+    readonly jobs?: SubagentJobRegistry;
+    readonly lifecycle?: SubagentLifecycleObserver;
+}
+export interface CliSubagentService {
+    spawn(request: SubagentRequest, context: ToolExecutionContext): Promise<SubagentResult>;
+    wait(id: string, context: ToolExecutionContext): Promise<SubagentResult>;
+    cancel(id: string, context: ToolExecutionContext): Promise<SubagentResult>;
+}
+interface SubagentJob {
+    readonly id: string;
+    readonly displayName: string;
+    readonly parentSessionId: string;
+    readonly controller: AbortController;
+    promise: Promise<SubagentResult>;
+    result?: SubagentResult;
+}
+/** Owns background-job lifetime for one interactive session across agent turns. */
+export declare class SubagentJobRegistry {
+    readonly jobs: Map<string, SubagentJob>;
+    activeJobs: number;
+    private nextDisplayName;
+    private closed;
+    allocateDisplayName(): string;
+    ensureCapacity(): void;
+    /** Cancels and observes session-owned background work before the TUI exits. */
+    close(): Promise<void>;
+}
+/** Executes least-privileged, bounded child agents and supports resumable background jobs. */
+export declare class DefaultCliSubagentService implements CliSubagentService {
+    private readonly options;
+    private readonly coordinator;
+    private readonly journal;
+    private readonly jobs;
+    constructor(options: CliSubagentServiceOptions);
+    spawn(request: SubagentRequest, context: ToolExecutionContext): Promise<SubagentResult>;
+    wait(id: string, context: ToolExecutionContext): Promise<SubagentResult>;
+    cancel(id: string, context: ToolExecutionContext): Promise<SubagentResult>;
+    private execute;
+    private createInstance;
+    private resolveModel;
+    private ownedJob;
+    private writeJournal;
+    private notifyLifecycle;
+}
+export {};

package/dist/application/orchestration/cli-subagent-service.js

@@ -0,0 +1,328 @@
+import crypto from 'node:crypto';
+import { AgentSdkError, AgentSdkErrorCode } from '@lotagate/agent-sdk';
+import { SubagentCoordinator } from './subagent-coordinator.js';
+import { SubagentJournalStore } from '../../infrastructure/sessions/subagent-journal-store.js';
+import { RESOURCE_LIMITS } from '../../domain/runtime/resource-limits.js';
+import { parseSubagentHandoff } from './subagent-handoff.js';
+import { subagentDisplayName } from '../../domain/orchestration/subagent-identity.js';
+import { CliError } from '../../domain/errors/cli-error.js';
+import { formatMcpActivityName } from '../agent/tool-display.js';
+/** Owns background-job lifetime for one interactive session across agent turns. */
+export class SubagentJobRegistry {
+    jobs = new Map();
+    activeJobs = 0;
+    nextDisplayName = 0;
+    closed = false;
+    allocateDisplayName() {
+        return subagentDisplayName(this.nextDisplayName++);
+    }
+    ensureCapacity() {
+        if (this.closed)
+            throw new Error('The subagent job registry is closed.');
+        while (this.jobs.size >= RESOURCE_LIMITS.subagentMaxRetainedJobs) {
+            const removable = [...this.jobs.entries()].find(([, job]) => job.result !== undefined);
+            if (removable === undefined)
+                throw new Error('The subagent job registry is full; wait for an existing job before starting another.');
+            this.jobs.delete(removable[0]);
+        }
+    }
+    /** Cancels and observes session-owned background work before the TUI exits. */
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        const pending = [...this.jobs.values()].filter((job) => job.result === undefined);
+        for (const job of pending)
+            job.controller.abort(new Error('Interactive session is closing.'));
+        await Promise.allSettled(pending.map((job) => job.promise));
+    }
+}
+/** Executes least-privileged, bounded child agents and supports resumable background jobs. */
+export class DefaultCliSubagentService {
+    options;
+    coordinator = new SubagentCoordinator();
+    journal;
+    jobs;
+    constructor(options) {
+        this.options = options;
+        this.journal = new SubagentJournalStore(options.runtime.paths);
+        this.jobs = options.jobs ?? new SubagentJobRegistry();
+    }
+    async spawn(request, context) {
+        const normalized = normalizeRequest(request);
+        const model = this.resolveModel(normalized.model);
+        const id = crypto.randomUUID();
+        this.jobs.ensureCapacity();
+        const displayName = this.jobs.allocateDisplayName();
+        if (this.jobs.activeJobs >= RESOURCE_LIMITS.subagentMaxConcurrent)
+            throw new Error('The maximum number of concurrent subagents is already running.');
+        this.jobs.activeJobs += 1;
+        const controller = linkedAbortController(context.signal);
+        const job = { id, displayName, parentSessionId: context.sessionId, controller, promise: Promise.resolve(createRunningResult(id, displayName, normalized, model)) };
+        this.jobs.jobs.set(id, job);
+        this.notifyLifecycle({ type: 'created', sessionId: context.sessionId, id, displayName: job.displayName, task: normalized.task, mode: normalized.mode, model, status: 'queued', background: normalized.background, timestamp: Date.now() });
+        this.options.runtime.logger.info?.('Subagent created.', { subagentId: id, displayName, mode: normalized.mode, model, background: normalized.background });
+        const promise = this.execute(id, displayName, normalized, model, context, controller.signal)
+            .then((result) => {
+            job.result = result;
+            this.notifyLifecycle({ type: terminalLifecycleType(result.status), sessionId: context.sessionId, id, displayName: job.displayName, task: normalized.task, mode: normalized.mode, model, status: result.status, background: normalized.background, timestamp: Date.now(), durationMs: result.durationMs, summary: result.summary, handoff: result.handoff });
+            this.options.runtime.logger.info?.('Subagent finished.', { subagentId: id, displayName, status: result.status, durationMs: result.durationMs, toolCount: result.toolsUsed.length, ...(result.limitReason === undefined ? {} : { limitReason: result.limitReason }) });
+            return result;
+        })
+            .finally(() => { this.jobs.activeJobs -= 1; controller.dispose(); });
+        job.promise = promise;
+        if (normalized.background)
+            return createRunningResult(id, displayName, normalized, model);
+        return promise;
+    }
+    async wait(id, context) {
+        return (await this.ownedJob(id, context)).promise;
+    }
+    async cancel(id, context) {
+        const job = await this.ownedJob(id, context);
+        job.controller.abort();
+        return job.promise;
+    }
+    async execute(id, displayName, request, model, context, signal) {
+        const startedAt = Date.now();
+        const mode = request.mode ?? 'research';
+        await this.writeJournal(context.sessionId, { recordType: 'created', id, displayName, task: request.task, mode, model, timestamp: new Date().toISOString() });
+        await this.writeJournal(context.sessionId, { recordType: 'started', id, displayName, mode, model, timestamp: new Date().toISOString() });
+        this.notifyLifecycle({ type: 'started', sessionId: context.sessionId, id, displayName, task: request.task, mode, model, status: 'running', background: request.background ?? false, timestamp: Date.now() });
+        try {
+            const planTask = { id, title: mode === 'research' ? 'Research task' : 'Worker task', description: buildChildInput(request), dependencies: [], status: 'queued' };
+            const results = await this.coordinator.run({ id: `subagent-plan-${id}`, goal: request.task, tasks: [planTask], requiresApproval: false, maxConcurrency: 1 }, { create: async (childTask) => this.createInstance(childTask, displayName, model, mode, request, context) }, schedulerLimits(), signal);
+            const output = results[0]?.output;
+            if (output === undefined)
+                throw new Error('The subagent completed without a result.');
+            const limitReason = output.limitReason;
+            const handoff = addLimitWarning(parseSubagentHandoff(output.content), limitReason);
+            const status = limitReason === undefined ? 'completed' : 'completed_with_warning';
+            const result = {
+                id,
+                displayName,
+                task: request.task,
+                status,
+                mode,
+                model,
+                summary: handoff.summary,
+                handoff,
+                toolsUsed: output.toolsUsed ?? [],
+                ...(output.tokensEstimated === true && output.tokens !== undefined ? { estimatedTokens: output.tokens } : {}),
+                ...(limitReason === undefined ? {} : { limitReason }),
+                durationMs: Date.now() - startedAt,
+            };
+            await this.writeJournal(context.sessionId, { recordType: status, result, timestamp: new Date().toISOString() });
+            return result;
+        }
+        catch (error) {
+            const cancelled = signal.aborted;
+            const limitReason = cancelled ? undefined : classifyLimit(error);
+            const handoff = {
+                summary: cancelled ? 'Subagent cancelled.' : limitReason === undefined ? error instanceof Error ? error.message : String(error) : `Subagent stopped after reaching its ${limitLabel(limitReason)} limit.`,
+                filesInspected: [], filesChanged: [], commandsRun: [], verification: [],
+                warnings: [cancelled ? 'The child was cancelled before completing.' : limitReason === undefined ? 'The child failed before producing a verified handoff.' : `The child reached its ${limitLabel(limitReason)} limit before producing a verified handoff.`],
+            };
+            const terminalStatus = cancelled ? 'cancelled' : limitReason === undefined ? 'failed' : 'completed_with_warning';
+            const result = { id, displayName, task: request.task, status: terminalStatus, mode, model, summary: handoff.summary, handoff, toolsUsed: [], ...(limitReason === undefined ? {} : { limitReason }), durationMs: Date.now() - startedAt };
+            await this.writeJournal(context.sessionId, { recordType: terminalStatus, result, timestamp: new Date().toISOString() });
+            return result;
+        }
+    }
+    async createInstance(task, displayName, model, mode, request, context) {
+        const reportAction = (lastAction) => {
+            this.notifyLifecycle({ type: 'activity', sessionId: context.sessionId, id: task.id, displayName, task: request.task, mode, model, status: 'running', background: request.background ?? false, timestamp: Date.now(), lastAction });
+        };
+        let modelTokens = 0;
+        let modelUsageObserved = false;
+        const child = await this.options.createAgent({ task, displayName, model, mode, ...(request.writeScope === undefined ? {} : { writeScope: request.writeScope }), onAction: reportAction, onUsage: (summary) => {
+                const usage = summary.usage;
+                if (usage === undefined)
+                    return;
+                modelUsageObserved = true;
+                modelTokens += Math.max(usage.totalTokens ?? 0, (usage.promptTokens ?? 0) + (usage.completionTokens ?? 0));
+            } });
+        let closed = false;
+        return {
+            run: async (_task, taskSignal) => {
+                await child.initialize();
+                const content = [];
+                const toolsUsed = new Set();
+                const runRequest = {
+                    input: task.description,
+                    model,
+                    sessionId: task.id,
+                    cwd: context.cwd ?? this.options.cwd,
+                    workspaceRoot: context.workspaceRoot ?? this.options.cwd,
+                    stream: true,
+                    signal: taskSignal,
+                    limits: { maxIterations: RESOURCE_LIMITS.subagentMaxIterations, maxToolCallsPerTurn: RESOURCE_LIMITS.subagentMaxToolCallsPerTurn, maxToolArgumentBytes: RESOURCE_LIMITS.subagentToolArgumentBytes, maxToolResultBytes: RESOURCE_LIMITS.subagentToolResultBytes },
+                    metadata: { parentSessionId: context.sessionId, parentRunId: context.runId, subagentMode: mode },
+                };
+                let limitReason;
+                try {
+                    for await (const event of child.run(runRequest)) {
+                        if (event.type === 'model.delta')
+                            content.push(event.content);
+                        if (event.type === 'session.completed' && content.length === 0)
+                            content.push(event.content);
+                        if (event.type === 'tool.called') {
+                            toolsUsed.add(event.toolName);
+                            const action = mcpAction(event.toolName);
+                            if (action !== undefined)
+                                reportAction(action);
+                        }
+                        if (event.type === 'session.failed')
+                            throw event.error;
+                    }
+                }
+                catch (error) {
+                    if (context.signal?.aborted)
+                        throw error;
+                    limitReason = taskSignal.aborted ? 'timeout' : classifyLimit(error);
+                    if (limitReason === undefined)
+                        throw error;
+                }
+                const summary = boundSummary(content.join(''));
+                const tokens = modelUsageObserved ? modelTokens : Math.ceil(Buffer.byteLength(summary, 'utf8') / 4);
+                return { content: summary, tokens, ...(modelUsageObserved ? {} : { tokensEstimated: true }), toolsUsed: [...toolsUsed].sort(), ...(limitReason === undefined ? {} : { limitReason }) };
+            },
+            close: async () => {
+                if (closed)
+                    return;
+                closed = true;
+                await child.close();
+            },
+        };
+    }
+    resolveModel(requested) {
+        const model = requested ?? this.options.model;
+        const allowed = new Set(this.options.allowedModels ?? [this.options.model]);
+        if (!allowed.has(model))
+            throw new Error(`Subagent model is not allowed: ${model}`);
+        return model;
+    }
+    async ownedJob(id, context) {
+        const normalized = id.trim();
+        const job = this.jobs.jobs.get(normalized);
+        if (job === undefined || job.parentSessionId !== context.sessionId)
+            throw new Error(`Subagent job not found: ${normalized}`);
+        return job;
+    }
+    async writeJournal(parentSessionId, record) {
+        try {
+            await this.journal.append(parentSessionId, this.options.cwd, record);
+        }
+        catch (error) {
+            this.options.runtime.logger.warn('Unable to persist subagent lifecycle record.', { reason: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    notifyLifecycle(event) {
+        const observer = this.options.lifecycle;
+        if (observer === undefined)
+            return;
+        void Promise.resolve(observer.onSubagentLifecycle(event)).catch((error) => {
+            this.options.runtime.logger.warn('Subagent lifecycle observer failed.', { reason: error instanceof Error ? error.message : String(error) });
+        });
+    }
+}
+function normalizeRequest(request) {
+    const task = request.task.trim();
+    if (task.length === 0)
+        throw new Error('agent.spawn requires a non-empty task.');
+    if (Buffer.byteLength(task, 'utf8') > RESOURCE_LIMITS.subagentTaskBytes)
+        throw new Error('agent.spawn task is too large.');
+    const context = request.context?.trim();
+    if (context !== undefined && Buffer.byteLength(context, 'utf8') > RESOURCE_LIMITS.subagentContextBytes)
+        throw new Error('agent.spawn context is too large.');
+    const mode = request.mode ?? 'research';
+    const writeScope = normalizeWriteScope(request.writeScope);
+    if (mode === 'worker' && writeScope.length === 0)
+        throw new Error('Worker subagents require a non-empty writeScope.');
+    if (mode === 'research' && writeScope.length > 0)
+        throw new Error('Research subagents cannot receive a writeScope.');
+    return { ...request, task, mode, background: request.background ?? false, ...(context === undefined ? {} : { context }), ...(writeScope.length === 0 ? {} : { writeScope }) };
+}
+function buildChildInput(request) {
+    const scope = request.writeScope === undefined ? '' : `\n<write_scope>\n${request.writeScope.join('\n')}\n</write_scope>`;
+    if (request.context === undefined)
+        return `<delegated_task>\n${request.task}\n</delegated_task>${scope}`;
+    return `<parent_context>\n${request.context}\n</parent_context>\n<delegated_task>\n${request.task}\n</delegated_task>${scope}`;
+}
+function normalizeWriteScope(value) {
+    if (value === undefined)
+        return [];
+    if (value.length > RESOURCE_LIMITS.subagentMaxWriteScopeItems)
+        throw new Error('agent.spawn writeScope has too many entries.');
+    const normalized = value.map((item) => item.trim()).filter(Boolean);
+    if (normalized.some((item) => Buffer.byteLength(item, 'utf8') > RESOURCE_LIMITS.subagentWriteScopeItemBytes))
+        throw new Error('agent.spawn writeScope entry is too large.');
+    if (normalized.some((item) => pathIsAbsolute(item) || item.split(/[\\/]/u).includes('..')))
+        throw new Error('agent.spawn writeScope must contain workspace-relative paths without traversal.');
+    return [...new Set(normalized)].sort();
+}
+function pathIsAbsolute(value) {
+    return value.startsWith('/') || /^[A-Za-z]:[\\/]/u.test(value) || value.startsWith('\\\\');
+}
+function createRunningResult(id, displayName, request, model) {
+    const mode = request.mode ?? 'research';
+    const handoff = { summary: 'Subagent is running in the background. Call agent.wait with this id when its result is needed.', filesInspected: [], filesChanged: [], commandsRun: [], verification: [], warnings: [] };
+    return { id, displayName, task: request.task, status: 'running', mode, model, summary: handoff.summary, handoff, toolsUsed: [], durationMs: 0 };
+}
+function linkedAbortController(parent) {
+    const controller = new AbortController();
+    const abort = () => controller.abort(parent?.reason);
+    if (parent?.aborted)
+        abort();
+    else
+        parent?.addEventListener('abort', abort, { once: true });
+    return Object.assign(controller, { dispose: () => parent?.removeEventListener('abort', abort) });
+}
+function boundSummary(value) {
+    const text = value.trim() || 'The subagent completed without a text summary.';
+    const bytes = Buffer.from(text, 'utf8');
+    return bytes.byteLength <= RESOURCE_LIMITS.subagentSummaryBytes ? text : `${bytes.subarray(0, RESOURCE_LIMITS.subagentSummaryBytes).toString('utf8')}\n[truncated]`;
+}
+function schedulerLimits() {
+    return { maxConcurrency: 1, maxTasks: 1, maxDurationMs: RESOURCE_LIMITS.subagentMaxDurationMs, maxTokens: RESOURCE_LIMITS.subagentMaxTokens };
+}
+function mcpAction(toolName) {
+    if (toolName.startsWith('filesystem.') || toolName === 'shell.exec' || toolName.startsWith('skill.'))
+        return undefined;
+    return { kind: 'mcp', label: `Using ${redactToolName(formatMcpActivityName(toolName))}` };
+}
+function redactToolName(value) {
+    const redacted = value.replace(/Bearer\s+[^\s]+/giu, 'Bearer [REDACTED]').replace(/sk-[A-Za-z0-9_-]{8,}/gu, '[REDACTED]');
+    return redacted.length <= 180 ? redacted : `${redacted.slice(0, 177)}...`;
+}
+function terminalLifecycleType(status) {
+    if (status === 'completed' || status === 'completed_with_warning' || status === 'failed' || status === 'cancelled')
+        return status;
+    throw new Error(`Subagent execution returned a non-terminal status: ${status}`);
+}
+function addLimitWarning(handoff, reason) {
+    if (reason === undefined)
+        return handoff;
+    return { ...handoff, warnings: [...handoff.warnings, `The child reached its ${limitLabel(reason)} limit before full completion.`] };
+}
+function classifyLimit(error) {
+    if (error instanceof AgentSdkError && error.code === AgentSdkErrorCode.AgentLimitExceeded) {
+        if (error.details?.['maxToolCallsPerTurn'] !== undefined || /tool calls/iu.test(error.message))
+            return 'tool_calls';
+        return 'iteration';
+    }
+    if (error instanceof CliError && /duration/iu.test(error.message))
+        return 'timeout';
+    if (error instanceof CliError && /token budget/iu.test(error.message))
+        return 'tokens';
+    return undefined;
+}
+function limitLabel(reason) {
+    if (reason === 'tool_calls')
+        return 'tool-call';
+    if (reason === 'iteration')
+        return 'iteration';
+    if (reason === 'tokens')
+        return 'token';
+    return 'time';
+}