@opencomputer/blue 0.0.6 → 0.0.9

package/README.md

@@ -130,6 +130,79 @@ When running this repository directly, substitute
 `../../node_modules/.bin/tsx ../../src/cli/index.ts` for `blue`. The installed
 package exposes the shorter `blue` binary.
 
+### Tools and connections
+
+Tools are checked-in OpenCode functions under `agent/tools/`. Connections are
+separate account authorizations: they can be replaced or revoked without
+changing agent code, and credentials never become part of an agent artifact.
+
+Add the built-in Gmail tools and their Google connection declaration:
+
+```bash
+blue tools add gmail
+```
+
+This creates `agent/tools/gmail.ts` with search, read, modify, and send tools,
+plus `agent/connections/google.json` with the required scopes. Blue compiles
+the tools into `.opencode/tools/`, so OpenCode discovers them and streams their
+normal tool events.
+
+Authorize a Google account for local development:
+
+```bash
+blue connections connect gmail --local
+blue dev
+blue session "Find unread email that needs a reply"
+```
+
+Local OAuth credentials are stored in the ignored
+`.blue/connections.json` file with mode `0600`. By default the CLI uses the
+platform's public Google OAuth client ID; set `BLUE_GOOGLE_CLIENT_ID` and
+optionally `BLUE_GOOGLE_CLIENT_SECRET` to use your own desktop OAuth client
+without contacting the hosted provider configuration. For a deployed agent:
+
+```bash
+blue deploy
+blue connections connect gmail --remote
+blue connections list
+```
+
+Remote credentials are AES-GCM encrypted in the account Durable Object. The
+MicroVM receives only its existing session-scoped runtime token. Custom tools
+use that token to call Blue's provider proxy, which restricts requests to the
+provider's supported API origins and refreshes OAuth tokens in the control
+plane.
+
+#### Gmail summarizer example
+
+The `examples/gmail-summarizer` agent is a safe starting point for inbox
+triage. In Google Cloud, enable the Gmail API, configure the OAuth consent
+screen with your account as a test user, and create an OAuth client with the
+Desktop app type. Then run:
+
+```bash
+cd examples/gmail-summarizer
+export BLUE_GOOGLE_CLIENT_ID="<client-id>.apps.googleusercontent.com"
+export BLUE_GOOGLE_CLIENT_SECRET="<client-secret>"
+blue connections connect gmail --local
+blue session \
+  "Summarize email from the last 24 hours. Group it into urgent, needs reply, informational, and low priority. Do not modify or send anything."
+```
+
+The browser consent redirects to a temporary loopback listener owned by the
+CLI. The resulting local credential remains in `.blue/connections.json`, which
+is ignored by Git. Run `blue connections list --local` to inspect it and
+`blue connections disconnect <connection-id> --local` to revoke it from Blue's
+local state.
+
+If Google reports `ACCESS_TOKEN_SCOPE_INSUFFICIENT`, open the OAuth app's
+Google Auth Platform **Data Access** settings and add
+`https://www.googleapis.com/auth/gmail.modify`. Confirm that the Gmail API is
+enabled and that the connecting account is an allowed test user, remove the
+old local connection, and reconnect while approving Gmail access. Blue
+validates the granted scopes during connection and will not store an
+identity-only token.
+
 ### Local Slack
 
 Install and authenticate the
@@ -220,7 +293,10 @@ The hosted Worker requires:
   `BLUE_WORKOS_JWKS_URL`;
 - `OPENROUTER_API_KEY` as a Worker secret;
 - `BLUE_CHANNEL_ENCRYPTION_KEY` as a Worker secret containing a base64-encoded
-  32-byte random key;
+  32-byte random key; this currently protects channel and tool connection
+  credentials;
+- `BLUE_GOOGLE_CLIENT_ID` and optionally `BLUE_GOOGLE_CLIENT_SECRET` for a
+  Google OAuth desktop client;
 - `BLUE_RUNTIME_IMAGE_ARN` and `BLUE_RUNTIME_IMAGE_VERSION`;
 - a `DEPLOYMENTS` service binding that returns signed platform artifact
   uploads;
@@ -241,6 +317,10 @@ npx wrangler secret put BLUE_RUNTIME_IMAGE_VERSION \
   --config wrangler.production.jsonc
 npx wrangler secret put BLUE_CHANNEL_ENCRYPTION_KEY \
   --config wrangler.production.jsonc
