@lotagate/cli 0.1.21 → 0.1.22

package/dist/application/agent/agent-history.d.ts

@@ -0,0 +1,3 @@
+import type { SessionEvent, TranscriptEntry } from '../../domain/session/session.js';
+/** Builds model-facing history without deleting the durable transcript. */
+export declare function buildAgentHistory(transcript: readonly TranscriptEntry[], events: readonly SessionEvent[]): TranscriptEntry[];

package/dist/application/agent/agent-history.js

@@ -0,0 +1,81 @@
+const TURN_EVENTS = new Set(['turn.started', 'turn.completed', 'turn.failed', 'turn.cancelled']);
+/** Builds model-facing history without deleting the durable transcript. */
+export function buildAgentHistory(transcript, events) {
+    const states = resolveTurnStates(events);
+    const legacyStates = resolveLegacyTurnStates(events);
+    const legacyUsers = transcript.filter((entry) => entry.type === 'user' && entry.turnId === undefined);
+    const representedTurns = new Set();
+    const history = [];
+    for (const entry of transcript) {
+        let state;
+        if (entry.turnId !== undefined)
+            state = states.get(entry.turnId);
+        else if (entry.type === 'user') {
+            state = legacyStates[legacyUsers.indexOf(entry)];
+        }
+        if (state === undefined || state.outcome === 'completed') {
+            history.push(entry);
+            continue;
+        }
+        if (entry.turnId !== undefined) {
+            if (representedTurns.has(entry.turnId))
+                continue;
+            representedTurns.add(entry.turnId);
+        }
+        if (entry.type !== 'user' && entry.turnId !== undefined)
+            continue;
+        history.push(failedTurnReference(entry, state));
+    }
+    return history;
+}
+function resolveTurnStates(events) {
+    const states = new Map();
+    for (const event of events) {
+        if (event.turnId === undefined || !TURN_EVENTS.has(event.type))
+            continue;
+        if (event.type === 'turn.started')
+            states.set(event.turnId, { outcome: 'incomplete' });
+        else if (event.type === 'turn.completed')
+            states.set(event.turnId, { outcome: 'completed' });
+        else {
+            const message = eventMessage(event);
+            states.set(event.turnId, { outcome: event.type === 'turn.cancelled' ? 'cancelled' : 'failed', ...(message === undefined ? {} : { message }) });
+        }
+    }
+    return states;
+}
+function resolveLegacyTurnStates(events) {
+    const states = [];
+    for (const event of events) {
+        if (event.turnId !== undefined || !TURN_EVENTS.has(event.type))
+            continue;
+        if (event.type === 'turn.started')
+            states.push({ outcome: 'incomplete' });
+        else {
+            const current = states.at(-1);
+            if (current === undefined)
+                continue;
+            current.outcome = event.type === 'turn.completed' ? 'completed' : event.type === 'turn.cancelled' ? 'cancelled' : 'failed';
+            const message = eventMessage(event);
+            if (message === undefined)
+                delete current.message;
+            else
+                current.message = message;
+        }
+    }
+    return states;
+}
+function failedTurnReference(entry, state) {
+    const status = state.outcome === 'cancelled' ? 'cancelled' : state.outcome === 'incomplete' ? 'incomplete' : 'failed';
+    const reason = state.message === undefined ? 'The turn did not complete.' : `Reason: ${state.message}`;
+    return {
+        type: 'system',
+        timestamp: entry.timestamp,
+        ...(entry.turnId === undefined ? {} : { turnId: entry.turnId }),
+        content: `[Previous turn — ${status}; reference only]\nOriginal request:\n${entry.content}\n${reason}\nDo not retry or continue this request unless the current user explicitly asks.`,
+    };
+}
+function eventMessage(event) {
+    const message = event.data?.['message'];
+    return typeof message === 'string' && message.trim().length > 0 ? message.slice(0, 1024) : undefined;
+}

package/dist/application/agent/agent-input-context.d.ts

@@ -0,0 +1,9 @@
+import { type WorkspaceFileReference } from '../workspace/workspace-file-reference-resolver.js';
+export interface AgentInputContext {
+    readonly input: string;
+    readonly references: readonly WorkspaceFileReference[];
+}
+/** Builds the same bounded, untrusted reference context for every CLI surface. */
+export declare function buildAgentInputContext(prompt: string, workspaceRoot: string, trusted: boolean, options?: {
+    includeContent?: boolean;
+}): Promise<AgentInputContext>;

