summer-engine 4.3.0 → 4.6.0

package/dist/core/usage-fields.js

@@ -0,0 +1,150 @@
+/**
+ * The extra fields a usage line (telemetry.ts, cli-usage.ts) can carry. Each
+ * is a closed shape checked here, so nothing a person typed, no path and no
+ * project or file name can reach one:
+ *
+ * - `projectIdHash`: the engine's own project id hash (sha256 of the random
+ *   id Summer Engine keeps in `.summer/local/.project_id`), the same value
+ *   Summer already uses to route requests to a project. Not the name or path.
+ * - `templateId`, `templateTags`: the library template a project started
+ *   from (`.summer/project.json`) and that template's library domains
+ *   (`facets.domains`, e.g. `2d`, `platformer`). Only ids from the shipped
+ *   catalog; anything else is left out.
+ * - `instanceCount`: how many game clients `engine.play` started.
+ * - `engineState`: four yes/no answers when a call failed with
+ *   `engine_not_running` (is the app installed, is an editor running, is one
+ *   holding a project, is the person signed in), from local files only.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { currentToolContext } from "./agent-host.js";
+import { hasEnvAuthToken } from "./auth.js";
+import { listEngineInstances } from "./engine.js";
+import { findEngineBinary } from "./engine-install.js";
+import { loadLibraryIndex } from "./library-search.js";
+import { getSummerDir } from "./store.js";
+import { getTemplateRegistry } from "./templates.js";
+import { readProjectManifest } from "../project-memory/project-manifest.js";
+const HASH = /^[0-9a-f]{16,128}$/;
+const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const MAX_TAGS = 8;
+/** Only the closed shapes above survive; everything else is dropped. */
+export function cleanUsageFields(fields) {
+    const out = {};
+    if (typeof fields.projectIdHash === "string" && HASH.test(fields.projectIdHash))
+        out.projectIdHash = fields.projectIdHash;
+    if (typeof fields.templateId === "string" && SLUG.test(fields.templateId))
+        out.templateId = fields.templateId;
+    if (Array.isArray(fields.templateTags)) {
+        const tags = fields.templateTags.filter((tag) => typeof tag === "string" && SLUG.test(tag)).slice(0, MAX_TAGS);
+        if (tags.length)
+            out.templateTags = tags;
+    }
+    if (typeof fields.instanceCount === "number" && Number.isInteger(fields.instanceCount) && fields.instanceCount >= 0 && fields.instanceCount <= 64) {
+        out.instanceCount = fields.instanceCount;
+    }
+    return out;
+}
+// One command per CLI process: its line reads these at exit (cli-usage.ts).
+let processNotes = {};
+let boundProjectIdHash;
+/** A tool or command noted fields for its usage line; never throws. */
+export function noteToolUsage(fields) {
+    try {
+        const clean = cleanUsageFields(fields);
+        const context = currentToolContext();
+        if (context)
+            Object.assign(context.usage, clean);
+        Object.assign(processNotes, clean);
+    }
+    catch {
+        // usage is best-effort
+    }
+}
+/** The fields noted in this process (the CLI line), with the bound project. */
+export function processUsageFields() {
+    return { ...(boundProjectIdHash ? { projectIdHash: boundProjectIdHash } : {}), ...processNotes };
+}
+/** The engine connection bound this project (api-client.ts connect and rebind). */
+export function noteBoundProject(projectIdHash) {
+    boundProjectIdHash = typeof projectIdHash === "string" && HASH.test(projectIdHash) ? projectIdHash : undefined;
+}
+export function boundProject() {
+    return boundProjectIdHash;
+}
+/** The library slug for a catalog template id or slug, else null. */
+export function catalogTemplateSlug(idOrSlug) {
+    try {
+        const entry = getTemplateRegistry().find((template) => template.id === idOrSlug || template.slug === idOrSlug);
+        return entry ? entry.slug : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** A catalog template's library domains (`facets.domains`), e.g. ["2d", "platformer"]. */
+export function templateTags(slug) {
+    try {
+        const entry = loadLibraryIndex().find((resource) => resource.id === `template/${slug}`);
+        return (entry?.facets?.domains ?? []).filter((tag) => SLUG.test(tag)).slice(0, MAX_TAGS);
+    }
+    catch {
+        return [];
+    }
+}
+const templateByHash = new Map();
+/**
+ * The catalog template the project with this hash started from: the running
+ * editor's registry entry gives its folder, `.summer/project.json` the
+ * template. Cached per hash; null when unknown or not a catalog template.
+ */
+export async function templateForProject(projectIdHash) {
+    if (templateByHash.has(projectIdHash))
+        return templateByHash.get(projectIdHash) ?? null;
+    let slug = null;
+    try {
+        const instance = (await listEngineInstances()).find((entry) => entry.projectIdHash === projectIdHash);
+        const id = instance ? readProjectManifest(instance.resourceRoot)?.template?.id : undefined;
+        slug = typeof id === "string" ? catalogTemplateSlug(id) : null;
+    }
+    catch {
+        slug = null;
+    }
+    templateByHash.set(projectIdHash, slug);
+    return slug;
+}
+/** What is true on this machine when the engine could not be reached. Local files only. */
+export async function engineState() {
+    const instances = await listEngineInstances(Date.now(), getSummerDir(), { anyHeartbeat: true }).catch(() => []);
+    return {
+        desktopInstalled: findEngineBinary() !== null,
+        engineRunning: instances.length > 0,
+        projectOpen: instances.some((instance) => !!instance.projectIdHash),
+        signedIn: hasEnvAuthToken() || existsSync(join(getSummerDir(), "auth-token")),
+    };
+}
+/**
+ * The extra fields of one usage line: what the call noted, else the bound
+ * project and its template, and the engine state for engine_not_running.
+ * Never throws.
+ */
+export async function usageLineFields(noted, error) {
+    try {
+        const fields = cleanUsageFields(noted);
+        if (fields.projectIdHash && !fields.templateId) {
+            const template = await templateForProject(fields.projectIdHash);
+            if (template)
+                fields.templateId = template;
+        }
+        return { ...fields, ...(error === "engine_not_running" ? { engineState: await engineState() } : {}) };
+    }
+    catch {
+        return {};
+    }
+}
+/** Test-only: forget notes, the bound project and the template cache. */
+export function _resetUsageFieldsForTests() {
+    processNotes = {};
+    boundProjectIdHash = undefined;
+    templateByHash.clear();
+}

package/dist/core/util/sleep.d.ts

@@ -1 +1,4 @@
 export declare function sleep(ms: number): Promise<void>;
+/** Whether `promise` settles within `ms`. The timer is cleared when it does,
+ *  so a quick answer never keeps a CLI process alive for the full wait. */
+export declare function settlesWithin(promise: Promise<unknown>, ms: number): Promise<boolean>;

package/dist/core/util/sleep.js

@@ -1,3 +1,15 @@
 export function sleep(ms) {
     return new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
 }
+/** Whether `promise` settles within `ms`. The timer is cleared when it does,
+ *  so a quick answer never keeps a CLI process alive for the full wait. */
+export function settlesWithin(promise, ms) {
+    return new Promise((resolveWithin) => {
+        const timer = setTimeout(() => resolveWithin(false), ms);
+        const done = () => {
+            clearTimeout(timer);
+            resolveWithin(true);
+        };
+        promise.then(done, done);
+    });
+}

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[];

package/dist/installer/agent-detect.js

@@ -0,0 +1,166 @@
+/**
+ * `summer setup --detect`: which agents from agent-table.ts are on this
+ * computer, where each one's MCP config file is, and whether it already lists
+ * summer-engine. Reads only; never writes.
+ *
+ * How an agent counts as installed (any one hit; `detectedBy` names each):
+ *  - bin: one of its commands is a file on PATH, or in a usual install folder
+ *    (~/.local/bin, /opt/homebrew/bin, %APPDATA%\npm, ...). A desktop app's
+ *    installer runs with a short PATH that leaves those out, so they are
+ *    checked by name. On Windows each name is tried with every PATHEXT ending.
+ *  - app: a macOS app bundle in /Applications or ~/Applications, or a Windows
+ *    executable under %LOCALAPPDATA%, %ProgramFiles% or %ProgramFiles(x86)%.
+ *  - folder: a config, data or install folder the agent makes on first run.
+ *  - extension: a VS Code extension folder in ~/.vscode/extensions.
+ * The per-agent names live in agent-table.ts (`detect`).
+ */
+import { accessSync, constants, existsSync, readdirSync, readFileSync, statSync } from "fs";
+import { join } from "path";
+import { allAgentSpecs, defaultPathContext, resolveMcpPath, } from "./agent-table.js";
+import { listsSummerEngine, readRecordedMcpServer } from "./version-check.js";
+import { toStepError } from "./setup-error.js";
+export function detectAgents(options = {}) {
+    const ctx = options.ctx ?? defaultPathContext();
+    const binDirs = searchedBinDirs(ctx, options.systemBinDirs);
+    const macAppDirs = options.macAppDirs ?? ["/Applications", join(ctx.home, "Applications")];
+    return allAgentSpecs().map((spec) => detectAgent(spec, ctx, binDirs, macAppDirs));
+}
+function detectAgent(spec, ctx, binDirs, macAppDirs) {
+    const detectedBy = [
+        ...(spec.detect.bins ?? []).flatMap((name) => findBin(name, binDirs, ctx)).map((path) => ({ kind: "bin", path })),
+        ...findApps(spec, ctx, macAppDirs).map((path) => ({ kind: "app", path })),
+        ...(spec.detect.dirs?.(ctx) ?? []).filter((path) => existsSync(path)).map((path) => ({ kind: "folder", path })),
+        ...findVsCodeExtensions(spec.detect.vscodeExtensions ?? [], ctx).map((path) => ({ kind: "extension", path })),
+    ];
+    const unique = detectedBy.filter((hit, index) => detectedBy.findIndex((other) => other.path === hit.path) === index);
+    const resolved = resolveMcpPath(spec, "user", ctx);
+    const override = ctx.env[spec.envOverride];
+    const configPath = override || resolved.path;
+    const configExists = existsSync(configPath);
+    let mcpEntry = false;
+    let mcpServer = null;
+    let configError;
+    if (configExists) {
+        try {
+            const text = readFileSync(configPath, "utf-8");
+            mcpEntry = listsSummerEngine(text, spec.format);
+            mcpServer = readRecordedMcpServer(text, spec.format);
+        }
+        catch (error) {
+            configError = toStepError(error, "config_unreadable");
+        }
+    }
+    return {
+        id: spec.id,
+        label: spec.label,
+        status: spec.status,
+        installed: unique.length > 0,
+        programFound: unique.some((hit) => hit.kind !== "folder"),
+        detectedBy: unique,
+        configPath,
+        configScope: resolved.scope,
+        configFormat: spec.format,
+        configExists,
+        mcpEntry,
+        mcpServer,
+        summerGames: Boolean(spec.remoteMcp),
+        skills: spec.skills !== null,
+        ...(configError ? { configError } : {}),
+    };
+}
+/** PATH first, then the install folders a GUI-launched process's PATH leaves out. */
+export function searchedBinDirs(ctx, systemBinDirs = ["/opt/homebrew/bin", "/usr/local/bin"]) {
+    const path = ctx.env.PATH ?? ctx.env.Path ?? "";
+    const sep = ctx.os === "win32" ? ";" : ":";
+    const fromPath = path.split(sep).filter(Boolean);
+    const home = ctx.home;
+    const usual = ctx.os === "win32"
+        ? [
+            join(home, ".local", "bin"),
+            join(ctx.env.APPDATA ?? join(home, "AppData", "Roaming"), "npm"),
+            join(localAppData(ctx), "Microsoft", "WinGet", "Links"),
+            join(localAppData(ctx), "pnpm"),
+            join(home, ".bun", "bin"),
+            join(home, ".volta", "bin"),
+            join(home, ".lmstudio", "bin"),
+        ]
+        : [
+            join(home, ".local", "bin"),
+            join(home, "bin"),
+            ...systemBinDirs,
+            join(home, ".npm-global", "bin"),
+            join(home, ".bun", "bin"),
+            join(home, ".volta", "bin"),
+            join(home, "Library", "pnpm"),
+            join(home, ".local", "share", "pnpm"),
+            join(home, ".claude", "local"),
+            join(home, ".opencode", "bin"),
+            join(home, ".lmstudio", "bin"),
+            ...nvmBinDirs(home),
+        ];
+    return [...new Set([...fromPath, ...usual])];
+}
+/** ~/.nvm/versions/node/<version>/bin for each installed Node (npm -g installs land there). */
+function nvmBinDirs(home) {
+    const root = join(home, ".nvm", "versions", "node");
+    try {
+        return readdirSync(root).map((version) => join(root, version, "bin"));
+    }
+    catch {
+        return [];
+    }
+}
+function localAppData(ctx) {
+    return ctx.env.LOCALAPPDATA ?? join(ctx.home, "AppData", "Local");
+}
+function findBin(name, dirs, ctx) {
+    const names = ctx.os === "win32"
+        ? [name, ...(ctx.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean).map((ext) => `${name}${ext.toLowerCase()}`)]
+        : [name];
+    const hits = [];
+    for (const dir of dirs) {
+        for (const candidate of names) {
+            const path = join(dir, candidate);
+            if (isRunnable(path, ctx)) {
+                hits.push(path);
+                break;
+            }
+        }
+    }
+    return hits;
+}
+function isRunnable(path, ctx) {
+    try {
+        if (!statSync(path).isFile())
+            return false;
+        if (ctx.os !== "win32")
+            accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function findApps(spec, ctx, macAppDirs) {
+    if (ctx.os === "darwin") {
+        return (spec.detect.macApps ?? []).flatMap((app) => macAppDirs.map((dir) => join(dir, app))).filter((path) => existsSync(path));
+    }
+    if (ctx.os === "win32") {
+        const roots = [localAppData(ctx), ctx.env.ProgramFiles, ctx.env["ProgramFiles(x86)"]].filter((root) => Boolean(root));
+        return (spec.detect.winApps ?? []).flatMap((exe) => roots.map((root) => join(root, exe))).filter((path) => existsSync(path));
+    }
+    return [];
+}
+function findVsCodeExtensions(prefixes, ctx) {
+    if (prefixes.length === 0)
+        return [];
+    const dir = join(ctx.home, ".vscode", "extensions");
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    return entries.filter((entry) => prefixes.some((prefix) => entry.toLowerCase().startsWith(prefix))).map((entry) => join(dir, entry));
+}

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

@@ -101,6 +101,25 @@ export interface AgentSpec {
     /** null: no skills/rules mechanism — MCP only. */
     skills: SkillHome | null;
     noSkillsNote?: string;
+    /** How `summer setup --detect` tells the agent is on this computer (agent-detect.ts). */
+    detect: AgentDetect;
+}
+/**
+ * Where an agent shows up once it is installed, on macOS and Windows (Linux
+ * uses the bins and folders). Any one hit counts as installed; `--detect`
+ * names each hit, so a caller can tell a live binary from a leftover folder.
+ */
+export interface AgentDetect {
+    /** Commands: looked up on PATH and in the usual install folders a GUI app's short PATH misses (agent-detect.ts). */
+    bins?: readonly string[];
+    /** macOS app bundles, looked up in /Applications and ~/Applications. */
+    macApps?: readonly string[];
+    /** Windows executables, relative to %LOCALAPPDATA%, %ProgramFiles% and %ProgramFiles(x86)%. */
+    winApps?: readonly string[];
+    /** Folders the agent creates on install or first run (config, data or install folder). */
+    dirs?: (ctx: PathContext) => string[];
+    /** VS Code extension id prefixes, looked up in ~/.vscode/extensions (folders named <id>-<version>). */
+    vscodeExtensions?: readonly string[];
 }
 /** True when this location is the shared agentskills.io folder. */
 export declare function isSharedSkillsPath(path: string): boolean;