@hue-run/sdk 0.4.2 → 0.5.1

package/dist/cli/mcp.d.ts

@@ -0,0 +1,76 @@
+/**
+ * `hue mcp install`: writes or prints the coding-agent configuration for Hue's MCP server. Every
+ * shape mirrors the snippets Hue shows in Settings and references the `HUE_MCP_KEY` environment
+ * variable (or a VS Code password input); a key value is never written.
+ */
+/** Streams, environment and working directory for {@link runMcpCommand}; tests inject these. */
+export interface McpCommandIo {
+    stdin?: NodeJS.ReadableStream;
+    stdout?: NodeJS.WritableStream;
+    stderr?: NodeJS.WritableStream;
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+}
+export declare const DEFAULT_MCP_URL = "https://mcp.hue.run/mcp";
+/** Prompt to paste into the agent after installation; identical to the one Hue shows. */
+export declare const MCP_VERIFY_PROMPT = "Use the Hue MCP: call get_project_context, then show my 5 most recent error traces with links.";
+export declare const MCP_USAGE = "Usage: hue mcp install --client <claude-code|cursor|codex|vscode|windsurf|gemini>\n                       [--url URL] [--scope project|user] [--dry-run] [--print]\n\nConfigure a coding agent to use the Hue MCP server. The configuration references the\nHUE_MCP_KEY environment variable; a key value is never written.\n\nOptions:\n  --client NAME   Coding agent to configure (required)\n  --url URL       Hue MCP endpoint (default https://mcp.hue.run/mcp)\n  --scope SCOPE   claude-code only: project writes .mcp.json (default); user runs\n                  `claude mcp add --scope user`\n  --dry-run       Print the resulting file content or command without writing or running\n  --print         Print the configuration snippet only\n  -h, --help      Show this help\n\nFiles: claude-code .mcp.json, cursor .cursor/mcp.json, vscode .vscode/mcp.json (relative to the\ncurrent directory). codex and gemini use their own CLI when it is on PATH; windsurf prints the\nsnippet for its user configuration file.";
+/** Canonical Hue client snippets; the JSON values are also the merge entries for config files. */
+export declare function renderMcpSnippets(url: string): {
+    claudeCodeServer: {
+        type: string;
+        url: string;
+        headers: {
+            Authorization: string;
+        };
+    };
+    claudeCodeProjectJson: string;
+    claudeCodeCli: {
+        args: string[];
+        display: string;
+    };
+    cursorServer: {
+        url: string;
+        headers: {
+            Authorization: string;
+        };
+    };
+    cursorJson: string;
+    codexCli: {
+        args: string[];
+        display: string;
+    };
+    codexToml: string;
+    vscodeServer: {
+        type: string;
+        url: string;
+        headers: {
+            Authorization: string;
+        };
+    };
+    vscodeInput: {
+        type: string;
+        id: string;
+        description: string;
+        password: boolean;
+    };
+    vscodeJson: string;
+    windsurfServer: {
+        serverUrl: string;
+        headers: {
+            Authorization: string;
+        };
+    };
+    windsurfJson: string;
+    geminiCli: {
+        args: string[];
+        display: string;
+    };
+};
+/** Validates the MCP endpoint: HTTPS, or HTTP for loopback test servers; no credentials or hash. */
+export declare function parseMcpUrl(value: string): string | null;
+/**
+ * Runs `hue mcp install` and returns the process exit code: 0 done or printed, 1 failed, 2 usage
+ * error. `argv` may start with the `mcp` command word.
+ */
+export declare function runMcpCommand(argv: string[], io?: McpCommandIo): Promise<number>;

package/dist/cli/mcp.js

