@zackbart/connecta 0.24.4 → 0.26.0

package/dist/catalog-service.js

@@ -1,9 +1,12 @@
-import { compactDiscoverySchema, compactDescriptionSchema, lexicalCorpusStatistics, lexicalQueryTerms, lexicalSearchQuery, matchesLexicalTerm, rankTools, schemaObjectKeys, summarizeDiscoveryDescription, summarizeDescription, } from "./catalog.js";
-import { mapSettledWithConcurrency, resolveDiscoveryConcurrency, } from "./concurrency.js";
+import { Effect, Result } from "effect";
+import { compactDiscoverySchema, compactDescriptionSchema, lexicalCorpusStatistics, lexicalQueryTerms, lexicalSearchQuery, matchesLexicalTerm, rankTools, schemaObjectKeys, summarizeDiscoveryDescription, summarizeDescription, typescriptSignature, } from "./catalog.js";
+import { resolveDiscoveryConcurrency } from "./concurrency.js";
 import { boundedEchoText, classifyCallError, framingError, } from "./errors.js";
 import { connectorGuide, connectorGuideRequired, connectorGuideSummary, connectorSkillName, } from "./skills.js";
-import { DEFAULT_PROBE_TIMEOUT_MS, normalizeTimeoutMs, withDeadline, } from "./timeout.js";
-import { isExplicitlyReadOnly } from "./tool-safety.js";
+import { runEdge, withDeadlineEffect } from "./runtime/run.js";
+import { SharedRead } from "./runtime/shared-read.js";
+import { DEFAULT_PROBE_TIMEOUT_MS, normalizeTimeoutMs, } from "./timeout.js";
+import { isApprovalExempt, isExplicitlyReadOnly, NO_EXEMPTIONS, } from "./tool-safety.js";
 export const DEFAULT_SEARCH_LIMIT = 8;
 export const MAX_SEARCH_LIMIT = 100;
 export const MAX_DESCRIBE_ADDRESSES = 100;
