callman-mcp 0.1.0

package/dist-cjs/client/api.js

@@ -0,0 +1,183 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CallmanApi = void 0;
+// Typed endpoint functions — one per backend route the tools use. Thin on
+// purpose: no business rules here, only paths, headers and shapes. `ws` is
+// the workspace id for workspace-scoped routes.
+class CallmanApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    // ── identity ────────────────────────────────────────────────────────
+    me() {
+        return this.http.request("GET", "/personal-tokens/me");
+    }
+    features() {
+        return this.http.request("GET", "/features");
+    }
+    // ── workspaces ──────────────────────────────────────────────────────
+    listWorkspaces() {
+        return this.http.request("GET", "/workspaces");
+    }
+    listMembers(workspaceId) {
+        return this.http.request("GET", `/workspaces/${workspaceId}/members`);
+    }
+    addMember(workspaceId, body) {
+        return this.http.request("POST", `/workspaces/${workspaceId}/members`, { body });
+    }
+    removeMember(workspaceId, memberId) {
+        return this.http.request("DELETE", `/workspaces/${workspaceId}/members/${memberId}`);
+    }
+    // ── collections / folders ───────────────────────────────────────────
+    listCollections(ws, page = 1, limit = 100) {
+        return this.http.request("GET", "/collections", { workspaceId: ws, query: { page, limit } });
+    }
+    async listAllCollections(ws) {
+        const out = [];
+        let page = 1;
+        for (;;) {
+            const result = await this.listCollections(ws, page, 100);
+            out.push(...result.items);
+            if (page >= result.pagination.totalPages || result.items.length === 0)
+                break;
+            page += 1;
+            if (page > 50)
+                break; // 5 000 collections — more than any workspace has
+        }
+        return out;
+    }
+    getCollection(ws, id) {
+        return this.http.request("GET", `/collections/${id}`, { workspaceId: ws });
+    }
+    createCollection(ws, body) {
+        return this.http.request("POST", "/collections", { workspaceId: ws, body });
+    }
+    updateCollection(ws, id, body) {
+        return this.http.request("PATCH", `/collections/${id}`, { workspaceId: ws, body });
+    }
+    deleteCollection(ws, id) {
+        return this.http.request("DELETE", `/collections/${id}`, { workspaceId: ws });
+    }
+    folderTree(ws, collectionId) {
+        return this.http.request("GET", `/folders/tree/${collectionId}`, { workspaceId: ws });
+    }
+    createFolder(ws, body) {
+        return this.http.request("POST", "/folders", { workspaceId: ws, body });
+    }
+    updateFolder(ws, id, body) {
+        return this.http.request("PATCH", `/folders/${id}`, { workspaceId: ws, body });
+    }
+    deleteFolder(ws, id) {
+        return this.http.request("DELETE", `/folders/${id}`, { workspaceId: ws });
+    }
+    exportCollection(ws, id, type) {
+        return this.http.request("GET", `/export/${id}`, { workspaceId: ws, query: { type } });
+    }
+    // ── requests ────────────────────────────────────────────────────────
+    requestTree(ws, collectionId) {
+        return this.http.request("GET", "/requests/tree", { workspaceId: ws, query: { collectionId } });
+    }
+    getRequest(ws, id) {
+        return this.http.request("GET", `/requests/${id}`, { workspaceId: ws });
+    }
+    createRequest(ws, body) {
+        return this.http.request("POST", "/requests", { workspaceId: ws, body });
+    }
+    updateRequest(ws, id, body) {
+        return this.http.request("PATCH", `/requests/${id}`, { workspaceId: ws, body });
+    }
+    deleteRequest(ws, id) {
+        return this.http.request("DELETE", `/requests/${id}`, { workspaceId: ws });
+    }
+    // ── import ──────────────────────────────────────────────────────────
+    importJson(ws, body) {
+        return this.http.request("POST", "/import/json", { workspaceId: ws, body, timeoutMs: 120_000 });
+    }
+    importScenario(ws, body) {
+        return this.http.request("POST", "/import/scenario", { workspaceId: ws, body, timeoutMs: 120_000 });
+    }
+    // ── environments / globals ──────────────────────────────────────────
+    listEnvironments(ws, reveal = false) {
+        return this.http.request("GET", "/environments", {
+            workspaceId: ws,
+            query: { page: 1, limit: 100, ...(reveal ? { reveal: "true" } : {}) },
+        });
+    }
+    getEnvironment(ws, id, reveal = false) {
+        return this.http.request("GET", `/environments/${id}`, { workspaceId: ws, query: reveal ? { reveal: "true" } : {} });
+    }
+    createEnvironment(ws, body) {
+        return this.http.request("POST", "/environments", { workspaceId: ws, body });
+    }
+    deleteEnvironment(ws, id) {
+        return this.http.request("DELETE", `/environments/${id}`, { workspaceId: ws });
+    }
+    addEnvironmentVariable(ws, id, body) {
+        return this.http.request("POST", `/environments/${id}/variables`, { workspaceId: ws, body });
+    }
+    updateEnvironmentVariable(ws, id, key, body) {
+        return this.http.request("PATCH", `/environments/${id}/variables/${encodeURIComponent(key)}`, { workspaceId: ws, body });
+    }
+    deleteEnvironmentVariable(ws, id, key) {
+        return this.http.request("DELETE", `/environments/${id}/variables/${encodeURIComponent(key)}`, { workspaceId: ws });
+    }
+    listGlobalVariables(ws, reveal = false) {
+        return this.http.request("GET", "/variables/global", { workspaceId: ws, query: reveal ? { reveal: "true" } : {} });
+    }
+    // ── scenarios ───────────────────────────────────────────────────────
+    listScenarios(ws) {
+        return this.http.request("GET", "/scenarios", { workspaceId: ws });
+    }
+    listScenarioFolders(ws) {
+        return this.http.request("GET", "/scenario-folders", { workspaceId: ws });
+    }
+    getScenario(ws, id, reveal = false) {
+        return this.http.request("GET", `/scenarios/${id}`, { workspaceId: ws, query: reveal ? { reveal: "true" } : {} });
+    }
+    createScenario(ws, body) {
+        return this.http.request("POST", "/scenarios", { workspaceId: ws, body });
+    }
+    patchScenario(ws, id, body) {
+        return this.http.request("PATCH", `/scenarios/${id}`, { workspaceId: ws, body });
+    }
+    deleteScenario(ws, id) {
+        return this.http.request("DELETE", `/scenarios/${id}`, { workspaceId: ws });
+    }
+    runScenario(ws, id, body) {
+        return this.http.request("POST", `/scenarios/${id}/run-server`, { workspaceId: ws, body });
+    }
+    listScenarioReports(ws, id, limit = 20) {
+        return this.http.request("GET", `/scenarios/${id}/reports`, { workspaceId: ws, query: { page: 1, limit } });
+    }
+    getScenarioReport(ws, id, reportId) {
+        return this.http.request("GET", `/scenarios/${id}/reports/${reportId}`, { workspaceId: ws });
+    }
+    // ── diagrams (user-owned, not workspace-scoped) ─────────────────────
+    listDiagrams() {
+        return this.http.request("GET", "/diagrams");
+    }
+    getDiagram(id) {
+        return this.http.request("GET", `/diagrams/${id}`);
+    }
+    createDiagram(body) {
+        return this.http.request("POST", "/diagrams", { body });
+    }
+    updateDiagram(id, body) {
+        return this.http.request("PUT", `/diagrams/${id}`, { body });
+    }
+    deleteDiagram(id) {
+        return this.http.request("DELETE", `/diagrams/${id}`);
+    }
+    shareDiagram(id, body) {
+        return this.http.request("POST", `/diagrams/${id}/share`, { body });
+    }
+    // ── local run bundle ────────────────────────────────────────────────
+    pipelineBundle(ws, collectionId, environmentId) {
+        return this.http.request("GET", "/pipeline/bundle", {
+            workspaceId: ws,
+            query: { collectionId, ...(environmentId ? { environmentId } : {}) },
+        });
+    }
+}
+exports.CallmanApi = CallmanApi;

