dsh-agy-cli 0.0.0-stage → 0.12.0

package/lib/agy/models.js

@@ -0,0 +1,203 @@
+import { resolveAgyExecutable, runProcess } from './process.js';
+import { normalizeModelId } from '../provider/config.js';
+import { MODEL_DISCOVERY_EMPTY_CODE, MODEL_DISCOVERY_FAILED_CODE, MODEL_DISCOVERY_OUTPUT_LIMIT_CODE, MODEL_DISCOVERY_TIMEOUT_CODE, } from '../provider/error-codes.js';
+export const DEFAULT_MODEL_DISCOVERY_TTL_MS = 5 * 60_000;
+export const DEFAULT_MODEL_DISCOVERY_TIMEOUT_MS = 10_000;
+export const MAX_MODEL_DISCOVERY_OUTPUT_BYTES = 1 * 1024 * 1024;
+const MODEL_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:+@/-]{0,255}$/;
+const MAX_MODEL_DISPLAY_LENGTH = 512;
+class ModelDiscoveryFailure extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = 'ModelDiscoveryFailure';
+    }
+}
+function isSuccessful(result) {
+    return result.termination === 'completed' && result.exitCode === 0;
+}
+function warningOf(error) {
+    if (error instanceof ModelDiscoveryFailure)
+        return { message: error.message, code: error.code };
+    return { message: 'AGY model discovery failed', code: MODEL_DISCOVERY_FAILED_CODE };
+}
+function metadataValue(preferred, fallback, key) {
+    const preferredValue = preferred[key];
+    if (preferredValue !== undefined)
+        return preferredValue;
+    return fallback?.[key];
+}
+/** Merge explicit configuration first, then add AGY-discovered models. Normalizes base ids and dedupes. */
+export function mergeModelCatalog(configured, discovered) {
+    const normalizedDiscovered = discovered.map(m => ({ ...m, id: normalizeModelId(m.id) }));
+    const discoveredById = new Map(normalizedDiscovered.map(model => [model.id.toLowerCase(), model]));
+    const merged = [];
+    const seen = new Set();
+    for (const configuredModel of configured) {
+        const baseId = normalizeModelId(configuredModel.id);
+        const key = baseId.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const discoveredModel = discoveredById.get(baseId.toLowerCase());
+        const model = { id: baseId };
+        const name = metadataValue(configuredModel, discoveredModel, 'name');
+        const description = metadataValue(configuredModel, discoveredModel, 'description');
+        const contextWindow = metadataValue(configuredModel, discoveredModel, 'contextWindow');
+        if (name !== undefined)
+            model.name = name;
+        if (description !== undefined)
+            model.description = description;
+        if (contextWindow !== undefined)
+            model.contextWindow = contextWindow;
+        merged.push(model);
+    }
+    for (const discoveredModel of normalizedDiscovered) {
+        const key = discoveredModel.id.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        merged.push({ ...discoveredModel });
+    }
+    return merged;
+}
+/** @deprecated Use normalizeModelId/extractModelEffort for effort-split handling. */
+export const MODEL_EFFORT_SUFFIX_RE = /-(?:low|medium|high)$/i;
+/** Parse the tab-separated, non-interactive output of `agy models`. Normalizes -high/-medium/-low suffix to base id and dedupes base. */
+export function parseAgyModels(output) {
+    const models = [];
+    const seen = new Set();
+    const baseSeen = new Set();
+    for (const rawLine of output.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (line.length === 0)
+            continue;
+        const fields = line.split(/\t+/);
+        const id = fields.shift()?.trim() ?? '';
+        const display = fields.join(' ').trim();
+        if (!MODEL_ID_PATTERN.test(id) || seen.has(id))
+            continue;
+        const baseId = normalizeModelId(id);
+        if (baseSeen.has(baseId.toLowerCase()))
+            continue;
+        // Header rows: "ID\tDisplay Name" and any case/column-naming variant of it
+        // must not become a phantom catalog entry. A real model id carries a dot
+        // or a digit-bearing version segment; a header word like MODEL does not.
+        const headerRow = /display|name/i.test(display)
+            && (id.toLowerCase() === 'id' || !/[.\d]/.test(id));
+        if (headerRow)
+            continue;
+        if (display.length > MAX_MODEL_DISPLAY_LENGTH || /[\u0000-\u001f\u007f]/.test(display))
+            continue;
+        seen.add(id);
+        baseSeen.add(baseId.toLowerCase());
+        // Preserve display but normalize id to base for DSH reasoningEffort split
+        // Handle displays like "Gemini 3.1 Pro (High)" or "Gemini 3.7 Flash - High"
+        const strippedDisplay = display
+            .replace(/\s*[\(\[]\s*(?:low|medium|high)\s*[\)\]]\s*$/i, '')
+            .replace(/(?:\s+|-)(?:low|medium|high)\s*$/i, '')
+            .trim();
+        const normalized = display.length === 0 ? { id: baseId } : { id: baseId, name: strippedDisplay.length === 0 ? baseId : strippedDisplay };
+        models.push(normalized);
+    }
+    return models;
+}
+/**
+ * Discover AGY models without invoking a model request. Results are kept in
+ * memory only. A refresh is single-flight and all failures fail open to the
+ * last successful catalog or the caller's static catalog.
+ */
+export class AgyModelDiscovery {
+    executable;
+    ttlMs;
+    timeoutMs;
+    maxOutputBytes;
+    runCommand;
+    now;
+    cache;
+    inFlight;
+    constructor(options = {}) {
+        this.executable = options.executable?.trim() === '' ? undefined : options.executable?.trim();
+        this.ttlMs = options.ttlMs ?? DEFAULT_MODEL_DISCOVERY_TTL_MS;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_MODEL_DISCOVERY_TIMEOUT_MS;
+        this.maxOutputBytes = Math.min(options.maxOutputBytes ?? MAX_MODEL_DISCOVERY_OUTPUT_BYTES, MAX_MODEL_DISCOVERY_OUTPUT_BYTES);
+        this.runCommand = options.runCommand ?? runProcess;
+        this.now = options.now ?? Date.now;
+    }
+    async discover(configured) {
+        const currentTime = this.now();
+        if (this.cache !== undefined && this.cache.expiresAt > currentTime) {
+            return { models: this.cache.models, source: 'cache', stale: false };
+        }
+        if (this.inFlight !== undefined)
+            return this.inFlight;
+        const refresh = this.refresh(configured);
+        this.inFlight = refresh;
+        try {
+            return await refresh;
+        }
+        finally {
+            if (this.inFlight === refresh)
+                this.inFlight = undefined;
+        }
+    }
+    async refresh(configured) {
+        try {
+            const request = {
+                executable: resolveAgyExecutable(this.executable),
+                args: ['models'],
+                timeoutMs: this.timeoutMs,
+                maxStdoutBytes: this.maxOutputBytes,
+                maxStderrBytes: this.maxOutputBytes,
+                windowsNoConsole: true,
+            };
+            const result = await this.runCommand(request);
+            if (!isSuccessful(result)) {
+                const code = result.termination === 'timeout'
+                    ? MODEL_DISCOVERY_TIMEOUT_CODE
+                    : result.termination === 'output-limit'
+                        ? MODEL_DISCOVERY_OUTPUT_LIMIT_CODE
+                        : MODEL_DISCOVERY_FAILED_CODE;
+                throw new ModelDiscoveryFailure(code === MODEL_DISCOVERY_TIMEOUT_CODE
+                    ? 'AGY model discovery command timed out'
+                    : code === MODEL_DISCOVERY_OUTPUT_LIMIT_CODE
+                        ? 'AGY model discovery output exceeded its limit'
+                        : 'AGY model discovery command failed', code);
+            }
+            const discovered = parseAgyModels(result.stdoutLines.join('\n'));
+            if (discovered.length === 0)
+                throw new ModelDiscoveryFailure('AGY model discovery returned no usable models', MODEL_DISCOVERY_EMPTY_CODE);
+            const models = mergeModelCatalog(configured, discovered);
+            this.cache = {
+                models,
+                expiresAt: this.now() + this.ttlMs,
+            };
+            return {
+                models,
+                source: configured.length === 0 ? 'discovered' : 'merged',
+                stale: false,
+            };
+        }
+        catch (error) {
+            const warning = warningOf(error);
+            if (this.cache !== undefined) {
+                return {
+                    models: this.cache.models,
+                    source: 'cache',
+                    stale: true,
+                    warning: warning.message,
+                    warningCode: warning.code,
+                };
+            }
+            return {
+                models: configured,
+                source: 'fallback',
+                stale: true,
+                warning: warning.message,
+                warningCode: warning.code,
+            };
+        }
+    }
+}
+//# sourceMappingURL=models.js.map

