summer-engine 4.5.0 → 4.8.0

package/dist/core/summer-api.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The Summer API (www.summerengine.com/v1, PublicSummerEngine
+ * src/lib/ops/views/http.ts) from this computer: the curated game-dev models
+ * and their prices, an exact estimate, a job, and its files. `summer api` and
+ * the summer_api_* MCP tools both call these. Sign-in is the Summer OAuth
+ * sign-in on this computer (summer login; core/oauth.ts, refreshed by
+ * itself): one Supabase OAuth access token as the bearer. Listing models and
+ * estimating need none. There are no API keys.
+ *
+ * Until Summer opens the API, every route answers 404 "Nothing is here.":
+ * that is SummerApiError api_not_open, one plain line for people and agents.
+ */
+export declare const API_NOT_OPEN = "Summer API is not open yet.";
+export declare const SIGN_IN_GONE_MESSAGE = "Your Summer sign-in was revoked or has expired. Run \"summer login\", then retry.";
+/** The longest a --wait follows one job (a 3D model with a rig can take minutes). */
+export declare const MAX_JOB_WAIT_MS: number;
+export declare class SummerApiError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly body?: Record<string, unknown> | undefined;
+    constructor(code: string, message: string, status: number, body?: Record<string, unknown> | undefined);
+}
+export interface SummerApiDependencies {
+    fetch: typeof fetch;
+    sleep: (ms: number) => Promise<void>;
+    now: () => number;
+    /** The sign-in's current access token (core/oauth.ts); tests pass a fake. */
+    token?: () => Promise<string>;
+    /** A new access token from the sign-in server now; it throws once the person revoked the app. */
+    refresh?: () => Promise<string>;
+}
+export type Job = Record<string, unknown> & {
+    id: string;
+    state: string;
+};
+/** GET /v1/models (optionally one capability), or one model with GET /v1/models/{id}. */
+export declare function listModels(options?: {
+    capability?: string;
+    model?: string;
+}, overrides?: Partial<SummerApiDependencies>): Promise<Record<string, unknown>>;
+/** POST /v1/estimate: the exact price of one job, and a quote id that holds it 15 minutes. Charges nothing. */
+export declare function estimateJob(model: string, input: Record<string, unknown>, overrides?: Partial<SummerApiDependencies>): Promise<Record<string, unknown>>;
+export declare const isFinished: (job: Job) => boolean;
+/**
+ * POST /v1/jobs: spends the person's credits (within the key's limit). One
+ * Idempotency-Key per run, so a retried request never runs twice; `waitSeconds`
+ * (at most 60) asks the server to answer when the job is done.
+ */
+export declare function runJob(model: string, input: Record<string, unknown>, options?: {
+    quoteId?: string;
+    idempotencyKey?: string;
+    waitSeconds?: number;
+}, overrides?: Partial<SummerApiDependencies>): Promise<Job>;
+export declare function getJob(jobId: string, overrides?: Partial<SummerApiDependencies>): Promise<Job>;
+export declare function cancelJob(jobId: string, overrides?: Partial<SummerApiDependencies>): Promise<Job>;
+/** Follow a job until it finishes or `timeoutMs` passes (then it answers the job as it is). */
+export declare function waitForJob(job: Job, options?: {
+    timeoutMs?: number;
+}, overrides?: Partial<SummerApiDependencies>): Promise<Job>;
+/** <assetId><ext> as a file name every system accepts: no : * ? " < > | (a colon is an NTFS stream), no device name. */
+export declare function jobFileName(assetId: string, fileUrl: string): string;
+/** The finished job's files: every asset's fileUrl, saved under `dir` as <assetId><ext>. */
+export declare function downloadJobFiles(job: Job, dir: string, overrides?: Partial<SummerApiDependencies>): Promise<string[]>;
+/** One job of a batch: one line of a --batch file, one item of summer_api_batch. */
+export interface BatchJob {
+    model: string;
+    input: Record<string, unknown>;
+    idempotencyKey?: string;
+}
+export type Batch = Record<string, unknown> & {
+    id: string;
+    jobs: Job[];
+    counts?: Record<string, number>;
+};
+/** The most jobs one POST /v1/batches takes. */
+export declare const MAX_BATCH_JOBS = 500;
+/** The longest a --wait follows one batch (it runs on the account's slots, in order). */
+export declare const MAX_BATCH_WAIT_MS: number;
+/** A JSONL batch: one job per line ({"model", "input", optional "idempotencyKey"}); blank lines are skipped. */
+export declare function parseBatchLines(text: string): BatchJob[];
+/** The same checks for jobs that came as a list (summer_api_batch). */
+export declare function checkBatch(jobs: unknown[]): BatchJob[];
+export declare function getBatch(batchId: string, overrides?: Partial<SummerApiDependencies>): Promise<Batch>;
+/**
+ * POST /v1/batches: up to 500 jobs, all or none. Each is priced first; when
+ * the paid credits and the app's limit cover them all, all are queued (202)
+ * and run in order on the account's slots. When not, nothing runs and the
+ * error (402) says how many fit and how much more is needed. One
+ * Idempotency-Key for the batch, so a retried request never queues it twice.
+ */
+export declare function createBatch(jobs: BatchJob[], options?: {
+    idempotencyKey?: string;
+}, overrides?: Partial<SummerApiDependencies>): Promise<Batch>;
+export declare const isBatchFinished: (batch: Batch) => boolean;
+/** Follow a batch until every job finishes or `timeoutMs` passes (then it answers the batch as it is). */
+export declare function waitForBatch(batch: Batch, options?: {
+    timeoutMs?: number;
+}, overrides?: Partial<SummerApiDependencies>): Promise<Batch>;
+/** Every done job's files under `dir`, by job id. */
+export declare function downloadBatchFiles(batch: Batch, dir: string, overrides?: Partial<SummerApiDependencies>): Promise<Record<string, string[]>>;
+/** summer_api_batch: follow when asked (within one call's time), save files when `out` is given. */
+export declare function batchToolResult(batch: Batch, args: {
+    wait?: boolean;
+    out?: string;
+}, overrides?: Partial<SummerApiDependencies>): Promise<Record<string, unknown>>;
+/** The answer the summer_api_* MCP tools (and `summer tool api-*`) give: the result, or {ok:false, error}. */
+export declare function summerApiToolAnswer(work: () => Promise<Record<string, unknown>>): Promise<Record<string, unknown>>;
+/** One MCP call waits at most this long for a job; then it answers the job as it is (call summer_api_job to keep following). */
+export declare const TOOL_JOB_WAIT_MS = 50000;
+/** summer_api_run and summer_api_job: follow when asked (within one call's time), save files when `out` is given. */
+export declare function jobToolResult(job: Job, args: {
+    wait?: boolean;
+    out?: string;
+}, overrides?: Partial<SummerApiDependencies>): Promise<Record<string, unknown>>;