package/dist/application/agent/agent-input-context.js

@@ -0,0 +1,12 @@
+import { WorkspaceFileReferenceResolver } from '../workspace/workspace-file-reference-resolver.js';
+/** Builds the same bounded, untrusted reference context for every CLI surface. */
+export async function buildAgentInputContext(prompt, workspaceRoot, trusted, options = {}) {
+    const resolver = new WorkspaceFileReferenceResolver(workspaceRoot);
+    const references = trusted ? await resolver.resolve(prompt) : [];
+    const instruction = resolver.instruction(references);
+    const content = trusted && options.includeContent !== false ? await resolver.contentInstruction(references) : undefined;
+    return {
+        input: [prompt, instruction, content].filter((value) => value !== undefined && value.length > 0).join('\n\n'),
+        references,
+    };
+}

package/dist/application/agent/agent-limit.d.ts

@@ -0,0 +1,3 @@
+export type AgentLimitReason = 'iterations' | 'tool_calls';
+export declare function classifyAgentLimit(error: unknown): AgentLimitReason | undefined;
+export declare function agentLimitNotice(reason: AgentLimitReason): string;

package/dist/application/agent/agent-limit.js

@@ -0,0 +1,12 @@
+import { AgentSdkError, AgentSdkErrorCode } from '@lotagate/agent-sdk';
+export function classifyAgentLimit(error) {
+    if (!(error instanceof AgentSdkError) || error.code !== AgentSdkErrorCode.AgentLimitExceeded)
+        return undefined;
+    if (error.details?.['maxToolCallsPerTurn'] !== undefined || /tool calls/iu.test(error.message))
+        return 'tool_calls';
+    return 'iterations';
+}
+export function agentLimitNotice(reason) {
+    const limit = reason === 'tool_calls' ? 'tool-call' : 'iteration';
+    return `The agent stopped after reaching its ${limit} safety limit. The response may be incomplete; send a focused follow-up to continue.`;
+}

package/dist/application/agent/agent-run-tracker.d.ts

@@ -0,0 +1,30 @@
+import type { AgentEvent } from '@lotagate/agent-sdk';
+import type { ModelCallSummary } from '../../ports/model-diagnostics.js';
+export type CliAgentRunState = 'preparing' | 'thinking' | 'executing_tool' | 'waiting_approval' | 'compacting' | 'completed' | 'failed' | 'cancelled' | 'stuck';
+export interface AgentRunSnapshot {
+    readonly state: CliAgentRunState;
+    readonly modelTurns: number;
+    readonly toolCalls: number;
+    readonly toolCompletions: number;
+    readonly toolFailures: number;
+    readonly modelContentLength: number;
+    readonly lastFinishReason?: string | null;
+    readonly toolNames: readonly string[];
+}
+/** Tracks the CLI-visible lifecycle without duplicating the Agent SDK loop. */
+export declare class AgentRunTracker {
+    private state;
+    private modelTurns;
+    private toolCalls;
+    private toolCompletions;
+    private toolFailures;
+    private modelContentLength;
+    private lastFinishReason;
+    private readonly toolNames;
+    observe(event: AgentEvent): void;
+    observeModel(summary: ModelCallSummary): void;
+    markCancelled(): void;
+    markFailed(): void;
+    markStuck(): void;
+    snapshot(): AgentRunSnapshot;
+}

package/dist/application/agent/agent-run-tracker.js

