@thenavidm/slipway 0.1.0

package/dist/install.d.ts

@@ -0,0 +1,98 @@
+/**
+ * `install <client>`: add this server to an MCP client's own configuration.
+ *
+ * Every client keeps its servers in a different file, in a different shape,
+ * and passes the environment on differently. Codex forwards only variables it
+ * is told to, Gemini CLI hides anything named like a key unless it is listed,
+ * and Claude Desktop sees nothing from a shell at all. Getting one of those
+ * wrong is a server that starts and then fails on its first call, so each
+ * client's shape lives here once, checked against that client's own docs.
+ *
+ * A credential is never written into a client's file unless `--copy-env`
+ * asks for it. Where a client can read a variable from its own environment,
+ * the entry names the variable instead of holding its value.
+ */
+import type { App, CliIO } from "./app.js";
+export type ClientId = "claude-code" | "codex" | "claude-desktop" | "cursor" | "vscode" | "gemini";
+export type Scope = "user" | "project";
+export declare const CLIENTS: Record<ClientId, {
+    title: string;
+    scopes: readonly Scope[];
+}>;
+/** How a client starts the server. */
+export type Launch = {
+    command: string;
+    args: string[];
+};
+export type InstallOptions = {
+    client: ClientId;
+    scope: Scope;
+    /** The key the server is listed under. Defaults to the app's name. */
+    name: string;
+    /** Copy the current values of the app's settings into the client's file. Only where a client cannot read them itself. */
+    copyEnv: boolean;
+    /** Start the server from this copy on disk rather than from npm. */
+    local: boolean;
+};
+export type InstallPlan = {
+    client: ClientId;
+    scope: Scope;
+    name: string;
+    /** The file this changes, for clients configured by file. */
+    file?: string;
+    /** The command this runs, for a client with its own command for adding servers. */
+    run?: {
+        command: string;
+        args: string[];
+    };
+    /** The entry as written. */
+    entry: unknown;
+    /** The file's full text after the change. */
+    text?: string;
+    /** Settings the client passes on from its own environment, settings copied in, and settings left for the person to add. */
+    env: {
+        forwarded: string[];
+        copied: string[];
+        toAdd: string[];
+    };
+    notes: string[];
+};
+/**
+ * How a client should start this server: the published package through npx,
+ * pinned to this version, or this copy on disk.
+ *
+ * npx needs the binary named: a package with an MCP and a CLI binary leaves
+ * npx to pick one otherwise, and the CLI started with no arguments prints its
+ * command list instead of serving.
+ */
+export declare function launchFor(app: App, options: {
+    local: boolean;
+    entry?: string;
+    platform?: NodeJS.Platform;
+}): Launch;
+/** Where each client keeps its servers, from its own documentation. */
+export declare function configFile(client: ClientId, scope: Scope, env: NodeJS.ProcessEnv, cwd: string, platform?: NodeJS.Platform): string | undefined;
+/**
+ * Put `[mcp_servers.<name>]` into a TOML file. An existing table of that name
+ * is updated in place: install's own keys are rewritten, `env_vars` keeps the
+ * names it already had, and every other key and subtable stays as written. A
+ * file that defines the server some other way is left alone, because
+ * rewriting it would mean parsing all of TOML.
+ */
+export declare function upsertCodexServer(text: string, name: string, launch: Launch, forwarded: string[], usesNpx: boolean): string;
+export declare function planInstall(app: App, options: InstallOptions, context: {
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    entry?: string;
+    platform?: NodeJS.Platform;
+}): InstallPlan;
+export type InstallResult = {
+    plan: InstallPlan;
+    backup?: string;
+    ran?: {
+        code: number;
+        output: string;
+    };
+};
+/** Write the plan's file, keeping a copy of the old one, or run the client's own command. */
+export declare function applyInstall(plan: InstallPlan, io: Pick<CliIO, "env">): Promise<InstallResult>;

package/dist/install.js

