@lotagate/cli 0.1.21 → 0.1.22

package/dist/application/orchestration/cli-turn-event-projector.d.ts

@@ -0,0 +1,12 @@
+import type { AgentEvent } from '@lotagate/agent-sdk';
+import { type CliTurnEvent } from './cli-turn-events.js';
+/** Converts external agent events into a small, CLI-owned lifecycle projection. */
+export declare class CliTurnEventProjector {
+    private readonly openSegments;
+    observe(event: AgentEvent): readonly CliTurnEvent[];
+    private delta;
+    private closeOpenSegment;
+    private approval;
+    private started;
+    private completed;
+}

package/dist/application/orchestration/cli-turn-event-projector.js

@@ -0,0 +1,81 @@
+import { actionDisplayName, actionId, actionKind } from './cli-turn-events.js';
+/** Converts external agent events into a small, CLI-owned lifecycle projection. */
+export class CliTurnEventProjector {
+    openSegments = new Map();
+    observe(event) {
+        switch (event.type) {
+            case 'session.started':
+                this.openSegments.delete(event.runId);
+                return [{ type: 'turn.started', runId: event.runId, timestamp: event.timestamp }];
+            case 'model.delta': return event.content.length === 0 ? [] : [this.delta(event)];
+            case 'tool.approval.requested': return [...this.closeOpenSegment(event.request.context.runId, 'progress', event.timestamp), this.approval(event)];
+            case 'tool.called': return [...this.closeOpenSegment(event.runId, 'progress', event.timestamp), this.started(event)];
+            case 'tool.completed': return [this.completed(event)];
+            case 'context.compacted': return [{ type: 'context.compacted', runId: event.runId, timestamp: event.timestamp }];
+            case 'session.completed': {
+                const boundary = this.closeOpenSegment(event.runId, 'final', event.timestamp);
+                if (boundary.length > 0)
+                    return [...boundary, { type: 'turn.completed', runId: event.runId, timestamp: event.timestamp }];
+                if (event.content.length === 0)
+                    return [{ type: 'turn.completed', runId: event.runId, timestamp: event.timestamp }];
+                const segmentId = `${event.runId}:final`;
+                return [
+                    { type: 'assistant.delta', runId: event.runId, segmentId, iteration: 0, content: event.content, timestamp: event.timestamp },
+                    { type: 'assistant.segment.completed', runId: event.runId, segmentId, iteration: 0, phase: 'final', timestamp: event.timestamp },
+                    { type: 'turn.completed', runId: event.runId, timestamp: event.timestamp },
+                ];
+            }
+            case 'session.failed': return [...this.closeOpenSegment(event.runId, 'progress', event.timestamp), { type: 'turn.failed', runId: event.runId, error: event.error, timestamp: event.timestamp }];
+            default: return [];
+        }
+    }
+    delta(event) {
+        const segmentId = `${event.runId}:${event.iteration}`;
+        this.openSegments.set(event.runId, { segmentId, iteration: event.iteration });
+        return { type: 'assistant.delta', runId: event.runId, segmentId, iteration: event.iteration, content: event.content, timestamp: event.timestamp };
+    }
+    closeOpenSegment(runId, phase, timestamp) {
+        const open = this.openSegments.get(runId);
+        if (open === undefined)
+            return [];
+        this.openSegments.delete(runId);
+        return [{ type: 'assistant.segment.completed', runId, segmentId: open.segmentId, iteration: open.iteration, phase, timestamp }];
+    }
+    approval(event) {
+        const request = event.request;
+        return {
+            type: 'action.approval_requested',
+            actionId: actionId(request.context.runId, request.toolName),
+            runId: request.context.runId,
+            toolName: request.toolName,
+            displayName: actionDisplayName(request.toolName),
+            kind: actionKind(request.toolName, request.toolInfo?.source),
+            timestamp: event.timestamp,
+        };
+    }
+    started(event) {
+        return {
+            type: 'action.started',
+            actionId: actionId(event.runId, event.toolName),
+            runId: event.runId,
+            toolName: event.toolName,
+            displayName: actionDisplayName(event.toolName),
+            kind: actionKind(event.toolName, event.source),
+            ...(event.source === undefined ? {} : { source: event.source }),
+            timestamp: event.timestamp,
+        };
+    }
+    completed(event) {
+        return {
+            type: 'action.completed',
+            actionId: actionId(event.runId, event.toolName),
+            runId: event.runId,
+            toolName: event.toolName,
+            displayName: actionDisplayName(event.toolName),
+            kind: actionKind(event.toolName, event.source),
+            status: event.isError ? 'failed' : 'completed',
+            isError: event.isError,
+            timestamp: event.timestamp,
+        };
+    }
+}