package/lib/agy/overrides.d.ts

@@ -0,0 +1,17 @@
+import { type AgyReasoningEffort } from './process.js';
+export interface AgyRuntimeOverrides {
+    hiddenModels: string[];
+    defaultEffort?: AgyReasoningEffort;
+    defaultModel?: string;
+}
+export declare function readAgyRuntimeOverrides(): AgyRuntimeOverrides | undefined;
+export declare function saveAgyRuntimeOverrides(updates: {
+    hiddenModels?: string[];
+    defaultEffort?: string;
+    defaultModel?: string;
+}): void;
+export declare function agyRuntimeOverridesPath(): string;
+/** Test-only: point the reader/writer at an alternate file. */
+export declare function __setAgyOverridesPathForTest(path: string | undefined): void;
+export declare function agyRuntimeOverridesMtimeMs(): number | undefined;
+//# sourceMappingURL=overrides.d.ts.map

package/lib/agy/overrides.js

@@ -0,0 +1,73 @@
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { dshHome } from '../dsh-home.js';
+import { isAgyReasoningEffort } from './process.js';
+const RUNTIME_OVERRIDES_PATH = join(dshHome(), 'agy-cli', 'runtime-overrides.json');
+// Indirection so tests (and the panel, if it ever runs in-process) can point the
+// reader at a different location without touching the user's real file.
+let _overridesPathOverride;
+// The panel and the generation path are two processes that must agree on the
+// default effort, so both read this one file (the panel writes it, see
+// src/web/router.ts). If the file is absent or unreadable the caller falls back
+// to its built-in default.
+export function readAgyRuntimeOverrides() {
+    const p = _overridesPathOverride ?? RUNTIME_OVERRIDES_PATH;
+    if (!existsSync(p))
+        return undefined;
+    let data;
+    try {
+        data = JSON.parse(readFileSync(p, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    const record = data;
+    if (record === null || typeof record !== 'object')
+        return undefined;
+    const hiddenModels = Array.isArray(record.hiddenModels)
+        ? record.hiddenModels.filter((value) => typeof value === 'string')
+        : [];
+    const parsed = { hiddenModels };
+    if (isAgyReasoningEffort(record.defaultEffort))
+        parsed.defaultEffort = record.defaultEffort;
+    if (typeof record.defaultModel === 'string' && record.defaultModel !== '')
+        parsed.defaultModel = record.defaultModel;
+    return parsed;
+}
+// Write half of the same file. Preserves the keys the caller did not touch
+// (the panel updates one field at a time; a plain overwrite would wipe
+// sibling keys) and atomically-ish replaces the whole file so a reader never
+// sees a half-written document. Effort is re-validated on write because the
+// panel posts a raw string; an unknown value must not persist.
+export function saveAgyRuntimeOverrides(updates) {
+    const p = _overridesPathOverride ?? RUNTIME_OVERRIDES_PATH;
+    const current = readAgyRuntimeOverrides() ?? { hiddenModels: [] };
+    const merged = { ...current };
+    if (updates.hiddenModels !== undefined)
+        merged.hiddenModels = updates.hiddenModels.filter((value) => typeof value === 'string');
+    if (updates.defaultEffort !== undefined) {
+        if (isAgyReasoningEffort(updates.defaultEffort))
+            merged.defaultEffort = updates.defaultEffort;
+    }
+    if (updates.defaultModel !== undefined)
+        merged.defaultModel = updates.defaultModel;
+    const dir = dirname(p);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(p, JSON.stringify(merged, null, 2) + '\n', 'utf8');
+}
+export function agyRuntimeOverridesPath() {
+    return _overridesPathOverride ?? RUNTIME_OVERRIDES_PATH;
+}
+/** Test-only: point the reader/writer at an alternate file. */
+export function __setAgyOverridesPathForTest(path) {
+    _overridesPathOverride = path;
+}
+export function agyRuntimeOverridesMtimeMs() {
+    try {
+        return statSync(RUNTIME_OVERRIDES_PATH).mtimeMs;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=overrides.js.map

package/lib/agy/parser.d.ts

@@ -0,0 +1,102 @@
+export interface AgyJsonEvent {
+    event: string;
+    [key: string]: unknown;
+}
+export type AgyParserErrorCode = 'INVALID_JSON_LINE' | 'INVALID_EVENT' | 'LINE_TOO_LONG';
+export declare const DEFAULT_MAX_LINE_LENGTH = 1048576;
+export interface AgyParserOptions {
+    /** Maximum UTF-16 code units accepted for one NDJSON line. */
+    maxLineLength?: number;
+}
+export declare class AgyParserError extends Error {
+    readonly code: AgyParserErrorCode;
+    readonly lineNumber: number;
+    readonly rawLine: string;
+    constructor(message: string, code: AgyParserErrorCode, lineNumber: number, rawLine: string, options?: ErrorOptions);
+}
+export type AgyEventCategory = 'init' | 'step_update' | 'checkpoint' | 'agent_response' | 'result' | 'tool' | 'permission' | 'error' | 'unknown';
+export type AgyEventCategoryCounts = Record<AgyEventCategory, number>;
+export type AgyToolEventKind = 'event-tool-call' | 'event-tool-result' | 'step-type-tool' | 'explicit-tool-name';
+export type AgyToolEventCarrierShape = 'not-send-message' | 'missing-recipient' | 'missing-message' | 'unreadable-recipient' | 'unreadable-message' | 'complete';
+export type AgyToolEventRecipientClass = 'not-applicable' | 'missing' | 'default-api' | 'dsh-recipient' | 'self-conversation' | 'other-conversation' | 'other';
+/** Safe structural metadata for diagnosing AGY tool events without logging payload values. */
+export interface AgyToolEventDiagnostic {
+    readonly eventName: string;
+    readonly kind: AgyToolEventKind;
+    readonly stepType?: string;
+    readonly toolName?: string;
+    readonly carrierShape: AgyToolEventCarrierShape;
+    readonly recipientClass: AgyToolEventRecipientClass;
+    readonly topLevelKeys: readonly string[];
+    readonly stepKeys: readonly string[];
+    readonly toolInputKeys: readonly string[];
+}
+export declare function isDshCarrierRecipient(value: string): boolean;
+export declare function isAgyToolEventKind(value: unknown): value is AgyToolEventKind;
+export declare function emptyAgyEventCategoryCounts(): AgyEventCategoryCounts;
+/** Parse one complete NDJSON line and require only the stable event envelope. */
+export declare function parseAgyJsonLine(rawLine: string, lineNumber?: number, maxLineLength?: number): AgyJsonEvent;
+/** Incremental parser for arbitrary stdout chunks, including CRLF streams. */
+export declare class AgyStreamParser {
+    private buffer;
+    private lineNumber;
+    private readonly maxLineLength;
+    constructor(options?: AgyParserOptions);
+    push(chunk: string): AgyJsonEvent[];
+    end(): AgyJsonEvent[];
+    private parseLine;
+}
+/** Parse an async sequence of stdout chunks without buffering the full stream. */
+export declare function parseAgyChunks(chunks: AsyncIterable<string>): AsyncIterable<AgyJsonEvent>;
+/** Extract the AGY conversation identity emitted by an init event. */
+export declare function conversationIdOf(event: AgyJsonEvent): string | undefined;
+/** Return AGY's step type without constraining future event payloads. */
+export declare function stepTypeOf(event: AgyJsonEvent): string | undefined;
+/** Extract an explicit AGY tool name from a step update, when present. */
+export declare function toolNameOf(event: AgyJsonEvent): string | undefined;
+export interface AgySendMessagePayload {
+    readonly recipient: string;
+    readonly message: string;
+}
+/** Extract the narrowly-scoped AGY send_message carrier used by DSH-owned mode. */
+export declare function sendMessageOf(event: AgyJsonEvent): AgySendMessagePayload | undefined;
+/** Classify only explicit AGY tool lifecycle signals. */
+export declare function toolEventKindOf(event: AgyJsonEvent): AgyToolEventKind | undefined;
+/** Recognize internal AGY tool lifecycle events without mapping them to DSH tools. */
+export declare function isToolEvent(event: AgyJsonEvent): boolean;
+/** Classify a tool event's carrier shape without retaining any payload values. */
+export declare function toolEventDiagnosticOf(event: AgyJsonEvent, activeConversationId?: string): AgyToolEventDiagnostic | undefined;
+/** Recognize permission checkpoints that cannot be answered by a headless Provider. */
+export declare function isPermissionEvent(event: AgyJsonEvent): boolean;
+/**
+ * Classify only stable event categories; unknown event names remain forward-compatible.
+ *
+ * A step_update carries its own step_type, so a nested `agent_response` update is
+ * counted as `agent_response` rather than being swallowed by the outer `step_update`
+ * case. Counts must reflect what the model actually emitted: reading `agent_response`
+ * as `step_update` made telemetry report zero streamed text on every turn, even
+ * though AGY streams text deltas natively.
+ */
+export declare function eventCategoryOf(event: AgyJsonEvent): AgyEventCategory;
+/**
+ * Bounded JSON of AGY's own `result` frame.
+ *
+ * `status: "ERROR"` is the only signal the adapter gets on the long-context
+ * failures this provider sees, and AGY omits `error` on those frames, so the
+ * `response` text and the remaining keys are the sole surviving diagnosis.
+ * Keys that carry bulk are truncated rather than dropped: a missing key and a
+ * truncated key look identical in telemetry and would be indistinguishable from
+ * "AGY said nothing".
+ */
+export declare function finalResultRawOf(event: AgyJsonEvent): string | undefined;
+/** Extract bounded classification detail from AGY error events without exposing the payload. */
+export declare function errorDetailOf(event: AgyJsonEvent): string | undefined;
+/** Extract a text delta from the observed AGY step_update envelope. */
+export declare function textDeltaOf(event: AgyJsonEvent): string | undefined;
+/** Extract the final response text from a result event. */
+export declare function responseOf(event: AgyJsonEvent): string | undefined;
+/** Extract the final AGY result status without constraining future statuses. */
+export declare function statusOf(event: AgyJsonEvent): string | undefined;
+/** Extract usage as an opaque object; AGY may add fields across versions. */
+export declare function usageOf(event: AgyJsonEvent): Record<string, unknown> | undefined;
+//# sourceMappingURL=parser.d.ts.map