@zackbart/connecta 0.9.1 → 0.10.1

package/src/skills.ts

@@ -1,8 +1,19 @@
-import type { Connector } from "./types.js";
+import type { Connector, ConnectaSurface } from "./types.js";
 
 export const CONNECTA_INSTRUCTIONS =
   'Connecta exposes integrations behind meta-tools. Unknown address: use search_tools with 2–4 distinctive action/object terms, no initial limit, and includeSchemas="compact"; describe_tools only if that shape is ambiguous or exact JSON constraints are needed. Use call_tool for one explicitly read-only call, batch_call for 2–10 independent read-only calls, and execute_code (when available) only for dependencies, loops, joins, or substantial reduction — searching inside that one run rather than searching first. Use call_destructive_tool individually for unannotated, write-capable, or destructive tools. authorize_connector follows auth_required; get_result follows truncation. If this routing is unfamiliar, fetch skills({ name: "usage" }).';
 
+/**
+ * The instructions a code-first deployment loads (#224). It never names
+ * `list_connectors`, `describe_tools`, or `batch_call` — not even to say they
+ * are gone. Always-loaded text describes the surface that exists; a sentence
+ * about three tools this deployment does not have is context paid for the past,
+ * and a model that names one anyway gets an unknown-tool error, which is a
+ * cheaper correction than the tokens the disclaimer costs every request.
+ */
+export const CODE_FIRST_INSTRUCTIONS =
+  'Connecta exposes integrations behind seven meta-tools, and execute_code is the primary one: write an async arrow function and use connecta.search (empty query browses every catalog), connecta.describe, connecta.call, and connecta.batch inside it for discovery, two or more calls, dependent steps, loops, joins, and reducing large results before they reach you. For a single read at an unknown address, search_tools with 2–4 distinctive action/object terms and includeSchemas="compact", then one call_tool — a lone cold call is cheaper direct than through a program. Use call_destructive_tool individually for unannotated, write-capable, or destructive tools; authorize_connector follows auth_required; get_result follows truncation. If this routing is unfamiliar, fetch skills({ name: "usage" }).';
+
 export const USAGE_SKILL = `# Connecta usage
 
 ## Choose the smallest execution tool
@@ -29,6 +40,33 @@ Connector namespace calls and \`connecta.call\` use the same read-only gate and
 Skip code mode for one call, calls suited to \`batch_call\`, or tools lacking \`readOnlyHint: true\`. Return only the needed reduction.
 `;
 
