@smithers-orchestrator/agents 0.16.0

package/src/agent-contract/createSmithersAgentContract.js

@@ -0,0 +1,188 @@
+import { renderSmithersAgentPromptGuidance } from "./renderSmithersAgentPromptGuidance.js";
+/** @typedef {import("./SmithersListedTool.ts").SmithersListedTool} SmithersListedTool */
+/** @typedef {import("./SmithersToolSurface.ts").SmithersToolSurface} SmithersToolSurface */
+/** @typedef {import("./SmithersAgentContractTool.ts").SmithersAgentContractTool} SmithersAgentContractTool */
+/** @typedef {import("./SmithersAgentToolCategory.ts").SmithersAgentToolCategory} SmithersAgentToolCategory */
+
+/**
+ * @typedef {{ toolSurface?: SmithersToolSurface; serverName?: string; tools: SmithersListedTool[]; }} CreateSmithersAgentContractOptions
+ */
+/** @typedef {import("./SmithersAgentContract.ts").SmithersAgentContract} SmithersAgentContract */
+
+const DEFAULT_SERVER_NAME = "smithers";
+const TOOL_CATEGORY_ORDER = [
+    "workflows",
+    "runs",
+    "approvals",
+    "debug",
+    "admin",
+];
+const WORKFLOW_TOOL_NAMES = new Set([
+    "graph",
+    "list_workflows",
+    "run_workflow",
+    "up",
+    "workflow_create",
+    "workflow_doctor",
+    "workflow_list",
+    "workflow_path",
+    "workflow_run",
+]);
+const APPROVAL_TOOL_NAMES = new Set([
+    "approve",
+    "deny",
+    "list_pending_approvals",
+    "resolve_approval",
+    "signal",
+]);
+const RUN_TOOL_NAMES = new Set([
+    "cancel",
+    "down",
+    "events",
+    "explain_run",
+    "get_run",
+    "inspect",
+    "list_runs",
+    "logs",
+    "ps",
+    "run_workflow",
+    "supervise",
+    "watch_run",
+    "why",
+]);
+const DEBUG_TOOL_NAMES = new Set([
+    "chat",
+    "diff",
+    "fork",
+    "get_artifacts",
+    "get_chat_transcript",
+    "get_node_detail",
+    "get_run_events",
+    "hijack",
+    "list_artifacts",
+    "node",
+    "openapi_list",
+    "rag_ingest",
+    "rag_query",
+    "replay",
+    "revert",
+    "revert_attempt",
+    "retry-task",
+    "scores",
+    "timeline",
+    "timetravel",
+]);
+const DESTRUCTIVE_TOOL_NAMES = new Set([
+    "approve",
+    "cancel",
+    "cron_add",
+    "cron_rm",
+    "cron_start",
+    "deny",
+    "down",
+    "fork",
+    "replay",
+    "resolve_approval",
+    "revert",
+    "revert_attempt",
+    "retry-task",
+    "run_workflow",
+    "signal",
+    "timetravel",
+    "up",
+    "workflow_create",
+    "workflow_run",
+]);
+/**
+ * @param {string | null | undefined} description
+ */
+function normalizeDescription(description) {
+    return (description ?? "")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/**
+ * @param {string} name
+ * @returns {SmithersAgentToolCategory}
+ */
+function inferCategory(name) {
+    if (WORKFLOW_TOOL_NAMES.has(name) || name.startsWith("workflow_")) {
+        return "workflows";
+    }
+    if (APPROVAL_TOOL_NAMES.has(name)) {
+        return "approvals";
+    }
+    if (RUN_TOOL_NAMES.has(name)) {
+        return "runs";
+    }
+    if (DEBUG_TOOL_NAMES.has(name)) {
+        return "debug";
+    }
+    if (name.startsWith("memory_") || name.startsWith("cron_")) {
+        return "admin";
+    }
+    return "admin";
+}
+/**
+ * @param {string} name
+ * @param {string} description
+ */
+function isDestructive(name, description) {
+    return (DESTRUCTIVE_TOOL_NAMES.has(name) ||
+        description.toLowerCase().startsWith("destructive:"));
+}
+/**
+ * @param {SmithersAgentContractTool[]} tools
+ */
+function sortTools(tools) {
+    return [...tools].sort((left, right) => {
+        const categoryDelta = TOOL_CATEGORY_ORDER.indexOf(left.category) -
+            TOOL_CATEGORY_ORDER.indexOf(right.category);
+        if (categoryDelta !== 0) {
+            return categoryDelta;
+        }
+        return left.name.localeCompare(right.name);
+    });
+}
+/**
+ * @param {SmithersAgentContract} contract
+ */
+function renderDocsGuidance(contract) {
+    const lines = [
+        `## Smithers ${contract.toolSurface} Tool Surface`,
+        "",
+        "| Tool | Category | Destructive | Description |",
+        "| --- | --- | --- | --- |",
+    ];
+    for (const tool of contract.tools) {
+        lines.push(`| \`${tool.name}\` | ${tool.category} | ${tool.destructive ? "yes" : "no"} | ${tool.description || "No description provided."} |`);
+    }
+    return lines.join("\n");
+}
+/**
+ * @param {CreateSmithersAgentContractOptions} options
+ * @returns {SmithersAgentContract}
+ */
+export function createSmithersAgentContract(options) {
+    const toolSurface = options.toolSurface ?? "semantic";
+    const serverName = options.serverName ?? DEFAULT_SERVER_NAME;
+    const tools = sortTools(options.tools.map((tool) => {
+        const description = normalizeDescription(tool.description);
+        return {
+            name: tool.name,
+            description,
+            destructive: isDestructive(tool.name, description),
+            category: inferCategory(tool.name),
+        };
+    }));
+    const contract = {
+        toolSurface,
+        serverName,
+        tools,
+        promptGuidance: "",
+        docsGuidance: "",
+    };
+    contract.promptGuidance = renderSmithersAgentPromptGuidance(contract);
+    contract.docsGuidance = renderDocsGuidance(contract);
+    return contract;
+}

package/src/agent-contract/index.js

@@ -0,0 +1,10 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./SmithersAgentContract.ts").SmithersAgentContract} SmithersAgentContract */
+/** @typedef {import("./SmithersAgentContractTool.ts").SmithersAgentContractTool} SmithersAgentContractTool */
+/** @typedef {import("./SmithersAgentToolCategory.ts").SmithersAgentToolCategory} SmithersAgentToolCategory */
+/** @typedef {import("./SmithersListedTool.ts").SmithersListedTool} SmithersListedTool */
+/** @typedef {import("./SmithersToolSurface.ts").SmithersToolSurface} SmithersToolSurface */
+// @smithers-type-exports-end
+
+export { renderSmithersAgentPromptGuidance } from "./renderSmithersAgentPromptGuidance.js";
+export { createSmithersAgentContract } from "./createSmithersAgentContract.js";

package/src/agent-contract/renderSmithersAgentPromptGuidance.js

@@ -0,0 +1,81 @@
+
+/** @typedef {import("./SmithersAgentContractTool.ts").SmithersAgentContractTool} SmithersAgentContractTool */
+/** @typedef {import("./SmithersAgentToolCategory.ts").SmithersAgentToolCategory} SmithersAgentToolCategory */
+
+/**
+ * @typedef {{ available?: boolean; toolNamePrefix?: string; }} RenderGuidanceOptions
+ */
+/** @typedef {import("./SmithersAgentContract.ts").SmithersAgentContract} SmithersAgentContract */
+const PROMPT_CATEGORY_ORDER = [
+    "workflows",
+    "runs",
+    "approvals",
+    "debug",
+];
+const CATEGORY_LABELS = {
+    workflows: "workflow discovery and launch",
+    runs: "run inspection and control",
+    approvals: "approval handling",
+    debug: "debugging and evidence gathering",
+    admin: "administration and maintenance",
+};
+const TOOL_CATEGORY_ORDER = [
+    "workflows",
+    "runs",
+    "approvals",
+    "debug",
+    "admin",
+];
+/**
+ * @param {Pick<SmithersAgentContractTool, "name">} tool
+ */
+function displayToolName(tool, prefix = "") {
+    return `\`${prefix}${tool.name}\``;
+}
+/**
+ * @param {SmithersAgentContractTool[]} tools
+ */
+function joinToolNames(tools, prefix = "") {
+    return tools.map((tool) => displayToolName(tool, prefix)).join(", ");
+}
+/**
+ * @param {SmithersAgentContractTool[]} tools
+ * @returns {Map<SmithersAgentToolCategory, SmithersAgentContractTool[]>}
+ */
+function groupToolsByCategory(tools) {
+    const grouped = new Map();
+    for (const category of TOOL_CATEGORY_ORDER) {
+        grouped.set(category, []);
+    }
+    for (const tool of tools) {
+        grouped.get(tool.category).push(tool);
+    }
+    return grouped;
+}
+/**
+ * @param {SmithersAgentContract} contract
+ * @param {RenderGuidanceOptions} [options]
+ */
+export function renderSmithersAgentPromptGuidance(contract, options = {}) {
+    const grouped = groupToolsByCategory(contract.tools);
+    const prefix = options.toolNamePrefix ?? "";
+    const available = options.available ?? true;
+    const lines = [
+        available
+            ? `You have access to the live Smithers ${contract.toolSurface} MCP surface on server "${contract.serverName}".`
+            : `The live Smithers ${contract.toolSurface} MCP contract for server "${contract.serverName}" is listed below, but MCP is disabled for this run.`,
+        "Only rely on the tool names listed here.",
+    ];
+    for (const category of PROMPT_CATEGORY_ORDER) {
+        const tools = grouped.get(category) ?? [];
+        if (tools.length === 0) {
+            continue;
+        }
+        lines.push(`For ${CATEGORY_LABELS[category]}, use ${joinToolNames(tools, prefix)}.`);
+    }
+    const destructiveTools = contract.tools.filter((tool) => tool.destructive);
+    if (destructiveTools.length > 0) {
+        lines.push(`Potentially destructive tools: ${joinToolNames(destructiveTools, prefix)}. Confirm intent before using them unless the user already asked for that action.`);
+    }
+    return lines.join("\n");
+}

package/src/capability-registry/AgentCapabilityRegistry.ts

@@ -0,0 +1,22 @@
+import type { AgentToolDescriptor } from "./AgentToolDescriptor";
+
+export type AgentCapabilityRegistry = {
+  version: 1;
+  engine: "claude-code" | "codex" | "gemini" | "kimi" | "pi" | "amp" | "forge";
+  runtimeTools: Record<string, AgentToolDescriptor>;
+  mcp: {
+    bootstrap: "inline-config" | "project-config" | "allow-list" | "unsupported";
+    supportsProjectScope: boolean;
+    supportsUserScope: boolean;
+  };
+  skills: {
+    supportsSkills: boolean;
+    installMode?: "files" | "dir" | "plugin";
+    smithersSkillIds: string[];
+  };
+  humanInteraction: {
+    supportsUiRequests: boolean;
+    methods: string[];
+  };
+  builtIns: string[];
+};

package/src/capability-registry/AgentToolDescriptor.ts

@@ -0,0 +1,4 @@
+export type AgentToolDescriptor = {
+  description?: string;
+  source?: "builtin" | "mcp" | "extension" | "skill" | "runtime";
+};

package/src/capability-registry/hashCapabilityRegistry.js

@@ -0,0 +1,43 @@
+import { createHash } from "node:crypto";
+import { normalizeCapabilityRegistry } from "./normalizeCapabilityRegistry.js";
+/** @typedef {import("./AgentCapabilityRegistry.ts").AgentCapabilityRegistry} AgentCapabilityRegistry */
+
+/**
+ * @param {unknown} value
+ * @returns {StableJson}
+ */
+function toStableJson(value) {
+    if (value === null ||
+        typeof value === "boolean" ||
+        typeof value === "number" ||
+        typeof value === "string") {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => toStableJson(entry));
+    }
+    if (!value || typeof value !== "object") {
+        return String(value);
+    }
+    return Object.fromEntries(Object.entries(value)
+        .filter(([, entry]) => entry !== undefined)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, entry]) => [key, toStableJson(entry)]));
+}
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function stableStringify(value) {
+    return JSON.stringify(toStableJson(value));
+}
+/**
+ * @param {AgentCapabilityRegistry | null | undefined} registry
+ * @returns {string}
+ */
+export function hashCapabilityRegistry(registry) {
+    const input = stableStringify({
+        capabilityRegistry: normalizeCapabilityRegistry(registry),
+    });
+    return createHash("sha256").update(input).digest("hex");
+}

