ai-discovery-manager-cli 0.1.0

package/dist/doctor.js

@@ -0,0 +1,148 @@
+import { MCPServerStdio } from "@openai/agents";
+import { access, stat } from "node:fs/promises";
+import { constants } from "node:fs";
+import path from "node:path";
+import { MODEL_IDS, resolveModel } from "./models.js";
+import { parseSafetyLevel } from "./safety.js";
+function overallStatus(checks) {
+    if (checks.some((check) => check.status === "error")) {
+        return "error";
+    }
+    if (checks.some((check) => check.status === "warn")) {
+        return "warn";
+    }
+    return "ok";
+}
+function redactedApiKey(value) {
+    if (!value) {
+        return undefined;
+    }
+    if (value.length <= 8) {
+        return "set";
+    }
+    return `${value.slice(0, 3)}...${value.slice(-4)}`;
+}
+export async function runDoctor(options) {
+    const checks = [];
+    const nodeMajor = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
+    checks.push({
+        name: "node",
+        status: nodeMajor >= 22 ? "ok" : "error",
+        message: nodeMajor >= 22
+            ? `Node ${process.versions.node} satisfies >=22.`
+            : `Node ${process.versions.node} is below the required >=22.`,
+    });
+    const apiKey = process.env.OPENAI_API_KEY;
+    checks.push({
+        name: "apiKey",
+        status: apiKey ? "ok" : "warn",
+        message: apiKey
+            ? "OPENAI_API_KEY is configured."
+            : "OPENAI_API_KEY is not set; non-dry-run commands will fail before API access.",
+        details: apiKey ? { value: redactedApiKey(apiKey) } : undefined,
+    });
+    const workspaceInfo = await stat(options.workspace).catch(() => undefined);
+    checks.push({
+        name: "workspace",
+        status: workspaceInfo?.isDirectory() ? "ok" : "error",
+        message: workspaceInfo?.isDirectory()
+            ? `Workspace exists: ${options.workspace}`
+            : `Workspace does not exist or is not a directory: ${options.workspace}`,
+    });
+    if (workspaceInfo?.isDirectory()) {
+        const writable = await access(options.workspace, constants.W_OK)
+            .then(() => true)
+            .catch(() => false);
+        checks.push({
+            name: "workspaceWritable",
+            status: writable ? "ok" : "warn",
+            message: writable
+                ? "Workspace is writable for artifacts and checkpoints."
+                : "Workspace may not be writable; artifact or checkpoint writes can fail.",
+            details: { checkpointRoot: path.join(options.workspace, ".ai-discovery", "runs") },
+        });
+    }
+    try {
+        resolveModel(options.model, "--model");
+        resolveModel(options.managerModel, "--manager-model");
+        resolveModel(options.specialistModel, "--specialist-model");
+        checks.push({
+            name: "models",
+            status: "ok",
+            message: "Configured models are in the text-only allowlist.",
+            details: {
+                model: options.model,
+                managerModel: options.managerModel,
+                specialistModel: options.specialistModel,
+                availableModels: MODEL_IDS,
+            },
+        });
+    }
+    catch (error) {
+        checks.push({
+            name: "models",
+            status: "error",
+            message: error instanceof Error ? error.message : String(error),
+            details: { availableModels: MODEL_IDS },
+        });
+    }
+    try {
+        parseSafetyLevel(String(options.safetyLevel));
+        checks.push({
+            name: "safetyLevel",
+            status: "ok",
+            message: `Safety level ${options.safetyLevel} is valid.`,
+        });
+    }
+    catch (error) {
+        checks.push({
+            name: "safetyLevel",
+            status: "error",
+            message: error instanceof Error ? error.message : String(error),
+        });
+    }
+    const malformedVectorStores = options.vectorStoreIds.filter((id) => !/^vs_[A-Za-z0-9_-]+$/.test(id));
+    checks.push({
+        name: "vectorStores",
+        status: malformedVectorStores.length === 0 ? "ok" : "warn",
+        message: malformedVectorStores.length === 0
+            ? options.vectorStoreIds.length > 0
+                ? "Vector store IDs are syntactically plausible."
+                : "No vector store IDs configured; File Search will stay disabled."
+            : "Some vector store IDs do not look like OpenAI vector store IDs.",
+        details: options.vectorStoreIds.length > 0
+            ? {
+                count: options.vectorStoreIds.length,
+                malformed: malformedVectorStores,
+            }
+            : undefined,
+    });
+    checks.push({
+        name: "mcp",
+        status: typeof MCPServerStdio === "function" ? "ok" : "error",
+        message: typeof MCPServerStdio === "function"
+            ? "Agents SDK MCPServerStdio is available for chat /mcp connections."
+            : "Agents SDK MCPServerStdio is not available.",
+    });
+    const distCli = await stat(path.resolve(process.cwd(), "dist", "cli.js")).catch(() => undefined);
+    checks.push({
+        name: "dist",
+        status: distCli?.isFile() ? "ok" : "warn",
+        message: distCli?.isFile()
+            ? "Built dist/cli.js exists."
+            : "dist/cli.js is missing; run `npm.cmd run build` before package/bin use.",
+    });
+    return {
+        status: overallStatus(checks),
+        checks,
+        availableModels: MODEL_IDS,
+        workspace: options.workspace,
+    };
+}
+export function formatDoctorReport(report) {
+    const lines = [`AI Discovery doctor: ${report.status.toUpperCase()}`];
+    for (const check of report.checks) {
+        lines.push(`[${check.status}] ${check.name}: ${check.message}`);
+    }
+    return lines.join("\n");
+}