package/dist/application/orchestration/cli-turn-events.d.ts

@@ -0,0 +1,76 @@
+import type { AgentEvent } from '@lotagate/agent-sdk';
+export type CliActionKind = 'filesystem' | 'shell' | 'mcp' | 'skill' | 'subagent' | 'other';
+export type CliActionStatus = 'waiting_approval' | 'running' | 'completed' | 'failed';
+export type AssistantSegmentPhase = 'progress' | 'final';
+export type CliTurnEvent = {
+    type: 'turn.started';
+    runId: string;
+    timestamp: string;
+} | {
+    type: 'assistant.delta';
+    runId: string;
+    segmentId: string;
+    iteration: number;
+    content: string;
+    timestamp: string;
+} | {
+    type: 'assistant.segment.completed';
+    runId: string;
+    segmentId: string;
+    iteration: number;
+    phase: AssistantSegmentPhase;
+    timestamp: string;
+} | {
+    type: 'action.approval_requested';
+    actionId: string;
+    runId: string;
+    toolName: string;
+    displayName: string;
+    kind: CliActionKind;
+    timestamp: string;
+} | {
+    type: 'action.started';
+    actionId: string;
+    runId: string;
+    toolName: string;
+    displayName: string;
+    kind: CliActionKind;
+    source?: string;
+    timestamp: string;
+} | {
+    type: 'action.completed';
+    actionId: string;
+    runId: string;
+    toolName: string;
+    displayName: string;
+    kind: CliActionKind;
+    status: Extract<CliActionStatus, 'completed' | 'failed'>;
+    isError: boolean;
+    timestamp: string;
+} | {
+    type: 'context.compacted';
+    runId: string;
+    timestamp: string;
+} | {
+    type: 'turn.completed';
+    runId: string;
+    timestamp: string;
+} | {
+    type: 'turn.failed';
+    runId: string;
+    error: Error;
+    timestamp: string;
+};
+export declare function actionId(runId: string, toolName: string): string;
+export declare function actionKind(toolName: string, source?: string): CliActionKind;
+export declare function actionDisplayName(toolName: string): string;
+export declare function isDurableTurnEvent(event: CliTurnEvent): boolean;
+export declare function toSafeTurnEventData(event: CliTurnEvent): Record<string, unknown>;
+/** Produces the only error text permitted in durable turn state or model-facing history. */
+export declare function safeTurnFailureMessage(error: unknown): string;
+export type ActionEvent = Extract<CliTurnEvent, {
+    type: 'action.started' | 'action.completed' | 'action.approval_requested';
+}>;
+export type ProjectableAgentEvent = Extract<AgentEvent, {
+    type: 'session.started' | 'model.delta' | 'tool.approval.requested' | 'tool.called' | 'tool.completed' | 'context.compacted' | 'session.completed' | 'session.failed';
+}>;

package/dist/application/orchestration/cli-turn-events.js