package/src/capability-registry/index.js

@@ -0,0 +1,8 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./AgentCapabilityRegistry.ts").AgentCapabilityRegistry} AgentCapabilityRegistry */
+/** @typedef {import("./AgentToolDescriptor.ts").AgentToolDescriptor} AgentToolDescriptor */
+// @smithers-type-exports-end
+
+export { normalizeCapabilityStringList } from "./normalizeCapabilityStringList.js";
+export { normalizeCapabilityRegistry } from "./normalizeCapabilityRegistry.js";
+export { hashCapabilityRegistry } from "./hashCapabilityRegistry.js";

package/src/capability-registry/normalizeCapabilityRegistry.js

@@ -0,0 +1,52 @@
+import { normalizeCapabilityStringList } from "./normalizeCapabilityStringList.js";
+/** @typedef {import("./AgentToolDescriptor.ts").AgentToolDescriptor} AgentToolDescriptor */
+
+/** @typedef {import("./AgentCapabilityRegistry.ts").AgentCapabilityRegistry} AgentCapabilityRegistry */
+
+/**
+ * @param {AgentToolDescriptor | null | undefined} descriptor
+ * @returns {AgentToolDescriptor}
+ */
+function normalizeToolDescriptor(descriptor) {
+    return {
+        description: descriptor?.description?.trim() || undefined,
+        source: descriptor?.source,
+    };
+}
+/**
+ * @param {AgentCapabilityRegistry | null | undefined} registry
+ * @returns {AgentCapabilityRegistry | null}
+ */
+export function normalizeCapabilityRegistry(registry) {
+    if (!registry) {
+        return null;
+    }
+    const runtimeTools = Object.fromEntries(Object.entries(registry.runtimeTools ?? {})
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([name, descriptor]) => [name, normalizeToolDescriptor(descriptor)]));
+    return {
+        version: 1,
+        engine: registry.engine,
+        runtimeTools,
+        mcp: {
+            bootstrap: registry.mcp.bootstrap,
+            supportsProjectScope: registry.mcp.supportsProjectScope,
+            supportsUserScope: registry.mcp.supportsUserScope,
+        },
+        skills: registry.skills.supportsSkills
+            ? {
+                supportsSkills: true,
+                installMode: registry.skills.installMode,
+                smithersSkillIds: normalizeCapabilityStringList(registry.skills.smithersSkillIds),
+            }
+            : {
+                supportsSkills: false,
+                smithersSkillIds: normalizeCapabilityStringList(registry.skills.smithersSkillIds),
+            },
+        humanInteraction: {
+            supportsUiRequests: registry.humanInteraction.supportsUiRequests,
+            methods: normalizeCapabilityStringList(registry.humanInteraction.methods),
+        },
+        builtIns: normalizeCapabilityStringList(registry.builtIns),
+    };
+}