@@ -199,16 +202,31 @@ export class CatalogService {
     concurrency;
     searchRoute;
     readOptions;
-    loaded = new Map();
-    loading = new Map();
+    requestSignal;
+    approval;
+    // The request-scoped catalog cache: one shared read per connector asked
+    // about, started by the first asker and joined by every later one. A
+    // success stays for the rest of the request, so a search and the call after
+    // it see one catalog; a failure, or a read cancelled because every asker
+    // left it, is dropped so the next ask reads again. The service lives and
+    // dies with one request, so no read here is ever awaited from another.
+    //
+    // Registry.getTools also joins concurrent reads in one request scope, which
+    // the operator UI and status reads rely on. This map overlaps it only for
+    // reads still in flight and is kept for what the registry's cannot do: hold
+    // the success for the rest of the request, recorded by the read itself
+    // rather than by an asker, whose probe deadline may have ended its wait.
+    catalogs = new Map();
     constructor(registry, baseUrl, options = {}) {
         this.registry = registry;
         this.baseUrl = baseUrl;
+        this.approval = options.approval ?? NO_EXEMPTIONS;
         this.requestScope = options.requestScope ?? {};
         this.probeTimeoutMs =
             normalizeTimeoutMs(options.probeTimeoutMs) ?? DEFAULT_PROBE_TIMEOUT_MS;
         this.concurrency = resolveDiscoveryConcurrency(options.concurrency);
         this.searchRoute = options.searchRoute ?? "search_tools";
+        this.requestSignal = options.requestSignal;
         this.readOptions = options.defer
             ? {
                 defer: options.defer,
@@ -237,34 +255,44 @@ export class CatalogService {
             ? { function: "connecta.search", arguments: searchArgs, purpose }
             : { tool: "search_tools", arguments: searchArgs, purpose };
     }
-    async loadConnector(id, callOptions = {}) {
-        const cached = this.loaded.get(id);
-        if (cached)
-            return cached;
-        const inFlight = this.loading.get(id);
-        if (inFlight)
-            return inFlight;
-        const loading = this.registry
-            .getTools(id, this.baseUrl, this.requestScope, callOptions, this.readOptions)
-            .then((tools) => {
-            this.loaded.set(id, tools);
-            return tools;
-        })
-            .finally(() => {
-            if (this.loading.get(id) === loading)
-                this.loading.delete(id);
+    loadConnector(id, callOptions = {}) {
+        return runEdge(this.catalog(id, callOptions));
+    }
+    // One connector's catalog from the request-scoped cache, reading it through
+    // the registry when this request has not yet. No asker's options govern the
+    // read: it carries its own signal and the catalog deadline, the probe
+    // timeout, whichever asker starts it. Each asker waits under its own signal
+    // and deadline, so a short-deadline call that starts the read and a search
+    // that joins it each end on their own terms, and the read is cancelled only
+    // once every asker has gone (#571).
+    catalog(id, callOptions) {
+        return Effect.suspend(() => {
+            let read = this.catalogs.get(id);
+            if (!read) {
+                const started = new SharedRead((signal) => this.registry.getTools(id, this.baseUrl, this.requestScope, { signal, timeoutMs: this.probeTimeoutMs }, this.readOptions), (succeeded) => {
+                    // Evicted before the read resumes anyone, so an asker that
+                    // retries on hearing of the failure starts a fresh read.
+                    if (!succeeded && this.catalogs.get(id) === started) {
+                        this.catalogs.delete(id);
+                    }
+                });
+                this.catalogs.set(id, started);
+                read = started;
+            }
+            return read.join(callOptions.signal);
         });
-        this.loading.set(id, loading);
-        return loading;
     }
-    loadForDiscovery(id, label) {
-        return withDeadline((signal) => this.loadConnector(id, {
-            signal,
-            timeoutMs: this.probeTimeoutMs,
-        }), {
+    // Every named catalog under its own probe deadline, `concurrency` at a time,
+    // each settling in its input slot: an unavailable catalog is a Failure
+    // there, not a failed discovery. `route` names the surface in a timeout.
+    // A probe also ends with its request, so no listing outlives the caller
+    // that asked for it.
+    discoveryCatalogs(ids, route) {
+        return Effect.forEach(ids, (id) => Effect.result(withDeadlineEffect((signal) => this.catalog(id, { signal }), {
+            ...(this.requestSignal ? { signal: this.requestSignal } : {}),
             timeoutMs: this.probeTimeoutMs,
-            timeoutError: new Error(`${label} timed out after ${this.probeTimeoutMs}ms`),
-        });
+            timeoutError: new Error(`${route} probe of "${id}" timed out after ${this.probeTimeoutMs}ms`),
+        })), { concurrency: this.concurrency });
     }
     outputSchema(connectorId, tool) {
         if (tool.outputSchema)
@@ -306,32 +334,35 @@ export class CatalogService {
             toolName,
         };
     }
-    async resolveTool(address, callOptions = {}) {
-        const resolved = this.registry.resolveAddress(address);
-        if (!resolved) {
-            return this.unknownAddressFailure(address, address);
-        }
-        const started = Date.now();
-        let tools;
-        try {
-            tools = await this.loadConnector(resolved.connector.id, callOptions);
-        }
-        catch (cause) {
-            return this.catalogLoadFailure(cause, started, resolved.connector, resolved.toolName);
-        }
-        const definition = tools.find((tool) => tool.name === resolved.toolName);
-        if (!definition) {
-            return this.unknownToolFailure(resolved.toolName, resolved.connector, started);
-        }
-        return {
-            ok: true,
-            resolved: {
-                connector: resolved.connector,
-                toolName: resolved.toolName,
-                definition,
-            },
-            catalogMs: Date.now() - started,
-        };
+    resolveTool(address, callOptions = {}) {
+        return runEdge(this.resolve(address, callOptions));
+    }
+    // resolveTool without the Promise, for InvocationService's pipeline, which
+    // yields it inside the call's deadline rather than crossing an edge. Never
+    // fails: an unloadable catalog is a resolution like any other refusal.
+    resolve(address, callOptions = {}) {
+        return Effect.suspend(() => {
+            const resolved = this.registry.resolveAddress(address);
+            if (!resolved) {
+                return Effect.succeed(this.unknownAddressFailure(address, address));
+            }
+            const { connector, toolName } = resolved;
+            const started = Date.now();
+            return Effect.match(this.catalog(connector.id, callOptions), {
+                onFailure: (cause) => this.catalogLoadFailure(cause, started, connector, toolName),
+                onSuccess: (tools) => {
+                    const definition = tools.find((tool) => tool.name === toolName);
+                    if (!definition) {
+                        return this.unknownToolFailure(toolName, connector, started);
+                    }
+                    return {
+                        ok: true,
+                        resolved: { connector, toolName, definition },
+                        catalogMs: Date.now() - started,
+                    };
+                },
+            });
+        });
     }
     async search(args) {
         if (args.query !== undefined && typeof args.query !== "string") {
@@ -361,21 +392,14 @@ export class CatalogService {
                 ? [scopedConnector]
                 : []
             : this.registry.listConnectors();
-        const catalogs = await mapSettledWithConcurrency(connectors, this.concurrency, (connector) => 
-        // Unlike the describe path, this label never reaches a caller: search
-        // only counts rejected catalogs (`unavailableCatalogs` below) and
-        // renders its own guidance, so the folded name here stays internal and
-        // needs no surface awareness.
-        this.loadForDiscovery(connector.id, `search_tools probe of "${connector.id}"`));
-        const searchableCatalogs = catalogs.map((catalog) => catalog.status === "fulfilled"
-            ? {
-                status: "fulfilled",
-                value: toolsForSafety(catalog.value, safety),
-            }
-            : catalog);
+        // Named for this service's route: a scoped search echoes a timed-out
+        // probe's message back as `queryAnalysis.catalogError`, and a program
+        // cannot call search_tools.
+        const catalogs = await runEdge(this.discoveryCatalogs(connectors.map((connector) => connector.id), this.searchRoute));
+        const searchableCatalogs = catalogs.map((catalog) => Result.map(catalog, (tools) => toolsForSafety(tools, safety)));
         const matches = [];
         let matchMode = "all";
-        const statistics = lexicalCorpusStatistics(searchableCatalogs.flatMap((catalog) => catalog.status === "fulfilled" ? [catalog.value] : []), retrievalQuery);
+        const statistics = lexicalCorpusStatistics(searchableCatalogs.flatMap((catalog) => Result.isSuccess(catalog) ? [catalog.success] : []), retrievalQuery);
         const trimmedQuery = query.trim();
         const isBrowse = trimmedQuery.length === 0;
         const queryTerms = lexicalQueryTerms(retrievalQuery);
@@ -394,8 +418,8 @@ export class CatalogService {
                 if (!connector) {
                     throw new Error("Catalog result has no corresponding connector");
                 }
-                if (catalog.status === "fulfilled") {
-                    for (const ranked of rankTools(catalog.value, retrievalQuery, mode, statistics, query)) {
+                if (Result.isSuccess(catalog)) {
+                    for (const ranked of rankTools(catalog.success, retrievalQuery, mode, statistics, query)) {
                         collected.push({
                             connector,
                             tool: ranked.tool,
@@ -407,8 +431,7 @@ export class CatalogService {
                         });
                     }
                 }
-                orderBase +=
-                    catalog.status === "fulfilled" ? catalog.value.length : 1;
+                orderBase += Result.isSuccess(catalog) ? catalog.success.length : 1;
             });
             return collected;
         };
@@ -444,12 +467,23 @@ export class CatalogService {
                 ? this.outputSchema(match.connector.id, match.tool)
                 : {};
             const input = match.tool.inputSchema ?? { type: "object" };
-            const renderedInput = withSchemas
-                ? renderSearchSchema(input, withSchemas)
-                : undefined;
-            const renderedOutput = withSchemas && output.schema
-                ? renderSearchSchema(output.schema, withSchemas)
+            const signature = withSchemas === "typescript"
+                ? typescriptSignature(input, output.schema, {
+                    observed: output.source === "observed",
+                    description: false,
+                })
                 : undefined;
+            const schemaFormat = withSchemas === "typescript" ? undefined : withSchemas;
+            const renderedInput = signature
+                ? { schema: undefined, truncated: signature.inputTruncated }
+                : schemaFormat
+                    ? renderSearchSchema(input, schemaFormat)
+                    : undefined;
+            const renderedOutput = signature
+                ? { schema: undefined, truncated: signature.outputTruncated }
+                : schemaFormat && output.schema
+                    ? renderSearchSchema(output.schema, schemaFormat)
+                    : undefined;
             const schemaKeys = withSchemas && args.includeSchemaKeys
                 ? schemaKeyMetadata(input, output.schema)
                 : undefined;
@@ -468,15 +502,16 @@ export class CatalogService {
                     name: match.tool.name,
                     address: `${match.connector.id}.${match.tool.name}`,
                     ...(description !== undefined ? { description } : {}),
-                    ...(withSchemas
+                    ...(schemaFormat
                         ? {
                             inputSchema: renderedInput?.schema,
                         }
                         : {}),
+                    ...(signature ? { signature: signature.text } : {}),
                     ...(renderedInput?.truncated
                         ? { inputSchemaTruncated: true }
                         : {}),
-                    ...(withSchemas && output.schema
+                    ...(schemaFormat && output.schema
                         ? {
                             outputSchema: renderedOutput?.schema,
                         }
@@ -503,6 +538,11 @@ export class CatalogService {
                     ...(match.tool.annotations
                         ? { annotations: match.tool.annotations }
                         : {}),
+                    // Config lets a program call this write without pausing (#566).
+                    // A marker, not a class: the tool stays approval-required.
+                    ...(isApprovalExempt(this.approval, match.connector, match.tool.name, match.tool)
+                        ? { approval: "exempt" }
+                        : {}),
                     ...(requiredReasons
                         ? {
                             guideRequired: true,
@@ -535,16 +575,19 @@ export class CatalogService {
                 unmatchedTerms.push(displayTerm(term));
             }
         }
-        const unavailableCatalogs = catalogs.filter((catalog) => catalog.status === "rejected").length;
+        const unavailableCatalogs = catalogs.filter(Result.isFailure).length;
         // Named field by field rather than spread: `CallErrorDetails` also carries
         // connector, operation, recovery, and nextAction, and a discovery read is
         // not a call — widening the classifier must not silently widen what a
         // catalog search hands back.
         const scopedCatalogError = (() => {
-            if (!scopedConnector || catalogs[0]?.status !== "rejected") {
+            const scopedCatalog = catalogs[0];
+            if (!scopedConnector ||
+                !scopedCatalog ||
+                Result.isSuccess(scopedCatalog)) {
                 return undefined;
             }
-            const error = classifyCallError(catalogs[0].reason, "catalog_lookup_failed");
+            const error = classifyCallError(scopedCatalog.failure, "catalog_lookup_failed");
             return {
                 code: error.code,
                 message: boundedEchoText(error.message),
@@ -717,19 +760,8 @@ export class CatalogService {
                 .map((entry) => entry.resolved?.connector.id)
                 .filter((id) => Boolean(id))),
         ];
-        const loaded = await mapSettledWithConcurrency(connectorIds, this.concurrency, (id) => this.loadForDiscovery(id, `connecta.describe probe of "${id}"`));
-        const catalogs = new Map();
-        loaded.forEach((result, index) => {
-            const connectorId = connectorIds[index];
-            if (connectorId === undefined) {
-                throw new Error("Catalog result has no corresponding connector id");
-            }
-            catalogs.set(connectorId, result.status === "fulfilled"
-                ? result.value
-                : result.reason instanceof Error
-                    ? result.reason
-                    : new Error(String(result.reason)));
-        });
+        const loaded = await runEdge(this.discoveryCatalogs(connectorIds, "connecta.describe"));
+        const catalogs = new Map(connectorIds.map((id, index) => [id, loaded[index]]));
         return resolved.map(({ address, resolved: addressResolution }) => {
             if (!addressResolution) {
                 const message = `Unknown address "${boundedEchoText(address)}"`;
@@ -743,8 +775,8 @@ export class CatalogService {
                 };
             }
             const catalog = catalogs.get(addressResolution.connector.id);
-            if (catalog instanceof Error) {
-                const classified = classifyCallError(catalog, "catalog_lookup_failed");
+            if (catalog && Result.isFailure(catalog)) {
+                const classified = classifyCallError(catalog.failure, "catalog_lookup_failed");
                 const message = boundedEchoText(classified.message);
                 return {
                     address: boundedEchoText(address),
@@ -759,10 +791,11 @@ export class CatalogService {
                     },
                 };
             }
-            const tool = catalog?.find((item) => item.name === addressResolution.toolName);
+            const tools = catalog?.success ?? [];
+            const tool = tools.find((item) => item.name === addressResolution.toolName);
             if (!tool) {
                 const message = `Unknown tool "${boundedEchoText(addressResolution.toolName)}" on connector "${addressResolution.connector.id}"`;
-                const suggestions = describeSuggestions(addressResolution.connector.id, addressResolution.toolName, catalog ?? []);
+                const suggestions = describeSuggestions(addressResolution.connector.id, addressResolution.toolName, tools);
                 return {
                     address: boundedEchoText(address),
                     error: message,
@@ -779,11 +812,19 @@ export class CatalogService {
             const input = tool.inputSchema ?? { type: "object" };
             const output = this.outputSchema(addressResolution.connector.id, tool);
             const description = summarizeDescription(tool.description, args.fullDescriptions === true);
+            const signature = format === "typescript"
+                ? typescriptSignature(input, output.schema, {
+                    observed: output.source === "observed",
+                    description: true,
+                })
+                : undefined;
             const compactInput = format === "compact"
                 ? compactDescriptionSchema(input) : undefined;
             const compactOutput = format === "compact" && output.schema
                 ? compactDescriptionSchema(output.schema) : undefined;
-            const requiredReasons = guideRequiredReasons(addressResolution.connector, tool, compactInput?.truncated === true || compactOutput?.truncated === true);
+            const inputTruncated = compactInput?.truncated === true || signature?.inputTruncated === true;
+            const outputTruncated = compactOutput?.truncated === true || signature?.outputTruncated === true;
+            const requiredReasons = guideRequiredReasons(addressResolution.connector, tool, inputTruncated || outputTruncated);
             const guideSummary = connectorGuideSummary(addressResolution.connector);
             return {
                 address,
@@ -801,16 +842,21 @@ export class CatalogService {
                         guideRequiredReasons: requiredReasons,
                     }
                     : {}),
-                inputSchema: compactInput?.text ?? input,
-                ...(compactInput?.truncated ? { inputSchemaTruncated: true } : {}),
-                ...(compactOutput?.truncated ? { outputSchemaTruncated: true } : {}),
-                ...(output.schema
+                ...(signature
+                    ? { signature: signature.text }
+                    : { inputSchema: compactInput?.text ?? input }),
+                ...(inputTruncated ? { inputSchemaTruncated: true } : {}),
+                ...(outputTruncated ? { outputSchemaTruncated: true } : {}),
+                ...(output.schema && !signature
                     ? {
                         outputSchema: compactOutput?.text ?? output.schema,
                     }
                     : {}),
                 ...(output.source ? { outputSchemaSource: output.source } : {}),
                 ...(tool.annotations ? { annotations: tool.annotations } : {}),
+                ...(isApprovalExempt(this.approval, addressResolution.connector, tool.name, tool)
+                    ? { approval: "exempt" }
+                    : {}),
             };
         });
     }