@lotagate/cli 0.1.21 → 0.1.22

package/dist/application/orchestration/headless-agent-turn.js

@@ -0,0 +1,82 @@
+import { prepareCliAgent } from '../agent/cli-agent-execution-service.js';
+import { AgentRunTracker } from '../agent/agent-run-tracker.js';
+import { CliError } from '../../domain/errors/cli-error.js';
+import { CLI_ERROR_CODES } from '../../domain/errors/error-codes.js';
+import { writeStreamChunk } from '../commands/stream-output.js';
+import { CliTurnEventProjector } from './cli-turn-event-projector.js';
+import { persistCliTurnEvent } from './cli-turn-persistence.js';
+import { agentLimitNotice, classifyAgentLimit } from '../agent/agent-limit.js';
+export async function runHeadlessAgentTurn(options) {
+    const tracker = new AgentRunTracker();
+    const prepared = await prepareCliAgent({
+        runtime: options.runtime, cwd: options.cwd, model: options.model, client: options.client, profile: 'headless-safe', approvalMode: 'auto',
+        ...(options.goal === undefined ? {} : { goal: options.goal }),
+        ...(options.agentSessionStore === undefined ? {} : { agentSessionStore: options.agentSessionStore }),
+        onModelComplete: (summary) => { if (summary.usage !== undefined)
+            options.onUsage?.({ usage: summary.usage, modelCalls: 1 }); },
+        ...(options.onSubagentUsage === undefined ? {} : { onSubagentModelComplete: (summary) => { if (summary.usage !== undefined)
+                options.onSubagentUsage?.({ usage: summary.usage, modelCalls: 1 }); } }),
+    });
+    const response = [];
+    let limitReason;
+    const projector = new CliTurnEventProjector();
+    try {
+        const inputContext = await prepared.buildInput(options.prompt);
+        if (options.agentSessionStore !== undefined && options.sessionId !== undefined) {
+            const history = await options.runtime.sessionStore.readHistory(options.sessionId);
+            options.agentSessionStore.hydrate(options.sessionId, prepared.system, history.transcript, history.events, inputContext.input);
+        }
+        for await (const event of prepared.run({ input: inputContext.input, model: options.model, ...(options.signal === undefined ? {} : { signal: options.signal }), ...(options.sessionId === undefined ? {} : { sessionId: options.sessionId }) })) {
+            tracker.observe(event);
+            for (const projected of projector.observe(event)) {
+                if (options.sessionId !== undefined) {
+                    try {
+                        await persistCliTurnEvent(options.runtime.sessionStore, options.sessionId, projected, { ...(options.turnId === undefined ? {} : { turnId: options.turnId }) });
+                    }
+                    catch (error) {
+                        options.runtime.logger.warn('Unable to persist agent lifecycle event.', { eventType: projected.type, reason: error instanceof Error ? error.message : String(error) });
+                    }
+                }
+                if (projected.type === 'assistant.delta')
+                    response.push(projected.content);
+            }
+            if (options.output !== undefined && options.json)
+                await writeStreamChunk(options.output, `${JSON.stringify(event)}\n`);
+            else if (options.output !== undefined && event.type === 'model.delta')
+                await writeStreamChunk(options.output, event.content);
+            else if (options.output !== undefined && event.type === 'session.completed' && response.length === 0) {
+                response.push(event.content);
+                await writeStreamChunk(options.output, event.content);
+            }
+            if (event.type === 'session.failed') {
+                limitReason = classifyAgentLimit(event.error);
+                if (limitReason === undefined)
+                    throw event.error;
+                break;
+            }
+        }
+        if (limitReason !== undefined) {
+            const notice = agentLimitNotice(limitReason);
+            response.push(response.length === 0 ? notice : `\n\n${notice}`);
+            if (options.output !== undefined && !options.json)
+                await writeStreamChunk(options.output, response.at(-1));
+            if (options.sessionId !== undefined)
+                options.agentSessionStore?.delete(options.sessionId);
+        }
+        if (response.join('').trim().length === 0) {
+            const snapshot = tracker.snapshot();
+            const code = snapshot.toolCalls > 0 ? CLI_ERROR_CODES.MODEL_EMPTY_FINAL : CLI_ERROR_CODES.MODEL_PROTOCOL_EMPTY_RESPONSE;
+            throw new CliError(code, 'Agent completed without a final text response.', { category: 'model', userMessage: 'The model completed without a final text response.', retryable: true });
+        }
+        return response.join('');
+    }
+    finally {
+        options.onSnapshot?.(tracker.snapshot());
+        try {
+            await prepared.close();
+        }
+        catch (error) {
+            options.runtime.logger.warn('Agent cleanup failed after a completed turn.', { reason: error instanceof Error ? error.message : String(error) });
+        }
+    }
+}

