@stage-labs/metro 0.1.0-beta.225 → 0.1.0-beta.226

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage-labs/metro",
-  "version": "0.1.0-beta.225",
+  "version": "0.1.0-beta.226",
   "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.225",
+  "version": "0.1.0-beta.226",
   "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/node_modules/@metro-labs/daemon/src/connectors/transfer-api.ts

@@ -0,0 +1,116 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { randomUUID, type KeyObject } from 'node:crypto';
+import { isRecord } from '@metro-labs/core/is-record';
+import { parseId } from '@metro-labs/core/ids';
+import { log } from '@metro-labs/core/log';
+import { ApiError } from '@metro-labs/http/api-error';
+import { apiSession, cors, readJsonBody, requireAdmin, sendJson } from '@metro-labs/http/api-http';
+import { openTransfer, sealTransfer, transferKeys } from './transfer-crypto.js';
+import type { LocalConnectorRow } from './store.js';
+import type { ConnectorCopyResult } from './transfer-store.js';
+
+const PREFIX = '/api/connectors/transfer';
+const MAX_BODY = 4 * 1024 * 1024 + 4096;
+const TTL = 5 * 60_000;
+
+export interface ConnectorTransferDeps {
+  read: () => LocalConnectorRow[];
+  copy: (value: unknown) => ConnectorCopyResult[];
+  now?: () => number;
+}
+
+interface Ticket {
+  privateKey: KeyObject;
+  organization: string;
+  expiresAt: number;
+}
+
+function selectedIds(raw: unknown): string[] | null {
+  if (raw === null) return null;
+  if (!Array.isArray(raw) || raw.length === 0 || raw.length > 500) throw new ApiError('choose connectors to copy', 400);
+  return [...new Set(raw.map((id: unknown) => {
+    if (typeof id !== 'string' || parseId(id) === null) throw new ApiError('choose connectors to copy', 400);
+    return id;
+  }))];
+}
+
+export class ConnectorTransfers {
+  private readonly tickets = new Map<string, Ticket>();
+
+  constructor(private readonly deps: ConnectorTransferDeps) {}
+
+  private prepare(organization: string): unknown {
+    const now = (this.deps.now ?? Date.now)();
+    for (const [id, ticket] of this.tickets) if (ticket.expiresAt <= now) this.tickets.delete(id);
+    if (this.tickets.size >= 64) throw new ApiError('too many pending connector copies, try again later', 429);
+    const { publicKey, privateKey } = transferKeys();
+    const ticket = randomUUID();
+    this.tickets.set(ticket, { privateKey, organization, expiresAt: now + TTL });
+    return { ticket, publicKey };
+  }
+
+  private export(body: Record<string, unknown>): unknown {
+    if (typeof body.publicKey !== 'string') throw new ApiError('invalid transfer key', 400);
+    const ids = selectedIds(body.ids);
+    const all = this.deps.read();
+    const rows = ids === null ? all : all.filter((row) => ids.includes(row.id));
+    const expected = ids?.length ?? rows.length;
+    if (rows.length !== expected) throw new ApiError('a selected connector no longer exists', 409);
+    if (rows.length > 500) throw new ApiError('copy at most 500 connectors at once', 413);
+    try {
+      return sealTransfer({ version: 1, connectors: rows }, body.publicKey);
+    } catch (err) {
+      if (err instanceof ApiError) throw err;
+      throw new ApiError('invalid transfer key', 400);
+    }
+  }
+
+  private receive(body: Record<string, unknown>, organization: string): unknown {
+    const id = typeof body.ticket === 'string' ? body.ticket : '';
+    const ticket = this.tickets.get(id);
+    if (ticket?.organization !== organization || ticket.expiresAt <= (this.deps.now ?? Date.now)()) {
+      this.tickets.delete(id);
+      throw new ApiError('this connector copy has expired, start again', 410);
+    }
+    let value: unknown;
+    try {
+      value = openTransfer(body.envelope, ticket.privateKey);
+    } catch {
+      throw new ApiError('invalid encrypted connector copy', 400);
+    }
+    const results = this.deps.copy(value);
+    this.tickets.delete(id);
+    return { results };
+  }
+
+  private async answer(req: IncomingMessage, path: string): Promise<unknown> {
+    const session = await apiSession(req);
+    if (session === null) throw new ApiError('unauthorized', 401);
+    requireAdmin(session);
+    const body = await readJsonBody(req, MAX_BODY);
+    if (!isRecord(body) || body.confirmed !== true) throw new ApiError('confirm copying saved logins and settings', 400);
+    if (path === `${PREFIX}/prepare`) return this.prepare(session.subject);
+    if (path === `${PREFIX}/export`) return this.export(body);
+    return this.receive(body, session.subject);
+  }
+
+  handle(req: IncomingMessage, res: ServerResponse): boolean {
+    const path = (req.url ?? '').split('?')[0] ?? '';
+    if (![`${PREFIX}/prepare`, `${PREFIX}/export`, `${PREFIX}/receive`].includes(path)) return false;
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204, cors(req)).end();
+      return true;
+    }
+    if (req.method !== 'POST') {
+      sendJson(req, res, 405, { error: 'method not allowed' });
+      return true;
+    }
+    this.answer(req, path).then((body) => {
+      sendJson(req, res, 200, body);
+    }).catch((err: unknown) => {
+      if (!(err instanceof ApiError)) log.warn('connector-transfer: request failed');
+      sendJson(req, res, err instanceof ApiError ? err.status : 500, { error: err instanceof ApiError ? err.message : 'connector copy failed' });
+    });
+    return true;
+  }
+}

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

