@lotagate/cli 0.1.21 → 0.1.22

package/dist/application/protocol/desktop-attachment-store.d.ts

@@ -0,0 +1,16 @@
+import type { AttachmentPayload } from '../../domain/session/attachment.js';
+export declare class DesktopAttachmentStore {
+    private readonly pending;
+    private readonly completed;
+    begin(input: {
+        id: string;
+        name: string;
+        mimeType: string;
+        sizeBytes: number;
+    }): void;
+    appendChunk(id: string, index: number, encoded: string): void;
+    complete(id: string): void;
+    take(ids: readonly string[]): AttachmentPayload[];
+    clear(): void;
+    private totalReservedBytes;
+}

package/dist/application/protocol/desktop-attachment-store.js

@@ -0,0 +1,82 @@
+import { CLI_ERROR_CODES } from '../../domain/errors/error-codes.js';
+import { CliError } from '../../domain/errors/cli-error.js';
+import { createImageAttachment, normalizeImage } from '../../infrastructure/clipboard/image-normalizer.js';
+import { RESOURCE_LIMITS } from '../../domain/runtime/resource-limits.js';
+export class DesktopAttachmentStore {
+    pending = new Map();
+    completed = new Map();
+    begin(input) {
+        if (!validId(input.id) || !validName(input.name) || !validMimeType(input.mimeType))
+            throw attachmentError(CLI_ERROR_CODES.ATTACHMENT_INVALID_IMAGE, 'Invalid desktop attachment metadata.', 'The attachment metadata is invalid.');
+        if (!Number.isSafeInteger(input.sizeBytes) || input.sizeBytes <= 0 || input.sizeBytes > RESOURCE_LIMITS.maxAttachmentBytes)
+            throw attachmentError(CLI_ERROR_CODES.ATTACHMENT_TOO_LARGE, 'Desktop attachment size is outside the allowed range.', 'The attachment exceeds the maximum allowed size.', true);
+        if (this.pending.has(input.id) || this.completed.has(input.id))
+            throw attachmentError(CLI_ERROR_CODES.ATTACHMENT_INVALID_IMAGE, 'Desktop attachment id is already in use.', 'This attachment has already been uploaded.');
+        if (this.totalReservedBytes() + input.sizeBytes > RESOURCE_LIMITS.pendingAttachmentTotalBytes || this.pending.size + this.completed.size >= RESOURCE_LIMITS.pendingAttachments)
+            throw attachmentError(CLI_ERROR_CODES.ATTACHMENT_TOO_LARGE, 'Desktop attachment limits exceeded.', 'Too many or too-large attachments are pending.', true);
+        this.pending.set(input.id, { id: input.id, name: input.name, mimeType: input.mimeType, sizeBytes: input.sizeBytes, nextIndex: 0, receivedBytes: 0, chunks: [] });
+    }
+    appendChunk(id, index, encoded) {
+        const attachment = this.pending.get(id);
+        if (attachment === undefined)
+            throw attachmentError(CLI_ERROR_CODES.ATTACHMENT_INVALID_IMAGE, 'Desktop attachment upload was not started.', 'The attachment upload is not active.');
+        if (!Number.isSafeInteger(index) || index !== attachment.nextIndex)
+            throw attachmentError(CLI_ERROR_CODES.ATTACHMENT_INVALID_IMAGE, 'Desktop attachment chunk order is invalid.', 'The attachment upload is out of order.');
+        const bytes = decodeBase64(encoded);
+        if (bytes.byteLength === 0 || bytes.byteLength > RESOURCE_LIMITS.desktopAttachmentChunkBytes || attachment.receivedBytes + bytes.byteLength > attachment.sizeBytes)
+            throw attachmentError(CLI_ERROR_CODES.ATTACHMENT_TOO_LARGE, 'Desktop attachment chunk exceeds its declared size.', 'The attachment upload is invalid or too large.', true);
+        attachment.chunks.push(bytes);
+        attachment.receivedBytes += bytes.byteLength;
+        attachment.nextIndex += 1;
+    }
+    complete(id) {
+        const pending = this.pending.get(id);
+        if (pending === undefined)
+            throw attachmentError(CLI_ERROR_CODES.ATTACHMENT_INVALID_IMAGE, 'Desktop attachment upload was not started.', 'The attachment upload is not active.');
+        if (pending.receivedBytes !== pending.sizeBytes)
+            throw attachmentError(CLI_ERROR_CODES.ATTACHMENT_INVALID_IMAGE, 'Desktop attachment upload is incomplete.', 'The attachment upload did not finish.');
+        const bytes = Buffer.concat(pending.chunks);
+        if (pending.mimeType.startsWith('image/')) {
+            const normalized = normalizeImage(bytes, pending.mimeType);
+            const base = createImageAttachment(normalized, 'file', pending.id);
+            this.completed.set(id, { attachment: { ...base, name: pending.name }, bytes: normalized.bytes });
+        }
+        else {
+            this.completed.set(id, { attachment: { id: pending.id, name: pending.name, mimeType: pending.mimeType, sizeBytes: bytes.byteLength, source: 'file' }, bytes });
+        }
+        this.pending.delete(id);
+    }
+    take(ids) {
+        if (new Set(ids).size !== ids.length)
+            throw attachmentError(CLI_ERROR_CODES.ATTACHMENT_INVALID_IMAGE, 'Desktop attachment ids must be unique.', 'An attachment was referenced more than once.');
+        const attachments = ids.map(id => {
+            const attachment = this.completed.get(id);
+            if (attachment === undefined)
+                throw attachmentError(CLI_ERROR_CODES.ATTACHMENT_INVALID_IMAGE, 'Desktop attachment is not complete.', 'Complete the attachment upload before sending the prompt.');
+            return attachment;
+        });
+        ids.forEach(id => this.completed.delete(id));
+        return attachments;
+    }
+    clear() {
+        this.pending.clear();
+        this.completed.clear();
+    }
+    totalReservedBytes() {
+        let total = 0;
+        for (const attachment of this.pending.values())
+            total += attachment.sizeBytes;
+        for (const attachment of this.completed.values())
+            total += attachment.bytes.byteLength;
+        return total;
+    }
+}
+function decodeBase64(value) {
+    if (!/^[A-Za-z0-9+/]*={0,2}$/u.test(value) || value.length === 0 || value.length % 4 !== 0)
+        throw attachmentError(CLI_ERROR_CODES.ATTACHMENT_INVALID_IMAGE, 'Desktop attachment chunk is not valid Base64.', 'The attachment upload is invalid.');
+    return Buffer.from(value, 'base64');
+}
+function validId(value) { return /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(value); }
+function validName(value) { return value.length > 0 && value.length <= 200 && !value.includes('\0'); }
+function validMimeType(value) { return value.length <= RESOURCE_LIMITS.jsonlIdBytes && /^[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*\/[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*$/u.test(value); }
+function attachmentError(code, message, userMessage, retryable = false) { return new CliError(code, message, { category: 'attachment', userMessage, retryable }); }

package/dist/application/protocol/desktop-command-catalog.d.ts

@@ -0,0 +1,2 @@
+import type { DesktopCommandListResult } from './desktop-command-contract.js';
+export declare function getDesktopCommandCatalog(): DesktopCommandListResult;

package/dist/application/protocol/desktop-command-catalog.js

@@ -0,0 +1,19 @@
+import { COMMAND_REGISTRY } from '../commands/command-runtime.js';
+import { isDesktopCommandExposed } from './desktop-command-contract.js';
+export function getDesktopCommandCatalog() {
+    return {
+        commands: COMMAND_REGISTRY
+            .list('direct')
+            .filter(isDesktopCommandExposed)
+            .map(toDescriptor),
+    };
+}
+function toDescriptor(action) {
+    return {
+        id: action.id,
+        path: action.path,
+        summary: action.summary,
+        ...(action.arguments === undefined ? {} : { arguments: action.arguments }),
+        ...(action.options === undefined ? {} : { options: action.options }),
+    };
+}

package/dist/application/protocol/desktop-command-contract.d.ts

@@ -0,0 +1,22 @@
+import type { CommandActionSpec, CommandArgumentSpec, CommandOptionSpec } from '../commands/command-contract.js';
+export interface DesktopCommandDescriptor {
+    readonly id: string;
+    readonly path: readonly string[];
+    readonly summary: string;
+    readonly arguments?: readonly CommandArgumentSpec[];
+    readonly options?: readonly CommandOptionSpec[];
+}
+export interface DesktopCommandListResult {
+    readonly commands: readonly DesktopCommandDescriptor[];
+}
+export interface DesktopCommandInvocation {
+    readonly actionId: string;
+    readonly positionals: readonly string[];
+    readonly options: Readonly<Record<string, string | boolean>>;
+}
+export interface DesktopCommandExecutionResult {
+    readonly accepted: true;
+    readonly commandId: string;
+    readonly actionId: string;
+}
+export declare function isDesktopCommandExposed(action: CommandActionSpec): boolean;

package/dist/application/protocol/desktop-command-contract.js

@@ -0,0 +1,3 @@
+export function isDesktopCommandExposed(action) {
+    return action.surfaces.includes('direct') && action.desktop?.exposed !== false;
+}

package/dist/application/protocol/desktop-command-executor.d.ts

@@ -0,0 +1,16 @@
+import type { CliRuntime } from '../../bootstrap/runtime-factory.js';
+import type { DesktopCommandInvocation } from './desktop-command-contract.js';
+import { type DesktopCommandOutputSink } from './desktop-command-output.js';
+export interface DesktopCommandExecutorOptions {
+    readonly runtime: CliRuntime;
+    readonly cwd: string;
+    readonly invocation: DesktopCommandInvocation;
+    readonly signal: AbortSignal;
+    readonly output: DesktopCommandOutputSink;
+    readonly activity?: DesktopCommandActivitySink;
+}
+export interface DesktopCommandActivitySink {
+    started(key: string, label: string): Promise<void>;
+    completed(key: string, isError: boolean): Promise<void>;
+}
+export declare function executeDesktopCommand(options: DesktopCommandExecutorOptions): Promise<number>;

package/dist/application/protocol/desktop-command-executor.js

@@ -0,0 +1,47 @@
+import { executeApplicationCommand } from '../commands/application-command-executor.js';
+import { COMMAND_REGISTRY } from '../commands/command-runtime.js';
+import { parseCommandInvocationForAction } from '../commands/command-parser.js';
+import { CliError } from '../../domain/errors/cli-error.js';
+import { CLI_ERROR_CODES } from '../../domain/errors/error-codes.js';
+import { isDesktopCommandExposed } from './desktop-command-contract.js';
+import { DesktopCommandOutput } from './desktop-command-output.js';
+export async function executeDesktopCommand(options) {
+    const invocation = parseDesktopInvocation(options.invocation);
+    const commandOutput = new DesktopCommandOutput(options.output);
+    const host = {
+        runtime: options.runtime,
+        cwd: options.cwd,
+        output: commandOutput,
+        writableOutput: commandOutput.writable,
+        signal: options.signal,
+        ...(options.activity === undefined ? {} : { activity: createActivityObserver(options.activity) }),
+    };
+    try {
+        const exitCode = await executeApplicationCommand(invocation, host);
+        await commandOutput.flush();
+        return exitCode;
+    }
+    finally {
+        await commandOutput.flush();
+        commandOutput.writable.destroy();
+    }
+}
+function parseDesktopInvocation(request) {
+    const action = COMMAND_REGISTRY.get(request.actionId);
+    if (action === undefined || !isDesktopCommandExposed(action)) {
+        throw new CliError(CLI_ERROR_CODES.INVALID_ARGUMENT, `Command action '${request.actionId}' is not available through the Desktop protocol.`, {
+            category: 'command',
+            userMessage: `The command '${request.actionId}' is not available in the Desktop application.`,
+        });
+    }
+    const options = new Map(Object.entries(request.options));
+    return parseCommandInvocationForAction(request.actionId, request.positionals, options, 'direct', COMMAND_REGISTRY);
+}
+function createActivityObserver(sink) {
+    return {
+        start(key, label) {
+            void sink.started(key, label);
+            return { complete: (isError) => void sink.completed(key, isError) };
+        },
+    };
+}

package/dist/application/protocol/desktop-command-output.d.ts

@@ -0,0 +1,15 @@
+import { Writable } from 'node:stream';
+import type { CommandOutput } from '../commands/command-output.js';
+export interface DesktopCommandOutputSink {
+    write(content: string, structured?: object): Promise<void>;
+}
+/** Adapts existing command output to ordered JSONL command.output events. */
+export declare class DesktopCommandOutput implements CommandOutput {
+    private readonly _sink;
+    private _pending;
+    readonly writable: Writable;
+    constructor(_sink: DesktopCommandOutputSink);
+    write(value: string): void;
+    writeStructured<T extends object>(value: T, fallbackText?: string): void;
+    flush(): Promise<void>;
+}

package/dist/application/protocol/desktop-command-output.js

@@ -0,0 +1,24 @@
+import { Writable } from 'node:stream';
+/** Adapts existing command output to ordered JSONL command.output events. */
+export class DesktopCommandOutput {
+    _sink;
+    _pending = Promise.resolve();
+    writable = new Writable({
+        write: (chunk, _encoding, callback) => {
+            this.write(String(chunk));
+            callback();
+        },
+    });
+    constructor(_sink) {
+        this._sink = _sink;
+    }
+    write(value) {
+        this._pending = this._pending.then(() => this._sink.write(value));
+    }
+    writeStructured(value, fallbackText) {
+        this._pending = this._pending.then(() => this._sink.write(fallbackText ?? '', value));
+    }
+    async flush() {
+        await this._pending;
+    }
+}

package/dist/application/protocol/desktop-execution-policy.d.ts

@@ -0,0 +1,17 @@
+export type DesktopPermissionPolicy = 'ask' | 'allowlist' | 'review' | 'autonomous';
+export type DesktopBrowserAccess = 'disabled' | 'read-only' | 'interactive' | 'autonomous';
+export interface DesktopExecutionPolicy {
+    readonly permissionPolicy: DesktopPermissionPolicy;
+    readonly allowedTools?: readonly string[];
+    readonly browserAccess: DesktopBrowserAccess;
+    readonly isolation: 'sandbox' | 'host';
+    readonly hostFallback: 'ask' | 'deny' | 'allow';
+    readonly timeoutMs: number;
+    readonly retryAttempt?: number;
+}
+/**
+ * Parses the required Desktop-only execution context at the CLI boundary.
+ * Standalone CLI commands use a separate protocol and never provide this
+ * object. Unknown fields are ignored so the new contract can grow additively.
+ */
+export declare function parseDesktopExecutionPolicy(value: unknown): DesktopExecutionPolicy;

package/dist/application/protocol/desktop-execution-policy.js

@@ -0,0 +1,49 @@
+import { RESOURCE_LIMITS } from '../../domain/runtime/resource-limits.js';
+/**
+ * Parses the required Desktop-only execution context at the CLI boundary.
+ * Standalone CLI commands use a separate protocol and never provide this
+ * object. Unknown fields are ignored so the new contract can grow additively.
+ */
+export function parseDesktopExecutionPolicy(value) {
+    if (!isRecord(value))
+        throw new Error('Invalid Desktop execution policy.');
+    const permissionPolicy = requiredEnum(value['permissionPolicy'], ['ask', 'allowlist', 'review', 'autonomous'], 'permissionPolicy');
+    const browserAccess = requiredEnum(value['browserAccess'], ['disabled', 'read-only', 'interactive', 'autonomous'], 'browserAccess');
+    const isolation = requiredEnum(value['isolation'], ['sandbox', 'host'], 'isolation');
+    const hostFallback = requiredEnum(value['hostFallback'], ['ask', 'deny', 'allow'], 'hostFallback');
+    const allowedTools = value['allowedTools'] === undefined ? undefined : parseAllowedTools(value['allowedTools']);
+    const timeoutMs = parseInteger(value['timeoutMs'], 10_000, 2 * 60 * 60 * 1_000, 'timeoutMs');
+    const retryAttempt = value['retryAttempt'] === undefined ? undefined : parseInteger(value['retryAttempt'], 0, 3, 'retryAttempt');
+    return {
+        permissionPolicy,
+        ...(allowedTools === undefined ? {} : { allowedTools }),
+        browserAccess,
+        isolation,
+        hostFallback,
+        timeoutMs,
+        ...(retryAttempt === undefined ? {} : { retryAttempt }),
+    };
+}
+function parseAllowedTools(value) {
+    if (!Array.isArray(value) || value.length > 128)
+        throw new Error('Invalid Desktop allowedTools.');
+    const tools = value.map((tool) => {
+        if (typeof tool !== 'string' || tool.trim().length === 0 || Buffer.byteLength(tool, 'utf8') > RESOURCE_LIMITS.jsonlIdBytes)
+            throw new Error('Invalid Desktop allowedTools entry.');
+        return tool.trim();
+    });
+    if (new Set(tools).size !== tools.length)
+        throw new Error('Desktop allowedTools must not contain duplicates.');
+    return tools;
+}
+function requiredEnum(value, values, key) {
+    if (typeof value !== 'string' || !values.includes(value))
+        throw new Error(`Invalid Desktop ${key}.`);
+    return value;
+}
+function parseInteger(value, minimum, maximum, key) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < minimum || value > maximum)
+        throw new Error(`Invalid Desktop ${key}.`);
+    return value;
+}
+function isRecord(value) { return typeof value === 'object' && value !== null && !Array.isArray(value); }