@@ -0,0 +1,68 @@
+/** Tracks the CLI-visible lifecycle without duplicating the Agent SDK loop. */
+export class AgentRunTracker {
+    state = 'preparing';
+    modelTurns = 0;
+    toolCalls = 0;
+    toolCompletions = 0;
+    toolFailures = 0;
+    modelContentLength = 0;
+    lastFinishReason;
+    toolNames = new Set();
+    observe(event) {
+        switch (event.type) {
+            case 'model.delta':
+                this.state = 'thinking';
+                this.modelContentLength += event.content.length;
+                break;
+            case 'model.completed':
+                this.state = 'thinking';
+                this.modelTurns += 1;
+                break;
+            case 'tool.approval.requested':
+                this.state = 'waiting_approval';
+                break;
+            case 'tool.called':
+                this.state = 'executing_tool';
+                this.toolCalls += 1;
+                this.toolNames.add(event.toolName);
+                break;
+            case 'tool.completed':
+                this.state = 'thinking';
+                this.toolCompletions += 1;
+                if (event.isError)
+                    this.toolFailures += 1;
+                break;
+            case 'context.compacted':
+                this.state = 'compacting';
+                break;
+            case 'session.completed':
+                this.state = 'completed';
+                this.modelContentLength += event.content.length;
+                break;
+            case 'session.failed':
+                this.state = 'failed';
+                break;
+            default: break;
+        }
+    }
+    observeModel(summary) {
+        this.lastFinishReason = summary.finishReason;
+        for (const name of summary.toolNames)
+            this.toolNames.add(name);
+    }
+    markCancelled() { this.state = 'cancelled'; }
+    markFailed() { this.state = 'failed'; }
+    markStuck() { this.state = 'stuck'; }
+    snapshot() {
+        return {
+            state: this.state,
+            modelTurns: this.modelTurns,
+            toolCalls: this.toolCalls,
+            toolCompletions: this.toolCompletions,
+            toolFailures: this.toolFailures,
+            modelContentLength: this.modelContentLength,
+            ...(this.lastFinishReason === undefined ? {} : { lastFinishReason: this.lastFinishReason }),
+            toolNames: [...this.toolNames].sort(),
+        };
+    }
+}

package/dist/application/agent/agent-session-store.d.ts

@@ -0,0 +1,19 @@
+import type { TextMessage } from '@lotagate/sdk';
+import type { AgentSessionPatch, AgentSessionState, SessionStore as AgentSessionStore } from '@lotagate/agent-sdk';
+import type { SessionEvent, TranscriptEntry } from '../../domain/session/session.js';
+/**
+ * Keeps the Agent SDK conversation alive across TUI turns while leaving the
+ * durable CLI session format owned by the CLI session store.
+ */
+export declare class CliAgentSessionStore implements AgentSessionStore {
+    private readonly sessions;
+    create(state: AgentSessionState): void;
+    get(sessionId: string): AgentSessionState | undefined;
+    update(sessionId: string, patch: AgentSessionPatch): void;
+    delete(sessionId: string): void;
+    /** Seeds a resumed session only when the current process has no SDK state. */
+    hydrate(sessionId: string, systemPrompt: string, transcript: readonly TranscriptEntry[], events: readonly SessionEvent[], currentInput: string): void;
+}
+export declare function toAgentMessage(entry: TranscriptEntry): TextMessage;
+/** Keeps durable history intact while rebuilding only the active post-compaction context. */
+export declare function retainLatestCompaction(transcript: readonly TranscriptEntry[]): TranscriptEntry[];

package/dist/application/agent/agent-session-store.js

@@ -0,0 +1,74 @@
+import { buildAgentHistory } from './agent-history.js';
+/**
+ * Keeps the Agent SDK conversation alive across TUI turns while leaving the
+ * durable CLI session format owned by the CLI session store.
+ */
+export class CliAgentSessionStore {
+    sessions = new Map();
+    create(state) {
+        this.sessions.set(state.sessionId, state);
+    }
+    get(sessionId) {
+        return this.sessions.get(sessionId);
+    }
+    update(sessionId, patch) {
+        const current = this.sessions.get(sessionId);
+        if (current === undefined)
+            throw new Error(`Agent session not found: ${sessionId}`);
+        this.sessions.set(sessionId, {
+            ...current,
+            ...patch,
+            ...(patch.finalContent === undefined ? {} : { finalContent: patch.finalContent }),
+            updatedAt: new Date().toISOString(),
+        });
+    }
+    delete(sessionId) {
+        this.sessions.delete(sessionId);
+    }
+    /** Seeds a resumed session only when the current process has no SDK state. */
+    hydrate(sessionId, systemPrompt, transcript, events, currentInput) {
+        if (this.sessions.has(sessionId))
+            return;
+        const source = [...transcript];
+        const currentIndex = findLastIndex(source, (entry) => entry.type === 'user' && entry.content === currentInput);
+        if (currentIndex >= 0)
+            source.splice(currentIndex, 1);
+        const previous = retainLatestCompaction(buildAgentHistory(source, events));
+        const messages = [
+            { role: 'system', content: systemPrompt },
+            ...previous.map(toAgentMessage),
+        ];
+        if (messages.length <= 1)
+            return;
+        const now = new Date().toISOString();
+        this.create({ sessionId, status: 'completed', messages, iteration: 0, createdAt: now, updatedAt: now });
+    }
+}
+export function toAgentMessage(entry) {
+    if (entry.type === 'system' && entry.content.startsWith('[Compacted context]\n')) {
+        return { role: 'user', content: `[Conversation summary — untrusted conversation context]\n${entry.content.slice('[Compacted context]\n'.length)}` };
+    }
+    if (entry.type === 'system')
+        return { role: 'system', content: entry.content };
+    if (entry.type === 'tool')
+        return { role: 'system', content: `[Tool result]\n${entry.content}` };
+    return { role: entry.type, content: entry.content };
+}
+/** Keeps durable history intact while rebuilding only the active post-compaction context. */
+export function retainLatestCompaction(transcript) {
+    let latest = -1;
+    for (let index = transcript.length - 1; index >= 0; index -= 1) {
+        const entry = transcript[index];
+        if (entry?.type === 'system' && entry.content.startsWith('[Compacted context]\n')) {
+            latest = index;
+            break;
+        }
+    }
+    return latest < 0 ? [...transcript] : transcript.slice(latest);
+}
+function findLastIndex(items, predicate) {
+    for (let index = items.length - 1; index >= 0; index -= 1)
+        if (predicate(items[index]))
+            return index;
+    return -1;
+}

