@zackbart/connecta 0.15.1 → 0.16.0

package/src/concurrency.ts

@@ -1,39 +0,0 @@
-const DEFAULT_DISCOVERY_CONCURRENCY = 4;
-
-export function resolveDiscoveryConcurrency(
-  value: number | undefined,
-): number {
-  return value !== undefined && Number.isInteger(value) && value > 0
-    ? value
-    : DEFAULT_DISCOVERY_CONCURRENCY;
-}
-
-/** Run `fn` over `items` with at most `limit` operations in flight. */
-export async function mapSettledWithConcurrency<T, R>(
-  items: readonly T[],
-  limit: number,
-  fn: (item: T, index: number) => Promise<R>,
-): Promise<PromiseSettledResult<R>[]> {
-  const settled = Array<PromiseSettledResult<R>>(items.length);
-  const remaining = items.entries();
-  const workers = Array.from(
-    { length: Math.min(limit, items.length) },
-    async () => {
-      for (;;) {
-        const next = remaining.next();
-        if (next.done) return;
-        const [index, item] = next.value;
-        try {
-          settled[index] = {
-            status: "fulfilled",
-            value: await fn(item, index),
-          };
-        } catch (reason) {
-          settled[index] = { status: "rejected", reason };
-        }
-      }
-    },
-  );
-  await Promise.all(workers);
-  return settled;
-}

package/src/connector-scope.ts

@@ -1,66 +0,0 @@
-import type { Connector, ConnectorContext } from "./types.js";
-
-/** Enough for local transport abort/close without letting cleanup own latency. */
-const CONNECTOR_SCOPE_CLOSE_BUDGET_MS = 100;
-
-/**
- * Bound on cleanup continued after the caller-facing window expires.
- *
- * `remoteMcp` spends at most one second asking the downstream to terminate its
- * session, leaving another second for the local close. Custom hooks still get a
- * finite background window: handing a never-settling promise to a Worker's
- * `waitUntil` would otherwise keep the invocation alive until the platform cap.
- */
-const CONNECTOR_SCOPE_DEFER_BUDGET_MS = 2_000;
-
-/** Runtime hook for work that may safely continue after a response is ready. */
-export type DeferredWork = (promise: Promise<unknown>) => void;
-
-/** Resolve when `work` settles or `budgetMs` expires; never reject. */
-function waitAtMost(work: Promise<void>, budgetMs: number): Promise<void> {
-  return new Promise((resolve) => {
-    const timer = setTimeout(resolve, budgetMs);
-    work.then(() => {
-      clearTimeout(timer);
-      resolve();
-    });
-  });
-}
-
-/**
- * Tell a connector that a scope owned by the core has ended.
- *
- * Scope teardown is deliberately best-effort: a missing hook is a no-op and a
- * rejected hook is swallowed so cleanup can never replace the probe result that
- * caused it. The hook gets a small, fixed completion window so edge runtimes do
- * not cut off a real close as the response ends. When the runtime supplies
- * `defer`, the bounded tail is handed to it without extending the caller-facing
- * window. Callers own the at-most-once guarantee and must not use the scope
- * again after this returns.
- */
-export async function closeConnectorScope(
-  connector: Connector,
-  ctx: ConnectorContext,
-  defer?: DeferredWork,
-): Promise<void> {
-  try {
-    const closing = connector.closeScope?.(ctx);
-    if (!closing) return;
-    // Attach both handlers before either timer can win, so a late rejection is
-    // consumed rather than becoming an unhandled rejection.
-    const settled = closing.then(
-      () => {},
-      () => {},
-    );
-    if (defer) {
-      try {
-        defer(waitAtMost(settled, CONNECTOR_SCOPE_DEFER_BUDGET_MS));
-      } catch {
-        // A runtime hook is best-effort too; the caller cap still applies.
-      }
-    }
-    await waitAtMost(settled, CONNECTOR_SCOPE_CLOSE_BUDGET_MS);
-  } catch {
-    // The scope is over whether or not the connector managed to clean it up.
-  }
-}

package/src/connectors/api.ts