package/dist/application/protocol/desktop-host-tool-executor.d.ts

@@ -0,0 +1,57 @@
+import type { ToolDefinition } from '@lotagate/sdk';
+import type { ToolExecutionContext, ToolExecutor, ToolInfo, ToolResult } from '@lotagate/agent-sdk';
+import type { ToolActivityObserver } from '../../ports/tool-activity.js';
+import type { ToolApprovalRequest } from '@lotagate/agent-sdk';
+import type { FileChangeDiff } from '../../domain/filesystem/file-change-diff.js';
+export type DesktopHostExecutionTool = 'filesystem' | 'shell' | 'git' | 'artifact';
+export interface DesktopHostExecutionRequest {
+    version: 2;
+    type: 'host.request';
+    requestId: string;
+    tool: DesktopHostExecutionTool;
+    sessionId: string;
+    runId: string;
+    action: string;
+    params: Record<string, unknown>;
+    executionBoundary: 'sandbox' | 'host';
+    hostFallback: 'ask' | 'deny' | 'allow';
+}
+export interface DesktopHostExecutionResponse {
+    version: 2;
+    type: 'host.response';
+    requestId: string;
+    tool: DesktopHostExecutionTool;
+    ok: boolean;
+    result?: unknown;
+    error?: {
+        code: string;
+        category: string;
+        message: string;
+        retryable: boolean;
+    };
+    executionBoundary?: 'sandbox' | 'host';
+    fallbackReason?: string;
+    fileChange?: FileChangeDiff;
+}
+export type DesktopHostInvoker = (request: DesktopHostExecutionRequest, signal?: AbortSignal) => Promise<DesktopHostExecutionResponse>;
+/**
+ * Routes Desktop-only host operations through the versioned host protocol.
+ * Standalone CLI callers never provide this executor and continue to use the
+ * local filesystem and shell executors.
+ */
+export declare class DesktopHostToolExecutor implements ToolExecutor {
+    private readonly options;
+    private readonly definitions;
+    constructor(options: {
+        request: DesktopHostInvoker;
+        executionBoundary: 'sandbox' | 'host';
+        hostFallback: 'ask' | 'deny' | 'allow';
+        onWrite?: (change: FileChangeDiff) => void | Promise<void>;
+        onFallbackApproval?: (request: ToolApprovalRequest, reason: string) => boolean | Promise<boolean>;
+        onActivity?: ToolActivityObserver;
+    });
+    listTools(): readonly ToolDefinition[];
+    getToolInfo(toolName: string): ToolInfo | undefined;
+    execute(toolName: string, input: Record<string, unknown>, context: ToolExecutionContext): Promise<ToolResult>;
+    private request;
+}

