@zackbart/connecta 0.1.0

package/src/skills.ts

@@ -0,0 +1,63 @@
+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.';
+
+export const USAGE_SKILL = `# Connecta usage
+
+## Choose the smallest execution tool
+
+- Unknown address: \`search_tools({ query, includeSchemas: "compact" })\`.
+- Schema still unclear: \`describe_tools({ addresses: [...] })\`.
+- One explicitly read-only call: \`call_tool\`.
+- Two to ten independent explicitly read-only calls: \`batch_call\`.
+- 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\`.
+
+Use \`list_connectors({ probe: false })\` for a fast inventory. 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\`.
+
+Single call:
+\`\`\`json
+{ "address": "crm.get_account", "args": { "id": "acct_123" }, "resultMode": "value" }
+\`\`\`
+
+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 }));
+}
+\`\`\`
+`;
+
+export const AVAILABLE_SKILLS = [
+  {
+    name: "usage",
+    description:
+      "How to choose among Connecta discovery, direct, batch, destructive, and code-mode tools.",
+    content: USAGE_SKILL,
+  },
+] as const;

package/src/storage/file.ts

@@ -0,0 +1,62 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname } from "node:path";
+import type { KVStorage } from "../types.js";
+
+interface Entry {
+  value: string;
+  exp?: number; // epoch ms
+}
+
+/**
+ * JSON-file-backed KVStorage for Node. Loads once, persists on every write via
+ * a temp-file + rename (atomic-ish). Only reachable via the "@zackbart/connecta/node"
+ * subpath so the main entry stays Workers-clean.
+ */
+export function fileStorage(path: string): KVStorage {
+  let data: Record<string, Entry> = {};
+  if (existsSync(path)) {
+    try {
+      data = JSON.parse(readFileSync(path, "utf8")) as Record<string, Entry>;
+    } catch {
+      data = {};
+    }
+  }
+  const persist = () => {
+    const dir = dirname(path);
+    if (dir) mkdirSync(dir, { recursive: true });
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, JSON.stringify(data));
+    renameSync(tmp, path);
+  };
+  const fresh = (key: string): Entry | null => {
+    const e = data[key];
+    if (!e) return null;
+    if (e.exp && Date.now() > e.exp) {
+      delete data[key];
+      return null;
+    }
+    return e;
+  };
+  return {
+    async get(key) {
+      return fresh(key)?.value ?? null;
+    },
+    async set(key, value, opts) {
+      data[key] = {
+        value,
+        exp: opts?.ttlSeconds ? Date.now() + opts.ttlSeconds * 1000 : undefined,
+      };
+      persist();
+    },
+    async delete(key) {
+      delete data[key];
+      persist();
+    },
+  };
+}

package/src/storage/memory.ts

@@ -0,0 +1,34 @@
+import type { KVStorage } from "../types.js";
+
+interface Entry {
+  value: string;
+  exp?: number; // epoch ms
+}
+
+/** In-memory KV store with expiry. The default for dev and Node. */
+export function memoryStorage(): KVStorage {
+  const map = new Map<string, Entry>();
+  const fresh = (key: string): Entry | null => {
+    const e = map.get(key);
+    if (!e) return null;
+    if (e.exp && Date.now() > e.exp) {
+      map.delete(key);
+      return null;
+    }
+    return e;
+  };
+  return {
+    async get(key) {
+      return fresh(key)?.value ?? null;
+    },
+    async set(key, value, opts) {
+      map.set(key, {
+        value,
+        exp: opts?.ttlSeconds ? Date.now() + opts.ttlSeconds * 1000 : undefined,
+      });
+    },
+    async delete(key) {
+      map.delete(key);
+    },
+  };
+}

package/src/types.ts

