@lotagate/cli 0.1.21 → 0.1.22

package/dist/domain/extensions/plugin-manifest.js

@@ -0,0 +1,43 @@
+import { CliError } from '../errors/cli-error.js';
+import { CLI_ERROR_CODES } from '../errors/error-codes.js';
+import { findUnexpectedRecordKey, isRecord } from '../validation/record-schema.js';
+export function parsePluginManifest(value, directory) {
+    if (!isRecord(value))
+        throw invalidPlugin('Manifest must be a JSON object.');
+    const record = value;
+    const unexpectedKey = findUnexpectedRecordKey(record, ['name', 'version', 'description', 'skills', 'agents', 'hooks', 'mcp']);
+    if (unexpectedKey !== undefined)
+        throw invalidPlugin(`Unsupported manifest field: \`${unexpectedKey}\`.`);
+    const name = record['name'];
+    const version = record['version'];
+    const description = optionalString(record, 'description');
+    const skillsDirectory = optionalString(record, 'skills');
+    const agentsDirectory = optionalString(record, 'agents');
+    const hooksDirectory = optionalString(record, 'hooks');
+    const mcpConfig = optionalString(record, 'mcp');
+    if (typeof name !== 'string' || !/^@[a-z0-9][a-z0-9-]{0,31}\/[a-z0-9][a-z0-9-]{0,63}$/.test(name))
+        throw invalidPlugin('Plugin name must use a lowercase namespace/name.');
+    if (typeof version !== 'string' || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version))
+        throw invalidPlugin('Plugin version must be semver-like.');
+    return {
+        name,
+        version,
+        ...(description === undefined ? {} : { description }),
+        directory,
+        ...(skillsDirectory === undefined ? {} : { skillsDirectory }),
+        ...(agentsDirectory === undefined ? {} : { agentsDirectory }),
+        ...(hooksDirectory === undefined ? {} : { hooksDirectory }),
+        ...(mcpConfig === undefined ? {} : { mcpConfig }),
+    };
+}
+function optionalString(record, field) {
+    const value = record[field];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string')
+        throw invalidPlugin(`Manifest field \`${field}\` must be a string.`);
+    return value;
+}
+function invalidPlugin(message) {
+    return new CliError(CLI_ERROR_CODES.PLUGIN_MANIFEST_INVALID, message, { category: 'extension', userMessage: `Invalid plugin: ${message}` });
+}

package/dist/domain/extensions/skill-manifest.d.ts

@@ -0,0 +1,10 @@
+export interface SkillManifest {
+    name: string;
+    description: string;
+    userInvocable: boolean;
+    modelInvocable: boolean;
+    allowedTools: readonly string[];
+    directory: string;
+    body: string;
+}
+export declare function parseSkillDocument(raw: string, directory: string): SkillManifest;

package/dist/domain/extensions/skill-manifest.js