package/src/capability-registry/normalizeCapabilityStringList.js

@@ -0,0 +1,9 @@
+/**
+ * @param {readonly string[] | null | undefined} values
+ * @returns {string[]}
+ */
+export function normalizeCapabilityStringList(values) {
+    return [...new Set((values ?? [])
+            .map((value) => value.trim())
+            .filter(Boolean))].sort((left, right) => left.localeCompare(right));
+}

package/src/cli-capabilities/CliAgentCapabilityAdapterId.ts

@@ -0,0 +1,6 @@
+export type CliAgentCapabilityAdapterId =
+  | "claude"
+  | "codex"
+  | "gemini"
+  | "kimi"
+  | "pi";

package/src/cli-capabilities/CliAgentCapabilityDoctorReport.ts

@@ -0,0 +1,18 @@
+import type { CliAgentCapabilityReportEntry } from "./CliAgentCapabilityReportEntry";
+
+export type CliAgentCapabilityIssue = {
+  code: string;
+  message: string;
+  severity: "error" | "warning";
+};
+
+export type CliAgentCapabilityDoctorEntry = CliAgentCapabilityReportEntry & {
+  ok: boolean;
+  issues: CliAgentCapabilityIssue[];
+};
+
+export type CliAgentCapabilityDoctorReport = {
+  ok: boolean;
+  issueCount: number;
+  agents: CliAgentCapabilityDoctorEntry[];
+};