package/dist/application/orchestration/plan-generator.d.ts

@@ -0,0 +1,7 @@
+import type { ExecutionPlan } from '../../domain/orchestration/task.js';
+import { TaskAssessmentService } from './task-assessment.js';
+export declare class PlanGenerator {
+    private readonly assessment;
+    constructor(assessment?: TaskAssessmentService);
+    generate(goal: string, requiresApproval?: boolean): ExecutionPlan;
+}

package/dist/application/orchestration/plan-generator.js

@@ -0,0 +1,34 @@
+import crypto from 'node:crypto';
+import { TaskAssessmentService } from './task-assessment.js';
+export class PlanGenerator {
+    assessment;
+    constructor(assessment = new TaskAssessmentService()) {
+        this.assessment = assessment;
+    }
+    generate(goal, requiresApproval = true) {
+        const assessment = this.assessment.assess(goal);
+        const tasks = assessment.requiresPlan ? createTaskPlan(goal, assessment) : [task('execute', assessment.complexity === 'moderate' ? 'Execute the requested work' : 'Answer the request', goal)];
+        return { id: crypto.randomUUID(), goal, tasks, requiresApproval: requiresApproval && assessment.requiresPlan, maxConcurrency: assessment.complexity === 'complex' ? 2 : 1 };
+    }
+}
+function createTaskPlan(goal, assessment) {
+    const intents = new Set(assessment.intents);
+    const tasks = [];
+    if (intents.has('change')) {
+        tasks.push(task('inspect', 'Inspect the relevant context', 'Inspect only the files, contracts, and constraints needed for this change.'));
+        tasks.push(task('implement', 'Apply the requested change', goal, ['inspect']));
+        if (intents.has('verify') || intents.has('change'))
+            tasks.push(task('verify', 'Verify the change', 'Run the focused checks required for the requested change.', ['implement']));
+        return tasks;
+    }
+    if (intents.has('inspect'))
+        tasks.push(task('inspect', 'Inspect the requested context', 'Read or list only the requested files and folders.', []));
+    if (intents.has('verify'))
+        tasks.push(task('verify', 'Run the requested checks', goal, tasks.length === 0 ? [] : [tasks[tasks.length - 1].id]));
+    if (intents.has('answer'))
+        tasks.push(task('answer', 'Summarize the result', 'Answer from the inspected evidence without making changes.', tasks.length === 0 ? [] : [tasks[tasks.length - 1].id]));
+    return tasks.length === 0 ? [task('answer', 'Answer the request', goal)] : tasks;
+}
+function task(id, title, description, dependencies = []) {
+    return { id, title, description, dependencies, status: 'queued' };
+}

package/dist/application/orchestration/subagent-coordinator.d.ts