@@ -0,0 +1,44 @@
+import { createCipheriv, createDecipheriv, createPublicKey, diffieHellman, generateKeyPairSync, hkdfSync, randomBytes, type KeyObject } from 'node:crypto';
+import { isRecord } from '@metro-labs/core/is-record';
+import { ApiError } from '@metro-labs/http/api-error';
+
+export interface TransferEnvelope {
+  key: string;
+  iv: string;
+  tag: string;
+  data: string;
+}
+
+export const transferKeys = (): { publicKey: string; privateKey: KeyObject } => {
+  const pair = generateKeyPairSync('x25519');
+  return { publicKey: pair.publicKey.export({ type: 'spki', format: 'pem' }).toString(), privateKey: pair.privateKey };
+};
+
+function sharedKey(privateKey: KeyObject, pem: string): ArrayBuffer {
+  if (pem.length > 1024) throw new ApiError('invalid transfer key', 400);
+  const publicKey = createPublicKey(pem);
+  if (publicKey.asymmetricKeyType !== 'x25519') throw new ApiError('invalid transfer key', 400);
+  return hkdfSync('sha256', diffieHellman({ privateKey, publicKey }), '', 'metro-connector-copy-v1', 32);
+}
+
+export function sealTransfer(value: unknown, publicKey: string): TransferEnvelope {
+  const pair = transferKeys();
+  const iv = randomBytes(12);
+  const cipher = createCipheriv('aes-256-gcm', Buffer.from(sharedKey(pair.privateKey, publicKey)), iv);
+  const plain = JSON.stringify(value);
+  if (Buffer.byteLength(plain) > 3 * 1024 * 1024) throw new ApiError('too many connector settings for one copy', 413);
+  const data = Buffer.concat([cipher.update(plain, 'utf8'), cipher.final()]);
+  return { key: pair.publicKey, iv: iv.toString('base64'), tag: cipher.getAuthTag().toString('base64'), data: data.toString('base64') };
+}
+
+export function openTransfer(raw: unknown, privateKey: KeyObject): unknown {
+  if (!isRecord(raw) || typeof raw.key !== 'string' || typeof raw.iv !== 'string' || typeof raw.tag !== 'string' || typeof raw.data !== 'string')
+    throw new ApiError('invalid encrypted transfer', 400);
+  const iv = Buffer.from(raw.iv, 'base64');
+  const tag = Buffer.from(raw.tag, 'base64');
+  if (iv.length !== 12 || tag.length !== 16) throw new ApiError('invalid encrypted transfer', 400);
+  const decipher = createDecipheriv('aes-256-gcm', Buffer.from(sharedKey(privateKey, raw.key)), iv);
+  decipher.setAuthTag(tag);
+  const plain = Buffer.concat([decipher.update(Buffer.from(raw.data, 'base64')), decipher.final()]);
+  return JSON.parse(plain.toString('utf8')) as unknown;
+}

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