package/dist/core/summer-api.js

@@ -0,0 +1,281 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { extname, join, resolve } from "node:path";
+import { summerRequestHeaders } from "./agent-host.js";
+import { getStoreAccessToken, isSignInGone, OAuthError } from "./oauth.js";
+import { resolveGatewayUrl } from "./config.js";
+/**
+ * The Summer API (www.summerengine.com/v1, PublicSummerEngine
+ * src/lib/ops/views/http.ts) from this computer: the curated game-dev models
+ * and their prices, an exact estimate, a job, and its files. `summer api` and
+ * the summer_api_* MCP tools both call these. Sign-in is the Summer OAuth
+ * sign-in on this computer (summer login; core/oauth.ts, refreshed by
+ * itself): one Supabase OAuth access token as the bearer. Listing models and
+ * estimating need none. There are no API keys.
+ *
+ * Until Summer opens the API, every route answers 404 "Nothing is here.":
+ * that is SummerApiError api_not_open, one plain line for people and agents.
+ */
+export const API_NOT_OPEN = "Summer API is not open yet.";
+export const SIGN_IN_GONE_MESSAGE = 'Your Summer sign-in was revoked or has expired. Run "summer login", then retry.';
+const FINISHED = new Set(["done", "failed", "cancelled", "declined", "expired", "stale"]);
+/** The longest a --wait follows one job (a 3D model with a rig can take minutes). */
+export const MAX_JOB_WAIT_MS = 20 * 60_000;
+export class SummerApiError extends Error {
+    code;
+    status;
+    body;
+    constructor(code, message, status, body) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.body = body;
+    }
+}
+const defaults = {
+    fetch,
+    sleep: (ms) => new Promise((done) => setTimeout(done, ms)),
+    now: Date.now,
+};
+async function call(method, path, options, deps) {
+    const key = await (deps.token ?? (() => getStoreAccessToken()))().catch((error) => {
+        if (options.key !== "required")
+            return null;
+        if (error instanceof OAuthError)
+            throw new SummerApiError("not_signed_in", 'This computer is not signed in to Summer. Run "summer login", then retry.', 401);
+        throw error;
+    });
+    try {
+        return await send(method, path, options, key, deps);
+    }
+    catch (error) {
+        // Before launch the API answers a refused sign-in the way it answers everyone: "Nothing is here."
+        // So check the sign-in itself: a revoked app cannot refresh, and a live one retries once with a new token.
+        if (!key || !(error instanceof SummerApiError) || error.code !== "api_not_open")
+            throw error;
+        const fresh = await (deps.refresh ?? (() => getStoreAccessToken(undefined, { force: true })))().catch((refused) => {
+            if (isSignInGone(refused))
+                throw new SummerApiError("sign_in_revoked", SIGN_IN_GONE_MESSAGE, 401);
+            throw error;
+        });
+        return send(method, path, options, fresh, deps);
+    }
+}
+async function send(method, path, options, key, deps) {
+    const gateway = await resolveGatewayUrl();
+    const res = await deps.fetch(`${gateway}/v1${path}`, {
+        method,
+        headers: {
+            ...summerRequestHeaders(),
+            ...(key ? { Authorization: `Bearer ${key}` } : {}),
+            ...(options.body !== undefined ? { "Content-Type": "application/json" } : {}),
+            ...options.headers,
+        },
+        ...(options.body !== undefined ? { body: JSON.stringify(options.body) } : {}),
+        signal: AbortSignal.timeout(90_000),
+    });
+    const body = ((await res.json().catch(() => null)) ?? {});
+    if (res.ok)
+        return { status: res.status, body };
+    const error = (body.error && typeof body.error === "object" ? body.error : {});
+    const message = typeof error.message === "string" ? error.message : `The Summer API answered ${res.status}.`;
+    if (res.status === 404 && (message === "Nothing is here." || !body.error))
+        throw new SummerApiError("api_not_open", API_NOT_OPEN, 404);
+    throw new SummerApiError(typeof error.code === "string" ? error.code : "request_failed", message, res.status, error);
+}
+/** GET /v1/models (optionally one capability), or one model with GET /v1/models/{id}. */
+export async function listModels(options = {}, overrides = {}) {
+    const deps = { ...defaults, ...overrides };
+    if (options.model)
+        return (await call("GET", `/models/${options.model.split("/").map(encodeURIComponent).join("/")}`, { key: "optional" }, deps)).body;
+    const query = options.capability ? `?capability=${encodeURIComponent(options.capability)}` : "";
+    return (await call("GET", `/models${query}`, { key: "optional" }, deps)).body;
+}
+/** POST /v1/estimate: the exact price of one job, and a quote id that holds it 15 minutes. Charges nothing. */
+export async function estimateJob(model, input, overrides = {}) {
+    return (await call("POST", "/estimate", { body: { model, input }, key: "optional" }, { ...defaults, ...overrides })).body;
+}
+function jobOf(body) {
+    const job = body.job;
+    if (!job || typeof job !== "object" || typeof job.id !== "string") {
+        throw new SummerApiError("request_failed", "The Summer API answered without a job.", 502, body);
+    }
+    return job;
+}
+export const isFinished = (job) => FINISHED.has(job.state);
+/**
+ * POST /v1/jobs: spends the person's credits (within the key's limit). One
+ * Idempotency-Key per run, so a retried request never runs twice; `waitSeconds`
+ * (at most 60) asks the server to answer when the job is done.
+ */
+export async function runJob(model, input, options = {}, overrides = {}) {
+    const headers = { "Idempotency-Key": options.idempotencyKey ?? randomUUID() };
+    if (options.waitSeconds)
+        headers.Prefer = `wait=${Math.min(60, Math.max(1, Math.round(options.waitSeconds)))}`;
+    const { body } = await call("POST", "/jobs", { body: { model, input, ...(options.quoteId ? { quoteId: options.quoteId } : {}) }, headers, key: "required" }, { ...defaults, ...overrides });
+    return jobOf(body);
+}
+export async function getJob(jobId, overrides = {}) {
+    return jobOf((await call("GET", `/jobs/${encodeURIComponent(jobId)}`, { key: "required" }, { ...defaults, ...overrides })).body);
+}
+export async function cancelJob(jobId, overrides = {}) {
+    return jobOf((await call("POST", `/jobs/${encodeURIComponent(jobId)}/cancel`, { body: {}, key: "required" }, { ...defaults, ...overrides })).body);
+}
+/** Follow a job until it finishes or `timeoutMs` passes (then it answers the job as it is). */
+export async function waitForJob(job, options = {}, overrides = {}) {
+    const deps = { ...defaults, ...overrides };
+    const until = deps.now() + (options.timeoutMs ?? MAX_JOB_WAIT_MS);
+    let current = job;
+    while (!isFinished(current) && deps.now() < until) {
+        const after = typeof current.pollAfterSeconds === "number" ? current.pollAfterSeconds : 5;
+        await deps.sleep(Math.min(30, Math.max(2, after)) * 1000);
+        current = await getJob(current.id, deps);
+    }
+    return current;
+}
+/** Names Windows keeps for devices, with any extension: CON.glb opens the console, not a file. */
+const WINDOWS_DEVICE_NAMES = /^(con|prn|aux|nul|com[0-9]|lpt[0-9])$/i;
+/** <assetId><ext> as a file name every system accepts: no : * ? " < > | (a colon is an NTFS stream), no device name. */
+export function jobFileName(assetId, fileUrl) {
+    const ext = extname(new URL(fileUrl).pathname).slice(0, 8);
+    const base = assetId.replace(/[^A-Za-z0-9._-]+/g, "-");
+    return `${WINDOWS_DEVICE_NAMES.test(base.split(".")[0]) ? `_${base}` : base}${/^\.[A-Za-z0-9]+$/.test(ext) ? ext : ".bin"}`;
+}
+/** The finished job's files: every asset's fileUrl, saved under `dir` as <assetId><ext>. */
+export async function downloadJobFiles(job, dir, overrides = {}) {
+    const deps = { ...defaults, ...overrides };
+    const result = (job.result && typeof job.result === "object" ? job.result : {});
+    const assets = (Array.isArray(result.assets) ? result.assets : []);
+    const target = resolve(dir);
+    await mkdir(target, { recursive: true });
+    const saved = [];
+    for (const [index, asset] of assets.entries()) {
+        if (typeof asset.fileUrl !== "string")
+            continue;
+        const res = await deps.fetch(asset.fileUrl, { signal: AbortSignal.timeout(120_000) });
+        if (!res.ok)
+            throw new SummerApiError("download_failed", `Could not download ${asset.fileUrl} (${res.status}).`, res.status);
+        const path = join(target, jobFileName(String(asset.assetId ?? `${job.id}-${index + 1}`), asset.fileUrl));
+        await writeFile(path, Buffer.from(await res.arrayBuffer()));
+        saved.push(path);
+    }
+    return saved;
+}
+/** The most jobs one POST /v1/batches takes. */
+export const MAX_BATCH_JOBS = 500;
+/** The longest a --wait follows one batch (it runs on the account's slots, in order). */
+export const MAX_BATCH_WAIT_MS = 2 * 60 * 60_000;
+function batchJobOf(value, where) {
+    const item = (value && typeof value === "object" && !Array.isArray(value) ? value : null);
+    if (!item || typeof item.model !== "string" || !item.model)
+        throw new SummerApiError("invalid_input", `${where}: needs "model", e.g. {"model": "3d/default", "input": {"prompt": "a wooden chest"}}.`, 400);
+    const input = item.input ?? {};
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        throw new SummerApiError("invalid_input", `${where}: "input" must be a JSON object.`, 400);
+    const key = item.idempotencyKey ?? item.idempotency_key;
+    if (key !== undefined && (typeof key !== "string" || !key))
+        throw new SummerApiError("invalid_input", `${where}: "idempotencyKey" must be a string.`, 400);
+    return { model: item.model, input: input, ...(typeof key === "string" ? { idempotencyKey: key } : {}) };
+}
+/** A JSONL batch: one job per line ({"model", "input", optional "idempotencyKey"}); blank lines are skipped. */
+export function parseBatchLines(text) {
+    const jobs = [];
+    for (const [index, raw] of text.split(/\r?\n/).entries()) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        let value;
+        try {
+            value = JSON.parse(line);
+        }
+        catch {
+            throw new SummerApiError("invalid_input", `Line ${index + 1} is not JSON.`, 400);
+        }
+        jobs.push(batchJobOf(value, `Line ${index + 1}`));
+    }
+    return checkBatch(jobs);
+}
+/** The same checks for jobs that came as a list (summer_api_batch). */
+export function checkBatch(jobs) {
+    if (jobs.length === 0)
+        throw new SummerApiError("invalid_input", "The batch has no jobs.", 400);
+    if (jobs.length > MAX_BATCH_JOBS)
+        throw new SummerApiError("invalid_input", `The batch has ${jobs.length} jobs; one batch takes at most ${MAX_BATCH_JOBS}.`, 400);
+    return jobs.map((job, index) => batchJobOf(job, `Job ${index + 1}`));
+}
+function batchOf(body) {
+    const batch = body.batch;
+    if (!batch || typeof batch !== "object" || typeof batch.id !== "string") {
+        throw new SummerApiError("request_failed", "The Summer API answered without a batch.", 502, body);
+    }
+    return batch;
+}
+export async function getBatch(batchId, overrides = {}) {
+    return batchOf((await call("GET", `/batches/${encodeURIComponent(batchId)}`, { key: "required" }, { ...defaults, ...overrides })).body);
+}
+/**
+ * POST /v1/batches: up to 500 jobs, all or none. Each is priced first; when
+ * the paid credits and the app's limit cover them all, all are queued (202)
+ * and run in order on the account's slots. When not, nothing runs and the
+ * error (402) says how many fit and how much more is needed. One
+ * Idempotency-Key for the batch, so a retried request never queues it twice.
+ */
+export async function createBatch(jobs, options = {}, overrides = {}) {
+    const deps = { ...defaults, ...overrides };
+    const headers = { "Idempotency-Key": options.idempotencyKey ?? randomUUID() };
+    const batch = batchOf((await call("POST", "/batches", { body: { jobs }, headers, key: "required" }, deps)).body);
+    // A replayed batch answers its job count only: read its jobs.
+    return Array.isArray(batch.jobs) ? batch : getBatch(batch.id, deps);
+}
+export const isBatchFinished = (batch) => batch.jobs.length > 0 && batch.jobs.every(isFinished);
+/** Follow a batch until every job finishes or `timeoutMs` passes (then it answers the batch as it is). */
+export async function waitForBatch(batch, options = {}, overrides = {}) {
+    const deps = { ...defaults, ...overrides };
+    const until = deps.now() + (options.timeoutMs ?? MAX_BATCH_WAIT_MS);
+    let current = batch;
+    while (!isBatchFinished(current) && deps.now() < until) {
+        await deps.sleep(10_000);
+        current = await getBatch(current.id, deps);
+    }
+    return current;
+}
+/** Every done job's files under `dir`, by job id. */
+export async function downloadBatchFiles(batch, dir, overrides = {}) {
+    const files = {};
+    for (const job of batch.jobs) {
+        if (job.state === "done")
+            files[job.id] = await downloadJobFiles(job, dir, overrides);
+    }
+    return files;
+}
+/** summer_api_batch: follow when asked (within one call's time), save files when `out` is given. */
+export async function batchToolResult(batch, args, overrides = {}) {
+    const follow = args.wait === true || typeof args.out === "string";
+    const final = follow && !isBatchFinished(batch) ? await waitForBatch(batch, { timeoutMs: TOOL_JOB_WAIT_MS }, overrides) : batch;
+    const files = typeof args.out === "string" ? await downloadBatchFiles(final, args.out, overrides) : undefined;
+    return {
+        batch: final,
+        ...(files ? { files } : {}),
+        ...(isBatchFinished(final) ? {} : { next: `Call summer_api_batch with batchId ${final.id} (wait: true${typeof args.out === "string" ? ", out" : ""}) to keep following it.` }),
+    };
+}
+/** The answer the summer_api_* MCP tools (and `summer tool api-*`) give: the result, or {ok:false, error}. */
+export async function summerApiToolAnswer(work) {
+    try {
+        return { ok: true, ...(await work()) };
+    }
+    catch (error) {
+        if (error instanceof SummerApiError)
+            return { ok: false, error: { code: error.code, message: error.message } };
+        return { ok: false, error: { code: "request_failed", message: error instanceof Error ? error.message : String(error) } };
+    }
+}
+/** One MCP call waits at most this long for a job; then it answers the job as it is (call summer_api_job to keep following). */
+export const TOOL_JOB_WAIT_MS = 50_000;
+/** summer_api_run and summer_api_job: follow when asked (within one call's time), save files when `out` is given. */
+export async function jobToolResult(job, args, overrides = {}) {
+    const follow = args.wait === true || typeof args.out === "string";
+    const final = follow && !isFinished(job) ? await waitForJob(job, { timeoutMs: TOOL_JOB_WAIT_MS }, overrides) : job;
+    const files = typeof args.out === "string" && final.state === "done" ? await downloadJobFiles(final, args.out, overrides) : undefined;
+    return { job: final, ...(files ? { files } : {}), ...(isFinished(final) ? {} : { next: `Call summer_api_job with jobId ${final.id} (wait: true) to keep following it.` }) };
+}

