@stage-labs/metro 0.1.0-beta.26 → 0.1.0-beta.261

package/runtime/node_modules/@metro-labs/daemon/src/connectors/relay-policy.ts

@@ -0,0 +1,90 @@
+import type { ServerResponse } from 'node:http';
+import { isRecord } from '@metro-labs/core/is-record';
+import { log } from '@metro-labs/core/log';
+
+export type BlockedReason = (connectorId: string, tool: string, args: Record<string, unknown>) => string | null;
+
+export interface Screened {
+  forward: Uint8Array<ArrayBuffer> | null;
+  answers: Record<string, unknown>[];
+  batch: boolean;
+}
+
+const encoder = new TextEncoder();
+
+function parsed(body: Uint8Array): unknown {
+  try {
+    return JSON.parse(new TextDecoder().decode(body));
+  } catch {
+    return undefined;
+  }
+}
+
+function toolOf(message: unknown): string | null {
+  if (!isRecord(message) || message.method !== 'tools/call' || !isRecord(message.params)) return null;
+  const name = message.params.name;
+  return typeof name === 'string' ? name : null;
+}
+
+function blockedAnswer(message: Record<string, unknown>, reason: string): Record<string, unknown> | null {
+  if (!('id' in message)) return null;
+  return { jsonrpc: '2.0', id: message.id, result: { isError: true, content: [{ type: 'text', text: reason }] } };
+}
+
+function argsOf(message: unknown): Record<string, unknown> {
+  if (!isRecord(message) || !isRecord(message.params)) return {};
+  return isRecord(message.params.arguments) ? message.params.arguments : {};
+}
+
+function reasonFor(message: unknown, connectorId: string, blocked: BlockedReason): string | null {
+  const tool = toolOf(message);
+  return tool === null ? null : blocked(connectorId, tool, argsOf(message));
+}
+
+export function screenCalls(body: Uint8Array<ArrayBuffer>, connectorId: string, blocked: BlockedReason): Screened | null {
+  const message = parsed(body);
+  const batch = Array.isArray(message);
+  const list: unknown[] = batch ? message : [message];
+  const answers: Record<string, unknown>[] = [];
+  const kept: unknown[] = [];
+  for (const item of list) {
+    const reason = reasonFor(item, connectorId, blocked);
+    if (reason === null || !isRecord(item)) {
+      kept.push(item);
+      continue;
+    }
+    log.info({ connector: connectorId, tool: toolOf(item) }, 'relay: a call the owner blocked was answered without the connector');
+    const answer = blockedAnswer(item, reason);
+    if (answer !== null) answers.push(answer);
+  }
+  if (kept.length === list.length) return null;
+  const forward = kept.length === 0 ? null : new Uint8Array(encoder.encode(JSON.stringify(kept)));
+  return { forward, answers, batch };
+}
+
+export function answerBlocked(res: ServerResponse, screened: Screened): void {
+  if (res.headersSent) return;
+  if (screened.answers.length === 0) {
+    res.writeHead(202).end();
+    return;
+  }
+  const body = screened.batch ? screened.answers : screened.answers[0];
+  res.writeHead(200, { 'content-type': 'application/json' });
+  res.end(JSON.stringify(body));
+}
+
+const sseFrames = (answers: Record<string, unknown>[]): string =>
+  answers.map((answer) => `event: message\ndata: ${JSON.stringify(answer)}\n\n`).join('');
+
+export async function mergeBlocked(res: ServerResponse, upstream: Response, headers: Record<string, string>, answers: Record<string, unknown>[]): Promise<void> {
+  const text = await upstream.text();
+  if ((headers['content-type'] ?? '').includes('text/event-stream')) {
+    res.writeHead(upstream.status, headers);
+    res.end(`${text}${sseFrames(answers)}`);
+    return;
+  }
+  const theirs = text.trim() === '' ? [] : parsed(encoder.encode(text));
+  const list: unknown[] = Array.isArray(theirs) ? theirs : theirs === undefined || theirs === null ? [] : [theirs];
+  res.writeHead(200, { ...headers, 'content-type': 'application/json' });
+  res.end(JSON.stringify([...list, ...answers]));
+}