@@ -0,0 +1,48 @@
+import { isDeepStrictEqual } from 'node:util';
+import { isRecord } from '@metro-labs/core/is-record';
+import { newId, parseId } from '@metro-labs/core/ids';
+import { ApiError } from '@metro-labs/http/api-error';
+import { connectorAuth, connectorName, readConfig } from './config.js';
+import { parseConnectorUrl } from './url.js';
+import { normalizePolicy } from '../policy/policy.js';
+import { localImportConnectors, readLocalConnectors, type LocalConnectorRow } from './store.js';
+
+export interface ConnectorCopyResult {
+  sourceId: string | null;
+  id?: string;
+  status: 'copied' | 'skipped' | 'invalid';
+}
+
+function copyRow(raw: unknown): LocalConnectorRow {
+  if (!isRecord(raw) || typeof raw.id !== 'string' || parseId(raw.id) === null || !isRecord(raw.config)) throw new ApiError('invalid connector', 400);
+  const name = connectorName(raw.name);
+  const url = parseConnectorUrl(raw.url).toString();
+  if (raw.config.policy !== undefined) normalizePolicy(raw.config.policy);
+  const config = readConfig(raw.config);
+  if (!isDeepStrictEqual(config, raw.config)) throw new ApiError('invalid connector settings', 400);
+  if (config.auth.kind === 'header') connectorAuth(config.auth.name, config.auth.value);
+  return { id: raw.id, name, url, config };
+}
+
+export function copyConnectorRows(value: unknown, dir?: string): ConnectorCopyResult[] {
+  if (!isRecord(value) || value.version !== 1 || !Array.isArray(value.connectors) || value.connectors.length > 500)
+    throw new ApiError('invalid connector transfer', 400);
+  const names = new Set(readLocalConnectors(dir).map((row) => row.name));
+  const imported: LocalConnectorRow[] = [];
+  const results: ConnectorCopyResult[] = value.connectors.map((raw: unknown) => {
+    const sourceId = isRecord(raw) && typeof raw.id === 'string' ? parseId(raw.id) : null;
+    let row: LocalConnectorRow;
+    try {
+      row = copyRow(raw);
+    } catch {
+      return { sourceId, status: 'invalid' };
+    }
+    if (names.has(row.name)) return { sourceId, status: 'skipped' };
+    names.add(row.name);
+    const id = newId();
+    imported.push({ ...row, id });
+    return { sourceId, id, status: 'copied' };
+  });
+  if (imported.length > 0) localImportConnectors(imported.map((row) => ({ ...row, config: { ...row.config } })), dir, 'append');
+  return results;
+}

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

@@ -11,6 +11,8 @@ import type { ModeInfo } from '@metro-labs/http/mode-api';
 import { loadedAgentOf, type AgentBundle, type BundleApiDeps } from '../agents/bundle.js';
 import { METRO_VERSION } from '@metro-labs/core/version';
 import type { ConnectorApiDeps } from '../connectors/api.js';