@@ -0,0 +1,51 @@
+import { CliError } from '../errors/cli-error.js';
+import { CLI_ERROR_CODES } from '../errors/error-codes.js';
+export function parseSkillDocument(raw, directory) {
+    const normalized = raw.replace(/^\uFEFF/, '');
+    if (!normalized.startsWith('---\n') && !normalized.startsWith('---\r\n'))
+        throw invalidSkill('Skill must start with YAML frontmatter.');
+    const match = normalized.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
+    if (match === null)
+        throw invalidSkill('Skill frontmatter is not closed.');
+    const frontmatter = match[1];
+    const body = match[2];
+    if (frontmatter === undefined || body === undefined)
+        throw invalidSkill('Skill document is incomplete.');
+    const fields = parseSimpleFrontmatter(frontmatter);
+    const name = fields['name'];
+    const description = fields['description'];
+    if (name === undefined || description === undefined)
+        throw invalidSkill('Skill requires name and description.');
+    if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(name))
+        throw invalidSkill('Skill name must be lowercase kebab-case.');
+    return {
+        name,
+        description,
+        userInvocable: fields['user-invocable'] !== 'false',
+        modelInvocable: fields['model-invocable'] !== 'false',
+        allowedTools: parseList(fields['allowed-tools']),
+        directory,
+        body: body.trim(),
+    };
+}
+function parseSimpleFrontmatter(raw) {
+    const result = {};
+    for (const line of raw.split(/\r?\n/)) {
+        const separator = line.indexOf(':');
+        if (separator <= 0)
+            continue;
+        const key = line.slice(0, separator).trim().toLowerCase();
+        const value = line.slice(separator + 1).trim().replace(/^['"]|['"]$/g, '');
+        result[key] = value;
+    }
+    return result;
+}
+function parseList(value) {
+    if (value === undefined || value.trim().length === 0)
+        return [];
+    const normalized = value.trim().replace(/^\[|\]$/g, '');
+    return normalized.split(',').map((item) => item.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean);
+}
+function invalidSkill(message) {
+    return new CliError(CLI_ERROR_CODES.SKILL_FRONTMATTER_INVALID, message, { category: 'extension', userMessage: `Invalid skill: ${message}` });
+}

package/dist/domain/filesystem/file-change-diff.d.ts

@@ -0,0 +1,21 @@
+export type FileDiffLineKind = 'context' | 'addition' | 'deletion';
+export interface FileDiffLine {
+    readonly kind: FileDiffLineKind;
+    readonly text: string;
+    readonly oldLine?: number;
+    readonly newLine?: number;
+}
+export interface FileChangeDiff {
+    readonly path: string;
+    readonly lines: readonly FileDiffLine[];
+    readonly additions: number;
+    readonly deletions: number;
+    readonly truncated: boolean;
+}
+export interface FileDiffOptions {
+    maxLines?: number;
+    maxInputLines?: number;
+    truncated?: boolean;
+}
+/** Creates a bounded, deterministic line diff suitable for terminal rendering. */
+export declare function createFileChangeDiff(path: string, before: string, after: string, options?: FileDiffOptions): FileChangeDiff;

package/dist/domain/filesystem/file-change-diff.js

@@ -0,0 +1,60 @@
+/** Creates a bounded, deterministic line diff suitable for terminal rendering. */
+export function createFileChangeDiff(path, before, after, options = {}) {
+    const maxInputLines = options.maxInputLines ?? 400;
+    const maxLines = options.maxLines ?? 240;
+    const oldLines = splitLines(before);
+    const newLines = splitLines(after);
+    const inputTruncated = oldLines.length > maxInputLines || newLines.length > maxInputLines;
+    const boundedOld = oldLines.slice(0, maxInputLines);
+    const boundedNew = newLines.slice(0, maxInputLines);
+    const matrix = buildLcsMatrix(boundedOld, boundedNew);
+    const lines = [];
+    let oldLine = 1;
+    let newLine = 1;
+    let oldIndex = 0;
+    let newIndex = 0;
+    while (oldIndex < boundedOld.length || newIndex < boundedNew.length) {
+        if (oldIndex < boundedOld.length && newIndex < boundedNew.length && boundedOld[oldIndex] === boundedNew[newIndex]) {
+            lines.push({ kind: 'context', text: boundedOld[oldIndex] ?? '', oldLine, newLine });
+            oldIndex += 1;
+            newIndex += 1;
+            oldLine += 1;
+            newLine += 1;
+        }
+        else if (newIndex < boundedNew.length && (oldIndex === boundedOld.length || (matrix[oldIndex + 1]?.[newIndex] ?? 0) < (matrix[oldIndex]?.[newIndex + 1] ?? 0))) {
+            lines.push({ kind: 'addition', text: boundedNew[newIndex] ?? '', newLine });
+            newIndex += 1;
+            newLine += 1;
+        }
+        else {
+            lines.push({ kind: 'deletion', text: boundedOld[oldIndex] ?? '', oldLine });
+            oldIndex += 1;
+            oldLine += 1;
+        }
+    }
+    const truncated = options.truncated === true || inputTruncated || lines.length > maxLines;
+    const visibleLines = lines.slice(0, maxLines);
+    return {
+        path,
+        lines: visibleLines,
+        additions: visibleLines.filter((line) => line.kind === 'addition').length,
+        deletions: visibleLines.filter((line) => line.kind === 'deletion').length,
+        truncated,
+    };
+}
+function splitLines(value) {
+    if (value.length === 0)
+        return [];
+    return value.replace(/\r\n/gu, '\n').split('\n');
+}
+function buildLcsMatrix(oldLines, newLines) {
+    const matrix = Array.from({ length: oldLines.length + 1 }, () => Array(newLines.length + 1).fill(0));
+    for (let oldIndex = oldLines.length - 1; oldIndex >= 0; oldIndex -= 1) {
+        for (let newIndex = newLines.length - 1; newIndex >= 0; newIndex -= 1) {
+            matrix[oldIndex][newIndex] = oldLines[oldIndex] === newLines[newIndex]
+                ? (matrix[oldIndex + 1]?.[newIndex + 1] ?? 0) + 1
+                : Math.max(matrix[oldIndex + 1]?.[newIndex] ?? 0, matrix[oldIndex]?.[newIndex + 1] ?? 0);
+        }
+    }
+    return matrix;
+}

package/dist/domain/media/gateway-media-contract.d.ts

@@ -0,0 +1,23 @@
+/** Mirrors the gateway's public media validation contract. The gateway remains authoritative. */
+export declare const GATEWAY_MEDIA_LIMITS: {
+    readonly imagePromptCharacters: 32000;
+    readonly imageCount: 16;
+    readonly imageEditFileBytes: number;
+    readonly imageEditMaskBytes: number;
+    readonly imageEditTotalBytes: number;
+    readonly audioUploadBytes: number;
+    readonly speechInputCharacters: 4096;
+    readonly speechInstructionsCharacters: 4096;
+    readonly speechVoiceCharacters: 64;
+    readonly audioPromptCharacters: 4096;
+    readonly transcriptionLanguageCharacters: 10;
+};
+/** The installed SDK buffers binary media responses to this exact upper bound. */
+export declare const SDK_BINARY_MEDIA_RESPONSE_BYTES: number;
+type Flags = ReadonlyMap<string, string | boolean>;
+export declare function validateMediaCommandOptions(action: string, positionals: readonly string[], flags: Flags): void;
+export declare function validateImageEditInputCount(paths: readonly string[]): void;
+export declare function validateUploadSize(bytes: number, maximum: number, label: string): void;
+export declare function validateImageEditTotalSize(bytes: number): void;
+export declare function formatByteLimit(bytes: number): string;
+export {};

package/dist/domain/media/gateway-media-contract.js

@@ -0,0 +1,163 @@
+import { CliError } from '../errors/cli-error.js';
+import { CLI_ERROR_CODES } from '../errors/error-codes.js';
+const KILOBYTE = 1_000;
+const MEGABYTE = 1_000_000;
+/** Mirrors the gateway's public media validation contract. The gateway remains authoritative. */
+export const GATEWAY_MEDIA_LIMITS = {
+    imagePromptCharacters: 32_000,
+    imageCount: 16,
+    imageEditFileBytes: 47 * MEGABYTE,
+    imageEditMaskBytes: 4 * MEGABYTE,
+    imageEditTotalBytes: 128 * MEGABYTE,
+    audioUploadBytes: 50 * MEGABYTE,
+    speechInputCharacters: 4_096,
+    speechInstructionsCharacters: 4_096,
+    speechVoiceCharacters: 64,
+    audioPromptCharacters: 4_096,
+    transcriptionLanguageCharacters: 10,
+};
+/** The installed SDK buffers binary media responses to this exact upper bound. */
+export const SDK_BINARY_MEDIA_RESPONSE_BYTES = 50 * 1024 * 1024;
+export function validateMediaCommandOptions(action, positionals, flags) {
+    validateOutputOptions(flags);
+    if (action === 'image.generate' || action === 'image.edit')
+        validateImageOptions(positionals, flags);
+    if (action === 'image.edit')
+        validateImageEditOptions(flags);
+    if (action === 'audio.speech')
+        validateSpeechOptions(positionals, flags);
+    if (action === 'audio.transcribe')
+        validateAudioUploadOptions(flags, true);
+    if (action === 'audio.translate')
+        validateAudioUploadOptions(flags, false);
+    if (action === 'video.generate')
+        validateVideoOptions(flags);
+}
+export function validateImageEditInputCount(paths) {
+    if (paths.length === 0)
+        throw invalid('`--image` requires at least one workspace image path.');
+    if (paths.length > GATEWAY_MEDIA_LIMITS.imageCount)
+        throw invalid(`Image edits support at most ${GATEWAY_MEDIA_LIMITS.imageCount} input images.`);
+}
+export function validateUploadSize(bytes, maximum, label) {
+    if (bytes > 0 && bytes <= maximum)
+        return;
+    throw invalid(`${label} must be between 1 byte and ${formatByteLimit(maximum)}.`);
+}
+export function validateImageEditTotalSize(bytes) {
+    if (bytes <= GATEWAY_MEDIA_LIMITS.imageEditTotalBytes)
+        return;
+    throw invalid(`Image edit uploads must not exceed ${formatByteLimit(GATEWAY_MEDIA_LIMITS.imageEditTotalBytes)} in total.`);
+}
+export function formatByteLimit(bytes) {
+    if (bytes >= MEGABYTE)
+        return `${bytes / MEGABYTE} MB`;
+    if (bytes >= KILOBYTE)
+        return `${bytes / KILOBYTE} KB`;
+    return `${bytes} bytes`;
+}
+function validateOutputOptions(flags) {
+    const out = value(flags, 'out');
+    if (enabled(flags, 'force') && out === undefined)
+        throw invalid('`--force` is only valid with `--out`.');
+}
+function validateImageOptions(positionals, flags) {
+    validateLength(requiredPrompt(positionals, 'image'), GATEWAY_MEDIA_LIMITS.imagePromptCharacters, 'Image prompt');
+    const count = integer(flags, 'n');
+    if (count !== undefined && (count < 1 || count > GATEWAY_MEDIA_LIMITS.imageCount))
+        throw invalid(`--n must be an integer between 1 and ${GATEWAY_MEDIA_LIMITS.imageCount}.`);
+    if (count !== undefined && count > 1 && value(flags, 'out') !== undefined)
+        throw invalid('--out can only be used when exactly one image artifact is requested. Use --out-dir instead.');
+    const size = value(flags, 'size');
+    if (size !== undefined && size !== 'auto' && !/^\d{2,4}x\d{2,4}$/u.test(size))
+        throw invalid('--size must be `auto` or WIDTHxHEIGHT.');
+    if (size !== undefined && size !== 'auto')
+        validateImageDimensions(size);
+    const format = value(flags, 'output-format');
+    const compression = integer(flags, 'output-compression');
+    if (compression !== undefined && (compression < 0 || compression > 100))
+        throw invalid('--output-compression must be an integer between 0 and 100.');
+    if (compression !== undefined && format !== 'jpeg' && format !== 'webp')
+        throw invalid('--output-compression requires --output-format jpeg or webp.');
+    validateLength(value(flags, 'moderation'), 64, 'Moderation value');
+    validateLength(value(flags, 'user'), 255, 'User value');
+}
+function validateImageEditOptions(flags) {
+    if (value(flags, 'image') === undefined)
+        throw invalid('Missing required option --image.');
+}
+function validateSpeechOptions(positionals, flags) {
+    validateLength(requiredPrompt(positionals, 'speech'), GATEWAY_MEDIA_LIMITS.speechInputCharacters, 'Speech input');
+    validateLength(required(flags, 'voice'), GATEWAY_MEDIA_LIMITS.speechVoiceCharacters, 'Voice');
+    validateLength(value(flags, 'instructions'), GATEWAY_MEDIA_LIMITS.speechInstructionsCharacters, 'Speech instructions');
+    const speed = number(flags, 'speed');
+    if (speed !== undefined && (speed < 0.25 || speed > 4))
+        throw invalid('--speed must be between 0.25 and 4.');
+}
+function validateAudioUploadOptions(flags, transcription) {
+    validateLength(value(flags, 'prompt'), GATEWAY_MEDIA_LIMITS.audioPromptCharacters, 'Audio prompt');
+    const temperature = number(flags, 'temperature');
+    if (temperature !== undefined && (temperature < 0 || temperature > 1))
+        throw invalid('--temperature must be between 0 and 1.');
+    if (!transcription)
+        return;
+    validateLength(value(flags, 'language'), GATEWAY_MEDIA_LIMITS.transcriptionLanguageCharacters, 'Language code');
+    if (value(flags, 'timestamp-granularities') !== undefined && value(flags, 'response-format') !== 'verbose_json')
+        throw invalid('--timestamp-granularities requires --response-format verbose_json.');
+}
+function validateVideoOptions(flags) {
+    if (enabled(flags, 'no-wait') && (value(flags, 'out') !== undefined || value(flags, 'out-dir') !== undefined || enabled(flags, 'force'))) {
+        throw invalid('--no-wait cannot be combined with output options. Use video download after the operation completes.');
+    }
+}
+function validateImageDimensions(value) {
+    const [widthRaw, heightRaw] = value.split('x');
+    const width = Number(widthRaw);
+    const height = Number(heightRaw);
+    if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height) || width < 1 || height < 1 || width > 4_096 || height > 4_096 || Math.max(width, height) / Math.min(width, height) > 3 || width % 16 !== 0 || height % 16 !== 0) {
+        throw invalid('--size must use positive dimensions up to 4096px, a maximum 3:1 aspect ratio, and multiples of 16.');
+    }
+}
+function requiredPrompt(positionals, label) {
+    const prompt = positionals.join(' ').trim();
+    if (prompt.length === 0)
+        throw invalid(`A prompt is required for ${label}.`);
+    return prompt;
+}
+function required(flags, name) {
+    const result = value(flags, name);
+    if (result === undefined)
+        throw invalid(`Missing required option --${name}.`);
+    return result;
+}
+function validateLength(text, maximum, label) {
+    if (text !== undefined && text.length > maximum)
+        throw invalid(`${label} must not exceed ${maximum} characters.`);
+}
+function integer(flags, name) {
+    const raw = value(flags, name);
+    if (raw === undefined)
+        return undefined;
+    if (!/^\d+$/u.test(raw) || !Number.isSafeInteger(Number(raw)))
+        throw invalid(`--${name} must be an integer.`);
+    return Number(raw);
+}
+function number(flags, name) {
+    const raw = value(flags, name);
+    if (raw === undefined)
+        return undefined;
+    const result = Number(raw);
+    if (!Number.isFinite(result))
+        throw invalid(`--${name} must be a finite number.`);
+    return result;
+}
+function value(flags, name) {
+    const candidate = flags.get(name);
+    return typeof candidate === 'string' && candidate.trim().length > 0 ? candidate.trim() : undefined;
+}
+function enabled(flags, name) {
+    return flags.get(name) === true || flags.get(name) === 'true';
+}
+function invalid(userMessage) {
+    return new CliError(CLI_ERROR_CODES.INVALID_ARGUMENT, userMessage, { category: 'media', userMessage });
+}