package/runtime/node_modules/@metro-labs/{mcp/src/daemon → daemon/src/connectors}/relay.ts

@@ -1,15 +1,16 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import type { RelayTarget } from '../db/connector-relay.js';
-import { cliIdentity } from './api-http.js';
-import { ApiError } from './api-error.js';
-import { errMsg, log } from './log.js';
+import { whyUnreachable } from './reach.js';
+import { noteHealth } from './health.js';
+import type { RelayTarget } from './store.js';
+import { ApiError } from '@metro-labs/http/api-error';
+import { errMsg, log } from '@metro-labs/core/log';
+import { answerBlocked, mergeBlocked, screenCalls, type BlockedReason } from './relay-policy.js';
 
 export interface RelayApiDeps {
-  target: (
-    collectionId: string,
-    connectorId: string,
-    force: boolean,
-  ) => Promise<RelayTarget>;
+  target: (connectorId: string, force: boolean) => Promise<RelayTarget>;
+  identify: (req: IncomingMessage) => { subject: string; agentId: string } | null;
+  signedOut: (connectorId: string) => void;
+  blocked?: BlockedReason;
 }
 
 const ID_PATH_RE = /^\/relay\/([A-Za-z0-9][A-Za-z0-9_-]{10})$/;
@@ -146,6 +147,18 @@ function startKeepalive(res: ServerResponse): Keepalive {
   };
 }
 
+function drainedOrClosed(res: ServerResponse): Promise<void> {
+  return new Promise((resolve) => {
+    const done = (): void => {
+      res.off('drain', done);
+      res.off('close', done);
+      resolve();
+    };
+    res.once('drain', done);
+    res.once('close', done);
+  });
+}
+
 async function pumpBody(
   res: ServerResponse,
   body: ReadableStream<Uint8Array>,
@@ -156,20 +169,25 @@ async function pumpBody(
     const { done, value } = await reader.read();
     if (done) return;
     touch();
-    const ok = res.write(value);
-    if (!ok)
-      await new Promise((resolve) => {
-        res.once('drain', resolve);
-      });
+    if (!res.write(value)) await drainedOrClosed(res);
   }
 }
 