@@ -0,0 +1,39 @@
+import { formatToolActivityName } from '../agent/tool-display.js';
+export function actionId(runId, toolName) {
+    return `${runId}:${toolName}`;
+}
+export function actionKind(toolName, source) {
+    if (toolName === 'agent.spawn')
+        return 'subagent';
+    if (toolName.startsWith('mcp__') || source === 'mcp')
+        return 'mcp';
+    if (toolName.startsWith('filesystem.') || source === 'filesystem')
+        return 'filesystem';
+    if (toolName.startsWith('shell.') || source === 'shell')
+        return 'shell';
+    if (toolName.startsWith('skill.') || source === 'skill')
+        return 'skill';
+    return 'other';
+}
+export function actionDisplayName(toolName) {
+    return formatToolActivityName(toolName);
+}
+export function isDurableTurnEvent(event) {
+    return event.type === 'action.started' || event.type === 'action.completed' || event.type === 'assistant.segment.completed';
+}
+export function toSafeTurnEventData(event) {
+    switch (event.type) {
+        case 'assistant.segment.completed': return { segmentId: event.segmentId, iteration: event.iteration, phase: event.phase };
+        case 'action.started': return { actionId: event.actionId, toolName: event.toolName, displayName: event.displayName, kind: event.kind, source: event.source, status: 'running' };
+        case 'action.completed': return { actionId: event.actionId, toolName: event.toolName, displayName: event.displayName, kind: event.kind, status: event.status, isError: event.isError };
+        case 'context.compacted': return { runId: event.runId };
+        case 'turn.completed': return { runId: event.runId };
+        case 'turn.failed': return { runId: event.runId, message: safeTurnFailureMessage(event.error) };
+        default: return {};
+    }
+}
+/** Produces the only error text permitted in durable turn state or model-facing history. */
+export function safeTurnFailureMessage(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.replace(/(api[-_ ]?key|authorization|bearer|token)\s*[:=]\s*[^\s,;]+/giu, '$1=[REDACTED]').slice(0, 1024);
+}

package/dist/application/orchestration/cli-turn-persistence.d.ts

@@ -0,0 +1,6 @@
+import type { SessionStore } from '../../ports/session-store.js';
+import { type CliTurnEvent } from './cli-turn-events.js';
+/** Persists only sanitized, durable lifecycle metadata; deltas and raw payloads stay ephemeral. */
+export declare function persistCliTurnEvent(store: SessionStore, sessionId: string, event: CliTurnEvent, options?: {
+    turnId?: string;
+}): Promise<void>;

package/dist/application/orchestration/cli-turn-persistence.js

@@ -0,0 +1,14 @@
+import { isDurableTurnEvent, toSafeTurnEventData } from './cli-turn-events.js';
+/** Persists only sanitized, durable lifecycle metadata; deltas and raw payloads stay ephemeral. */
+export async function persistCliTurnEvent(store, sessionId, event, options = {}) {
+    if (!isDurableTurnEvent(event))
+        return;
+    await store.appendEvent({
+        type: `agent.${event.type}`,
+        timestamp: event.timestamp,
+        sessionId,
+        ...(options.turnId === undefined ? {} : { turnId: options.turnId }),
+        ...('runId' in event ? { runId: event.runId } : {}),
+        data: toSafeTurnEventData(event),
+    });
+}

package/dist/application/orchestration/goal-evaluator.d.ts

@@ -0,0 +1,18 @@
+import type { LotaGate } from '@lotagate/sdk';
+import type { GoalEvaluation } from '../../domain/orchestration/goal.js';
+import type { ModelUsageReport } from '../../ports/model-diagnostics.js';
+export interface GoalVerificationContext {
+    toolCalls: number;
+    toolFailures: number;
+    toolNames: readonly string[];
+}
+export interface GoalEvaluationInput {
+    objective: string;
+    response: string;
+    turn: number;
+    model: string;
+    signal?: AbortSignal;
+    verification?: GoalVerificationContext;
+    onUsage?: (report: ModelUsageReport) => void;
+}
+export declare function evaluateGoal(client: LotaGate, input: GoalEvaluationInput): Promise<GoalEvaluation>;

package/dist/application/orchestration/goal-evaluator.js

