@cursor/july 0.1.93 → 0.1.95

package/dist/internal/session-engine.js

@@ -44,7 +44,8 @@ import { createHostFilesApi } from "./host-files.js";
 import { createHostKvApi } from "./host-kv.js";
 import { createHostOtelApi } from "./host-otel.js";
 import { createHostPlatforms, createHostSlackClient, } from "./host-platforms.js";
-import { formatContinuationToken, newContinuationKey, newSessionId, newToolCallId, } from "./ids.js";
+import { HostedAdmissionLocalSendError, isDuringHostedAdmission, } from "./hosted-admission-context.js";
+import { formatContinuationToken, newContinuationKey, newSessionId, newToolCallId, parseContinuationToken, } from "./ids.js";
 import { validateToolInput } from "./json-schema.js";
 import { McpHost } from "./mcp-host.js";
 import { shouldStartProcessMemoryTelemetry, startProcessMemoryTelemetry, } from "./process-memory-telemetry.js";
@@ -54,7 +55,7 @@ import { sessionExternalLinks } from "./session-links.js";
 import { SessionStore } from "./session-store.js";
 import { syncSkillsToStore } from "./skills-sync.js";
 import { StorageCoordinator } from "./storage-coordinator.js";
-import { decideToolCall } from "./tool-policy.js";
+import { decideToolCall, resolveEffect } from "./tool-policy.js";
 import { normalizeToolResult, toolCallErrorMessage } from "./tool-result.js";
 import { estimateTurnCostFromApi, roundCostUsd, } from "./turn-cost.js";
 import { TurnGovernor } from "./turn-governor.js";
@@ -90,6 +91,24 @@ export class ToolNotDirectlyCallableError extends Error {
         this.name = "ToolNotDirectlyCallableError";
     }
 }