package/dist/installer/agent-config.d.ts

@@ -18,6 +18,10 @@ export interface AgentConfigOptions {
     channel?: string;
     /** MCP tool profile written as SUMMER_PROFILE; default the agent's own (full for most). */
     profile?: Profile;
+    /** A bundled Node runtime and summer-engine package (the Summer desktop installer):
+     *  the entry runs `<node> <packageDir>/dist/bin/summer.js mcp` instead of npx.
+     *  Check it with resolveBundledRuntime first. Ignores localDev and channel. */
+    runtime?: BundledRuntime;
     cwd?: string;
     env?: NodeJS.ProcessEnv;
 }
@@ -39,6 +43,8 @@ export interface AgentConfigResult {
     channel: string;
     /** The MCP tool profile the entry runs (full = every tool, no SUMMER_PROFILE written). */
     profile: Profile;
+    /** Set when the entry runs a bundled Node runtime (--runtime, --package-dir). */
+    runtime: BundledRuntime | null;
     warnings: string[];
     nextSteps: string[];
 }
@@ -89,6 +95,29 @@ export declare function normalizeChannel(channel: string | undefined): string;
  */
 export declare function withProfile(server: StdioMcpServerConfig, profile: Profile): StdioMcpServerConfig;
 export declare function createSummerMcpServerConfig(localDev: boolean, platform?: NodeJS.Platform, channel?: string): StdioMcpServerConfig;
