dsh-agy-cli 0.0.0-stage → 0.12.0

package/lib/agent-installer.d.ts

@@ -0,0 +1,66 @@
+import { type AgentPreset, type AgentPresetId } from './agent-presets.js';
+/**
+ * Where the AGY CLI discovers agent templates.
+ *
+ * This is `gemini-root-config/agents`, not `~/.gemini/config/agents`: the CLI
+ * keeps a second, differently-populated `agents` directory under its data root
+ * and only scans this one (`agy agents` lists a template added here and ignores
+ * one removed from the other). `DSH_AGY_CONFIG_ROOT` mirrors
+ * {@link agyConfigRoot} in `mcp/agy-registration.ts`, so pointing AGY at
+ * another root moves both the MCP table and the templates together.
+ */
+export declare const DEFAULT_AGENT_DIRECTORY: string;
+export type AgentInstallAction = 'create' | 'unchanged' | 'conflict' | 'backup-and-create';
+export declare class AgentInstallError extends Error {
+    readonly code: 'AGENT_TARGET_EXISTS' | 'AGENT_TARGET_NOT_FILE' | 'AGENT_INSTALL_FAILED';
+    constructor(message: string, code: 'AGENT_TARGET_EXISTS' | 'AGENT_TARGET_NOT_FILE' | 'AGENT_INSTALL_FAILED', options?: ErrorOptions);
+}
+export interface AgentInstallOptions {
+    preset: AgentPresetId | string;
+    directory?: string;
+    apply?: boolean;
+    backup?: boolean;
+}
+export interface AgentInstallResult {
+    preset: AgentPresetId;
+    agentName: string;
+    targetPath: string;
+    applied: boolean;
+    action: AgentInstallAction;
+    backupPath?: string;
+}
+/**
+ * Preview or explicitly install one bundled Agent template.
+ * Existing files are never overwritten unless both apply and backup are set.
+ */
+export declare function installAgentPreset(options: AgentInstallOptions): Promise<AgentInstallResult>;
+export interface AgentDirectoryEntry {
+    id: AgentPresetId;
+    agentName: string;
+    fileName: string;
+    description: string;
+    tools: readonly string[];
+    writeAccess: boolean;
+}
+/** One bundled template that is not present in the directory AGY scans. */
+export interface MissingAgentTemplate {
+    readonly preset: AgentPresetId;
+    readonly agentName: string;
+    readonly targetPath: string;
+}
+/**
+ * Which bundled templates are absent from the AGY agent directory.
+ *
+ * AGY refuses an unknown profile before it accepts any input, exiting with
+ * `error: unknown agent "<name>" (available: ...)`; the adapter then sees a
+ * child that died while its stdin was being written and reports
+ * `AGY_INPUT_FAILED`, which names the wrong component. Checking the directory up
+ * front turns that into one actionable line.
+ *
+ * Only presence is checked, never the contents: a user who edited their copy of
+ * a template meant to, and overwriting it is not this function's business.
+ */
+export declare function findMissingAgentTemplates(presets: readonly AgentPreset[], directory?: string): Promise<readonly MissingAgentTemplate[]>;
+export declare function describeAgentPresets(): readonly AgentDirectoryEntry[];
+export declare function isAgentPreset(value: unknown): value is AgentPresetId;
+//# sourceMappingURL=agent-installer.d.ts.map

package/lib/agent-installer.js

