@camelai/camelrun 0.0.0 → 0.11.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qaml-ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# @camelai/camelrun
+
+The camelRun CLI: deploy and manage agents on [camelRun](https://agents.camelai.dev)
+from a terminal, a script or CI, and give a coding agent the same powers over MCP.
+
+```sh
+npm install -g @camelai/camelrun
+camelrun login                   # an API key from the console's API tokens page
+camelrun init support            # writes agent.yaml
+camelrun deploy                  # the definition, and the agents it lists
+camelrun run support "Which tickets look urgent?"
+```
+
+`agent.yaml` keeps an agent's configuration in your repository; deploying again makes a new
+revision only when it changed, and `--apply` moves live agents to it between their turns:
+
+```yaml
+key: support
+model: anthropic/claude-sonnet-5-5
+systemPromptFile: prompts/support.md
+builtins: [web_search, ask_user]
+mcpServers:
+  - name: app
+    url: https://app.example.com/mcp
+    auth: { type: bearer, token: "${APP_MCP_TOKEN}" }
+agents:
+  - key: support
+```
+
+Output is JSON when stdout is not a terminal (or with `--json`); exit code 2 means a run waits
+on a person (`camelrun inputs`, `camelrun answer`).
+
+## For coding agents
+
+The hosted MCP server needs nothing installed; sign in when the client asks:
+
+```sh
+claude mcp add --transport http camelrun https://agents.camelai.dev/mcp
+```
+
+Or run it locally, where its `deploy` also reads your repository's manifests:
+
+```sh
+claude mcp add camelrun -- npx -y @camelai/camelrun mcp
+```
+
+Every command, the manifest's fields and the MCP tools:
+[CLI and MCP server](https://agents.camelai.dev/docs/reference/cli.md).

package/dist/api.js

@@ -0,0 +1,73 @@
+/** A refused call: the runtime's `error` message, with the HTTP status and its `code` when it gave one. */
+export class ApiError extends Error {
+    status;
+    code;
+    constructor(status, message, code) { super(message); this.status = status; this.code = code; }
+}
+/** SHA-256 as hex, with Web Crypto: the same in Node and browsers. */
+async function sha256(text) {
+    const digest = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
+    return [...new Uint8Array(digest)].map(byte => byte.toString(16).padStart(2, "0")).join("");
+}
+/** The runtime's REST API, called with a tenant API key (`art_…`). */
+export class Api {
+    url;
+    apiKey;
+    headers;
+    fetch;
+    tenant;
+    // Browser fetch requires the global receiver, even when stored on this client.
+    constructor(credentials, fetch = globalThis.fetch.bind(globalThis)) {
+        this.url = credentials.url.replace(/\/+$/, "");
+        this.apiKey = credentials.apiKey;
+        this.headers = credentials.headers ?? {};
+        this.fetch = fetch;
+    }
+    async call(method, path, body, headers = {}) {
+        const response = await this.fetch(this.url + path, {
+            method,
+            headers: { ...(this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}), ...this.headers, ...(body !== undefined ? { "Content-Type": "application/json" } : {}), ...headers },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        const text = await response.text();
+        let json;
+        try {
+            json = text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            json = undefined;
+        }
+        if (!response.ok) {
+            const message = json?.error ?? json?.message ?? (text.slice(0, 300) || response.statusText);
+            throw new ApiError(response.status, response.status === 401 ? `${message} (check your API key: camelrun login)` : message, json?.code);
+        }
+        return json;
+    }
+    get(path) { return this.call("GET", path); }
+    /** A public document of the runtime's (its docs), as text. */
+    async text(path) {
+        const response = await this.fetch(this.url + path);
+        if (!response.ok)
+            throw new ApiError(response.status, `${path}: ${response.status === 404 ? "no such page (read_docs with no path lists them)" : response.statusText}`);
+        return response.text();
+    }
+    me() { return this.get("/v1/me"); }
+    /** A definition's id from its key: the runtime derives it from the tenant and the key. */
+    async definitionId(keyOrId) {
+        if (/^def_[a-f0-9]{20}$/.test(keyOrId))
+            return keyOrId;
+        this.tenant ??= this.me().then(me => me.tenant);
+        return `def_${(await sha256(`${await this.tenant}:${keyOrId}`)).slice(0, 20)}`;
+    }
+    /** An agent's id from its key or id (`client_…`). */
+    async agentId(keyOrId) {
+        if (keyOrId.startsWith("client_"))
+            return keyOrId;
+        const agents = await this.get("/v1/agents");
+        const found = agents.find(agent => agent.key === keyOrId);
+        if (!found)
+            throw new ApiError(404, `No agent with key ${JSON.stringify(keyOrId)} (camelrun agents list shows them)`);
+        return found.id;
+    }
+}
+export const enc = encodeURIComponent;

package/dist/bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from "./cli.js";
+process.exitCode = await main(process.argv.slice(2));

package/dist/cli.js

@@ -0,0 +1,363 @@
+import { existsSync, writeFileSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
+import { parseArgs } from "node:util";
+import { Api, enc } from "./api.js";
+import { DEFAULT_URL, forget, resolve, save } from "./config.js";
+import { DEFAULT_FILES, template } from "./manifest.js";
+import { findManifest, loadManifests } from "./manifest-files.js";
+import * as ops from "./ops.js";
+import { VERSION } from "./version.js";
+const HELP = `camelrun: deploy and manage agents on camelRun
+
+Usage: camelrun <command> [options]
+
+Setup
+  login [--api-key art_…]          Save an API key (checked against the runtime)
+  logout                           Forget the saved key
+  whoami                           The tenant the key belongs to, and its default model
+  models [--available]             Models, or only those your account can use
+  init [key] [--model m]           Write an agent.yaml manifest here
+
+Deploy
+  deploy [file…] [--apply] [--dry-run]
+                                   Upsert each manifest's definition by its key and make its agents;
+                                   --apply also moves live agents to the new revision between turns
+
+Agents (an agent is its key or its id, client_…)
+  agents list
+  agents get <agent>               Configuration, definition revision and tool sources
+  agents create <key> [--definition key|id] [--model m] [--prompt text] [--name n]
+  agents configure <agent> [--model m] [--prompt text] [--prompt-append text] [--thinking level]
+  agents delete <agent> --yes      Stop it and purge its history and files
+  run <agent> <message…> [--wait s] [--no-wait] [--from user] [--steer] [--allow-disconnected]
+  runs get <agent> <requestId> [--wait s]
+  history <agent> [--limit n]
+  abort <agent>
+  inputs [agent]                   Questions and approvals waiting on someone
+  answer <agent> <inputId> <value> true/false, text, JSON, or "decline"
+  schedules list <agent>
+  schedules add <agent> --text t (--in s | --at iso) [--every s]
+  schedules delete <agent> <scheduleId>
+
+Definitions (a definition is its key or its id, def_…)
+  definitions list
+  definitions get <definition>
+  definitions agents <definition>  Its agents and the revision each has
+  definitions delete <definition> --yes
+
+MCP
+  mcp                              Serve these commands as an MCP server over stdio
+                                   (or connect clients to the hosted one: https://agents.camelai.dev/mcp)
+
+Options
+  --json                           Print JSON (the default when stdout is not a terminal)
+  --api-key <key>, --url <url>     Instead of CAMELAI_API_KEY / CAMELAI_URL / the saved login
+
+Docs: https://agents.camelai.dev/llms.txt`;
+const OPTIONS = {
+    json: { type: "boolean" }, help: { type: "boolean", short: "h" }, version: { type: "boolean", short: "v" },
+    "api-key": { type: "string" }, url: { type: "string" },
+    apply: { type: "boolean" }, "dry-run": { type: "boolean" }, available: { type: "boolean" }, force: { type: "boolean" }, yes: { type: "boolean", short: "y" },
+    model: { type: "string" }, prompt: { type: "string" }, "prompt-append": { type: "string" }, thinking: { type: "string" }, name: { type: "string" }, definition: { type: "string" },
+    wait: { type: "string" }, "no-wait": { type: "boolean" }, from: { type: "string" }, steer: { type: "boolean" }, "allow-disconnected": { type: "boolean" }, "request-id": { type: "string" },
+    limit: { type: "string" }, text: { type: "string" }, in: { type: "string" }, at: { type: "string" }, every: { type: "string" },
+};
+class UsageError extends Error {
+}
+/** Run the CLI; resolves with its exit code: 0, 1 for an error, 2 when a run waits on a person. */
+export async function main(argv, io = { out: text => process.stdout.write(text + "\n"), err: text => process.stderr.write(text + "\n"), tty: !!process.stdout.isTTY, env: process.env, cwd: process.cwd() }) {
+    let parsed;
+    try {
+        parsed = parseArgs({ args: argv, options: OPTIONS, allowPositionals: true, strict: true });
+    }
+    catch (error) {
+        io.err(`${error.message}\n\nRun camelrun --help for usage.`);
+        return 1;
+    }
+    const { values: flags, positionals } = parsed;
+    if (flags.version) {
+        io.out(VERSION);
+        return 0;
+    }
+    const [command, ...args] = positionals;
+    if (!command || flags.help || command === "help") {
+        io.out(HELP);
+        return 0;
+    }
+    const json = flags.json || !io.tty;
+    const print = (value, human) => io.out(json || !human ? JSON.stringify(value, null, 2) : human());
+    const api = () => new Api(resolve({ apiKey: flags["api-key"], url: flags.url }, io.env));
+    try {
+        switch (command) {
+            case "mcp": {
+                const { serve } = await import("./mcp.js");
+                await serve(() => api(), { cwd: io.cwd });
+                return 0;
+            }
+            case "login": return await login(flags, io, print);
+            case "logout": {
+                const path = forget(io.env);
+                print({ loggedOut: !!path }, () => path ? `Removed ${path}` : "No saved key");
+                return 0;
+            }
+            case "whoami": {
+                const client = api();
+                const me = await client.me();
+                print({ ...me, url: client.url }, () => `${me.login ?? me.tenant} (tenant ${me.tenant}) on ${client.url}\nDefault model: ${me.defaultModel}`);
+                return 0;
+            }
+            case "models": {
+                const models = await api().get(`/v1/models${flags.available ? "?available=true" : ""}`);
+                print(models.map(({ id, name, available, contextWindow, reasoning, cost }) => ({ id, name, available, contextWindow, reasoning, cost })), () => table(models, ["id", "available", "contextWindow", "reasoning"]));
+                return 0;
+            }
+            case "init": {
+                const key = args[0] ?? io.cwd.split("/").pop().replace(/[^A-Za-z0-9_-]/g, "-").slice(0, 80);
+                const path = `${io.cwd}/agent.yaml`;
+                if (DEFAULT_FILES.some(name => existsSync(`${io.cwd}/${name}`)) && !flags.force)
+                    throw new UsageError("A manifest is already here (--force overwrites agent.yaml)");
+                writeFileSync(path, template(key, flags.model));
+                print({ file: path, key }, () => `Wrote ${path}. Edit it, then: camelrun deploy`);
+                return 0;
+            }
+            case "deploy": {
+                const files = args.length ? args : [findManifest(io.cwd)];
+                const manifests = files.flatMap(file => loadManifests(file.startsWith("/") ? file : `${io.cwd}/${file}`, io.env));
+                const results = await ops.deploy(api(), manifests, { apply: flags.apply, dryRun: flags["dry-run"] });
+                if (flags["dry-run"] && json)
+                    print(results.map((result, index) => ({ ...result, definition: ops.redact(manifests[index].definition) })));
+                else
+                    print(results, () => results.map(describeDeploy).join("\n"));
+                return results.some(result => result.agents.some(agent => agent.status === "failed") || result.applied?.some(applied => applied.status === "failed")) ? 1 : 0;
+            }
+            case "agents": return await agents(args, flags, api, print);
+            case "definitions": return await definitions(args, flags, api, print);
+            case "run": {
+                const [agent, ...words] = args;
+                if (!agent || !words.length)
+                    throw new UsageError("Usage: camelrun run <agent> <message…>");
+                const result = await ops.run(api(), agent, words.join(" "), { wait: waitSeconds(flags), from: flags.from, steer: flags.steer, allowDisconnected: flags["allow-disconnected"], requestId: flags["request-id"] });
+                return printRun(result, print, io);
+            }
+            case "runs": {
+                const [sub, agent, requestId] = args;
+                if (sub !== "get" || !agent || !requestId)
+                    throw new UsageError("Usage: camelrun runs get <agent> <requestId> [--wait s]");
+                const client = api();
+                return printRun(await ops.waitFor(client, await client.agentId(agent), requestId, flags.wait ? Number(flags.wait) : 0), print, io);
+            }
+            case "history": {
+                if (!args[0])
+                    throw new UsageError("Usage: camelrun history <agent> [--limit n]");
+                const page = await ops.history(api(), args[0], flags.limit ? Number(flags.limit) : 20);
+                print(page, () => page.messages.map((message) => {
+                    const head = message.role === "toolResult" ? `[${message.tool} →]` : `${message.role}${"from" in message ? ` (${message.from})` : ""}:`;
+                    const calls = "toolCalls" in message ? message.toolCalls.map(call => `\n  → ${call.name}(${JSON.stringify(call.arguments).slice(0, 200)})`).join("") : "";
+                    return `${head} ${message.text ?? ""}${calls}`;
+                }).join("\n\n") || "(no messages)");
+                return 0;
+            }
+            case "abort": {
+                if (!args[0])
+                    throw new UsageError("Usage: camelrun abort <agent>");
+                const client = api();
+                const id = await client.agentId(args[0]);
+                print(await client.call("POST", `/v1/agents/${enc(id)}/abort`, {}), () => `Aborted the running turn of ${args[0]}`);
+                return 0;
+            }
+            case "inputs": {
+                const client = api();
+                const inputs = args[0] ? await client.get(`/v1/agents/${enc(await client.agentId(args[0]))}/inputs?state=pending`) : await client.get("/v1/inputs?state=pending");
+                print(inputs, () => inputs.length ? inputs.map(input => `${input.id}  ${input.agent}  ${input.kind}: ${input.message ?? JSON.stringify(input.detail).slice(0, 200)}`).join("\n") : "Nothing is waiting");
+                return 0;
+            }
+            case "answer": {
+                const [agent, inputId, ...rest] = args;
+                if (!agent || !inputId || !rest.length)
+                    throw new UsageError("Usage: camelrun answer <agent> <inputId> <value>");
+                const raw = rest.join(" ");
+                let value = raw;
+                try {
+                    value = JSON.parse(raw);
+                }
+                catch { /* text */ }
+                const result = await ops.answer(api(), agent, inputId, value, { from: flags.from, wait: waitSeconds(flags) });
+                return "requestId" in result ? printRun(result, print, io) : (print(result, () => result.note), 0);
+            }
+            case "schedules": return await schedules(args, flags, api, print);
+            default: throw new UsageError(`Unknown command: ${command}. Run camelrun --help`);
+        }
+    }
+    catch (error) {
+        io.err(json && !(error instanceof UsageError) ? JSON.stringify({ error: error.message, ...("status" in error ? { status: error.status, code: error.code } : {}) }) : `Error: ${error.message}`);
+        return 1;
+    }
+}
+async function login(flags, io, print) {
+    let apiKey = flags["api-key"] || io.env.CAMELAI_API_KEY;
+    if (!apiKey) {
+        if (!process.stdin.isTTY)
+            throw new UsageError("Pass --api-key art_… (or set CAMELAI_API_KEY); create one under API tokens at https://agents.camelai.dev/console");
+        const prompt = createInterface({ input: process.stdin, output: process.stderr });
+        apiKey = (await prompt.question("API key (from https://agents.camelai.dev/console, API tokens): ")).trim();
+        prompt.close();
+    }
+    const url = flags.url || io.env.CAMELAI_URL || DEFAULT_URL;
+    const me = await new Api({ apiKey, url }).me();
+    const path = save({ apiKey, url }, io.env);
+    print({ tenant: me.tenant, url, saved: path }, () => `Logged in as ${me.login ?? me.tenant} on ${url} (key saved to ${path})`);
+    return 0;
+}
+async function agents(args, flags, api, print) {
+    const [sub, target] = args;
+    const client = api();
+    switch (sub) {
+        case "list":
+        case undefined: {
+            const list = await client.get("/v1/agents");
+            print(list, () => list.length ? table(list, ["key", "id", "model", "running", "connected"]) : "No agents yet: camelrun deploy, or camelrun agents create <key>");
+            return 0;
+        }
+        case "get": {
+            if (!target)
+                throw new UsageError("Usage: camelrun agents get <agent>");
+            const detail = await client.get(`/v1/agents/${enc(await client.agentId(target))}`);
+            print(detail);
+            return 0;
+        }
+        case "create": {
+            if (!target)
+                throw new UsageError("Usage: camelrun agents create <key> [--definition d] [--model m] [--prompt text]");
+            const created = await ops.upsertAgent(client, target, { definition: flags.definition, model: flags.model, systemPrompt: flags.prompt, systemPromptAppend: flags["prompt-append"], name: flags.name });
+            print(created, () => `${created.key}: ${created.id}${created.reconfigured ? " (reconfigured)" : ""}`);
+            return 0;
+        }
+        case "configure": {
+            if (!target)
+                throw new UsageError("Usage: camelrun agents configure <agent> [--model m] [--prompt text] [--prompt-append text] [--thinking level]");
+            const changes = Object.fromEntries(Object.entries({ model: flags.model, systemPrompt: flags.prompt, systemPromptAppend: flags["prompt-append"], thinkingLevel: flags.thinking }).filter(([, value]) => value !== undefined));
+            if (!Object.keys(changes).length)
+                throw new UsageError("Nothing to change: pass --model, --prompt, --prompt-append or --thinking");
+            const result = await ops.configure(client, target, changes);
+            print(result, () => result.status === "failed" ? `Failed: ${result.error?.message}` : result.status === "running" ? `Queued behind its current run (request ${result.requestId})` : `Configured ${target}`);
+            return result.status === "failed" ? 1 : 0;
+        }
+        case "delete": {
+            if (!target)
+                throw new UsageError("Usage: camelrun agents delete <agent> --yes");
+            if (!flags.yes)
+                throw new UsageError(`Deleting ${target} stops it and purges its history and files. Pass --yes to go ahead.`);
+            const id = await client.agentId(target);
+            print(await client.call("DELETE", `/v1/agents/${enc(id)}`), () => `Deleted ${target} (${id})`);
+            return 0;
+        }
+        default: throw new UsageError(`Unknown: agents ${sub}. Run camelrun --help`);
+    }
+}
+async function definitions(args, flags, api, print) {
+    const [sub, target] = args;
+    const client = api();
+    switch (sub) {
+        case "list":
+        case undefined: {
+            const list = await client.get("/v1/definitions");
+            print(list, () => list.length ? table(list, ["id", "name", "revision", "model"]) : "No definitions yet: camelrun init, then camelrun deploy");
+            return 0;
+        }
+        case "get":
+        case "agents":
+        case "delete": {
+            if (!target)
+                throw new UsageError(`Usage: camelrun definitions ${sub} <definition>`);
+            const id = await client.definitionId(target);
+            if (sub === "get")
+                print(await client.get(`/v1/definitions/${id}`));
+            else if (sub === "agents") {
+                const list = await client.get(`/v1/definitions/${id}/agents`);
+                print(list, () => list.length ? table(list, Object.keys(list[0]).slice(0, 5)) : "No agents");
+            }
+            else {
+                if (!flags.yes)
+                    throw new UsageError(`Pass --yes to delete ${target}; its agents are left as they are`);
+                print(await client.call("DELETE", `/v1/definitions/${id}`), () => `Deleted ${target} (${id})`);
+            }
+            return 0;
+        }
+        default: throw new UsageError(`Unknown: definitions ${sub}. Run camelrun --help`);
+    }
+}
+async function schedules(args, flags, api, print) {
+    const [sub, agent, scheduleId] = args;
+    if (!agent)
+        throw new UsageError("Usage: camelrun schedules list|add|delete <agent> …");
+    const client = api();
+    const id = await client.agentId(agent);
+    switch (sub) {
+        case "list": {
+            const list = await client.get(`/v1/agents/${enc(id)}/schedules`);
+            print(list, () => list.length ? list.map(item => `${item.id}  ${new Date(item.dueAt).toISOString()}${item.everySeconds ? ` every ${item.everySeconds}s` : ""}  ${item.text ?? item.code}`).join("\n") : "No schedules");
+            return 0;
+        }
+        case "add": {
+            if (!flags.text || (!flags.in && !flags.at))
+                throw new UsageError("Usage: camelrun schedules add <agent> --text t (--in seconds | --at iso) [--every seconds]");
+            const body = { text: flags.text, ...(flags.in ? { inSeconds: Number(flags.in) } : { at: flags.at }), ...(flags.every ? { everySeconds: Number(flags.every) } : {}) };
+            const created = await client.call("POST", `/v1/agents/${enc(id)}/schedules`, body);
+            print(created, () => `${created.id}: due ${new Date(created.dueAt).toISOString()}`);
+            return 0;
+        }
+        case "delete": {
+            if (!scheduleId)
+                throw new UsageError("Usage: camelrun schedules delete <agent> <scheduleId>");
+            print(await client.call("DELETE", `/v1/agents/${enc(id)}/schedules/${enc(scheduleId)}`), () => `Deleted ${scheduleId}`);
+            return 0;
+        }
+        default: throw new UsageError(`Unknown: schedules ${sub}. Run camelrun --help`);
+    }
+}
+function waitSeconds(flags) {
+    if (flags["no-wait"])
+        return 0;
+    if (flags.wait === undefined)
+        return undefined;
+    const seconds = Number(flags.wait);
+    if (!Number.isFinite(seconds) || seconds < 0)
+        throw new UsageError("--wait is a number of seconds");
+    return seconds;
+}
+function printRun(result, print, io) {
+    print(result, () => {
+        switch (result.status) {
+            case "running": return `Still running: camelrun runs get ${result.agent} ${result.requestId} --wait 60`;
+            case "failed": return `Failed (${result.error?.code}): ${result.error?.message}`;
+            case "input_required": return [result.text, ...(result.inputs ?? []).map(input => `Waiting on ${input.kind} ${input.id}: ${input.message ?? JSON.stringify(input.detail)}\n  camelrun answer ${result.agent} ${input.id} <value>`)].filter(Boolean).join("\n");
+            default: return [result.text || "(no reply)", ...(result.toolErrors ?? []).map(error => `tool error: ${JSON.stringify(error)}`)].join("\n");
+        }
+    });
+    if (result.status === "failed")
+        return 1;
+    if (result.status === "input_required") {
+        if (io.tty)
+            io.err("(the run waits on the input above)");
+        return 2;
+    }
+    return 0;
+}
+function table(rows, columns) {
+    const cell = (value) => value === null || value === undefined ? "-" : typeof value === "object" ? JSON.stringify(value) : String(value);
+    const widths = columns.map(column => Math.max(column.length, ...rows.map(row => cell(row[column]).length)));
+    const line = (values) => values.map((value, index) => value.padEnd(widths[index])).join("  ").trimEnd();
+    return [line(columns), ...rows.map(row => line(columns.map(column => cell(row[column]))))].join("\n");
+}
+function describeDeploy(result) {
+    const lines = [`${result.key}: ${result.status}${result.status === "planned" ? ` (now at revision ${result.revision || "none"})` : ` (${result.id}, revision ${result.revision})`}`];
+    for (const source of (result.toolSources ?? []))
+        lines.push(`  tools from ${source.name}: ${source.status === "error" ? `error: ${source.error}` : `${source.tools?.length ?? 0} tools`}`);
+    for (const applied of result.applied ?? [])
+        lines.push(`  applied to ${applied.agent}: ${applied.status}${applied.error ? ` (${applied.error})` : ""}`);
+    if (result.status === "updated" && !result.applied)
+        lines.push("  live agents keep their revision; deploy with --apply to move them");
+    for (const agent of result.agents)
+        lines.push(`  agent ${agent.key}: ${agent.status}${agent.id ? ` (${agent.id})` : ""}${agent.reconfigured ? ", reconfigured between its turns" : ""}${agent.error ? `: ${agent.error}` : ""}`);
+    return lines.join("\n");
+}

package/dist/config.js

@@ -0,0 +1,42 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+export const DEFAULT_URL = "https://agents.camelai.dev";
+/** Where `camelrun login` keeps the key: $CAMELRUN_CONFIG, else $XDG_CONFIG_HOME/camelrun, else ~/.config/camelrun. */
+export function configPath(env = process.env) {
+    if (env.CAMELRUN_CONFIG)
+        return env.CAMELRUN_CONFIG;
+    return join(env.XDG_CONFIG_HOME || join(homedir(), ".config"), "camelrun", "credentials.json");
+}
+export function readSaved(env = process.env) {
+    const path = configPath(env);
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+export function save(credentials, env = process.env) {
+    const path = configPath(env);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(path, JSON.stringify(credentials, null, 2) + "\n", { mode: 0o600 });
+    chmodSync(path, 0o600);
+    return path;
+}
+export function forget(env = process.env) {
+    const path = configPath(env);
+    const had = existsSync(path);
+    rmSync(path, { force: true });
+    return had ? path : undefined;
+}
+/** Flags first, then CAMELAI_API_KEY / CAMELAI_URL, then what `camelrun login` saved. */
+export function resolve(flags, env = process.env) {
+    const saved = readSaved(env);
+    const apiKey = flags.apiKey || env.CAMELAI_API_KEY || saved.apiKey;
+    if (!apiKey)
+        throw new Error("No API key: run `camelrun login`, or set CAMELAI_API_KEY (create one under API tokens at https://agents.camelai.dev/console)");
+    return { apiKey, url: flags.url || env.CAMELAI_URL || saved.url || DEFAULT_URL };
+}

package/dist/manifest-files.js

@@ -0,0 +1,21 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, extname, resolve } from "node:path";
+import { DEFAULT_FILES, fromDocuments, parseManifests } from "./manifest.js";
+/** The manifest in `cwd`: agent.yaml, agent.yml or agent.json. */
+export function findManifest(cwd = process.cwd()) {
+    const found = DEFAULT_FILES.map(name => resolve(cwd, name)).find(path => existsSync(path));
+    if (!found)
+        throw new Error(`No manifest: expected one of ${DEFAULT_FILES.join(", ")} here, or pass a path (camelrun init writes one)`);
+    return found;
+}
+/** Files a manifest at `path` names, read relative to it. */
+export const filesBeside = (path) => (relative) => readFileSync(resolve(dirname(path), relative), "utf8");
+/** The manifests in a file, with `${NAME}` read from `env` and the files they name read beside it. */
+export function loadManifests(file, env = process.env) {
+    const path = resolve(file);
+    if (!existsSync(path))
+        throw new Error(`${file}: no such file`);
+    const text = readFileSync(path, "utf8");
+    const source = { env, readFile: filesBeside(path) };
+    return extname(path) === ".json" ? fromDocuments([JSON.parse(text)], path, file, source) : parseManifests(text, file, source).map(manifest => ({ ...manifest, file: path }));
+}

package/dist/manifest.js

@@ -0,0 +1,110 @@
+import { parseAllDocuments, parse as parseYaml } from "yaml";
+export const DEFAULT_FILES = ["agent.yaml", "agent.yml", "agent.json"];
+const KEY = /^[A-Za-z0-9_-]{1,80}$/;
+/** Manifests from YAML text (several documents are several manifests). */
+export function parseManifests(text, where, source = {}) {
+    const documents = parseAllDocuments(text).map(document => {
+        if (document.errors.length)
+            throw new Error(`${where}: ${document.errors[0].message}`);
+        return document.toJS();
+    }).filter(document => document != null);
+    return fromDocuments(documents, where, where, source);
+}
+/** Manifests from parsed documents, checked for keys used twice. */
+export function fromDocuments(documents, file, where, source = {}) {
+    if (!documents.length)
+        throw new Error(`${where}: empty`);
+    const manifests = documents.map((document, index) => {
+        const at = documents.length > 1 ? `${where} (document ${index + 1})` : where;
+        return parseManifest(interpolate(document, source.env ?? {}, source.env ? at : `${at}${source.noEnv ? ` (${source.noEnv})` : ""}`), file, at, source);
+    });
+    const keys = manifests.map(manifest => manifest.key);
+    const repeated = keys.find((key, index) => keys.indexOf(key) !== index);
+    if (repeated)
+        throw new Error(`${where}: the key ${repeated} is used twice`);
+    return manifests;
+}
+/** A manifest from its parsed document, with the files it names read through `source.readFile`. */
+export function parseManifest(document, file, where = file, source = {}) {
+    if (!document || typeof document !== "object" || Array.isArray(document))
+        throw new Error(`${where}: a manifest is a mapping of fields`);
+    const { key, agents = [], systemPromptFile, ...definition } = document;
+    if (typeof key !== "string" || !KEY.test(key))
+        throw new Error(`${where}: key is required, 1 to 80 letters, digits, _ and - (the same key is the same definition)`);
+    if (typeof definition.name !== "string" || !definition.name)
+        definition.name = key;
+    const read = (field, instead, path) => {
+        if (!source.readFile)
+            throw new Error(`${where}: a hosted deploy reads no files, so ${field} cannot be used; give ${instead}, or deploy with the camelrun CLI`);
+        return source.readFile(path);
+    };
+    if (systemPromptFile !== undefined) {
+        if (definition.systemPrompt !== undefined)
+            throw new Error(`${where}: give systemPrompt or systemPromptFile, not both`);
+        definition.systemPrompt = read("systemPromptFile", "systemPrompt", String(systemPromptFile)).trim();
+    }
+    if (Array.isArray(definition.openApi)) {
+        definition.openApi = definition.openApi.map((openApi) => {
+            if (!openApi || typeof openApi !== "object" || openApi.specFile === undefined)
+                return openApi;
+            const { specFile, ...rest } = openApi;
+            if (rest.spec !== undefined)
+                throw new Error(`${where}: an openApi source takes spec or specFile, not both`);
+            const text = read("specFile", "spec", String(specFile));
+            return { ...rest, spec: /\.json$/i.test(specFile) ? JSON.parse(text) : parseYaml(text) };
+        });
+    }
+    if (!Array.isArray(agents))
+        throw new Error(`${where}: agents is a list of { key, … }`);
+    for (const agent of agents) {
+        if (!agent || typeof agent !== "object" || typeof agent.key !== "string" || !KEY.test(agent.key))
+            throw new Error(`${where}: each agent needs a key, 1 to 80 letters, digits, _ and -`);
+        if ("definition" in agent)
+            throw new Error(`${where}: agent ${agent.key} is made from this manifest's definition; leave out definition`);
+    }
+    return { key, definition, agents, file };
+}
+/** Replace `${NAME}` and `${NAME:-default}` in every string; `$${…}` is left as `${…}`. */
+export function interpolate(value, env, where) {
+    if (typeof value === "string") {
+        return value.replace(/\$(\$)?\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g, (match, escaped, name, fallback) => {
+            if (escaped)
+                return match.slice(1);
+            const found = env[name] ?? fallback;
+            if (found === undefined)
+                throw new Error(`${where}: \${${name}} is not set`);
+            return found;
+        });
+    }
+    if (Array.isArray(value))
+        return value.map(item => interpolate(item, env, where));
+    if (value && typeof value === "object")
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, interpolate(item, env, where)]));
+    return value;
+}
+export function template(key, model) {
+    return `# An agent on camelRun. Deploy it with \`camelrun deploy\`; deploying again
+# updates the definition in place (the same key is the same definition).
+# Fields: https://agents.camelai.dev/docs/guides/definitions.md
+key: ${key}
+name: ${key}
+${model ? `model: ${model}` : "# model: anthropic/claude-sonnet-5-5   # camelrun models --available lists yours"}
+systemPrompt: |
+  You are a helpful assistant. Be concise.
+# systemPromptFile: prompts/${key}.md   # or keep the prompt in its own file
+# thinkingLevel: low
+builtins: [web_fetch, web_search]
+# Remote tools. Strings can read environment variables, so credentials stay out of the file.
+# mcpServers:
+#   - name: app
+#     url: https://app.example.com/mcp
+#     auth: { type: bearer, token: "\${APP_MCP_TOKEN}" }
+# openApi:
+#   - name: billing
+#     specFile: openapi.yaml
+#     auth: { type: runtime }
+# Keyed agents to make from this definition on deploy (they live until deleted).
+agents:
+  - key: ${key}
+`;
+}

package/dist/mcp.js

@@ -0,0 +1,41 @@
+import { isAbsolute, resolve } from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { findManifest, loadManifests } from "./manifest-files.js";
+import { errorText, INSTRUCTIONS, resultText, tools } from "./tools.js";
+import { VERSION } from "./version.js";
+import { readFileSync } from "node:fs";
+/** Serve the CLI's operations as MCP tools over stdio. Credentials are read on each call, so a login takes effect at once. */
+export async function serve(api, options) {
+    const server = createServer(api, options);
+    // The transport does not notice its client going away: stdin ending is that.
+    const closed = new Promise(resolve => { server.server.onclose = resolve; process.stdin.once("end", resolve); });
+    await server.connect(new StdioServerTransport());
+    await closed;
+    await server.close();
+}
+/**
+ * The tools (tools.ts) as an MCP server, for `api`. With `cwd` it runs on the user's machine: deploy reads manifests
+ * and the files they name, and `${NAME}` reads the environment. Without it (the runtime's hosted /mcp), deploy takes
+ * the manifest's YAML only, and reads no file and no environment variable of the server's.
+ */
+export function createServer(api, options = {}) {
+    const { cwd } = options;
+    const server = new McpServer({ name: "camelrun", title: "camelRun", version: VERSION }, { instructions: INSTRUCTIONS });
+    const local = cwd === undefined ? undefined : {
+        env: process.env,
+        readFile: (path) => readFileSync(resolve(cwd, path), "utf8"),
+        load: (file) => loadManifests(file ? (isAbsolute(file) ? file : resolve(cwd, file)) : findManifest(cwd)),
+    };
+    for (const tool of tools(api, { local })) {
+        server.registerTool(tool.name, { description: tool.description, inputSchema: tool.input, annotations: tool.annotations }, (async (args) => {
+            try {
+                return { content: [{ type: "text", text: resultText(await tool.run(args)) }] };
+            }
+            catch (error) {
+                return { isError: true, content: [{ type: "text", text: errorText(error) }] };
+            }
+        }));
+    }
+    return server;
+}

package/dist/ops.js

@@ -0,0 +1,151 @@
+import { ApiError, enc } from "./api.js";
+/** Deploy manifests: upsert each definition by its key, apply it to live agents if asked, and make its keyed agents. */
+export async function deploy(api, manifests, options = {}) {
+    const results = [];
+    for (const manifest of manifests) {
+        const id = await api.definitionId(manifest.key);
+        const before = await api.get(`/v1/definitions/${id}`).catch(error => { if (error instanceof ApiError && error.status === 404)
+            return undefined; throw error; });
+        if (options.dryRun) {
+            results.push({ key: manifest.key, id, name: String(manifest.definition.name), revision: before?.revision ?? 0, status: "planned", agents: manifest.agents.map(agent => ({ key: agent.key, status: "planned" })) });
+            continue;
+        }
+        const saved = await api.call("POST", "/v1/definitions", manifest.definition, { "Idempotency-Key": manifest.key });
+        const result = {
+            key: manifest.key, id: saved.id, name: saved.name, revision: saved.revision,
+            status: !before ? "created" : before.revision === saved.revision ? "unchanged" : "updated",
+            ...(saved.toolSources ? { toolSources: saved.toolSources } : {}),
+            agents: [],
+        };
+        if (options.apply && result.status !== "created")
+            result.applied = (await api.call("PATCH", `/v1/definitions/${saved.id}`, { apply: "all" })).applied ?? [];
+        for (const { key, ...config } of manifest.agents) {
+            try {
+                const agent = await api.call("POST", "/v1/agents", { definition: saved.id, ...config }, { "Idempotency-Key": key });
+                result.agents.push({ key, id: agent.id, status: "ready", ...(agent.reconfigured ? { reconfigured: true } : {}) });
+            }
+            catch (error) {
+                result.agents.push({ key, status: "failed", error: error.message });
+            }
+        }
+        results.push(result);
+    }
+    return results;
+}
+/** The definition a manifest would send, with credentials hidden, for a dry run. */
+export function redact(value) {
+    if (Array.isArray(value))
+        return value.map(redact);
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, /^(token|apiKey|secret|password)$/i.test(key) || (key === "headers" && item && typeof item === "object") ? redactAll(item) : redact(item)]));
+    }
+    return value;
+}
+const redactAll = (value) => value && typeof value === "object" ? Object.fromEntries(Object.keys(value).map(key => [key, "***"])) : "***";
+/** A request record as a run: what it said, what it waits on, or why it failed. */
+export function summarize(agent, record) {
+    const base = { agent, requestId: record.id };
+    if (record.state !== "completed")
+        return { ...base, status: "running" };
+    const outcome = record.outcome ?? {};
+    const result = outcome.result ?? {};
+    const failure = outcome.error ? { code: outcome.uncertain ? "uncertain" : "runtime_error", message: outcome.error }
+        : result.error ? { code: result.code ?? "model_error", message: result.error }
+            : result.stopped === "spend_limit" ? { code: "spend_limit", message: "The agent reached its spend limit; raise it to go on" } : undefined;
+    const status = failure ? "failed" : result.stopped === "input_required" ? "input_required" : "completed";
+    return {
+        ...base, status,
+        ...(typeof result.reply === "string" ? { text: result.reply } : {}),
+        ...(failure ? { error: failure } : {}),
+        ...(result.inputs?.length ? { inputs: result.inputs.map((input) => ({ id: input.id, kind: input.kind, ...(input.message ? { message: input.message } : {}), detail: input.detail })) } : {}),
+        ...(result.toolErrors?.length ? { toolErrors: result.toolErrors } : {}),
+        ...(result.files?.length ? { files: result.files } : {}),
+        ...(result.usage ? { usage: result.usage } : {}),
+    };
+}
+/** Wait up to `seconds` for a request to end; a run still going then comes back `running`. */
+export async function waitFor(api, agentId, requestId, seconds, signal) {
+    const deadline = Date.now() + seconds * 1000;
+    for (let delay = 250;; delay = Math.min(delay * 1.5, 2000)) {
+        const record = await api.get(`/v1/agents/${enc(agentId)}/requests/${enc(requestId)}`);
+        if (record.state === "completed" || Date.now() + delay > deadline || signal?.aborted)
+            return summarize(agentId, record);
+        await new Promise(resolve => setTimeout(resolve, delay));
+    }
+}
+/** Send an agent a message and wait up to `wait` seconds for its run. `requestId` makes a retry the same run. */
+export async function run(api, agent, text, options = {}) {
+    const id = await api.agentId(agent);
+    const record = await api.call("POST", `/v1/agents/${enc(id)}/prompt`, {
+        text, requestId: options.requestId ?? `cli_${globalThis.crypto.randomUUID()}`, ...(options.allowDisconnected ? { allowDisconnected: true } : {}),
+        ...(options.from ? { from: { id: options.from } } : {}), ...(options.steer ? { whileRunning: "steer" } : {}),
+    });
+    return options.wait === 0 ? summarize(id, record) : waitFor(api, id, record.id, options.wait ?? Infinity, options.signal);
+}
+/** Answer an input the way the SDK does: true/false for an approval, text or { question: answer } for questions, fields for a form. */
+export async function answer(api, agent, inputId, value, options = {}) {
+    const id = await api.agentId(agent);
+    const inputs = await api.get(`/v1/agents/${enc(id)}/inputs`);
+    const input = inputs.find(item => item.id === inputId);
+    if (!input)
+        throw new ApiError(404, `No input ${inputId} on ${agent}`);
+    const body = { ...answerFor(input, value), ...(options.from ? { from: { id: options.from } } : {}) };
+    const answered = await api.call("POST", `/v1/agents/${enc(id)}/inputs/${enc(inputId)}`, body);
+    if (!answered.request)
+        return { agent: id, input: inputId, status: "answered", note: "Other inputs of this run still wait; it resumes once they are answered" };
+    return options.wait === 0 ? summarize(id, answered.request) : waitFor(api, id, answered.request.id, options.wait ?? Infinity);
+}
+function answerFor(input, value) {
+    if (value === "decline" || (value === false && input.kind !== "approval" && input.kind !== "url"))
+        return { action: "decline" };
+    switch (input.kind) {
+        case "approval":
+        case "url":
+            if (typeof value !== "boolean")
+                throw new Error(`Answer ${input.kind === "approval" ? "an approval" : "a url step"} with true or false`);
+            return { action: value ? "accept" : "decline" };
+        case "question": {
+            const questions = input.detail?.questions ?? [];
+            if (typeof value === "string" || Array.isArray(value)) {
+                if (questions.length !== 1)
+                    throw new Error(`This input asks ${questions.length} questions: answer with {"<question>": "<answer>"} for each`);
+                return { action: "accept", content: { answers: { [questions[0].question]: value } } };
+            }
+            return { action: "accept", content: { answers: value } };
+        }
+        default: return { action: "accept", content: value };
+    }
+}
+/** An agent's recent messages, flattened to role and text (tool calls by name), oldest first. */
+export async function history(api, agent, limit = 20) {
+    const id = await api.agentId(agent);
+    const page = await api.get(`/v1/agents/${enc(id)}/history?limit=${Math.max(1, Math.min(500, limit))}`);
+    return { agent: id, total: page.total, messages: page.entries.map((entry) => ({ index: entry.index, ...flatten(entry.message) })) };
+}
+function flatten(message) {
+    const content = typeof message.content === "string" ? [{ type: "text", text: message.content }] : message.content ?? [];
+    const text = content.filter((part) => part.type === "text").map((part) => part.text).join("");
+    const calls = content.filter((part) => part.type === "toolCall").map((part) => ({ name: part.name, arguments: part.arguments }));
+    return {
+        role: message.role,
+        ...(message.toolName ? { tool: message.toolName } : {}),
+        ...(message.from ? { from: message.from.id } : {}),
+        ...(text ? { text: message.role === "toolResult" && text.length > 2000 ? `${text.slice(0, 2000)}…` : text } : {}),
+        ...(calls.length ? { toolCalls: calls } : {}),
+        ...(message.isError ? { isError: true } : {}),
+        ...(message.errorMessage ? { error: message.errorMessage } : {}),
+    };
+}
+/** An agent for `key` made (or found) outside a manifest: from a definition, or with its own model and prompt. */
+export async function upsertAgent(api, key, config) {
+    const { definition, ...rest } = config;
+    const body = { ...(definition ? { definition: await api.definitionId(definition) } : {}), ...Object.fromEntries(Object.entries(rest).filter(([, value]) => value !== undefined)) };
+    const created = await api.call("POST", "/v1/agents", body, { "Idempotency-Key": key });
+    return { key, id: created.id, expiresAt: created.expiresAt, ...(created.reconfigured ? { reconfigured: true } : {}) };
+}
+/** Change one agent's model, prompt or thinking level between its runs, and wait up to `wait` seconds for it to land. */
+export async function configure(api, agent, changes, wait = 30) {
+    const id = await api.agentId(agent);
+    const record = await api.call("PATCH", `/v1/agents/${enc(id)}/configuration`, { requestId: `cli_${globalThis.crypto.randomUUID()}`, ...changes });
+    return waitFor(api, id, record.id, wait);
+}