+export class InvalidContinuationTokenError extends Error {
+    constructor(detail) {
+        super(`Invalid continuation token: ${detail}`);
+        this.name = "InvalidContinuationTokenError";
+    }
+}
+/**
+ * A session-bound direct call whose harness cwd cannot be materialized and
+ * whose effect is not read: a write tool may rely on ctx.workspaceDir being
+ * the real session workspace, so it fails typed instead of silently running
+ * in a scratch directory.
+ */
+export class WorkspaceUnavailableError extends Error {
+    constructor(toolName, cause) {
+        super(`Session workspace unavailable for tool "${toolName}": ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.name = "WorkspaceUnavailableError";
+    }
+}
 export class ToolInputError extends Error {
     constructor(args) {
         super(`Invalid input for tool "${args.toolName}": ${args.detail}`);
@@ -116,7 +135,7 @@ export class ApprovalInterruptedError extends Error {
 }
 export class SessionEngine {
     constructor(options) {
-        var _a, _b, _c, _d;
+        var _a, _b, _c, _d, _e;
         /** In-flight lazy restores, deduped per channel + continuation key. */
         this.restoreInFlight = new Map();
         this.channelsById = new Map();
@@ -189,6 +208,7 @@ export class SessionEngine {
         // for why the choice does not belong to the agent author.
         const frameworkStorage = selectFrameworkStorageDefinition({
             authored: options.project.storage,
+            architecture: options.project.agent.architecture,
         });
         this.storage =
             frameworkStorage === undefined
@@ -215,8 +235,11 @@ export class SessionEngine {
         // Peer and Cursor-account transports are symbolic until the serve host
         // resolves them; the host-side MCP registry starts with the concrete
         // connections and gains the rest via setResolvedConnections.
-        this.mcpHost = new McpHost(options.project.agent.connections.filter((connection) => !isSymbolicConnectionTransport(connection.transport)));
-        const basePlatforms = (_d = options.platforms) !== null && _d !== void 0 ? _d : createHostPlatforms();
+        this.mcpHost = new McpHost([
+            ...options.project.agent.connections,
+            ...((_d = options.project.agent.hostConnections) !== null && _d !== void 0 ? _d : []),
+        ].filter((connection) => !isSymbolicConnectionTransport(connection.transport)));
+        const basePlatforms = (_e = options.platforms) !== null && _e !== void 0 ? _e : createHostPlatforms();
         const slackBinding = resolveDedicatedSlackHostBinding(options.project.channels);
         this.platforms =
             slackBinding === undefined
@@ -477,6 +500,13 @@ export class SessionEngine {
         return __awaiter(this, arguments, void 0, function* (channelId, message, options = {}) {
             var _a;
             var _b, _c, _d, _e, _f, _g;
+            if (isDuringHostedAdmission()) {
+                // Only sends that bypassed the admission capture stub (typically a
+                // startup-captured `onStart` send) reach the engine inside the
+                // admission window; running one would leak an invisible local session
+                // on a sessionless pod.
+                throw new HostedAdmissionLocalSendError();
+            }
             const identity = channelId === HTTP_CHANNEL_ID
                 ? httpContinuationIdentity(this.project.httpChannel)
                 : channelContinuationIdentity(this.channelsById.get(channelId));
@@ -1539,23 +1569,17 @@ export class SessionEngine {
      * Connection names a cloud turn can only reach through the host connection
      * bridge on the tool MCP endpoint: filtered account connections without a
      * public bridge URL, and host-OAuth connections whose tokens live on this
-     * host. `hostOnly` names are never bridged — that flag means the model
-     * must not see the connection at all, on any runtime.
+     * host.
      */
     cloudBridgeableConnectionNames() {
-        const hostOnlyNames = new Set(this.project.agent.connections
-            .filter((connection) => connection.hostOnly === true)
-            .map((connection) => connection.name));
         const names = [];
         for (const connection of this.project.agent.connections) {
-            if (!hostOnlyNames.has(connection.name) &&
-                isHostOauthConnectionTransport(connection.transport)) {
+            if (isHostOauthConnectionTransport(connection.transport)) {
                 names.push(connection.name);
             }
         }
         for (const resolved of this.resolvedConnections) {
-            if (!hostOnlyNames.has(resolved.name) &&
-                resolved.accountServersFilter !== undefined &&
+            if (resolved.accountServersFilter !== undefined &&
                 resolved.cloudUrl === undefined) {
                 names.push(resolved.name);
             }
@@ -1565,8 +1589,7 @@ export class SessionEngine {
     /**
      * True when cloud turns reach `name` through the host connection bridge —
      * the gate the tool MCP endpoint applies before forwarding a bridge
-     * request to `host.mcp`, so `hostOnly` connections (and arbitrary names)
-     * stay unreachable from a VM.
+     * request to `host.mcp`, so arbitrary names stay unreachable from a VM.
      */
     isCloudBridgedConnection(name) {
         if (this.cloudServerToolsConnection === undefined) {
@@ -1591,24 +1614,26 @@ export class SessionEngine {
         return Object.assign(Object.assign({}, connection), { url: url.toString() });
     }
     /**
-     * Authored + resolved MCP servers for a turn. Skips `hostOnly`. On cloud
-     * turns, connections whose credential lives on this host — filtered
-     * account connections without a public bridge URL, host-OAuth servers —
-     * mount as host connection bridges over the tool MCP endpoint instead of
+     * Authored + resolved MCP servers for a turn. Skips advertised
+     * connections (those surface as named server tools). On cloud turns,
+     * connections whose credential lives on this host — filtered account
+     * connections without a public bridge URL, host-OAuth servers — mount
+     * as host connection bridges over the tool MCP endpoint instead of
      * being omitted or failing the turn closed.
      */
     buildMcpServers(runtime, sessionId, sessionAuth) {
+        var _a;
         // The Grok Bot harness manages its own MCP surface; authored
         // connections are refused at discovery, so there is nothing to mount.
         if (runtime === "grokbot") {
             return {};
         }
         // Advertised connections surface as named server tools instead of an
-        // attached MCP server (each tool appears exactly once), so they are
-        // excluded here alongside hostOnly.
-        const hostOnlyNames = new Set(this.project.agent.connections
-            .filter((connection) => connection.hostOnly === true || connection.advertiseTools === true)
+        // attached MCP server (each tool appears exactly once).
+        const advertisedNames = new Set(this.project.agent.connections
+            .filter((connection) => connection.advertiseTools === true)
             .map((connection) => connection.name));
+        const hostConnectionNames = new Set(((_a = this.project.agent.hostConnections) !== null && _a !== void 0 ? _a : []).map((connection) => connection.name));
         const bridgedNames = new Set(runtime === "cloud" &&
             sessionId !== undefined &&
             this.cloudServerToolsConnection !== undefined &&
@@ -1617,7 +1642,8 @@ export class SessionEngine {
             : []);
         assertCloudCanHonorAccountServersFilters({
             runtime,
-            resolvedConnections: this.resolvedConnections.filter((resolved) => !hostOnlyNames.has(resolved.name)),
+            resolvedConnections: this.resolvedConnections.filter((resolved) => !advertisedNames.has(resolved.name) &&
+                !hostConnectionNames.has(resolved.name)),
             bridgedNames,
         });
         const bridgeTransport = (name) => sessionId === undefined || !bridgedNames.has(name)
@@ -1625,7 +1651,8 @@ export class SessionEngine {
             : this.cloudBridgeTransport(sessionId, name);
         const servers = {};
         for (const connection of this.project.agent.connections) {
-            if (hostOnlyNames.has(connection.name)) {
+            if (advertisedNames.has(connection.name) ||
+                hostConnectionNames.has(connection.name)) {
                 continue;
             }
             if (isSymbolicConnectionTransport(connection.transport)) {
@@ -1661,7 +1688,8 @@ export class SessionEngine {
             servers[connection.name] = connection.transport;
         }
         for (const resolved of this.resolvedConnections) {
-            if (hostOnlyNames.has(resolved.name)) {
+            if (advertisedNames.has(resolved.name) ||
+                hostConnectionNames.has(resolved.name)) {
                 continue;
             }
             const url = runtime === "cloud" ? resolved.cloudUrl : resolved.localUrl;
@@ -1698,14 +1726,12 @@ export class SessionEngine {
     }
     /**
      * True when a connection with per-session `auth` attaches to the model
-     * (not `hostOnly`, not advertised). These turns set
+     * (not advertised). These turns set
      * {@link RunnerTurnRequest.perSendMcpServers} so the evaluated headers
      * ride every send instead of being pinned on the cached agent handle.
      */
     hasAttachedAuthedConnections() {
-        return this.project.agent.connections.some((connection) => connection.auth !== undefined &&
-            connection.hostOnly !== true &&
-            connection.advertiseTools !== true);
+        return this.project.agent.connections.some((connection) => connection.auth !== undefined && connection.advertiseTools !== true);
     }
     /**
      * Evaluate per-session connection auth (`defineConnection({ auth })`)
@@ -1716,9 +1742,7 @@ export class SessionEngine {
      */
     evaluateConnectionAuth(record) {
         return __awaiter(this, void 0, void 0, function* () {
-            const authed = this.project.agent.connections.filter((connection) => connection.auth !== undefined &&
-                connection.hostOnly !== true &&
-                connection.advertiseTools !== true);
+            const authed = this.project.agent.connections.filter((connection) => connection.auth !== undefined && connection.advertiseTools !== true);
             if (authed.length === 0) {
                 return undefined;
             }
@@ -2021,61 +2045,184 @@ export class SessionEngine {
      * with the same `{ content, isError }` envelope the model would see, not
      * an exception.
      */
-    callTool(toolName_1) {
-        return __awaiter(this, arguments, void 0, function* (toolName, input = {}, options = {}) {
-            var _a;
-            const tool = this.project.agent.tools.find((t) => t.name === toolName);
-            if (tool === undefined) {
-                throw new UnknownToolError(toolName, this.project.agent.tools
-                    .filter((t) => t.execution === "server")
-                    .map((t) => t.name));
-            }
-            const execute = tool.definition.execute;
-            if (tool.execution !== "server" || typeof execute !== "function") {
-                throw new ToolNotDirectlyCallableError(toolName);
-            }
-            const validation = validateToolInput(tool.definition.inputSchema, input);
-            if (!validation.ok) {
-                throw new ToolInputError({ toolName, detail: validation.message });
+    /**
+     * The session identity a direct call (or catalog listing) runs under:
+     * an explicit sessionId, a continuation token resolved to a live (or
+     * restorable) session with the same owner/busy checks a sessionId call
+     * gets, or — when neither maps to a session — a synthetic identity
+     * carrying the token's channel id and continuation key so binding
+     * resolvers (e.g. VFS mounts) can still serve the call.
+     */
+    resolveDirectCallIdentity(callId, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c;
+            if (options.sessionId !== undefined &&
+                options.continuationToken !== undefined) {
+                throw new InvalidContinuationTokenError("mutually exclusive with sessionId — a real session already carries its own continuation key");
             }
-            const callId = newToolCallId(toolName);
             const auth = (_a = options.auth) !== null && _a !== void 0 ? _a : null;
             let record;
-            let session;
-            let workspaceDir;
-            let scratchDir;
+            let continuation = null;
             if (options.sessionId !== undefined) {
                 record = yield this.sessions.get(options.sessionId);
                 if (record === undefined) {
                     throw new UnknownSessionError(options.sessionId);
                 }
+            }
+            else if (options.continuationToken !== undefined) {
+                continuation = parseContinuationToken(options.continuationToken);
+                if (continuation === null) {
+                    throw new InvalidContinuationTokenError(`expected "<channelId>:<key>" (as /v1/sessions lists it), got "${options.continuationToken}"`);
+                }
+                // A token that maps to a live (or restorable) session takes the
+                // session path: same owner check, same turn serialization, same
+                // event recording as an explicit sessionId. Skipping those just
+                // because the caller addressed the session by token would fail open.
+                record = (_b = (yield this.sessions.findByContinuation(continuation.channelId, continuation.key))) !== null && _b !== void 0 ? _b : (yield this.restoreSessionByContinuation(continuation.channelId, continuation.key));
+                if (record !== undefined && !samePrincipal(record.auth, auth)) {
+                    throw new SessionAuthError(record.sessionId);
+                }
+            }
+            if (record !== undefined) {
                 // Direct calls respect the same serialization as follow-up sends: a
                 // running model turn owns the session workspace and event stream.
                 if (this.activeTurns.has(record.sessionId) ||
                     this.pendingTurns.has(record.sessionId)) {
                     throw new SessionBusyError(record.sessionId);
                 }
-                session = this.sessionInfo(record);
-                workspaceDir = this.harnessCwd(record);
+                return {
+                    record,
+                    session: this.sessionInfo(record),
+                    workspaceDir: this.harnessCwd(record),
+                    scratchDir: undefined,
+                };
             }
-            else {
-                session = {
+            // No session behind the token (or no token at all): a synthetic
+            // session carries the token's channel id and key, so binding resolvers
+            // keyed on the continuation key (e.g. VFS mounts) can serve the call
+            // with no live session. The workspace stays scratch and nothing is
+            // recorded on a session event stream.
+            const scratchDir = join(this.stateRoot, "tool-calls", callId);
+            return {
+                record: undefined,
+                session: {
                     id: callId,
-                    channelId: DIRECT_TOOL_CALL_CHANNEL_ID,
+                    channelId: (_c = continuation === null || continuation === void 0 ? void 0 : continuation.channelId) !== null && _c !== void 0 ? _c : DIRECT_TOOL_CALL_CHANNEL_ID,
                     mode: "task",
+                    continuationKey: continuation === null || continuation === void 0 ? void 0 : continuation.key,
                     auth,
-                };
+                },
+                workspaceDir: scratchDir,
+                scratchDir,
+            };
+        });
+    }
+    /**
+     * The live tool catalog for one session identity: authored server tools
+     * plus the advertised passthroughs a turn under the same identity would
+     * see, under their model-facing names. A connection whose listing fails
+     * is skipped and reported in `connectionErrors` — the inspection surface
+     * degrades legibly instead of hiding every other tool behind one broken
+     * connector.
+     */
+    listCatalogTools() {
+        return __awaiter(this, arguments, void 0, function* (options = {}) {
+            const { session } = yield this.resolveDirectCallIdentity(newToolCallId("catalog"), options);
+            const connectionErrors = [];
+            const advertised = yield resolveAdvertisedTools({
+                agent: this.project.agent,
+                session,
+                hostMcp: this.mcpHost,
+                onConnectionError: (connection, error) => {
+                    connectionErrors.push({
+                        connection,
+                        message: error instanceof Error ? error.message : String(error),
+                    });
+                },
+            });
+            return {
+                tools: [...this.project.agent.tools, ...advertised],
+                connectionErrors,
+            };
+        });
+    }
+    callTool(toolName_1) {
+        return __awaiter(this, arguments, void 0, function* (toolName, input = {}, options = {}) {
+            const callId = newToolCallId(toolName);
+            // Identity resolves before the tool lookup: advertised connection tools
+            // only exist relative to a session (per-session auth), so finding them
+            // needs the same identity the call runs under.
+            const identity = yield this.resolveDirectCallIdentity(callId, options);
+            const record = identity.record;
+            const session = identity.session;
+            let workspaceDir = identity.workspaceDir;
+            let scratchDir = identity.scratchDir;
+            let tool = this.project.agent.tools.find((t) => t.name === toolName);
+            if (tool === undefined &&
+                this.project.agent.connections.some((c) => c.advertiseTools === true)) {
+                // Advertised passthroughs are ordinary server tools in the session's
+                // namespace; resolve the live listing so direct calls address them by
+                // the same model-facing name a turn would. A listing failure fails
+                // the call closed, like it fails a turn.
+                const advertised = yield resolveAdvertisedTools({
+                    agent: this.project.agent,
+                    session,
+                    hostMcp: this.mcpHost,
+                });
+                tool = advertised.find((t) => t.name === toolName);
+            }
+            if (tool === undefined) {
+                throw new UnknownToolError(toolName, this.project.agent.tools
+                    .filter((t) => t.execution === "server")
+                    .map((t) => t.name));
+            }
+            const execute = tool.definition.execute;
+            if (tool.execution !== "server" || typeof execute !== "function") {
+                throw new ToolNotDirectlyCallableError(toolName);
+            }
+            const validation = validateToolInput(tool.definition.inputSchema, input);
+            if (!validation.ok) {
+                throw new ToolInputError({ toolName, detail: validation.message });
+            }
+            let workspaceUnavailable = false;
+            try {
+                yield mkdir(workspaceDir, { recursive: true });
+            }
+            catch (error) {
+                if (record === undefined) {
+                    throw error;
+                }
+                // A session's harness cwd can be a path the serving process cannot
+                // create (e.g. an absolute `local.cwd` like /repo on a hosted pod
+                // where the sandboxed harness would have made it). Read-effect calls
+                // fall back to a scratch workspace instead of failing: tools that
+                // resolve their state from the session identity (VFS mounts) never
+                // touch ctx.workspaceDir. Advertised passthroughs are relocatable by
+                // construction: their execute body forwards to the connection and
+                // never reads the workspace. A write (or undeclared, which resolves
+                // to write) authored tool may rely on ctx.workspaceDir being the
+                // real session workspace, so silently relocating it is not safe —
+                // fail typed instead.
+                const relocatable = tool.advertised === true ||
+                    resolveEffect(tool.definition.effect, validation.value) === "read";
+                if (!relocatable) {
+                    throw new WorkspaceUnavailableError(toolName, error);
+                }
+                this.logger(`[session] tool ${toolName} workspace unavailable (direct ${callId}); using scratch: ${error instanceof Error ? error.message : String(error)}`);
                 scratchDir = join(this.stateRoot, "tool-calls", callId);
                 workspaceDir = scratchDir;
+                workspaceUnavailable = true;
+                yield mkdir(workspaceDir, { recursive: true });
             }
-            yield mkdir(workspaceDir, { recursive: true });
             // Match what a model turn would see: session workspaces get the same
             // scaffold as executeTurn (seeds only before the first turn); scratch
             // workspaces are materialized fresh.
             yield materializeWorkspace({
                 agent: this.project.agent,
-                workspaceDir: record === undefined ? workspaceDir : this.scaffoldDir(record),
-                seed: record === undefined || record.turnCount === 0,
+                workspaceDir: record === undefined || workspaceUnavailable
+                    ? workspaceDir
+                    : this.scaffoldDir(record),
+                seed: record === undefined || workspaceUnavailable || record.turnCount === 0,
                 stateRoot: this.stateRoot,
             });
             // A per-call turnId keeps these events visible in trajectories (which
@@ -2172,11 +2319,16 @@ export class SessionEngine {
                 });
             }
             const errorMessage = isError ? toolCallErrorMessage(result) : undefined;
-            return Object.assign(Object.assign({ toolName,
+            return {
+                toolName,
                 callId,
                 isError,
                 result,
-                durationMs }, (errorMessage === undefined ? {} : { errorMessage })), (record === undefined ? {} : { sessionId: record.sessionId }));
+                durationMs,
+                errorMessage,
+                sessionId: record === null || record === void 0 ? void 0 : record.sessionId,
+                scratchWorkspace: workspaceUnavailable ? true : undefined,
+            };
         });
     }
     /**

package/dist/internal/tool-catalog.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Projections for the live tool catalog (`GET /v1/tools` and
+ * `GET /v1/tools/:name`): the session's tool namespace exactly as a turn
+ * would assemble it — authored server tools plus advertised MCP
+ * passthroughs — under model-facing names.
+ *
+ * Titles are curated data, never derived from descriptions: advertised
+ * tools inherit the upstream server's MCP `annotations.title` (bounded at
+ * listing time), and the well-known non-MCP tool names carry a hardcoded
+ * title here so every deployment shows the same display names.
+ */
+import type { DiscoveredTool, JsonSchemaObject, ToolEffect, ToolExecution } from "../types.js";
+/** Light listing entry: identifiers and curated display data only. */
+export interface CatalogListEntry {
+    name: string;
+    title?: string;
+    /** Connection name for advertised MCP tools; absent for authored tools. */
+    source?: string;
+}
+/** Full description behind `GET /v1/tools/:name`. */
+export interface CatalogDetailEntry extends CatalogListEntry {
+    description: string;
+    execution: ToolExecution;
+    needsApproval: boolean;
+    effect?: ToolEffect | "dynamic";
+    inputSchema: JsonSchemaObject;
+    outputSchema?: JsonSchemaObject;
+}
+export declare function catalogListEntry(tool: DiscoveredTool): CatalogListEntry;
+export declare function catalogDetailEntry(tool: DiscoveredTool): CatalogDetailEntry;
+//# sourceMappingURL=tool-catalog.d.ts.map

package/dist/internal/tool-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-catalog.d.ts","sourceRoot":"","sources":["../../src/internal/tool-catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EAChB,UAAU,EACV,aAAa,EACd,MAAM,aAAa,CAAC;AAoDrB,sEAAsE;AACtE,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,qDAAqD;AACrD,MAAM,WAAW,kBAAmB,SAAQ,gBAAgB;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,aAAa,CAAC;IACzB,aAAa,EAAE,OAAO,CAAC;IACvB,MAAM,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IAChC,WAAW,EAAE,gBAAgB,CAAC;IAC9B,YAAY,CAAC,EAAE,gBAAgB,CAAC;CACjC;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,gBAAgB,CAMvE;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,cAAc,GAAG,kBAAkB,CAU3E"}

package/dist/internal/tool-catalog.js

@@ -0,0 +1,67 @@
+/**
+ * Projections for the live tool catalog (`GET /v1/tools` and
+ * `GET /v1/tools/:name`): the session's tool namespace exactly as a turn
+ * would assemble it — authored server tools plus advertised MCP
+ * passthroughs — under model-facing names.
+ *
+ * Titles are curated data, never derived from descriptions: advertised
+ * tools inherit the upstream server's MCP `annotations.title` (bounded at
+ * listing time), and the well-known non-MCP tool names carry a hardcoded
+ * title here so every deployment shows the same display names.
+ */
+/**
+ * Display names for the well-known tool names that do not come from MCP
+ * (authored tools have no title field; adding one to `defineTool` for a
+ * presentation concern is not worth the authoring surface).
+ */
+const WELL_KNOWN_TOOL_TITLES = {
+    diff: "Show change diffs",
+    glob: "Find files by pattern",
+    grep: "Search file contents",
+    ls: "List a directory",
+    read: "Read a file",
+    search: "Search with a typed query",
+    write: "Write a file",
+};
+function catalogTitle(tool) {
+    var _a;
+    if (tool.advertised === true) {
+        return (_a = tool.annotations) === null || _a === void 0 ? void 0 : _a.title;
+    }
+    return WELL_KNOWN_TOOL_TITLES[tool.name];
+}
+/**
+ * Sand connector identifiers scope the connector name by owner
+ * (`dashboard-team-<id>-Buildkite`, `dashboard-<Name>`, `user-<Name>`);
+ * the suffix is the human-meaningful name.
+ */
+const CONNECTOR_SCOPE_PREFIX = /^(?:dashboard-team-\d+-|dashboard-|user-)/;
+/**
+ * Where a tool comes from, for humans: the upstream connector/plugin name
+ * when the tool declares one (the reserved `__conn__` selector's values
+ * name it), the connection name otherwise. One aggregating connection
+ * (e.g. a tenant `plugins` endpoint) hosts tools from several connectors,
+ * and "plugins" tells an operator nothing — "Buildkite" does.
+ */
+function catalogSource(tool) {
+    var _a, _b;
+    if (tool.advertised !== true) {
+        return undefined;
+    }
+    const properties = tool.inputSchema.properties;
+    const first = (_b = (_a = properties === null || properties === void 0 ? void 0 : properties.__conn__) === null || _a === void 0 ? void 0 : _a.enum) === null || _b === void 0 ? void 0 : _b[0];
+    if (typeof first === "string" && first !== "") {
+        return first.replace(CONNECTOR_SCOPE_PREFIX, "");
+    }
+    return tool.connection;
+}
+export function catalogListEntry(tool) {
+    return {
+        name: tool.name,
+        title: catalogTitle(tool),
+        source: catalogSource(tool),
+    };
+}
+export function catalogDetailEntry(tool) {
+    return Object.assign(Object.assign({}, catalogListEntry(tool)), { description: tool.description, execution: tool.execution, needsApproval: tool.needsApproval, effect: tool.effect, inputSchema: tool.inputSchema, outputSchema: tool.outputSchema });
+}