package/src/cli-capabilities/CliAgentCapabilityReportEntry.ts

@@ -0,0 +1,9 @@
+import type { AgentCapabilityRegistry } from "../capability-registry";
+import type { CliAgentCapabilityAdapterId } from "./CliAgentCapabilityAdapterId";
+
+export type CliAgentCapabilityReportEntry = {
+  id: CliAgentCapabilityAdapterId;
+  binary: string;
+  fingerprint: string;
+  capabilities: AgentCapabilityRegistry;
+};

package/src/cli-capabilities/formatCliAgentCapabilityDoctorReport.js

@@ -0,0 +1,24 @@
+
+/** @typedef {import("./CliAgentCapabilityDoctorReport.ts").CliAgentCapabilityDoctorReport} CliAgentCapabilityDoctorReport */
+/**
+ * @param {CliAgentCapabilityDoctorReport} report
+ * @returns {string}
+ */
+export function formatCliAgentCapabilityDoctorReport(report) {
+    if (report.ok) {
+        return `All ${report.agents.length} built-in CLI agent capability registries passed.`;
+    }
+    const lines = [
+        `Capability issues found: ${report.issueCount}`,
+    ];
+    for (const agent of report.agents) {
+        if (agent.issues.length === 0) {
+            continue;
+        }
+        lines.push(`${agent.id} (${agent.capabilities.engine})`);
+        for (const issue of agent.issues) {
+            lines.push(`  - [${issue.severity}] ${issue.code}: ${issue.message}`);
+        }
+    }
+    return lines.join("\n");
+}