+/**
+ * A Node runtime and a summer-engine package shipped next to each other (the
+ * Summer desktop installer bundles both, so the person needs no Node.js of
+ * their own). Both are absolute paths.
+ */
+export interface BundledRuntime {
+    /** The node executable (node, or node.exe on Windows). */
+    node: string;
+    /** The summer-engine package folder: the one with package.json and dist/bin/summer.js. */
+    packageDir: string;
+}
+/** The CLI entry point inside a summer-engine package folder. */
+export declare function bundledCliPath(packageDir: string): string;
+/**
+ * --runtime <node> and --package-dir <dir>: both or neither, and both must
+ * exist. The runtime must be an executable file (any file on Windows); the
+ * package folder must hold summer-engine's package.json and its built CLI.
+ * Returns absolute paths, so the agent's entry works from any folder.
+ */
+export declare function resolveBundledRuntime(node: string | undefined, packageDir: string | undefined, cwd?: string): BundledRuntime | null;
+/** The entry for a bundled runtime: `<node> <packageDir>/dist/bin/summer.js mcp`.
+ *  node is a real executable, so no cmd.exe wrapper is needed on Windows. */
+export declare function bundledRuntimeServerConfig(runtime: BundledRuntime): StdioMcpServerConfig;
 export declare function renderConfigSnippet(agent: SupportedAgent, server: StdioMcpServerConfig): string;
 /** The key under which the file lists MCP servers (see McpFormat in agent-table.ts). */
 export declare function topLevelKey(format: McpFormat): string;