@@ -0,0 +1,33 @@
+import type { AgentTask, ExecutionPlan, SchedulerLimits } from '../../domain/orchestration/task.js';
+import type { SubagentLimitReason } from '../../domain/orchestration/subagent.js';
+import { TaskScheduler } from './task-scheduler.js';
+export interface SubagentOutput {
+    content: string;
+    tokens?: number;
+    tokensEstimated?: boolean;
+    toolsUsed?: readonly string[];
+    limitReason?: SubagentLimitReason;
+}
+export interface SubagentInstance {
+    run(task: AgentTask, signal: AbortSignal): Promise<SubagentOutput>;
+    close?(): Promise<void>;
+}
+export interface SubagentFactory {
+    create(task: AgentTask): Promise<SubagentInstance>;
+}
+export interface SubagentRunResult {
+    task: AgentTask;
+    output: SubagentOutput;
+}
+export interface SubagentCoordinatorOptions {
+    approvePlan?: (plan: ExecutionPlan) => boolean | Promise<boolean>;
+    onTaskEvent?: (event: {
+        type: 'started' | 'completed' | 'failed';
+        task: AgentTask;
+    }) => void | Promise<void>;
+}
+export declare class SubagentCoordinator {
+    private readonly scheduler;
+    constructor(scheduler?: TaskScheduler);
+    run(plan: ExecutionPlan, factory: SubagentFactory, limits: SchedulerLimits, signal?: AbortSignal, options?: SubagentCoordinatorOptions): Promise<readonly SubagentRunResult[]>;
+}

package/dist/application/orchestration/subagent-coordinator.js

@@ -0,0 +1,28 @@
+import { CliError } from '../../domain/errors/cli-error.js';
+import { CLI_ERROR_CODES } from '../../domain/errors/error-codes.js';
+import { TaskGraph } from './task-graph.js';
+import { TaskScheduler } from './task-scheduler.js';
+export class SubagentCoordinator {
+    scheduler;
+    constructor(scheduler = new TaskScheduler()) {
+        this.scheduler = scheduler;
+    }
+    async run(plan, factory, limits, signal, options = {}) {
+        if (plan.requiresApproval && !(await options.approvePlan?.(plan))) {
+            throw new CliError(CLI_ERROR_CODES.TASK_PLAN_APPROVAL_REQUIRED, 'Plan approval was not granted.', { category: 'orchestration', userMessage: 'Plan approval is required before execution.' });
+        }
+        const graph = new TaskGraph(plan.tasks);
+        const instances = new Map();
+        try {
+            const results = await this.scheduler.run(graph, async (task, taskSignal) => {
+                const instance = await factory.create(task);
+                instances.set(task.id, instance);
+                return instance.run(task, taskSignal);
+            }, { ...limits, maxConcurrency: Math.min(limits.maxConcurrency, plan.maxConcurrency) }, { ...(signal === undefined ? {} : { signal }), estimateTokens: (output) => output.tokens ?? 0, ...(options.onTaskEvent === undefined ? {} : { onTaskEvent: options.onTaskEvent }) });
+            return results.map(({ task, value: output }) => ({ task, output }));
+        }
+        finally {
+            await Promise.allSettled([...instances.values()].map((instance) => instance.close?.()));
+        }
+    }
+}

package/dist/application/orchestration/subagent-handoff.d.ts

@@ -0,0 +1,2 @@
+import type { SubagentHandoff } from '../../domain/orchestration/subagent.js';
+export declare function parseSubagentHandoff(output: string): SubagentHandoff;

package/dist/application/orchestration/subagent-handoff.js