@@ -0,0 +1,88 @@
+import { RESOURCE_LIMITS } from '../../domain/runtime/resource-limits.js';
+import { estimateTurnUsage } from '../../infrastructure/tokens/tiktoken-token-estimator.js';
+export async function evaluateGoal(client, input) {
+    const evaluatorPrompt = [
+        `<objective>\n${bounded(input.objective, RESOURCE_LIMITS.goalObjectiveBytes)}\n</objective>`,
+        `<latest-turn>\n${bounded(input.response, RESOURCE_LIMITS.goalEvidenceBytes)}\n</latest-turn>`,
+        `<verification>\n${formatVerification(input.verification)}\n</verification>`,
+        `<turn>${input.turn}</turn>`,
+    ].join('\n');
+    try {
+        const response = await client.chat.completions.create({
+            model: input.model,
+            messages: [
+                { role: 'system', content: 'Evaluate whether the user goal is complete. Return JSON only with decision (continue|complete|blocked), reason, and evidence (array of strings). Mark complete only when every requirement has concrete evidence from the latest work and verification context. A model claim alone is not evidence. Do not invent evidence and do not use tools.' },
+                { role: 'user', content: evaluatorPrompt },
+            ],
+            stream: false,
+            max_tokens: 512,
+            temperature: 0,
+        }, input.signal === undefined ? undefined : { signal: input.signal });
+        const content = response.choices[0]?.message.content;
+        const usage = mapUsage(response.usage);
+        const estimated = usage === undefined ? estimateTurnUsage({ model: input.model, prompt: evaluatorPrompt, response: textContent(content) }) : usage;
+        if (estimated !== undefined)
+            input.onUsage?.({ usage: estimated, modelCalls: 1 });
+        const parsed = parseEvaluation(content);
+        if (parsed === undefined)
+            throw new Error('Goal evaluator returned an invalid decision.');
+        return { ...requireConcreteCompletionEvidence(parsed, input.verification), timestamp: new Date().toISOString(), evaluatorModel: input.model };
+    }
+    catch (error) {
+        throw new Error(`Goal evaluator failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+}
+function requireConcreteCompletionEvidence(evaluation, verification) {
+    if (evaluation.decision !== 'complete')
+        return evaluation;
+    if (verification === undefined || verification.toolCalls === 0 || verification.toolFailures > 0) {
+        return {
+            decision: 'continue',
+            reason: 'Completion requires successful tool-backed verification; continue inspecting and validating the workspace.',
+            evidence: verification?.toolFailures === 0 ? verification.toolNames : [],
+        };
+    }
+    return evaluation;
+}
+function parseEvaluation(content) {
+    const text = textContent(content);
+    const match = text.match(/\{[\s\S]*\}/u);
+    if (match === null)
+        return undefined;
+    try {
+        const value = JSON.parse(match[0]);
+        const decision = value['decision'];
+        const reason = value['reason'];
+        const evidence = value['evidence'];
+        if (decision !== 'continue' && decision !== 'complete' && decision !== 'blocked')
+            return undefined;
+        if (typeof reason !== 'string' || !Array.isArray(evidence) || evidence.some((item) => typeof item !== 'string'))
+            return undefined;
+        return { decision, reason: bounded(reason, RESOURCE_LIMITS.goalReasonBytes), evidence: evidence.slice(0, RESOURCE_LIMITS.goalEvidenceItems).map((item) => bounded(item, RESOURCE_LIMITS.goalEvidenceBytes)) };
+    }
+    catch {
+        return undefined;
+    }
+}
+function mapUsage(usage) {
+    if (usage === undefined)
+        return undefined;
+    return {
+        ...(typeof usage.prompt_tokens === 'number' ? { promptTokens: usage.prompt_tokens } : {}),
+        ...(typeof usage.completion_tokens === 'number' ? { completionTokens: usage.completion_tokens } : {}),
+        ...(typeof usage.total_tokens === 'number' ? { totalTokens: usage.total_tokens } : {}),
+    };
+}
+function formatVerification(value) {
+    if (value === undefined)
+        return 'No tool verification metadata was available; do not mark complete from a claim alone.';
+    return `tool_calls=${value.toolCalls}; tool_failures=${value.toolFailures}; tools=${value.toolNames.slice(0, 32).join(', ') || 'none'}`;
+}
+function textContent(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    return content.map((part) => typeof part === 'object' && part !== null && 'text' in part && typeof part.text === 'string' ? part.text : '').join('');
+}
+function bounded(value, maximum) { return value.length <= maximum ? value : `${value.slice(0, maximum - 3)}...`; }

package/dist/application/orchestration/goal-input.d.ts

@@ -0,0 +1,3 @@
+import type { CreateGoalInput } from '../../domain/orchestration/goal.js';
+export declare function parseGoalInput(objective: string, flags: ReadonlyMap<string, string | boolean>): CreateGoalInput;
+export declare function parseGoalLimits(flags: ReadonlyMap<string, string | boolean>): Omit<CreateGoalInput, 'objective'>;

package/dist/application/orchestration/goal-input.js

@@ -0,0 +1,19 @@
+import { getPositiveIntegerFlag } from '../commands/cli-args.js';
+import { RESOURCE_LIMITS } from '../../domain/runtime/resource-limits.js';
+export function parseGoalInput(objective, flags) {
+    return { objective, maxTurns: RESOURCE_LIMITS.goalDefaultMaxTurns, maxDurationMs: RESOURCE_LIMITS.goalDefaultMaxDurationMs, ...parseGoalLimits(flags) };
+}
+export function parseGoalLimits(flags) {
+    const tokenBudget = readPositive(flags, 'token-budget');
+    const maxTurns = readPositive(flags, 'max-turns');
+    const maxDurationMs = readPositive(flags, 'max-duration-ms');
+    return { ...(tokenBudget === undefined ? {} : { tokenBudget }), ...(maxTurns === undefined ? {} : { maxTurns }), ...(maxDurationMs === undefined ? {} : { maxDurationMs }) };
+}
+function readPositive(flags, name) {
+    const maximum = name === 'max-duration-ms'
+        ? RESOURCE_LIMITS.goalMaximumMaxDurationMs
+        : name === 'max-turns'
+            ? RESOURCE_LIMITS.goalMaximumMaxTurns
+            : RESOURCE_LIMITS.goalMaximumTokenBudget;
+    return getPositiveIntegerFlag(flags, name, maximum);
+}

package/dist/application/orchestration/goal-output.d.ts

@@ -0,0 +1,2 @@
+import type { GoalState } from '../../domain/orchestration/goal.js';
+export declare function formatGoalStatus(state: GoalState): string;

package/dist/application/orchestration/goal-output.js

@@ -0,0 +1,11 @@
+export function formatGoalStatus(state) {
+    return [
+        `Goal ${state.status}`, `Objective: ${state.objective}`, `Turns: ${state.turns}`, `Evaluator runs: ${state.evaluatorRuns}`,
+        `Tokens: ${state.usage.totalTokens} (input ${state.usage.inputTokens}, output ${state.usage.outputTokens}${state.usage.estimated ? ', estimated' : ''})`,
+        ...(state.tokenBudget === undefined ? [] : [`Token budget: ${state.tokenBudget}`]),
+        ...(state.maxTurns === undefined ? [] : [`Max turns: ${state.maxTurns}`]),
+        ...(state.maxDurationMs === undefined ? [] : [`Max duration: ${state.maxDurationMs} ms`]),
+        ...(state.lastError === undefined ? [] : [`Last error: ${state.lastError}`]),
+        ...(state.lastEvaluation === undefined ? [] : [`Last evaluation: ${state.lastEvaluation.decision} — ${state.lastEvaluation.reason}`]),
+    ].join('\n');
+}

package/dist/application/orchestration/goal-runner.d.ts

@@ -0,0 +1,22 @@
+import type { LotaGate } from '@lotagate/sdk';
+import type { AgentRunSnapshot } from '../agent/agent-run-tracker.js';
+import type { CliRuntime } from '../../bootstrap/runtime-factory.js';
+import type { GoalState } from '../../domain/orchestration/goal.js';
+import { GoalUsageAccumulator } from './goal-usage.js';
+export interface GoalRunnerOptions {
+    runtime: CliRuntime;
+    sessionId: string;
+    objective: string;
+    model: string;
+    client: LotaGate;
+    signal?: AbortSignal;
+    initialPrompt?: string;
+    runTurn: (prompt: string, callbacks: GoalTurnCallbacks, signal: AbortSignal) => Promise<string>;
+    onMessage?: (message: string) => void;
+}
+export interface GoalTurnCallbacks {
+    onUsage: (report: Parameters<GoalUsageAccumulator['add']>[0]) => void;
+    onSnapshot: (snapshot: AgentRunSnapshot) => void;
+    onError: (error: unknown) => void;
+}
+export declare function runGoalLoop(options: GoalRunnerOptions): Promise<GoalState | undefined>;

package/dist/application/orchestration/goal-runner.js

@@ -0,0 +1,153 @@
+import { RESOURCE_LIMITS } from '../../domain/runtime/resource-limits.js';
+import { evaluateGoal } from './goal-evaluator.js';
+import { GoalUsageAccumulator } from './goal-usage.js';
+import { CliError } from '../../domain/errors/cli-error.js';
+export async function runGoalLoop(options) {
+    let prompt = options.initialPrompt ?? options.objective;
+    let turnsThisRun = 0;
+    let evaluatorRunsThisRun = 0;
+    options.onMessage?.(`Goal started: ${options.objective}`);
+    while (true) {
+        const state = await options.runtime.goalStore.get(options.sessionId);
+        if (state === undefined || state.status !== 'active')
+            break;
+        const limit = executionLimit(state, turnsThisRun, evaluatorRunsThisRun);
+        if (limit !== undefined) {
+            await pauseForLimit(options, limit);
+            break;
+        }
+        await options.runtime.goalStore.recordTurn(options.sessionId);
+        turnsThisRun += 1;
+        const turnUsage = new GoalUsageAccumulator();
+        let verification;
+        let turnError;
+        let response = '';
+        const turn = deadlineSignal(state, options.signal);
+        try {
+            response = await options.runTurn(prompt, {
+                onUsage: (report) => turnUsage.add(report),
+                onSnapshot: (snapshot) => { verification = { toolCalls: snapshot.toolCalls, toolFailures: snapshot.toolFailures, toolNames: snapshot.toolNames }; },
+                onError: (error) => { turnError = error; },
+            }, turn.signal);
+        }
+        catch (error) {
+            turnError = error;
+        }
+        finally {
+            turn.dispose();
+        }
+        await persistUsage(options, turnUsage);
+        if (isGoalDeadline(turn.signal, options.signal)) {
+            await pauseForLimit(options, { kind: 'duration', reason: 'Goal execution duration limit reached.' });
+            break;
+        }
+        if (turnError !== undefined || response.trim().length === 0) {
+            await pauseAfterFailure(options, turnError ?? new Error('The agent turn did not return a final response.'));
+            break;
+        }
+        const afterTurn = await options.runtime.goalStore.get(options.sessionId);
+        if (afterTurn?.tokenBudget !== undefined && afterTurn.usage.totalTokens >= afterTurn.tokenBudget) {
+            await pauseForLimit(options, { kind: 'tokens', reason: 'Goal token budget reached after the agent turn.' });
+            break;
+        }
+        const evaluationUsage = new GoalUsageAccumulator();
+        const evaluationDeadline = deadlineSignal(afterTurn ?? state, options.signal);
+        try {
+            const evaluation = await evaluateGoal(options.client, {
+                objective: options.objective,
+                response,
+                turn: afterTurn?.turns ?? state.turns + 1,
+                model: options.model,
+                signal: evaluationDeadline.signal,
+                ...(verification === undefined ? {} : { verification }),
+                onUsage: (report) => evaluationUsage.add(report),
+            });
+            if (isGoalDeadline(evaluationDeadline.signal, options.signal)) {
+                await pauseForLimit(options, { kind: 'duration', reason: 'Goal execution duration limit reached during evaluation.' });
+                break;
+            }
+            evaluatorRunsThisRun += 1;
+            await persistUsage(options, evaluationUsage);
+            const afterEvaluation = await options.runtime.goalStore.get(options.sessionId);
+            const updated = afterEvaluation?.tokenBudget !== undefined && afterEvaluation.usage.totalTokens >= afterEvaluation.tokenBudget
+                ? await pauseForLimit(options, { kind: 'tokens', reason: 'Goal token budget reached during evaluation.' })
+                : await options.runtime.goalStore.recordEvaluation(options.sessionId, evaluation);
+            if (updated?.status !== 'active')
+                break;
+            prompt = nextPrompt(options.objective, evaluation.reason, evaluation.evidence);
+        }
+        catch (error) {
+            if (isGoalDeadline(evaluationDeadline.signal, options.signal)) {
+                await persistUsage(options, evaluationUsage);
+                await pauseForLimit(options, { kind: 'duration', reason: 'Goal execution duration limit reached during evaluation.' });
+                break;
+            }
+            await persistUsage(options, evaluationUsage);
+            await pauseAfterFailure(options, error);
+            break;
+        }
+        finally {
+            evaluationDeadline.dispose();
+        }
+    }
+    const final = await options.runtime.goalStore.get(options.sessionId);
+    options.onMessage?.(final === undefined ? 'Goal ended.' : `Goal ${final.status}. Turns: ${final.turns}. Tokens: ${final.usage.totalTokens}${final.usage.estimated ? ' (estimated)' : ''}.`);
+    return final;
+}
+function deadlineSignal(state, parent) {
+    const controller = new AbortController();
+    const abort = () => controller.abort(parent?.reason);
+    if (parent?.aborted)
+        abort();
+    else
+        parent?.addEventListener('abort', abort, { once: true });
+    const remaining = Math.max(1, (state.maxDurationMs ?? RESOURCE_LIMITS.goalDefaultMaxDurationMs) - (Date.now() - Date.parse(state.startedAt)));
+    const timer = setTimeout(() => controller.abort(new Error('Goal execution duration limit reached.')), remaining);
+    return { signal: controller.signal, dispose: () => { clearTimeout(timer); parent?.removeEventListener('abort', abort); } };
+}
+function executionLimit(state, turnsThisRun, evaluatorRunsThisRun) {
+    const maxTurns = state.maxTurns ?? RESOURCE_LIMITS.goalDefaultMaxTurns;
+    if (turnsThisRun >= maxTurns)
+        return { kind: 'turns', reason: 'Goal safety turn guard reached for this run.' };
+    if (evaluatorRunsThisRun >= RESOURCE_LIMITS.goalDefaultMaxEvaluatorRuns)
+        return { kind: 'evaluator', reason: 'Goal safety evaluator guard reached for this run.' };
+    if (state.tokenBudget !== undefined && state.usage.totalTokens >= state.tokenBudget)
+        return { kind: 'tokens', reason: 'Goal token budget reached.' };
+    const started = Date.parse(state.startedAt);
+    const elapsed = Number.isFinite(started) ? Date.now() - started : Number.MAX_SAFE_INTEGER;
+    if (elapsed >= (state.maxDurationMs ?? RESOURCE_LIMITS.goalDefaultMaxDurationMs))
+        return { kind: 'duration', reason: 'Goal execution duration limit reached.' };
+    return undefined;
+}
+async function persistUsage(options, usage) {
+    const delta = usage.delta();
+    if ((delta.modelCalls ?? 0) === 0)
+        return;
+    const state = await options.runtime.goalStore.get(options.sessionId);
+    if (state?.status === 'active')
+        await options.runtime.goalStore.recordUsage(options.sessionId, delta);
+}
+async function pauseAfterFailure(options, error) {
+    const reason = sanitizeFailureReason(error);
+    const state = await options.runtime.goalStore.get(options.sessionId);
+    if (state?.status === 'active')
+        await options.runtime.goalStore.pause(options.sessionId, `Goal paused: ${reason}`);
+}
+async function pauseForLimit(options, limit) {
+    const state = await options.runtime.goalStore.get(options.sessionId);
+    if (state?.status !== 'active')
+        return state;
+    const paused = await options.runtime.goalStore.pause(options.sessionId, `Goal paused by safety limit: ${limit.reason}`);
+    options.onMessage?.(`Goal paused safely: ${limit.reason}\nResume the goal to continue from the persisted state.`);
+    return paused;
+}
+function isGoalDeadline(signal, parent) {
+    return signal.aborted && signal !== parent && signal.reason instanceof Error && /Goal execution duration limit reached/iu.test(signal.reason.message);
+}
+function sanitizeFailureReason(error) {
+    const raw = error instanceof CliError ? error.userMessage : error instanceof Error ? error.message : String(error);
+    return raw.replace(/(api[-_ ]?key|authorization|bearer|token)\s*[:=]\s*[^\s,;]+/giu, '$1=[REDACTED]').slice(0, RESOURCE_LIMITS.goalReasonBytes);
+}
+function nextPrompt(objective, reason, evidence) {
+    return `<active-goal>\n${objective}\n</active-goal>\n<last-evaluation>\n${reason}\n${evidence.join('\n')}\n</last-evaluation>\nContinue the work and verify the remaining requirements.`;
+}

package/dist/application/orchestration/goal-usage.d.ts

@@ -0,0 +1,9 @@
+import type { ChatUsage } from '../../ports/chat-model.js';
+import type { ModelUsageReport } from '../../ports/model-diagnostics.js';
+import type { GoalUsage, GoalUsageDelta } from '../../domain/orchestration/goal.js';
+export declare class GoalUsageAccumulator {
+    private current;
+    add(report: ModelUsageReport | ChatUsage): void;
+    snapshot(): GoalUsage;
+    delta(): GoalUsageDelta;
+}

package/dist/application/orchestration/goal-usage.js

@@ -0,0 +1,19 @@
+export class GoalUsageAccumulator {
+    current = { inputTokens: 0, outputTokens: 0, totalTokens: 0, modelCalls: 0, estimated: false };
+    add(report) {
+        const usage = 'usage' in report ? report.usage : report;
+        const modelCalls = 'usage' in report ? report.modelCalls ?? 1 : 1;
+        const inputTokens = usage.promptTokens ?? 0;
+        const outputTokens = usage.completionTokens ?? 0;
+        const totalTokens = Math.max(usage.totalTokens ?? 0, inputTokens + outputTokens);
+        this.current = {
+            inputTokens: this.current.inputTokens + inputTokens,
+            outputTokens: this.current.outputTokens + outputTokens,
+            totalTokens: this.current.totalTokens + totalTokens,
+            modelCalls: this.current.modelCalls + modelCalls,
+            estimated: this.current.estimated || usage.estimated === true,
+        };
+    }
+    snapshot() { return { ...this.current }; }
+    delta() { return { ...this.current }; }
+}

package/dist/application/orchestration/headless-agent-turn.d.ts

@@ -0,0 +1,32 @@
+import type { LotaGate } from '@lotagate/sdk';
+import type { CliRuntime } from '../../bootstrap/runtime-factory.js';
+import type { AgentGoalSummary } from '../agent/capability-profile.js';
+import type { SessionStore as AgentSessionStore } from '@lotagate/agent-sdk';
+import type { ModelUsageReport } from '../../ports/model-diagnostics.js';
+import type { AgentRunSnapshot } from '../agent/agent-run-tracker.js';
+import type { SessionEvent, TranscriptEntry } from '../../domain/session/session.js';
+type HydratableAgentSessionStore = AgentSessionStore & {
+    hydrate(sessionId: string, systemPrompt: string, transcript: readonly TranscriptEntry[], events: readonly SessionEvent[], currentInput: string): void;
+    delete(sessionId: string): void;
+};
+export interface HeadlessAgentTurnOptions {
+    runtime: CliRuntime;
+    cwd: string;
+    model: string;
+    client: LotaGate;
+    prompt: string;
+    output?: {
+        write(chunk: string): unknown;
+    };
+    json?: boolean;
+    signal?: AbortSignal;
+    sessionId?: string;
+    turnId?: string;
+    goal?: AgentGoalSummary;
+    agentSessionStore?: HydratableAgentSessionStore;
+    onUsage?: (report: ModelUsageReport) => void;
+    onSubagentUsage?: (report: ModelUsageReport) => void;
+    onSnapshot?: (snapshot: AgentRunSnapshot) => void;
+}
+export declare function runHeadlessAgentTurn(options: HeadlessAgentTurnOptions): Promise<string>;
+export {};