package/dist/installer/agent-config.js

@@ -1,9 +1,10 @@
-import { existsSync, readFileSync } from "fs";
+import { accessSync, constants as fsConstants, existsSync, readFileSync, statSync } from "fs";
 import { copyFile, mkdir, readFile, writeFile } from "fs/promises";
 import { dirname, join, resolve } from "path";
 import { fileURLToPath } from "url";
 import { Document, isMap, parseDocument } from "yaml";
 import { PACKAGE_ROOT } from "../core/package-root.js";
+import { SetupError } from "./setup-error.js";
 import { agentAliasMap, agentSpec, defaultPathContext, resolveMcpPath, supportedAgents, } from "./agent-table.js";
 export { supportedAgents } from "./agent-table.js";
 export const SUMMER_MCP_SERVER_NAME = "summer-engine";
@@ -50,7 +51,8 @@ export async function configureAgentMcp(options) {
     const channel = normalizeChannel(options.channel);
     const spec = agentSpec(options.agent);
     const profile = options.profile ?? spec.mcpProfile ?? "full";
-    const server = withProfile(createSummerMcpServerConfig(Boolean(options.localDev), process.platform, channel), profile);
+    const runtime = options.runtime ?? null;
+    const server = withProfile(runtime ? bundledRuntimeServerConfig(runtime) : createSummerMcpServerConfig(Boolean(options.localDev), process.platform, channel), profile);
     const target = resolveConfigTarget(spec, options.scope, cwd, env);
     // An entry an earlier setup wrote where the agent no longer reads (Devin Desktop moved from ~/.codeium/windsurf).
     const moved = spec.mcp.movedFrom ? spec.mcp.movedFrom(defaultPathContext(env, cwd)) : null;
@@ -76,9 +78,10 @@ export async function configureAgentMcp(options) {
         wrote: shouldWrite && update.changed,
         dryRun,
         print,
-        localDev: Boolean(options.localDev),
+        localDev: !runtime && Boolean(options.localDev),
         channel,
         profile,
+        runtime,
         warnings: target.warnings,
         nextSteps: [`Updated ${target.path}.`, spec.restart],
     };
@@ -320,6 +323,67 @@ export function createSummerMcpServerConfig(localDev, platform = process.platfor
         args: ["-y", spec, "mcp"],
     };
 }