package/dist/domain/media/media-contract.d.ts

@@ -0,0 +1,28 @@
+export type MediaArtifactKind = 'image' | 'speech' | 'transcription' | 'translation' | 'video';
+export interface MediaBinary {
+    readonly bytes: Uint8Array;
+    readonly contentType?: string;
+}
+export interface GeneratedImage {
+    readonly base64?: string;
+    readonly url?: string;
+    readonly revisedPrompt?: string;
+}
+export interface VideoOperation {
+    readonly id: string;
+    readonly done: boolean;
+    readonly errorMessage?: string;
+}
+export interface MediaArtifactRequest {
+    readonly kind: MediaArtifactKind;
+    readonly source: string;
+    readonly extension: string;
+    /** Filename stem without extension; the artifact store appends extension. */
+    readonly out?: string;
+    readonly outDir?: string;
+    readonly force: boolean;
+}
+export interface StoredMediaArtifact {
+    readonly path: string;
+    readonly bytes: number;
+}

package/dist/domain/media/media-contract.js

@@ -0,0 +1 @@
+export {};

package/dist/domain/media/media-execution-policy.d.ts

@@ -0,0 +1,9 @@
+export interface MediaExecutionPolicy {
+    readonly videoPollIntervalMs: number;
+    readonly videoWaitTimeoutMs: number;
+    readonly downloadTimeoutMs: number;
+}
+type Environment = Readonly<Record<string, string | undefined>>;
+/** CLI-owned local resource policy. It does not alter gateway or SDK contracts. */
+export declare function resolveMediaExecutionPolicy(environment?: Environment): MediaExecutionPolicy;
+export {};