package/src/cli-capabilities/getCliAgentCapabilityDoctorReport.js

@@ -0,0 +1,92 @@
+import { getCliAgentCapabilityReport } from "./getCliAgentCapabilityReport.js";
+/** @typedef {import("./CliAgentCapabilityDoctorReport.ts").CliAgentCapabilityDoctorReport} CliAgentCapabilityDoctorReport */
+
+/**
+ * @param {AgentCapabilityRegistry} registry
+ * @returns {CliAgentCapabilityIssue[]}
+ */
+function diagnoseCapabilityRegistry(registry) {
+    const issues = [];
+    if (registry.version !== 1) {
+        issues.push({
+            code: "registry-version",
+            message: `Expected capability registry version 1, received ${registry.version}.`,
+            severity: "error",
+        });
+    }
+    if (!registry.skills.supportsSkills) {
+        if (registry.skills.installMode) {
+            issues.push({
+                code: "skills-install-mode-without-support",
+                message: "Skills install mode is set even though the adapter declares no skills support.",
+                severity: "error",
+            });
+        }
+        if (registry.skills.smithersSkillIds.length > 0) {
+            issues.push({
+                code: "skills-listed-without-support",
+                message: "Smithers skills are listed even though the adapter declares no skills support.",
+                severity: "error",
+            });
+        }
+    }
+    else if (!registry.skills.installMode) {
+        issues.push({
+            code: "missing-skills-install-mode",
+            message: "Adapters that support skills must declare an install mode.",
+            severity: "error",
+        });
+    }
+    if (!registry.humanInteraction.supportsUiRequests) {
+        if (registry.humanInteraction.methods.length > 0) {
+            issues.push({
+                code: "ui-methods-without-support",
+                message: "UI request methods are listed even though the adapter declares no UI request support.",
+                severity: "error",
+            });
+        }
+    }
+    else if (registry.humanInteraction.methods.length === 0) {
+        issues.push({
+            code: "missing-ui-methods",
+            message: "Adapters that support UI requests must declare at least one method.",
+            severity: "error",
+        });
+    }
+    if (registry.mcp.bootstrap === "unsupported") {
+        if (registry.mcp.supportsProjectScope || registry.mcp.supportsUserScope) {
+            issues.push({
+                code: "unsupported-mcp-with-scope",
+                message: "Unsupported MCP adapters cannot advertise project or user scope support.",
+                severity: "error",
+            });
+        }
+    }
+    else if (!registry.mcp.supportsProjectScope && !registry.mcp.supportsUserScope) {
+        issues.push({
+            code: "mcp-bootstrap-without-scope",
+            message: "Supported MCP adapters should advertise at least one supported scope.",
+            severity: "warning",
+        });
+    }
+    return issues;
+}
+/**
+ * @returns {CliAgentCapabilityDoctorReport}
+ */
+export function getCliAgentCapabilityDoctorReport() {
+    const agents = getCliAgentCapabilityReport().map((entry) => {
+        const issues = diagnoseCapabilityRegistry(entry.capabilities);
+        return {
+            ...entry,
+            ok: issues.length === 0,
+            issues,
+        };
+    });
+    const issueCount = agents.reduce((count, entry) => count + entry.issues.length, 0);
+    return {
+        ok: issueCount === 0,
+        issueCount,
+        agents,
+    };
+}