+/** The CLI entry point inside a summer-engine package folder. */
+export function bundledCliPath(packageDir) {
+    return join(packageDir, "dist", "bin", "summer.js");
+}
+/**
+ * --runtime <node> and --package-dir <dir>: both or neither, and both must
+ * exist. The runtime must be an executable file (any file on Windows); the
+ * package folder must hold summer-engine's package.json and its built CLI.
+ * Returns absolute paths, so the agent's entry works from any folder.
+ */
+export function resolveBundledRuntime(node, packageDir, cwd = process.cwd()) {
+    if (node === undefined && packageDir === undefined)
+        return null;
+    if (!node || !packageDir) {
+        throw new SetupError("runtime_incomplete", "--runtime and --package-dir go together: name the node executable and the summer-engine package folder.");
+    }
+    const nodePath = resolve(cwd, node);
+    const nodeStat = statIfExists(nodePath);
+    if (!nodeStat)
+        throw new SetupError("runtime_not_found", `--runtime ${nodePath} does not exist.`);
+    if (!nodeStat.isFile())
+        throw new SetupError("runtime_not_found", `--runtime ${nodePath} is not a file. Name the node executable itself.`);
+    if (process.platform !== "win32") {
+        try {
+            accessSync(nodePath, fsConstants.X_OK);
+        }
+        catch {
+            throw new SetupError("runtime_not_executable", `--runtime ${nodePath} is not executable.`);
+        }
+    }
+    const dir = resolve(cwd, packageDir);
+    if (!statIfExists(dir)?.isDirectory())
+        throw new SetupError("package_dir_not_found", `--package-dir ${dir} is not a folder.`);
+    let name;
+    try {
+        name = JSON.parse(readFileSync(join(dir, "package.json"), "utf-8")).name;
+    }
+    catch {
+        name = undefined;
+    }
+    if (name !== "summer-engine") {
+        throw new SetupError("package_dir_invalid", `--package-dir ${dir} is not the summer-engine package: it has no package.json named summer-engine.`);
+    }
+    if (!statIfExists(bundledCliPath(dir))?.isFile()) {
+        throw new SetupError("package_dir_invalid", `--package-dir ${dir} has no built CLI at dist/bin/summer.js.`);
+    }
+    return { node: nodePath, packageDir: dir };
+}
+/** The entry for a bundled runtime: `<node> <packageDir>/dist/bin/summer.js mcp`.
+ *  node is a real executable, so no cmd.exe wrapper is needed on Windows. */
+export function bundledRuntimeServerConfig(runtime) {
+    return { command: runtime.node, args: [bundledCliPath(runtime.packageDir), "mcp"] };
+}
+function statIfExists(path) {
+    try {
+        return statSync(path);
+    }
+    catch {
+        return null;
+    }
+}
 export function renderConfigSnippet(agent, server) {
     const format = agentSpec(agent).format;
     if (format === "toml")
@@ -449,14 +513,14 @@ async function upsertYamlConfig(path, keyPath, entry, write) {
     // would make the root a flow mapping and the whole file would render as {}.
     const doc = current.trim() === "" ? new Document({}) : parseDocument(current);
     if (doc.errors.length > 0) {
-        throw new Error(`Could not parse YAML in ${path}: ${doc.errors[0].message}`);
+        throw new SetupError("config_invalid", `Could not parse YAML in ${path}: ${doc.errors[0].message}`);
     }
     if (!isMap(doc.contents)) {
-        throw new Error(`Expected ${path} to contain a YAML mapping.`);
+        throw new SetupError("config_invalid", `Expected ${path} to contain a YAML mapping.`);
     }
     const parent = doc.getIn(keyPath.slice(0, -1));
     if (parent !== undefined && parent !== null && !isMap(parent)) {
-        throw new Error(`Existing ${keyPath[0]} value in ${path} must be a mapping.`);
+        throw new SetupError("config_invalid", `Existing ${keyPath[0]} value in ${path} must be a mapping.`);
     }
     doc.setIn(keyPath, doc.createNode(entry));
     const next = doc.toString();
@@ -474,7 +538,7 @@ async function readJsonConfig(path) {
         content = await readFile(path, "utf-8");
     }
     catch (error) {
-        throw new Error(`Could not read ${path}: ${formatError(error)}`);
+        throw new SetupError("config_unreadable", `Could not read ${path}: ${formatError(error)}`);
     }
     if (content.trim() === "")
         return {};
@@ -483,10 +547,10 @@ async function readJsonConfig(path) {
         parsed = JSON.parse(content);
     }
     catch (error) {
-        throw new Error(`Could not parse JSON in ${path}: ${formatError(error)}`);
+        throw new SetupError("config_invalid", `Could not parse JSON in ${path}: ${formatError(error)}`);
     }
     if (!isJsonObject(parsed)) {
-        throw new Error(`Expected ${path} to contain a JSON object.`);
+        throw new SetupError("config_invalid", `Expected ${path} to contain a JSON object.`);
     }
     return parsed;
 }
@@ -662,7 +726,7 @@ async function readTextFileIfExists(path) {
         return await readFile(path, "utf-8");
     }
     catch (error) {
-        throw new Error(`Could not read ${path}: ${formatError(error)}`);
+        throw new SetupError("config_unreadable", `Could not read ${path}: ${formatError(error)}`);
     }
 }
 function upsertTomlTable(content, table, name = SUMMER_MCP_SERVER_NAME) {
@@ -716,7 +780,7 @@ function copyJsonObject(value) {
 }
 function mergeNamedObject(value, key, entry, label) {
     if (value !== undefined && !isJsonObject(value)) {
-        throw new Error(`Existing ${label} value must be a JSON object.`);
+        throw new SetupError("config_invalid", `Existing ${label} value must be a JSON object.`);
     }
     return {
         ...(isJsonObject(value) ? value : {}),

package/dist/installer/agent-detect.d.ts

@@ -0,0 +1,44 @@
+import { type ConfigScope, type McpFormat, type PathContext, type SupportedAgent } from "./agent-table.js";
+import { type SetupStepError } from "./setup-error.js";
+import type { StdioMcpServerConfig } from "./agent-config.js";
+export interface DetectHit {
+    kind: "bin" | "app" | "folder" | "extension";
+    path: string;
+}
+export interface DetectedAgent {
+    id: SupportedAgent;
+    label: string;
+    /** legacy: the product was retired or renamed; setup still writes it, with a warning. */
+    status: "active" | "legacy";
+    installed: boolean;
+    /** A command, app or extension was found, not only a folder. A folder can outlive the
+     *  program, or be one an earlier Summer setup made for its skills or config. */
+    programFound: boolean;
+    /** Every place that showed the agent is installed (empty when not installed). */
+    detectedBy: DetectHit[];
+    /** The MCP config file `summer setup <id>` writes at user scope (project scope for agents with no user file). */
+    configPath: string;
+    configScope: ConfigScope;
+    configFormat: McpFormat;
+    configExists: boolean;
+    /** The config file lists a summer-engine MCP server, in any shape. */
+    mcpEntry: boolean;
+    /** The command the summer-engine entry runs, when it is a local (stdio) entry. */
+    mcpServer: StdioMcpServerConfig | null;
+    /** Setup also adds the Summer Games MCP for this agent. */
+    summerGames: boolean;
+    /** Setup also installs skills for this agent. */
+    skills: boolean;
+    /** Set when the config file exists but cannot be read. */
+    configError?: SetupStepError;
+}
+export interface DetectOptions {
+    ctx?: PathContext;
+    /** Folders searched for macOS app bundles; default /Applications and ~/Applications. */
+    macAppDirs?: string[];
+    /** Shared command folders outside home searched on macOS and Linux; default Homebrew's /opt/homebrew/bin and /usr/local/bin. */
+    systemBinDirs?: string[];
+}
+export declare function detectAgents(options?: DetectOptions): DetectedAgent[];
+/** PATH first, then the install folders a GUI-launched process's PATH leaves out. */
+export declare function searchedBinDirs(ctx: PathContext, systemBinDirs?: string[]): string[];