package/dist/hypothesisSchema.js

@@ -0,0 +1,106 @@
+export const HYPOTHESIS_OUTPUT_SCHEMA = `title: Short descriptive name
+
+research_question: >
+  What question is this hypothesis trying to answer?
+
+hypothesis_statement: >
+  If X is true or if we intervene on X, then Y should happen because of mechanism Z.
+
+domain:
+  field: biology / chemistry / medicine / physics / AI / etc.
+  system: organism, model, dataset, material, algorithm, etc.
+
+background_evidence:
+  supporting_evidence:
+    - claim:
+      source:
+      strength: weak / moderate / strong
+  conflicting_evidence:
+    - claim:
+      source:
+      strength: weak / moderate / strong
+
+mechanism:
+  proposed_causal_chain:
+    - Step 1
+    - Step 2
+    - Step 3
+  key_assumptions:
+    - Assumption 1
+    - Assumption 2
+
+predictions:
+  primary_prediction: >
+    What should be observed if the hypothesis is correct?
+  secondary_predictions:
+    - Additional expected outcome
+    - Another expected outcome
+  falsifying_observation: >
+    What result would make the hypothesis unlikely?
+
+test_plan:
+  experiment_or_analysis: >
+    How would this be tested?
+  required_data:
+    - Dataset, measurement, simulation, or experiment needed
+  controls:
+    positive_control:
+    negative_control:
+  comparison_baseline:
+  success_criteria:
+
+confounders_and_alternatives:
+  possible_confounders:
+    - Confounder 1
+    - Confounder 2
+  alternative_explanations:
+    - Alternative mechanism 1
+    - Alternative mechanism 2
+
+feasibility:
+  required_resources:
+    - Data
+    - Tools
+    - Expertise
+  estimated_cost: low / medium / high
+  estimated_time: short / medium / long
+  risk_level: low / medium / high
+
+evaluation:
+  novelty: 1-5
+  plausibility: 1-5
+  testability: 1-5
+  impact: 1-5
+  feasibility: 1-5
+  overall_priority: 1-5
+
+uncertainty:
+  confidence_score: 0.0-1.0
+  main_uncertainty: >
+    What is the biggest thing we do not know?
+
+status:
+  state: proposed / under_review / testing / supported / weakened / rejected
+  last_updated:`;
+export const HYPOTHESIS_SCHEMA_INSTRUCTIONS = [
+    "The final answer must be only a YAML document matching this schema exactly, with the keys in this order. Do not wrap it in Markdown fences, and do not add commentary, summaries, citations sections, or extra fields outside the schema.",
+    "",
+    HYPOTHESIS_OUTPUT_SCHEMA,
+    "",
+    "Field requirements:",
+    "- Fill every top-level key in the schema, preserving nested key names and order.",
+    "- Use the enum values shown in the schema for evidence strength, cost, time, risk, and status state.",
+    "- Score novelty, plausibility, testability, impact, feasibility, and overall_priority as integers from 1 to 5.",
+    "- Score confidence_score as a decimal from 0.0 to 1.0.",
+    "- For last_updated, use an ISO date (YYYY-MM-DD) when the run date is known; otherwise leave the value empty.",
+    "- Keep the hypothesis causal and falsifiable: make the X, Y, and mechanism Z relationship explicit.",
+    "- Include supporting and conflicting evidence at the claim level. Each evidence item must include a source when verified; do not invent citations, URLs, DOIs, authors, or papers.",
+    "- If evidence cannot be verified with available tools, mark the source as unverified or unavailable and lower the evidence strength accordingly.",
+    "- Include at least one falsifying observation, at least one plausible confounder, and at least one alternative explanation.",
+    "- Keep experiments and analyses safe, non-harmful, and appropriate for computational, observational, or review settings unless the user has supplied an approved real-world protocol context.",
+    "",
+    "Scientific safety and validity:",
+    "- Treat biological, chemical, medical, and physical-world domains as safety-sensitive. Do not provide procedural wet-lab, clinical, chemical synthesis, or harmful operational instructions.",
+    "- Preserve units, assumptions, provenance, uncertainty, and limitations where they affect the hypothesis or test plan.",
+    "- Prefer bounded, reproducible, source-grounded analysis over speculative claims.",
+].join("\n");

