@zackbart/connecta 0.34.0 → 0.35.0

package/examples/worker/alchemy.run.ts

@@ -0,0 +1,116 @@
+/**
+ * The Alchemy stack that deploys this Worker: the script, its D1 database,
+ * Worker Loader, vars and secrets, the Worker-level Cloudflare Access
+ * application with Managed OAuth, and the `/agent/*` bypass application.
+ * README.md § "Deploy" walks through it; wrangler.jsonc serves only
+ * `wrangler dev`.
+ *
+ * Deploy, update, and plan with an explicit stage, from this folder:
+ *   npx alchemy deploy --stage production
+ * Alchemy reads CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, and the two
+ * secrets below from the environment or `.env`. Never commit `.env` or
+ * `.alchemy/`: local state records secret values in plaintext.
+ */
+import * as Alchemy from "alchemy";
+import * as Cloudflare from "alchemy/Cloudflare";
+import * as Output from "alchemy/Output";
+import * as Config from "effect/Config";
+import * as Effect from "effect/Effect";
+
+// Who may sign in. Replace with the deployment's own Access rule.
+const signIn = { emailDomain: "example.com" };
+
+export default Alchemy.Stack(
+  "Connecta",
+  { providers: Cloudflare.providers(), state: Alchemy.localState() },
+  Effect.gen(function* () {
+    // The one database. Retained on destroy: `alchemy destroy` forgets it
+    // instead of deleting every grant, credential, and token in it, and the
+    // next deploy adopts it again by name. connecta creates its tables.
+    const database = yield* Cloudflare.D1.Database("ConnectaDB", { name: "connecta" }).pipe(
+      Alchemy.RemovalPolicy.retain(),
+    );
+
+    // Optional R2 bucket, for an api() connector handler that stores files.
+    // connecta itself never uses one. Bind it as FILES in env below.
+    // const files = yield* Cloudflare.R2.Bucket("Files", { name: "connecta-files" }).pipe(
+    //   Alchemy.RemovalPolicy.retain(),
+    // );
+
+    // Attached to the Worker itself, so Access supplies ctx.access. Managed
+    // OAuth's allowlist must keep all three redirect URIs (AGENTS.md).
+    const access = yield* Cloudflare.Access.Application("ConnectaAccess", {
+      type: "self_hosted",
+      name: "connecta",
+      policies: [
+        { decision: "allow", include: [signIn] },
+        // Admits a service token at the edge for `connecta doctor`'s /health
+        // read; connecta refuses service identities on MCP and operator routes.
+        // { decision: "non_identity", include: [{ serviceToken: "<service token id>" }] },
+      ],
+      oauthConfiguration: {
+        enabled: true,
+        dynamicClientRegistration: {
+          enabled: true,
+          allowedUris: [
+            "https://claude.ai/api/mcp/auth_callback",
+            "https://chatgpt.com/connector_platform_oauth_redirect",
+            "https://chatgpt.com/connector/oauth/*",
+          ],
+        },
+      },
+    });
+
+    const worker = yield* Cloudflare.Worker("Connecta", {
+      name: "connecta",
+      main: "./src/index.ts",
+      // Keep enable_request_signal: a client disconnect aborts its request.
+      // Keep enable_weak_ref: it releases an authentication charge whose
+      // cancelled work can never settle.
+      compatibility: {
+        date: "2025-01-01",
+        flags: [
+          "nodejs_compat",
+          "enable_request_signal",
+          "enable_weak_ref",
+          "unhandled_rejection_after_microtask_checkpoint",
+        ],
+      },
+      access,
+      env: {
+        CONNECTA_DB: database,
+        // Required by execute_code; Dynamic Workers use the Workers Paid plan.
+        LOADER: Cloudflare.WorkerLoader(),
+        // FILES: files,
+        // The Worker's own URL: its custom domain if any, else workers.dev.
+        PUBLIC_URL: Cloudflare.Worker.URL,
+        // Comma-separated Access user ids (user_uuid, else email).
+        CONNECTA_MAINTAINERS: "operator@example.com",
+        // CONNECTA_ACTIVITY: "on",
+        // Declare every secret here. Each deploy replaces the Worker's whole
+        // binding set, deleting secrets set any other way.
+        DOWNSTREAM_TOKEN: Config.Redacted("DOWNSTREAM_TOKEN"),
+        CREDENTIAL_ENCRYPTION_KEY: Config.Redacted("CREDENTIAL_ENCRYPTION_KEY"),
+      },
+    });
+
+    // Lets agents reach /agent/<pool> with only their cta_ token. It bypasses
+    // Access on the Worker's primary URL host and never on any other path.
+    const agents = yield* Cloudflare.Access.Application("ConnectaAgents", {
+      type: "self_hosted",
+      name: "connecta agents",
+      destinations: Output.map(worker.url, (url) => [
+        { type: "public" as const, uri: `${new URL(url!).host}/agent/*` },
+      ]),
+      policies: [{ decision: "bypass", include: ["everyone"] }],
+    });
+
+    return {
+      url: worker.url,
+      workerId: worker.workerId,
+      databaseId: database.databaseId,
+      accessApplicationId: access.applicationId,
+      agentsApplicationId: agents.applicationId,
+    };
+  }),
+);