package/src/cli-capabilities/getCliAgentCapabilityReport.js

@@ -0,0 +1,52 @@
+import { hashCapabilityRegistry, normalizeCapabilityRegistry, } from "../capability-registry/index.js";
+import { createClaudeCodeCapabilityRegistry } from "../ClaudeCodeAgent.js";
+import { createCodexCapabilityRegistry } from "../CodexAgent.js";
+import { createGeminiCapabilityRegistry } from "../GeminiAgent.js";
+import { createKimiCapabilityRegistry } from "../KimiAgent.js";
+import { createPiCapabilityRegistry } from "../PiAgent.js";
+/** @typedef {import("./CliAgentCapabilityReportEntry.ts").CliAgentCapabilityReportEntry} CliAgentCapabilityReportEntry */
+
+const CLI_AGENT_CAPABILITY_ADAPTERS = [
+    {
+        id: "claude",
+        binary: "claude",
+        buildRegistry: () => createClaudeCodeCapabilityRegistry(),
+    },
+    {
+        id: "codex",
+        binary: "codex",
+        buildRegistry: () => createCodexCapabilityRegistry(),
+    },
+    {
+        id: "gemini",
+        binary: "gemini",
+        buildRegistry: () => createGeminiCapabilityRegistry(),
+    },
+    {
+        id: "kimi",
+        binary: "kimi",
+        buildRegistry: () => createKimiCapabilityRegistry(),
+    },
+    {
+        id: "pi",
+        binary: "pi",
+        buildRegistry: () => createPiCapabilityRegistry(),
+    },
+];
+/**
+ * @returns {CliAgentCapabilityReportEntry[]}
+ */
+export function getCliAgentCapabilityReport() {
+    return CLI_AGENT_CAPABILITY_ADAPTERS.map((adapter) => {
+        const capabilities = normalizeCapabilityRegistry(adapter.buildRegistry());
+        if (!capabilities) {
+            throw new Error(`Capability registry missing for adapter ${adapter.id}`);
+        }
+        return {
+            id: adapter.id,
+            binary: adapter.binary,
+            fingerprint: hashCapabilityRegistry(capabilities),
+            capabilities,
+        };
+    });
+}

package/src/cli-capabilities/index.js

@@ -0,0 +1,11 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./CliAgentCapabilityAdapterId.ts").CliAgentCapabilityAdapterId} CliAgentCapabilityAdapterId */
+/** @typedef {import("./CliAgentCapabilityDoctorReport.ts").CliAgentCapabilityDoctorEntry} CliAgentCapabilityDoctorEntry */
+/** @typedef {import("./CliAgentCapabilityDoctorReport.ts").CliAgentCapabilityDoctorReport} CliAgentCapabilityDoctorReport */
+/** @typedef {import("./CliAgentCapabilityDoctorReport.ts").CliAgentCapabilityIssue} CliAgentCapabilityIssue */
+/** @typedef {import("./CliAgentCapabilityReportEntry.ts").CliAgentCapabilityReportEntry} CliAgentCapabilityReportEntry */
+// @smithers-type-exports-end
+
+export { getCliAgentCapabilityReport } from "./getCliAgentCapabilityReport.js";
+export { getCliAgentCapabilityDoctorReport } from "./getCliAgentCapabilityDoctorReport.js";
+export { formatCliAgentCapabilityDoctorReport } from "./formatCliAgentCapabilityDoctorReport.js";

package/src/diagnostics/DiagnosticCheck.ts

@@ -0,0 +1,11 @@
+import type { DiagnosticCheckId } from "./DiagnosticCheckId";
+
+export type DiagnosticCheckStatus = "pass" | "fail" | "skip" | "error";
+
+export type DiagnosticCheck = {
+  id: DiagnosticCheckId;
+  status: DiagnosticCheckStatus;
+  message: string;
+  detail?: Record<string, unknown>;
+  durationMs: number;
+};

package/src/diagnostics/DiagnosticCheckId.ts

@@ -0,0 +1,4 @@
+export type DiagnosticCheckId =
+  | "cli_installed"
+  | "api_key_valid"
+  | "rate_limit_status";

package/src/diagnostics/DiagnosticContext.ts

@@ -0,0 +1,4 @@
+export type DiagnosticContext = {
+  env: Record<string, string>;
+  cwd: string;
+};