@stage-labs/metro 0.1.0-beta.15 → 0.1.0-beta.151

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

@@ -0,0 +1,75 @@
+import { str } from '@metro-labs/core/str';
+
+export interface PendingAtt {
+  kind?: string;
+  name?: string;
+}
+
+export interface PendingMsg {
+  line: string;
+  from: string;
+  station: string;
+  text: string;
+  ts: string;
+  messageId: string;
+  lineName: string;
+  fromName: string;
+  fromDisplayName: string;
+  attachments: PendingAtt[];
+  saved: Set<number>;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+export interface MediaCtx {
+  line: string;
+  from: string;
+  station: string;
+  text?: string;
+  ts?: string;
+  messageId?: string;
+  lineName?: string;
+  fromName?: string;
+  fromDisplayName?: string;
+}
+
+export function capSet(set: Set<string>, max: number): void {
+  while (set.size > max) {
+    const oldest = set.values().next();
+    if (oldest.done) break;
+    set.delete(oldest.value);
+  }
+}
+
+export const tsMeta = (v: unknown): Record<string, string> => {
+  const ts = str(v);
+  return ts ? { ts } : {};
+};
+
+export const displayNameMeta = (v: unknown): Record<string, string> => {
+  const name = str(v);
+  return name ? { from_display_name: name } : {};
+};
+
+export const senderMeta = (c: MediaCtx): Record<string, string> => ({
+  ...tsMeta(c.ts),
+  ...(c.messageId ? { message_id: c.messageId } : {}),
+  ...(c.lineName ? { line_name: c.lineName } : {}),
+  ...(c.fromName ? { from_name: c.fromName } : {}),
+  ...displayNameMeta(c.fromDisplayName),
+});
+
+export function takeMediaCtx(buf: PendingMsg): MediaCtx {
+  const ctx: MediaCtx = {
+    line: buf.line,
+    from: buf.from,
+    station: buf.station,
+    text: buf.text,
+    ts: buf.ts,
+    messageId: buf.messageId,
+    lineName: buf.lineName,
+    fromName: buf.fromName,
+    fromDisplayName: buf.fromDisplayName,
+  };
+  buf.text = '';
+  return ctx;
+}

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

@@ -0,0 +1,129 @@
+import {
+  bufferedSince,
+  currentBusSeq,
+  subscribeEvents,
+  type MetroEvent,
+} from '@metro-labs/core/events';
+import type { InboundRelay } from './inbound.js';
+
+export interface ReplayLedger {
+  startAt: number;
+  delivered: Set<number>;
+}
+
+export const newReplayLedger = (startAt = -1): ReplayLedger => ({
+  startAt,
+  delivered: new Set<number>(),
+});
+
+interface ChannelRelayDeps {
+  relay: InboundRelay;
+  log: (...a: unknown[]) => void;
+  inScope: (line: string) => boolean;
+  ledger?: ReplayLedger;
+}
+
+const PENDING_MAX = 2000;
+
+export class ChannelRelay {
+  private readonly deps: ChannelRelayDeps;
+  private readonly ledger: ReplayLedger;
+  private chain: Promise<void> = Promise.resolve();
+
+  constructor(deps: ChannelRelayDeps) {
+    this.deps = deps;
+    this.ledger = deps.ledger ?? newReplayLedger();
+  }
+
+  start(): () => void {
+    if (this.ledger.startAt < 0) this.ledger.startAt = currentBusSeq();
+    return subscribeEvents((event, busSeq) => {
+      this.enqueue(event, busSeq, false);
+    });
+  }
+
+  replayMissed(): void {
+    const missed = bufferedSince(this.ledger.startAt).filter(
+      (b) => !this.ledger.delivered.has(b.busSeq),
+    );
+    const first = missed.at(0);
+    const last = missed.at(-1);
+    if (!first || !last) return;
+    this.deps.log(
+      'relay: replay',
+      `(${missed.length} events)`,
+      'range',
+      `${first.busSeq}..${last.busSeq}`,
+    );
+    for (const b of missed) this.enqueue(b.event, b.busSeq, true);
+  }
+
+  private enqueue(event: MetroEvent, busSeq: number, replay: boolean): void {
+    const { delivered } = this.ledger;
+    if (delivered.has(busSeq)) return;
+    delivered.add(busSeq);
+    if (delivered.size > PENDING_MAX) {
+      const cutoff = busSeq - PENDING_MAX;
+      for (const s of delivered) if (s <= cutoff) delivered.delete(s);
+    }
+    this.chain = this.chain.then(() =>
+      this.deliver(event, busSeq, replay).catch((err: unknown) => {
+        this.deps.log(
+          'relay: delivery step failed; chain kept alive',
+          'busSeq',
+          busSeq,
+          'line',
+          event.line,
+          err,
+        );
+      }),
+    );
+  }
+
+  private withhold(event: MetroEvent, busSeq: number): void {
+    this.ledger.delivered.delete(busSeq);
+    this.deps.log(
+      'relay: withheld (line outside the channel session scope)',
+      'busSeq',
+      busSeq,
+      'line',
+      event.line,
+    );
+  }
+
+  private async deliver(
+    event: MetroEvent,
+    busSeq: number,
+    replay: boolean,
+  ): Promise<void> {
+    if (!this.deps.inScope(event.line)) {
+      this.withhold(event, busSeq);
+      return;
+    }
+    this.deps.log(
+      'relay: notify',
+      'busSeq',
+      busSeq,
+      'id',
+      event.id,
+      'replay',
+      replay,
+    );
+    try {
+      await this.deps.relay.handleEvent(
+        event as unknown as Record<string, unknown>,
+        replay,
+      );
+    } catch (err) {
+      this.ledger.delivered.delete(busSeq);
+      this.deps.log(
+        'channel delivery failed; bounded replay on reconnect',
+        'busSeq',
+        busSeq,
+        'line',
+        event.line,
+        err,
+      );
+    }
+  }
+}

package/runtime/node_modules/@metro-labs/daemon/src/channels/webhook-note.ts

@@ -0,0 +1,51 @@
+const MAX_BODY_CHARS = 8 * 1024;
+
+const HEADERS_KEPT = [
+  'x-github-event',
+  'x-github-delivery',
+  'x-intercom-topic',
+  'x-request-id',
+  'user-agent',
+];
+
+interface WebhookPayload {
+  headers?: Record<string, string>;
+  body?: unknown;
+}
+
+function renderBody(body: unknown): string {
+  if (body === undefined || body === null) return '';
+  const text =
+    typeof body === 'string' ? body : JSON.stringify(body, null, 2);
+  if (text.length <= MAX_BODY_CHARS) return text;
+  return (
+    text.slice(0, MAX_BODY_CHARS) +
+    `\n[truncated: ${String(text.length - MAX_BODY_CHARS)} more characters]`
+  );
+}
+
+function renderHeaders(headers: Record<string, string> | undefined): string {
+  if (!headers) return '';
+  const kept = HEADERS_KEPT.flatMap((k) =>
+    headers[k] === undefined ? [] : [`${k}: ${headers[k]}`],
+  );
+  return kept.length === 0 ? '' : kept.join('\n') + '\n';
+}
+
+export function buildWebhookNote(
+  summary: string,
+  lineName: string | undefined,
+  payload: unknown,
+): string {
+  const p = (
+    payload !== null && typeof payload === 'object' ? payload : {}
+  ) as WebhookPayload;
+  const label = lineName ? `${lineName}: ` : '';
+  const body = renderBody(p.body);
+  return (
+    `[webhook received] ${label}${summary}\n` +
+    renderHeaders(p.headers) +
+    (body ? `\n${body}\n` : '') +
+    'Inbound only: this line takes no send, reply or react.'
+  );
+}

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

@@ -0,0 +1,354 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { errMsg, log } from '@metro-labs/core/log';
+import { apiFailure, apiSession, requireAdmin, cors, readJsonBody, sendJson } from '@metro-labs/http/api-http';
+import { ApiError } from '@metro-labs/http/api-error';
+import { isRecord } from '@metro-labs/core/is-record';
+import { listClaudeSettings, SETTINGS_MAX, writeClaudeSettings } from './settings.js';
+import {
+  createClaudeSkill,
+  deleteClaudeSkill,
+  listClaudeSkills,
+  readClaudeSkill,
+  writeClaudeSkill,
+} from './skills.js';
+import {
+  answerClaudeLogin,
+  claudeAccount,
+  claudeInstalled,
+  claudeLoginView,
+  endClaudeLogin,
+  startClaudeLogin,
+  type LoginDeps,
+} from './login.js';
+import {
+  claudeSetupStatus,
+  ensureClaudeSetup,
+  isPermissionMode,
+  permissionMode,
+  setPermissionMode,
+  setPrivacy,
+  setSystemPrompt,
+  systemPrompt,
+  SYSTEM_PROMPT_MAX,
+  type PermissionMode,
+  type SetupDeps,
+} from './setup.js';
+import {
+  ensureSession,
+  sessionRunning,
+  sessionStatus,
+  setAutostart,
+  startSession,
+  stopSession,
+  type SessionDeps,
+} from './session.js';
+import { claudeVersion, updateClaude, type VersionDeps } from './version.js';
+import { readSessionFile, receiveSessionFile, SESSION_FILE_MAX, sessionFilePath, writeSessionFile } from './session-files.js';
+import { createReadStream } from 'node:fs';
+import { pipeline } from 'node:stream/promises';
+import {
+  claudeDir,
+  deleteClaudeSession,
+  listClaudeProjects,
+  listClaudeSessions,
+  listMemory,
+  readMemoryFile,
+  readTranscript,
+  writeMemoryFile,
+} from './files.js';
+
+const PREFIX = '/api/claude';
+const BODY_MAX = SETTINGS_MAX + 4096;
+const SESSION_BODY_MAX = SESSION_FILE_MAX + 4096;
+const WRITABLE = new Set(['GET', 'DELETE', 'PUT', 'POST']);
+const PAGE = 100;
+const PAGE_MAX = 500;
+
+export interface ClaudeApiDeps {
+  authorize: (subject: string) => void;
+  dir?: () => string;
+  login?: LoginDeps;
+  session?: SessionDeps;
+  setup?: SetupDeps;
+  version?: VersionDeps;
+}
+
+function projectOf(query: URLSearchParams): string {
+  const project = query.get('project');
+  if (project === null || project === '') throw new ApiError('project is required', 400);
+  return project;
+}
+
+function pageOf(query: URLSearchParams): { offset: number; limit: number } {
+  const offset = Math.max(0, Math.floor(Number(query.get('offset') ?? '0')) || 0);
+  const limit = Math.min(PAGE_MAX, Math.max(1, Math.floor(Number(query.get('limit') ?? String(PAGE))) || PAGE));
+  return { offset, limit };
+}
+
+type Handler = (query: URLSearchParams, dir: string, item: string) => unknown;
+
+const COLLECTIONS: Record<string, Handler> = {
+  projects: (_query, dir) => ({ projects: listClaudeProjects(dir) }),
+  sessions: (query, dir) => ({ sessions: listClaudeSessions(projectOf(query), dir) }),
+  memory: (query, dir) => listMemory(projectOf(query), dir),
+  settings: (_query, dir) => ({ files: listClaudeSettings(dir) }),
+  skills: (_query, dir) => ({ skills: listClaudeSkills(dir) }),
+};
+
+const ITEMS: Record<string, Handler> = {
+  sessions: (query, dir, id) => {
+    if (query.get('raw') === '1') return { id, text: readSessionFile(projectOf(query), id, dir) };
+    const { offset, limit } = pageOf(query);
+    return readTranscript(projectOf(query), id, offset, limit, dir);
+  },
+  memory: (query, dir, name) => ({ name, content: readMemoryFile(projectOf(query), name, dir) }),
+  skills: (_query, dir, id) => readClaudeSkill(decodeURIComponent(id), dir),
+};
+
+const parts = (path: string): string[] => path.slice(PREFIX.length + 1).split('/').filter(Boolean);
+
+const seenIn = (body: Record<string, unknown>): string | null | undefined =>
+  'seenAt' in body ? (typeof body.seenAt === 'string' ? body.seenAt : null) : undefined;
+
+const WRITE_HEADS = new Set(['settings', 'skills', 'memory', 'sessions']);
+
+interface Write {
+  text: string;
+  seen: string | null | undefined;
+  modifiedAt: string | undefined;
+}
+
+function writeItem(head: string, item: string, write: Write, search: string, dir: string): unknown {
+  if (head === 'skills') return writeClaudeSkill(decodeURIComponent(item), write.text, write.seen, dir);
+  if (head === 'sessions') return writeSessionFile(projectOf(new URLSearchParams(search)), item, write.text, dir);
+  if (head === 'memory') return writeMemoryFile(projectOf(new URLSearchParams(search)), decodeURIComponent(item), write.text, dir, write.modifiedAt);
+  return writeClaudeSettings(item, write.text, write.seen, dir);
+}
+
+async function writeAnswer(req: IncomingMessage, path: string, search: string, dir: string): Promise<unknown> {
+  const [head = '', item = ''] = parts(path);
+  if (!WRITE_HEADS.has(head) || item === '') throw new ApiError('method not allowed', 405);
+  const body = await readJsonBody(req, head === 'sessions' ? SESSION_BODY_MAX : BODY_MAX);
+  if (!isRecord(body) || typeof body.text !== 'string') throw new ApiError('text is required', 400);
+  const modifiedAt = typeof body.modifiedAt === 'string' ? body.modifiedAt : undefined;
+  return writeItem(head, item, { text: body.text, seen: seenIn(body), modifiedAt }, search, dir);
+}
+
+async function created(req: IncomingMessage, path: string, dir: string): Promise<unknown> {
+  const rest = parts(path);
+  if (rest.length !== 1 || rest[0] !== 'skills') throw new ApiError('method not allowed', 405);
+  const body = await readJsonBody(req, BODY_MAX);
+  if (!isRecord(body) || typeof body.name !== 'string') throw new ApiError('name is required', 400);
+  return createClaudeSkill(body.name, typeof body.text === 'string' ? body.text : undefined, dir);
+}
+
+const ADMIN_ONLY = /^\/(login|session|version|setup)(\/|$)/;
+const LOGIN = 'login';
+const SESSION = 'session';
+const SETUP = 'setup';
+const SETUP_BODY_MAX = SYSTEM_PROMPT_MAX * 2;
+const VERSION = 'version';
+
+interface SetupChange {
+  privacy?: boolean;
+  permissionMode?: PermissionMode;
+  systemPrompt?: string;
+}
+
+function promptChange(raw: unknown): string | undefined {
+  if (raw === undefined) return undefined;
+  if (typeof raw !== 'string') throw new ApiError('systemPrompt must be text', 400);
+  if (Buffer.byteLength(raw) > SYSTEM_PROMPT_MAX) throw new ApiError(`systemPrompt must be under ${String(SYSTEM_PROMPT_MAX / 1024)} KiB`, 400);
+  return raw;
+}
+
+function privacyChange(raw: unknown): boolean | undefined {
+  if (raw === undefined) return undefined;
+  if (typeof raw !== 'boolean') throw new ApiError('privacy must be true or false', 400);
+  return raw;
+}
+
+function modeChange(raw: unknown): PermissionMode | undefined {
+  if (raw === undefined) return undefined;
+  if (!isPermissionMode(raw)) throw new ApiError('permissionMode must be auto or bypass', 400);
+  return raw;
+}
+
+function setupChange(body: unknown): SetupChange {
+  if (!isRecord(body)) throw new ApiError('a body is required', 400);
+  const privacy = privacyChange(body.privacy);
+  const permissionMode = modeChange(body.permissionMode);
+  const systemPrompt = promptChange(body.systemPrompt);
+  if (privacy === undefined && permissionMode === undefined && systemPrompt === undefined) throw new ApiError('nothing to change', 400);
+  return {
+    ...(privacy === undefined ? {} : { privacy }),
+    ...(permissionMode === undefined ? {} : { permissionMode }),
+    ...(systemPrompt === undefined ? {} : { systemPrompt }),
+  };
+}
+
+function restartsSession(change: SetupChange, agents: string | undefined): boolean {
+  let restart = false;
+  if (change.permissionMode !== undefined && change.permissionMode !== permissionMode(agents)) {
+    setPermissionMode(change.permissionMode, agents);
+    restart = true;
+  }
+  if (change.systemPrompt !== undefined && change.systemPrompt.trim() !== systemPrompt(agents)) {
+    setSystemPrompt(change.systemPrompt, agents);
+    restart = true;
+  }
+  return restart;
+}
+
+function applySetupChange(change: SetupChange, deps: ClaudeApiDeps): void {
+  const setup = deps.setup ?? {};
+  if (change.privacy !== undefined) setPrivacy(change.privacy, setup.agents);
+  if (restartsSession(change, setup.agents) && sessionRunning(deps.session?.tmux ?? 'tmux')) stopSession(deps.session ?? {});
+  ensureClaudeSetup(setup);
+}
+
+async function setupAnswer(req: IncomingMessage, deps: ClaudeApiDeps): Promise<unknown> {
+  const setup = deps.setup ?? {};
+  const method = req.method ?? 'GET';
+  if (method === 'GET') return claudeSetupStatus(setup);
+  if (method !== 'POST') throw new ApiError('method not allowed', 405);
+  applySetupChange(setupChange(await readJsonBody(req, SETUP_BODY_MAX)), deps);
+  return claudeSetupStatus(setup);
+}
+
+function sessionCommand(body: Record<string, unknown>, session: SessionDeps): unknown {
+  if (body.action === 'start') {
+    const status = sessionStatus(session);
+    if (status.running) return status;
+    if (status.blocked !== null) throw new ApiError(`cannot start a Claude session: ${status.blocked}`, 409);
+    return startSession(session);
+  }
+  if (body.action === 'stop') return stopSession(session);
+  if (body.action !== undefined) throw new ApiError('action must be start or stop', 400);
+  if (body.autostart === true) ensureSession(session);
+  return sessionStatus(session);
+}
+
+async function sessionAnswer(req: IncomingMessage, deps: ClaudeApiDeps): Promise<unknown> {
+  const session = deps.session ?? {};
+  const method = req.method ?? 'GET';
+  if (method === 'GET') return sessionStatus(session);
+  if (method !== 'POST') throw new ApiError('method not allowed', 405);
+  const body = await readJsonBody(req);
+  if (!isRecord(body)) throw new ApiError('a body is required', 400);
+  if (typeof body.autostart === 'boolean') setAutostart(body.autostart, session.agents);
+  return sessionCommand(body, session);
+}
+
+async function loginAnswer(req: IncomingMessage, id: string, deps: ClaudeApiDeps): Promise<unknown> {
+  const method = req.method ?? 'GET';
+  if (id === '') {
+    if (method === 'POST') return startClaudeLogin(deps.login);
+    if (method === 'GET') return { available: claudeInstalled(), ...claudeAccount() };
+    throw new ApiError('method not allowed', 405);
+  }
+  if (method === 'GET') return claudeLoginView(id);
+  if (method === 'DELETE') return endClaudeLogin(id);
+  if (method !== 'POST') throw new ApiError('method not allowed', 405);
+  const body = await readJsonBody(req);
+  if (!isRecord(body) || typeof body.text !== 'string') throw new ApiError('text is required', 400);
+  return answerClaudeLogin(id, body.text);
+}
+
+function removed(rest: string[], query: URLSearchParams, dir: string): unknown {
+  const [head = '', item = ''] = rest;
+  if (rest.length !== 2) throw new ApiError('method not allowed', 405);
+  if (head === 'skills') return { deleted: deleteClaudeSkill(decodeURIComponent(item), dir) };
+  if (head !== 'sessions') throw new ApiError('method not allowed', 405);
+  deleteClaudeSession(projectOf(query), item, dir);
+  return { deleted: item };
+}
+
+function answer(method: string, path: string, query: URLSearchParams, dir: string): unknown {
+  const rest = parts(path);
+  const [head = '', item = ''] = rest;
+  if (method === 'DELETE') return removed(rest, query, dir);
+  if (method !== 'GET') throw new ApiError('method not allowed', 405);
+  const handler = rest.length === 1 ? COLLECTIONS[head] : rest.length === 2 ? ITEMS[head] : undefined;
+  if (handler === undefined) throw new ApiError('no such route', 404);
+  return handler(query, dir, item);
+}
+
+function versionAnswer(req: IncomingMessage, deps: ClaudeApiDeps): Promise<unknown> {
+  const version: VersionDeps = { ...deps.version, session: deps.version?.session ?? deps.session };
+  const method = req.method ?? 'GET';
+  if (method === 'GET') return claudeVersion(version);
+  if (method !== 'POST') throw new ApiError('method not allowed', 405);
+  return updateClaude(version);
+}
+
+const SINGLETONS: Record<string, (req: IncomingMessage, deps: ClaudeApiDeps) => Promise<unknown>> = {
+  [SESSION]: sessionAnswer,
+  [SETUP]: setupAnswer,
+  [VERSION]: versionAnswer,
+};
+
+function routed(req: IncomingMessage, path: string, search: string, deps: ClaudeApiDeps): unknown {
+  const dir = (deps.dir ?? claudeDir)();
+  const [head = '', item = ''] = parts(path);
+  if (head === LOGIN) return loginAnswer(req, item, deps);
+  const single = item === '' ? SINGLETONS[head] : undefined;
+  if (single !== undefined) return single(req, deps);
+  if (req.method === 'PUT') return writeAnswer(req, path, search, dir);
+  if (req.method === 'POST') return created(req, path, dir);
+  return answer(req.method ?? 'GET', path, new URLSearchParams(search), dir);
+}
+
+const TEXT = 'text/plain; charset=utf-8';
+
+async function streamed(req: IncomingMessage, res: ServerResponse, path: string, search: string, dir: string): Promise<boolean> {
+  const [head = '', item = ''] = parts(path);
+  if (head !== 'sessions' || item === '') return false;
+  const query = new URLSearchParams(search);
+  if (req.method === 'GET' && query.get('raw') === '1') {
+    const file = sessionFilePath(projectOf(query), item, dir);
+    res.writeHead(200, { 'content-type': TEXT, 'cache-control': 'no-store', ...cors(req) });
+    await pipeline(createReadStream(file), res).catch(() => {
+      res.destroy();
+    });
+    return true;
+  }
+  if (req.method === 'PUT' && !(req.headers['content-type'] ?? '').includes('json')) {
+    sendJson(req, res, 200, await receiveSessionFile(projectOf(query), item, req, dir));
+    return true;
+  }
+  return false;
+}
+
+export function handleClaudeRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: ClaudeApiDeps,
+): boolean {
+  const [path = '', search = ''] = (req.url ?? '').split('?');
+  if (path !== PREFIX && !path.startsWith(`${PREFIX}/`)) return false;
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204, cors(req)).end();
+    return true;
+  }
+  if (!WRITABLE.has(req.method ?? '')) {
+    sendJson(req, res, 405, { error: 'method not allowed' });
+    return true;
+  }
+  apiSession(req)
+    .then(async (session) => {
+      if (!session) throw new ApiError('unauthorized', 401);
+      deps.authorize(session.subject);
+      if (req.method !== 'GET' && ADMIN_ONLY.test(path)) requireAdmin(session);
+      if (await streamed(req, res, path, search, (deps.dir ?? claudeDir)())) return;
+      sendJson(req, res, 200, await routed(req, path, search, deps));
+    })
+    .catch((err: unknown) => {
+      if (err instanceof ApiError) apiFailure(req, res, err, 'claude-api');
+      else {
+        log.warn({ err: errMsg(err) }, 'claude-api: request failed');
+        if (!res.headersSent) sendJson(req, res, 500, { error: 'claude-api failed' });
+      }
+    });
+  return true;
+}