@@ -0,0 +1,466 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { access, chmod, lstat, mkdir, open, readFile, rename, stat, unlink, } from "node:fs/promises";
+import { basename, delimiter, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { isLoopbackHost } from "../config.js";
+export const DEFAULT_MCP_URL = "https://mcp.hue.run/mcp";
+const SERVER_NAME = "hue";
+const ENV_VAR = "HUE_MCP_KEY";
+const INPUT_ID = `${SERVER_NAME}-mcp-key`;
+const MAX_CONFIG_BYTES = 1024 * 1024;
+/** Prompt to paste into the agent after installation; identical to the one Hue shows. */
+export const MCP_VERIFY_PROMPT = "Use the Hue MCP: call get_project_context, then show my 5 most recent error traces with links.";
+const CLIENT_IDS = ["claude-code", "cursor", "codex", "vscode", "windsurf", "gemini"];
+const CLIENT_LABELS = {
+    "claude-code": "Claude Code",
+    cursor: "Cursor",
+    codex: "Codex",
+    vscode: "VS Code",
+    windsurf: "Windsurf",
+    gemini: "Gemini CLI",
+};
+export const MCP_USAGE = `Usage: hue mcp install --client <claude-code|cursor|codex|vscode|windsurf|gemini>
+                       [--url URL] [--scope project|user] [--dry-run] [--print]
+
+Configure a coding agent to use the Hue MCP server. The configuration references the
+${ENV_VAR} environment variable; a key value is never written.
+
+Options:
+  --client NAME   Coding agent to configure (required)
+  --url URL       Hue MCP endpoint (default ${DEFAULT_MCP_URL})
+  --scope SCOPE   claude-code only: project writes .mcp.json (default); user runs
+                  \`claude mcp add --scope user\`
+  --dry-run       Print the resulting file content or command without writing or running
+  --print         Print the configuration snippet only
+  -h, --help      Show this help
+
+Files: claude-code .mcp.json, cursor .cursor/mcp.json, vscode .vscode/mcp.json (relative to the
+current directory). codex and gemini use their own CLI when it is on PATH; windsurf prints the
+snippet for its user configuration file.`;
+const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
+/** Canonical Hue client snippets; the JSON values are also the merge entries for config files. */
+export function renderMcpSnippets(url) {
+    const bearer = (reference) => `Bearer ${reference}`;
+    const claudeCodeServer = {
+        type: "http",
+        url,
+        headers: { Authorization: bearer(`\${${ENV_VAR}}`) },
+    };
+    const cursorServer = { url, headers: { Authorization: bearer(`\${env:${ENV_VAR}}`) } };
+    const vscodeServer = {
+        type: "http",
+        url,
+        headers: { Authorization: bearer(`\${input:${INPUT_ID}}`) },
+    };
+    const vscodeInput = {
+        type: "promptString",
+        id: INPUT_ID,
+        description: "Hue coding-agent key",
+        password: true,
+    };
+    const windsurfServer = {
+        serverUrl: url,
+        headers: { Authorization: bearer(`\${env:${ENV_VAR}}`) },
+    };
+    return {
+        claudeCodeServer,
+        claudeCodeProjectJson: json({ mcpServers: { [SERVER_NAME]: claudeCodeServer } }),
+        claudeCodeCli: {
+            args: [
+                "mcp",
+                "add",
+                "--transport",
+                "http",
+                "--scope",
+                "user",
+                SERVER_NAME,
+                url,
+                "--header",
+                `Authorization: Bearer \${${ENV_VAR}}`,
+            ],
+            display: `claude mcp add --transport http --scope user ${SERVER_NAME} ${url} --header 'Authorization: Bearer \${${ENV_VAR}}'`,
+        },
+        cursorServer,
+        cursorJson: json({ mcpServers: { [SERVER_NAME]: cursorServer } }),
+        codexCli: {
+            args: ["mcp", "add", SERVER_NAME, "--url", url, "--bearer-token-env-var", ENV_VAR],
+            display: `codex mcp add ${SERVER_NAME} --url ${url} --bearer-token-env-var ${ENV_VAR}`,
+        },
+        codexToml: `[mcp_servers.${SERVER_NAME}]\nurl = "${url}"\nbearer_token_env_var = "${ENV_VAR}"\n`,
+        vscodeServer,
+        vscodeInput,
+        vscodeJson: json({ servers: { [SERVER_NAME]: vscodeServer }, inputs: [vscodeInput] }),
+        windsurfServer,
+        windsurfJson: json({ mcpServers: { [SERVER_NAME]: windsurfServer } }),
+        geminiCli: {
+            args: [
+                "mcp",
+                "add",
+                "--transport",
+                "http",
+                SERVER_NAME,
+                url,
+                "-H",
+                `Authorization: Bearer $${ENV_VAR}`,
+            ],
+            // Single quotes keep the reference literal when a person runs this in a shell where the
+            // key is exported; Gemini CLI resolves $HUE_MCP_KEY from its settings at runtime.
+            display: `gemini mcp add --transport http ${SERVER_NAME} ${url} -H 'Authorization: Bearer $${ENV_VAR}'`,
+        },
+    };
+}
+class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConfigError";
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Replaces only the `hue` entry under `key`, keeping every other server and top-level field. */
+function mergeServerEntry(existing, key, entry, display) {
+    if (existing !== undefined && !isRecord(existing))
+        throw new ConfigError(`${display} must contain a JSON object.`);
+    const root = existing ?? {};
+    const servers = root[key];
+    if (servers !== undefined && !isRecord(servers))
+        throw new ConfigError(`${display}: "${key}" must be a JSON object.`);
+    return { ...root, [key]: { ...(servers ?? {}), [SERVER_NAME]: entry } };
+}
+function mergeVscodeInput(root, input, display) {
+    const inputs = root.inputs;
+    if (inputs !== undefined && !Array.isArray(inputs))
+        throw new ConfigError(`${display}: "inputs" must be a JSON array.`);
+    const others = (inputs ?? []).filter((item) => !(isRecord(item) && item.id === INPUT_ID));
+    return { ...root, inputs: [...others, input] };
+}
+async function readJsonConfig(path, display) {
+    let info;
+    try {
+        info = await lstat(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw new ConfigError(`Cannot read ${display}: ${error.message}`);
+    }
+    if (info.isSymbolicLink())
+        throw new ConfigError(`Refusing to use ${display}: it is a symbolic link.`);
+    if (!info.isFile())
+        throw new ConfigError(`Refusing to use ${display}: it is not a regular file.`);
+    if (info.size > MAX_CONFIG_BYTES)
+        throw new ConfigError(`Refusing to use ${display}: it is larger than 1 MiB.`);
+    const text = await readFile(path, "utf8");
+    if (!text.trim())
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new ConfigError(`${display} is not valid JSON (comments are not supported); fix it or add the snippet by hand.`);
+    }
+}
+async function rejectSymlink(path, display) {
+    try {
+        if ((await lstat(path)).isSymbolicLink())
+            throw new ConfigError(`Refusing to write ${display}: it is a symbolic link.`);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw error;
+    }
+}
+/** Atomic write for a secret-free config file: temporary file, fsync, rename; mode 0644. */
+async function writeConfigFile(path, text, display) {
+    await mkdir(dirname(path), { recursive: true });
+    await rejectSymlink(path, display);
+    const temporary = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+    try {
+        const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o644);
+        try {
+            await handle.writeFile(text, "utf8");
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await chmod(temporary, 0o644);
+        await rejectSymlink(path, display);
+        await rename(temporary, path);
+    }
+    catch (error) {
+        await unlink(temporary).catch(() => undefined);
+        throw error;
+    }
+}
+async function findExecutable(name, env) {
+    const searchPath = env.PATH ?? env.Path ?? "";
+    const extensions = process.platform === "win32" ? (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";") : [""];
+    for (const directory of searchPath.split(delimiter)) {
+        if (!directory)
+            continue;
+        for (const extension of extensions) {
+            const candidate = join(directory, `${name}${extension.toLowerCase()}`);
+            try {
+                if (!(await stat(candidate)).isFile())
+                    continue;
+                if (process.platform !== "win32")
+                    await access(candidate, constants.X_OK);
+                return candidate;
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    return null;
+}
+/** Runs a client CLI without a shell, forwarding its output; null when it could not start. */
+function runClientCli(executable, args, options) {
+    return new Promise((resolveRun) => {
+        try {
+            const child = spawn(executable, args, {
+                cwd: options.cwd,
+                env: options.env,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            child.stdout.on("data", (chunk) => {
+                options.stdout.write(chunk);
+            });
+            child.stderr.on("data", (chunk) => {
+                options.stderr.write(chunk);
+            });
+            child.once("error", () => resolveRun(null));
+            child.once("close", (code) => resolveRun(code));
+        }
+        catch {
+            resolveRun(null);
+        }
+    });
+}
+/** Validates the MCP endpoint: HTTPS, or HTTP for loopback test servers; no credentials or hash. */
+export function parseMcpUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopbackHost(url.hostname)))
+        return null;
+    if (url.username || url.password || url.hash)
+        return null;
+    return url.href;
+}
+function parseMcpArguments(argv) {
+    return parseArgs({
+        args: argv,
+        allowPositionals: true,
+        strict: true,
+        options: {
+            client: { type: "string" },
+            url: { type: "string" },
+            scope: { type: "string" },
+            "dry-run": { type: "boolean", default: false },
+            print: { type: "boolean", default: false },
+            help: { type: "boolean", short: "h", default: false },
+        },
+    });
+}
+function displayPath(cwd, path) {
+    const shown = relative(cwd, path);
+    return shown && !shown.startsWith("..") && !isAbsolute(shown) ? shown : path;
+}
+function planFor(client, scope, url) {
+    const snippets = renderMcpSnippets(url);
+    switch (client) {
+        case "claude-code":
+            return scope === "user"
+                ? {
+                    kind: "cli",
+                    executable: "claude",
+                    args: snippets.claudeCodeCli.args,
+                    display: snippets.claudeCodeCli.display,
+                    snippet: `${snippets.claudeCodeCli.display}\n`,
+                    fallback: ["claude is not on PATH. Run this where Claude Code is installed:"],
+                }
+                : {
+                    kind: "file",
+                    file: ".mcp.json",
+                    key: "mcpServers",
+                    entry: snippets.claudeCodeServer,
+                    snippet: snippets.claudeCodeProjectJson,
+                };
+        case "cursor":
+            return {
+                kind: "file",
+                file: join(".cursor", "mcp.json"),
+                key: "mcpServers",
+                entry: snippets.cursorServer,
+                snippet: snippets.cursorJson,
+            };
+        case "codex":
+            return {
+                kind: "cli",
+                executable: "codex",
+                args: snippets.codexCli.args,
+                display: snippets.codexCli.display,
+                snippet: snippets.codexToml,
+                fallback: [
+                    "codex is not on PATH. Add this to ~/.codex/config.toml (or run the command where Codex is installed):",
+                    snippets.codexToml.trimEnd(),
+                ],
+            };
+        case "vscode":
+            return {
+                kind: "file",
+                file: join(".vscode", "mcp.json"),
+                key: "servers",
+                entry: snippets.vscodeServer,
+                input: snippets.vscodeInput,
+                snippet: snippets.vscodeJson,
+            };
+        case "windsurf":
+            return {
+                kind: "manual",
+                snippet: snippets.windsurfJson,
+                hint: "Merge this into ~/.codeium/windsurf/mcp_config.json (Windsurf > Settings > MCP); the command does not write to your home directory.",
+            };
+        case "gemini":
+            return {
+                kind: "cli",
+                executable: "gemini",
+                args: snippets.geminiCli.args,
+                display: snippets.geminiCli.display,
+                snippet: `${snippets.geminiCli.display}\n`,
+                fallback: ["gemini is not on PATH. Run this where Gemini CLI is installed:"],
+            };
+    }
+}
+function nextSteps(client) {
+    const label = CLIENT_LABELS[client];
+    const lines = client === "vscode"
+        ? [
+            `${label} prompts for the key (input ${INPUT_ID}) when the server starts; paste the ${ENV_VAR} value that hue login stored in .env.hue.`,
+        ]
+        : [
+            `Export ${ENV_VAR} in the shell that starts ${label}; hue login stores it in .env.hue:`,
+            "  set -a; . ./.env.hue; set +a",
+        ];
+    return [...lines, "Then ask your agent:", `  ${MCP_VERIFY_PROMPT}`];
+}
+/**
+ * Runs `hue mcp install` and returns the process exit code: 0 done or printed, 1 failed, 2 usage
+ * error. `argv` may start with the `mcp` command word.
+ */
+export async function runMcpCommand(argv, io = {}) {
+    const stdout = io.stdout ?? process.stdout;
+    const stderr = io.stderr ?? process.stderr;
+    const env = io.env ?? process.env;
+    const cwd = io.cwd ?? process.cwd();
+    const out = (line) => {
+        stdout.write(`${line}\n`);
+    };
+    const fail = (message, code = 1) => {
+        stderr.write(`${message}\n`);
+        return code;
+    };
+    let parsed;
+    try {
+        parsed = parseMcpArguments(argv);
+    }
+    catch (error) {
+        return fail(`${error.message}\n\n${MCP_USAGE}`, 2);
+    }
+    if (parsed.values.help) {
+        out(MCP_USAGE);
+        return 0;
+    }
+    const positionals = parsed.positionals[0] === "mcp" ? parsed.positionals.slice(1) : parsed.positionals;
+    if (positionals.length !== 1 || positionals[0] !== "install")
+        return fail(`${positionals.length === 0 ? "Missing subcommand." : `Unknown subcommand: ${positionals.join(" ")}`}\n\n${MCP_USAGE}`, 2);
+    const client = parsed.values.client;
+    if (!client || !CLIENT_IDS.includes(client))
+        return fail(`${client ? `Unknown client: ${client}.` : "--client is required."} Choose one of ${CLIENT_IDS.join(", ")}.\n\n${MCP_USAGE}`, 2);
+    const scope = parsed.values.scope ?? "project";
+    if (scope !== "project" && scope !== "user")
+        return fail(`--scope must be project or user.\n\n${MCP_USAGE}`, 2);
+    if (scope === "user" && client !== "claude-code")
+        return fail("--scope user is only available with --client claude-code.", 2);
+    const url = parseMcpUrl(parsed.values.url ?? DEFAULT_MCP_URL);
+    if (!url)
+        return fail("--url must be an HTTPS URL such as https://mcp.hue.run/mcp (plain HTTP is accepted for loopback test servers only).", 2);
+    const plan = planFor(client, scope, url);
+    if (parsed.values.print) {
+        stdout.write(plan.snippet);
+        return 0;
+    }
+    const steps = nextSteps(client);
+    if (plan.kind === "manual") {
+        out(plan.hint);
+        stdout.write(plan.snippet);
+        for (const line of steps)
+            out(line);
+        return 0;
+    }
+    if (plan.kind === "cli") {
+        if (parsed.values["dry-run"]) {
+            out(`Would run: ${plan.display}`);
+            return 0;
+        }
+        const executable = await findExecutable(plan.executable, env);
+        if (!executable) {
+            for (const line of plan.fallback)
+                out(line);
+            out(plan.display);
+            for (const line of steps)
+                out(line);
+            return 0;
+        }
+        out(`Running: ${plan.display}`);
+        const code = await runClientCli(executable, plan.args, { cwd, env, stdout, stderr });
+        if (code === null)
+            return fail(`${plan.executable} could not be started. Run this command yourself:\n${plan.display}`);
+        if (code !== 0)
+            return fail(`${plan.executable} exited with code ${code}. Run this command yourself:\n${plan.display}`);
+        out(`Registered the "${SERVER_NAME}" MCP server (${url}) with ${CLIENT_LABELS[client]}.`);
+        for (const line of steps)
+            out(line);
+        return 0;
+    }
+    const path = resolve(cwd, plan.file);
+    const display = displayPath(cwd, path);
+    let content;
+    try {
+        const existing = await readJsonConfig(path, display);
+        let merged = mergeServerEntry(existing, plan.key, plan.entry, display);
+        if (plan.input)
+            merged = mergeVscodeInput(merged, plan.input, display);
+        content = json(merged);
+    }
+    catch (error) {
+        if (error instanceof ConfigError)
+            return fail(`${error.message}\nSnippet for ${display}:\n${plan.snippet.trimEnd()}`);
+        return fail(`Could not read ${display}: ${error.message}`);
+    }
+    if (parsed.values["dry-run"]) {
+        out(`Would write ${display}:`);
+        stdout.write(content);
+        return 0;
+    }
+    try {
+        await writeConfigFile(path, content, display);
+    }
+    catch (error) {
+        return fail(`Could not write ${display}: ${error.message}`);
+    }
+    out(`Wrote ${display} with the "${SERVER_NAME}" MCP server (${url}).`);
+    for (const line of steps)
+        out(line);
+    return 0;
+}

package/dist/evals/client.d.ts

@@ -1,6 +1,6 @@
 import type { ProjectConnection } from "../types.js";
 import { type AttemptConnectionBundleV2, type PrepareAttemptRequestV2 } from "./attempt.js";
-import type { CaseWrite, CompleteExecution, Completion, Dataset, DatasetCase, DatasetVersion, EvaluationItem, EvaluationRun, EnvironmentEvidenceSnapshot, Execution, Experiment, ExperimentCase, ExperimentItem, Identity, JsonValue, LocalAgentClaim, LocalAgentRegistration, RegisteredLocalAgent, JudgeBudget, JudgeJob, Page, PageOptions, RegistryPageOptions, Result, ResultSummary, Scorer, ScorerDefinition, ScorerVersion, SimulationMcpCapability, StartExecution, Subject, StoredResult } from "./types.js";
+import type { ArtifactReservation, ArtifactUpload, CaseConversion, CaseConversionSummary, CaseWrite, CompleteExecution, Completion, Dataset, DatasetCase, DatasetVersion, EvaluationItem, EvaluationRun, EvaluationRunSummary, EnvironmentEvidenceSnapshot, Execution, Experiment, ExperimentCase, ExperimentItem, Identity, JsonValue, LocalAgentClaim, LocalAgentRegistration, RegisteredLocalAgent, JudgeBudget, JudgeJob, Page, PageOptions, RegistryPageOptions, Result, ResultSummary, Scorer, ScorerDefinition, ScorerVersion, SimulationMcpCapability, StartExecution, Subject, StoredResult } from "./types.js";
 /** Connection options for {@link createEvaluationClient}. */
 export interface EvaluationClientOptions {
     /** Project service key sent as a Bearer token; server side only. */
@@ -30,6 +30,10 @@ export declare class EvaluationClient {
     private readonly timeoutMillis;
     constructor(options: EvaluationClientOptions);
     private request;
+    /** Verified bytes of one ready artifact in this project, bounded to the 25 MiB pilot file size. */
+    downloadArtifact(id: string): Promise<Uint8Array>;
+    /** Stage bytes at the storage capability Hue issued. The Hue key is never sent to storage. */
+    uploadArtifactBytes(upload: ArtifactUpload, bytes: Uint8Array, contentType: string): Promise<void>;
     private page;
     private registryPage;
     /** Reads the current project to confirm the key and origin. */
@@ -113,6 +117,25 @@ export declare class EvaluationClient {
     revokeAttemptConnection(input: {
         bindingId: string;
     }): Promise<import("./attempt.js").RevokeAttemptResult>;
+    /** Reads one artifact reservation and its verification state. */
+    getArtifact(id: string): Promise<ArtifactReservation>;
+    /** Reserves an artifact by declared identity; replaying the key returns the same reservation. */
+    reserveArtifact(input: {
+        /** Stable key; replaying it returns the same reservation. */
+        idempotencyKey: string;
+        /** Declared file name. */
+        filename: string;
+        /** Declared content type. */
+        contentType: string;
+        /** Declared size in bytes. */
+        byteSize: number;
+        /** Declared SHA-256, hex encoded. */
+        sha256: string;
+    }): Promise<ArtifactReservation>;
+    /** Issues a short-lived storage capability for staging the reserved artifact's bytes. */
+    requestArtifactUpload(id: string): Promise<ArtifactUpload>;
+    /** Asks Hue to verify the staged bytes against the declared identity. */
+    completeArtifact(id: string): Promise<ArtifactReservation>;
     /** Saves an execution's outcome and creates its immutable subject. */
     completeExecution(id: string, input: CompleteExecution): Promise<Completion>;
     /** Marks an experiment finished. */
@@ -134,6 +157,8 @@ export declare class EvaluationClient {
     }>;
     /** Reads an evaluation run and its scoring progress. */
     getEvaluationRun(id: string): Promise<EvaluationRun>;
+    /** Every evaluation run of the project, oldest first; a grading worker polls this for pending pins. */
+    listEvaluationRuns(page?: PageOptions): Promise<Page<EvaluationRunSummary>>;
     /** Lists the subjects of an evaluation run. */
     listEvaluationItems(id: string, page?: PageOptions): Promise<Page<EvaluationItem>>;
     /** Reads an immutable subject, including output and reference when available. */
@@ -205,6 +230,10 @@ export declare class EvaluationClient {
         /** Acknowledged terminal queue state. */
         state: "completed" | "attention";
     }>;
+    /** Lists Scenarios (draft and published) of the project; requires a Read and write key. */
+    listCaseConversions(page?: PageOptions): Promise<Page<CaseConversionSummary>>;
+    /** Reads one Scenario with its immutable publication pins. */
+    getCaseConversion(id: string): Promise<CaseConversion>;
     /** Creates the legacy execution-scoped generic MCP capability for one world. */
     createSimulationMcpCapability(input: {
         runId: string;