package/dist-cjs/client/errors.js

@@ -0,0 +1,104 @@
+"use strict";
+// Errors from the Callman API, carrying the backend's error code so tools can
+// turn them into actionable text for the model (see `hintFor`).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hintFor = exports.ToolInputError = exports.CallmanNetworkError = exports.CallmanApiError = void 0;
+class CallmanApiError extends Error {
+    status;
+    code;
+    details;
+    method;
+    path;
+    constructor(input) {
+        super(input.message);
+        this.name = "CallmanApiError";
+        this.status = input.status;
+        this.code = input.code;
+        this.details = input.details;
+        this.method = input.method;
+        this.path = input.path;
+    }
+}
+exports.CallmanApiError = CallmanApiError;
+class CallmanNetworkError extends Error {
+    apiUrl;
+    cause;
+    constructor(apiUrl, message, cause) {
+        super(message);
+        this.name = "CallmanNetworkError";
+        this.apiUrl = apiUrl;
+        this.cause = cause;
+    }
+}
+exports.CallmanNetworkError = CallmanNetworkError;
+// Raised by tools before any API call: bad references, missing scopes known
+// up front, disabled features, ambiguous names. `data` is surfaced verbatim
+// in structuredContent so the model can act (e.g. pick a candidate).
+class ToolInputError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.name = "ToolInputError";
+        this.code = code;
+        this.data = data;
+    }
+}
+exports.ToolInputError = ToolInputError;
+const SCOPE_HINT = "Create a token with that permission in the Callman desktop app (Settings → AI tools → New token) and update the CALLMAN_TOKEN in your MCP config.";
+const hintFor = (error) => {
+    switch (error.code) {
+        case "PAT_SCOPE_MISSING": {
+            const required = Array.isArray(error.details?.required)
+                ? (error.details.required ?? []).join(" or ")
+                : "an additional scope";
+            return `The token lacks the permission ${required}. ${SCOPE_HINT}`;
+        }
+        case "PAT_ROUTE_FORBIDDEN":
+            return "This area of Callman is not available to AI tools yet (mocks, connections, history, UI tests, admin). Use the desktop app for it.";
+        case "FEATURE_DISABLED":
+            return "AI tools are switched off for this account by an administrator (feature flag mcp). Ask them to enable it in the admin panel.";
+        case "SECRET_MASKED_VALUE_REJECTED":
+            return "A masked value (••••) was sent back as if it were real. Read the value with get_environment reveal:true (needs environments:reveal) or set a new real value.";
+        case "SCENARIO_VERSION_CONFLICT":
+            return "Someone changed the scenario since it was read. Re-read it with get_scenario, reapply your change on the current version, then call update_scenario with the new expectedVersion (or force:true to overwrite).";
+        case "DIAGRAM_DOCUMENT_INVALID":
+            return "The diagram document was rejected by the server's validator; fix the listed errors (unknown component types are listed under unknownTypes — read callman://diagram/components).";
+        case "PERSONAL_TOKEN_LIMIT":
+            return "You have reached the maximum number of active personal tokens. Revoke an old one in Settings → AI tools.";
+        case "WORKSPACE_MEMBER_USER_NOT_FOUND":
+            return "No Callman account exists for that email, and the server does not send invitations. Ask the person to sign up (cloud) or sign in once (on-prem, LDAP), then add them again.";
+        case "WORKSPACE_MEMBER_EXISTS":
+            return "That person is already a member of the workspace. Use list_workspace_members to see their role.";
+        case "WORKSPACE_MEMBER_REMOVE_FORBIDDEN":
+            return "That member cannot be removed (the last owner of a workspace must stay).";
+        case "VALIDATION_ERROR":
+            return "The request body did not pass validation — check the listed fields against callman://docs/request-schema.";
+        case "WORKSPACE_ACCESS_DENIED":
+        case "WORKSPACE_NOT_FOUND":
+        case "WORKSPACE_ID_REQUIRED":
+        case "WORKSPACE_REQUIRED":
+            return "Pass `workspace` (name or id) to the tool, or set CALLMAN_WORKSPACE_ID in the MCP config. Call list_workspaces to see the options.";
+        default:
+            break;
+    }
+    switch (error.status) {
+        case 401:
+            return "The token was rejected (missing, expired or revoked). Create a new token in the Callman desktop app (Settings → AI tools) and set CALLMAN_TOKEN in your MCP config.";
+        case 403:
+            return "Your workspace role does not allow this (viewers cannot write). Ask a workspace owner for the editor role, or pick another workspace.";
+        case 404:
+            return "Nothing matched that id. Use the list_* / search_* tools to find the right item — names work as references too.";
+        case 409:
+            return "That name already exists. Pick another name or reuse the existing item (list it first).";
+        case 413:
+            return "The payload is too large for the server. Split the import or reduce the document.";
+        case 429:
+            return "Rate limit reached for this token. Wait for the Retry-After period and try again with fewer calls.";
+        default:
+            return error.status >= 500
+                ? "The Callman server returned an error. Try again; if it persists, check the server logs."
+                : "See the error details.";
+    }
+};
+exports.hintFor = hintFor;