@@ -1,159 +0,0 @@
-import { precompileValidator, validateToolInput } from "../validate.js";
-import type {
-  Connector,
-  ConnectorCallAdmissionPolicy,
-  ConnectorCredentialConfig,
-  ConnectorCredentialValues,
-  ConnectorContext,
-  ConnectorUsageGuide,
-  CredentialTestResult,
-  JsonSchema,
-  ToolAnnotations,
-  ToolDef,
-} from "../types.js";
-
-export interface ApiTool {
-  name: string;
-  description?: string;
-  /** A plain JSON Schema object describing the tool input. */
-  inputSchema?: JsonSchema;
-  /** A plain JSON Schema object describing the tool's structured output. */
-  outputSchema?: JsonSchema;
-  /**
-   * Standard MCP-style behavior hints. Only an explicit readOnlyHint: true
-   * admits the tool to call_tool and execute_code.
-   */
-  annotations?: ToolAnnotations;
-  handler: (args: any, ctx: ConnectorContext) => Promise<unknown> | unknown;
-}
-
-export interface ApiOptions {
-  /** Human-readable display name; the connector id remains the address prefix. */
-  title?: string;
-  description?: string;
-  /**
-   * Max inline result size (bytes) for this connector's tools before
-   * call_tool truncates and stashes the full text for get_result
-   * paging. Overrides the deployment's `calls.maxResultBytes`; omit to inherit
-   * it. Must be a whole number of bytes >= 1; anything else warns at startup
-   * and is ignored.
-   */
-  maxResultBytes?: number;
-  /** Optional per-runtime downstream call-admission policy. */
-  callAdmission?: ConnectorCallAdmissionPolicy;
-  /**
-   * Optional agent-facing usage guide served by `skills` as
-   * `connector:<id>`. A string is markdown; the structured form adds bounded
-   * discovery metadata. See `Connector.usageGuide`.
-   */
-  usageGuide?: string | ConnectorUsageGuide;
-  /** Optional operator-managed credential exposed through ctx.credential and /credentials. */
-  credential?: ConnectorCredentialConfig;
-  /** Optional validation behind /credentials' Test action. */
-  testCredential?: (
-    value: string,
-    ctx: ConnectorContext,
-  ) => Promise<CredentialTestResult>;
-  /** Optional validation for named multi-field credentials. */
-  testCredentials?: (
-    values: ConnectorCredentialValues,
-    ctx: ConnectorContext,
-  ) => Promise<CredentialTestResult>;
-  /**
-   * Validate call arguments against each tool's `inputSchema` before invoking
-   * the handler (default true). Mismatches fail with a non-retryable
-   * `invalid_args` ConnectorCallError instead of reaching the handler. Set
-   * false to restore the pre-validation pass-through for deployments relying
-   * on loose coercion.
-   */
-  validateArgs?: boolean;
-  /**
-   * Fail-closed on a tool whose `inputSchema` the validator cannot evaluate
-   * (default false). The default surfaces such a schema as a one-time warning
-   * and then passes the raw arguments through, so a broken schema never breaks
-   * an otherwise working tool. Set true to instead reject those calls with a
-   * non-retryable `invalid_args` ConnectorCallError, so a schema that cannot be
-   * enforced never silently admits unvalidated input. Only consulted when
-   * `validateArgs` is not false.
-   */
-  strictValidation?: boolean;
-  tools: ApiTool[];
-}
-
-/**
- * A connector defined entirely in code: static tool defs + fetch handlers.
- * Tool inputs are plain JSON Schema objects (bring your own zod-to-json-schema
- * conversion if you prefer zod). call_tool JSON-wraps the handler's return.
- *
- * Arguments are validated against `inputSchema` before the handler runs
- * (disable with `validateArgs: false`). Remote MCP inputs are also validated,
- * but in the shared invocation path against the request-local downstream
- * catalog. These API-only controls stay here because hand-written handlers may
- * deliberately accept loose coercion or choose fail-closed schema handling.
- */
-export function api(id: string, opts: ApiOptions): Connector {
-  const defs: ToolDef[] = opts.tools.map((t) => ({
-    name: t.name,
-    ...(t.description !== undefined ? { description: t.description } : {}),
-    ...(t.inputSchema !== undefined ? { inputSchema: t.inputSchema } : {}),
-    ...(t.outputSchema !== undefined ? { outputSchema: t.outputSchema } : {}),
-    ...(t.annotations !== undefined ? { annotations: t.annotations } : {}),
-  }));
-  const byName = new Map(opts.tools.map((t) => [t.name, t]));
-  const validateArgs = opts.validateArgs ?? true;
-  const strictValidation = opts.strictValidation ?? false;
-  if (validateArgs) {
-    // Compile each schema now so a validator-hostile inputSchema surfaces once
-    // here rather than silently on its first call. Warning-only; never throws.
-    for (const t of opts.tools) {
-      if (t.inputSchema)
-        precompileValidator(t.inputSchema, { address: `${id}.${t.name}` });
-    }
-  }
-  return {
-    id,
-    ...(opts.title !== undefined ? { title: opts.title } : {}),
-    kind: "api",
-    ...(opts.description !== undefined
-      ? { description: opts.description }
-      : {}),
-    ...(opts.maxResultBytes !== undefined
-      ? { maxResultBytes: opts.maxResultBytes }
-      : {}),
-    ...(opts.callAdmission !== undefined
-      ? { callAdmission: opts.callAdmission }
-      : {}),
-    ...(opts.usageGuide !== undefined ? { usageGuide: opts.usageGuide } : {}),
-    ...(opts.credential !== undefined ? { credential: opts.credential } : {}),
-    ...(opts.testCredential !== undefined
-      ? { testCredential: opts.testCredential }
-      : {}),
-    ...(opts.testCredentials !== undefined
-      ? { testCredentials: opts.testCredentials }
-      : {}),
-    staticTools: defs,
-    async listTools() {
-      return defs;
-    },
-    async callTool(name, args, ctx) {
-      const tool = byName.get(name);
-      if (!tool) {
-        throw new Error(`Unknown tool "${name}" on connector "${id}"`);
-      }
-      const input = args ?? {};
-      if (validateArgs && tool.inputSchema) {
-        const invalid = validateToolInput(tool.inputSchema, input, {
-          address: `${id}.${name}`,
-          logger: ctx.logger,
-          failClosed: strictValidation,
-        });
-        if (invalid) throw invalid;
-      }
-      // `await` (not a bare promise return) so a handler that throws before
-      // its first await never sits handler-less for the thenable-adoption
-      // microtask — workerd and vitest both report that gap as an unhandled
-      // rejection even though the caller catches the failure.
-      return await tool.handler(input, ctx);
-    },
-  };
-}