package/dist/domain/media/media-execution-policy.js

@@ -0,0 +1,31 @@
+import { CliError } from '../errors/cli-error.js';
+import { CLI_ERROR_CODES } from '../errors/error-codes.js';
+const DEFAULT_VIDEO_POLL_INTERVAL_MS = 5_000;
+const DEFAULT_VIDEO_WAIT_TIMEOUT_MS = 20 * 60 * 1_000;
+const DEFAULT_MEDIA_DOWNLOAD_TIMEOUT_MS = 60_000;
+/** CLI-owned local resource policy. It does not alter gateway or SDK contracts. */
+export function resolveMediaExecutionPolicy(environment = process.env) {
+    const videoPollIntervalMs = readPositiveInteger(environment, 'LOTAGATE_VIDEO_POLL_INTERVAL_MS', DEFAULT_VIDEO_POLL_INTERVAL_MS);
+    const videoWaitTimeoutMs = readPositiveInteger(environment, 'LOTAGATE_VIDEO_WAIT_TIMEOUT_MS', DEFAULT_VIDEO_WAIT_TIMEOUT_MS);
+    if (videoWaitTimeoutMs < videoPollIntervalMs)
+        throw invalidPolicy('LOTAGATE_VIDEO_WAIT_TIMEOUT_MS must not be smaller than LOTAGATE_VIDEO_POLL_INTERVAL_MS.');
+    return {
+        videoPollIntervalMs,
+        videoWaitTimeoutMs,
+        downloadTimeoutMs: readPositiveInteger(environment, 'LOTAGATE_MEDIA_DOWNLOAD_TIMEOUT_MS', DEFAULT_MEDIA_DOWNLOAD_TIMEOUT_MS),
+    };
+}
+function readPositiveInteger(environment, name, fallback) {
+    const raw = environment[name];
+    if (raw === undefined || raw.trim().length === 0)
+        return fallback;
+    if (!/^\d+$/u.test(raw))
+        throw invalidPolicy(`${name} must be a positive integer.`);
+    const value = Number(raw);
+    if (!Number.isSafeInteger(value) || value <= 0)
+        throw invalidPolicy(`${name} must be a positive integer.`);
+    return value;
+}
+function invalidPolicy(userMessage) {
+    return new CliError(CLI_ERROR_CODES.CONFIG_SCHEMA_INVALID, userMessage, { category: 'config', userMessage });
+}