package/examples/worker/gitignore

@@ -0,0 +1,10 @@
+# Rename this file to .gitignore in a copied deployment, before the first
+# `git add`: npm strips .gitignore files from published packages.
+# Alchemy local state records deployed secret values in plaintext.
+.alchemy/
+.env
+.env.*
+.dev.vars
+.dev.vars.*
+.wrangler/
+node_modules/

package/examples/worker/src/connecta.config.ts

@@ -18,29 +18,31 @@
  * Setup (this example has no package.json of its own — it self-references the
  * installed `@zackbart/connecta` package):
  *   1. `pnpm install` in the connecta repository root (../../ from here) so the
- *      package import and wrangler resolve. A copy in its own repository
- *      installs `@zackbart/connecta @cloudflare/codemode` instead. Codemode is
- *      an optional peer.
- *   2. `wrangler d1 create connecta` and put its id in wrangler.jsonc under
- *      `d1_databases`. connecta creates its tables on first use.
- *   3. Set secrets:
- *        wrangler secret put DOWNSTREAM_TOKEN
- *        wrangler secret put CREDENTIAL_ENCRYPTION_KEY
- *      and PUBLIC_URL as a plain var in wrangler.jsonc.
- *   4. Attach Cloudflare Access to this Worker. Enable Managed OAuth and
+ *      package import and alchemy resolve. A copy in its own repository
+ *      installs `@zackbart/connecta @cloudflare/codemode` plus the exact
+ *      alchemy and effect pins instead (README.md § "Copied into its own
+ *      repository"). Codemode is an optional peer.
+ *   2. alchemy.run.ts declares the deployment: this Worker, its one D1
+ *      database (connecta creates its tables on first use), the Worker Loader,
+ *      the vars, and the DOWNSTREAM_TOKEN and CREDENTIAL_ENCRYPTION_KEY
+ *      secrets, read from the environment or .env at deploy time. Declare
+ *      every secret there: each deploy removes bindings set any other way.
+ *   3. It attaches Cloudflare Access to this Worker with Managed OAuth and
  *      Dynamic Client Registration. Its Allowed redirect URIs must include
  *      Claude's https://claude.ai/api/mcp/auth_callback plus ChatGPT's
  *      https://chatgpt.com/connector_platform_oauth_redirect and
  *      https://chatgpt.com/connector/oauth/* forms (see ../AGENTS.md).
- *      Then add one self-hosted Access application per hostname for
- *      `<host>/agent/*` with a single Bypass policy (Everyone), so agents send
- *      only their cta_ token (README.md § "Let agents through Access").
- *   5. Use the Workers Paid plan required by the `worker_loaders` binding.
- *   6. List the maintainers' Access user ids (the identity's user_uuid, else
- *      its email) in the CONNECTA_MAINTAINERS var, comma-separated.
- *   7. `wrangler deploy` from this folder (examples/worker), where wrangler.jsonc
- *      lives. Point a maintainer's MCP client at `<PUBLIC_URL>/mcp`, and an
- *      agent's at `<PUBLIC_URL>/agent/ci`.
+ *      A second self-hosted application bypasses Access for
+ *      `<host>/agent/*` only, so agents send only their cta_ token
+ *      (README.md § "Let agents through Access").
+ *   4. Use the Workers Paid plan required by the Worker Loader binding.
+ *   5. List the maintainers' Access user ids (the identity's user_uuid, else
+ *      its email) in the CONNECTA_MAINTAINERS var, comma-separated, and set
+ *      the stack's Access sign-in rule.
+ *   6. `npx alchemy deploy --stage production` from this folder
+ *      (examples/worker). Never commit .env or .alchemy/. Point a
+ *      maintainer's MCP client at `<PUBLIC_URL>/mcp`, and an agent's at
+ *      `<PUBLIC_URL>/agent/ci`. wrangler.jsonc serves only `wrangler dev`.
  */
 import { api, defineConfig, remoteMcp } from "@zackbart/connecta";
 import { activityHistory } from "@zackbart/connecta/activity";
