@zackbart/connecta 0.7.9 → 0.8.1

package/src/skills.ts

@@ -1,12 +1,14 @@
 import type { Connector } from "./types.js";
 
 export const CONNECTA_INSTRUCTIONS =
-  'Connecta exposes many integrations behind meta-tools. When an address is unknown, start with search_tools and includeSchemas="compact"; use describe_tools only when that schema is insufficient. Use call_tool for one explicitly read-only call, batch_call for 2–10 independent explicitly read-only calls, and execute_code (when available) only for dependent read-only steps, loops, joins, or reducing large results. Unannotated, write-capable, and destructive tools must use call_destructive_tool individually. Use authorize_connector only after auth_required and get_result only for truncated results. For the detailed workflow, call skills({ name: "usage" }) once per task.';
+  'Connecta exposes many integrations behind meta-tools. When an address is unknown, start with search_tools and includeSchemas="compact"; use describe_tools only when that schema is insufficient. Use call_tool for one explicitly read-only call, batch_call for 2–10 independent explicitly read-only calls, and execute_code (when available) only for dependent read-only steps, loops, joins, or reducing large results. Unannotated, write-capable, and destructive tools must use call_destructive_tool individually. Use authorize_connector only after auth_required and get_result only for truncated results. Fetch skills({ name: "usage" }) when this routing workflow is unfamiliar.';
 
 export const USAGE_SKILL = `# Connecta usage
 
 ## Choose the smallest execution tool
 
+Use exact addresses returned by discovery; never invent one.
+
 - Unknown address: \`search_tools({ query, includeSchemas: "compact" })\`.
 - Schema still unclear: \`describe_tools({ addresses: [...] })\`.
 - One explicitly read-only call: \`call_tool\`.
@@ -14,45 +16,17 @@ export const USAGE_SKILL = `# Connecta usage
 - Dependent read-only calls, loops, joins, branching, or large-result reduction: \`execute_code\` when available.
 - Any unannotated, write-capable, or destructive call: \`call_destructive_tool\`, individually and only after reviewing its schema and consequences.
 - Truncated result: retry with \`fields\` when possible; otherwise page it with \`get_result\`.
-- \`auth_required\`: use \`authorize_connector\`, have the operator complete consent, then confirm with \`list_connectors\`.
+- \`auth_required\`: use \`authorize_connector\`, give its recovery handoff to the operator, then retry the original call.
 
-Use \`list_connectors({ probe: false })\` for a fast inventory. Use \`probe: true\` only when diagnosing live health or authorization. The fast inventory already reports a connector whose stored credential failed a proactive check as \`auth_required\` (with \`credentialCheck\` and the URL to open), so trust it and authorize up front rather than probing to confirm.
+Use \`list_connectors({ probe: false })\` for a fast inventory based on recent call observations and local credential-shape drift. Use \`probe: true\` only when diagnosing live health or authorization.
 
 ## Code mode
 
-Use code mode when a later call depends on an earlier result, when joining across connectors, or when filtering or aggregating data in the sandbox will substantially shrink the response. Use \`Promise.all\` or \`connecta.batch\` for independent calls inside one execution.
-
-Do not use code mode for one straightforward call, for independent calls already handled by \`batch_call\`, or for any tool not explicitly annotated \`readOnlyHint: true\`. Code mode has a bounded host-call budget and per-call deadline. Return only the reduced value the agent needs; do not return a large upstream payload unchanged.
-
-## Examples
-
-These addresses are illustrative; always use the exact address returned by \`search_tools\`.
+Use code mode when calls depend on earlier results, when joining connectors, or when sandbox filtering or aggregation will substantially shrink the response. Use \`Promise.all\` or \`connecta.batch\` for independent calls inside one execution.
 
-Single call:
-\`\`\`json
-{ "address": "crm.get_account", "args": { "id": "acct_123" }, "resultMode": "value" }
-\`\`\`
+Connector namespace calls and \`connecta.call\` use the same read-only gate and throw on downstream errors. Catch only failures the workflow can handle; let authorization failures return to the agent for recovery.
 
-Independent calls:
-\`\`\`json
-{ "calls": [
-  { "address": "crm.get_account", "args": { "id": "acct_123" } },
-  { "address": "billing.list_invoices", "args": { "status": "open" } }
-] }
-\`\`\`
-
-Dependent code with reduction:
-\`\`\`js
-async () => {
-  const accounts = await crm.search_accounts({ query: "renewal" });
-  const details = await Promise.all(
-    accounts.results.slice(0, 5).map((account) =>
-      crm.get_account({ id: account.id })
-    )
-  );
-  return details.map(({ id, name, status }) => ({ id, name, status }));
-}
-\`\`\`
+Do not use code mode for one call, independent calls already handled by \`batch_call\`, or any tool lacking \`readOnlyHint: true\`. Host calls and time are bounded. Return only the reduced value the agent needs.
 `;
 
 /**
@@ -75,13 +49,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 +71,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 +102,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);
 }
@@ -172,10 +147,7 @@ export interface SkillListing {
 /**
  * Every fetchable skill: the built-in guides plus one entry per connector that
  * carries a usage guide. Derived from the connector list passed in — the single
- * place guide visibility is decided. The `skills` meta-tool passes its
- * connection's `registry.listConnectors()`, so a toolkit-scoped session lists
- * only in-scope guides, and `resolveSkill` below reports an out-of-scope
- * `connector:<id>` exactly as it reports an unknown connector.
+ * place guide visibility is decided.
  */
 export function listSkills(connectors: readonly Connector[]): SkillListing[] {
   const listing: SkillListing[] = AVAILABLE_SKILLS.map((skill) => ({

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/timeout.ts

@@ -1,7 +1,5 @@
-// The deadline vocabulary shared by every non-call downstream probe: the
-// discovery meta-tools' catalog fan-out (src/meta-tools.ts) and the credential
-// liveness checks (src/credential-health.ts). One definition so a "probe" means
-// the same thing, and is bounded the same way, wherever one is issued.
+// The deadline vocabulary shared by downstream discovery probes and tool calls.
+// One definition keeps those waits bounded consistently.
 
 /**
  * Generous default bound for a single downstream probe/catalog call. High enough

package/src/types.ts

@@ -174,7 +174,7 @@ export interface ConnectorContext {
   timeoutMs?: number;
 }
 
-export type ConnectorStatusState = "ok" | "auth_required" | "error";
+type ConnectorStatusState = "ok" | "auth_required" | "error";
 
 export interface ConnectorStatus {
   state: ConnectorStatusState;
@@ -226,19 +226,6 @@ export interface Connector {
     values: ConnectorCredentialValues,
     ctx: ConnectorContext,
   ): Promise<CredentialTestResult>;
-  /**
-   * Optional: whether this connector currently holds a stored downstream
-   * credential — an OAuth grant it persisted, typically. Read only by the
-   * credential liveness checks: a connector with nothing stored has no
-   * credential whose liveness could be in question, and probing it anyway would
-   * start an authorization flow nobody asked for.
-   *
-   * Implement it on connectors that manage their own credential storage (the
-   * shipped `remoteMcp` does, for `auth: { type: "oauth" }`). Connectors whose
-   * credential lives in connecta's vault (`credential` above) need not: the
-   * vault answers for them. Must not perform downstream I/O.
-   */
-  hasStoredCredential?(ctx: ConnectorContext): Promise<boolean>;
   /**
    * Statically-known tool defs, exposed by in-code connectors (`api()`) for
    * startup convention checks. Remote connectors omit this — their tools are
@@ -320,6 +307,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;
 }
 
 /**
@@ -377,50 +371,12 @@ export interface ExecutorLease {
   release(): void;
 }
 
-/**
- * Which toolkits one inbound identity may open — the membership half of the
- * deployment=org / toolkit=team framing (docs/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.
- *
- * An identity with NO binding is unbound and keeps the pre-binding behavior:
- * any declared toolkit, or the full registry. A binding is enforced at connect
- * time, before any scoped registry is constructed.
- */
-export interface ToolkitBinding {
-  /** Toolkit names this identity may select with `?toolkit=<name>`. */
-  readonly toolkits: readonly string[];
-  /**
-   * Whether this identity may also connect with no `?toolkit=` and see the full
-   * registry (and read the deployment-wide operator surfaces). Defaults to
-   * false: binding a credential to a toolkit means binding it.
-   */
-  readonly unscoped?: boolean;
-}
-
 /** Result of an inbound-auth check. */
 export type AuthResult =
   | {
       ok: true;
       userId?: string;
       subjectId?: string;
-      /**
-       * Toolkit binding resolved for THIS identity — the seam for an adapter
-       * that maps its own users (or an IdP claim) to views. Omit to inherit the
-       * provider's `toolkitBinding`.
-       *
-       * When the provider also declares one, the declaration is a **CEILING**,
-       * not a default: connecta intersects the two, and grants `unscoped` only
-       * if both do. A per-identity binding can therefore narrow the credential's
-       * view but never widen it — otherwise an adapter reading a user-writable
-       * claim would let the user name their own toolkits. When the provider
-       * declares nothing, this binding is used as given.
-       *
-       * Validated on arrival (a malformed one refuses the request with 403
-       * rather than being ignored), but never checked against the configured
-       * toolkits, which is only possible for the static declaration at startup.
-       */
-      toolkitBinding?: ToolkitBinding;
     }
   | { ok: false; response: Response };
 
@@ -520,14 +476,6 @@ export interface InboundAuth {
    * provider instead of asking the operator to paste a static bearer secret.
    */
   uiAuth?: UiAuthConfig;
-  /**
-   * Optional toolkit binding for every identity this provider admits
-   * (docs/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`.
-   */
-  toolkitBinding?: ToolkitBinding;
   /** Serve/short-circuit .well-known + OPTIONS. Return null when not handled. */
   handleMetadata?(
     request: Request,