package/dist/domain/orchestration/goal.d.ts

@@ -0,0 +1,58 @@
+export type GoalStatus = 'active' | 'paused' | 'completed' | 'blocked' | 'budget_limited' | 'usage_limited';
+export type GoalDecision = 'continue' | 'complete' | 'blocked' | 'budget_limited' | 'usage_limited';
+export interface GoalEvaluation {
+    decision: GoalDecision;
+    reason: string;
+    evidence: readonly string[];
+    timestamp: string;
+    evaluatorModel?: string;
+}
+export interface GoalUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    modelCalls: number;
+    estimated: boolean;
+}
+export interface GoalUsageDelta {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+    modelCalls?: number;
+    estimated?: boolean;
+}
+export interface GoalState {
+    id: string;
+    sessionId: string;
+    objective: string;
+    status: GoalStatus;
+    createdAt: string;
+    updatedAt: string;
+    startedAt: string;
+    turns: number;
+    evaluatorRuns: number;
+    usage: GoalUsage;
+    tokenBudget?: number;
+    maxTurns?: number;
+    maxDurationMs?: number;
+    lastEvaluation?: GoalEvaluation;
+    lastError?: string;
+}
+export interface CreateGoalInput {
+    objective: string;
+    tokenBudget?: number;
+    maxTurns?: number;
+    maxDurationMs?: number;
+}
+export declare function validateGoalInput(input: CreateGoalInput): CreateGoalInput;
+/** Identifies journal events that must carry a complete goal snapshot. */
+export declare function isGoalEventType(value: string): boolean;
+/** Validates the complete durable goal state before it controls execution limits. */
+export declare function isGoalState(value: unknown): value is GoalState;
+/** Validates the durable evaluator result embedded in a goal snapshot. */
+export declare function isGoalEvaluation(value: unknown): value is GoalEvaluation;
+/** Validates the data payload written by a durable goal lifecycle event. */
+export declare function isPersistedGoalEventData(value: unknown): boolean;
+export declare function transitionGoal(state: GoalState, status: GoalStatus): GoalState;
+export declare function addGoalUsage(current: GoalUsage, delta: GoalUsageDelta): GoalUsage;
+export declare const EMPTY_GOAL_USAGE: GoalUsage;