+npx wrangler secret put BLUE_GOOGLE_CLIENT_ID \
+  --config wrangler.production.jsonc
+npx wrangler secret put BLUE_GOOGLE_CLIENT_SECRET \
+  --config wrangler.production.jsonc
 ```
 
 Generate the channel encryption secret with `openssl rand -base64 32`. Every
@@ -248,6 +328,11 @@ remote Slack installation receives a unique callback credential, stored by
 Blue only as a hash. Slack CLI configures that callback automatically from the
 agent manifest.
 
+Google local authorization uses a desktop loopback redirect with PKCE.
+Gmail's `gmail.modify` scope is restricted, so a public production OAuth app
+must complete Google's verification requirements. OAuth access and refresh
+tokens are never returned by the Blue API after connection.
+
 Configure the platform Worker's AWS secrets plus
 `BLUE_AWS_REGION`, `BLUE_ARTIFACT_BUCKET`, `BLUE_EXECUTION_ROLE_ARN`,
 `BLUE_NETWORK_CONNECTOR_ARN`, `BLUE_S3_FILESYSTEM_ID`, and

package/dist/cli/index.js

@@ -1,19 +1,24 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { existsSync, mkdirSync } from "node:fs";
 import { rm } from "node:fs/promises";
+import { createServer } from "node:http";
 import { basename, dirname, resolve } from "node:path";
 import process from "node:process";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
-import { DEFAULT_BLUE_API_URL, accessTokenFor, login, logout, readCredentials, } from "../auth/cli-auth.js";
+import { DEFAULT_BLUE_API_URL, accessTokenFor, login, logout, openBrowser, readCredentials, } from "../auth/cli-auth.js";
+import { assertGoogleScopes, exchangeGoogleCode, GMAIL_SCOPES, googleAuthorizationUrl, resolveGoogleIdentity, } from "../connections/google.js";
+import { readLocalConnections, writeLocalConnections, } from "../connections/local.js";
 import { captureLocalSlackState, localSlackStatePath, readLocalSlackState, readRemoteSlackState, remoteSlackStatePath, renderSlackProjectManifest, writeRemoteSlackState, } from "../channels/slack-project.js";
-import { addSlackChannel, findAgentRoot, initializeAgent, prepareAgent, } from "../core/agent.js";
+import { addSlackChannel, addGmailTools, findAgentRoot, initializeAgent, prepareAgent, } from "../core/agent.js";
 import { buildAgentArtifact } from "../core/artifact.js";
 import { findDevState, requestDevManager, startDevManager, } from "../dev/manager.js";
 import { startLocalControlPlane } from "../dev/local-control-plane.js";
 import { authenticateOpenRouter, readOpenRouterCredential, } from "../openrouter/auth.js";
 import { agentLandingPath } from "../landing/agent.js";
+import { renderConnectionCallback } from "../landing/connection-callback.js";
 import { BlueClient } from "../sdk/client.js";
 const DEFAULT_EDGE = DEFAULT_BLUE_API_URL;
 function argument(name) {
@@ -514,6 +519,7 @@ async function deployAgent(edge) {
         agentId: built.agentId,
         alias,
         channels: built.channels,
+        connections: built.connections,
         artifact: upload.artifact,
     });
     const identity = await client.whoami();
@@ -523,6 +529,7 @@ async function deployAgent(edge) {
         `alias: ${deployment.alias}\n` +
         `url: ${agentUrl}\n` +
         `channels: ${deployment.channels.join(", ") || "none"}\n` +
+        `connections: ${deployment.connections.join(", ") || "none"}\n` +
         `artifact: s3://${deployment.artifact.bucket}/${deployment.artifact.key}\n` +
         `ready in: ${String(built.elapsedMs)}ms\n`);
 }
@@ -558,6 +565,210 @@ async function agentRootForSlack() {
     }
     return root;
 }