@@ -0,0 +1,254 @@
+// Core contracts for connecta. Web-API only — no node: imports here.
+
+/** A JSON Schema object describing a tool's input. */
+export type JsonSchema = Record<string, unknown>;
+
+/** Minimal key/value store — the only state connecta needs. */
+export interface KVStorage {
+  get(key: string): Promise<string | null>;
+  set(
+    key: string,
+    value: string,
+    opts?: { ttlSeconds?: number },
+  ): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+
+export interface Logger {
+  debug(...args: unknown[]): void;
+  info(...args: unknown[]): void;
+  warn(...args: unknown[]): void;
+  error(...args: unknown[]): void;
+}
+
+export interface ToolDef {
+  name: string; // unique within the connector
+  description?: string;
+  inputSchema?: JsonSchema;
+  /** Optional JSON Schema describing the tool's structured result. */
+  outputSchema?: JsonSchema;
+  /**
+   * Standard MCP tool behavior hints plus provider-specific extensions.
+   * Connecta fails closed: only readOnlyHint === true (without a contradictory
+   * destructiveHint) may use call_tool, batch_call, or execute_code. Every
+   * other tool must cross the call_destructive_tool approval boundary.
+   */
+  annotations?: ToolAnnotations;
+}
+
+export interface ToolAnnotations extends Record<string, unknown> {
+  title?: string;
+  readOnlyHint?: boolean;
+  destructiveHint?: boolean;
+  idempotentHint?: boolean;
+  openWorldHint?: boolean;
+}
+
+export type ConnectorCredentialValues = Record<string, string>;
+
+/** Read-only access to the credentials assigned to one connector. */
+export interface ConnectorCredentialAccess {
+  /**
+   * Returns one decrypted field. Omitting `field` preserves the original
+   * single-credential behavior and reads the reserved `value` field.
+   */
+  get(field?: string): Promise<string | null>;
+  /** Returns every decrypted field, or null when nothing is configured. */
+  getAll(): Promise<ConnectorCredentialValues | null>;
+}
+
+/** Operator-facing description of one named credential field. */
+export interface ConnectorCredentialFieldConfig {
+  /** Stable field name used by connector code and the credential API. */
+  name: string;
+  /** Short field label, e.g. "Account email". */
+  label: string;
+  /** Plain-language guidance shown in /ui. Never include the credential itself. */
+  description?: string;
+  /** Input placeholder, e.g. "you@example.com". */
+  placeholder?: string;
+  /** Browser input type. Defaults to password. */
+  inputType?: "email" | "password" | "text";
+}
+
+/** Operator-facing description of the credential set a connector needs. */
+export interface ConnectorCredentialConfig {
+  /** Short group or field label, e.g. "API token" or "Service credentials". */
+  label: string;
+  /** Plain-language guidance shown in /ui. Never include the credential itself. */
+  description?: string;
+  /** Password-field placeholder, e.g. "Paste API token". */
+  placeholder?: string;
+  /**
+   * Named fields for multi-value authentication. Omit to retain the original
+   * one-secret credential behavior.
+   */
+  fields?: ConnectorCredentialFieldConfig[];
+}
+
+export interface CredentialTestResult {
+  ok: boolean;
+  message?: string;
+}
+
+export interface ConnectorContext {
+  /** Storage namespaced to this connector. */
+  storage: KVStorage;
+  logger: Logger;
+  /** Public base URL of this deployment (origin), used for OAuth callbacks. */
+  baseUrl: string;
+  /**
+   * Read-only access to this connector's operator-managed credential. Present
+   * only when the connector declares `credential` and the deployment configures
+   * `credentialEncryptionKey`.
+   */
+  credential?: ConnectorCredentialAccess;
+  /**
+   * Identity shared by connector calls that belong to one inbound request.
+   * Connectors may use it to reuse request-safe resources within that request,
+   * but must never retain I/O resources beyond the scope's lifetime.
+   *
+   * Optional for custom/test contexts; the context object itself is the scope
+   * when omitted.
+   */
+  requestScope?: object;
+  /** Best-effort cancellation signal for this individual tool call. */
+  signal?: AbortSignal;
+  /** Requested tool-call deadline in milliseconds. */
+  timeoutMs?: number;
+}
+
+export type ConnectorStatusState = "ok" | "auth_required" | "error";
+
+export interface ConnectorStatus {
+  state: ConnectorStatusState;
+  /** When state === "auth_required", the URL the operator should open. */
+  authorizationUrl?: string;
+  message?: string;
+}
+
+/** The whole plugin contract — the one open seam. */
+export interface Connector {
+  id: string; // address prefix; [a-z0-9_-]+
+  /** Human-readable display name; the stable `id` remains the tool-address prefix. */
+  title?: string;
+  /** How call_tool wraps results. "mcp" passes the content array through; anything else is JSON-wrapped. */
+  kind?: "mcp" | "api";
+  description?: string;
+  /** Optional operator-managed credential slot rendered inside this connector's /ui card. */
+  credential?: ConnectorCredentialConfig;
+  /** Optional server-side check used by /ui's Test action. */
+  testCredential?(
+    value: string,
+    ctx: ConnectorContext,
+  ): Promise<CredentialTestResult>;
+  /** Optional multi-field credential check used by /ui's Test action. */
+  testCredentials?(
+    values: ConnectorCredentialValues,
+    ctx: ConnectorContext,
+  ): Promise<CredentialTestResult>;
+  /**
+   * Statically-known tool defs, exposed by in-code connectors (`api()`) for
+   * startup convention checks. Remote connectors omit this — their tools are
+   * fetched lazily over the network and are not known at construction time.
+   */
+  staticTools?: ToolDef[];
+  listTools(ctx: ConnectorContext): Promise<ToolDef[]>;
+  callTool(
+    name: string,
+    args: unknown,
+    ctx: ConnectorContext,
+  ): Promise<unknown>;
+  /** Optional connector-level health/auth status for list_connectors. */
+  status?(ctx: ConnectorContext): Promise<ConnectorStatus>;
+  /**
+   * Optional: start (or with force, restart from scratch) a downstream OAuth
+   * flow (called by authorize_connector). Present only on connectors that use
+   * downstream OAuth. Returns the resulting status — "auth_required" with an
+   * authorizationUrl when there is a URL to open, "ok" when already authorized.
+   */
+  startAuth?(
+    ctx: ConnectorContext,
+    opts?: { force?: boolean },
+  ): Promise<ConnectorStatus>;
+  /**
+   * Optional: verify the OAuth `state` returned to /oauth/callback/<id> against
+   * the value this connector generated when it started the flow. Present only
+   * on downstream-OAuth connectors. The callback MUST reject before finishAuth
+   * when this returns false — otherwise anyone holding the pending URL could
+   * complete consent with their own account.
+   */
+  verifyState?(state: string | null, ctx: ConnectorContext): Promise<boolean>;
+  /** Optional: complete a downstream OAuth flow (called by /oauth/callback/<id>). */
+  finishAuth?(code: string, ctx: ConnectorContext): Promise<void>;
+}
+
+/** Result of one sandboxed code execution. */
+export interface ExecuteResult {
+  result: unknown;
+  error?: string;
+  logs?: string[];
+}
+
+/** A named group of host functions exposed to sandboxed code as a global. */
+export interface ExecutorProvider {
+  name: string;
+  fns: Record<string, (...args: unknown[]) => Promise<unknown>>;
+}
+
+/**
+ * Runs model-written JavaScript in a sandbox where the ONLY capabilities are
+ * the provider functions — no network, filesystem, env, or timers. Structurally
+ * compatible with `DynamicWorkerExecutor` from `@cloudflare/codemode` (Workers);
+ * `quickJsExecutor()` from "@zackbart/connecta/quickjs" is the Node implementation.
+ * NEVER back this with an unsandboxed eval — the code is untrusted.
+ */
+export interface Executor {
+  execute(code: string, providers: ExecutorProvider[]): Promise<ExecuteResult>;
+}
+
+/** Result of an inbound-auth check. */
+export type AuthResult =
+  | { ok: true; userId?: string; subjectId?: string }
+  | { ok: false; response: Response };
+
+/** Public browser-auth configuration exposed to connecta's status UI. */
+export type UiAuthConfig = {
+  kind: "clerk";
+  publishableKey: string;
+  frontendApiUrl: string;
+  signInUrl?: string;
+  signUpUrl?: string;
+};
+
+/** Optional labels used by Connecta's browser UI and OAuth result pages. */
+export interface ConnectaBranding {
+  /** Product label. Defaults to "Connecta". */
+  productName?: string;
+  /** Organization or owner shown beside the product label. */
+  ownerName?: string;
+  /** Optional link for the organization or owner label. */
+  ownerUrl?: string;
+  /** Status-dashboard introduction. */
+  description?: string;
+}
+
+/** An inbound authentication provider (bearer token, Clerk, ...). */
+export interface InboundAuth {
+  kind: string;
+  /**
+   * Optional browser sign-in configuration. When present, `/ui` uses this
+   * provider instead of asking the operator to paste a static bearer secret.
+   */
+  uiAuth?: UiAuthConfig;
+  /** Serve/short-circuit .well-known + OPTIONS. Return null when not handled. */
+  handleMetadata?(
+    request: Request,
+    baseUrl: string,
+  ): Response | null | Promise<Response | null>;
+  /** Attempt to authorize a request. */
+  authorize(
+    request: Request,
+    baseUrl: string,
+  ): AuthResult | Promise<AuthResult>;
+}