package/dist/application/agent/capability-profile.d.ts

@@ -0,0 +1,37 @@
+export type AgentCapabilityProfile = 'interactive-trusted' | 'interactive-untrusted' | 'headless-safe' | 'protocol-safe' | 'subagent';
+export type AgentSubagentMode = 'research' | 'worker';
+export interface AgentSkillSummary {
+    name: string;
+    description: string;
+}
+export interface AgentInstructionSummary {
+    path: string;
+    content: string;
+}
+export interface AgentGoalSummary {
+    objective: string;
+    status: string;
+    turns: number;
+    evaluatorRuns: number;
+    tokensUsed: number;
+    tokenBudget?: number;
+    maxTurns?: number;
+    maxDurationMs?: number;
+    lastEvaluation?: string;
+    lastError?: string;
+}
+export interface AgentCapabilitySnapshot {
+    profile: AgentCapabilityProfile;
+    model: string;
+    cwd: string;
+    workspaceRoot: string;
+    trusted: boolean;
+    subagentMode?: AgentSubagentMode;
+    subagentModels?: readonly string[];
+    tools: readonly string[];
+    skills: readonly AgentSkillSummary[];
+    plugins: readonly string[];
+    instructions?: readonly AgentInstructionSummary[];
+    goal?: AgentGoalSummary;
+}
+export declare function createCapabilitySnapshot(input: AgentCapabilitySnapshot): AgentCapabilitySnapshot;

package/dist/application/agent/capability-profile.js

@@ -0,0 +1,13 @@
+export function createCapabilitySnapshot(input) {
+    return {
+        ...input,
+        ...(input.subagentModels === undefined ? {} : { subagentModels: [...new Set(input.subagentModels)].sort() }),
+        tools: uniqueSorted(input.tools),
+        skills: [...input.skills].sort((left, right) => left.name.localeCompare(right.name)),
+        plugins: uniqueSorted(input.plugins),
+        ...(input.instructions === undefined ? {} : { instructions: [...input.instructions].sort((left, right) => left.path.localeCompare(right.path)) }),
+    };
+}
+function uniqueSorted(values) {
+    return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}

package/dist/application/agent/cli-agent-execution-service.d.ts