package/dist-cjs/client/http.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CallmanHttpClient = void 0;
+const errors_js_1 = require("./errors.js");
+const log_js_1 = require("../lib/log.js");
+const isEnvelope = (value) => typeof value === "object" && value !== null && "success" in value;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+class CallmanHttpClient {
+    apiUrl;
+    token;
+    fetchImpl;
+    timeoutMs;
+    userAgent;
+    logger;
+    constructor(options) {
+        this.apiUrl = options.apiUrl.replace(/\/+$/, "");
+        this.token = options.token;
+        this.fetchImpl = options.fetch ?? globalThis.fetch;
+        this.timeoutMs = options.timeoutMs ?? 30_000;
+        this.userAgent = options.userAgent ?? "callman-mcp";
+        this.logger = options.logger ?? log_js_1.silentLogger;
+    }
+    get hasToken() {
+        return Boolean(this.token);
+    }
+    buildUrl(path, query) {
+        const url = new URL(`${this.apiUrl}/api${path.startsWith("/") ? path : `/${path}`}`);
+        for (const [key, value] of Object.entries(query ?? {})) {
+            if (value === undefined || value === null)
+                continue;
+            url.searchParams.set(key, String(value));
+        }
+        return url.toString();
+    }
+    async request(method, path, options = {}) {
+        const { status, data } = await this.requestRaw(method, path, options);
+        if (status === 204)
+            return undefined;
+        return data;
+    }
+    async requestRaw(method, path, options = {}) {
+        const url = this.buildUrl(path, options.query);
+        const retries = options.retries ?? (method === "GET" ? 2 : 0);
+        let attempt = 0;
+        for (;;) {
+            try {
+                return await this.once(method, path, url, options);
+            }
+            catch (error) {
+                const retryable = error instanceof errors_js_1.CallmanNetworkError ||
+                    (error instanceof errors_js_1.CallmanApiError && error.status >= 500 && error.status !== 501);
+                if (!retryable || attempt >= retries)
+                    throw error;
+                attempt += 1;
+                this.logger.debug(`retrying ${method} ${path} (attempt ${attempt + 1})`);
+                await sleep(200 * attempt);
+            }
+        }
+    }
+    async once(method, path, url, options) {
+        const headers = {
+            Accept: "application/json",
+            "User-Agent": this.userAgent,
+        };
+        if (this.token)
+            headers.Authorization = `Bearer ${this.token}`;
+        if (options.workspaceId)
+            headers["x-workspace-id"] = options.workspaceId;
+        if (options.body !== undefined)
+            headers["Content-Type"] = "application/json";
+        let response;
+        try {
+            response = await this.fetchImpl(url, {
+                method,
+                headers,
+                body: options.body === undefined ? undefined : JSON.stringify(options.body),
+                signal: AbortSignal.timeout(options.timeoutMs ?? this.timeoutMs),
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new errors_js_1.CallmanNetworkError(this.apiUrl, `Could not reach ${this.apiUrl} (${message}). Check CALLMAN_API_URL — on-prem servers need the same address the desktop app uses, reachable from this machine.`, error);
+        }
+        let parsed = null;
+        const text = await response.text();
+        if (text) {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = null;
+            }
+        }
+        if (!response.ok) {
+            const envelope = isEnvelope(parsed) ? parsed : null;
+            const retryAfter = response.headers.get("retry-after");
+            throw new errors_js_1.CallmanApiError({
+                status: response.status,
+                code: envelope?.code ?? (response.status === 404 && !envelope ? "ROUTE_NOT_FOUND" : `HTTP_${response.status}`),
+                message: envelope?.message ?? envelope?.error ?? `HTTP ${response.status}`,
+                details: retryAfter ? { ...(asRecord(envelope?.details) ?? {}), retryAfterSeconds: Number(retryAfter) } : envelope?.details,
+                method,
+                path,
+            });
+        }
+        if (response.status === 204 || parsed === null)
+            return { status: response.status, data: null };
+        if (!isEnvelope(parsed))
+            return { status: response.status, data: parsed };
+        if (parsed.success === false) {
+            throw new errors_js_1.CallmanApiError({
+                status: response.status,
+                code: parsed.code ?? "UNEXPECTED_FAILURE",
+                message: parsed.message ?? parsed.error ?? "Request failed",
+                details: parsed.details,
+                method,
+                path,
+            });
+        }
+        return { status: response.status, data: parsed.data ?? null };
+    }
+}
+exports.CallmanHttpClient = CallmanHttpClient;
+const asRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;

package/dist-cjs/client/types.js

@@ -0,0 +1,5 @@
+"use strict";
+// Backend response shapes the server reads. Mirrors the frozen fields of the
+// Callman REST API (callman-backend `.claude/API_CONVENTIONS.md`) — additive
+// fields are optional so older servers still parse.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist-cjs/config.js

@@ -0,0 +1,73 @@
+"use strict";
+// Configuration for the callman-mcp server, resolved ONCE at startup from
+// environment variables (the only host-specific input) and frozen. Every
+// other module reads the resolved object — never process.env — so the same
+// tool layer can be hosted by the backend later with a different source.
+//
+//   CALLMAN_API_URL         server ORIGIN (https://api.callman.io, or the
+//                           on-prem address incl. any prefix); `/api` is
+//                           appended here, exactly like callme-cli.
+//   CALLMAN_TOKEN           personal token (cm_pat_…) from Settings → AI tools
+//   CALLMAN_TOKEN_FILE      alternative: path of a file holding the token
+//   CALLMAN_WORKSPACE_ID    default workspace (optional — tools resolve it)
+//   CALLMAN_ALLOW_RUN       "0"/"false" disables local request execution
+//   CALLMAN_LOG_LEVEL       silent | error | warn | info | debug (stderr)
+//   CALLMAN_TIMEOUT_MS      per API call (default 30s)
+//   CALLMAN_RUN_TIMEOUT_MS  whole local run (default 10 min)
+//   CALLMAN_MAX_BODY_BYTES  response-body preview cap in run output (16 KB)
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveConfig = exports.normalizeApiUrl = exports.MAX_BODY_BYTES_LIMIT = exports.DEFAULT_CLOUD_API_URL = void 0;
+exports.DEFAULT_CLOUD_API_URL = "https://api.callman.io";
+const LOG_LEVELS = ["silent", "error", "warn", "info", "debug"];
+exports.MAX_BODY_BYTES_LIMIT = 256 * 1024;
+const pick = (...candidates) => {
+    for (const candidate of candidates) {
+        if (typeof candidate === "string" && candidate.trim() !== "")
+            return candidate.trim();
+    }
+    return null;
+};
+const numberOr = (raw, fallback, min, max) => {
+    const parsed = raw === undefined ? NaN : Number(raw);
+    if (!Number.isFinite(parsed))
+        return fallback;
+    return Math.min(max, Math.max(min, Math.floor(parsed)));
+};
+const boolOr = (raw, fallback) => {
+    if (raw === undefined || raw.trim() === "")
+        return fallback;
+    return !["0", "false", "no", "off"].includes(raw.trim().toLowerCase());
+};
+const normalizeApiUrl = (raw) => {
+    let url = raw.trim().replace(/\/+$/, "");
+    // Accept the desktop's VITE_API_URL form (…/api) too — the client appends /api.
+    url = url.replace(/\/api$/i, "");
+    if (!/^https?:\/\//i.test(url)) {
+        throw new Error(`CALLMAN_API_URL must start with http:// or https:// (got "${raw}")`);
+    }
+    return url;
+};
+exports.normalizeApiUrl = normalizeApiUrl;
+const resolveConfig = ({ env, readTokenFile }) => {
+    const apiUrl = (0, exports.normalizeApiUrl)(pick(env.CALLMAN_API_URL) ?? exports.DEFAULT_CLOUD_API_URL);
+    let token = pick(env.CALLMAN_TOKEN);
+    const tokenFile = pick(env.CALLMAN_TOKEN_FILE);
+    if (!token && tokenFile) {
+        if (!readTokenFile)
+            throw new Error("CALLMAN_TOKEN_FILE is set but no file reader is available");
+        token = readTokenFile(tokenFile).trim() || null;
+    }
+    const logLevelRaw = (pick(env.CALLMAN_LOG_LEVEL) ?? "warn").toLowerCase();
+    const logLevel = LOG_LEVELS.includes(logLevelRaw) ? logLevelRaw : "warn";
+    return Object.freeze({
+        apiUrl,
+        token,
+        defaultWorkspaceId: pick(env.CALLMAN_WORKSPACE_ID),
+        allowLocalRun: boolOr(env.CALLMAN_ALLOW_RUN, true),
+        logLevel,
+        timeoutMs: numberOr(env.CALLMAN_TIMEOUT_MS, 30_000, 1_000, 600_000),
+        runTimeoutMs: numberOr(env.CALLMAN_RUN_TIMEOUT_MS, 600_000, 1_000, 3_600_000),
+        maxBodyBytes: numberOr(env.CALLMAN_MAX_BODY_BYTES, 16 * 1024, 256, exports.MAX_BODY_BYTES_LIMIT),
+    });
+};
+exports.resolveConfig = resolveConfig;

package/dist-cjs/context.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createToolContext = void 0;
+const api_js_1 = require("./client/api.js");
+const errors_js_1 = require("./client/errors.js");
+const http_js_1 = require("./client/http.js");
+const cache_js_1 = require("./lib/cache.js");
+const ids_js_1 = require("./lib/ids.js");
+const log_js_1 = require("./lib/log.js");
+const createToolContext = (options) => {
+    const logger = options.logger ?? log_js_1.silentLogger;
+    const http = new http_js_1.CallmanHttpClient({
+        apiUrl: options.config.apiUrl,
+        token: options.config.token,
+        fetch: options.fetch,
+        timeoutMs: options.config.timeoutMs,
+        userAgent: `callman-mcp/${options.version}`,
+        logger,
+    });
+    const api = new api_js_1.CallmanApi(http);
+    const cache = new cache_js_1.TtlCache(options.cacheTtlMs ?? 15_000);
+    let runLock = Promise.resolve();
+    const listWorkspaces = () => cache.getOrSet("workspaces", () => api.listWorkspaces());
+    const pickWorkspace = async (explicit, required) => {
+        const workspaces = await listWorkspaces();
+        const wanted = (explicit ?? "").trim() || options.config.defaultWorkspaceId || "";
+        if (wanted) {
+            const byId = workspaces.find((workspace) => workspace.id === wanted);
+            if (byId)
+                return byId;
+            const needle = (0, ids_js_1.normalizeName)(wanted);
+            const byName = workspaces.filter((workspace) => (0, ids_js_1.normalizeName)(workspace.name) === needle);
+            if (byName.length === 1)
+                return byName[0];
+            const byPartial = workspaces.filter((workspace) => (0, ids_js_1.normalizeName)(workspace.name).includes(needle));
+            if (byName.length === 0 && byPartial.length === 1)
+                return byPartial[0];
+            if ((0, ids_js_1.isObjectId)(wanted) && explicit) {
+                // A well-formed id that is not in the list: let the server answer
+                // (it may be a workspace the user was just added to).
+                return { id: wanted, name: wanted, role: "viewer" };
+            }
+            if (!required)
+                return null;
+            throw new errors_js_1.ToolInputError(byName.length > 1 || byPartial.length > 1 ? "WORKSPACE_AMBIGUOUS" : "WORKSPACE_NOT_FOUND", byName.length > 1 || byPartial.length > 1
+                ? `Several workspaces match "${wanted}". Pass the id instead.`
+                : `No workspace matches "${wanted}".`, { candidates: summarize(byPartial.length > 0 ? byPartial : workspaces) });
+        }
+        if (workspaces.length === 1)
+            return workspaces[0];
+        if (!required)
+            return null;
+        throw new errors_js_1.ToolInputError(workspaces.length === 0 ? "WORKSPACE_NONE" : "WORKSPACE_REQUIRED", workspaces.length === 0
+            ? "You are not a member of any workspace."
+            : "Several workspaces are available — pass `workspace` (name or id) or set CALLMAN_WORKSPACE_ID.", { candidates: summarize(workspaces) });
+    };
+    return {
+        config: options.config,
+        api,
+        logger,
+        cache,
+        version: options.version,
+        listWorkspaces,
+        getTokenScopes: () => cache.getOrSet("token-scopes", async () => {
+            try {
+                return (await api.me()).token.scopes ?? [];
+            }
+            catch (error) {
+                logger.debug("could not read token scopes", error instanceof Error ? error.message : error);
+                return [];
+            }
+        }),
+        resolveWorkspace: async (explicit) => (await pickWorkspace(explicit, true)),
+        resolveWorkspaceOrNull: (explicit) => pickWorkspace(explicit, false),
+        withRunLock: async (fn) => {
+            const previous = runLock;
+            let release = () => { };
+            runLock = new Promise((resolve) => {
+                release = resolve;
+            });
+            try {
+                await previous.catch(() => undefined);
+                return await fn();
+            }
+            finally {
+                release();
+            }
+        },
+        invalidate: (prefix) => (prefix ? cache.delete(prefix) : cache.clear()),
+        pollDelaysMs: options.pollDelaysMs ?? { fast: 2000, slow: 5000 },
+    };
+};
+exports.createToolContext = createToolContext;
+const summarize = (workspaces) => workspaces.slice(0, 20).map((workspace) => ({ id: workspace.id, name: workspace.name, role: workspace.role }));