package/dist/jsonOutput.js

@@ -0,0 +1,65 @@
+export function emitJsonEvent(type, payload = {}) {
+    process.stdout.write(`${JSON.stringify({
+        type,
+        timestamp: new Date().toISOString(),
+        ...payload,
+    })}\n`);
+}
+export function serializeError(error) {
+    if (error instanceof Error) {
+        return {
+            message: error.message,
+            name: error.name,
+            stack: process.env.AI_DISCOVERY_DEBUG ? error.stack : undefined,
+        };
+    }
+    return { message: String(error) };
+}
+export function serializeUsage(usage) {
+    if (!usage) {
+        return undefined;
+    }
+    return {
+        requests: usage.requests,
+        inputTokens: usage.inputTokens,
+        outputTokens: usage.outputTokens,
+        totalTokens: usage.totalTokens,
+        inputTokensDetails: usage.inputTokensDetails.length > 0 ? usage.inputTokensDetails : undefined,
+        outputTokensDetails: usage.outputTokensDetails.length > 0
+            ? usage.outputTokensDetails
+            : undefined,
+        requestUsageEntries: usage.requestUsageEntries?.map((entry) => ({
+            endpoint: entry.endpoint,
+            inputTokens: entry.inputTokens,
+            outputTokens: entry.outputTokens,
+            totalTokens: entry.totalTokens,
+        })),
+    };
+}
+export function extractTraceId(result) {
+    const state = result.state;
+    return state?._trace?.traceId;
+}
+export function extractCitations(text) {
+    const urls = new Set();
+    const dois = new Set();
+    for (const match of text.matchAll(/\bhttps?:\/\/[^\s)<>"']+/g)) {
+        urls.add(match[0].replace(/[.,;:]+$/g, ""));
+    }
+    for (const match of text.matchAll(/\b10\.\d{4,9}\/[-._;()/:A-Z0-9]+/gi)) {
+        dois.add(match[0].replace(/[.,;:]+$/g, ""));
+    }
+    return {
+        urls: [...urls],
+        dois: [...dois],
+    };
+}
+export function tokenCostStats(usage) {
+    return {
+        currency: "USD",
+        amount: null,
+        note: usage
+            ? "Model-specific pricing is not bundled; use token usage for external cost calculation."
+            : "Usage was not reported by the SDK for this run.",
+    };
+}

package/dist/mcpManager.js

@@ -0,0 +1,196 @@
+import { MCPServerStdio, getAllMcpTools, } from "@openai/agents";
+export class SessionMcpManager {
+    servers = new Map();
+    has(name) {
+        return this.servers.has(name);
+    }
+    list() {
+        return [...this.servers.values()];
+    }
+    get size() {
+        return this.servers.size;
+    }
+    /** Connect a new stdio MCP server and register it for the session. */
+    async connect(spec) {
+        if (this.servers.has(spec.name)) {
+            throw new Error(`An MCP server named "${spec.name}" is already connected. Disconnect it first.`);
+        }
+        const server = new MCPServerStdio({
+            name: spec.name,
+            command: spec.command,
+            args: spec.args,
+            cwd: spec.cwd,
+            env: Object.keys(spec.env).length > 0 ? spec.env : undefined,
+            // Tools rarely change within a session; cache to avoid re-listing on
+            // every turn. The cache is dropped when the server disconnects.
+            cacheToolsList: true,
+        });
+        await server.connect();
+        const record = {
+            name: spec.name,
+            command: spec.command,
+            args: spec.args,
+            cwd: spec.cwd,
+            envKeys: spec.envKeys,
+            server,
+        };
+        this.servers.set(spec.name, record);
+        return record;
+    }
+    /** Disconnect and forget a single server. */
+    async disconnect(name) {
+        const record = this.servers.get(name);
+        if (!record) {
+            throw new Error(`No MCP server named "${name}" is connected.`);
+        }
+        this.servers.delete(name);
+        await record.server.close().catch(() => undefined);
+    }
+    /** List the tools published by one server (or throw if unknown). */
+    async toolsFor(name) {
+        const record = this.servers.get(name);
+        if (!record) {
+            throw new Error(`No MCP server named "${name}" is connected.`);
+        }
+        const tools = await record.server.listTools();
+        return tools.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+        }));
+    }
+    /**
+     * Build the agent-facing tool list across all connected servers, with
+     * server-name prefixes to prevent collisions. Returns an empty array when no
+     * servers are connected.
+     */
+    async agentTools() {
+        const mcpServers = this.list().map((record) => record.server);
+        if (mcpServers.length === 0) {
+            return [];
+        }
+        return getAllMcpTools({
+            mcpServers,
+            includeServerInToolNames: true,
+        });
+    }
+    /** Close every server (best-effort) and clear the registry. */
+    async closeAll() {
+        const records = this.list();
+        this.servers.clear();
+        await Promise.all(records.map((record) => record.server.close().catch(() => undefined)));
+    }
+}
+/** Split a command line into tokens, honoring simple single/double quoting. */
+export function tokenizeMcpArgs(input) {
+    const tokens = [];
+    const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
+    let match;
+    while ((match = re.exec(input)) !== null) {
+        tokens.push(match[1] ?? match[2] ?? match[3] ?? "");
+    }
+    return tokens;
+}
+/**
+ * Parse the tokens that follow `/mcp connect`:
+ *   <name> [--cwd <path>] [--env KEY=value | --env KEY]... -- <command> [args...]
+ *
+ * For `--env KEY` (no `=`), the value is read from the parent process env at
+ * parse time. Values are placed into `env` for the child process but only the
+ * key names are recorded in `envKeys` for later display.
+ */
+export function parseMcpConnect(tokens) {
+    if (tokens.length === 0) {
+        throw new Error("Usage: /mcp connect <name> [--cwd <path>] [--env KEY=value | --env KEY]... -- <command> [args...]");
+    }
+    const [name, ...rest] = tokens;
+    if (name.startsWith("--")) {
+        throw new Error("MCP server name must come first, before any flags.");
+    }
+    const env = {};
+    const envKeys = [];
+    let cwd;
+    let index = 0;
+    for (; index < rest.length; index += 1) {
+        const token = rest[index];
+        if (token === "--") {
+            index += 1;
+            break;
+        }
+        if (token === "--cwd") {
+            const value = rest[index + 1];
+            if (value === undefined || value === "--") {
+                throw new Error("--cwd requires a path value.");
+            }
+            cwd = value;
+            index += 1;
+            continue;
+        }
+        if (token === "--env") {
+            const value = rest[index + 1];
+            if (value === undefined || value === "--") {
+                throw new Error("--env requires KEY=value or KEY.");
+            }
+            const eq = value.indexOf("=");
+            if (eq >= 0) {
+                const key = value.slice(0, eq);
+                if (!key) {
+                    throw new Error(`Invalid --env entry "${value}".`);
+                }
+                env[key] = value.slice(eq + 1);
+                if (!envKeys.includes(key))
+                    envKeys.push(key);
+            }
+            else {
+                const key = value;
+                const fromParent = process.env[key];
+                if (fromParent !== undefined) {
+                    env[key] = fromParent;
+                }
+                if (!envKeys.includes(key))
+                    envKeys.push(key);
+            }
+            index += 1;
+            continue;
+        }
+        throw new Error(`Unknown /mcp connect flag "${token}". Put the command after a "--" separator.`);
+    }
+    const command = rest[index];
+    if (!command) {
+        throw new Error('No MCP command provided. Place it after "--", e.g. /mcp connect docs -- npx -y my-mcp-server.');
+    }
+    const args = rest.slice(index + 1);
+    return { name, command, args, cwd, env, envKeys };
+}
+export const MCP_HELP = [
+    "MCP (session-only stdio servers):",
+    "  /mcp connect <name> [--cwd <path>] [--env KEY=value | --env KEY]... -- <command> [args...]",
+    "                     Start and attach a stdio MCP server for this session.",
+    "                     --env KEY (no value) forwards KEY from the current env.",
+    "                     Env values are never printed or saved; only key names are shown.",
+    "  /mcp status        List connected servers (command, args, cwd, env key names).",
+    "  /mcp tools [name]  List tools for one server, or all connected servers.",
+    "  /mcp disconnect <name>",
+    "                     Stop and detach a server.",
+    "  /mcp help          Show this help.",
+    "",
+    "MCP tools are exposed to the assistant prefixed by server name to avoid collisions.",
+    "Configs are session-only: nothing is persisted to disk.",
+].join("\n");
+/** Render `/mcp status` text for the current set of connected servers. */
+export function formatMcpStatus(records) {
+    if (records.length === 0) {
+        return "No MCP servers connected. Use `/mcp connect ...` (see `/mcp help`).";
+    }
+    const lines = [`Connected MCP servers (${records.length}):`];
+    for (const record of records) {
+        const cmd = [record.command, ...record.args].join(" ");
+        lines.push(`  - ${record.name}: ${cmd}`);
+        if (record.cwd) {
+            lines.push(`      cwd: ${record.cwd}`);
+        }
+        if (record.envKeys.length > 0) {
+            lines.push(`      env keys: ${record.envKeys.join(", ")} (values hidden)`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/models.js

@@ -0,0 +1,117 @@
+/**
+ * Text-only model allowlist for AI Discovery.
+ *
+ * The CLI and chat deliberately accept only this curated set of OpenAI text
+ * models. Image, audio, realtime, and embedding models are intentionally
+ * excluded — every workflow here produces or reasons over text artifacts, so a
+ * narrow allowlist keeps `--model`, `--manager-model`, `--specialist-model`, and
+ * the chat `/model` command from silently routing to an unsupported endpoint.
+ */
+/**
+ * The complete, ordered catalog of allowed text models. Order is used for the
+ * numbered `/model <n>` chat shortcut and the `/models` listing.
+ */
+export const MODEL_CATALOG = [
+    {
+        id: "gpt-5.5",
+        label: "GPT-5.5",
+        description: "Flagship text reasoning model. Default.",
+    },
+    {
+        id: "gpt-5.5-pro",
+        label: "GPT-5.5 Pro",
+        description: "Highest-effort GPT-5.5 variant for the hardest reasoning.",
+    },
+    {
+        id: "gpt-5.4",
+        label: "GPT-5.4",
+        description: "Previous-generation flagship text model.",
+    },
+    {
+        id: "gpt-5.4-pro",
+        label: "GPT-5.4 Pro",
+        description: "Highest-effort GPT-5.4 variant.",
+    },
+    {
+        id: "gpt-5.4-mini",
+        label: "GPT-5.4 mini",
+        description: "Faster, cheaper GPT-5.4 for lighter tasks.",
+    },
+    {
+        id: "gpt-5.4-nano",
+        label: "GPT-5.4 nano",
+        description: "Smallest, fastest GPT-5.4 for simple tasks.",
+    },
+];
+/** Canonical IDs in catalog order. */
+export const MODEL_IDS = MODEL_CATALOG.map((m) => m.id);
+const CANONICAL_BY_ID = new Map(MODEL_CATALOG.map((m) => [m.id, m]));
+/**
+ * Reduce a user-supplied model string to a comparable canonical key.
+ *
+ * Handles common display aliases such as `GPT-5.5 Pro`, `GPT 5.4 mini`, and
+ * `gpt_5.4_nano` by lowercasing, collapsing whitespace/underscores to single
+ * hyphens, and inserting the hyphen in a bare `gpt5.5` form. The result is only
+ * a lookup key; it is not assumed to be a valid model on its own.
+ */
+function canonicalizeKey(input) {
+    return input
+        .trim()
+        .toLowerCase()
+        .replace(/[\s_]+/g, "-")
+        .replace(/^gpt(?=\d)/, "gpt-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+/**
+ * Resolve an arbitrary model string to a canonical catalog ID, or `undefined`
+ * if it is not an allowed text model.
+ */
+export function normalizeModel(input) {
+    const key = canonicalizeKey(input);
+    return CANONICAL_BY_ID.has(key) ? key : undefined;
+}
+/**
+ * Resolve a model string to a canonical catalog ID or throw a descriptive
+ * error listing the allowed models. Used by every model-accepting input
+ * (`--model`, `--manager-model`, `--specialist-model`, `OPENAI_MODEL`, and the
+ * chat `/model` command).
+ */
+export function resolveModel(input, source = "model") {
+    const resolved = normalizeModel(input);
+    if (!resolved) {
+        throw new Error(`Unknown ${source} "${input}". Allowed text models: ${MODEL_IDS.join(", ")}.`);
+    }
+    return resolved;
+}
+/** Look up display metadata for a canonical model ID. */
+export function modelInfo(id) {
+    return CANONICAL_BY_ID.get(id);
+}
+/** Pretty label for a model ID, falling back to the raw ID. */
+export function modelLabel(id) {
+    return CANONICAL_BY_ID.get(id)?.label ?? id;
+}
+/** Multi-line, numbered catalog listing for `/models` and help output. */
+export function formatModelCatalog(activeId) {
+    return MODEL_CATALOG.map((m, index) => {
+        const marker = m.id === activeId ? "*" : " ";
+        return `${marker} ${index + 1}. ${m.label} (${m.id}) — ${m.description}`;
+    }).join("\n");
+}
+/**
+ * Resolve a `/model` argument that may be either a model name/alias or a
+ * 1-based catalog index. Throws on anything unrecognized.
+ */
+export function resolveModelSelector(selector) {
+    const trimmed = selector.trim();
+    if (/^\d+$/.test(trimmed)) {
+        const index = Number.parseInt(trimmed, 10) - 1;
+        const picked = MODEL_CATALOG[index];
+        if (!picked) {
+            throw new Error(`Model number ${trimmed} is out of range (1-${MODEL_CATALOG.length}).`);
+        }
+        return picked.id;
+    }
+    return resolveModel(trimmed, "model");
+}