@@ -67,7 +69,7 @@ export interface Env {
   /** "on" switches on activity history, in CONNECTA_DB. */
   CONNECTA_ACTIVITY?: string;
   /**
-   * Worker Loader binding (wrangler.jsonc `worker_loaders`) powering
+   * Worker Loader binding (alchemy.run.ts `LOADER`) powering
    * execute_code. Dynamic Workers require the Workers Paid plan.
    */
   LOADER: WorkerLoader;
@@ -138,7 +140,7 @@ export default defineConfig((env: Env) => {
           // with a static key: the operator manages it inside its connection
           // in the operator UI, so no Worker secret holds it.
           //   type: "credential",
-          //   credential: { label: "Notion internal integration token" },
+          //   credential: { label: "Downstream token accepted by the hosted server" },
         },
         // Use `authScope: "personal"` with OAuth or credential auth when each
         // Access user connects their own downstream account. Literal headers

package/examples/worker/wrangler.jsonc

@@ -1,13 +1,22 @@
+// Local development only: `wrangler dev` runs this Worker with local D1 and a
+// simulated Access identity. Deploy with alchemy.run.ts, never with this file,
+// and keep its vars, flags, and bindings in step with that stack.
 {
   "$schema": "node_modules/wrangler/config-schema.json",
   "name": "connecta-example",
   "main": "src/index.ts",
   "compatibility_date": "2025-01-01",
-  "compatibility_flags": ["nodejs_compat", "enable_request_signal"],
+  "compatibility_flags": [
+    "nodejs_compat",
+    "enable_request_signal",
+    "enable_weak_ref",
+    "unhandled_rejection_after_microtask_checkpoint",
+  ],
   "observability": { "enabled": true },
 
-  // Plain vars. Secrets (CREDENTIAL_ENCRYPTION_KEY, DOWNSTREAM_TOKEN) are set with
-  // `wrangler secret put <NAME>`, not here.
+  // Plain vars. Local secrets (CREDENTIAL_ENCRYPTION_KEY, DOWNSTREAM_TOKEN) go
+  // in an uncommitted .dev.vars file; deployed ones are declared in
+  // alchemy.run.ts.
   // CONNECTA_ACTIVITY switches on activity history in src/connecta.config.ts
   // when "on"; its data stays in CONNECTA_DB.
   "vars": {
@@ -28,8 +37,8 @@
     },
   },
 
-  // The one database. Create with `wrangler d1 create connecta` and paste
-  // the id. connecta creates its tables on first use; nothing to apply.
+  // The one database, local under `wrangler dev`; alchemy.run.ts creates the
+  // deployed one. connecta creates its tables on first use; nothing to apply.
   "d1_databases": [
     {
       "binding": "CONNECTA_DB",

package/guides/connecting-agents.md

@@ -0,0 +1,157 @@
+# Connecting an agent
+
+Your **operator** is the person or team running the Connecta server. They
+choose which agent can connect, which tools it can use, and which service
+accounts those tools use. The model cannot grant itself more access.
+
+This guide explains those choices. The [operator documentation](../documentation/README.md)
+has exact setup and verification steps.
+
+## Choose the pool first
+
+Imagine an agent named `assistant` that helps with CRM records and tickets.
+Its operator creates a pool with the actions needed for that job and adds
+the agent as a member. The pool can be read-only if updates must be impossible.
+
+```mermaid
+flowchart LR
+    Identity["Agent · assistant"] --> Pool["Member of pool · tickets"]
+    Pool --> Tools["Allowed CRM and ticket tools"]
+    Tools --> Accounts["Connecta uses each connection's configured account"]
+```
+
+The address uses the **pool name**, not the agent name. If `assistant` belongs
+to a pool called `tickets`, its address is `/agent/tickets` on your Connecta
+server. For a pool called `assistant`, it is `/agent/assistant`.
+Ask your operator for the complete URL, such as
+`https://connecta.example.com/agent/tickets`; the model should not guess it.
+
+For shared organization access, a maintainer connects the service accounts
+once. The agent proves its identity to Connecta and never needs the CRM's
+password or the ticket service's API key. The operator should enable the
+[encrypted credential vault](../documentation/auth.md#connect-a-shared-credential)
+before saving those credentials or connecting accounts.
+
+## What to ask your operator for
+
+- **The pool name and complete endpoint URL.** Confirm this agent is a member.
+- **The authentication method.** Ask how the AI app will receive the agent
+  credential privately; keep it out of prompts and source files.
+- **The tools and accounts.** Know which actions are available, whose account
+  they use, and whether changes are allowed. In 0.35.0, a pool can offer
+  [native tools](../documentation/meta-tools.md#tool-presentation) for apps
+  with their own tool search.
+- **The approval policy.** Find out whether writes ask a person or run unattended.
+- **A safe first test.** Agree on a small read, such as listing one ticket,
+  and the result you expect.
+
+People use separate sign-in endpoints. The
+[pool reference](../documentation/auth.md#pools) owns the address and membership rules.
+
+## Choose how the agent proves its identity
+
+| Method                   | Best fit                    | What the operator provides                                     |
+| ------------------------ | --------------------------- | -------------------------------------------------------------- |
+| Connecta agent token     | An agent running anywhere   | A `cta_` secret issued for the declared agent.                 |
+| Vercel workload identity | An agent deployed on Vercel | Permission for a trusted project and its allowed environments. |
+
+An agent token stays in the AI app's secret store. The app presents it when
+it connects. Vercel identity uses a signed project token instead of a
+separately provisioned Connecta secret.
+
+```mermaid
+sequenceDiagram
+    participant H as AI app
+    participant C as Connecta
+    H->>C: Present the configured agent credential
+    C->>C: Verify the credential and pool membership
+    C-->>H: Serve the pool's permitted tools
+```
+
+Anyone who obtains either token can act as the agent. Trust the Vercel
+project code and build steps that can obtain its tokens, and enable only
+environments that should have the pool's access.
+
+The [token management guide](../documentation/auth.md#issue-rotate-or-revoke-an-agent-token)
+and [Vercel identity guide](../documentation/auth.md#vercel-workload-credentials)
+own availability, setup, rotation, and revocation. If both methods are
+enabled, stopping one does not stop the other.
+
+## An optional integration for Eve
+
+**Eve** is an app framework for building agents. If your agent uses Eve,
+`@zackbart/connecta-eve` can connect it to a pool and load the endpoint's
+instructions at the start of a turn. The helper runs in the Eve app; your
+Connecta server runs separately.
+
+The [helper's README](https://github.com/zackbart/connecta/blob/main/packages/connecta-eve/README.md)
+owns installation, supported Node/Eve versions, environment setup, and the
+Vercel variant. The following two files illustrate its two jobs after your
+operator has configured the endpoint and credential.
+
+`agent/connections/connecta.ts` connects to the pool:
+
+```ts
+import { connectaConnection } from "@zackbart/connecta-eve";
+
+export default connectaConnection({
+  pool: "tickets",
+  description: "Shared CRM and tickets for the assistant.",
+});
+```
+
+`agent/instructions/connecta.ts` supplies guidance for using it:
+
+```ts
+import { connectaInstructions } from "@zackbart/connecta-eve";
+
+export default connectaInstructions({ pool: "tickets" });
+```
+
+Both files must use the same endpoint and credential source. The helper uses
+the configured agent credential, without forwarding the chatting person's
+identity. Instructions help the model use tools; they grant no permissions.
+
+## Decide whether writes need a person
+
+The helper defaults to unattended execution of authorized writes. Connecting
+an agent does not automatically add an approval step.
+
+```mermaid
+flowchart TB
+    Call["Agent requests a change"] --> Ask{"App asks for approval?"}
+    Ask -->|Yes| Approved{"Person approves?"}
+    Approved -->|No| Stop["Stop"]
+    Approved -->|Yes| Pool{"Connecta allows this write?"}
+    Ask -->|No| Pool
+    Pool -->|No| Refuse["Refuse before sending"]
+    Pool -->|Yes| Send["Send the change"]
+```
+
+For an interactive Eve agent, `gateWrites: true` asks before tools not marked
+read-only. An explicit Eve approval policy takes precedence. If the agent
+must never update data, use a read-only pool.
+
+Approval may rely on an earlier tool label. A writable pool can execute a
+newly classified write without a fresh approval; a read-only pool refuses it.
+[Safety and trust](./safety-and-trust.md) explains the boundary, and the
+[helper guide](https://github.com/zackbart/connecta/blob/main/packages/connecta-eve/README.md#approval-and-writes)
+explains the policy mechanics.
+
+## When accounts or audiences differ
+
+Personal connections belong to a signed-in person and are absent for agents.
+Google Workspace has an explicit exception: an operator can assign a pool
+owner whose account the agent will use. See
+[Workspace pool owners](../documentation/auth.md#pool-owners-for-google-workspace)
+before connecting an agent to someone's account.
+
+An assistant serving several people must use a pool appropriate for everyone
+in the conversation. Its app chooses that pool; the model does not choose
+its own access level. Keep private results out of broader conversations.
+The [pool layout guide](../documentation/auth.md#organizing-an-agents-pools)
+owns that policy.
+
+After setup, run the agreed small read with your operator. Use the
+[verification guide](../documentation/deploying.md#verify-and-diagnose)
+when the connection or access differs from what you expected.

package/guides/how-it-works.md

@@ -0,0 +1,156 @@
+# How Connecta works
+
+Connecta is a front door for the services your agent needs. It gives the
+agent one connection, then checks each request before it reaches a service.
+Your **operator**, the person or team running Connecta, chooses what belongs
+behind that door.
+
+This guide explains the pieces. The [operator documentation](../documentation/README.md)
+owns exact setup and behavior.
+
+## Start with connections
+
+A **connector** is one connection to a service. For example, a connector
+called `crm` could reach your shared CRM account, where you keep customer
+records. Its tools might find a person or update their address.
+A second connector could reach a different account at the same service.
+
+An **API** is the interface a service gives other software. Connecta can wrap
+that interface in tools, or connect to a hosted MCP server that already offers
+tools. MCP is the standard used to make those tools available to AI apps.
+
+```mermaid
+flowchart LR
+    Connecta --> Maintained["Maintained integration"] --> Vendor["Vendor API"]
+    Connecta --> Remote["Remote MCP connection"] --> Hosted["Hosted tools"]
+    Connecta --> Custom["Your API connection"] --> CRM["Your CRM API"]
+```
+
+A maintained integration comes with Connecta's tools and guidance. A remote
+MCP connection uses the tools the server offers to that account. A custom
+API connection lets your operator describe selected actions.
+
+All three go through Connecta's access checks. A remote server's list of
+actions can change, and Connecta relies on truthful descriptions of which
+actions change data.
+
+The README lists [maintained connections](../README.md#what-you-can-connect).
+For setup and migrations, see [Integrating services](../documentation/integrating.md).
+
+## A pool is a smaller front door
+
+A **pool** is a named selection of tools and the people or agents allowed
+to use them. The operator creates it and gives it an **endpoint**: a
+connection address for that pool.
+
+One pool might let the assistant read CRM records. Another might let a
+person update tickets. Tools and accounts are separate choices: a pool
+chooses the actions, while each connection uses its configured account.
+
+```mermaid
+flowchart LR
+    Alice["alice · person"] --> Tickets["tickets pool<br/>ticket tools"]
+    Assistant["assistant · agent"] --> CRM["crm pool<br/>CRM reads"]
+    Tickets --> Check["Connecta checks access"]
+    CRM --> Check
+    Check --> Accounts["Use each connection's configured account"]
+```
+
+People sign in. Agents use an identity configured by the operator.
+The model cannot change that identity or add itself to a pool.
+
+Each request uses one pool. Belonging to two pools does not merge them.
+An AI app can switch between pools it is allowed to use; its software must
+choose the right one for the conversation. The model does not choose its
+own access level.
+
+Maintainers run the deployment and can reach its whole tool list through
+the main human endpoint. Other people use their assigned pools.
+Agents use shared accounts selected by the operator. They do not inherit
+the account of the person chatting with them.
+
+[Connecting agents](./connecting-agents.md) explains pool addresses and
+account choices, including the Google Workspace exception.
+
+## Finding a tool and using it are separate steps
+
+First the agent finds an action and learns what information it needs.
+Then it calls that action. The default connection gives the AI app six small
+**meta-tools** to help it do this without loading every service's tools into
+the conversation.
+
+| Tool                    | Job                                                                          |
+| ----------------------- | ---------------------------------------------------------------------------- |
+| `search_tools`          | Find available actions.                                                      |
+| `call_tool`             | Call a discovered action that reads data.                                    |
+| `call_destructive_tool` | Call a discovered action that changes data, under the app's approval policy. |
+| `execute_code`          | Combine discovery, actions, and a small answer in a program.                 |
+| `authorize_connector`   | Request the permitted account-connection handoff.                            |
+| `skills`                | Read guidance for using a connection.                                        |
+
+In 0.35.0, **native tools** let apps with their own tool search find service
+actions directly. The operator chooses the pool's presentation.
+
+```mermaid
+flowchart TB
+    Meta["Default · meta-tools<br/>Connecta helps find the action"] --> Checks
+    Native["Optional · native tools<br/>the app finds the action"] --> Checks
+    Checks["Same access checks"] --> Service["Service action"]
+```
+
+The presentation changes how an action is found, without granting more
+access. The [tool reference](../documentation/meta-tools.md#tool-presentation)
+tracks availability and supported behavior.
+
+## Why run code inside Connecta?
+
+Suppose the agent needs a count of open tickets for each CRM account.
+Instead of returning every record to the conversation, a short JavaScript
+program can fetch the records, match their IDs, and return a small table.
+
+The program runs in a restricted environment. It can use only this endpoint's
+tools, and cannot create connections, choose another identity, or obtain
+service credentials. Limits keep it from running indefinitely or returning
+unbounded data.
+
+With meta-tools, one discovered read can use a direct call. Finding an unfamiliar
+action, combining several calls, or reducing a large answer belongs in a program.
+On a writable endpoint, a program may also change data. The AI app decides
+whether to ask for approval before running it.
+
+The [endpoint workflow](../documentation/operating.md) and
+[code reference](../documentation/code-mode.md) explain the mechanics.
+
+## Follow one call
+
+```mermaid
+sequenceDiagram
+    participant A as AI app
+    participant C as Connecta
+    participant S as Service
+    A->>C: Request an action through a pool
+    C->>C: Check caller, allowed tools, and read-only rules
+    C->>S: Send with the configured service credential
+    S-->>C: Result or failure
+    C-->>A: Bounded result with known secrets redacted
+```
+
+These checks also apply to calls inside programs. Guessing a tool name does
+not bypass them. Read-only rules refuse tools marked as writes before they
+are sent.
+
+For tools marked as writes, Connecta does not automatically repeat a sent
+change after an uncertain failure. Truthful tool classification matters;
+[Safety and trust](./safety-and-trust.md) explains the limit and recovery.
+
+## Why an answer may be shorter
+
+Programs can filter, count, join, and summarize records before returning
+them. Connecta also limits output size. Some large results return a preview
+and a handle for retrieving more; some tools shorten fields and report it.
+A preview is not necessarily the whole answer.
+
+The [result reference](../documentation/meta-tools.md#result-representation)
+explains how to retrieve more. Never repeat a change just to recover its
+output. Redaction keeps known secrets out of results; it does not make
+business records safe to share with everyone.