@@ -0,0 +1,81 @@
+import type { LotaGate } from '@lotagate/sdk';
+import type { AgentEvent, AgentRunRequest, LotaGateAgent, ContextManagementOptions, SessionStore as AgentSessionStore, ToolExecutor } from '@lotagate/agent-sdk';
+import type { CliRuntime } from '../../bootstrap/runtime-factory.js';
+import { type CliApprovalMode, type ToolApprovalDecision } from '../security/tool-approval-service.js';
+import { type AgentCapabilityProfile, type AgentGoalSummary } from './capability-profile.js';
+import type { ModelCallSummary } from '../../ports/model-diagnostics.js';
+import { type AgentInputContext } from './agent-input-context.js';
+import type { SkillManifest } from '../../domain/extensions/skill-manifest.js';
+import type { FileChangeDiff } from '../../domain/filesystem/file-change-diff.js';
+import type { ToolApprovalRequest } from '@lotagate/agent-sdk';
+import type { ToolActivityObserver } from '../../ports/tool-activity.js';
+import { type SubagentJobRegistry } from '../orchestration/cli-subagent-service.js';
+import type { SubagentMode } from '../../domain/orchestration/subagent.js';
+import type { SubagentLifecycleObserver } from '../../ports/subagent-lifecycle.js';
+import { type BrowserHostInvoker } from '../protocol/browser-host-tool-executor.js';
+import { type DesktopHostInvoker } from '../protocol/desktop-host-tool-executor.js';
+import type { DesktopBrowserAccess } from '../protocol/desktop-execution-policy.js';
+export interface CliAgentExecutionOptions {
+    runtime: CliRuntime;
+    cwd: string;
+    model: string;
+    client: LotaGate;
+    profile: AgentCapabilityProfile;
+    /** Non-interactive callers cannot answer an approval prompt. */
+    approvalMode?: CliApprovalMode;
+    onModelComplete?: (summary: ModelCallSummary) => void;
+    onSubagentModelComplete?: (summary: ModelCallSummary) => void;
+    initialSkill?: SkillManifest;
+    onWrite?: (change: FileChangeDiff) => void | Promise<void>;
+    prompt?: (request: ToolApprovalRequest) => boolean | Promise<boolean>;
+    rememberApproval?: (request: ToolApprovalRequest) => void | Promise<void>;
+    onApprovalPersistenceFailure?: (request: ToolApprovalRequest, error: unknown) => void | Promise<void>;
+    audit?: (decision: ToolApprovalDecision) => void | Promise<void>;
+    contextManagement?: ContextManagementOptions;
+    agentSessionStore?: AgentSessionStore;
+    toolActivity?: ToolActivityObserver;
+    /** Internal child-agent guard. Child agents never receive agent.spawn. */
+    allowSubagents?: boolean;
+    /** Child capability mode. Research is the least-privileged default. */
+    subagentMode?: SubagentMode;
+    /** Model ids permitted for delegated children. Defaults to the parent model only. */
+    allowedSubagentModels?: readonly string[];
+    /** Workspace-relative paths a worker child may write. */
+    subagentWriteScope?: readonly string[];
+    /** Session-owned registry keeps background subagents available across turns. */
+    subagentJobs?: SubagentJobRegistry;
+    /** CLI presentation can observe delegated-work lifecycle without entering the SDK boundary. */
+    subagentLifecycle?: SubagentLifecycleObserver;
+    goal?: AgentGoalSummary;
+    /** Desktop-only bridge. Standalone CLI callers leave this undefined. */
+    browserHost?: BrowserHostInvoker;
+    /** Optional Desktop automation tool scope. Standalone callers leave this undefined. */
+    allowedTools?: readonly string[];
+    /** Optional Desktop automation skill selection. Standalone callers leave this undefined. */
+    selectedSkills?: readonly string[];
+    /** Optional Desktop browser exposure policy. The host remains authoritative. */
+    browserAccess?: DesktopBrowserAccess;
+    /** Desktop-only host execution bridge. Standalone callers leave this undefined. */
+    desktopHost?: DesktopHostInvoker;
+    /** Selects where Desktop-owned filesystem and shell tools execute. */
+    executionBoundary?: 'sandbox' | 'host';
+    /** Host fallback policy for a Desktop-owned sandbox request. */
+    hostFallback?: 'ask' | 'deny' | 'allow';
+    /** Reuses the Desktop tool approval surface when sandbox fallback needs consent. */
+    onExecutionFallbackApproval?: (request: ToolApprovalRequest, reason: string) => boolean | Promise<boolean>;
+}
+export interface PreparedCliAgent {
+    readonly agent: LotaGateAgent;
+    readonly system: string;
+    readonly trusted: boolean;
+    readonly buildInput: (prompt: string) => Promise<AgentInputContext>;
+    readonly close: () => Promise<void>;
+    readonly run: (request: Pick<AgentRunRequest, 'input' | 'model' | 'signal' | 'sessionId' | 'metadata' | 'limits' | 'stream'>) => AsyncIterable<AgentEvent>;
+}
+/**
+ * Composes the CLI-owned capabilities around the public Agent SDK runtime.
+ * The SDK remains responsible for MCP transport, tool dispatch and the agent
+ * loop; this service only supplies workspace policy and CLI extensions.
+ */
+export declare function prepareCliAgent(options: CliAgentExecutionOptions): Promise<PreparedCliAgent>;
+export declare function composeFullToolExecutors(hostExecution: ToolExecutor | undefined, filesystem: ToolExecutor, shell: ToolExecutor, skill: ToolExecutor, browser?: ToolExecutor): readonly ToolExecutor[];