@@ -0,0 +1,68 @@
+import { RESOURCE_LIMITS } from '../../domain/runtime/resource-limits.js';
+const MAX_HANDOFF_ITEMS = 32;
+const MAX_ITEM_BYTES = 1_024;
+export function parseSubagentHandoff(output) {
+    const bounded = boundText(output, RESOURCE_LIMITS.subagentSummaryBytes);
+    const parsed = parseJsonObject(bounded);
+    if (parsed === undefined) {
+        return {
+            summary: bounded || 'The subagent completed without a text summary.',
+            filesInspected: [],
+            filesChanged: [],
+            commandsRun: [],
+            verification: [],
+            warnings: ['The child returned an unstructured summary; verify the result directly.'],
+        };
+    }
+    return {
+        summary: boundedString(parsed['summary']) ?? 'The subagent completed without a text summary.',
+        filesInspected: boundedList(parsed['filesInspected']),
+        filesChanged: boundedList(parsed['filesChanged']),
+        commandsRun: boundedList(parsed['commandsRun']),
+        verification: boundedList(parsed['verification']),
+        warnings: boundedList(parsed['warnings']),
+    };
+}
+function parseJsonObject(value) {
+    const candidates = [value.trim(), extractJsonBlock(value)];
+    for (const candidate of candidates) {
+        if (candidate === undefined || candidate.length === 0)
+            continue;
+        try {
+            const parsed = JSON.parse(candidate);
+            if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed))
+                return parsed;
+        }
+        catch { /* The child may have returned normal prose; the caller receives a warning. */ }
+    }
+    return undefined;
+}
+function extractJsonBlock(value) {
+    const start = value.indexOf('{');
+    const end = value.lastIndexOf('}');
+    return start >= 0 && end > start ? value.slice(start, end + 1) : undefined;
+}
+function boundedList(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .filter((item) => typeof item === 'string')
+        .map((item) => boundedString(item))
+        .filter((item) => item !== undefined)
+        .slice(0, MAX_HANDOFF_ITEMS);
+}
+function boundedString(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    return Buffer.byteLength(trimmed, 'utf8') <= MAX_ITEM_BYTES
+        ? trimmed
+        : `${Buffer.from(trimmed, 'utf8').subarray(0, MAX_ITEM_BYTES - 3).toString('utf8')}...`;
+}
+function boundText(value, maxBytes) {
+    const trimmed = value.trim();
+    const bytes = Buffer.from(trimmed, 'utf8');
+    return bytes.byteLength <= maxBytes ? trimmed : `${bytes.subarray(0, maxBytes - 16).toString('utf8')}\n[truncated]`;
+}

package/dist/application/orchestration/subagent-tool-executor.d.ts

@@ -0,0 +1,12 @@
+import type { ToolDefinition } from '@lotagate/sdk';
+import type { ToolExecutionContext, ToolExecutor, ToolInfo, ToolResult } from '@lotagate/agent-sdk';
+import type { CliSubagentService } from './cli-subagent-service.js';
+/** Exposes the same orchestration capability definitions to runtime and context accounting. */
+export declare function subagentToolDefinitions(): readonly ToolDefinition[];
+export declare class SubagentToolExecutor implements ToolExecutor {
+    private readonly service;
+    constructor(service: CliSubagentService);
+    listTools(): readonly ToolDefinition[];
+    getToolInfo(toolName: string): ToolInfo | undefined;
+    execute(toolName: string, input: Record<string, unknown>, context: ToolExecutionContext): Promise<ToolResult>;
+}

package/dist/application/orchestration/subagent-tool-executor.js

