@zackbart/connecta 0.24.3 → 0.25.0

package/dist/catalog-service.js

@@ -1,8 +1,10 @@
-import { compactDiscoverySchema, compactDescriptionSchema, lexicalCorpusStatistics, lexicalQueryTerms, lexicalSearchQuery, matchesLexicalTerm, rankTools, schemaObjectKeys, summarizeDiscoveryDescription, summarizeDescription, } from "./catalog.js";
-import { mapSettledWithConcurrency, resolveDiscoveryConcurrency, } from "./concurrency.js";
+import { Deferred, Effect, Exit, 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 { runEdge, withDeadlineEffect } from "./runtime/run.js";
+import { DEFAULT_PROBE_TIMEOUT_MS, normalizeTimeoutMs, } from "./timeout.js";
 import { isExplicitlyReadOnly } from "./tool-safety.js";
 export const DEFAULT_SEARCH_LIMIT = 8;
 export const MAX_SEARCH_LIMIT = 100;
@@ -199,8 +201,20 @@ export class CatalogService {
     concurrency;
     searchRoute;
     readOptions;
-    loaded = new Map();
-    loading = new Map();
+    requestSignal;
+    // The request-scoped catalog cache: one Deferred per connector asked about,
+    // completed by the first asker's registry read 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 is dropped so the next ask reads
+    // again. The service lives and dies with one request, so no Deferred 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;
@@ -209,6 +223,7 @@ export class CatalogService {
             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 +252,45 @@ 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. The first asker's options
+    // govern the read and a joiner shares its outcome, as the registry's own
+    // flight below does. The read settles the Deferred itself, not the asker's
+    // fiber, so a probe deadline ends one asker's wait and never the read.
+    catalog(id, callOptions) {
+        return Effect.suspend(() => {
+            const cached = this.catalogs.get(id);
+            if (cached)
+                return Deferred.await(cached);
+            const read = Deferred.makeUnsafe();
+            this.catalogs.set(id, read);
+            // The executor turns a synchronous throw from getTools into a rejection.
+            new Promise((resolve) => resolve(this.registry.getTools(id, this.baseUrl, this.requestScope, callOptions, this.readOptions))).then((tools) => {
+                Deferred.doneUnsafe(read, Exit.succeed(tools));
+            }, (cause) => {
+                // Evicted before the Deferred resumes anyone, so an asker that
+                // retries on hearing of the failure starts a fresh read.
+                if (this.catalogs.get(id) === read)
+                    this.catalogs.delete(id);
+                Deferred.doneUnsafe(read, Exit.fail(cause));
+            });
+            return Deferred.await(read);
         });
-        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, timeoutMs: this.probeTimeoutMs }), {
+            ...(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 +332,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 +390,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 +416,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 +429,7 @@ export class CatalogService {
                         });
                     }
                 }
-                orderBase +=
-                    catalog.status === "fulfilled" ? catalog.value.length : 1;
+                orderBase += Result.isSuccess(catalog) ? catalog.success.length : 1;
             });
             return collected;
         };
@@ -444,12 +465,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 +500,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,
                         }
@@ -535,16 +568,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 +753,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 +768,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 +784,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 +805,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,10 +835,12 @@ 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,
                     }