@zackbart/connecta 0.37.1 → 0.39.0

package/dist/types.d.ts

@@ -193,6 +193,14 @@ export interface ConnectorCredentialConfig {
      */
     fields?: ConnectorCredentialFieldConfig[];
 }
+/**
+ * Why a credential test did not pass, as a typed fact with no downstream text.
+ * `rejected`: the service refused the credential. `scope`: it accepted the
+ * credential but refused a permission the connection needs. `unreachable`: the
+ * service could not be reached or was unavailable. `timeout`: it did not
+ * answer within the test's deadline. `failed`: anything else.
+ */
+export type CredentialFailureClass = "rejected" | "scope" | "unreachable" | "timeout" | "failed";
 export interface CredentialTestResult {
     ok: boolean;
     /**
@@ -201,6 +209,25 @@ export interface CredentialTestResult {
      * `ok`, and the log records only that a test failed.
      */
     message?: string;
+    /**
+     * Why a failed test failed. Optional: an unclassified failure is `failed`.
+     * Ignored when `ok` is true.
+     */
+    failure?: CredentialFailureClass;
+}
+/**
+ * How agent-facing text names Connecta's routes on the surface serving an
+ * operation: `call_tool`, `call_destructive_tool`, `search_tools`,
+ * `execute_code`, `authorize_connector` and `skills` on the six-tool surface,
+ * and other wording where those tools are not listed.
+ */
+export interface AgentRouteNames {
+    readonly search: string;
+    readonly read: string;
+    readonly write: string;
+    readonly program: string;
+    readonly authorize: string;
+    readonly skills: string;
 }
 export interface ConnectorContext {
     /** Explicit downstream consent initiation, never set by status/catalog/calls. */
@@ -236,6 +263,12 @@ export interface ConnectorContext {
     defer?: (promise: Promise<unknown>) => void;
     /** Requested connector-operation deadline in milliseconds. */
     timeoutMs?: number;
+    /**
+     * Route names for text this operation writes for the agent, such as "call
+     * authorize_connector" in an auth error. Connecta sets it on every context
+     * it builds; build such text from it rather than spelling a tool name.
+     */
+    routes?: AgentRouteNames;
 }
 type ConnectorStatusState = "ok" | "per_caller" | "auth_required" | "credential_required" | "error";
 /** The last agent-facing catalog read this runtime served for one connector. */

package/dist/url-safety.js

@@ -117,10 +117,6 @@ export function classifyHost(hostname) {
         return "loopback";
     return "public";
 }
-/** True for loopback and private hosts alike. */
-export function isPrivateHost(hostname) {
-    return classifyHost(hostname) !== "public";
-}
 /**
  * Why connecta must not fetch `target`, a URL the downstream advertised, for a
  * connector configured at `configured` — or undefined when it may.

package/dist/usage-guide.js

@@ -1,43 +1,36 @@
+import { META_ROUTES } from "./agent-routes.js";
+import { UNCOUNTED_GUEST_FUNCTIONS } from "./guest-functions.js";
 /** Self-contained content for the usage skill; independent of skill registration. */
 export const USAGE_SKILL = `---
 name: usage
-description: How to route work between one execute_code program and Connecta's explicit call, authorization, and result tools.
+description: How to route work between one ${META_ROUTES.program} program and Connecta's explicit call, authorization, and result tools.
 ---
 
 # Connecta usage
 
 ## Choose the route
 
-| Work | Tool |
-| --- | --- |
-| One known-address read | call_tool |
-| One known-address write | call_destructive_tool |
-| Discovery, multiple or dependent calls, paging, reduction | execute_code |
-
-Read one account with call_tool: \`{ "address": "crm.get_account", "args": { "id": "acct_42" } }\`.
-Discover and call together when schemas suffice. search_tools covers catalog
-inspection. On a read-only endpoint, as execute_code's description says, search
-omits writes (guides may name them) and each fails read_only_endpoint; tell the
-user. Unannotated tools fail closed to writes.
-For a requested write, make the call through the write route; the host may ask
-the user to confirm it. Connecta classifies and routes writes; the host owns approval.
+Route as the server instructions and ${META_ROUTES.program}'s first sentence say.
+Read one account with ${META_ROUTES.read}: \`{ "address": "crm.get_account", "args": { "id": "acct_42" } }\`.
+On a read-only endpoint search omits writes (guides may name them) and each
+fails read_only_endpoint; tell the user. Unannotated tools fail closed to writes.
+Connecta classifies and routes a requested write; the host owns approval.
 
 ## The global and the envelopes
 
 Pass JavaScript \`async () => { ... }\`, no arguments. Do not shadow \`connecta\`.
 No imports, require, filesystem, fetch, or timers.
 
-Use \`connecta.call(address, args, { timeoutMs })\` or
-\`connecta.call({ address, args, timeoutMs })\`; both return \`{ data, format }\`.
-\`format: "json"\` carries JSON; \`format: "text"\` carries text. Parse text only
-when documented as JSON. Verify collection roots.
+\`connecta.call(address, args, { timeoutMs })\` and
+\`connecta.call({ address, args, timeoutMs })\` return \`{ data, format }\`.
+Parse \`format: "text"\` only when documented as JSON. Verify collection roots.
 
 \`connecta.read("resource://id/"+encodeURIComponent(uri))\` returns \`{ contents }\` for advertised URIs.
 
-Search/describe return \`{ tools }\`, never an array. Search also returns
-\`catalogErrors\`, pagination, and possible \`absence\`; check failures before
-selecting a match. JSON schemas are the program default. Compact schemas have
-\`schemaFormat: "text"\`; do not read their .properties. Select the exact tool and
+Search/describe return \`{ tools }\`, never an array. Check search's
+\`catalogErrors\` and \`absence\` before selecting a match. Search defaults to a
+TypeScript \`signature\`; text schemas have \`schemaFormat: "text"\` and no .properties.
+A \`readyCalls\` entry is a complete read: \`connecta.call(entry.address, entry.args)\`. Select the exact tool and
 account/environment, inspect its schema, and supply its required keys and types.
 
 Discover an unfamiliar read and reduce its result:
@@ -79,13 +72,13 @@ async () => {
 
 Host-call budget exhaustion ends the run with budget_exceeded. Catch and
 allSettled cannot recover it or return partial output. Bound batches before
-starting them; every guest call except emit spends host calls.
+starting them; every guest call except ${UNCOUNTED_GUEST_FUNCTIONS} spends host calls.
 Split remaining reads. Never replay writes for their output.
 
 ## Per-connector guides
 
-Fetch a listed guide with skills by its exact name, or \`connecta.skill(name)\`
-inside a program; it returns \`{ name, text, format: "text" }\`.
+Fetch a listed guide by its exact name with the skills tool, or
+\`connecta.skill(name)\` inside a program; it returns \`{ name, text, format: "text" }\`.
 \`guideRequired: true\` is a hard stop. connector_required and approval_required
 remain after schema expansion; schema_truncated clears after exact describe.
 Otherwise fetch for units, pagination, aliases, or sequences.
@@ -134,15 +127,3 @@ base64 and PNG/JPEG/GIF/WebP MIME. Emit works without await, delivers on success
 and obeys byte/block budgets; text shares the return cap. Return reduced JSON.
 
 `;
-/** Kept in sync with GuestApi by the declaration test. These are type notation, not runnable JS. */
-export const GUEST_API_DECLARATION = `search(args?: CatalogSearchArgs): Promise<CatalogSearchResult>;
-describe(args?: CatalogDescribeArgs): Promise<{ tools: CatalogDescription[] }>;
-call(address: string, args?: unknown, options?: { timeoutMs?: number }): Promise<GuestResult>;
-call(request: { address: string; args?: unknown; timeoutMs?: number }): Promise<GuestResult>;
-read(uri: string): Promise<GuestResourceResult>;
-result(
-  id: string | GuestResultHandle,
-  options?: { page?: number; offset?: number; maxBytes?: number },
-): Promise<GuestResultPage>;
-skill(name: string): Promise<{ name: string; text: string; format: "text" }>;
-emit(block: GuestNativeBlock | GuestResult): PromiseLike<void>;`;

package/dist/validate.d.ts

@@ -1,4 +1,5 @@
 import { ConnectorCallError } from "./errors.js";
+import type { ArgumentValidationDetails } from "./errors.js";
 import { type FailureSubject } from "./operator-record.js";
 import type { JsonSchema, Logger } from "./types.js";
 export interface ValidateToolInputOptions {
@@ -31,6 +32,8 @@ export interface CompileValidatorOptions {
 }
 /** Optional in-process properties have the same absence semantics as JSON input. Never mutate the caller. */
 export declare function normalizeToolInput<A>(value: A): A;
+/** One example synthesized from the published schema alone, checked by its validator; never caller values. */
+export declare function schemaExample(schema: JsonSchema): Pick<ArgumentValidationDetails, "example" | "exampleUnavailable">;
 /**
  * Validate call arguments against a tool's JSON Schema.
  *