@@ -0,0 +1,93 @@
+const TOOLS = [
+    {
+        type: 'function',
+        function: {
+            name: 'agent.spawn',
+            description: 'Delegate one bounded side task. Research mode is read-only by default; worker mode requires an explicitly requested independent implementation task. Use background true for bounded parallel work and agent.wait for its result.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    task: { type: 'string', description: 'A single, specific task for the child agent.' },
+                    context: { type: 'string', description: 'Optional bounded parent-provided evidence needed to complete the task. Do not include secrets.' },
+                    model: { type: 'string', description: 'Optional model id from the allowlist; omit to inherit the parent model.' },
+                    mode: { type: 'string', enum: ['research', 'worker'], description: 'research (default) or worker for an explicitly requested implementation task.' },
+                    background: { type: 'boolean', description: 'Run without blocking the current turn. Call agent.wait with the returned id when needed.' },
+                    writeScope: { type: 'array', items: { type: 'string' }, description: 'Required for worker mode: workspace-relative files or directories the child may write.' },
+                },
+                required: ['task'],
+                additionalProperties: false,
+            },
+        },
+    },
+    idTool('agent.wait', 'Wait for a background subagent owned by this session and return its structured handoff.'),
+    idTool('agent.cancel', 'Cancel a running background subagent owned by this session.'),
+];
+/** Exposes the same orchestration capability definitions to runtime and context accounting. */
+export function subagentToolDefinitions() { return TOOLS; }
+export class SubagentToolExecutor {
+    service;
+    constructor(service) {
+        this.service = service;
+    }
+    listTools() { return subagentToolDefinitions(); }
+    getToolInfo(toolName) {
+        if (!TOOLS.some((tool) => getToolName(tool) === toolName))
+            return undefined;
+        return { toolName, source: 'custom', executorId: 'cli-subagent', metadata: { category: 'orchestration' } };
+    }
+    async execute(toolName, input, context) {
+        try {
+            const result = toolName === 'agent.spawn'
+                ? await this.service.spawn(parseSpawnRequest(input), context)
+                : toolName === 'agent.wait'
+                    ? await this.service.wait(requireId(input), context)
+                    : toolName === 'agent.cancel'
+                        ? await this.service.cancel(requireId(input), context)
+                        : undefined;
+            if (result === undefined)
+                return { content: `Unknown orchestration tool: ${toolName}`, isError: true };
+            return { content: JSON.stringify(result), isError: result.status === 'failed' || result.status === 'cancelled' };
+        }
+        catch (error) {
+            return { content: error instanceof Error ? error.message : String(error), isError: true };
+        }
+    }
+}
+function parseSpawnRequest(input) {
+    if (typeof input['task'] !== 'string')
+        throw new Error('agent.spawn requires a task string.');
+    const mode = input['mode'];
+    if (mode !== undefined && mode !== 'research' && mode !== 'worker')
+        throw new Error('agent.spawn mode must be research or worker.');
+    const context = input['context'];
+    if (context !== undefined && typeof context !== 'string')
+        throw new Error('agent.spawn context must be a string.');
+    const model = input['model'];
+    if (model !== undefined && typeof model !== 'string')
+        throw new Error('agent.spawn model must be a string.');
+    const background = input['background'];
+    if (background !== undefined && typeof background !== 'boolean')
+        throw new Error('agent.spawn background must be a boolean.');
+    const writeScope = input['writeScope'];
+    if (writeScope !== undefined && (!Array.isArray(writeScope) || writeScope.some((item) => typeof item !== 'string')))
+        throw new Error('agent.spawn writeScope must be an array of strings.');
+    return {
+        task: input['task'],
+        ...(context === undefined ? {} : { context }),
+        ...(model === undefined ? {} : { model }),
+        ...(mode === undefined ? {} : { mode }),
+        ...(background === undefined ? {} : { background }),
+        ...(writeScope === undefined ? {} : { writeScope }),
+    };
+}
+function requireId(input) {
+    if (typeof input['id'] !== 'string' || input['id'].trim().length === 0)
+        throw new Error('The subagent id is required.');
+    return input['id'].trim();
+}
+function idTool(name, description) {
+    return { type: 'function', function: { name, description, parameters: { type: 'object', properties: { id: { type: 'string', description: 'Subagent id returned by agent.spawn.' } }, required: ['id'], additionalProperties: false } } };
+}
+function getToolName(definition) {
+    return 'function' in definition ? definition.function.name : undefined;
+}

package/dist/application/orchestration/task-assessment.d.ts

@@ -0,0 +1,4 @@
+import type { TaskAssessment } from '../../domain/orchestration/task.js';
+export declare class TaskAssessmentService {
+    assess(prompt: string): TaskAssessment;
+}

package/dist/application/orchestration/task-assessment.js