+export const CODE_FIRST_USAGE_SKILL = `# Connecta usage
+
+## The surface
+
+Seven tools: \`execute_code\`, \`search_tools\`, \`call_tool\`, \`call_destructive_tool\`, \`authorize_connector\`, \`get_result\`, \`skills\`. Broad discovery and multi-call work live inside a program rather than in top-level tools.
+
+## Choose the smallest execution tool
+
+Use exact addresses returned by discovery; never invent one. Search with 2–4 distinctive action/object terms rather than the full request.
+
+- One read at an unknown address: \`search_tools({ query, includeSchemas: "compact" })\`, then \`call_tool\` once. A lone cold call is cheaper direct than through a program.
+- Anything wider — two or more calls, dependent steps, loops, joins, branching, browsing a whole catalog, or a result that must be reduced: one \`execute_code\` run.
+- Any unannotated, write-capable, or destructive call: \`call_destructive_tool\`, individually and only after reviewing its schema and consequences. Generated code cannot make one.
+- Truncated result: retry with \`fields\` when possible; otherwise page it with \`get_result\`.
+- \`auth_required\`: use \`authorize_connector\`, give its recovery handoff to the operator, then retry the original call.
+
+## Inside a program
+
+One async arrow function. The only capabilities are one global per connector (\`<connectorId>.<toolName>(args)\`), the four \`connecta\` functions, and \`console.log\`.
+
+- What exists: \`connecta.search({})\` browses every catalog and \`connecta.search({ connector: "<id>" })\` browses one — that inventory is what a program discovers with, and each match carries its \`address\` and annotations.
+- Exact schemas for known addresses: \`connecta.describe({ addresses: [...] })\`; \`format: "json"\` only for exact constraints.
+- Two to ten independent calls: \`connecta.batch([...])\`. Each outcome is \`{ address, ok: true, data }\` or \`{ address, ok: false, error, errorDetails: { code, retryable } }\`, which is also how a program tells a policy refusal from a transient failure.
+- Search inside the run rather than searching first, and return only the reduction the answer needs — never raw payloads.
+- Only tools annotated \`readOnlyHint: true\` are reachable; the read-only gate, credentials, and admission are enforced below the sandbox, so nothing a program does widens what it can reach.
+`;
+
 /**
  * Appended to USAGE_SKILL only when the deployment actually has at least one
  * connector guide. A deployment with none — every deployment that has not
@@ -41,6 +79,20 @@ export const CONNECTOR_GUIDES_SECTION = `
 Some connectors here ship their own usage guide — preferred tools, address quirks, pagination conventions, rate-limit etiquette, query patterns. \`skills({})\` lists each one as \`connector:<connectorId>\`; fetch it with \`skills({ name: "connector:<connectorId>" })\`. \`search_tools\` and \`describe_tools\` set \`guide\` on matches whose connector has one. Read a connector's guide before working with it for the first time in a task.
 `;
 
+/** The same section, naming only surfaces a code-first deployment has. */
+const CODE_FIRST_CONNECTOR_GUIDES_SECTION = `
+## Per-connector guides
+
+Some connectors here ship their own usage guide — preferred tools, address quirks, pagination conventions, rate-limit etiquette, query patterns. \`skills({})\` lists each one as \`connector:<connectorId>\`; fetch it with \`skills({ name: "connector:<connectorId>" })\`. \`search_tools\`, \`connecta.search\`, and \`connecta.describe\` set \`guide\` on matches whose connector has one. Read a connector's guide before working with it for the first time in a task.
+`;
+
+/** The always-loaded MCP `instructions` string for `surface`. */
+export function instructionsFor(surface: ConnectaSurface): string {
+  return surface === "code-first"
+    ? CODE_FIRST_INSTRUCTIONS
+    : CONNECTA_INSTRUCTIONS;
+}
+
 /** True when at least one of `connectors` carries a usage guide. */
 export function hasConnectorGuides(connectors: readonly Connector[]): boolean {
   return connectors.some(
@@ -49,10 +101,19 @@ export function hasConnectorGuides(connectors: readonly Connector[]): boolean {
 }
 
 /** The built-in usage guide, plus the guides section when there is one to point at. */
-function usageSkill(connectors: readonly Connector[]): string {
-  return hasConnectorGuides(connectors)
-    ? USAGE_SKILL + CONNECTOR_GUIDES_SECTION
-    : USAGE_SKILL;
+function usageSkill(
+  connectors: readonly Connector[],
+  surface: ConnectaSurface,
+): string {
+  const base =
+    surface === "code-first" ? CODE_FIRST_USAGE_SKILL : USAGE_SKILL;
+  if (!hasConnectorGuides(connectors)) return base;
+  return (
+    base +
+    (surface === "code-first"
+      ? CODE_FIRST_CONNECTOR_GUIDES_SECTION
+      : CONNECTOR_GUIDES_SECTION)
+  );
 }
 
 const AVAILABLE_SKILLS = [
@@ -60,6 +121,8 @@ const AVAILABLE_SKILLS = [
     name: "usage",
     description:
       "How to choose among Connecta discovery, direct, batch, destructive, and code-mode tools.",
+    codeFirstDescription:
+      "How to route work between one execute_code program and Connecta's explicit call, authorization, and result tools.",
     content: usageSkill,
   },
 ] as const;
@@ -149,10 +212,14 @@ export interface SkillListing {
  * carries a usage guide. Derived from the connector list passed in — the single
  * place guide visibility is decided.
  */
-export function listSkills(connectors: readonly Connector[]): SkillListing[] {
+export function listSkills(
+  connectors: readonly Connector[],
+  surface: ConnectaSurface = "classic",
+): SkillListing[] {
   const listing: SkillListing[] = AVAILABLE_SKILLS.map((skill) => ({
     name: skill.name,
-    description: skill.description,
+    description:
+      surface === "code-first" ? skill.codeFirstDescription : skill.description,
   }));
   for (const connector of connectors) {
     const guide = connectorGuide(connector);
@@ -177,11 +244,14 @@ export type SkillLookup =
 export function resolveSkill(
   name: string,
   connectors: readonly Connector[],
+  surface: ConnectaSurface = "classic",
 ): SkillLookup {
   const builtIn = AVAILABLE_SKILLS.find((skill) => skill.name === name);
-  if (builtIn) return { found: true, content: builtIn.content(connectors) };
+  if (builtIn) {
+    return { found: true, content: builtIn.content(connectors, surface) };
+  }
   const available = () =>
-    listSkills(connectors)
+    listSkills(connectors, surface)
       .map((skill) => skill.name)
       .join(", ");
   if (name.startsWith(CONNECTOR_SKILL_PREFIX)) {

package/src/storage/file.ts

@@ -114,5 +114,10 @@ export function fileStorage(
       delete data[key];
       persist();
     },
+    async list(prefix) {
+      return Object.keys(data)
+        .filter((key) => Boolean(fresh(key)) && key.startsWith(prefix))
+        .sort();
+    },
   };
 }

package/src/storage/memory.ts

@@ -32,5 +32,13 @@ export function memoryStorage(): KVStorage {
     async delete(key) {
       map.delete(key);
     },
+    async list(prefix) {
+      return [...map.keys()]
+        .filter((key) => {
+          fresh(key);
+          return key.startsWith(prefix) && map.has(key);
+        })
+        .sort();
+    },
   };
 }

package/src/types.ts

@@ -12,6 +12,11 @@ export interface KVStorage {
     opts?: { ttlSeconds?: number },
   ): Promise<void>;
   delete(key: string): Promise<void>;
+  /**
+   * Sorted keys beginning with `prefix`. Optional for existing adapters;
+   * subsystems that need independent, enumerable records require it explicitly.
+   */
+  list?(prefix: string): Promise<string[]>;
 }
 
 export interface Logger {
@@ -304,6 +309,21 @@ export interface Connector {
   ): Promise<Response | null>;
 }
 
+/**
+ * Which model-facing surface a deployment advertises. The `executor` decides
+ * it; this type is how a deployment overrides that.
+ *
+ * - `code-first`: seven tools, the default wherever an executor is configured.
+ *   `list_connectors`, `describe_tools`, and `batch_call` are not top-level
+ *   tools; their behavior lives in `connecta.search`, `connecta.describe`, and
+ *   `connecta.batch` inside a program.
+ * - `classic`: the nine base meta-tools, plus `execute_code` when an executor
+ *   is configured. Without an executor it is what a deployment necessarily
+ *   serves and the eval gate's control arm; with one it is the ten-tool shape
+ *   the gate's incremental arm measures, and the only thing `surface` is for.
+ */
+export type ConnectaSurface = "classic" | "code-first";
+
 /** Result of one sandboxed code execution. */
 export interface ExecuteResult {
   result: unknown;

package/src/ui.ts

@@ -14,6 +14,7 @@ import {
 } from "./concurrency.js";
 import {
   type CredentialManagementCapability,
+  type AccessTokenManagementCapability,
   type UiConnector,
   type UiData,
   type UiTool,
@@ -32,6 +33,7 @@ import { CONNECTA_VERSION } from "./version.js";
 
 export {
   filterUiConnectors,
+  type AccessTokenManagementCapability,
   type CredentialManagementCapability,
   type UiConnector,
   type UiData,
@@ -265,17 +267,23 @@ export function droppedUiAuthUrls(uiAuth?: UiAuthConfig): string[] {
   ];
 }
 
-export type OperatorPage = "connections" | "credentials" | "activity";
+export type OperatorPage =
+  | "connections"
+  | "credentials"
+  | "tokens"
+  | "activity";
 
 const OPERATOR_PAGE_LABELS: Readonly<Record<OperatorPage, string>> = {
   connections: "Connections",
   credentials: "Credentials",
+  tokens: "Access tokens",
   activity: "Activity",
 };
 
 export function operatorPageForPath(path: string): OperatorPage | undefined {
   if (path === "/") return "connections";
   if (path === "/credentials") return "credentials";
+  if (path === "/tokens") return "tokens";
   if (path === "/activity") return "activity";
   return undefined;
 }
@@ -315,6 +323,7 @@ export async function buildUiData(
   defer?: DeferredWork,
   oauthManagement = false,
   discoveryConcurrency?: number,
+  accessTokenManagement: AccessTokenManagementCapability = "not_configured",
 ): Promise<UiData> {
   const requestScope = {};
   const connectorSet = registry.listConnectors();
@@ -474,6 +483,7 @@ export async function buildUiData(
     connectors,
     activityEnabled,
     credentialManagement,
+    accessTokenManagement,
     oauthManagement,
   };
 }
@@ -583,6 +593,8 @@ ${clerkScript}
           data-operator-page="connections"${page === "connections" ? ' aria-current="page"' : ""}>Connections</a>
         <a id="credentialsNav" class="navlink hidden" href="/credentials"
           data-operator-page="credentials"${page === "credentials" ? ' aria-current="page"' : ""}>Credentials</a>
+        <a id="tokensNav" class="navlink hidden" href="/tokens"
+          data-operator-page="tokens"${page === "tokens" ? ' aria-current="page"' : ""}>Access tokens</a>
         <a id="activityNav" class="navlink hidden" href="/activity"
           data-operator-page="activity"${page === "activity" ? ' aria-current="page"' : ""}>Activity</a>
       </nav>
@@ -656,6 +668,43 @@ ${clerkScript}
     </div>
   </section>
 
+  <section id="tokensView"${page === "tokens" ? "" : ' class="hidden"'}>
+    <div class="lead pgrid">
+      <h1 id="tokensHeading" class="pcap" tabindex="-1">Access tokens</h1>
+      <div class="pbody">
+        <p class="activity-copy">Create named Bearer tokens for MCP clients. Each secret is shown once; revoke it when that client should lose access.</p>
+        <p id="tokenNotice" class="meta" role="status" aria-live="polite"
+          tabindex="-1"></p>
+        <div id="tokenUnavailable" class="unavailable hidden"></div>
+        <div id="tokenAvailable" class="hidden">
+          <form id="tokenCreateForm" class="token-create">
+            <label for="tokenName">Client name</label>
+            <div class="row">
+              <input id="tokenName" type="text" maxlength="80"
+                placeholder="Claude desktop, ChatGPT production…"
+                autocomplete="off">
+              <button id="createToken" class="linklike" type="submit">Create token</button>
+            </div>
+          </form>
+          <section id="tokenReveal" class="token-reveal hidden"
+            aria-labelledby="tokenRevealHeading">
+            <div class="token-reveal-head">
+              <h2 id="tokenRevealHeading" tabindex="-1">Copy this token now</h2>
+              <span class="cap">Shown once</span>
+            </div>
+            <p class="meta">Store it in the MCP client before leaving this page. It cannot be displayed again.</p>
+            <div class="endpoint-row token-secret">
+              <code id="createdToken" class="mono"></code>
+              <button id="copyCreatedToken" class="linklike" type="button">Copy token</button>
+            </div>
+            <button id="dismissCreatedToken" class="linklike" type="button">I stored it</button>
+          </section>
+          <div id="tokenList" class="token-ledger" aria-busy="false"></div>
+        </div>
+      </div>
+    </div>
+  </section>
+
   <section id="activityView"${page === "activity" ? "" : ' class="hidden"'}>
     <div class="lead pgrid">
       <h1 id="activityHeading" class="pcap" tabindex="-1">Activity</h1>

package/src/version.ts

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.9.1";
+export const CONNECTA_VERSION = "0.10.1";