@stage-labs/metro 0.1.0-beta.271 → 0.1.0-beta.273

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage-labs/metro",
-  "version": "0.1.0-beta.271",
+  "version": "0.1.0-beta.273",
   "description": "The metro command line: run your agent on this machine, relaying its chat channels and connectors to Claude Code.",
   "license": "MIT",
   "repository": {

package/runtime/marketplace/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "metro",
-  "version": "0.1.0-beta.271",
+  "version": "0.1.0-beta.273",
   "description": "Metro for Claude Code, installed by the metro daemon on this machine: every connector the agent holds as its own MCP server relayed through the daemon, the orchestrator-only guard on the main thread, and the standing rules loaded at each session start. No vendor credential ever sits in a config file.",
   "author": {
     "name": "Bonustrack",

package/runtime/marketplace/plugin/STAGE.md

@@ -45,6 +45,9 @@ The separate `metadata.status` and `metadata.priority` fields are optional. Stat
 - Delete one of your own messages: `delete {"line": "…", "message_id": "…"}`. XMTP has no edit and no typing.
 - History: `read {"line": "…", "limit": 20}`.
 - Poll: `ask {"line": "…", "question": "Ship today?", "options": ["Yes", "No"]}`.
+- Poll votes are numeric reactions with zero-based indexes: `0` is the first option, `1` is the second, and so on, in the poll's stored option order. For the poll above, `0` means Yes and `1` means No. Never use a one-based guess. Match the inbound reaction's `target_id` to the poll's `messageId` returned by `ask`, not its `pollId` or the reaction's own `message_id`.
+- With several questions, the first question still uses bare option indexes (`0`, `1`, …); later questions use `q:o`, with both indexes zero-based. `1:0` means the first option of the second question. Explicit `0:0` also means the first option of the first question.
+- Keep the poll's questions, options and `messageId`: `read` shows `[poll]` and `[reaction]`, not their choices or vote values. If the original mapping is unavailable, do not guess.
 - File: `create_upload {"name": "report.pdf"}`, run the `curl` line it returns in a shell, then `send {"line": "…", "attachments": [{"upload": "<upload_id>"}]}`. Files that are not images are refused over about 190 KiB.
 
 **Frames.** A frame is a small interactive view: a report, a choice, a form. Stage shows the frame itself in the chat (its `start` screen when it has screens), at image size, at most 400 x 400, clipped with a fade when taller. A tap opens it full screen. Its buttons do nothing in the chat: they work in the full view.

package/runtime/node_modules/@metro-labs/core/src/tickets.ts

@@ -2,6 +2,7 @@ import { randomBytes } from 'node:crypto';
 
 export interface TicketStore<T> {
   mint: (value: T, now?: number) => { ticket: string; expiresAt: number };
+  peek: (ticket: string, now?: number) => T | undefined;
   take: (ticket: string, now?: number) => T | undefined;
   size: (now?: number) => number;
 }
@@ -24,6 +25,12 @@ export function ticketStore<T>(ttlMs: number, max: number): TicketStore<T> {
       open.set(ticket, { value, expiresAt });
       return { ticket, expiresAt };
     },
+    peek(ticket, now = Date.now()) {
+      const entry = open.get(ticket);
+      if (entry !== undefined && entry.expiresAt > now) return entry.value;
+      open.delete(ticket);
+      return undefined;
+    },
     take(ticket, now = Date.now()) {
       const entry = open.get(ticket);
       open.delete(ticket);

package/runtime/node_modules/@metro-labs/daemon/src/agents/accounts-api.ts

@@ -5,7 +5,7 @@ import { approversForAccount } from './map.js';
 import { isRecord } from '@metro-labs/core/is-record';
 import type { RecentSender } from './senders.js';
 import { ApiError } from '@metro-labs/http/api-error';
-import { apiFailure, bodyField, readJsonBody, sendJson } from '@metro-labs/http/api-http';
+import { apiFailure, bodyField, readJsonBody, sendJson, type ApiSession } from '@metro-labs/http/api-http';
 import { type AccountRef } from './account-attach.js';
 import { type AccountRoute } from './account-routes.js';
 import { handlePolicy, type SetPolicy } from './policy-route.js';
@@ -138,7 +138,7 @@ async function storeAccount(
 
 function asInput(body: unknown): Record<string, unknown> {
   const out: Record<string, unknown> = {};
-  for (const key of ['apiId', 'apiHash', 'phone', 'mailbox', 'clientId', 'clientSecret'])
+  for (const key of ['apiId', 'apiHash', 'phone', 'mailbox', 'clientId', 'clientSecret', 'mode', 'sendEnabled', 'accountId'])
     out[key] = bodyField(body, key);
   return out;
 }
@@ -148,12 +148,13 @@ async function handleStart(
   res: ServerResponse,
   deps: AccountApiDeps,
   agentId: string,
+  owner: AttachOwner,
 ): Promise<void> {
   const body = await readJsonBody(req);
   const station = bodyField(body, 'station');
   if (isInteractiveStation(station)) {
     const view = await deps.attachSessions.start(
-      { agentId },
+      owner,
       station,
       asInput(body),
     );
@@ -320,10 +321,12 @@ async function dispatchAttach(
   deps: AccountApiDeps,
   agentId: string,
   route: Extract<AccountRoute, { kind: 'start' | 'session' | 'step' }>,
+  session?: ApiSession,
 ): Promise<void> {
-  if (route.kind === 'start') return handleStart(req, res, deps, agentId);
-  if (route.kind === 'session') return handleSession(req, res, deps, { agentId }, route.attachId);
-  return handleStep(req, res, deps, { agentId }, route.attachId);
+  const owner: AttachOwner = { agentId, organization: session?.subject, userId: session?.userId, sessionId: session?.sessionId, authorization: req.headers.authorization };
+  if (route.kind === 'start') return handleStart(req, res, deps, agentId, owner);
+  if (route.kind === 'session') return handleSession(req, res, deps, owner, route.attachId);
+  return handleStep(req, res, deps, owner, route.attachId);
 }
 
 async function dispatchRoute(
@@ -332,8 +335,9 @@ async function dispatchRoute(
   deps: AccountApiDeps,
   agentId: string,
   route: AccountRoute,
+  session?: ApiSession,
 ): Promise<void> {
-  if (route.kind === 'start' || route.kind === 'session' || route.kind === 'step') return dispatchAttach(req, res, deps, agentId, route);
+  if (route.kind === 'start' || route.kind === 'session' || route.kind === 'step') return dispatchAttach(req, res, deps, agentId, route, session);
   if (route.kind === 'allowlist') return handleAllowlist(req, res, deps, agentId, route);
   if (route.kind === 'enabled') return handleEnabled(req, res, deps, agentId, route);
   if (route.kind === 'policy') return handlePolicy(req, res, deps, agentId, route);
@@ -348,9 +352,10 @@ export async function handleAccountRoute(
   deps: AccountApiDeps,
   agentId: string,
   route: AccountRoute,
+  session?: ApiSession,
 ): Promise<void> {
   try {
-    await dispatchRoute(req, res, deps, agentId, route);
+    await dispatchRoute(req, res, deps, agentId, route, session);
   } catch (err) {
     apiFailure(req, res, err);
   }

package/runtime/node_modules/@metro-labs/daemon/src/agents/api.ts

@@ -25,6 +25,7 @@ export interface AgentApiDeps extends AccountApiDeps {
   capabilities: () => Record<string, string[]>;
   toolGroups?: () => Record<string, { name: string; group: string }[]>;
   attachable?: string[];
+  features?: string[];
   connectorIds: (agentIds: string[]) => Promise<Map<string, string[]>>;
 }
 
@@ -69,6 +70,7 @@ async function handleList(
   const base = {
     agents: list.map((a) => agentPayload(a, connectors)),
     capabilities: deps.capabilities(),
+    features: deps.features ?? [],
     attachable: deps.attachable ?? ATTACHABLE,
     ...(deps.toolGroups === undefined ? {} : { tools: deps.toolGroups() }),
   };
@@ -100,7 +102,7 @@ async function dispatch(
     sendJson(req, res, 401, { error: 'unauthorized' });
     return;
   }
-  if (tgt.kind === 'accounts') await handleAccountRoute(req, res, deps, tgt.id, tgt.route);
+  if (tgt.kind === 'accounts') await handleAccountRoute(req, res, deps, tgt.id, tgt.route, session);
   else await handleList(req, res, deps);
 }
 

package/runtime/node_modules/@metro-labs/daemon/src/agents/file-admin.ts

@@ -116,6 +116,7 @@ function assertUnclaimed(existing: Stored[], agent: LoadedAgent): void {
 }
 
 function assertImportable(agent: LoadedAgent): void {
+  if (agent.accounts.some((a) => a.station === 'gmail' && a.config.managed === true)) throw new AgentAdminError('Managed Gmail cannot be imported. Connect the mailbox again on this box.', 400);
   const immovable = agent.accounts.find((a) => !MOVABLE_STATIONS.has(a.station));
   if (immovable !== undefined)
     throw new AgentAdminError(
@@ -170,6 +171,7 @@ function mergedStations(
   const fromMetro = agent.accounts
     .map((a) => ({ ...a, allowlist: a.allowlist ?? ['*'] }))
     .filter((m) => mode === 'overwrite' || !here(m.station, m.id));
+  if (fromMetro.some((m) => m.station === 'gmail' && before.some((s) => s.station === 'gmail' && s.id === m.id && s.config.managed === true))) throw new AgentAdminError('Managed Gmail cannot be overwritten by an import. Delete the connection first.', 400);
   const kept = before.filter((s) => !fromMetro.some((m) => m.station === s.station && m.id === s.id));
   return [...fromMetro, ...kept];
 }
@@ -198,6 +200,16 @@ function fileFor(
   }
 }
 
+export function localRenewGmail(agentId: string, accountId: string, previous: string, config: Record<string, unknown>, dir = agentsDir()): AccountRef {
+  const stored = agentOrThrow(agentId, dir);
+  const account = stored.file.stations.find((s) => s.station === 'gmail' && s.id === accountId);
+  if (account === undefined || (account.config.authorizationId ?? account.config.refreshToken) !== previous) throw new AgentAdminError('This Gmail connection changed. Start again.', 409);
+  if (account.config.accountEmail !== config.accountEmail) throw new AgentAdminError('The Gmail mailbox did not match. Nothing was changed.', 400);
+  account.config = { ...account.config, ...config };
+  save(stored);
+  return { agentId, station: 'gmail', accountId };
+}
+
 export function readLocalAgentFile(agentId: string, dir = agentsDir()): AgentFile {
   const found = storedAgents(dir).find((s) => s.file.id === agentId);
   if (found === undefined) throw missing();
@@ -233,7 +245,7 @@ export async function localAttachAccount(
   assertCredentialFree(storedAgents(dir), station, config);
   const taken = new Set(stored.file.stations.map((a) => a.id));
   const accountId = freshId(taken);
-  stored.file.stations.push({ station, id: accountId, allowlist: ['*'], enabled: true, config });
+  stored.file.stations.push({ station, id: accountId, allowlist: ['*'], enabled: true, ...(station === 'gmail' && config.sendEnabled === false ? { policy: { write: 'deny' as const } } : {}), config });
   save(stored);
   return Promise.resolve({ agentId, station, accountId });
 }

package/runtime/node_modules/@metro-labs/daemon/src/boot/boot.ts

@@ -7,7 +7,8 @@ import { acquireLock, STATE_DIR, trainsDir } from './paths.js';
 import { installCrashGuard, markDaemonReady } from './crash-guard.js';
 import { METRO_VERSION } from '@metro-labs/core/version';
 import { funnelDriver, Tunnel, tunnelWanted } from '../net/tunnel.js';
-import { webhookPort } from '../files/attach-serve.js';
+import { publicBaseUrl, webhookPort } from '../files/attach-serve.js';
+import { setManagedHost } from '@metro-labs/gmail/managed-binding';
 import {
   localConnectHint,
   publicConnectHint,
@@ -80,7 +81,8 @@ supervisor.onTrainEvent((env, train) => {
 });
 
 let webhookServer: Server | null = null;
-const tunnel = tunnelWanted() ? new Tunnel(funnelDriver(webhookPort()), announcePublic) : null;
+const syncGmailHost = (): void => { setManagedHost(publicBaseUrl()); };
+const tunnel = tunnelWanted() ? new Tunnel(funnelDriver(webhookPort()), announcePublic, undefined, syncGmailHost) : null;
 
 function announcePublic(url: string): void {
   process.stderr.write(`\n${publicConnectHint(url, localOwner())}`);
@@ -140,6 +142,7 @@ installBearerSessions(agentsDir(), localOwner);
   log.info({ agent: await ensureLocalAgent() }, 'local daemon: agent');
   await materializeFrom(fileSource);
   forgetOrphans(knownAccounts());
+  syncGmailHost();
   supervisor.start();
   sweepLeftoverCalls();
   const metroMcp = await createMetroMcp({ liveEvents: liveEvents() });

package/runtime/node_modules/@metro-labs/daemon/src/claude/setup.ts

@@ -160,6 +160,7 @@ const PRIOR_STAGE: ReadonlySet<string> = new Set([
   'f87e9494ea6151d140b742c1b88b4f435ae653559be641fddc2160cd24dd4e1b',
   'cb4307b016855c1a09d48bc8b3924a3080bd78b205963df3d6f20401d0486df9',
   'f2be51c5290d2e61b47f10c379fa45d051a59a6b3f06d99174c2a170074bc8f5',
+  '4c727aa110c9023371cfb364f3304ad9db22cdf2501208ef1e42e6ccc245b00f',
 ]);
 const PRIOR_MEMORY: ReadonlySet<string> = new Set(['08795399635c8cdec2b50cb4e336f89ae880f3997ae52560ef647a9cdc8f1b08']);
 

package/runtime/node_modules/@metro-labs/daemon/src/net/tunnel.ts

@@ -187,12 +187,18 @@ export class Tunnel {
     private driver: TunnelDriver,
     private onUrl: (url: string) => void = () => undefined,
     private resolves: Resolves = resolvesPublicly,
+    private onChange: () => void = () => undefined,
   ) {}
 
+  private setUrl(url: string | null): void {
+    liveUrl = url;
+    this.onChange();
+  }
+
   private noticeUrl(text: string): void {
     const url = this.driver.urlIn(text);
     if (url === null || url === liveUrl) return;
-    liveUrl = url;
+    this.setUrl(url);
     this.restartDelay = RESTART_DELAY_MS;
     log.info({ url }, `${this.driver.name} up; waiting for its name to resolve`);
     this.announceWhenResolvable(url).catch((err: unknown) => {
@@ -240,7 +246,7 @@ export class Tunnel {
     }, SILENT_MS).unref();
     child.on('exit', (code) => {
       this.child = null;
-      liveUrl = null;
+      this.setUrl(null);
       if (this.closed) return;
       this.afterExit(code).catch((err: unknown) => {
         log.warn({ err: errMsg(err) }, `${this.driver.name}: exit handling failed`);
@@ -289,7 +295,7 @@ export class Tunnel {
       if (misses < ADOPTED_MISSES) return;
       this.unwatch();
       log.warn({ url }, `${this.driver.name}: the Funnel this daemon adopted no longer answers; publishing our own`);
-      liveUrl = null;
+      this.setUrl(null);
       this.restartDelay = RESTART_DELAY_MS;
       this.start();
     };
@@ -312,5 +318,6 @@ export class Tunnel {
     this.unwatch();
     this.child?.kill('SIGINT');
     this.child = null;
+    this.setUrl(null);
   }
 }

package/runtime/node_modules/@metro-labs/daemon/src/routes/bearer.ts

@@ -28,7 +28,7 @@ export function bearerSessionsFor(owner: () => string | null, keys: SigningKeys)
     const held = owner();
     if (held === null || session.organization === null || session.organization !== held)
       throw new ApiError('this machine belongs to another organization', 403);
-    return { subject: held, role: session.role === 'admin' ? 'admin' : 'member', ...(isOperatorUser(session.userId) ? { operator: true as const } : {}) };
+    return { subject: held, userId: session.userId, sessionId: session.sessionId, role: session.role === 'admin' ? 'admin' : 'member', ...(isOperatorUser(session.userId) ? { operator: true as const } : {}) };
   };
 }
 

package/runtime/node_modules/@metro-labs/daemon/src/routes/gmail-attach.ts

@@ -0,0 +1,67 @@
+import { randomUUID } from 'node:crypto';
+import { ApiError } from '@metro-labs/http/api-error';
+import { stringOf } from '@metro-labs/http/api-http';
+import { publicBaseUrl } from '../files/attach-serve.js';
+import { localOwner, readLocalAgentFile, localRenewGmail } from '../agents/file-admin.js';
+import { startManagedGmail } from '../stations/attach-gmail.js';
+import { startGmail } from '../stations/attach-browser.js';
+import type { AttachOwner, StartAttach } from '../stations/attach-session.js';
+import type { AttachOutcome, DriverHooks } from '../stations/attach-driver.js';
+import { assertGmailNotDeleting } from './gmail-detach.js';
+
+export function assertAttachOwner(owner: AttachOwner): void {
+  readLocalAgentFile(owner.agentId);
+  if (owner.organization !== undefined && owner.organization !== localOwner()) throw new ApiError('This box changed organization. Start again.', 403);
+}
+
+function gmailHost(): string {
+  const raw = publicBaseUrl();
+  const url = raw === null ? null : new URL(raw);
+  if (url === null || url.protocol !== 'https:' || url.username || url.password || url.pathname !== '/' || url.search || url.hash) throw new ApiError('Managed Gmail needs this box registered in Metro with its HTTPS address.', 400);
+  return url.host;
+}
+
+interface Upgrade {
+  accountId: string;
+  previous: string;
+}
+
+function gmailInput(owner: AttachOwner, input: Record<string, unknown>): { fields: Record<string, unknown>; upgrade?: Upgrade } {
+  if (input.mode !== 'upgrade') return { fields: { ...input, sendEnabled: false } };
+  const accountId = stringOf(input.accountId);
+  assertGmailNotDeleting(owner.agentId, accountId);
+  const account = readLocalAgentFile(owner.agentId).stations.find((s) => s.station === 'gmail' && s.id === accountId);
+  if (account === undefined) throw new ApiError('No such Gmail connection.', 404);
+  if (account.config.sendEnabled !== false) throw new ApiError('Sending is already authorized for this Gmail connection.', 409);
+  return {
+    fields: { clientId: account.config.clientId, clientSecret: account.config.clientSecret, mailbox: account.config.accountEmail, sendEnabled: true, mode: account.config.managed === true ? 'managed' : 'byo' },
+    upgrade: { accountId, previous: stringOf(account.config.authorizationId ?? account.config.refreshToken) },
+  };
+}
+
+export const startGmailAttach: StartAttach = async (_station, input, hooks, owner) => {
+  assertAttachOwner(owner);
+  const { fields, upgrade } = gmailInput(owner, input);
+  const bound: DriverHooks = {
+    ...hooks,
+    done: (outcome: AttachOutcome) => {
+      hooks.done({ ...outcome, config: { ...outcome.config, authorizationId: randomUUID(), ...(upgrade === undefined ? {} : { gmailUpgrade: upgrade }) } });
+    },
+  };
+  if (fields.mode !== 'managed') return startGmail(fields, bound);
+  const host = gmailHost();
+  return startManagedGmail({ host, owner, mailbox: fields.mailbox, sendEnabled: fields.sendEnabled === true, check: () => {
+    assertAttachOwner(owner);
+    if (gmailHost() !== host) throw new ApiError('This box changed address. Start again.', 409);
+  } }, bound);
+};
+
+export function finishGmailUpgrade(owner: AttachOwner, config: Record<string, unknown>): ReturnType<typeof localRenewGmail> | null {
+  const value = config.gmailUpgrade;
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return null;
+  const upgrade = value as Record<string, unknown>;
+  assertGmailNotDeleting(owner.agentId, stringOf(upgrade.accountId));
+  const saved = { ...config };
+  delete saved.gmailUpgrade;
+  return localRenewGmail(owner.agentId, stringOf(upgrade.accountId), stringOf(upgrade.previous), saved);
+}

package/runtime/node_modules/@metro-labs/daemon/src/routes/gmail-detach.ts

@@ -0,0 +1,37 @@
+import { ApiError } from '@metro-labs/http/api-error';
+import { localDetachAccount, localOwner, readLocalAgentFile } from '../agents/file-admin.js';
+import { forwardTrainCall } from '../stations/train-call.js';
+
+const deleting = new Set<string>();
+const keyOf = (agentId: string, accountId: string): string => `${agentId}/${accountId}`;
+
+export function assertGmailNotDeleting(agentId: string, accountId: string): void {
+  if (deleting.has(keyOf(agentId, accountId))) throw new ApiError('This Gmail connection is being deleted. Try again after it finishes.', 409);
+}
+
+async function revokeConnection(accountId: string, authorizationId: unknown): Promise<void> {
+  try {
+    const response = await forwardTrainCall('gmail', 'disconnect', { account: accountId, authorizationId });
+    const result = response.result as { revoked?: unknown } | undefined;
+    if (response.error !== undefined || result?.revoked !== true) throw new Error('revocation not confirmed');
+  } catch {
+    throw new ApiError('Google access could not be revoked. The Gmail channel was kept. Keep the Gmail service running and try deleting again.', 503);
+  }
+}
+
+export const detachWithGmailRevocation: typeof localDetachAccount = async (agentId, station, accountId, dir) => {
+  const config = station === 'gmail' ? readLocalAgentFile(agentId, dir).stations.find((a) => a.station === station && a.id === accountId)?.config : undefined;
+  if (config?.managed !== true) return localDetachAccount(agentId, station, accountId, dir);
+  assertGmailNotDeleting(agentId, accountId);
+  const key = keyOf(agentId, accountId);
+  const owner = localOwner(dir);
+  deleting.add(key);
+  try {
+    await revokeConnection(accountId, config.authorizationId);
+    const current = readLocalAgentFile(agentId, dir).stations.find((a) => a.station === station && a.id === accountId)?.config;
+    if (localOwner(dir) !== owner || current?.authorizationId !== config.authorizationId) throw new ApiError('This box or Gmail connection changed during deletion. Google access was revoked; review the connection before trying again.', 409);
+    return await localDetachAccount(agentId, station, accountId, dir);
+  } finally {
+    deleting.delete(key);
+  }
+};

package/runtime/node_modules/@metro-labs/daemon/src/routes/local-mode.ts

@@ -1,6 +1,9 @@
 import { ApiError } from '@metro-labs/http/api-error';
 import { errMsg, log } from '@metro-labs/core/log';
 import { AttachSessions } from '../stations/attach-session.js';
+import { startInteractiveAttach } from '../stations/attach-interactive.js';
+import { assertAttachOwner, finishGmailUpgrade, startGmailAttach } from './gmail-attach.js';
+import { detachWithGmailRevocation } from './gmail-detach.js';
 import { recentSenders } from '../agents/senders.js';
 import { forwardTrainCall } from '../stations/train-call.js';
 import { syncPluginServers } from '../connectors/plugin-sync.js';
@@ -36,7 +39,6 @@ import { blockedReason } from '../connectors/gates.js';
 import {
   setLocalOwner,
   localAttachAccount,
-  localDetachAccount,
   localSetAllowlist,
   localSetPolicy,
   localSetAccountEnabled,
@@ -64,11 +66,14 @@ export interface LocalModeDeps {
 function attachSessions(deps: LocalModeDeps): AttachSessions {
   return new AttachSessions({
     authorize: (owner) => {
-      readLocalAgentFile(owner.agentId);
+      assertAttachOwner(owner);
       return Promise.resolve();
     },
-    complete: async (owner, station, config) => {
-      const ref = await localAttachAccount(owner.agentId, station, config);
+    start: (station, input, hooks, owner) => station === 'gmail' ? startGmailAttach(station, input, hooks, owner) : startInteractiveAttach(station, input, hooks),
+    complete: async (owner, station, config, active) => {
+      assertAttachOwner(owner);
+      if (!active()) throw new ApiError('This sign-in was cancelled or expired.', 409);
+      const ref = (station === 'gmail' ? finishGmailUpgrade(owner, config) : null) ?? await localAttachAccount(owner.agentId, station, config);
       const activated = await deps.syncStations(station).then(
         () => true,
         (err: unknown) => {
@@ -92,10 +97,11 @@ function agentApi(deps: LocalModeDeps): AgentApiDeps {
     capabilities: deps.capabilities,
     ...(deps.toolGroups === undefined ? {} : { toolGroups: deps.toolGroups }),
     attachable: ATTACHABLE.filter((s) => s !== 'webhook'),
+    features: ['gmail-managed'],
     connectorIds: connectorIdsOfLocalAgents,
     prepareAccount: deps.prepareAccount,
     attachAccount: localAttachAccount,
-    detachAccount: localDetachAccount,
+    detachAccount: detachWithGmailRevocation,
     syncStations: deps.syncStations,
     setAllowlist: localSetAllowlist,
     setPolicy: localSetPolicy,
@@ -151,7 +157,7 @@ function bundleApi(deps: LocalModeDeps): BundleApiDeps {
       const file = readLocalAgentFile(agentId);
       const bundle: AgentBundle = {
         version: 1,
-        agent: { id: file.id, name: file.name ?? '', stations: file.stations },
+        agent: { id: file.id, name: file.name ?? '', stations: file.stations.filter((a) => a.station !== 'gmail' || a.config.managed !== true) },
         connectors: readLocalConnectors().map((c) => ({ id: c.id, name: c.name, url: c.url, config: { ...c.config } })),
       };
       return Promise.resolve(bundle);

package/runtime/node_modules/@metro-labs/daemon/src/stations/attach-browser.ts

@@ -34,6 +34,7 @@ function refused(err: unknown, provider: string): StationAttachError {
 }
 
 function browserAttach(login: BrowserLogin, hooks: DriverHooks, how: BrowserAttach): StartedAttach {
+  let cancelled = false;
   const finish = async (input: StepInput): Promise<void> => {
     const state = text(input.state);
     if (state !== login.state) throw new StationAttachError(OTHER_ATTEMPT, 400);
@@ -45,7 +46,8 @@ function browserAttach(login: BrowserLogin, hooks: DriverHooks, how: BrowserAtta
     const code = text(input.code);
     if (code === '') throw new StationAttachError(`${how.provider} did not send a sign-in code back`, 400);
     try {
-      hooks.done(await login.finish(code, state));
+      const outcome = await login.finish(code, state);
+      if (!cancelled) hooks.done(outcome);
     } catch (err) {
       hooks.fail(said(err, `Metro could not finish the ${how.provider} sign-in.`));
     }
@@ -55,7 +57,10 @@ function browserAttach(login: BrowserLogin, hooks: DriverHooks, how: BrowserAtta
     prompt: { step: 'browser', prompt: how.prompt, authorizeUrl: login.authorizeUrl },
     expiresAt: Date.now() + BROWSER_TTL_MS,
     driver: {
-      cancel: () => how.cancel?.() ?? Promise.resolve(),
+      cancel: () => {
+        cancelled = true;
+        return how.cancel?.() ?? Promise.resolve();
+      },
       submit: (input) => (input.mode === 'device' && device !== undefined ? device() : finish(input)),
     },
   };
@@ -94,7 +99,7 @@ export async function startGmail(input: Record<string, unknown>, hooks: DriverHo
   const { GmailBrowserLogin, failureOf } = await import('@metro-labs/gmail/login');
   let login;
   try {
-    login = new GmailBrowserLogin({ clientId: input.clientId, clientSecret: input.clientSecret, mailbox: input.mailbox });
+    login = new GmailBrowserLogin({ clientId: input.clientId, clientSecret: input.clientSecret, mailbox: input.mailbox, sendEnabled: input.sendEnabled === true });
   } catch (err) {
     throw refused(err, 'Google');
   }

package/runtime/node_modules/@metro-labs/daemon/src/stations/attach-driver.ts

@@ -31,7 +31,7 @@ export interface StepInput {
 }
 
 export interface AttachDriver {
-  submit: (input: StepInput) => Promise<void>;
+  submit: (input: StepInput, authorization?: string) => Promise<void>;
   cancel: () => Promise<void>;
 }
 

package/runtime/node_modules/@metro-labs/daemon/src/stations/attach-gmail.ts

@@ -0,0 +1,78 @@
+import { parseMailbox, pkcePair, SignInError } from '@metro-labs/core/stations/oauth';
+import { managedRequest, managedTokens } from '@metro-labs/gmail/managed';
+import { ApiError } from '@metro-labs/http/api-error';
+import { stringOf } from '@metro-labs/http/api-http';
+import type { AttachOwner } from './attach-session.js';
+import type { AttachOutcome, DriverHooks, StartedAttach } from './attach-driver.js';
+
+interface ManagedStart {
+  host: string;
+  owner: AttachOwner;
+  mailbox: unknown;
+  sendEnabled: boolean;
+  check: () => void;
+}
+
+function authorizationOf(owner: AttachOwner): string {
+  if (!owner.userId || !owner.sessionId || !owner.organization || !owner.authorization) throw new ApiError('Sign in to Metro again before connecting Gmail.', 401);
+  return owner.authorization;
+}
+
+function signInLink(started: Record<string, unknown>): { state: string; authorizeUrl: string; expiresAt: number } {
+  const state = stringOf(started.state);
+  const authorizeUrl = stringOf(started.authorizeUrl);
+  const url = new URL(authorizeUrl);
+  const expiresAt = started.expiresAt;
+  if (!state || url.origin !== 'https://accounts.google.com' || url.pathname !== '/o/oauth2/v2/auth' || url.searchParams.get('state') !== state || url.searchParams.get('redirect_uri') !== 'https://metro.box/' || typeof expiresAt !== 'number' || !Number.isFinite(expiresAt) || expiresAt <= Date.now()) throw new SignInError('Metro returned an invalid Gmail sign-in link.');
+  return { state, authorizeUrl, expiresAt };
+}
+
+function outcomeOf(result: Record<string, unknown>, input: ManagedStart, mailbox: string | null): AttachOutcome {
+  const accountEmail = parseMailbox(result.accountEmail);
+  if (accountEmail === null || (mailbox !== null && accountEmail !== mailbox) || result.managed !== true || result.managedHost !== input.host || result.sendEnabled !== input.sendEnabled) throw new SignInError('Metro returned a Gmail connection for a different mailbox or access level.');
+  return { config: { ...managedTokens(result), accountEmail, managed: true, managedHost: input.host, managedOrganization: input.owner.organization, sendEnabled: input.sendEnabled }, identity: { email: accountEmail } };
+}
+
+export async function startManagedGmail(input: ManagedStart, hooks: DriverHooks): Promise<StartedAttach> {
+  const { host, owner, sendEnabled, check } = input;
+  const bearer = authorizationOf(owner);
+  const pair = pkcePair();
+  const mailbox = parseMailbox(input.mailbox);
+  check();
+  const started = await managedRequest('start', { host, agentId: owner.agentId, challenge: pair.challenge, ...(mailbox === null ? {} : { mailbox }), sendEnabled }, bearer);
+  check();
+  const { state, authorizeUrl, expiresAt } = signInLink(started);
+  let cancelled = false;
+  let used = false;
+  return {
+    expiresAt,
+    prompt: { step: 'browser', prompt: sendEnabled ? 'Approve sending for this mailbox on Google. Metro write permissions stay unchanged.' : 'Choose a Google account and approve read-only Gmail access. Metro cannot send mail with this connection.', authorizeUrl },
+    driver: {
+      cancel: async () => {
+        cancelled = true;
+        await managedRequest('cancel', { state, host, agentId: owner.agentId }, bearer);
+      },
+      submit: async (value, authorization) => {
+        if (cancelled || used || Date.now() >= expiresAt) throw new ApiError('This sign-in is finished or expired. Start again.', 409);
+        if (stringOf(value.state) !== state) throw new ApiError('This sign-in belongs to another attempt.', 400);
+        if (!authorization) throw new ApiError('Sign in to Metro again.', 401);
+        used = true;
+        try {
+          if (stringOf(value.error)) {
+            await managedRequest('cancel', { state, host, agentId: owner.agentId }, authorization);
+            hooks.fail('Google sign-in was declined or blocked. Nothing was connected.');
+            return;
+          }
+          const code = stringOf(value.code);
+          if (!code) throw new ApiError('Google did not return a sign-in code.', 400);
+          check();
+          const result = await managedRequest('exchange', { state, code, verifier: pair.verifier, host, agentId: owner.agentId }, authorization);
+          check();
+          if (!cancelled) hooks.done(outcomeOf(result, input, mailbox));
+        } catch {
+          hooks.fail('Metro could not finish this Gmail sign-in. Start again.');
+        }
+      },
+    },
+  };
+}

package/runtime/node_modules/@metro-labs/daemon/src/stations/attach-session.ts

@@ -18,6 +18,7 @@ export type StartAttach = (
   station: InteractiveStation,
   input: Record<string, unknown>,
   hooks: DriverHooks,
+  owner: AttachOwner,
 ) => Promise<StartedAttach>;
 
 export const ATTACH_ID_RE = /^as_[A-Za-z0-9_-]{22}$/;
@@ -30,6 +31,10 @@ const MAX_TOTAL = 40;
 
 export interface AttachOwner {
   agentId: string;
+  organization?: string;
+  userId?: string;
+  sessionId?: string;
+  authorization?: string;
 }
 
 export interface AttachView {
@@ -54,6 +59,7 @@ type CompleteAttach = (
   owner: AttachOwner,
   station: StationName,
   config: Record<string, unknown>,
+  active: () => boolean,
 ) => Promise<{ accountId: string; activated: boolean }>;
 
 type AuthorizeAttach = (owner: AttachOwner) => Promise<void>;
@@ -68,6 +74,8 @@ interface Session {
   owner: AttachOwner;
   driver: AttachDriver | null;
   view: AttachView;
+  finishing?: boolean;
+  committing?: boolean;
 }
 
 const missing = (): ApiError => new ApiError('no such attach session', 404);
@@ -114,7 +122,8 @@ export class AttachSessions {
 
   private own(owner: AttachOwner, attachId: string): Session {
     const session = this.sessions.get(attachId);
-    if (session?.owner.agentId !== owner.agentId) throw missing();
+    if (session === undefined || session.owner.agentId !== owner.agentId || session.owner.organization !== owner.organization || session.owner.userId !== owner.userId || session.owner.sessionId !== owner.sessionId) throw missing();
+    if (session.view.expiresAt <= Date.now()) throw new ApiError('this sign-in expired; start again', 410);
     return session;
   }
 
@@ -153,12 +162,21 @@ export class AttachSessions {
     outcome: AttachOutcome,
   ): Promise<void> {
     const session = this.sessions.get(attachId);
-    if (session?.view.status !== 'pending') return;
+    const active = (): boolean => session !== undefined && this.sessions.get(attachId) === session && session.view.status === 'pending' && session.view.expiresAt > Date.now();
+    if (!active() || session === undefined || session.finishing === true) return;
+    session.finishing = true;
     try {
+      await this.deps.authorize(session.owner);
+      if (!active()) return;
       const landed = await this.deps.complete(
         session.owner,
         station,
         outcome.config,
+        () => {
+          if (!active()) return false;
+          session.committing = true;
+          return true;
+        },
       );
       this.settle(session, {
         status: 'done',
@@ -229,7 +247,12 @@ export class AttachSessions {
         station,
         input,
         this.hooksFor(attachId, station),
+        owner,
       );
+      if (this.sessions.get(attachId) !== session || session.view.expiresAt <= Date.now()) {
+        await started.driver.cancel();
+        throw new ApiError('this sign-in expired or stopped; start again', 410);
+      }
       session.driver = started.driver;
       if (started.expiresAt !== undefined) session.view.expiresAt = started.expiresAt;
       this.hooksFor(attachId, station).prompt(started.prompt);
@@ -257,12 +280,15 @@ export class AttachSessions {
     const driver = session.driver;
     if (session.view.status !== 'pending' || !driver)
       throw new ApiError('this sign-in is already finished', 409);
-    await driver.submit(input);
+    await this.deps.authorize(owner);
+    this.own(owner, attachId);
+    await driver.submit(input, owner.authorization);
     return { ...session.view };
   }
 
   async cancel(owner: AttachOwner, attachId: string): Promise<void> {
     const session = this.own(owner, attachId);
+    if (session.committing === true) throw new ApiError('this sign-in has already been saved', 409);
     this.sessions.delete(attachId);
     await session.driver?.cancel().catch(() => undefined);
     log.info({ attachId }, 'attach-session: cancelled');
@@ -270,7 +296,7 @@ export class AttachSessions {
 
   async sweep(now = Date.now()): Promise<void> {
     for (const [attachId, session] of [...this.sessions]) {
-      if (session.view.expiresAt > now) continue;
+      if (session.view.expiresAt > now || (session.committing === true && session.view.status === 'pending')) continue;
       this.sessions.delete(attachId);
       const driver = session.driver;
       session.driver = null;

package/runtime/node_modules/@metro-labs/gmail/package.json

@@ -6,7 +6,9 @@
   "exports": {
     ".": "./src/station.ts",
     "./train": "./src/index.ts",
-    "./login": "./src/login.ts"
+    "./login": "./src/login.ts",
+    "./managed": "./src/managed.ts",
+    "./managed-binding": "./src/managed-binding.ts"
   },
   "scripts": {
     "build": "tsc",

package/runtime/node_modules/@metro-labs/gmail/src/accounts.ts

@@ -3,13 +3,18 @@ import { threadOfLine } from '@metro-labs/core/stations/mail';
 import { TokenKeeper, type FetchLike } from '@metro-labs/core/stations/oauth';
 import { TrainError } from '@metro-labs/core/train-error';
 import { refreshTokens } from './auth.js';
+import { renewManaged, revokeManaged } from './managed.js';
+import { checkManagedBinding, type ManagedBinding } from './managed-binding.js';
 import { loadState, saveState, type AccountState } from './state.js';
 
-export interface AccountConfig {
+export interface AccountConfig extends ManagedBinding {
   id: string;
   accountEmail: string;
-  clientId: string;
-  clientSecret: string;
+  clientId?: string;
+  clientSecret?: string;
+  refreshGrant?: string;
+  authorizationId?: string;
+  sendEnabled?: boolean;
   refreshToken: string;
   accessToken?: string;
   expiresAt?: number;
@@ -18,9 +23,15 @@ export interface AccountConfig {
 
 const filled = (v: unknown): boolean => typeof v === 'string' && v !== '';
 
+function checkClient(a: AccountConfig, die: Die): void {
+  if (a.managed === true) {
+    if (!filled(a.refreshGrant) || !filled(a.managedHost) || !filled(a.managedOrganization) || !filled(a.authorizationId) || typeof a.sendEnabled !== 'boolean') die(`account '${a.id}' has an incomplete managed sign-in`);
+  } else if (!filled(a.clientId) || !filled(a.clientSecret)) die(`account '${a.id}' has no OAuth client`);
+}
+
 function checkAccount(a: AccountConfig, die: Die): void {
   if (!filled(a.accountEmail) || !a.accountEmail.includes('@')) die(`account '${a.id}' has no mailbox address`);
-  if (!filled(a.clientId) || !filled(a.clientSecret)) die(`account '${a.id}' has no OAuth client`);
+  checkClient(a, die);
   if (!filled(a.refreshToken)) die(`account '${a.id}' has no refresh token`);
 }
 
@@ -39,15 +50,24 @@ export class Account {
   readonly email: string;
   readonly state: AccountState;
   private readonly keeper: TokenKeeper;
+  private readonly pendingTokens = new Set<Promise<string>>();
+  private closing = false;
+  private revoked = false;
 
   constructor(
     readonly cfg: AccountConfig,
     private readonly fetchImpl: FetchLike = (input, init) => fetch(input, init),
   ) {
     this.email = cfg.accountEmail.toLowerCase();
-    this.state = loadState(cfg.id, { refreshToken: cfg.refreshToken, accessToken: cfg.accessToken ?? '', expiresAt: cfg.expiresAt ?? 0 });
-    const client = { clientId: cfg.clientId, clientSecret: cfg.clientSecret };
-    this.keeper = new TokenKeeper(this.state, (refreshToken) => refreshTokens(client, refreshToken, this.fetchImpl).catch(signedOut), () => {
+    this.state = loadState(cfg.id, cfg);
+    const client = { clientId: cfg.clientId ?? '', clientSecret: cfg.clientSecret ?? '' };
+    this.keeper = new TokenKeeper(this.state, async (refreshToken) => {
+      checkManagedBinding(cfg);
+      const tokens = await (cfg.managed === true
+        ? renewManaged(refreshToken, this.state.refreshGrant ?? '', cfg.managedHost ?? '', this.fetchImpl)
+        : refreshTokens(client, refreshToken, this.fetchImpl, Date.now(), cfg.sendEnabled)).catch(signedOut);
+      return tokens;
+    }, () => {
       this.save();
     });
   }
@@ -60,12 +80,44 @@ export class Account {
     saveState(this.cfg.id, this.state);
   }
 
-  token(force = false): Promise<string> {
-    return this.keeper.token(force);
+  check(): void {
+    if (this.closing) throw new TrainError('gmail_disconnecting', 'This Gmail connection is disconnecting.', { retryable: false });
+    checkManagedBinding(this.cfg);
+  }
+
+  async token(force = false): Promise<string> {
+    this.check();
+    const pending = this.keeper.token(force);
+    this.pendingTokens.add(pending);
+    try {
+      const token = await pending;
+      this.check();
+      return token;
+    } finally {
+      this.pendingTokens.delete(pending);
+    }
+  }
+
+  async disconnect(authorizationId: unknown): Promise<void> {
+    if (this.cfg.managed !== true || !authorizationId || authorizationId !== this.cfg.authorizationId) throw new TrainError('gmail_connection_changed', 'This Gmail connection changed. Try deleting again.', { retryable: false });
+    if (this.revoked) return;
+    if (this.closing) throw new TrainError('gmail_disconnecting', 'This Gmail connection is disconnecting.', { retryable: false });
+    this.closing = true;
+    try {
+      await Promise.allSettled([...this.pendingTokens]);
+      await revokeManaged(this.state.refreshToken, this.state.refreshGrant ?? '', this.cfg.managedHost ?? '', this.fetchImpl);
+      this.revoked = true;
+    } catch (err) {
+      this.closing = false;
+      throw err;
+    }
   }
 
-  fetch(input: string, init?: RequestInit): Promise<Response> {
-    return this.fetchImpl(input, init);
+  async fetch(input: string, init?: RequestInit): Promise<Response> {
+    this.check();
+    const result = await this.fetchImpl(input, init);
+    this.check();
+    return result;
   }
 }
 

package/runtime/node_modules/@metro-labs/gmail/src/actions.ts

@@ -1,14 +1,19 @@
 import { makeStation, respond } from '@metro-labs/core/stations/station-runtime';
-import { accounts } from './accounts.js';
+import { accountOf, accounts } from './accounts.js';
 import { MAILBOX_URL } from './config.js';
 import { reply, send } from './outbound.js';
 import { read } from './query.js';
 
 function listAccounts(id: string): void {
-  const list = [...accounts.values()].map((a) => ({ id: a.id, handle: a.email, url: `${MAILBOX_URL}mail/u/${a.email}/`, email: a.email }));
+  const list = [...accounts.values()].map((a) => ({ id: a.id, handle: a.email, url: `${MAILBOX_URL}mail/u/${a.email}/`, email: a.email, managed: a.cfg.managed === true, ...(a.cfg.sendEnabled === undefined ? {} : { sendEnabled: a.cfg.sendEnabled }) }));
   respond(id, { result: { accounts: list } });
 }
 
+async function disconnect(id: string, args: Record<string, unknown>): Promise<void> {
+  await accountOf(args).disconnect(args.authorizationId);
+  respond(id, { result: { revoked: true } });
+}
+
 export const handleCall = makeStation({
-  handlers: { accounts: listAccounts, send, reply, read },
+  handlers: { accounts: listAccounts, send, reply, read, disconnect },
 });

package/runtime/node_modules/@metro-labs/gmail/src/api.ts

@@ -21,11 +21,14 @@ export async function gmail(acct: Account, path: string, init: RequestInit = {})
   if (res.status === 401) res = await call(acct, path, init, true);
   if (res.ok) return res;
   const detail = await googleMessage(res);
+  acct.check();
   throw res.status === 404 && path.startsWith(`${USER}/history`) ? new HistoryGone(detail) : refusalOf(GMAIL, res.status, detail);
 }
 
 export async function gmailJson<T>(acct: Account, path: string, init: RequestInit = {}): Promise<T> {
-  return (await (await gmail(acct, path, init)).json()) as T;
+  const body = (await (await gmail(acct, path, init)).json()) as T;
+  acct.check();
+  return body;
 }
 
 export const queryOf = (params: [string, string][]): string => new URLSearchParams(params).toString();

package/runtime/node_modules/@metro-labs/gmail/src/attachments.ts

@@ -20,7 +20,10 @@ export async function saveFile(acct: Account, messageId: string, file: MailFile,
   if (file.size !== undefined) assertAttachmentSize(file.size);
   const data = file.data ?? (file.attachmentId === null ? null : await attachmentData(acct, messageId, file.attachmentId));
   if (data === null) throw new TrainError('gmail_file_missing', `Gmail gave no content for ${file.name}`, { retryable: false });
-  return saveBufferToCache(new Uint8Array(Buffer.from(data, 'base64url')), messageId, index, { mime: file.mime, name: file.name });
+  acct.check();
+  const saved = await saveBufferToCache(new Uint8Array(Buffer.from(data, 'base64url')), messageId, index, { mime: file.mime, name: file.name });
+  acct.check();
+  return saved;
 }
 
 export async function assertSendable(files: OutgoingFile[]): Promise<void> {

package/runtime/node_modules/@metro-labs/gmail/src/auth.ts

@@ -1,5 +1,12 @@
 import { postForm, SignInError, tokensOf, type FetchLike, type OAuthBody, type Tokens } from '@metro-labs/core/stations/oauth';
-import { apiBase, authorizeBase, redirectUri, SCOPES, tokenUrl } from './config.js';
+import { apiBase, authorizeBase, redirectUri, scopesFor, tokenUrl } from './config.js';
+
+export function checkScopes(scope: unknown, sendEnabled: boolean): void {
+  const granted = typeof scope === 'string' ? scope.split(/\s+/).filter(Boolean) : [];
+  const wanted = scopesFor(sendEnabled).split(' ');
+  if (wanted.some((s) => !granted.includes(s)) || granted.some((s) => !wanted.includes(s)))
+    throw new SignInError('Google did not grant exactly the requested Gmail access. Review this app in your Google Account, then connect again.');
+}
 
 export interface GmailClient {
   clientId: string;
@@ -30,13 +37,14 @@ export function failureOf(body: OAuthBody): string {
   return detail === '' ? `Google refused the sign-in (${error === '' ? 'no reason given' : error}).` : `Google refused the sign-in: ${detail}`;
 }
 
-export function authorizeUrl(client: GmailClient, challenge: string, state: string, loginHint: string | null): string {
+export function authorizeUrl(client: GmailClient, challenge: string, state: string, loginHint: string | null, sendEnabled = false): string {
   const query = new URLSearchParams({
     ...(loginHint === null ? {} : { login_hint: loginHint }),
     client_id: client.clientId,
     redirect_uri: redirectUri(),
     response_type: 'code',
-    scope: SCOPES,
+    scope: scopesFor(sendEnabled),
+    ...(sendEnabled ? { include_granted_scopes: 'true' } : {}),
     state,
     code_challenge: challenge,
     code_challenge_method: 'S256',
@@ -49,7 +57,7 @@ export function authorizeUrl(client: GmailClient, challenge: string, state: stri
 const post = (fields: Record<string, string>, fetchImpl: FetchLike): Promise<{ status: number; body: OAuthBody }> =>
   postForm(tokenUrl(), fields, fetchImpl, 'Google');
 
-export async function redeemCode(client: GmailClient, code: string, verifier: string, fetchImpl: FetchLike, now = Date.now()): Promise<Tokens> {
+export async function redeemCode(client: GmailClient, code: string, verifier: string, fetchImpl: FetchLike, now = Date.now(), sendEnabled = false): Promise<Tokens> {
   const { status, body } = await post(
     {
       grant_type: 'authorization_code',
@@ -62,15 +70,17 @@ export async function redeemCode(client: GmailClient, code: string, verifier: st
     fetchImpl,
   );
   if (status !== 200) throw new SignInError(failureOf(body));
+  checkScopes(body.scope, sendEnabled);
   return tokensOf(body, now, 'Google');
 }
 
-export async function refreshTokens(client: GmailClient, refreshToken: string, fetchImpl: FetchLike, now = Date.now()): Promise<Tokens> {
+export async function refreshTokens(client: GmailClient, refreshToken: string, fetchImpl: FetchLike, now = Date.now(), sendEnabled?: boolean): Promise<Tokens> {
   const { status, body } = await post(
     { grant_type: 'refresh_token', refresh_token: refreshToken, client_id: client.clientId, client_secret: client.clientSecret },
     fetchImpl,
   );
   if (status !== 200) throw new SignInError(`Google refused to renew this mailbox's sign-in, so connect Gmail again. ${failureOf(body)}`);
+  if (sendEnabled !== undefined) checkScopes(body.scope, sendEnabled);
   return tokensOf(body, now, 'Google', refreshToken);
 }
 

package/runtime/node_modules/@metro-labs/gmail/src/config.ts

@@ -1,6 +1,8 @@
 import { envUrl, envValue } from '@metro-labs/core/stations/oauth';
 
-export const SCOPES = ['https://www.googleapis.com/auth/gmail.readonly', 'https://www.googleapis.com/auth/gmail.send'].join(' ');
+export const READ_SCOPE = 'https://www.googleapis.com/auth/gmail.readonly';
+export const SEND_SCOPE = 'https://www.googleapis.com/auth/gmail.send';
+export const scopesFor = (sendEnabled = false): string => [READ_SCOPE, ...(sendEnabled ? [SEND_SCOPE] : [])].join(' ');
 
 export const MAILBOX_URL = 'https://mail.google.com/';
 

package/runtime/node_modules/@metro-labs/gmail/src/inbound.ts

@@ -46,6 +46,7 @@ async function deliver(acct: Account, messageId: string): Promise<boolean> {
   }
   const files = mailFilesOf(m);
   const env = mailEnvelope('gmail', acct.id, acct.email, item, files.map(metaOf), verdict.verified);
+  acct.check();
   emitInbound(acct.id, env);
   const at = { station: 'gmail', account: acct.id, line: String(env.line), forId: String(env.id) };
   for (const [index, file] of files.entries())

package/runtime/node_modules/@metro-labs/gmail/src/login.ts

@@ -12,6 +12,7 @@ export interface GmailLoginDeps {
   clientId?: unknown;
   clientSecret?: unknown;
   mailbox?: unknown;
+  sendEnabled?: boolean;
   fetch?: FetchLike;
   now?: () => number;
 }
@@ -22,13 +23,14 @@ export class GmailBrowserLogin extends BrowserSignIn<GmailLoginResult> {
     const mailbox = parseMailbox(deps.mailbox);
     const fetchImpl: FetchLike = deps.fetch ?? ((input, init) => fetch(input, init));
     const now = deps.now ?? Date.now;
+    const sendEnabled = deps.sendEnabled === true;
     super({
-      authorize: (challenge, state) => authorizeUrl(client, challenge, state, mailbox),
+      authorize: (challenge, state) => authorizeUrl(client, challenge, state, mailbox, sendEnabled),
       redeem: async (code, verifier) => {
-        const tokens = await redeemCode(client, code, verifier, fetchImpl, now());
+        const tokens = await redeemCode(client, code, verifier, fetchImpl, now(), sendEnabled);
         const email = await verifyMailbox(tokens.accessToken, fetchImpl, mailbox);
         return {
-          config: { accountEmail: email, ...client, ...tokens, createdAt: new Date(now()).toISOString() },
+          config: { accountEmail: email, ...client, ...tokens, sendEnabled, createdAt: new Date(now()).toISOString() },
           identity: { email },
         };
       },

package/runtime/node_modules/@metro-labs/gmail/src/managed-binding.ts

@@ -0,0 +1,33 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { ensureSecureDir, writeSecure } from '@metro-labs/core/secure-fs';
+import { TrainError } from '@metro-labs/core/train-error';
+
+export interface ManagedBinding {
+  managed?: boolean;
+  managedOrganization?: string;
+  managedHost?: string;
+}
+
+const bindingDir = (): string => process.env.METRO_AGENTS_DIR ?? join(homedir(), '.metro', 'agents');
+
+export function setManagedHost(url: string | null): void {
+  const dir = bindingDir();
+  ensureSecureDir(dir);
+  writeSecure(join(dir, '.gmail-host'), url === null ? '' : new URL(url).host);
+}
+
+export function checkManagedBinding(config: ManagedBinding): void {
+  if (config.managed !== true) return;
+  let owner = '';
+  let host = '';
+  try {
+    owner = readFileSync(join(bindingDir(), '.owner'), 'utf8').trim();
+    host = readFileSync(join(bindingDir(), '.gmail-host'), 'utf8').trim();
+  } catch {
+    throw new TrainError('gmail_binding_changed', 'Reconnect managed Gmail on this box before using it.', { retryable: false });
+  }
+  if (!owner || owner !== config.managedOrganization || !host || host !== config.managedHost)
+    throw new TrainError('gmail_binding_changed', 'This box changed owner or address. Reconnect managed Gmail before using it.', { retryable: false });
+}

package/runtime/node_modules/@metro-labs/gmail/src/managed.ts

@@ -0,0 +1,45 @@
+import { SignInError, type FetchLike, type Tokens } from '@metro-labs/core/stations/oauth';
+
+const BASE = 'https://api.metro.box/api/gmail';
+const reach: FetchLike = (input, init) => fetch(input, init);
+
+export interface ManagedTokens extends Tokens {
+  refreshGrant: string;
+}
+
+export async function managedRequest(path: 'start' | 'exchange' | 'cancel' | 'refresh' | 'revoke', body: Record<string, unknown>, bearer?: string, fetchImpl = reach): Promise<Record<string, unknown>> {
+  let response: Response;
+  try {
+    response = await fetchImpl(`${BASE}/${path}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', ...(bearer === undefined ? {} : { authorization: bearer }) },
+      body: JSON.stringify(body),
+      redirect: 'error',
+      signal: AbortSignal.timeout(25_000),
+    });
+  } catch {
+    throw new SignInError('Metro could not reach managed Gmail sign-in. Try again.');
+  }
+  if (!response.ok) {
+    const retry = response.status >= 500 ? 'Try again later.' : 'Start Gmail sign-in again. Your Google Workspace administrator may need to allow the app.';
+    throw new SignInError(`Metro could not complete managed Gmail sign-in. ${retry}`);
+  }
+  const value: unknown = await response.json().catch(() => null);
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) throw new SignInError('Metro returned an invalid Gmail answer.');
+  return value as Record<string, unknown>;
+}
+
+export function managedTokens(value: Record<string, unknown>): ManagedTokens {
+  if (typeof value.accessToken !== 'string' || !value.accessToken || typeof value.refreshToken !== 'string' || !value.refreshToken || typeof value.refreshGrant !== 'string' || !value.refreshGrant || typeof value.expiresAt !== 'number' || !Number.isFinite(value.expiresAt))
+    throw new SignInError('Metro returned an incomplete Gmail sign-in.');
+  return { accessToken: value.accessToken, refreshToken: value.refreshToken, refreshGrant: value.refreshGrant, expiresAt: value.expiresAt };
+}
+
+export async function renewManaged(refreshToken: string, refreshGrant: string, host: string, fetchImpl = reach): Promise<ManagedTokens> {
+  return managedTokens(await managedRequest('refresh', { refreshToken, refreshGrant, host }, undefined, fetchImpl));
+}
+
+export async function revokeManaged(refreshToken: string, refreshGrant: string, host: string, fetchImpl = reach): Promise<void> {
+  const result = await managedRequest('revoke', { refreshToken, refreshGrant, host }, undefined, fetchImpl);
+  if (result.revoked !== true) throw new SignInError('Metro did not confirm Google revocation. Try again.');
+}

package/runtime/node_modules/@metro-labs/gmail/src/outbound.ts

@@ -74,6 +74,7 @@ async function outgoing(args: Args): Promise<Outgoing> {
   const parsed = threadOfLine('gmail', line);
   if (parsed === null) throw new TrainError('gmail_bad_line', `not a valid gmail line: ${line}`, { retryable: false });
   const acct = accountOf(args);
+  if (acct.cfg.sendEnabled === false) throw new TrainError('gmail_read_only', 'This Gmail connection is read-only. Allow sending with Google in channel settings, then choose a Metro write policy.', { retryable: false });
   const files = filesOf(args.attachments);
   const text = typeof args.text === 'string' ? args.text : '';
   if (text.trim() === '' && files.length === 0) throw new TrainError('gmail_text_required', 'give some text or a file to send', { retryable: false });

package/runtime/node_modules/@metro-labs/gmail/src/query.ts

@@ -69,6 +69,7 @@ async function searched(acct: Account, q: ReadQuery, beforeAt: string): Promise<
 async function list(id: string, acct: Account, q: ReadQuery): Promise<void> {
   const beforeAt = await receivedAt(acct, q.before);
   const found = q.threadId !== null && q.query === '' ? await inThread(acct, q, q.threadId, beforeAt) : await searched(acct, q, beforeAt);
+  acct.check();
   respond(id, {
     result: {
       account: acct.id,
@@ -85,6 +86,7 @@ async function one(id: string, acct: Account, messageId: string): Promise<void>
     const saved = await saveFile(acct, m.id, file, index);
     attachments.push({ name: file.name, mime: file.mime, kind: file.kind, size: saved.bytes, local_path: saved.path });
   }
+  acct.check();
   respond(id, { result: { account: acct.id, message: { ...mailFull('gmail', acct.id, itemOf(m)), attachments } } });
 }
 

package/runtime/node_modules/@metro-labs/gmail/src/state.ts

@@ -4,16 +4,22 @@ import { seenOf } from '@metro-labs/core/stations/mail';
 import { tokenStateOf, type Tokens } from '@metro-labs/core/stations/oauth';
 
 export interface AccountState extends Tokens {
+  refreshGrant?: string;
+  authorizationId?: string;
   historyId: string | null;
   seen: string[];
 }
 
 export const stateFiles = accountFiles('GMAIL_STATE_DIR', 'gmail-state-');
 
-export function loadState(accountId: string, seed: Partial<Tokens>): AccountState {
+export function loadState(accountId: string, seed: Partial<AccountState>): AccountState {
   const saved = readJson<Record<string, unknown>>(stateFiles.path(accountId), {});
+  const same = saved.authorizationId === seed.authorizationId;
+  const held = same ? saved : {};
   return {
-    ...tokenStateOf(saved, seed),
+    ...tokenStateOf(held, seed),
+    refreshGrant: typeof held.refreshGrant === 'string' ? held.refreshGrant : seed.refreshGrant,
+    authorizationId: seed.authorizationId,
     historyId: typeof saved.historyId === 'string' && saved.historyId !== '' ? saved.historyId : null,
     seen: seenOf(saved.seen),
   };

package/runtime/node_modules/@metro-labs/http/src/api-http.ts

@@ -8,6 +8,8 @@ export type Role = 'admin' | 'member';
 
 export interface ApiSession {
   subject: string;
+  userId?: string;
+  sessionId?: string;
   role: Role;
   operator?: true;
 }

package/runtime/runtime.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.1.0-beta.271"
+  "version": "0.1.0-beta.273"
 }

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/tickets.ts

@@ -2,6 +2,7 @@ import { randomBytes } from 'node:crypto';
 
 export interface TicketStore<T> {
   mint: (value: T, now?: number) => { ticket: string; expiresAt: number };
+  peek: (ticket: string, now?: number) => T | undefined;
   take: (ticket: string, now?: number) => T | undefined;
   size: (now?: number) => number;
 }
@@ -24,6 +25,12 @@ export function ticketStore<T>(ttlMs: number, max: number): TicketStore<T> {
       open.set(ticket, { value, expiresAt });
       return { ticket, expiresAt };
     },
+    peek(ticket, now = Date.now()) {
+      const entry = open.get(ticket);
+      if (entry !== undefined && entry.expiresAt > now) return entry.value;
+      open.delete(ticket);
+      return undefined;
+    },
     take(ticket, now = Date.now()) {
       const entry = open.get(ticket);
       open.delete(ticket);

package/runtime/sdk-runner/runner.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.0-beta.271",
+  "version": "0.1.0-beta.273",
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.3.287",
     "@modelcontextprotocol/sdk": "^1.29.0",