@@ -0,0 +1,35 @@
+export class TaskAssessmentService {
+    assess(prompt) {
+        const normalized = prompt.trim();
+        const reasons = [];
+        let score = 0;
+        if (normalized.length > 240) {
+            score += 1;
+            reasons.push('long prompt');
+        }
+        if (/(and then|sau đó|then|multiple|nhiều|từng bước|plan|kế hoạch|refactor|implement|triển khai)/iu.test(normalized)) {
+            score += 2;
+            reasons.push('multiple steps or implementation work');
+        }
+        if (/@[\w./-]+|\b(files?|folders?|repo|repository|codebase|tests?)\b/iu.test(normalized)) {
+            score += 1;
+            reasons.push('workspace or multiple resource references');
+        }
+        const intents = classifyIntents(normalized);
+        const complexity = score >= 3 ? 'complex' : score >= 1 ? 'moderate' : 'simple';
+        const requiresPlan = complexity === 'complex' || intents.length > 1;
+        return { complexity, requiresPlan, estimatedTasks: requiresPlan ? Math.max(2, intents.length) : 1, reasons, intents };
+    }
+}
+function classifyIntents(prompt) {
+    const intents = [];
+    if (/\b(fix|change|edit|update|implement|add|remove|create|refactor|modify|write|sửa|thêm|xóa|tạo|cập nhật|triển khai)\b/iu.test(prompt))
+        intents.push('change');
+    if (/\b(inspect|check|read|list|review|audit|analy[sz]e|examine|kiểm tra|đọc|liệt kê|xem|rà soát|phân tích)\b|@[\w./-]+/iu.test(prompt))
+        intents.push('inspect');
+    if (/\b(tests?|verify|validate|lint|typecheck|build|kiểm thử|xác minh|kiểm chứng)\b/iu.test(prompt))
+        intents.push('verify');
+    if (intents.length === 0 || (intents.includes('inspect') && !intents.includes('change') && !intents.includes('verify')))
+        intents.push('answer');
+    return intents;
+}

package/dist/application/orchestration/task-graph.d.ts

@@ -0,0 +1,13 @@
+import type { AgentTask, TaskStatus } from '../../domain/orchestration/task.js';
+export declare class TaskGraph {
+    private readonly tasks;
+    constructor(tasks: readonly AgentTask[]);
+    list(): readonly AgentTask[];
+    get(taskId: string): AgentTask | undefined;
+    setStatus(taskId: string, status: TaskStatus): AgentTask;
+    ready(): readonly AgentTask[];
+    hasPending(): boolean;
+    private validateDependencies;
+    private assertAcyclic;
+    private require;
+}

package/dist/application/orchestration/task-graph.js

@@ -0,0 +1,56 @@
+import { CliError } from '../../domain/errors/cli-error.js';
+import { CLI_ERROR_CODES } from '../../domain/errors/error-codes.js';
+export class TaskGraph {
+    tasks = new Map();
+    constructor(tasks) {
+        for (const task of tasks) {
+            if (this.tasks.has(task.id))
+                throw new CliError(CLI_ERROR_CODES.TASK_DEPENDENCY_CYCLE, `Duplicate task id: ${task.id}`, { category: 'orchestration', userMessage: 'The plan contains a duplicate task id.' });
+            this.tasks.set(task.id, { ...task, dependencies: [...task.dependencies] });
+        }
+        this.validateDependencies();
+        this.assertAcyclic();
+    }
+    list() { return [...this.tasks.values()]; }
+    get(taskId) { return this.tasks.get(taskId); }
+    setStatus(taskId, status) {
+        const task = this.require(taskId);
+        const updated = { ...task, status };
+        this.tasks.set(taskId, updated);
+        return updated;
+    }
+    ready() {
+        return this.list().filter((task) => task.status === 'queued' && task.dependencies.every((dependency) => this.tasks.get(dependency)?.status === 'completed'));
+    }
+    hasPending() { return this.list().some((task) => task.status === 'queued' || task.status === 'running'); }
+    validateDependencies() {
+        for (const task of this.tasks.values())
+            for (const dependency of task.dependencies)
+                if (!this.tasks.has(dependency)) {
+                    throw new CliError(CLI_ERROR_CODES.TASK_DEPENDENCY_CYCLE, `Missing task dependency: ${dependency}`, { category: 'orchestration', userMessage: `The plan references a missing dependency: ${dependency}.` });
+                }
+    }
+    assertAcyclic() {
+        const visiting = new Set();
+        const visited = new Set();
+        const visit = (taskId) => {
+            if (visiting.has(taskId))
+                throw new CliError(CLI_ERROR_CODES.TASK_DEPENDENCY_CYCLE, 'Task dependency cycle detected.', { category: 'orchestration', userMessage: 'The plan contains a task dependency cycle.' });
+            if (visited.has(taskId))
+                return;
+            visiting.add(taskId);
+            for (const dependency of this.require(taskId).dependencies)
+                visit(dependency);
+            visiting.delete(taskId);
+            visited.add(taskId);
+        };
+        for (const taskId of this.tasks.keys())
+            visit(taskId);
+    }
+    require(taskId) {
+        const task = this.tasks.get(taskId);
+        if (task === undefined)
+            throw new CliError(CLI_ERROR_CODES.TASK_SCHEDULER_OVERLOADED, `Task not found: ${taskId}`, { category: 'orchestration', userMessage: `Task not found: ${taskId}.` });
+        return task;
+    }
+}