package/dist/application/protocol/desktop-host-tool-executor.js

@@ -0,0 +1,53 @@
+import { randomUUID } from 'node:crypto';
+import { filesystemToolDefinitions } from '../../infrastructure/filesystem/local-filesystem-tool-executor.js';
+import { shellToolDefinitions } from '../../infrastructure/shell/shell-tool-executor.js';
+/**
+ * Routes Desktop-only host operations through the versioned host protocol.
+ * Standalone CLI callers never provide this executor and continue to use the
+ * local filesystem and shell executors.
+ */
+export class DesktopHostToolExecutor {
+    options;
+    definitions = [...filesystemToolDefinitions(), ...shellToolDefinitions()];
+    constructor(options) {
+        this.options = options;
+    }
+    listTools() { return this.definitions; }
+    getToolInfo(toolName) {
+        if (!this.definitions.some(definition => toolNameOf(definition) === toolName))
+            return undefined;
+        return { toolName, source: toolName === 'shell.exec' ? 'shell' : 'filesystem', executorId: 'desktop-host-execution', metadata: { boundary: this.options.executionBoundary } };
+    }
+    async execute(toolName, input, context) {
+        if (!this.definitions.some(definition => toolNameOf(definition) === toolName))
+            return { content: `Unknown Desktop host tool: ${toolName}`, isError: true };
+        const tool = toolName === 'shell.exec' ? 'shell' : 'filesystem';
+        const activity = this.options.onActivity?.start({ key: `${context.runId}:${toolName}`, toolName, source: tool, label: `${this.options.executionBoundary === 'sandbox' ? 'Sandbox' : 'Host'} ${toolName}` });
+        try {
+            let response = await this.options.request(this.request(tool, toolName, input, context), context.signal);
+            if (!response.ok && response.error?.code === 'SANDBOX_FALLBACK_REQUIRED' && this.options.hostFallback === 'ask') {
+                const toolInfo = this.getToolInfo(toolName);
+                const approved = await this.options.onFallbackApproval?.({ toolName, input, context, ...(toolInfo === undefined ? {} : { toolInfo }) }, response.error.message) ?? false;
+                if (approved)
+                    response = await this.options.request({ ...this.request(tool, toolName, input, context), executionBoundary: 'host', hostFallback: 'deny' }, context.signal);
+            }
+            if (!response.ok) {
+                activity?.complete(true);
+                return { content: response.error?.message ?? 'Desktop rejected the execution request.', isError: true, metadata: { code: response.error?.code ?? 'HOST_EXECUTION_ERROR', boundary: response.executionBoundary ?? this.options.executionBoundary, retryable: response.error?.retryable ?? false } };
+            }
+            activity?.complete(false);
+            if (response.fileChange !== undefined)
+                await this.options.onWrite?.(response.fileChange);
+            return { content: boundJson(response.result, context.maxResultBytes), isError: false, metadata: { boundary: response.executionBoundary ?? this.options.executionBoundary, ...(response.fallbackReason === undefined ? {} : { fallbackReason: response.fallbackReason }) } };
+        }
+        catch (error) {
+            activity?.complete(true);
+            return { content: error instanceof Error ? error.message : 'Desktop execution failed.', isError: true, metadata: { boundary: this.options.executionBoundary } };
+        }
+    }
+    request(tool, action, input, context) {
+        return { version: 2, type: 'host.request', requestId: randomUUID(), tool, sessionId: context.sessionId, runId: context.runId, action, params: input, executionBoundary: this.options.executionBoundary, hostFallback: this.options.hostFallback };
+    }
+}
+function toolNameOf(definition) { return 'function' in definition ? definition.function.name : undefined; }
+function boundJson(value, maxBytes) { const content = typeof value === 'string' ? value : JSON.stringify(value ?? null); return Buffer.byteLength(content, 'utf8') <= maxBytes ? content : `${content.slice(0, Math.max(0, maxBytes - 12))}\n[truncated]`; }