+import { ConnectorTransfers } from '../connectors/transfer-api.js';
+import { copyConnectorRows } from '../connectors/transfer-store.js';
 import { authenticate } from '../mcp/request-identity.js';
 import type { RelayApiDeps } from '../connectors/relay.js';
 import {
@@ -192,6 +194,7 @@ export function localSessionApis(deps: LocalModeDeps): SessionApis {
     agentApi: agentApi(deps),
     bundleApi: bundleApi(deps),
     connectorApi,
+    connectorTransfers: new ConnectorTransfers({ read: readLocalConnectors, copy: copyConnectorRows }),
     relayApi,
     claudeApi: { liveEvents: deps.liveEvents },
     updateApi: { restart: deps.restart },

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

@@ -7,6 +7,7 @@ import {
   type ConnectorApiDeps,
 } from '../connectors/api.js';
 import type { RelayApiDeps } from '../connectors/relay.js';
+import type { ConnectorTransfers } from '../connectors/transfer-api.js';
 import { handleClaudeRequest, type ClaudeApiDeps } from '../claude/api.js';
 import type { ModeInfo } from '@metro-labs/http/mode-api';
 import { handleBundleRequest, type BundleApiDeps } from '../agents/bundle.js';
@@ -33,6 +34,7 @@ export interface SessionApis {
   terminalApi?: TerminalApiDeps;
   claudeApi?: ClaudeApiDeps;
   connectorApi?: ConnectorApiDeps;
+  connectorTransfers?: ConnectorTransfers;
   relayApi?: RelayApiDeps;
   mode?: () => ModeInfo;
 }
@@ -48,6 +50,7 @@ export function handleSessionApis(
   const routes: (() => boolean)[] = [
     () => handleSessionApiRequest(req, res),
     () => handleApprovalsRequest(req, res),
+    ...when(apis.connectorTransfers, (d) => d.handle(req, res)),
     ...when(apis.connectorApi, (d) => handleConnectorApiRequest(req, res, d)),
     ...when(apis.bundleApi, (d) => handleBundleRequest(req, res, d)),
     ...when(apis.updateApi, (d) => handleUpdateRequest(req, res, d)),

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

@@ -1,7 +1,7 @@
-import { accountForCall, convOf, lineOf } from './accounts.js';
+import { accountForCall, convOf, lineOf, parseLine } from './accounts.js';
 import { respond } from '@metro-labs/core/stations/station-runtime';
-import { warmGroupName } from './conv-helpers.js';
-import { mergeAppData, readAppData, type GroupLike } from './labels.js';
+import { ethIdentifiers, warmGroupName } from './conv-helpers.js';
+import { mergeAppData, normalizeAssigned, readAppDataObject, type GroupLike } from './labels.js';
 import { TrainError } from '@metro-labs/core/train-error';
 
 type Args = Record<string, unknown>;
@@ -50,7 +50,7 @@ async function applyMergedAppData(
     await group.updateAppData(res.blob);
     return res.merged;
   }
-  return readAppData(group.appData);
+  return readAppDataObject(group.appData);
 }
 
 async function applyChannelMeta(
@@ -73,7 +73,19 @@ async function applyChannelMeta(
       `${verb} target is not a group (no updateAppData)`,
     );
   }
-  await group.sync?.().catch(() => undefined);
+  await conv.sync();
+  if (appData) mergeAppData(group.appData, appData);
+  else readAppDataObject(group.appData);
+  if (appData && Object.hasOwn(appData, 'assigned')) {
+    const assigned = normalizeAssigned(appData.assigned);
+    const inboxIds = await Promise.all(
+      ethIdentifiers(assigned).map((identifier) => acct.client.fetchInboxIdByIdentifier(identifier)),
+    );
+    const members = new Set((await conv.members()).map((member) => member.inboxId));
+    if (inboxIds.some((inboxId) => !inboxId || !members.has(inboxId))) {
+      throw new TrainError('INVALID_ARGS', 'Assignees must be current channel members');
+    }
+  }
 
   await applyNameAndDescription(group, name, description);
   const merged = await applyMergedAppData(
@@ -95,24 +107,38 @@ function metaFields(merged: Record<string, unknown>): {
   labels: string[];
   github: string | undefined;
   preview: string | undefined;
+  assigned: unknown;
 } {
   return {
     labels: Array.isArray(merged.labels) ? (merged.labels as string[]) : [],
     github: typeof merged.github === 'string' ? merged.github : undefined,
     preview: typeof merged.preview === 'string' ? merged.preview : undefined,
+    assigned: Object.hasOwn(merged, 'assigned') ? merged.assigned : [],
   };
 }
 
+const metadataWrites = new Map<string, Promise<Record<string, unknown>>>();
+
 export async function updateChannelMeta(id: string, args: Args): Promise<void> {
   const line = resolveLine(args, 'updateChannelMeta');
+  const parsed = parseLine(line);
+  if (!parsed) throw new TrainError('INVALID_ARGS', `bad xmtp line: ${line}`);
+  const key = lineOf(parsed.accountId, parsed.convId);
   const { name, description, appData } = args as {
     name?: string;
     description?: string;
     appData?: Record<string, unknown>;
   };
-  const result = await applyChannelMeta(
-    { line, name, description, appData },
-    'updateChannelMeta',
-  );
-  respond(id, { result });
+  if (name !== undefined && typeof name !== 'string') {
+    throw new TrainError('INVALID_ARGS', 'name must be a string');
+  }
+  const task = () => applyChannelMeta({ line, name, description, appData }, 'updateChannelMeta');
+  const previous = metadataWrites.get(key);
+  const pending = previous ? previous.then(task, task) : task();
+  metadataWrites.set(key, pending);
+  try {
+    respond(id, { result: await pending });
+  } finally {
+    if (metadataWrites.get(key) === pending) metadataWrites.delete(key);
+  }
 }

package/runtime/node_modules/@metro-labs/xmtp/src/conv-helpers.ts

@@ -3,7 +3,7 @@ import { convOf, type Account } from './accounts.js';
 import { inboxEthCache, cacheInboxEth } from './wire.js';
 import { TrainError } from '@metro-labs/core/train-error';
 import type { MemberList, MetroMember } from '@metro-labs/core/stations/types';
-import { readAppData, type GroupLike } from './labels.js';
+import { readAppData, readAppDataObject, type GroupLike } from './labels.js';
 
 export { parseMemberArgs, resolveMembers } from './member-args.js';
 
@@ -78,6 +78,9 @@ export async function buildGroupInfo(
   acct: Account,
   conv: Conv,
 ): Promise<Record<string, unknown>> {
+  await conv.sync();
+  const rawAppData = (conv as unknown as GroupLike).appData ?? '';
+  const appData = readAppDataObject(rawAppData);
   const inboxIds = (await conv.members()).map((m) => m.inboxId);
   const addresses = await resolveAddresses(acct, inboxIds);
   const isDm =
@@ -86,9 +89,7 @@ export async function buildGroupInfo(
   const gn = (conv as unknown as { name?: string | (() => Promise<string>) })
     .name;
   const resolvedName = typeof gn === 'function' ? await gn() : (gn ?? '');
-  const { labels, github, preview } = readAppData(
-    (conv as unknown as GroupLike).appData,
-  );
+  const { labels, github, preview } = readAppData(rawAppData);
   return {
     line,
     id: conv.id,
@@ -99,6 +100,9 @@ export async function buildGroupInfo(
     labels,
     github,
     preview,
+    assigned: Object.hasOwn(appData, 'assigned') ? appData.assigned : [],
+    appData,
+    rawAppData,
     members: inboxIds.map((iid) => ({
       inboxId: iid,
       address: addresses[iid] ?? null,

package/runtime/node_modules/@metro-labs/xmtp/src/labels.ts

@@ -1,3 +1,5 @@
+import { TrainError } from '@metro-labs/core/train-error';
+
 export interface GroupLike {
   id: string;
   appData?: string;
@@ -10,6 +12,7 @@ export interface GroupLike {
 
 const MAX_LABELS = 16;
 const MAX_LABEL_LEN = 24;
+const MAX_APP_DATA_BYTES = 8192;
 
 function cleanLabels(raw: unknown): string[] {
   if (!Array.isArray(raw)) return [];
@@ -27,18 +30,40 @@ function cleanLabels(raw: unknown): string[] {
   return out;
 }
 
-function parseAppDataObject(
+export function readAppDataObject(
   existingAppData: string | undefined,
 ): Record<string, unknown> {
   if (!existingAppData?.trim()) return {};
-  try {
-    const p: unknown = JSON.parse(existingAppData);
-    if (p && typeof p === 'object' && !Array.isArray(p))
-      return p as Record<string, unknown>;
-  } catch {
-    return {};
+  const parsed: unknown = JSON.parse(existingAppData);
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new TrainError('INVALID_ARGS', 'Channel appData must be a JSON object');
+  }
+  return parsed as Record<string, unknown>;
+}
+
+export function normalizeAssigned(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    throw new TrainError('INVALID_ARGS', 'assigned must be an array of Ethereum addresses');
+  }
+  const addresses: string[] = [];
+  for (const address of value) {
+    if (typeof address !== 'string' || !/^0x[0-9a-fA-F]{40}$/.test(address.trim())) {
+      throw new TrainError('INVALID_ARGS', 'assigned must contain valid Ethereum addresses');
+    }
+    addresses.push(address.trim().toLowerCase());
+  }
+  return [...new Set(addresses)];
+}
+
+export function metadataPatch(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TrainError('INVALID_ARGS', 'metadata must be a JSON object');
+  }
+  const patch = value as Record<string, unknown>;
+  if (Object.hasOwn(patch, 'v')) {
+    throw new TrainError('INVALID_ARGS', 'metadata cannot change the reserved v field');
   }
-  return {};
+  return patch;
 }
 
 function trimmedString(v: unknown): string | undefined {
@@ -65,13 +90,24 @@ export function readAppData(appData: string | undefined): {
   }
 }
 
+function checkedLabels(value: unknown): string[] {
+  if (!Array.isArray(value) || value.some((label: unknown) => typeof label !== 'string')) {
+    throw new TrainError('INVALID_ARGS', 'labels must be an array of strings');
+  }
+  return cleanLabels(value);
+}
+
 function applyMergeKey(
   merged: Record<string, unknown>,
   k: string,
   v: unknown,
 ): void {
   if (k === 'labels') {
-    merged.labels = cleanLabels(v);
+    merged.labels = checkedLabels(v);
+    return;
+  }
+  if (k === 'assigned') {
+    merged.assigned = normalizeAssigned(v);
     return;
   }
   if (k === 'github') {
@@ -87,19 +123,25 @@ function applyMergeKey(
     return;
   }
   if (v === undefined || v === null) Reflect.deleteProperty(merged, k);
-  else merged[k] = v;
+  else Object.defineProperty(merged, k, { value: v, enumerable: true, configurable: true, writable: true });
 }
 
 export function mergeAppData(
   existingAppData: string | undefined,
   patch: Record<string, unknown>,
 ): { blob: string; merged: Record<string, unknown> } {
-  const merged: Record<string, unknown> = {
-    ...parseAppDataObject(existingAppData),
-    v: 1,
-  };
-  for (const [k, v] of Object.entries(patch)) applyMergeKey(merged, k, v);
-  return { blob: JSON.stringify(merged), merged };
+  const current = readAppDataObject(existingAppData);
+  const checked = metadataPatch(patch);
+  if (Object.hasOwn(checked, 'assigned') && Object.hasOwn(current, 'assigned')) {
+    normalizeAssigned(current.assigned);
+  }
+  const merged: Record<string, unknown> = { v: 1, ...current };
+  for (const [k, v] of Object.entries(checked)) applyMergeKey(merged, k, v);
+  const blob = JSON.stringify(merged);
+  if (Buffer.byteLength(blob, 'utf8') > MAX_APP_DATA_BYTES) {
+    throw new TrainError('INVALID_ARGS', `Channel appData exceeds ${MAX_APP_DATA_BYTES} bytes`);
+  }
+  return { blob, merged };
 }
 
 export function normalizeGithubUrl(url: unknown): string {

package/runtime/node_modules/@metro-labs/xmtp/src/tools-handlers.ts

@@ -1,5 +1,6 @@
 import type { CanonicalAttachment, ToolContext } from '@metro-labs/core/stations/types';
 import { TrainError } from '@metro-labs/core/train-error';
+import { metadataPatch, mergeAppData } from './labels.js';
 import {
   guessMime,
   isImageMime,
@@ -9,24 +10,34 @@ import {
 
 export const str = (v: unknown): string => (typeof v === 'string' ? v : '');
 
+function channelAppData(a: Record<string, unknown>): Record<string, unknown> {
+  const appData = a.metadata === undefined ? {} : { ...metadataPatch(a.metadata) };
+  for (const key of ['labels', 'github', 'preview']) {
+    if (!Object.hasOwn(a, key)) continue;
+    if (Object.hasOwn(appData, key)) {
+      throw new TrainError('INVALID_ARGS', `Specify ${key} only once, inside metadata or at the top level`);
+    }
+    appData[key] = a[key];
+  }
+  mergeAppData(undefined, appData);
+  return appData;
+}
+
 export async function setChannelMetadata(
   a: Record<string, unknown>,
   ctx: ToolContext,
 ) {
   const line = str(a.line);
   if (!line) return ctx.err('set_channel_metadata requires `line`');
-  const labels = a.labels as unknown[] | undefined;
-  const github = a.github as string | undefined;
-  const preview = a.preview as string | undefined;
-  const metaName = a.name as string | undefined;
-  const appData: Record<string, unknown> = {};
-  if (Array.isArray(labels)) appData.labels = labels.map(String);
-  if (typeof github === 'string') appData.github = github;
-  if (typeof preview === 'string') appData.preview = preview;
+  if (Object.hasOwn(a, 'name') && typeof a.name !== 'string') {
+    return ctx.err('set_channel_metadata name must be a string');
+  }
+  const appData = channelAppData(a);
+  const metaName = a.name;
   const hasName = typeof metaName === 'string' && metaName.length > 0;
   if (!hasName && Object.keys(appData).length === 0)
     return ctx.err(
-      'set_channel_metadata requires at least one of `labels`, `github`, `preview`, `name`',
+      'set_channel_metadata requires at least one of `metadata`, `github`, `preview`, `name`, `labels`',
     );
   const callArgs: Record<string, unknown> = { line, appData };
   if (hasName) callArgs.name = metaName;

package/runtime/node_modules/@metro-labs/xmtp/src/tools.ts

@@ -115,7 +115,9 @@ export const XMTP_TOOLS: StationTool[] = [
     description:
       "Read an XMTP channel's current metadata + membership. Args: line (required). Returns " +
       '{line, id, account, version (dm|group), name, memberCount, labels, github, preview, ' +
-      'members:[{inboxId, address}]}. xmtp-only (daemon `groupInfo`). Use before ' +
+      'assigned, appData (stored JSON object), rawAppData (stored JSON string), ' +
+      'members:[{inboxId, address}]}. Syncs first and fails if metadata cannot be read. ' +
+      'xmtp-only (daemon `groupInfo`). Use before ' +
       'set_channel_metadata/add_members to see current state.',
     inputSchema: {
       type: 'object',
@@ -167,17 +169,36 @@ export const XMTP_TOOLS: StationTool[] = [
     group: 'write',
     description:
       "Update an existing channel's metadata. Args: line (required, the metro:// line), and " +
-      'any of labels? (string[]), github? (url), preview? (url), name? (string). All provided ' +
-      'fields go in one updateChannelMeta call: the name first, then the labels and links ' +
-      'merged into the group appData. xmtp-only ' +
-      '(channel metadata lives on xmtp groups). Returns the updated channel info.',
+      'any of metadata? (JSON object), github? (url), preview? (url), name? (string). ' +
+      'metadata is a shallow appData patch: omitted keys are preserved, supplied nested ' +
+      'values replace that key, and null deletes custom keys. v is reserved. Put labels ' +
+      'and assigned inside metadata. assigned replaces the array with normalized lowercase ' +
+      'Ethereum addresses of current members. Read group_info and union existing IDs to ' +
+      'add assignees. labels remains a legacy top-level alias. Duplicate top-level/metadata ' +
+      'label/link aliases are refused. All fields use one updateChannelMeta call. xmtp-only. ' +
+      'Returns updated metadata. Reread group_info to verify persistence.',
     inputSchema: {
       type: 'object',
       properties: {
         line: lineProp,
+        metadata: {
+          type: 'object',
+          description: 'Shallow JSON appData patch. Omitted keys stay unchanged. v is reserved.',
+          properties: {
+            labels: { type: 'array', items: { type: 'string' } },
+            assigned: {
+              type: 'array',
+              description: 'Replacement assignee list. Current member Ethereum addresses only. [] clears.',
+              items: { type: 'string', pattern: '^0x[0-9a-fA-F]{40}$' },
+            },
+            github: { type: 'string' },
+            preview: { type: 'string' },
+          },
+          additionalProperties: true,
+        },
         labels: {
           type: 'array',
-          description: 'Status labels to set.',
+          description: 'Legacy alias. Prefer metadata.labels.',
           items: { type: 'string' },
         },
         github: {

package/runtime/runtime.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.1.0-beta.225"
+  "version": "0.1.0-beta.226"
 }