package/dist/application/orchestration/task-scheduler.d.ts

@@ -0,0 +1,18 @@
+import type { AgentTask, SchedulerLimits } from '../../domain/orchestration/task.js';
+import type { TaskGraph } from './task-graph.js';
+export interface TaskExecutionResult<T> {
+    task: AgentTask;
+    value: T;
+    tokens?: number;
+}
+export interface TaskSchedulerOptions<T> {
+    signal?: AbortSignal;
+    estimateTokens?: (value: T) => number;
+    onTaskEvent?: (event: {
+        type: 'started' | 'completed' | 'failed';
+        task: AgentTask;
+    }) => void | Promise<void>;
+}
+export declare class TaskScheduler {
+    run<T>(graph: TaskGraph, execute: (task: AgentTask, signal: AbortSignal) => Promise<T>, limits: SchedulerLimits, options?: TaskSchedulerOptions<T>): Promise<readonly TaskExecutionResult<T>[]>;
+}

package/dist/application/orchestration/task-scheduler.js

@@ -0,0 +1,88 @@
+import { CliError } from '../../domain/errors/cli-error.js';
+import { CLI_ERROR_CODES } from '../../domain/errors/error-codes.js';
+export class TaskScheduler {
+    async run(graph, execute, limits, options = {}) {
+        if (!Number.isInteger(limits.maxConcurrency) || limits.maxConcurrency < 1 || limits.maxConcurrency > 32 || limits.maxTasks < 1 || limits.maxDurationMs < 1) {
+            throw new CliError(CLI_ERROR_CODES.TASK_SCHEDULER_OVERLOADED, 'Scheduler limits are invalid.', { category: 'orchestration', userMessage: 'Scheduler limits are invalid.' });
+        }
+        if (graph.list().length > limits.maxTasks)
+            throw new CliError(CLI_ERROR_CODES.TASK_SCHEDULER_OVERLOADED, 'Plan exceeds the task limit.', { category: 'orchestration', userMessage: 'The plan exceeds the task limit.' });
+        const results = [];
+        const active = new Map();
+        const startedAt = Date.now();
+        const controller = new AbortController();
+        const forwardAbort = () => controller.abort(options.signal?.reason);
+        if (options.signal?.aborted)
+            forwardAbort();
+        else
+            options.signal?.addEventListener('abort', forwardAbort, { once: true });
+        const deadline = setTimeout(() => controller.abort(new Error('Task plan duration limit exceeded.')), limits.maxDurationMs);
+        let usedTokens = 0;
+        try {
+            while (graph.hasPending()) {
+                if (controller.signal.aborted)
+                    throw isDeadlineAbort(controller.signal)
+                        ? durationLimitError()
+                        : interrupted();
+                if (Date.now() - startedAt > limits.maxDurationMs) {
+                    controller.abort();
+                    throw new CliError(CLI_ERROR_CODES.TASK_SCHEDULER_OVERLOADED, 'Plan exceeded its duration limit.', { category: 'orchestration', userMessage: 'The plan exceeded its maximum duration.' });
+                }
+                for (const task of graph.ready()) {
+                    if (active.size >= limits.maxConcurrency)
+                        break;
+                    graph.setStatus(task.id, 'running');
+                    await options.onTaskEvent?.({ type: 'started', task });
+                    const operation = execute(task, controller.signal).then(async (value) => {
+                        graph.setStatus(task.id, 'completed');
+                        const tokens = options.estimateTokens?.(value);
+                        if (tokens !== undefined)
+                            usedTokens += Math.max(0, tokens);
+                        if (limits.maxTokens !== undefined && usedTokens > limits.maxTokens)
+                            throw new CliError(CLI_ERROR_CODES.TASK_SCHEDULER_OVERLOADED, 'Plan exceeded its token budget.', { category: 'orchestration', userMessage: 'The plan exceeded its token budget.' });
+                        results.push({ task: graph.get(task.id) ?? task, value, ...(tokens === undefined ? {} : { tokens }) });
+                        await options.onTaskEvent?.({ type: 'completed', task: graph.get(task.id) ?? task });
+                    }).catch(async (error) => {
+                        graph.setStatus(task.id, 'failed');
+                        await options.onTaskEvent?.({ type: 'failed', task: graph.get(task.id) ?? task });
+                        throw error;
+                    }).finally(() => { active.delete(task.id); });
+                    active.set(task.id, operation);
+                }
+                if (active.size === 0) {
+                    if (graph.hasPending())
+                        throw new CliError(CLI_ERROR_CODES.TASK_SCHEDULER_OVERLOADED, 'No runnable task remains.', { category: 'orchestration', userMessage: 'No runnable task remains; check dependencies or task failures.' });
+                    break;
+                }
+                try {
+                    await Promise.race(active.values());
+                }
+                catch (error) {
+                    // Abort cooperative siblings before observing their cleanup. This avoids
+                    // unnecessary tool calls or provider usage after the plan has failed.
+                    controller.abort(error);
+                    await Promise.allSettled(active.values());
+                    if (isDeadlineAbort(controller.signal))
+                        throw durationLimitError();
+                    throw error;
+                }
+            }
+            return results;
+        }
+        finally {
+            controller.abort();
+            clearTimeout(deadline);
+            await Promise.allSettled(active.values());
+            options.signal?.removeEventListener('abort', forwardAbort);
+        }
+    }
+}
+function isDeadlineAbort(signal) {
+    return signal.reason instanceof Error && signal.reason.message === 'Task plan duration limit exceeded.';
+}
+function durationLimitError() {
+    return new CliError(CLI_ERROR_CODES.TASK_SCHEDULER_OVERLOADED, 'Plan exceeded its duration limit.', { category: 'orchestration', userMessage: 'The plan exceeded its maximum duration.' });
+}
+function interrupted() {
+    return new CliError(CLI_ERROR_CODES.INTERRUPTED, 'Task plan was cancelled.', { category: 'orchestration', userMessage: 'Task plan execution was cancelled.' });
+}

package/dist/application/project/project-trust-service.d.ts

@@ -0,0 +1,13 @@
+import { type ProjectIdentity } from '../../domain/project/project-identity.js';
+import type { ProjectTrustStore, TrustedProject } from '../../ports/project-trust-store.js';
+export declare class ProjectTrustService {
+    private readonly store;
+    constructor(store: ProjectTrustStore);
+    inspect(inputPath: string): Promise<ProjectIdentity>;
+    isTrusted(identity: ProjectIdentity): Promise<boolean>;
+    grant(identity: ProjectIdentity): Promise<TrustedProject>;
+    revoke(identity: ProjectIdentity): Promise<boolean>;
+    requireTrusted(identity: ProjectIdentity): Promise<void>;
+    list(): Promise<readonly TrustedProject[]>;
+    private canonicalize;
+}