package/dist/application/protocol/desktop-orchestration-events.d.ts

@@ -0,0 +1,5 @@
+import type { ExecutionPlan } from '../../domain/orchestration/task.js';
+import type { SubagentLifecycleEvent } from '../../ports/subagent-lifecycle.js';
+export declare function subagentDesktopPayload(event: SubagentLifecycleEvent, turnId: string): Record<string, unknown>;
+export declare function planDesktopPayload(plan: ExecutionPlan, turnId: string): Record<string, unknown>;
+export declare function planStepPayload(plan: ExecutionPlan, turnId: string, index: number, status: 'started' | 'completed'): Record<string, unknown>;

package/dist/application/protocol/desktop-orchestration-events.js

@@ -0,0 +1,37 @@
+export function subagentDesktopPayload(event, turnId) {
+    return {
+        turnId,
+        sessionId: event.sessionId,
+        id: event.id,
+        displayName: event.displayName,
+        task: boundText(event.task, 16_384),
+        mode: event.mode,
+        model: event.model,
+        status: event.status,
+        background: event.background,
+        timestamp: event.timestamp,
+        ...(event.durationMs === undefined ? {} : { durationMs: event.durationMs }),
+        ...(event.summary === undefined ? {} : { summary: boundText(event.summary, 24_576) }),
+        ...(event.lastAction === undefined ? {} : { lastAction: event.lastAction }),
+        ...(event.handoff === undefined ? {} : { handoff: event.handoff }),
+    };
+}
+export function planDesktopPayload(plan, turnId) {
+    return {
+        turnId,
+        planId: plan.id,
+        goal: boundText(plan.goal, 16_384),
+        totalSteps: plan.tasks.length,
+        steps: plan.tasks.map((step, index) => ({ index, id: step.id, title: boundText(step.title, 512), description: boundText(step.description, 8_192), status: step.status })),
+    };
+}
+export function planStepPayload(plan, turnId, index, status) {
+    const step = plan.tasks[index];
+    if (step === undefined)
+        return { turnId, planId: plan.id, index, status };
+    return { turnId, planId: plan.id, index, stepId: step.id, status };
+}
+function boundText(value, maxBytes) {
+    const bytes = Buffer.from(value, 'utf8');
+    return bytes.byteLength <= maxBytes ? value : `${bytes.subarray(0, maxBytes).toString('utf8')}\n[truncated]`;
+}