+async function currentAgentRoot() {
+    const root = await findAgentRoot(argument("agent-dir") ?? process.cwd());
+    if (!root) {
+        throw new Error("No Blue agent repository was found");
+    }
+    return root;
+}
+async function googleOAuthCallback(begin) {
+    const codeVerifier = randomBytes(32).toString("base64url");
+    const codeChallenge = createHash("sha256")
+        .update(codeVerifier)
+        .digest("base64url");
+    let expectedState = "";
+    let resolveCallback;
+    let rejectCallback;
+    const callback = new Promise((resolvePromise, reject) => {
+        resolveCallback = resolvePromise;
+        rejectCallback = reject;
+    });
+    const server = createServer((request, response) => {
+        const url = new URL(request.url ?? "/", "http://127.0.0.1");
+        if (url.pathname !== "/oauth/callback") {
+            response.writeHead(404).end();
+            return;
+        }
+        const error = url.searchParams.get("error");
+        const code = url.searchParams.get("code");
+        const state = url.searchParams.get("state");
+        response.writeHead(error || !code || state !== expectedState ? 400 : 200, {
+            "content-type": "text/html; charset=utf-8",
+        });
+        response.end(error || !code || state !== expectedState
+            ? renderConnectionCallback({
+                provider: "Google",
+                status: "error",
+            })
+            : renderConnectionCallback({
+                provider: "Google",
+                status: "success",
+            }));
+        if (error) {
+            rejectCallback(new Error(`Google authorization failed: ${error}`));
+        }
+        else if (!code || !state || state !== expectedState) {
+            rejectCallback(new Error("Google returned an invalid OAuth callback"));
+        }
+        else {
+            resolveCallback({ code, state });
+        }
+    });
+    await new Promise((resolvePromise, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            server.off("error", reject);
+            resolvePromise();
+        });
+    });
+    const address = server.address();
+    if (!address || typeof address === "string") {
+        server.close();
+        throw new Error("Could not create the local OAuth callback");
+    }
+    const redirectUri = `http://127.0.0.1:${String(address.port)}/oauth/callback`;
+    try {
+        const started = await begin(redirectUri, codeChallenge);
+        expectedState = started.state;
+        process.stdout.write(`Open ${started.authorizationUrl}\n`);
+        openBrowser(started.authorizationUrl);
+        const timeout = new Promise((_resolve, reject) => {
+            setTimeout(() => reject(new Error("Google authorization timed out")), 5 * 60_000).unref();
+        });
+        const result = await Promise.race([callback, timeout]);
+        return { ...result, codeVerifier, redirectUri };
+    }
+    finally {
+        await new Promise((resolvePromise) => server.close(() => resolvePromise()));
+    }
+}
+async function connectGoogleLocal(edge) {
+    const root = await currentAgentRoot();
+    const clientId = process.env.BLUE_GOOGLE_CLIENT_ID ??
+        (await (await clientFor(edge)).connectionProvider("google")).clientId;
+    const config = {
+        clientId,
+        clientSecret: process.env.BLUE_GOOGLE_CLIENT_SECRET,
+    };
+    const state = randomBytes(24).toString("base64url");
+    const callback = await googleOAuthCallback(async (redirectUri, codeChallenge) => ({
+        state,
+        authorizationUrl: googleAuthorizationUrl({
+            config,
+            redirectUri,
+            scopes: [...GMAIL_SCOPES],
+            state,
+            codeChallenge,
+        }),
+    }));
+    const credential = await exchangeGoogleCode({
+        config,
+        code: callback.code,
+        codeVerifier: callback.codeVerifier,
+        redirectUri: callback.redirectUri,
+    });
+    assertGoogleScopes(credential, [...GMAIL_SCOPES]);
+    const identity = await resolveGoogleIdentity(credential);
+    const path = resolve(root, ".blue", "connections.json");
+    const connections = await readLocalConnections(path);
+    const label = argument("label") ?? "default";
+    const timestamp = new Date().toISOString();
+    const next = {
+        id: randomUUID(),
+        provider: "google",
+        label,
+        externalAccountId: identity.id,
+        displayName: identity.email,
+        scopes: credential.scopes.length
+            ? credential.scopes
+            : [...GMAIL_SCOPES],
+        clientId,
+        clientSecret: config.clientSecret,
+        credential,
+        createdAt: timestamp,
+        updatedAt: timestamp,
+    };
+    await writeLocalConnections(path, [
+        next,
+        ...connections.filter((connection) => connection.provider !== "google" || connection.label !== label),
+    ]);
+    process.stdout.write(`connected: local\nprovider: google\naccount: ${identity.email}\nlabel: ${label}\n`);
+}
+async function connectGoogleRemote(edge) {
+    await currentAgentRoot();
+    const agentId = argument("agent") ?? (await inferDeployedAgent());
+    if (!agentId) {
+        throw new Error("Run this inside an agent repository or pass --agent");
+    }
+    const client = await clientFor(edge);
+    let connectionId;
+    try {
+        const callback = await googleOAuthCallback(async (redirectUri, codeChallenge) => {
+            const started = await client.startConnection({
+                provider: "google",
+                agentId,
+                label: argument("label") ?? "default",
+                scopes: [...GMAIL_SCOPES],
+                redirectUri,
+                codeChallenge,
+            });
+            connectionId = started.connection.id;
+            return {
+                authorizationUrl: started.authorizationUrl,
+                state: started.state,
+            };
+        });
+        if (!connectionId)
+            throw new Error("Connection was not reserved");
+        const connection = await client.completeConnection(connectionId, callback);
+        process.stdout.write(`connected: remote\nconnection: ${connection.id}\n` +
+            `provider: ${connection.provider}\n` +
+            `account: ${connection.displayName ?? connection.externalAccountId ?? "unknown"}\n` +
+            `agent: ${connection.agentId}@${connection.alias}\n` +
+            `label: ${connection.label}\n`);
+    }
+    catch (error) {
+        if (connectionId) {
+            await client.disconnectConnection(connectionId).catch(() => undefined);
+        }
+        throw error;
+    }
+}
+async function listConnections(edge) {
+    let found = false;
+    const root = await findAgentRoot(process.cwd());
+    if (!hasFlag("remote") && root) {
+        const local = await readLocalConnections(resolve(root, ".blue", "connections.json"));
+        for (const connection of local) {
+            found = true;
+            process.stdout.write(`${connection.id}  ${connection.provider.padEnd(10)}  local       ` +
+                `${connection.label.padEnd(12)}  ${connection.displayName}\n`);
+        }
+    }
+    if (!hasFlag("local")) {
+        const remote = await (await clientFor(edge)).listConnections();
+        for (const connection of remote) {
+            found = true;
+            process.stdout.write(`${connection.id}  ${connection.provider.padEnd(10)}  ` +
+                `${connection.status.padEnd(11)}  ${connection.label.padEnd(12)}  ` +
+                `${connection.displayName ?? connection.externalAccountId ?? "pending"}\n`);
+        }
+    }
+    if (!found)
+        process.stdout.write("No connections.\n");
+}
+async function disconnectLocalConnection(connectionId) {
+    const root = await currentAgentRoot();
+    const path = resolve(root, ".blue", "connections.json");
+    const connections = await readLocalConnections(path);
+    const next = connections.filter((connection) => connection.id !== connectionId);
+    if (next.length === connections.length) {
+        throw new Error("Local connection not found");
+    }
+    await writeLocalConnections(path, next);
+    process.stdout.write(`disconnected: ${connectionId}\n`);
+}
 async function connectLocalSlack() {
     const root = await agentRootForSlack();
     await runSlackCli(root, ["app", "install", "--environment", "local"], "local");
@@ -736,7 +947,9 @@ async function dev() {
         port,
         agentId: prepared.name,
         slackEnabled: builtInSlackChannel(prepared.root),
+        googleEnabled: existsSync(resolve(prepared.root, "agent", "connections", "google.json")),
         statePath: resolve(prepared.root, ".blue", "dev", "control-plane.json"),
+        connectionStatePath: resolve(prepared.root, ".blue", "connections.json"),
         openRouterApiKey: process.env.OPENROUTER_API_KEY,
         model: process.env.BLUE_MODEL,
     });