@@ -0,0 +1,325 @@
+/**
+ * `install <client>`: add this server to an MCP client's own configuration.
+ *
+ * Every client keeps its servers in a different file, in a different shape,
+ * and passes the environment on differently. Codex forwards only variables it
+ * is told to, Gemini CLI hides anything named like a key unless it is listed,
+ * and Claude Desktop sees nothing from a shell at all. Getting one of those
+ * wrong is a server that starts and then fails on its first call, so each
+ * client's shape lives here once, checked against that client's own docs.
+ *
+ * A credential is never written into a client's file unless `--copy-env`
+ * asks for it. Where a client can read a variable from its own environment,
+ * the entry names the variable instead of holding its value.
+ */
+import { execFile } from "node:child_process";
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { UsageError } from "./errors.js";
+export const CLIENTS = {
+    "claude-code": { title: "Claude Code", scopes: ["user", "project"] },
+    codex: { title: "Codex", scopes: ["user", "project"] },
+    "claude-desktop": { title: "Claude Desktop", scopes: ["user"] },
+    cursor: { title: "Cursor", scopes: ["user", "project"] },
+    vscode: { title: "VS Code", scopes: ["project"] },
+    gemini: { title: "Gemini CLI", scopes: ["user", "project"] },
+};
+/**
+ * How a client should start this server: the published package through npx,
+ * pinned to this version, or this copy on disk.
+ *
+ * npx needs the binary named: a package with an MCP and a CLI binary leaves
+ * npx to pick one otherwise, and the CLI started with no arguments prints its
+ * command list instead of serving.
+ */
+export function launchFor(app, options) {
+    const platform = options.platform ?? process.platform;
+    let launch;
+    if (app.definition.package && !options.local) {
+        launch = { command: "npx", args: ["--yes", `--package=${app.definition.package}@${app.version}`, app.bins.mcp] };
+    }
+    else {
+        const entry = options.entry ?? (process.argv[1] ? realpathSync(process.argv[1]) : undefined);
+        if (!entry)
+            throw new UsageError("Could not tell where this server is installed.", { hint: "Run install from the installed binary." });
+        launch = { command: process.execPath, args: [entry] };
+    }
+    // Windows runs npx as a batch file, which a client that starts processes without a shell cannot launch directly.
+    if (platform === "win32" && launch.command === "npx")
+        return { command: "cmd", args: ["/c", "npx", ...launch.args] };
+    return launch;
+}
+/** "A", "A and B", "A, B and C". */
+function list(names) {
+    return names.length <= 1 ? (names[0] ?? "") : `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}`;
+}
+/** "it" or "them", for a list of settings. */
+function them(names) {
+    return names.length === 1 ? "it" : "them";
+}
+function home(env) {
+    return env.HOME || env.USERPROFILE || homedir();
+}
+/** Where each client keeps its servers, from its own documentation. */
+export function configFile(client, scope, env, cwd, platform = process.platform) {
+    const h = home(env);
+    switch (client) {
+        case "codex":
+            return scope === "project" ? join(cwd, ".codex", "config.toml") : join(env.CODEX_HOME || join(h, ".codex"), "config.toml");
+        case "claude-desktop":
+            if (platform === "darwin")
+                return join(h, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+            if (platform === "win32")
+                return join(env.APPDATA || join(h, "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
+            throw new UsageError("Claude Desktop runs on macOS and Windows only.");
+        case "cursor":
+            return scope === "project" ? join(cwd, ".cursor", "mcp.json") : join(h, ".cursor", "mcp.json");
+        case "vscode":
+            return join(cwd, ".vscode", "mcp.json");
+        case "gemini":
+            return scope === "project" ? join(cwd, ".gemini", "settings.json") : join(h, ".gemini", "settings.json");
+        case "claude-code":
+            return undefined;
+    }
+}
+/** A TOML basic string. JSON's escapes are TOML's escapes for every character a command or path holds. */
+function tomlString(value) {
+    return JSON.stringify(value);
+}
+/** The keys install writes in a Codex table. Every other key, and every subtable, is the person's and stays. */
+const CODEX_KEYS = new Set(["command", "args", "env_vars", "startup_timeout_sec"]);
+function bracketDepth(text) {
+    // Brackets inside quoted strings do not count.
+    const bare = text.replace(/"(?:[^"\\]|\\.)*"|'[^']*'/g, "");
+    return (bare.match(/\[/g)?.length ?? 0) - (bare.match(/\]/g)?.length ?? 0);
+}
+function quotedStrings(text) {
+    return [...text.matchAll(/"((?:[^"\\]|\\.)*)"/g)].map((match) => JSON.parse(`"${match[1]}"`));
+}
+/**
+ * Put `[mcp_servers.<name>]` into a TOML file. An existing table of that name
+ * is updated in place: install's own keys are rewritten, `env_vars` keeps the
+ * names it already had, and every other key and subtable stays as written. A
+ * file that defines the server some other way is left alone, because
+ * rewriting it would mean parsing all of TOML.
+ */
+export function upsertCodexServer(text, name, launch, forwarded, usesNpx) {
+    const key = `(?:${escape(name)}|"${escape(name)}")`;
+    const own = new RegExp(`^\\s*\\[\\s*mcp_servers\\s*\\.\\s*${key}\\s*(?:\\]|\\.)`);
+    const header = /^\s*\[/;
+    const lines = text.split("\n");
+    let current = "";
+    for (const line of lines) {
+        if (header.test(line)) {
+            current = line.trim().replace(/\s+/g, "");
+            continue;
+        }
+        const inline = current === "[mcp_servers]" && new RegExp(`^\\s*${key}\\s*=`).test(line);
+        const dotted = current === "" && new RegExp(`^\\s*mcp_servers\\s*\\.\\s*${key}\\s*[.=]`).test(line);
+        if (inline || dotted) {
+            throw new UsageError(`This file already defines ${name} in a form install does not rewrite.`, { hint: "Edit that entry by hand, or remove it and run install again." });
+        }
+    }
+    const start = lines.findIndex((line) => own.test(line));
+    let end = start + 1;
+    if (start !== -1)
+        while (end < lines.length && !(header.test(lines[end]) && !own.test(lines[end])))
+            end++;
+    const block = start === -1 ? [] : lines.slice(start + 1, end);
+    // Split the old table into install's keys, which are replaced, and the rest, which stays.
+    const kept = [];
+    const names = new Set(forwarded);
+    let depth = 0;
+    let skippedKey = "";
+    let rest = block.length;
+    for (let i = 0; i < block.length; i++) {
+        const line = block[i];
+        if (depth > 0) {
+            if (skippedKey === "env_vars")
+                for (const value of quotedStrings(line))
+                    names.add(value);
+            depth += bracketDepth(line);
+            continue;
+        }
+        if (header.test(line)) {
+            rest = i;
+            break;
+        }
+        const match = /^\s*([A-Za-z0-9_-]+)\s*=\s*(.*)$/.exec(line);
+        if (match && CODEX_KEYS.has(match[1])) {
+            skippedKey = match[1];
+            if (skippedKey === "env_vars")
+                for (const value of quotedStrings(match[2]))
+                    names.add(value);
+            depth = Math.max(0, bracketDepth(match[2]));
+            continue;
+        }
+        kept.push(line);
+    }
+    const subtables = block.slice(rest);
+    const tableKey = /^[A-Za-z0-9_-]+$/.test(name) ? name : tomlString(name);
+    const table = [`[mcp_servers.${tableKey}]`, `command = ${tomlString(launch.command)}`, `args = [${launch.args.map(tomlString).join(", ")}]`];
+    if (names.size)
+        table.push(`env_vars = [${[...names].map(tomlString).join(", ")}]`);
+    // npx downloads the package the first time, which can outlast Codex's ten-second default.
+    if (usesNpx)
+        table.push(`startup_timeout_sec = 60`);
+    while (kept.length && kept[kept.length - 1].trim() === "")
+        kept.pop();
+    const ownLines = [...table, ...kept, ...(subtables.length ? ["", ...subtables] : [])];
+    while (ownLines.length && ownLines[ownLines.length - 1].trim() === "")
+        ownLines.pop();
+    if (start === -1) {
+        const body = text.replace(/\s*$/, "");
+        return `${body}${body ? "\n\n" : ""}${ownLines.join("\n")}\n`;
+    }
+    const after = lines.slice(end);
+    while (after.length && after[0].trim() === "")
+        after.shift();
+    return [...lines.slice(0, start), ...ownLines, ...(after.length ? ["", ...after] : [""])].join("\n");
+}
+function escape(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function readJson(file) {
+    if (!existsSync(file))
+        return {};
+    const text = readFileSync(file, "utf8");
+    if (!text.trim())
+        return {};
+    try {
+        const value = JSON.parse(text);
+        if (value && typeof value === "object" && !Array.isArray(value))
+            return value;
+    }
+    catch {
+        // Falls through to the refusal below.
+    }
+    throw new UsageError(`${file} is not plain JSON, so install will not rewrite it. It may hold comments.`, { hint: "Add the entry by hand: run install again with --dry-run to see it." });
+}
+export function planInstall(app, options, context) {
+    const { client, scope, name } = options;
+    const info = CLIENTS[client];
+    if (!info.scopes.includes(scope)) {
+        throw new UsageError(`${info.title} has no ${scope} scope here. It takes: ${info.scopes.join(", ")}.`);
+    }
+    const launch = launchFor(app, { local: options.local, ...(context.entry ? { entry: context.entry } : {}), ...(context.platform ? { platform: context.platform } : {}) });
+    const usesNpx = launch.command === "npx" || launch.args.includes("npx");
+    const settings = app.definition.settings ?? [];
+    const variables = settings.map((setting) => setting.env);
+    const env = { forwarded: [], copied: [], toAdd: [] };
+    const notes = [];
+    const file = configFile(client, scope, context.env, context.cwd, context.platform);
+    if (client === "claude-code") {
+        const entry = { type: "stdio", command: launch.command, args: launch.args };
+        if (variables.length)
+            notes.push(`Claude Code passes its own environment to the server: set ${list(variables)} in the shell you start Claude Code from.`);
+        return { client, scope, name, entry, env, notes, run: { command: "claude", args: ["mcp", "add-json", name, JSON.stringify(entry), "--scope", scope] } };
+    }
+    if (client === "codex") {
+        env.forwarded = variables;
+        const before = existsSync(file) ? readFileSync(file, "utf8") : "";
+        const text = upsertCodexServer(before, name, launch, variables, usesNpx);
+        if (variables.length)
+            notes.push(`Codex passes ${list(variables)} on from its own environment: set ${them(variables)} where you start Codex.`);
+        if (scope === "project")
+            notes.push("Codex reads a project's .codex/config.toml only once the project is trusted.");
+        const entry = upsertCodexServer("", name, launch, variables, usesNpx).trim();
+        return { client, scope, name, file, entry, text, env, notes };
+    }
+    // The JSON clients. An existing entry keeps everything install does not manage: its own env values above all.
+    const config = readJson(file);
+    const key = client === "vscode" ? "servers" : "mcpServers";
+    const servers = (config[key] && typeof config[key] === "object" && !Array.isArray(config[key]) ? config[key] : {});
+    const previous = (servers[name] && typeof servers[name] === "object" ? servers[name] : {});
+    const previousEnv = (previous.env && typeof previous.env === "object" ? previous.env : {});
+    const values = { ...previousEnv };
+    const inputs = [];
+    for (const setting of settings) {
+        const variable = setting.env;
+        if (variable in previousEnv)
+            continue;
+        if (client === "cursor")
+            values[variable] = `\${env:${variable}}`;
+        else if (client === "gemini")
+            values[variable] = `\${${variable}}`;
+        else if (client === "vscode" && setting.secret) {
+            const id = variable.toLowerCase().replace(/_/g, "-");
+            inputs.push({ type: "promptString", id, description: setting.description, password: true });
+            values[variable] = `\${input:${id}}`;
+        }
+        else if (options.copyEnv && context.env[variable]) {
+            values[variable] = context.env[variable];
+            env.copied.push(variable);
+            continue;
+        }
+        else {
+            env.toAdd.push(variable);
+            continue;
+        }
+        env.forwarded.push(variable);
+    }
+    const server = {
+        ...(client === "cursor" || client === "vscode" ? { type: "stdio" } : {}),
+        ...previous,
+        command: launch.command,
+        args: launch.args,
+        ...(Object.keys(values).length ? { env: values } : {}),
+    };
+    const next = { ...config, [key]: { ...servers, [name]: server } };
+    if (client === "vscode" && inputs.length) {
+        const existing = Array.isArray(config.inputs) ? config.inputs : [];
+        next.inputs = [...existing, ...inputs.filter((input) => !existing.some((have) => have.id === input.id))];
+    }
+    if (client === "cursor" && env.forwarded.length)
+        notes.push(`Cursor reads ${list(env.forwarded)} from its own environment.`);
+    if (client === "gemini") {
+        if (env.forwarded.length)
+            notes.push(`Gemini CLI fills ${list(env.forwarded)} from its own environment. It hides variables named like keys from servers unless an entry lists them, as this one does.`);
+        notes.push("Gemini CLI starts servers only in folders you trust.");
+    }
+    if (client === "vscode") {
+        if (inputs.length)
+            notes.push(`VS Code asks for ${list(inputs.map((input) => String(input.id)))} the first time the server starts, and stores the answer securely.`);
+        if (env.toAdd.length)
+            notes.push(`${list(env.toAdd)} ${env.toAdd.length === 1 ? "keeps its default" : "keep their defaults"}. Add ${them(env.toAdd)} to the server's env in ${file} to change ${them(env.toAdd)}.`);
+    }
+    if (client === "claude-desktop") {
+        if (env.copied.length)
+            notes.push(`Copied ${list(env.copied)} from this shell into ${file}, which is now readable by you only.`);
+        if (env.toAdd.length) {
+            notes.push(`Claude Desktop does not read a shell's environment. Add ${list(env.toAdd)} to the env of "${name}" in ${file}, or run install again with --copy-env to copy ${them(env.toAdd)} from this shell.`);
+        }
+    }
+    return { client, scope, name, file, entry: server, text: `${JSON.stringify(next, null, 2)}\n`, env, notes };
+}
+/** A timestamp for a backup file name: 20261004-183000. */
+function stamp(date = new Date()) {
+    return date.toISOString().replace(/[-:]/g, "").replace("T", "-").slice(0, 15);
+}
+/** Write the plan's file, keeping a copy of the old one, or run the client's own command. */
+export async function applyInstall(plan, io) {
+    if (plan.run) {
+        const run = plan.run;
+        const ran = await new Promise((resolve) => {
+            execFile(run.command, run.args, { env: io.env, timeout: 60_000 }, (error, stdout, stderr) => {
+                const code = error ? (typeof error.code === "number" ? Number(error.code) : 1) : 0;
+                resolve({ code: error?.code === "ENOENT" ? 127 : code, output: `${stdout}${stderr}`.trim() });
+            });
+        });
+        return { plan, ran };
+    }
+    const file = plan.file;
+    mkdirSync(dirname(file), { recursive: true });
+    let backup;
+    if (existsSync(file)) {
+        backup = `${file}.bak-${stamp()}`;
+        copyFileSync(file, backup);
+    }
+    writeFileSync(file, plan.text);
+    // A file holding a copied credential is the owner's alone, whether or not install created it.
+    if (plan.env.copied.length && process.platform !== "win32")
+        chmodSync(file, 0o600);
+    return { plan, ...(backup ? { backup } : {}) };
+}

package/dist/jobs.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Work that takes longer than a client waits for one call.
+ *
+ * Clients stop waiting on a tool after about a minute, and some much sooner,
+ * so a render, an export or a long sync cannot simply run inside the call.
+ * A job tool starts the work and waits a bounded time. A job that finishes in
+ * time comes back with its result, as any call would. One that does not comes
+ * back as a job the caller checks with a generated `<name>_status` tool, so a
+ * model never polls blind and a script never guesses at a status endpoint.
+ *
+ * Two kinds:
+ * - the service runs the job and has its own status endpoint (`id`, `status`
+ *   and `done` say how to read it), or
+ * - the handler itself is slow (`background: true`), and Slipway runs it in
+ *   this process and keeps its result for an hour.
+ */
+import { SlipwayError } from "./errors.js";
+import type { ToolContext } from "./tool.js";
+/** Progress a job reports, as MCP progress notifications carry it. */
+export type JobProgress = {
+    progress: number;
+    total?: number;
+    message?: string;
+};
+/** A job the service runs, with an endpoint that reports how it is going. */
+export type ServiceJob<Ctx = any, S = any> = {
+    /** Where the job id is in what the handler returned: a dotted path such as `id` or `job.id`, or a function. */
+    id: string | ((started: any) => string | number | undefined);
+    /** Read the job's current status from the service. */
+    status: (id: string, ctx: ToolContext<Ctx>) => S | Promise<S>;
+    /** Whether a status means the job has finished, either way. Called on what the handler returned, then on each status. */
+    done: (status: S) => boolean;
+    /** Whether a finished status means it failed. A failed job is reported as an error, with the status as its details. */
+    failed?: (status: S) => boolean;
+    /** Progress to report while a call waits, read from a status. */
+    progress?: (status: S) => JobProgress | undefined;
+    /** How often to check while waiting, in milliseconds. Defaults to 2000. */
+    pollMs?: number;
+    /** How long a call waits before handing back the job, in seconds. Defaults to 25. */
+    waitSeconds?: number;
+};
+/** A handler that is slow on its own: Slipway runs it in the background and keeps its result. */
+export type BackgroundJob = {
+    background: true;
+    /** How long a call waits before handing back the job, in seconds. Defaults to 25. */
+    waitSeconds?: number;
+};
+export type JobDefinition<Ctx = any> = ServiceJob<Ctx> | BackgroundJob;
+/** What a job tool and its status tool return. */
+export type JobResult = {
+    job_id: string;
+    tool: string;
+    done: boolean;
+    /** The service's latest status, for a job the service runs. */
+    status?: unknown;
+    /** What the tool returned, for a background job that finished. */
+    result?: unknown;
+    /** The last progress a background job reported. */
+    progress?: JobProgress;
+    started_at?: string;
+    finished_at?: string;
+    /** How to check again, while the job is still running. */
+    check?: string;
+};
+/** A client stops waiting on a call after about a minute, so no call waits longer than this. */
+export declare const MAX_WAIT_SECONDS = 55;
+export declare const DEFAULT_WAIT_SECONDS = 25;
+export declare function isBackground(job: JobDefinition): job is BackgroundJob;
+export declare function waitSecondsFor(job: JobDefinition): number;
+export declare function pollMsFor(job: ServiceJob): number;
+export declare function readJobId(job: ServiceJob, started: unknown): string | undefined;
+/**
+ * Wait until `finished` settles or `ms` passes, whichever is first. Infinity
+ * waits for as long as it takes. Resolves true when it finished. A canceled
+ * call stops waiting at once.
+ */
+export declare function waitFor(finished: Promise<unknown>, ms: number, signal: AbortSignal | undefined): Promise<boolean>;
+/** Sleep between status checks, cut short by a canceled call. */
+export declare function pause(ms: number, signal: AbortSignal | undefined): Promise<void>;
+/** A failed service job, reported with the status that says why. */
+export declare function jobFailed(tool: string, id: string, status: unknown): SlipwayError;
+type Entry = {
+    id: string;
+    tool: string;
+    startedAt: number;
+    finishedAt?: number;
+    state: "running" | "done" | "failed";
+    result?: unknown;
+    error?: SlipwayError;
+    progress?: JobProgress;
+    /** Settles when the job finishes, either way. Never rejects. */
+    finished: Promise<void>;
+    /** Whoever is waiting on the job right now, to forward its progress to. */
+    listener?: (progress: JobProgress) => void;
+};
+/**
+ * Background jobs of one process.
+ *
+ * Bounded both ways: at most 100 run at once, and a finished job is kept for
+ * an hour, so a server that runs for weeks never grows without limit. Ids are
+ * random, so one caller cannot read another's job by counting.
+ */
+export declare class JobRegistry {
+    private readonly jobs;
+    private static readonly MAX_RUNNING;
+    private static readonly KEEP_MS;
+    private static readonly MAX_KEPT;
+    start(tool: string, work: (progress: (update: JobProgress) => void) => Promise<unknown>): Entry;
+    get(id: string, tool: string): Entry;
+    private prune;
+}
+export type BackgroundEntry = Entry;
+/** A background job as its caller sees it. Throws the job's own error once it failed. */
+export declare function backgroundResult(entry: Entry, check: string): JobResult;
+/** Everything one job call needs from the app that runs it. */
+export type JobCall = {
+    /** The job tool's name, and the job it defines. */
+    jobTool: string;
+    job: JobDefinition;
+    /** Start a new job by running the tool's handler with a context, or check the job with this id. */
+    start?: (ctx: ToolContext<any>) => unknown;
+    jobId?: string;
+    /** How long this call waits for the job to finish. Infinity waits to the end. */
+    waitMs: number;
+    /** The caller canceled: stop waiting. */
+    waitSignal?: AbortSignal;
+    /** A signal for one request to the service: the caller's cancel plus the tool's timeout. */
+    requestSignal: () => AbortSignal;
+    /** The handler's context for one request to the service, or for a background job from start to finish. */
+    context: (signal: AbortSignal, progress: (update: JobProgress) => void) => ToolContext<any>;
+    /** Progress to send the caller while it waits. */
+    progress: (update: JobProgress) => void;
+    registry: JobRegistry;
+    /** A background job's own deadline, from the tool's timeout. */
+    timeoutMs?: number;
+    /** How to check a job again, in the words of the surface that asked. */
+    check: (id: string) => string;
+    /** Race a request against its signal, so a handler that ignores it still stops being waited for. */
+    untilAborted: <T>(work: Promise<T>, signal: AbortSignal) => Promise<T>;
+};
+/** Start or check a job, and wait for it as long as this call may. */
+export declare function runJob(call: JobCall): Promise<JobResult>;
+export {};