package/dist/application/protocol/json-line-writer.d.ts

@@ -0,0 +1,9 @@
+import type { Writable } from 'node:stream';
+/** Serializes protocol messages in order and applies Writable backpressure. */
+export declare class JsonLineWriter<T> {
+    private readonly output;
+    private tail;
+    constructor(output: Writable);
+    write(value: T): Promise<void>;
+    flush(): Promise<void>;
+}

package/dist/application/protocol/json-line-writer.js

@@ -0,0 +1,19 @@
+import { once } from 'node:events';
+/** Serializes protocol messages in order and applies Writable backpressure. */
+export class JsonLineWriter {
+    output;
+    tail = Promise.resolve();
+    constructor(output) {
+        this.output = output;
+    }
+    write(value) {
+        const operation = this.tail.then(async () => {
+            if (this.output.write(`${JSON.stringify(value)}\n`))
+                return;
+            await once(this.output, 'drain');
+        });
+        this.tail = operation.catch(() => undefined);
+        return operation;
+    }
+    async flush() { await this.tail; }
+}

package/dist/application/protocol/jsonl-agent-command.d.ts

@@ -0,0 +1,3 @@
+import type { Readable, Writable } from 'node:stream';
+import type { createCompositionRoot } from '../../bootstrap/composition-root.js';
+export declare function runAgentCommand(positionals: readonly string[], runtime: ReturnType<typeof createCompositionRoot>, cwd: string, stdin: Readable, stdout: Writable): Promise<number>;