package/dist/tools.js

@@ -0,0 +1,141 @@
+import { z } from "zod";
+import { enc } from "./api.js";
+import { parseManifests } from "./manifest.js";
+import * as ops from "./ops.js";
+export const INSTRUCTIONS = `Deploy and manage agents on camelRun (https://agents.camelai.dev).
+
+- An agent is durable and keyed: the same key is the same agent, with its history, until deleted. Tools take an agent's key or its id (client_…).
+- A definition is a reusable configuration (model, system prompt, built-ins, MCP servers, OpenAPI specs). Keep it in the repository as agent.yaml and deploy it with deploy: the same key is the same definition, and deploying again makes a new revision. apply: true also moves live agents to it between their turns.
+- run_agent sends a message and waits up to wait seconds. A run still going comes back with status "running": call get_run with its requestId. A run with status "input_required" waits on a person: show them its inputs, then answer_input.
+- read_docs reads the runtime's documentation (the manifest's fields are in guides/definitions.md).`;
+const agent = z.string().describe("The agent's key, or its id (client_…)");
+const definition = z.string().describe("The definition's key, or its id (def_…)");
+const wait = z.number().min(0).max(300).optional().describe("Seconds to wait for the run to end (default 50); a run still going comes back as running");
+/** Every tool, for `api`. */
+export function tools(api, options = {}) {
+    const list = [];
+    const tool = (name, description, input, run, annotations = {}) => {
+        list.push({ name, description, input, annotations, run });
+    };
+    const read = { readOnlyHint: true };
+    tool("whoami", "The tenant the API key belongs to, the runtime's URL and the default model.", {}, async () => {
+        const client = api();
+        return { ...await client.me(), url: client.url };
+    }, read);
+    tool("list_models", "Models agents can use: pass a model's id as `model`.", { available: z.boolean().optional().describe("Only models the account has a key for (default true)") }, async ({ available }) => {
+        const models = await api().get(`/v1/models${available === false ? "" : "?available=true"}`);
+        return models.map(({ id, name, contextWindow, reasoning, cost, available }) => ({ id, name, available, contextWindow, reasoning, cost }));
+    }, read);
+    const local = options.local;
+    const hosted = !local;
+    tool("deploy", "Deploy agent manifests: upsert each definition by its key (a new revision only when it changed) and make the keyed agents it lists. " +
+        (hosted
+            ? "Give `manifest`, the YAML itself (as an agent.yaml holds it). This server reads no files and no environment variables: put the system prompt in systemPrompt and any OpenAPI spec in spec."
+            : "Give `file` (a path to an agent.yaml; default ./agent.yaml) or `manifest` (the YAML itself). `${NAME}` in strings reads this server's environment."), {
+        ...(hosted ? {} : { file: z.string().optional().describe("Path to the manifest, relative to the working directory") }),
+        manifest: hosted ? z.string().describe("The manifest's YAML") : z.string().optional().describe("The manifest's YAML, instead of a file"),
+        apply: z.boolean().optional().describe("Also move live agents made from the definition to the new revision, between their turns"),
+        dryRun: z.boolean().optional().describe("Show what would be deployed, credentials hidden, without changing anything"),
+    }, async (args) => {
+        const { file, manifest, apply, dryRun } = args;
+        if (file && manifest)
+            throw new Error("Give file or manifest, not both");
+        const manifests = manifest !== undefined
+            ? parseManifests(manifest, "manifest", local
+                ? { env: local.env, readFile: local.readFile }
+                : { noEnv: "a hosted deploy reads no environment variables: write the value in, or deploy with the camelrun CLI" })
+            : local.load(file);
+        const results = await ops.deploy(api(), manifests, { apply, dryRun });
+        return dryRun ? results.map((result, index) => ({ ...result, definition: ops.redact(manifests[index].definition) })) : results;
+    });
+    tool("list_definitions", "The account's definitions.", {}, async () => {
+        const list = await api().get("/v1/definitions");
+        return list.map(({ id, name, revision, model, builtins, updatedAt }) => ({ id, name, revision, model, builtins, updatedAt }));
+    }, read);
+    tool("get_definition", "A definition in full: model, prompt, built-ins and tool sources (never their credentials).", { definition }, async ({ definition }) => {
+        const client = api();
+        return client.get(`/v1/definitions/${await client.definitionId(definition)}`);
+    }, read);
+    tool("definition_agents", "The agents made from a definition, and the revision each has.", { definition }, async ({ definition }) => {
+        const client = api();
+        return client.get(`/v1/definitions/${await client.definitionId(definition)}/agents`);
+    }, read);
+    tool("delete_definition", "Delete a definition. Its agents are left as they are.", { definition }, async ({ definition }) => {
+        const client = api();
+        return client.call("DELETE", `/v1/definitions/${await client.definitionId(definition)}`);
+    }, { destructiveHint: true });
+    tool("list_agents", "The account's agents: key, id, model, and whether each is running.", {}, () => api().get("/v1/agents"), read);
+    tool("get_agent", "An agent's configuration, the definition revision it has, and every source of its tools with what each offers.", { agent }, async ({ agent }) => {
+        const client = api();
+        return client.get(`/v1/agents/${enc(await client.agentId(agent))}`);
+    }, read);
+    tool("create_agent", "Make the agent for a key, or find it: from a definition, or with its own model and system prompt. The same key is the same agent; it lives until deleted.", {
+        key: z.string().regex(/^[A-Za-z0-9_-]{1,80}$/).describe("Your name for the agent: 1 to 80 letters, digits, _ and -"),
+        definition: definition.optional(),
+        model: z.string().optional().describe("A model id from list_models"),
+        systemPrompt: z.string().optional().describe("Not with a definition, which owns the prompt"),
+        systemPromptAppend: z.string().optional().describe("Text after the prompt, e.g. this agent's own context"),
+        name: z.string().optional(),
+        builtins: z.array(z.enum(["web_fetch", "web_search", "schedule", "ask_user"])).optional().describe("Without a definition: tools the runtime answers itself"),
+    }, ({ key, ...config }) => ops.upsertAgent(api(), key, config), { idempotentHint: true });
+    tool("configure_agent", "Change one agent's model, system prompt, prompt addition or thinking level between its runs; its history is kept.", {
+        agent,
+        model: z.string().optional(),
+        systemPrompt: z.string().optional(),
+        systemPromptAppend: z.string().optional().describe("\"\" removes it"),
+        thinkingLevel: z.enum(["off", "minimal", "low", "medium", "high", "xhigh", "max"]).optional(),
+    }, ({ agent, ...changes }) => {
+        const given = Object.fromEntries(Object.entries(changes).filter(([, value]) => value !== undefined));
+        if (!Object.keys(given).length)
+            throw new Error("Nothing to change");
+        return ops.configure(api(), agent, given);
+    });
+    tool("delete_agent", "Delete an agent: it stops at once, and its history and files are purged. Its key makes a fresh agent next time.", { agent }, async ({ agent }) => {
+        const client = api();
+        return client.call("DELETE", `/v1/agents/${enc(await client.agentId(agent))}`);
+    }, { destructiveHint: true });
+    tool("run_agent", "Send an agent a message and wait for its run: the reply, the input it waits on, or why it failed. A run still going after `wait` seconds comes back as running; call get_run.", {
+        agent, message: z.string(), wait,
+        from: z.string().optional().describe("Who is sending, as a user id in the application"),
+        steer: z.boolean().optional().describe("If a run is going, have it read this after its current step instead of queuing it"),
+        allowDisconnected: z.boolean().optional().describe("Run even though the application serving its attached tools is not connected; those calls then fail"),
+        requestId: z.string().optional().describe("Retrying with the same id is the same run"),
+    }, ({ agent, message, wait, ...options }) => ops.run(api(), agent, message, { ...options, wait: wait ?? 50 }));
+    tool("get_run", "A run's status and result, waiting up to `wait` seconds for it to end.", { agent, requestId: z.string(), wait }, async ({ agent, requestId, wait }) => {
+        const client = api();
+        return ops.waitFor(client, await client.agentId(agent), requestId, wait ?? 50);
+    }, read);
+    tool("agent_history", "An agent's latest messages, in whole turns: text, tool calls and tool results.", { agent, limit: z.number().int().min(1).max(500).optional().describe("Default 20") }, ({ agent, limit }) => ops.history(api(), agent, limit), read);
+    tool("abort_agent", "Stop an agent's running turn.", { agent }, async ({ agent }) => {
+        const client = api();
+        return client.call("POST", `/v1/agents/${enc(await client.agentId(agent))}/abort`, {});
+    });
+    tool("list_inputs", "Questions, approvals and forms waiting on a person: one agent's, or every agent's.", { agent: agent.optional() }, async ({ agent }) => {
+        const client = api();
+        return agent ? client.get(`/v1/agents/${enc(await client.agentId(agent))}/inputs?state=pending`) : client.get("/v1/inputs?state=pending");
+    }, read);
+    tool("answer_input", "Answer an input and wait for the run it resumes. An approval takes true or false; a question the chosen label or your own words (several questions: {\"<question>\": \"<answer>\"}); a form its fields; \"decline\" declines. Only answer with what the person decided.", { agent, inputId: z.string(), value: z.union([z.boolean(), z.string(), z.array(z.string()), z.record(z.string(), z.unknown())]), from: z.string().optional().describe("Who is answering, as a user id in the application"), wait }, ({ agent, inputId, value, from, wait }) => ops.answer(api(), agent, inputId, value, { from, wait: wait ?? 50 }));
+    tool("list_schedules", "An agent's scheduled wake-ups.", { agent }, async ({ agent }) => {
+        const client = api();
+        return client.get(`/v1/agents/${enc(await client.agentId(agent))}/schedules`);
+    }, read);
+    tool("add_schedule", "Wake an agent later with a message: once (inSeconds or at), or repeatedly (everySeconds, at least 60).", {
+        agent, text: z.string(),
+        inSeconds: z.number().optional(), at: z.string().optional().describe("ISO time"), everySeconds: z.number().int().min(60).optional(),
+    }, async ({ agent, ...schedule }) => {
+        const client = api();
+        return client.call("POST", `/v1/agents/${enc(await client.agentId(agent))}/schedules`, schedule);
+    });
+    tool("delete_schedule", "Cancel a scheduled wake-up.", { agent, scheduleId: z.string() }, async ({ agent, scheduleId }) => {
+        const client = api();
+        return client.call("DELETE", `/v1/agents/${enc(await client.agentId(agent))}/schedules/${enc(scheduleId)}`);
+    }, { destructiveHint: true });
+    tool("read_docs", "The runtime's documentation as Markdown: with no path, the index (llms.txt); else a page such as guides/definitions.md, guides/tools.md or reference/cli.md.", {
+        path: z.string().regex(/^(?!.*\.\.)[A-Za-z0-9/_.-]*$/).optional(),
+    }, ({ path }) => api().text(path ? `/docs/${path.replace(/^\/?(docs\/)?/, "")}` : "/llms.txt"), read);
+    return list;
+}
+/** A tool's result as text, as MCP and WebMCP clients take it. */
+export const resultText = (result) => typeof result === "string" ? result : JSON.stringify(result, null, 2);
+/** An error as the model should read it: the HTTP status, when there was one, and the message. */
+export const errorText = (error) => `${error?.status ? `${error.status}: ` : ""}${error.message}`;

package/dist/version.js

@@ -0,0 +1,2 @@
+import { readFileSync } from "node:fs";
+export const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;

package/package.json

@@ -1 +1,37 @@
-{"name":"@camelai/camelrun","version":"0.0.0","license":"MIT"}
+{
+  "name": "@camelai/camelrun",
+  "version": "0.11.0",
+  "description": "camelRun CLI: deploy and manage agents on camelRun from a terminal, or from a coding agent over MCP (camelrun mcp).",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/qaml-ai/run.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://agents.camelai.dev",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "bin": {
+    "camelrun": "dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && chmod +x dist/bin.js",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.1",
+    "yaml": "^2.9.0",
+    "zod": "^4.6.5"
+  }
+}