-async function pipe(res: ServerResponse, upstream: Response): Promise<void> {
+function passedHeaders(upstream: Response): Record<string, string> {
   const headers: Record<string, string> = {};
   for (const name of PASS_RES) {
     const value = upstream.headers.get(name);
     if (value !== null) headers[name] = value;
   }
+  return headers;
+}
+
+async function pipe(res: ServerResponse, upstream: Response, answers: Record<string, unknown>[]): Promise<void> {
+  const headers = passedHeaders(upstream);
+  if (answers.length > 0 && (upstream.status === 200 || upstream.status === 202)) {
+    await mergeBlocked(res, upstream, headers, answers);
+    return;
+  }
   const sse = (headers['content-type'] ?? '').includes('text/event-stream');
   if (sse) headers['x-accel-buffering'] = 'no';
   res.writeHead(upstream.status, headers);
@@ -196,18 +214,17 @@ type Exchanged =
 
 async function exchange(
   req: IncomingMessage,
-  collectionId: string,
   connectorId: string,
   deps: RelayApiDeps,
   body: Uint8Array<ArrayBuffer> | null,
   signal: AbortSignal,
 ): Promise<Exchanged> {
-  const target = await deps.target(collectionId, connectorId, false);
+  const target = await deps.target(connectorId, false);
   if (target.kind !== 'ok') return { kind: target.kind };
   let upstream = await forward(req, target, body, signal);
   if (!authFailed(upstream.status)) return { kind: 'response', upstream };
   await upstream.body?.cancel();
-  const fresh = await deps.target(collectionId, connectorId, true);
+  const fresh = await deps.target(connectorId, true);
   if (fresh.kind !== 'ok') return { kind: 'signin' };
   upstream = await forward(req, fresh, body, signal);
   if (!authFailed(upstream.status)) return { kind: 'response', upstream };
@@ -218,7 +235,6 @@ async function exchange(
 async function relayExchange(
   req: IncomingMessage,
   res: ServerResponse,
-  collectionId: string,
   connectorId: string,
   deps: RelayApiDeps,
 ): Promise<void> {
@@ -231,29 +247,58 @@ async function relayExchange(
   res.once('finish', () => {
     res.socket?.removeListener('close', bail);
   });
-  const body = req.method === 'POST' ? await readCapped(req) : null;
-  const out = await exchange(
-    req,
-    collectionId,
-    connectorId,
-    deps,
-    body,
-    control.signal,
-  );
+  try {
+    await relayOnce(req, res, connectorId, deps, control.signal);
+  } catch (err) {
+    if (!control.signal.aborted) throw err;
+    log.debug({ connector: connectorId }, 'relay: the client left before the answer ended');
+    if (!res.writableEnded) res.end();
+  }
+}
+
+async function deliver(
+  res: ServerResponse,
+  connectorId: string,
+  deps: RelayApiDeps,
+  out: Exchanged,
+  answers: Record<string, unknown>[],
+): Promise<void> {
   if (out.kind === 'missing') {
     answer(res, 404, { error: 'no such connector' });
     return;
   }
   if (out.kind === 'signin') {
+    noteHealth(connectorId, false, 'the sign-in has expired, connect it again');
+    deps.signedOut(connectorId);
     signinAnswer(res, connectorId);
     return;
   }
   if (out.upstream.status >= 300 && out.upstream.status < 400) {
     await out.upstream.body?.cancel();
+    noteHealth(connectorId, false, 'the connector redirected; metro does not follow');
     answer(res, 502, { error: 'the connector redirected; metro does not follow' });
     return;
   }
-  await pipe(res, out.upstream);
+  const { status } = out.upstream;
+  noteHealth(connectorId, status < 400, status < 400 ? null : `the connector answered ${String(status)}`);
+  await pipe(res, out.upstream, answers);
+}
+
+async function relayOnce(
+  req: IncomingMessage,
+  res: ServerResponse,
+  connectorId: string,
+  deps: RelayApiDeps,
+  signal: AbortSignal,
+): Promise<void> {
+  const read = req.method === 'POST' ? await readCapped(req) : null;
+  const screened = read === null || deps.blocked === undefined ? null : screenCalls(read, connectorId, deps.blocked);
+  if (screened?.forward === null) {
+    answerBlocked(res, screened);
+    return;
+  }
+  const out = await exchange(req, connectorId, deps, screened === null ? read : screened.forward, signal);
+  await deliver(res, connectorId, deps, out, screened?.answers ?? []);
 }
 
 function dispatch(
@@ -262,23 +307,23 @@ function dispatch(
   connectorId: string,
   deps: RelayApiDeps,
 ): void {
-  const who = cliIdentity(req);
+  const who = deps.identify(req);
   if (who === null) {
     answer(res, 401, { error: 'unauthorized' });
     return;
   }
-  relayExchange(req, res, who.collectionId, connectorId, deps).catch(
-    (err: unknown) => {
+  relayExchange(req, res, connectorId, deps)
+    .catch((err: unknown) => {
       if (err instanceof ApiError) {
         answer(res, err.status, { error: err.message });
       } else {
         log.warn({ err: errMsg(err), connector: connectorId }, 'relay: failed');
-        answer(res, 502, { error: 'metro could not reach the connector' });
+        noteHealth(connectorId, false, `metro could not reach the connector: ${whyUnreachable(err)}`);
+        answer(res, 502, { error: `metro could not reach the connector: ${whyUnreachable(err)}` });
         if (!res.writableEnded) res.end();
       }
       closeIfBodyUnread(req, res);
-    },
-  );
+    });
 }
 
 export function handleRelayRequest(

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

@@ -0,0 +1,385 @@
+import { join } from 'node:path';
+import { syncPluginServers } from './plugin-sync.js';
+import { registerConnectors } from './gates.js';
+import type { ToolPolicy } from '../policy/policy.js';
+import type { ToolGroup } from '@metro-labs/core/stations/types';
+import { listRemoteTools, type RemoteTool } from './tools.js';
+import { readJson, writeSecure } from '@metro-labs/core/secure-fs';
+import { errMsg, log } from '@metro-labs/core/log';
+import {
+  authHeaders,
+  connectorUrlText,
+  ConnectorVerifyError,
+  parseConnectorUrl,
+  verifyRemoteMcp,
+  type ConnectorAuth,
+  type OAuthAuth,
+  type VerifiedRecord,
+} from './verify.js';
+import { oauthExpired, refreshOAuth } from './oauth.js';
+import { advertisesOAuth } from './oauth-discovery.js';
+import {
+  ConnectorError,
+  connectorAuth,
+  connectorClient,
+  connectorName,
+  readConfig,
+  signInState,
+  stamp,
+  type ConnectorConfig,
+  type ConnectorSignIn,
+} from './config.js';
+import type { OAuthClient } from './oauth-client.js';
+import { agentsDir } from '../agents/files.js';
+import { newId } from '@metro-labs/core/ids';
+import type { LoadedConnector } from '../stations/materialize.js';
+
+export interface LocalConnectorRow {
+  id: string;
+  name: string;
+  url: string;
+  config: ConnectorConfig;
+}
+
+export interface Connector {
+  id: string;
+  name: string;
+  url: string;
+  auth: ConnectorAuth['kind'];
+  header: string | null;
+  signIn: ConnectorSignIn;
+  verified: VerifiedRecord;
+  client: OAuthClient | null;
+  policy: ToolPolicy;
+}
+
+export interface PendingConnectorInput {
+  name: unknown;
+  url: unknown;
+  clientId: unknown;
+  clientSecret: unknown;
+}
+
+export interface ConnectorInput extends PendingConnectorInput {
+  header: unknown;
+  value: unknown;
+}
+
+export type ConnectorCheck =
+  | { id: string; name: string; ok: true; verified: VerifiedRecord }
+  | { id: string; name: string; ok: false; reason: string };
+
+export interface DeletedConnector {
+  id: string;
+  name: string;
+}
+
+const UNVERIFIED = { at: '', server: '' };
+
+function connectorFromRow(row: LocalConnectorRow): Connector {
+  const auth = row.config.auth;
+  return {
+    id: row.id,
+    name: row.name,
+    url: row.url,
+    auth: auth.kind,
+    header: auth.kind === 'header' ? auth.name : null,
+    signIn: signInState(row.config),
+    verified: row.config.verified,
+    client: row.config.client,
+    policy: row.config.policy ?? {},
+  };
+}
+
+const FILE = 'connectors.json';
+const filePath = (dir: string): string => join(dir, FILE);
+
+const isRow = (v: unknown): v is { id: string; name: string; url: string; config?: unknown } =>
+  typeof v === 'object' &&
+  v !== null &&
+  typeof (v as { id?: unknown }).id === 'string' &&
+  typeof (v as { name?: unknown }).name === 'string' &&
+  typeof (v as { url?: unknown }).url === 'string';
+
+const asList = (value: unknown): unknown[] =>
+  Array.isArray(value) ? value.map((item: unknown) => item) : [];
+
+export function readLocalConnectors(dir = agentsDir()): LocalConnectorRow[] {
+  const raw = readJson<{ connectors?: unknown }>(filePath(dir), {}, {
+    warn: 'connectors.json: malformed, ignoring',
+  });
+  return asList(raw.connectors).filter(isRow).map((r) => ({
+    id: r.id,
+    name: r.name,
+    url: r.url,
+    config: readConfig(r.config),
+  }));
+}
+
+function writeRows(dir: string, rows: LocalConnectorRow[]): void {
+  writeSecure(filePath(dir), `${JSON.stringify({ version: 1, connectors: rows }, null, 2)}\n`);
+  if (dir !== agentsDir()) return;
+  syncPluginServers(rows);
+  registerConnectors(rows);
+}
+
+const missing = (): ConnectorError => new ConnectorError('no such connector', 404);
+
+function rowOrThrow(id: string, dir: string): LocalConnectorRow {
+  const row = readLocalConnectors(dir).find((r) => r.id === id);
+  if (row === undefined) throw missing();
+  return row;
+}
+
+function replace(dir: string, row: LocalConnectorRow): Connector {
+  writeRows(dir, readLocalConnectors(dir).map((r) => (r.id === row.id ? row : r)));
+  return connectorFromRow(row);
+}
+
+async function oauthCapable(url: URL, auth: ConnectorAuth): Promise<boolean> {
+  if (auth.kind === 'oauth') return true;
+  if (auth.kind === 'header') return false;
+  return advertisesOAuth(url);
+}
+
+export function localImportConnectors(
+  rows: LoadedConnector[],
+  dir = agentsDir(),
+  mode: 'append' | 'overwrite' = 'overwrite',
+): number {
+  const current = readLocalConnectors(dir);
+  const fresh =
+    mode === 'overwrite'
+      ? rows
+      : rows.filter((row) => !current.some((r) => r.id === row.id || r.name === row.name));
+  const imported: LocalConnectorRow[] = fresh.map((row) => ({
+    id: row.id,
+    name: row.name,
+    url: row.url,
+    config: readConfig(row.config),
+  }));
+  const ids = new Set(imported.map((r) => r.id));
+  const names = new Set(imported.map((r) => r.name));
+  writeRows(dir, [...current.filter((r) => !ids.has(r.id) && !names.has(r.name)), ...imported]);
+  return imported.length;
+}
+
+export async function localListConnectors(dir = agentsDir()): Promise<Connector[]> {
+  return Promise.resolve(readLocalConnectors(dir).map(connectorFromRow));
+}
+
+export async function localGetConnector(id: string, dir = agentsDir()): Promise<Connector> {
+  return Promise.resolve(connectorFromRow(rowOrThrow(id, dir)));
+}
+
+function assertNameFree(name: string, exceptId: string | null, dir: string): void {
+  if (readLocalConnectors(dir).some((r) => r.id !== exceptId && r.name === name))
+    throw new ConnectorError(`a connector named '${name}' already exists on this daemon`, 409);
+}
+
+function insert(dir: string, name: string, url: URL, config: ConnectorConfig): Connector {
+  assertNameFree(name, null, dir);
+  const row: LocalConnectorRow = { id: newId(), name, url: connectorUrlText(url), config };
+  writeRows(dir, [...readLocalConnectors(dir), row]);
+  return connectorFromRow(row);
+}
+
+export async function localCreateConnector(input: ConnectorInput, dir = agentsDir()): Promise<Connector> {
+  const name = connectorName(input.name);
+  const url = parseConnectorUrl(input.url);
+  const auth = connectorAuth(input.header, input.value);
+  const client = connectorClient(input.clientId, input.clientSecret);
+  const verified = stamp(await verifyRemoteMcp(url, auth));
+  return insert(dir, name, url, {
+    auth,
+    createdAt: new Date().toISOString(),
+    verified,
+    oauth: await oauthCapable(url, auth),
+    client,
+  });
+}
+
+export async function localCreatePendingConnector(input: PendingConnectorInput, dir = agentsDir()): Promise<Connector> {
+  const name = connectorName(input.name);
+  const url = parseConnectorUrl(input.url);
+  const client = connectorClient(input.clientId, input.clientSecret);
+  return Promise.resolve(
+    insert(dir, name, url, { auth: { kind: 'none' }, createdAt: new Date().toISOString(), verified: UNVERIFIED, oauth: true, client }),
+  );
+}
+
+export async function localReconnectConnector(
+  id: string,
+  auth: OAuthAuth,
+  dir = agentsDir(),
+): Promise<Connector> {
+  const row = rowOrThrow(id, dir);
+  const verified = stamp(await verifyRemoteMcp(parseConnectorUrl(row.url), auth));
+  return replace(dir, { ...row, config: { ...row.config, auth, verified, oauth: true } });
+}
+
+const signedOut = (row: LocalConnectorRow): LocalConnectorRow => ({ ...row, config: { ...row.config, auth: { kind: 'none' }, oauth: true } });
+
+export async function localDisconnectConnector(id: string, dir = agentsDir()): Promise<Connector> {
+  const row = rowOrThrow(id, dir);
+  if (row.config.auth.kind !== 'oauth') throw new ConnectorError('that connector is not signed in', 400);
+  return Promise.resolve(replace(dir, signedOut(row)));
+}
+
+export function localMarkSignedOut(id: string, dir = agentsDir()): void {
+  const row = readLocalConnectors(dir).find((r) => r.id === id);
+  if (row?.config.auth.kind !== 'oauth') return;
+  log.info({ id, name: row.name }, 'local relay: the vendor refused the token after a refresh; the connector is signed out');
+  replace(dir, signedOut(row));
+}
+
+async function freshAuth(row: LocalConnectorRow, dir: string): Promise<ConnectorAuth> {
+  const auth = row.config.auth;
+  if (auth.kind !== 'oauth' || !oauthExpired(auth)) return auth;
+  return refreshOnce(row, auth, dir);
+}
+
+function updateRow(dir: string, id: string, config: Partial<LocalConnectorRow['config']>): void {
+  const now = readLocalConnectors(dir).find((r) => r.id === id);
+  if (now !== undefined) replace(dir, { ...now, config: { ...now.config, ...config } });
+}
+
+export async function localVerifyConnector(id: string, dir = agentsDir()): Promise<ConnectorCheck> {
+  const row = rowOrThrow(id, dir);
+  try {
+    const url = parseConnectorUrl(row.url);
+    const auth = await freshAuth(row, dir);
+    const verified = stamp(await verifyRemoteMcp(url, auth));
+    const oauth = row.config.oauth || (await oauthCapable(url, auth));
+    updateRow(dir, row.id, { auth, verified, oauth });
+    return { id: row.id, name: row.name, ok: true, verified };
+  } catch (err) {
+    if (!(err instanceof ConnectorVerifyError)) throw err;
+    return { id: row.id, name: row.name, ok: false, reason: err.message };
+  }
+}
+
+const groupsOf = (tools: RemoteTool[]): Record<string, ToolGroup> =>
+  Object.fromEntries(tools.map((tool) => [tool.name, tool.readOnly ? 'read' : 'write'] as const));
+
+function keepGroups(dir: string, id: string, tools: RemoteTool[]): void {
+  const now = readLocalConnectors(dir).find((r) => r.id === id);
+  const groups = groupsOf(tools);
+  if (now === undefined || JSON.stringify(now.config.toolGroups ?? {}) === JSON.stringify(groups)) return;
+  const config = { ...now.config };
+  delete config.toolGroups;
+  replace(dir, { ...now, config: Object.keys(groups).length > 0 ? { ...config, toolGroups: groups } : config });
+}
+
+export async function localConnectorTools(id: string, dir = agentsDir()): Promise<RemoteTool[]> {
+  const row = rowOrThrow(id, dir);
+  const url = parseConnectorUrl(row.url);
+  const tools = await listRemoteTools(url, await freshAuth(row, dir));
+  keepGroups(dir, id, tools);
+  return tools;
+}
+
+async function refreshGroups(id: string, dir: string): Promise<void> {
+  try {
+    await localConnectorTools(id, dir);
+  } catch (err) {
+    log.warn({ id, err: errMsg(err) }, 'connector policy: could not list the tools; the last known read and write groups stay');
+  }
+}
+
+export async function localSetConnectorPolicy(id: string, policy: ToolPolicy, dir = agentsDir()): Promise<Connector> {
+  const row = rowOrThrow(id, dir);
+  const config = { ...row.config };
+  delete config.policy;
+  const saved = replace(dir, { ...row, config: Object.keys(policy).length > 0 ? { ...config, policy } : config });
+  await refreshGroups(id, dir);
+  return saved;
+}
+
+export async function loadConnectorPolicies(dir = agentsDir()): Promise<void> {
+  const rows = readLocalConnectors(dir);
+  registerConnectors(rows);
+  for (const row of rows) if (row.config.policy !== undefined) await refreshGroups(row.id, dir);
+}
+
+export async function localRenameConnector(id: string, raw: string, dir = agentsDir()): Promise<Connector> {
+  const name = connectorName(raw);
+  const row = rowOrThrow(id, dir);
+  assertNameFree(name, id, dir);
+  return Promise.resolve(replace(dir, { ...row, name }));
+}
+
+export async function localDeleteConnector(id: string, dir = agentsDir()): Promise<DeletedConnector> {
+  const row = rowOrThrow(id, dir);
+  writeRows(dir, readLocalConnectors(dir).filter((r) => r.id !== id));
+  return Promise.resolve({ id: row.id, name: row.name });
+}
+
+const inflight = new Map<string, Promise<OAuthAuth>>();
+
+function refreshOnce(row: LocalConnectorRow, auth: OAuthAuth, dir: string): Promise<OAuthAuth> {
+  const running = inflight.get(row.id);
+  if (running !== undefined) return running;
+  const job = refreshOAuth(auth, parseConnectorUrl(row.url).toString())
+    .then((fresh) => {
+      updateRow(dir, row.id, { auth: fresh });
+      return fresh;
+    })
+    .finally(() => {
+      inflight.delete(row.id);
+    });
+  inflight.set(row.id, job);
+  return job;
+}
+
+export type RelayTarget =
+  | { kind: 'ok'; url: string; headers: Record<string, string> }
+  | { kind: 'missing' }
+  | { kind: 'signin' };
+
+function staleUsable(auth: OAuthAuth, now = Date.now()): boolean {
+  return auth.expiresAt === undefined || auth.expiresAt > now;
+}
+
+function unrefreshedTarget(
+  url: string,
+  auth: OAuthAuth,
+  force: boolean,
+  now = Date.now(),
+): RelayTarget {
+  if (force) return { kind: 'signin' };
+  return { kind: 'ok', url, headers: staleUsable(auth, now) ? authHeaders(auth) : {} };
+}
+
+function fixedTarget(
+  url: string,
+  auth: Exclude<ConnectorAuth, OAuthAuth>,
+  force: boolean,
+): RelayTarget {
+  if (force) return { kind: 'signin' };
+  return { kind: 'ok', url, headers: authHeaders(auth) };
+}
+
+async function oauthTarget(row: LocalConnectorRow, auth: OAuthAuth, force: boolean, dir: string): Promise<RelayTarget> {
+  if (!force && !oauthExpired(auth)) return { kind: 'ok', url: row.url, headers: authHeaders(auth) };
+  try {
+    const fresh = await refreshOnce(row, auth, dir);
+    return { kind: 'ok', url: row.url, headers: authHeaders(fresh) };
+  } catch (err) {
+    log.warn({ id: row.id, err: errMsg(err) }, 'local relay: token refresh failed');
+    return unrefreshedTarget(row.url, auth, force);
+  }
+}
+
+export async function localRelayTarget(
+  connectorId: string,
+  force: boolean,
+  dir = agentsDir(),
+): Promise<RelayTarget> {
+  const row = readLocalConnectors(dir).find((r) => r.id === connectorId);
+  if (row === undefined) return { kind: 'missing' };
+  parseConnectorUrl(row.url);
+  const auth = row.config.auth;
+  if (auth.kind === 'oauth') return oauthTarget(row, auth, force, dir);
+  return fixedTarget(row.url, auth, force);
+}