package/dist/domain/orchestration/goal.js

@@ -0,0 +1,113 @@
+import { RESOURCE_LIMITS } from '../runtime/resource-limits.js';
+const GOAL_EVENT_TYPES = new Set([
+    'goal.created', 'goal.replaced', 'goal.paused', 'goal.resumed', 'goal.evaluated',
+    'goal.completed', 'goal.blocked', 'goal.budget_limited', 'goal.usage_limited',
+    'goal.usage_recorded', 'goal.cleared', 'goal.turn.started',
+]);
+export function validateGoalInput(input) {
+    const objective = input.objective.trim();
+    if (objective.length === 0 || objective.length > 16_384 || /[\0\r\n]/u.test(objective)) {
+        throw new Error('Goal objective must contain between 1 and 16384 printable characters.');
+    }
+    for (const [name, value] of Object.entries(input)) {
+        if (name === 'objective' || value === undefined)
+            continue;
+        if (!Number.isSafeInteger(value) || value <= 0)
+            throw new Error(`Goal limit ${name} must be a positive integer.`);
+    }
+    if (input.maxDurationMs !== undefined && input.maxDurationMs > RESOURCE_LIMITS.goalMaximumMaxDurationMs) {
+        throw new Error('Goal maxDurationMs cannot exceed 8 hours.');
+    }
+    return { objective, ...(input.tokenBudget === undefined ? {} : { tokenBudget: input.tokenBudget }), ...(input.maxTurns === undefined ? {} : { maxTurns: input.maxTurns }), ...(input.maxDurationMs === undefined ? {} : { maxDurationMs: input.maxDurationMs }) };
+}
+/** Identifies journal events that must carry a complete goal snapshot. */
+export function isGoalEventType(value) {
+    return GOAL_EVENT_TYPES.has(value);
+}
+/** Validates the complete durable goal state before it controls execution limits. */
+export function isGoalState(value) {
+    if (!isRecord(value))
+        return false;
+    return typeof value['id'] === 'string' && typeof value['sessionId'] === 'string' && isValidGoalObjective(value['objective'])
+        && isGoalStatus(value['status']) && isTimestamp(value['createdAt']) && isTimestamp(value['updatedAt']) && isTimestamp(value['startedAt'])
+        && isNonNegativeSafeInteger(value['turns']) && isNonNegativeSafeInteger(value['evaluatorRuns']) && isGoalUsage(value['usage'])
+        && isOptionalPositiveSafeInteger(value['tokenBudget']) && isOptionalPositiveSafeInteger(value['maxTurns'])
+        && isOptionalDuration(value['maxDurationMs']) && isOptionalGoalEvaluation(value['lastEvaluation'])
+        && (value['lastError'] === undefined || (typeof value['lastError'] === 'string' && Buffer.byteLength(value['lastError'], 'utf8') <= RESOURCE_LIMITS.goalReasonBytes));
+}
+/** Validates the durable evaluator result embedded in a goal snapshot. */
+export function isGoalEvaluation(value) {
+    if (!isRecord(value))
+        return false;
+    return isGoalDecision(value['decision']) && typeof value['reason'] === 'string' && Buffer.byteLength(value['reason'], 'utf8') <= RESOURCE_LIMITS.goalReasonBytes
+        && Array.isArray(value['evidence']) && value['evidence'].length <= RESOURCE_LIMITS.goalEvidenceItems
+        && value['evidence'].every((item) => typeof item === 'string' && Buffer.byteLength(item, 'utf8') <= RESOURCE_LIMITS.goalEvidenceBytes)
+        && isTimestamp(value['timestamp'])
+        && (value['evaluatorModel'] === undefined || typeof value['evaluatorModel'] === 'string');
+}
+/** Validates the data payload written by a durable goal lifecycle event. */
+export function isPersistedGoalEventData(value) {
+    if (!isRecord(value) || !isGoalState(value['goal']))
+        return false;
+    return value['evaluation'] === undefined || isGoalEvaluation(value['evaluation']);
+}
+export function transitionGoal(state, status) {
+    if (state.status === 'completed' || state.status === 'blocked' || state.status === 'budget_limited' || state.status === 'usage_limited') {
+        throw new Error(`Cannot transition a terminal goal from ${state.status}.`);
+    }
+    if (status === 'active' && state.status !== 'paused')
+        throw new Error(`Cannot resume a goal from ${state.status}.`);
+    if (status === 'paused' && state.status !== 'active')
+        throw new Error(`Cannot pause a goal from ${state.status}.`);
+    return { ...state, status, updatedAt: new Date().toISOString() };
+}
+export function addGoalUsage(current, delta) {
+    const inputTokens = nonNegative(current.inputTokens + (delta.inputTokens ?? 0));
+    const outputTokens = nonNegative(current.outputTokens + (delta.outputTokens ?? 0));
+    const totalTokens = nonNegative(current.totalTokens + (delta.totalTokens ?? (delta.inputTokens ?? 0) + (delta.outputTokens ?? 0)));
+    return {
+        inputTokens,
+        outputTokens,
+        totalTokens,
+        modelCalls: nonNegative(current.modelCalls + (delta.modelCalls ?? 0)),
+        estimated: current.estimated || delta.estimated === true,
+    };
+}
+export const EMPTY_GOAL_USAGE = Object.freeze({ inputTokens: 0, outputTokens: 0, totalTokens: 0, modelCalls: 0, estimated: false });
+function nonNegative(value) {
+    return Number.isSafeInteger(value) && value >= 0 ? value : Number.MAX_SAFE_INTEGER;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isGoalStatus(value) {
+    return value === 'active' || value === 'paused' || value === 'completed' || value === 'blocked' || value === 'budget_limited' || value === 'usage_limited';
+}
+function isGoalDecision(value) {
+    return value === 'continue' || value === 'complete' || value === 'blocked' || value === 'budget_limited' || value === 'usage_limited';
+}
+function isGoalUsage(value) {
+    if (!isRecord(value))
+        return false;
+    return isNonNegativeSafeInteger(value['inputTokens']) && isNonNegativeSafeInteger(value['outputTokens'])
+        && isNonNegativeSafeInteger(value['totalTokens']) && isNonNegativeSafeInteger(value['modelCalls'])
+        && typeof value['estimated'] === 'boolean';
+}
+function isOptionalGoalEvaluation(value) {
+    return value === undefined || isGoalEvaluation(value);
+}
+function isOptionalPositiveSafeInteger(value) {
+    return value === undefined || (typeof value === 'number' && Number.isSafeInteger(value) && value > 0);
+}
+function isOptionalDuration(value) {
+    return value === undefined || (typeof value === 'number' && Number.isSafeInteger(value) && value > 0 && value <= RESOURCE_LIMITS.goalMaximumMaxDurationMs);
+}
+function isNonNegativeSafeInteger(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+function isTimestamp(value) {
+    return typeof value === 'string' && Number.isFinite(Date.parse(value));
+}
+function isValidGoalObjective(value) {
+    return typeof value === 'string' && value.trim().length > 0 && value.length <= RESOURCE_LIMITS.goalObjectiveBytes && !/[\0\r\n]/u.test(value);
+}

package/dist/domain/orchestration/subagent-identity.d.ts

@@ -0,0 +1,2 @@
+/** Returns a concise, stable display identity for one parent-session subagent. */
+export declare function subagentDisplayName(sequence: number): string;

package/dist/domain/orchestration/subagent-identity.js

@@ -0,0 +1,8 @@
+const DISPLAY_NAMES = ['Atlas', 'Nova', 'Orion', 'Sage', 'Lyra', 'Ember', 'Aster', 'Coda'];
+/** Returns a concise, stable display identity for one parent-session subagent. */
+export function subagentDisplayName(sequence) {
+    const normalized = Math.max(0, Math.floor(sequence));
+    const base = DISPLAY_NAMES[normalized % DISPLAY_NAMES.length] ?? 'Agent';
+    const generation = Math.floor(normalized / DISPLAY_NAMES.length) + 1;
+    return generation === 1 ? base : `${base} ${generation}`;
+}