package/dist/application/protocol/jsonl-agent-command.js

@@ -0,0 +1,97 @@
+import { AuthenticationService } from '../auth/authentication-service.js';
+import { JsonlProtocolRunner } from './jsonl-protocol.js';
+import { createLotaGateClient } from '../../infrastructure/sdk/lotagate-client-factory.js';
+import { CliError } from '../../domain/errors/cli-error.js';
+import { CLI_ERROR_CODES } from '../../domain/errors/error-codes.js';
+import { prepareCliAgent } from '../agent/cli-agent-execution-service.js';
+import { AgentRunTracker } from '../agent/agent-run-tracker.js';
+import { loadExecutionConfig } from '../config/execution-config.js';
+import { agentLimitNotice, classifyAgentLimit } from '../agent/agent-limit.js';
+import { runDesktopAgentCommand } from './desktop-agent-command.js';
+export async function runAgentCommand(positionals, runtime, cwd, stdin, stdout) {
+    const action = positionals[0] ?? 'stdio';
+    if (action === 'desktop')
+        return runDesktopAgentCommand(runtime, cwd, stdin, stdout);
+    if (action !== 'stdio')
+        throw new CliError(CLI_ERROR_CODES.INVALID_ARGUMENT, 'Unsupported agent action.', { category: 'arguments', userMessage: 'Use `lotagate agent stdio` or `lotagate agent desktop`.' });
+    const loaded = await loadExecutionConfig(runtime, cwd);
+    if (loaded.config.model === null)
+        throw new CliError(CLI_ERROR_CODES.MODEL_NOT_FOUND, 'No model is selected.', { category: 'model', userMessage: 'Select a model before running the stdio agent.' });
+    const profileName = loaded.config.profile ?? AuthenticationService.defaultProfileName();
+    const credential = await runtime.auth.requireCredential(profileName);
+    const runner = new JsonlProtocolRunner(async function* (request, signal) {
+        const model = request.params.model ?? loaded.config.model;
+        runtime.logger.info('Protocol agent request started.', { model, promptLength: request.params.prompt.length });
+        const tracker = new AgentRunTracker();
+        const onModelComplete = (summary) => {
+            tracker.observeModel(summary);
+            runtime.logger.debug('Model turn completed.', {
+                model: summary.model,
+                stream: summary.stream,
+                contentLength: summary.contentLength,
+                toolCallCount: summary.toolCallCount,
+                toolNames: summary.toolNames,
+                finishReason: summary.finishReason,
+            });
+        };
+        const prepared = await prepareCliAgent({
+            runtime,
+            cwd,
+            model,
+            client: createLotaGateClient(credential.profile, credential.apiKey),
+            profile: 'protocol-safe',
+            approvalMode: loaded.config.approvalMode,
+            onModelComplete,
+        });
+        let streamedText = false;
+        let limitNotice;
+        try {
+            const input = await prepared.buildInput(request.params.prompt);
+            for await (const event of prepared.run({ input: input.input, model, signal })) {
+                tracker.observe(event);
+                if (event.type === 'tool.called')
+                    runtime.logger.info('Agent tool called.', { toolName: event.toolName });
+                if (event.type === 'tool.completed')
+                    runtime.logger.info('Agent tool completed.', { toolName: event.toolName, isError: event.isError });
+                if (event.type === 'model.delta' && event.content.length > 0) {
+                    streamedText = true;
+                    yield { type: 'delta', content: event.content };
+                }
+                else if (event.type === 'session.completed' && !streamedText && event.content.length > 0) {
+                    streamedText = true;
+                    yield { type: 'delta', content: event.content };
+                }
+                if (event.type === 'session.failed') {
+                    const limitReason = classifyAgentLimit(event.error);
+                    if (limitReason === undefined)
+                        throw event.error;
+                    limitNotice = agentLimitNotice(limitReason);
+                    break;
+                }
+            }
+            if (limitNotice !== undefined) {
+                streamedText = true;
+                yield { type: 'delta', content: limitNotice };
+            }
+            if (!streamedText) {
+                const snapshot = tracker.snapshot();
+                if (snapshot.toolCalls > 0)
+                    tracker.markStuck();
+                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,
+                    details: { toolCalls: snapshot.toolCalls, toolCompletions: snapshot.toolCompletions, toolNames: snapshot.toolNames, finishReason: snapshot.lastFinishReason },
+                });
+            }
+            yield { type: 'completed' };
+            runtime.logger.info('Protocol agent request completed.', { model });
+        }
+        finally {
+            await prepared.close();
+        }
+    });
+    const result = await runner.run(stdin, stdout);
+    return result.errorCount === 0 ? 0 : 1;
+}