@@ -0,0 +1,147 @@
+import { randomUUID } from 'node:crypto';
+import { lstat, mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, join, resolve } from 'node:path';
+import { getAgentPreset, listAgentPresets, readAgentPresetTemplate, requireAgentPreset, } from './agent-presets.js';
+/**
+ * Where the AGY CLI discovers agent templates.
+ *
+ * This is `gemini-root-config/agents`, not `~/.gemini/config/agents`: the CLI
+ * keeps a second, differently-populated `agents` directory under its data root
+ * and only scans this one (`agy agents` lists a template added here and ignores
+ * one removed from the other). `DSH_AGY_CONFIG_ROOT` mirrors
+ * {@link agyConfigRoot} in `mcp/agy-registration.ts`, so pointing AGY at
+ * another root moves both the MCP table and the templates together.
+ */
+export const DEFAULT_AGENT_DIRECTORY = join(process.env.DSH_AGY_CONFIG_ROOT?.trim() || join(homedir(), '.gemini', 'antigravity-cli', 'gemini-root-config'), 'agents');
+export class AgentInstallError extends Error {
+    code;
+    constructor(message, code, options) {
+        super(message, options);
+        this.code = code;
+        this.name = 'AgentInstallError';
+    }
+}
+function configuredAgentDirectory(directory) {
+    const selected = directory?.trim() || process.env.AGY_AGENT_DIR?.trim() || DEFAULT_AGENT_DIRECTORY;
+    return resolve(selected);
+}
+async function targetState(targetPath) {
+    try {
+        const stat = await lstat(targetPath);
+        if (!stat.isFile())
+            return { exists: true, file: false };
+        return { exists: true, file: true, content: await readFile(targetPath, 'utf8') };
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return { exists: false };
+        throw error;
+    }
+}
+function backupPathFor(targetPath) {
+    return `${targetPath}.backup-${new Date().toISOString().replace(/[:.]/g, '-')}-${randomUUID()}`;
+}
+async function writeAtomic(targetPath, content) {
+    const directory = resolve(targetPath, '..');
+    const tempPath = join(directory, `.${basename(targetPath)}.${randomUUID()}.tmp`);
+    try {
+        await writeFile(tempPath, content, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+        await rename(tempPath, targetPath);
+    }
+    catch (error) {
+        await unlink(tempPath).catch(() => undefined);
+        throw new AgentInstallError(`Could not install Agent template: ${error instanceof Error ? error.message : String(error)}`, 'AGENT_INSTALL_FAILED', { cause: error });
+    }
+}
+function resultFor(preset, targetPath, applied, action, backupPath) {
+    return {
+        preset: preset.id,
+        agentName: preset.agentName,
+        targetPath,
+        applied,
+        action,
+        ...(backupPath === undefined ? {} : { backupPath }),
+    };
+}
+/**
+ * Preview or explicitly install one bundled Agent template.
+ * Existing files are never overwritten unless both apply and backup are set.
+ */
+export async function installAgentPreset(options) {
+    const preset = requireAgentPreset(options.preset);
+    const directory = configuredAgentDirectory(options.directory);
+    const targetPath = join(directory, preset.fileName);
+    const content = await readAgentPresetTemplate(preset);
+    const state = await targetState(targetPath);
+    if (state.exists && !state.file) {
+        throw new AgentInstallError(`Agent target is not a regular file: ${targetPath}`, 'AGENT_TARGET_NOT_FILE');
+    }
+    if (state.exists && state.content === content) {
+        // Nothing was written, so `applied` must stay false even under --apply:
+        // the CLI would otherwise report "applied" for a no-op.
+        return resultFor(preset, targetPath, false, 'unchanged');
+    }
+    if (state.exists && options.apply !== true) {
+        return resultFor(preset, targetPath, false, 'conflict');
+    }
+    if (state.exists && options.backup !== true) {
+        throw new AgentInstallError(`Agent target already exists; preview first, then use --backup to preserve it: ${targetPath}`, 'AGENT_TARGET_EXISTS');
+    }
+    if (options.apply !== true) {
+        return resultFor(preset, targetPath, false, 'create');
+    }
+    await mkdir(directory, { recursive: true });
+    let backupPath;
+    if (state.exists) {
+        backupPath = backupPathFor(targetPath);
+        await rename(targetPath, backupPath);
+    }
+    try {
+        await writeAtomic(targetPath, content);
+    }
+    catch (error) {
+        if (backupPath !== undefined) {
+            await rename(backupPath, targetPath).catch(() => undefined);
+        }
+        throw error;
+    }
+    return resultFor(preset, targetPath, true, backupPath === undefined ? 'create' : 'backup-and-create', backupPath);
+}
+/**
+ * Which bundled templates are absent from the AGY agent directory.
+ *
+ * AGY refuses an unknown profile before it accepts any input, exiting with
+ * `error: unknown agent "<name>" (available: ...)`; the adapter then sees a
+ * child that died while its stdin was being written and reports
+ * `AGY_INPUT_FAILED`, which names the wrong component. Checking the directory up
+ * front turns that into one actionable line.
+ *
+ * Only presence is checked, never the contents: a user who edited their copy of
+ * a template meant to, and overwriting it is not this function's business.
+ */
+export async function findMissingAgentTemplates(presets, directory) {
+    const root = configuredAgentDirectory(directory);
+    const missing = [];
+    for (const preset of presets) {
+        const targetPath = join(root, preset.fileName);
+        const state = await targetState(targetPath);
+        if (!state.exists || !state.file)
+            missing.push({ preset: preset.id, agentName: preset.agentName, targetPath });
+    }
+    return missing;
+}
+export function describeAgentPresets() {
+    return listAgentPresets().map(preset => ({
+        id: preset.id,
+        agentName: preset.agentName,
+        fileName: preset.fileName,
+        description: preset.description,
+        tools: preset.tools,
+        writeAccess: preset.writeAccess,
+    }));
+}
+export function isAgentPreset(value) {
+    return getAgentPreset(value) !== undefined;
+}
+//# sourceMappingURL=agent-installer.js.map

package/lib/agent-presets.d.ts

@@ -0,0 +1,42 @@
+export declare const AGENT_PRESET_IDS: readonly ["tool-free", "mcp-executor", "image-view", "read-only", "workspace-write"];
+export type AgentPresetId = typeof AGENT_PRESET_IDS[number];
+export type AgentExecutionMode = 'plan' | 'accept-edits';
+export interface AgentPreset {
+    readonly id: AgentPresetId;
+    readonly agentName: string;
+    readonly fileName: string;
+    readonly description: string;
+    readonly tools: readonly string[];
+    readonly writeAccess: boolean;
+    readonly mode: AgentExecutionMode | undefined;
+}
+export declare function listAgentPresets(): readonly AgentPreset[];
+export declare function getAgentPreset(value: unknown): AgentPreset | undefined;
+export declare function requireAgentPreset(value: string): AgentPreset;
+/**
+ * The Agent templates one request can reach, given the effective settings.
+ *
+ * AGY resolves `--agent` itself and exits with `unknown agent` when the named
+ * profile has no template on disk, so the set that must exist is derivable from
+ * the config without starting anything:
+ *
+ * - `dsh-owned` pins the executor preset, but an image-bearing request swaps in
+ *   the image preset, so an enabled `imageInput: experimental` adds it;
+ * - every other tool policy uses the configured `agent` string verbatim. That
+ *   string is matched against the bundled names first, because a user who typed
+ *   `dsh-agy-read-only` is naming a bundled template and deserves the same
+ *   presence check; an unmatched name is returned with no preset so callers can
+ *   see it is the user's own template to keep in place.
+ */
+export declare function agentTemplatesForRequest(options: {
+    readonly toolPolicy: 'reject' | 'agy-owned' | 'dsh-owned';
+    readonly agentPreset?: AgentPresetId | undefined;
+    readonly agent?: string | undefined;
+    readonly imageInput?: 'off' | 'experimental' | undefined;
+}): readonly {
+    readonly preset: AgentPreset | undefined;
+    readonly agentName: string;
+}[];
+/** Read a bundled template; the template file is included in the npm tarball. */
+export declare function readAgentPresetTemplate(value: AgentPresetId | AgentPreset): Promise<string>;
+//# sourceMappingURL=agent-presets.d.ts.map

package/lib/agent-presets.js

@@ -0,0 +1,130 @@
+import { readFile } from 'node:fs/promises';
+export const AGENT_PRESET_IDS = ['tool-free', 'mcp-executor', 'image-view', 'read-only', 'workspace-write'];
+const PRESETS = Object.freeze({
+    'tool-free': Object.freeze({
+        id: 'tool-free',
+        agentName: 'dsh-agy-tool-free',
+        fileName: 'dsh-agy-tool-free.md',
+        description: 'Text-only reasoning with no AGY tools.',
+        tools: Object.freeze([]),
+        writeAccess: false,
+        mode: undefined,
+    }),
+    'mcp-executor': Object.freeze({
+        id: 'mcp-executor',
+        agentName: 'dsh-agy-mcp-executor',
+        fileName: 'dsh-agy-mcp-executor.md',
+        // `excludeDefaultComponents: true` in the template is what removes the
+        // built-in tools; `tools: []` alone does not. Measured against AGY 1.3.2:
+        // an otherwise identical template carrying only `tools: []` still exposed
+        // all 60 built-ins, and the model called `run_command`, which headless mode
+        // then soft-denied, producing an empty response. A tool that does not exist
+        // cannot be called, which is the only reliable way to keep AGY's own
+        // executors out of the loop — an agent template that merely asks the model
+        // not to use them is bypassed probabilistically.
+        description: 'All actions through the DSH MCP server; no AGY built-in tools.',
+        tools: Object.freeze([]),
+        writeAccess: false,
+        mode: undefined,
+    }),
+    'image-view': Object.freeze({
+        id: 'image-view',
+        agentName: 'dsh-agy-image-view',
+        fileName: 'dsh-agy-image-view.md',
+        description: 'Per-request image inspection with only view_file enabled.',
+        tools: Object.freeze(['view_file']),
+        writeAccess: false,
+        mode: 'plan',
+    }),
+    'read-only': Object.freeze({
+        id: 'read-only',
+        agentName: 'dsh-agy-read-only',
+        fileName: 'dsh-agy-read-only.md',
+        description: 'Read-only workspace inspection and search.',
+        tools: Object.freeze(['find_by_name', 'grep_search', 'view_file', 'list_dir']),
+        writeAccess: false,
+        mode: 'plan',
+    }),
+    'workspace-write': Object.freeze({
+        id: 'workspace-write',
+        agentName: 'dsh-agy-workspace-write',
+        fileName: 'dsh-agy-workspace-write.md',
+        description: 'Bounded file edits inside an explicitly configured workspace.',
+        tools: Object.freeze([
+            'find_by_name',
+            'grep_search',
+            'view_file',
+            'list_dir',
+            'multi_replace_file_content',
+            'replace_file_content',
+            'write_to_file',
+        ]),
+        writeAccess: true,
+        mode: 'accept-edits',
+    }),
+});
+export function listAgentPresets() {
+    return AGENT_PRESET_IDS.map(id => PRESETS[id]);
+}
+export function getAgentPreset(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    return AGENT_PRESET_IDS.includes(value)
+        ? PRESETS[value]
+        : undefined;
+}
+export function requireAgentPreset(value) {
+    const preset = getAgentPreset(value);
+    if (preset === undefined) {
+        throw new TypeError(`Unknown Agent preset: ${value}. Expected one of: ${AGENT_PRESET_IDS.join(', ')}`);
+    }
+    return preset;
+}
+/**
+ * The Agent templates one request can reach, given the effective settings.
+ *
+ * AGY resolves `--agent` itself and exits with `unknown agent` when the named
+ * profile has no template on disk, so the set that must exist is derivable from
+ * the config without starting anything:
+ *
+ * - `dsh-owned` pins the executor preset, but an image-bearing request swaps in
+ *   the image preset, so an enabled `imageInput: experimental` adds it;
+ * - every other tool policy uses the configured `agent` string verbatim. That
+ *   string is matched against the bundled names first, because a user who typed
+ *   `dsh-agy-read-only` is naming a bundled template and deserves the same
+ *   presence check; an unmatched name is returned with no preset so callers can
+ *   see it is the user's own template to keep in place.
+ */
+export function agentTemplatesForRequest(options) {
+    const names = [];
+    const push = (preset, agentName) => {
+        if (agentName === undefined || names.some(entry => entry.agentName === agentName))
+            return;
+        names.push({ preset, agentName });
+    };
+    if (options.toolPolicy === 'dsh-owned') {
+        const executor = getAgentPreset('mcp-executor');
+        push(executor, executor?.agentName);
+        if (options.imageInput === 'experimental') {
+            const image = getAgentPreset('image-view');
+            push(image, image?.agentName);
+        }
+        return names;
+    }
+    const byPresetId = options.agentPreset === undefined ? undefined : getAgentPreset(options.agentPreset);
+    if (byPresetId !== undefined) {
+        push(byPresetId, byPresetId.agentName);
+        return names;
+    }
+    const byName = options.agent === undefined
+        ? undefined
+        : listAgentPresets().find(preset => preset.agentName === options.agent || preset.id === options.agent);
+    push(byName, options.agent);
+    return names;
+}
+/** Read a bundled template; the template file is included in the npm tarball. */
+export async function readAgentPresetTemplate(value) {
+    const preset = typeof value === 'string' ? requireAgentPreset(value) : value;
+    return readFile(new URL(`../agents/${preset.fileName}`, import.meta.url), 'utf8');
+}
+//# sourceMappingURL=agent-presets.js.map

package/lib/agents-cli.d.ts

@@ -0,0 +1,3 @@
+export declare function formatAgentsHelp(): string;
+export declare function runAgentsCli(argv: readonly string[], stdout?: (text: string) => void, stderr?: (text: string) => void): Promise<number>;
+//# sourceMappingURL=agents-cli.d.ts.map

package/lib/agents-cli.js

@@ -0,0 +1,110 @@
+import { AgentInstallError, describeAgentPresets, installAgentPreset, } from './agent-installer.js';
+import { AGENT_PRESET_IDS } from './agent-presets.js';
+function optionValue(args, name) {
+    const index = args.indexOf(name);
+    if (index === -1)
+        return undefined;
+    const value = args[index + 1];
+    if (value === undefined || value.startsWith('--'))
+        return undefined;
+    return value;
+}
+export function formatAgentsHelp() {
+    return `Usage: dsh-agy-cli agents <command> [options]
+
+Quota-free Agent template management. Preview is the default; no files are changed without --apply.
+
+Commands:
+  list                    List bundled Agent presets
+  install <preset>        Preview or install one preset
+
+Options:
+  --dir <path>            Agent directory (default: $AGY_AGENT_DIR or the AGY config root's agents/)
+  --apply                 Write the template; omitted means preview only
+  --backup                Move an existing file aside before --apply
+  --json                  Output structured JSON
+  -h, --help              Show help information
+
+Presets: ${AGENT_PRESET_IDS.join(', ')}
+
+Examples:
+  npx dsh-agy-cli agents list
+  npx dsh-agy-cli agents install read-only --dir ~/.gemini/antigravity-cli/gemini-root-config/agents
+  npx dsh-agy-cli agents install workspace-write --apply --backup
+`;
+}
+function formatInstallResult(result) {
+    // "unchanged" is neither applied nor a preview: the file already holds the
+    // target content, so saying either would mislead the operator.
+    const mode = result.action === 'unchanged' ? 'unchanged' : result.applied ? 'applied' : 'preview';
+    const lines = [
+        `mode: ${mode}`,
+        `preset: ${result.preset}`,
+        `agent: ${result.agentName}`,
+        `target: ${result.targetPath}`,
+        `action: ${result.action}`,
+    ];
+    if (result.backupPath !== undefined)
+        lines.push(`backup: ${result.backupPath}`);
+    if (!result.applied && result.action === 'create')
+        lines.push('next: rerun with --apply to write the file');
+    if (!result.applied && result.action === 'conflict')
+        lines.push('next: rerun with --apply --backup to preserve and replace the file');
+    return lines.join('\n');
+}
+export async function runAgentsCli(argv, stdout = text => process.stdout.write(text), stderr = text => process.stderr.write(text)) {
+    const args = [...argv];
+    if (args[0] === 'agents' || args[0] === 'agent')
+        args.shift();
+    if (args.includes('-h') || args.includes('--help')) {
+        stdout(`${formatAgentsHelp()}\n`);
+        return 0;
+    }
+    const command = args.shift() ?? 'list';
+    const jsonOutput = args.includes('--json');
+    if (command === 'list') {
+        const entries = describeAgentPresets();
+        if (jsonOutput)
+            stdout(`${JSON.stringify({ quotaUsed: false, presets: entries }, null, 2)}\n`);
+        else {
+            stdout(`${entries.map(entry => `${entry.id}: ${entry.agentName} [${entry.tools.join(', ') || 'no tools'}]`).join('\n')}\n`);
+        }
+        return 0;
+    }
+    if (command !== 'install') {
+        stderr(`Unknown agents command: ${command}. Use --help for usage.\n`);
+        return 2;
+    }
+    const preset = args.shift();
+    if (preset === undefined) {
+        stderr(`Missing Agent preset. Expected one of: ${AGENT_PRESET_IDS.join(', ')}\n`);
+        return 2;
+    }
+    try {
+        const directory = optionValue(args, '--dir');
+        const result = await installAgentPreset({
+            preset,
+            ...(directory === undefined ? {} : { directory }),
+            apply: args.includes('--apply'),
+            backup: args.includes('--backup'),
+        });
+        if (jsonOutput)
+            stdout(`${JSON.stringify({ quotaUsed: false, ...result }, null, 2)}\n`);
+        else
+            stdout(`${formatInstallResult(result)}\n`);
+        return 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (jsonOutput) {
+            stdout(`${JSON.stringify({ quotaUsed: false, ok: false, error: {
+                    code: error instanceof AgentInstallError ? error.code : 'AGENT_INSTALL_FAILED',
+                    message,
+                } }, null, 2)}\n`);
+        }
+        else
+            stderr(`Error installing Agent template: ${message}\n`);
+        return 1;
+    }
+}
+//# sourceMappingURL=agents-cli.js.map

package/lib/agy/diagnostics.d.ts

@@ -0,0 +1,29 @@
+import { type ProcessRequest, type ProcessResult } from './process.js';
+export interface AgyDiagnosticOptions {
+    executable?: string;
+    expectedAgent?: string;
+    minimumVersion?: string;
+    timeoutMs?: number;
+    runCommand?: AgyDiagnosticCommand;
+}
+export type AgyDiagnosticCommand = (request: ProcessRequest) => Promise<ProcessResult>;
+export interface AgyDiagnosticResult {
+    ok: boolean;
+    /** Safe source label; never contains the resolved user filesystem path. */
+    executable: string;
+    executableSource: 'explicit' | 'environment' | 'path';
+    version: string | undefined;
+    agents: readonly string[];
+    expectedAgent: string | undefined;
+    minimumVersion: string | undefined;
+    versionSupported: boolean;
+    agentAvailable: boolean;
+    errors: readonly string[];
+}
+export declare function parseAgyVersion(output: string): string | undefined;
+export declare function isAgyVersionAtLeast(actual: string, minimum: string): boolean;
+/** Parse the plain one-agent-per-line output of `agy agents`. */
+export declare function parseAgyAgents(output: string): string[];
+/** Check the local AGY executable without spending model quota or invoking tools. */
+export declare function diagnoseAgy(options?: AgyDiagnosticOptions): Promise<AgyDiagnosticResult>;
+//# sourceMappingURL=diagnostics.d.ts.map

package/lib/agy/diagnostics.js

@@ -0,0 +1,109 @@
+import { AgyProcessError, resolveAgyExecutable, runProcess } from './process.js';
+import { redactText } from './redact.js';
+function parseVersionValue(value) {
+    const match = /(?:^|\D)(\d+)\.(\d+)\.(\d+)(?:$|\D)/.exec(value);
+    if (match === null)
+        return undefined;
+    const major = Number(match[1]);
+    const minor = Number(match[2]);
+    const patch = Number(match[3]);
+    if (![major, minor, patch].every(Number.isSafeInteger))
+        return undefined;
+    return { major, minor, patch, text: `${major}.${minor}.${patch}` };
+}
+export function parseAgyVersion(output) {
+    return parseVersionValue(output)?.text;
+}
+export function isAgyVersionAtLeast(actual, minimum) {
+    const actualVersion = parseVersionValue(actual);
+    const minimumVersion = parseVersionValue(minimum);
+    if (actualVersion === undefined || minimumVersion === undefined)
+        return false;
+    if (actualVersion.major !== minimumVersion.major)
+        return actualVersion.major > minimumVersion.major;
+    if (actualVersion.minor !== minimumVersion.minor)
+        return actualVersion.minor > minimumVersion.minor;
+    return actualVersion.patch >= minimumVersion.patch;
+}
+/** Parse the plain one-agent-per-line output of `agy agents`. */
+export function parseAgyAgents(output) {
+    return [...new Set(output
+            .split(/\r?\n/)
+            .map(line => line.trim())
+            .filter(line => /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(line)))];
+}
+function commandRequest(executable, args, timeoutMs) {
+    return timeoutMs === undefined
+        ? { executable, args, windowsNoConsole: true }
+        : { executable, args, timeoutMs, windowsNoConsole: true };
+}
+function commandFailure(label, result) {
+    if (result.termination === 'completed' && result.exitCode === 0)
+        return undefined;
+    return `${label} failed (${result.termination}, exit code ${result.exitCode ?? 'unknown'})`;
+}
+function executableSource(options) {
+    if (options.executable?.trim())
+        return 'explicit';
+    if (process.env.AGY_PATH?.trim() || process.env.AGY_EXECUTABLE?.trim())
+        return 'environment';
+    return 'path';
+}
+async function runDiagnosticCommand(label, executable, args, timeoutMs, runCommand) {
+    try {
+        const result = await runCommand(commandRequest(executable, args, timeoutMs));
+        return { result, error: commandFailure(label, result) };
+    }
+    catch (error) {
+        if (error instanceof AgyProcessError) {
+            return { result: undefined, error: redactText(error.message, 512) };
+        }
+        return {
+            result: undefined,
+            error: `${label} failed: ${redactText(error instanceof Error ? error.message : String(error), 512)}`,
+        };
+    }
+}
+/** Check the local AGY executable without spending model quota or invoking tools. */
+export async function diagnoseAgy(options = {}) {
+    const executable = resolveAgyExecutable(options.executable);
+    const source = executableSource(options);
+    const runCommand = options.runCommand ?? runProcess;
+    const versionCheck = await runDiagnosticCommand('agy --version', executable, ['--version'], options.timeoutMs, runCommand);
+    const agentsCheck = await runDiagnosticCommand('agy agents', executable, ['agents'], options.timeoutMs, runCommand);
+    const versionOutput = versionCheck.result === undefined
+        ? ''
+        : versionCheck.result.stdoutLines.join('\n');
+    const version = parseAgyVersion(versionOutput);
+    const agentsOutput = agentsCheck.result === undefined
+        ? ''
+        : agentsCheck.result.stdoutLines.join('\n');
+    const agents = parseAgyAgents(agentsOutput);
+    const versionSupported = options.minimumVersion === undefined
+        ? version !== undefined
+        : version !== undefined && isAgyVersionAtLeast(version, options.minimumVersion);
+    const agentAvailable = options.expectedAgent === undefined || agents.includes(options.expectedAgent);
+    const errors = [
+        ...(versionCheck.error === undefined ? [] : [versionCheck.error]),
+        ...(agentsCheck.error === undefined ? [] : [agentsCheck.error]),
+        ...(version === undefined ? ['Unable to parse AGY version from --version output'] : []),
+        ...(options.minimumVersion !== undefined && !versionSupported
+            ? [`AGY version ${version ?? 'unknown'} is below the required minimum ${options.minimumVersion}`]
+            : []),
+        ...(options.expectedAgent !== undefined && !agentAvailable
+            ? [`AGY Agent "${redactText(options.expectedAgent, 128)}" was not found`] : []),
+    ];
+    return {
+        ok: errors.length === 0,
+        executable: source,
+        executableSource: source,
+        version,
+        agents,
+        expectedAgent: options.expectedAgent,
+        minimumVersion: options.minimumVersion,
+        versionSupported,
+        agentAvailable,
+        errors,
+    };
+}
+//# sourceMappingURL=diagnostics.js.map

package/lib/agy/errors.d.ts

@@ -0,0 +1,20 @@
+import { CONTEXT_WINDOW_EXCEEDED_CODE, QUOTA_EXCEEDED_CODE } from '@deepseek-ai/dsh-llm';
+/** Stable provider-neutral codes emitted after classifying AGY text/status details. */
+export type AgyClassifiedErrorCode = typeof CONTEXT_WINDOW_EXCEEDED_CODE | typeof QUOTA_EXCEEDED_CODE | 'AUTH' | 'RATE_LIMIT' | 'MODEL_NOT_FOUND' | 'AGY_AGENT_MISSING' | 'AGY_STATUS' | 'AGY_EXIT' | 'TRANSPORT';
+/**
+ * Classify observed AGY status/stderr/error-event detail. This is deliberately
+ * conservative: unknown text keeps the caller-supplied fallback code.
+ *
+ * Note the ordering is load-bearing for 429s. AGY emits
+ * `RESOURCE_EXHAUSTED (code 429)` for both a drained 5h/weekly bucket and a
+ * transient burst limit; only the drained form names a reset far in the future.
+ * The drained form is reported as RATE_LIMIT so the bounded retry in
+ * `dsh-llm-retry` can re-issue the turn — live probes showed the bucket sits on
+ * a boundary value where 1 in 5 attempts succeeds (probe_retry_efficacy.mjs:
+ * 5/5 rounds recovered, 2-3 attempts each), while a 92-96h reset means retrying
+ * beyond a few attempts is pure token burn.
+ */
+export declare function classifyAgyFailure(detail: string, fallback: string): string;
+/** Keep user-facing failure text bounded and redacted; structured logs use only the code. */
+export declare function safeAgyFailureMessage(prefix: string, detail: string | undefined): string;
+//# sourceMappingURL=errors.d.ts.map