@@ -809,6 +1022,12 @@ Usage:
   blue demo [prompt] [--agent-dir path] [--harness mock|opencode]
   blue run <prompt> [--agent <agent>@<alias>]
   blue auth openrouter
+  blue tools add gmail [--agent-dir path]
+  blue connections connect gmail --local
+  blue connections connect gmail --remote [--agent agent@alias]
+  blue connections list [--local|--remote]
+  blue connections disconnect <connection-id> --local
+  blue connections disconnect <connection-id> --remote
   blue channels add slack [--agent-dir path]
   blue channels connect slack --local
   blue channels connect slack --remote [--agent agent@alias]
@@ -910,6 +1129,48 @@ async function main() {
         process.stdout.write("OpenRouter connected locally.\n");
         return;
     }
+    if (command === "tools") {
+        const [action, toolName] = positional(3);
+        if (action === "add" && toolName === "gmail") {
+            process.stdout.write(`created: ${await addGmailTools(argument("agent-dir") ?? process.cwd())}\n`);
+            return;
+        }
+        throw new Error("Usage: blue tools add gmail");
+    }
+    if (command === "connections") {
+        const [action, provider, connectionId] = positional(3);
+        if (action === "connect" && (provider === "gmail" || provider === "google")) {
+            if (hasFlag("local") && hasFlag("remote")) {
+                throw new Error("Choose either --local or --remote");
+            }
+            if (!hasFlag("local") && !hasFlag("remote")) {
+                throw new Error("Pass --local or --remote");
+            }
+            if (hasFlag("local")) {
+                await connectGoogleLocal(hostedEdge());
+            }
+            else {
+                await connectGoogleRemote(hostedEdge());
+            }
+            return;
+        }
+        if (action === "list") {
+            await listConnections(hostedEdge());
+            return;
+        }
+        if (action === "disconnect" && provider) {
+            if (hasFlag("local")) {
+                await disconnectLocalConnection(provider);
+            }
+            else {
+                const connection = await (await clientFor(hostedEdge())).disconnectConnection(provider);
+                process.stdout.write(`disconnected: ${connection.id}\n`);
+            }
+            return;
+        }
+        void connectionId;
+        throw new Error("Unsupported connections command");
+    }
     if (command === "channels") {
         const [action, channel, connectionId] = positional(3);
         if (action === "add" && channel === "slack") {