@zackbart/connecta 0.7.8 → 0.8.0

package/src/skills.ts

@@ -75,13 +75,13 @@ export function hasConnectorGuides(connectors: readonly Connector[]): boolean {
 }
 
 /** The built-in usage guide, plus the guides section when there is one to point at. */
-export function usageSkill(connectors: readonly Connector[]): string {
+function usageSkill(connectors: readonly Connector[]): string {
   return hasConnectorGuides(connectors)
     ? USAGE_SKILL + CONNECTOR_GUIDES_SECTION
     : USAGE_SKILL;
 }
 
-export const AVAILABLE_SKILLS = [
+const AVAILABLE_SKILLS = [
   {
     name: "usage",
     description:
@@ -97,7 +97,7 @@ export const AVAILABLE_SKILLS = [
  * The prefixed form is the ONLY way to reach a connector guide: a bare
  * connector id is never resolved, so nothing shadows anything silently.
  */
-export const CONNECTOR_SKILL_PREFIX = "connector:";
+const CONNECTOR_SKILL_PREFIX = "connector:";
 
 /** The skill name that fetches `connector`'s guide. */
 export function connectorSkillName(connectorId: string): string {
@@ -128,8 +128,9 @@ const NOT_SUMMARY_RE = /^\s*(?:<!--|\|)|^\s*(?:-{3,}|\*{3,}|_{3,})\s*$/;
 /** Drop a leading YAML frontmatter block — metadata, not summary text. */
 function withoutFrontmatter(lines: string[]): string[] {
   let start = 0;
-  while (start < lines.length && lines[start].trim() === "") start++;
-  if (start >= lines.length || !RULE_RE.test(lines[start])) return lines;
+  while (start < lines.length && (lines[start] ?? "").trim() === "") start++;
+  const openingRule = lines[start];
+  if (openingRule === undefined || !RULE_RE.test(openingRule)) return lines;
   const close = lines.findIndex((line, i) => i > start && RULE_RE.test(line));
   return close === -1 ? lines : lines.slice(close + 1);
 }

package/src/storage/file.ts

@@ -104,7 +104,9 @@ export function fileStorage(
     async set(key, value, opts) {
       data[key] = {
         value,
-        exp: opts?.ttlSeconds ? Date.now() + opts.ttlSeconds * 1000 : undefined,
+        ...(opts?.ttlSeconds
+          ? { exp: Date.now() + opts.ttlSeconds * 1000 }
+          : {}),
       };
       persist();
     },

package/src/storage/memory.ts

@@ -24,7 +24,9 @@ export function memoryStorage(): KVStorage {
     async set(key, value, opts) {
       map.set(key, {
         value,
-        exp: opts?.ttlSeconds ? Date.now() + opts.ttlSeconds * 1000 : undefined,
+        ...(opts?.ttlSeconds
+          ? { exp: Date.now() + opts.ttlSeconds * 1000 }
+          : {}),
       });
     },
     async delete(key) {

package/src/toolkits.ts

@@ -137,7 +137,7 @@ function toolFilter(
  * an allowlist is a scope the operator did not write, and a scope nobody wrote
  * is not one an operator can reason about. (A definition scopes visibility only;
  * WHICH identity may select it is the separate binding below — see the module
- * header and docs/toolkits.md.) Tool names are checked only for connectors that expose
+ * header and documentation/toolkits.md.) Tool names are checked only for connectors that expose
  * `staticTools` (i.e. `api()`); a remote connector's catalog is fetched lazily
  * over the network and is unknown at construction time.
  */
@@ -331,7 +331,7 @@ export function resolveToolkitBinding(
  * Returns a frozen, deduplicated copy: nothing downstream can be mutated by the
  * adapter after the check, and every name is known to fit the grammar.
  */
-export function normalizeToolkitBinding(value: unknown): ToolkitBinding | null {
+function normalizeToolkitBinding(value: unknown): ToolkitBinding | null {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     return null;
   }

package/src/types.ts

@@ -44,6 +44,61 @@ export interface ToolAnnotations extends Record<string, unknown> {
   openWorldHint?: boolean;
 }
 
+/** Inputs a connector may reduce to a non-secret admission partition key. */
+export interface ConnectorCallAdmissionInput {
+  toolName: string;
+  args: unknown;
+}
+
+/** Exact sliding-window budget for one connector-call partition. */
+export interface ConnectorRollingWindowBudget {
+  kind: "rolling-window";
+  /** Calls admitted during `windowMs` before another is proactively refused. */
+  maxCalls: number;
+  /** Width of the rolling window in milliseconds. */
+  windowMs: number;
+}
+
+/**
+ * One connector-level downstream call-admission rule.
+ *
+ * This release accepts the plural `rules` container below but enforces exactly
+ * one rule. That keeps the public shape ready for providers whose concurrency
+ * and budget limits eventually need different partition dimensions without
+ * pretending multi-rule admission is already atomic.
+ */
+export interface ConnectorCallAdmissionRule {
+  /** Maximum simultaneous Connector.callTool attempts in one partition. */
+  maxConcurrency?: number;
+  /** Callers allowed to wait behind the concurrency bound. Default 32. */
+  maxQueueSize?: number;
+  /** Maximum concurrency-queue wait in milliseconds. Default 5,000. */
+  queueTimeoutMs?: number;
+  /** Retry hint for concurrency overloads. Default 1,000. */
+  retryAfterMs?: number;
+  /** Optional exact rolling-window call-start budget. */
+  budget?: ConnectorRollingWindowBudget;
+  /**
+   * Derive a bounded, non-secret partition key from the tool call. Omit for
+   * one connector-wide partition. Connecta retains the returned key only; it
+   * never copies arguments into limiter state.
+   */
+  partitionKey?(
+    input: Readonly<ConnectorCallAdmissionInput>,
+  ): string;
+}
+
+/** Optional downstream call-admission policy declared by one connector. */
+export interface ConnectorCallAdmissionPolicy {
+  /**
+   * Plural-ready policy container. Exactly one rule is supported in this
+   * release; empty or multi-rule policies fail construction.
+   */
+  rules: readonly ConnectorCallAdmissionRule[];
+  /** Maximum simultaneously retained partition states. Default 1,024. */
+  maxPartitions?: number;
+}
+
 export type ConnectorCredentialValues = Record<string, string>;
 
 /** Read-only access to the credentials assigned to one connector. */
@@ -145,6 +200,12 @@ export interface Connector {
    * the connector inherits the deployment-wide cap.
    */
   maxResultBytes?: number;
+  /**
+   * Optional per-runtime admission policy for downstream tool calls. It covers
+   * call_tool, every batch_call child, and execute_code host calls, but not
+   * catalog/status/auth operations.
+   */
+  callAdmission?: ConnectorCallAdmissionPolicy;
   /**
    * Optional agent-facing usage guide (markdown) for this connector — preferred
    * tools, address quirks, pagination conventions, rate-limit etiquette, good
@@ -259,6 +320,13 @@ export interface ExecuteResult {
 export interface ExecutorProvider {
   name: string;
   fns: Record<string, (...args: unknown[]) => Promise<unknown>>;
+  /**
+   * Optional trusted sandbox-side setup run after provider globals exist.
+   * Connecta uses this to install lazy connector namespace proxies without
+   * materializing one host closure per tool. This is host-authored code, never
+   * model input.
+   */
+  prelude?: string;
 }
 
 /**
@@ -318,7 +386,7 @@ export interface ExecutorLease {
 
 /**
  * Which toolkits one inbound identity may open — the membership half of the
- * deployment=org / toolkit=team framing (docs/toolkits.md). A mapping, never a
+ * deployment=org / toolkit=team framing (documentation/toolkits.md). A mapping, never a
  * policy engine: one identity → the toolkit names it may select, plus whether
  * it may connect with no `?toolkit=` at all.
  *
@@ -461,7 +529,7 @@ export interface InboundAuth {
   uiAuth?: UiAuthConfig;
   /**
    * Optional toolkit binding for every identity this provider admits
-   * (docs/toolkits.md). Declared statically so `createConnecta` can validate the
+   * (documentation/toolkits.md). Declared statically so `createConnecta` can validate the
    * names against `ConnectaConfig.toolkits` and throw on a typo — a binding
    * nobody wrote is not one an operator can reason about. An `authorize` result
    * may narrow it per identity with its own `toolkitBinding`.