@stage-labs/metro 0.1.0-beta.231 → 0.1.0-beta.232

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage-labs/metro",
-  "version": "0.1.0-beta.231",
+  "version": "0.1.0-beta.232",
   "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.231",
+  "version": "0.1.0-beta.232",
   "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

@@ -1,6 +1,6 @@
 ---
 name: stage
-description: How to use Stage channels (XMTP groups, https://stage.box) through metro. Create a channel, rename it, add or remove members, set labels and assignees, read its info, and send, reply, react, unreact, delete and read messages. Works only when this agent has an XMTP account in metro.
+description: How to use Stage channels (XMTP groups, https://stage.box) through metro. Create a channel, rename it, add or remove members, set labels and assignees, read its info, and send, reply, react, unreact, delete and read messages, and post frames (interactive ChatKit widget views). Works only when this agent has an XMTP account in metro.
 ---
 
 Stage (https://stage.box) is a messenger built on XMTP. A Stage channel is an XMTP group. You use it with the metro tools below (`mcp__metro__<name>`).
@@ -40,3 +40,20 @@ Move it from Backlog or To-do to In progress, then In review, then Done. Use Blo
 - History: `read {"line": "…", "limit": 20}`.
 - Poll: `ask {"line": "…", "question": "Ship today?", "options": ["Yes", "No"]}`.
 - 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 it in the chat as a card with a title and a description, and opens it full screen on a tap.
+- Send: `send_frame {"line": "…", "title": "Deploy", "description": "Version 2.4 is ready", "widget": {…}}`. `title` and `description` are optional: they come from the first `Title` and text in the widget when missing.
+- `widget` is OpenAI ChatKit widget JSON, with ChatKit's names and props (https://openai.github.io/chatkit-js/): a `Card`, `ListView` or `Basic` root, with `Row`, `Col`, `Box`, `Text`, `Title`, `Caption`, `Markdown`, `Badge`, `Icon`, `Image`, `Button`, `Divider`, `Spacer`, `Form`, `Input`, `Textarea`, `Select`, `DatePicker`, `Checkbox`, `RadioGroup` and `Table`. Images must be `https://`. Number spacing is in steps of 4px. At most 64K characters, 16 levels deep and 500 nodes. Stage shows a small notice for anything it does not know.
+- Example:
+  ```json
+  {"type": "Card", "children": [
+    {"type": "Title", "value": "Deploy version 2.4?"},
+    {"type": "Text", "value": "3 fixes, no migration.", "color": "secondary"},
+    {"type": "Input", "name": "note", "placeholder": "Note (optional)"},
+    {"type": "Row", "children": [
+      {"type": "Button", "label": "Deploy", "onClickAction": {"type": "deploy", "payload": {"version": "2.4"}}},
+      {"type": "Button", "label": "Not now", "color": "secondary", "onClickAction": {"type": "deploy.cancel"}}
+    ]}
+  ]}
+  ```
+- A tap comes back to you as a reply to the frame: `Frame action: deploy {"version":"2.4","note":"…"} (tapped "Deploy")`. The values of the fields (`Input`, `Select`, `Checkbox`, …) are added to the payload by their `name`. `Button.onClickAction`, `ListViewItem.onClickAction`, a `Card` `confirm`/`cancel` (`{"label", "action"}`) and a `Form` `onSubmitAction` send one. Answer it like any message.

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

@@ -160,7 +160,10 @@ const PRIOR_METRO: ReadonlySet<string> = new Set([
   '5ce3f76d610aae91adc922d0edc6c8be1f27aa2fec4a5e3a6d6231a04fb9310b',
   'b910597d24f31fa479b130a2545f94dd23684d802d99e36b637fc57c818a33be',
 ]);
-const PRIOR_STAGE: ReadonlySet<string> = new Set(['dd7d30474765de3865ddc87c1cf3220161ded09502027cdff18597e5df0aab43']);
+const PRIOR_STAGE: ReadonlySet<string> = new Set([
+  'dd7d30474765de3865ddc87c1cf3220161ded09502027cdff18597e5df0aab43',
+  '47439ecbe661ca70471a6839ab30a963714c296ad8c14ca23c6eebc3929038cc',
+]);
 const PRIOR_MEMORY: ReadonlySet<string> = new Set();
 
 interface ShippedSkill {

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

@@ -12,7 +12,8 @@ import {
 import { convOf, type Account } from './accounts.js';
 import { resolveMsgId } from './wire.js';
 import { emitOutbound } from './emit.js';
-import { PollCodec, buildPollContent, encodeDeleteMessage } from './codecs.js';
+import { FrameCodec, PollCodec, buildPollContent, encodeDeleteMessage } from './codecs.js';
+import { buildFrameContent } from './frames.js';
 import { convHandlers } from './actions-conv.js';
 import { messagingAliases } from '@metro-labs/core/stations/messaging-normalize';
 import { TrainError } from '@metro-labs/core/train-error';
@@ -48,6 +49,16 @@ async function ask(id: string, args: Args): Promise<void> {
   respond(id, { result: { messageId: sentId, pollId: mintedId } });
 }
 
+async function sendFrame(id: string, args: Args): Promise<void> {
+  const { line } = args as { line: string };
+  const { acct, conv } = await convOf(line);
+  if (!conv) throw noConv(line);
+  const { frame, title } = buildFrameContent(args);
+  const sentId = await conv.send(new FrameCodec().encode(frame));
+  emitOutbound(acct.cfg.id, line, sentId, `Frame: ${title}`);
+  respond(id, { result: { messageId: sentId, title } });
+}
+
 async function referenceInboxOf(conv: Conversation, xmtpMsgId: string): Promise<string> {
   const recent = await conv.messages({ limit: 200, direction: 1 });
   const inbox = recent.find((m) => m.id === xmtpMsgId)?.senderInboxId;
@@ -211,6 +222,7 @@ const handlers: Record<string, (id: string, args: Args) => Promise<void>> = {
   resolve_sender: resolveSenderAction,
   send,
   ask,
+  sendFrame,
   react,
   reply,
   delete: remove,

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

@@ -164,6 +164,40 @@ export const SignatureReferenceCodec =
     c.signature ? `[Signature] ${c.signature}` : '[Signature]',
   );
 
+export const ContentTypeFrame: ContentTypeId = {
+  authorityId: 'stage.box',
+  typeId: 'frame',
+  versionMajor: 1,
+  versionMinor: 0,
+};
+export interface FrameContent {
+  title?: string;
+  description?: string;
+  widget: Record<string, unknown>;
+}
+export const frameFallback = (c: FrameContent): string => {
+  const head = c.title ? `Frame: ${c.title}` : 'Frame';
+  return c.description ? `${head}\n${c.description}` : head;
+};
+export const FrameCodec = makeJsonCodec<FrameContent>(ContentTypeFrame, frameFallback);
+
+export const ContentTypeFrameAction: ContentTypeId = {
+  authorityId: 'stage.box',
+  typeId: 'frameAction',
+  versionMajor: 1,
+  versionMinor: 0,
+};
+export interface FrameActionContent {
+  frameId: string;
+  action: { type: string; payload?: Record<string, unknown> };
+  label?: string;
+}
+export const frameActionText = (c: FrameActionContent): string => {
+  const payload = c.action.payload === undefined ? '' : ` ${JSON.stringify(c.action.payload)}`;
+  return `Frame action: ${c.action.type}${payload}`;
+};
+const FrameActionCodec = makeJsonCodec<FrameActionContent>(ContentTypeFrameAction, frameActionText);
+
 const ContentTypeDeleteMessage: ContentTypeId = {
   authorityId: 'xmtp.org',
   typeId: 'deleteMessage',
@@ -195,4 +229,6 @@ export const CODECS = (): ContentCodec[] => [
   new PollCodec(),
   new SignatureRequestCodec(),
   new SignatureReferenceCodec(),
+  new FrameCodec(),
+  new FrameActionCodec(),
 ];

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

@@ -9,6 +9,8 @@ import {
 } from './attachments.js';
 import { reportAttachment } from '@metro-labs/core/stations/train-events';
 import { sentByMe } from './wire.js';
+import { frameActionText, frameFallback, type FrameContent } from './codecs.js';
+import { asFrameAction } from './frames.js';
 
 export interface EnvelopeCtx {
   accountId: string;
@@ -300,6 +302,32 @@ function refEnvelope(
   return undefined;
 }
 
+function frameEnvelope(
+  base: Record<string, unknown>,
+  typeId: string,
+  c: object,
+): Record<string, unknown> | undefined {
+  if (typeId === 'frame') {
+    const f = c as Partial<FrameContent>;
+    const frame: FrameContent = {
+      ...(typeof f.title === 'string' ? { title: f.title } : {}),
+      ...(typeof f.description === 'string' ? { description: f.description } : {}),
+      widget: typeof f.widget === 'object' && f.widget !== null ? f.widget : {},
+    };
+    return { ...base, text: frameFallback(frame), payload: { contentType: typeId, frame: c } };
+  }
+  const a = typeId === 'frameAction' ? asFrameAction(c) : undefined;
+  if (!a) return undefined;
+  const label = a.label ? ` (tapped "${a.label}")` : '';
+  return {
+    ...base,
+    text: `${frameActionText(a)}${label}`,
+    event: { type: 'reply', replyTo: a.frameId },
+    ...(sentByMe(a.frameId) ? { reply_to_self: true } : {}),
+    payload: { contentType: typeId, frameAction: a, replyTo: a.frameId },
+  };
+}
+
 export function typedEnvelope(
   base: Record<string, unknown>,
   typeId: string | undefined,
@@ -311,6 +339,7 @@ export function typedEnvelope(
   if (typeId === 'poll') return pollPayload(base, typeId, c);
   return (
     attachmentEnvelope(base, typeId ?? '', c, ctx) ??
-    refEnvelope(base, typeId, c)
+    refEnvelope(base, typeId, c) ??
+    frameEnvelope(base, typeId ?? '', c)
   );
 }

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

@@ -0,0 +1,95 @@
+import { TrainError } from '@metro-labs/core/train-error';
+import type { FrameActionContent, FrameContent } from './codecs.js';
+
+export const FRAME_MAX_CHARS = 64 * 1024;
+const MAX_TITLE = 200;
+const MAX_DESCRIPTION = 1000;
+const SUMMARY_SCAN = 80;
+const TEXT_TYPES = new Set(['Text', 'Caption', 'Markdown']);
+
+type Node = Record<string, unknown>;
+
+const isNode = (v: unknown): v is Node =>
+  typeof v === 'object' && v !== null && !Array.isArray(v);
+
+const bad = (message: string): TrainError => new TrainError('INVALID_ARGS', message);
+
+function plain(value: unknown): string {
+  if (typeof value !== 'string') return '';
+  return value
+    .replace(/!?\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/^\s*(?:#{1,6}|>)\s*/gm, '')
+    .replace(/[*_`~]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function childrenOf(node: Node): Node[] {
+  const c = node.children;
+  if (Array.isArray(c)) return c.filter(isNode);
+  return isNode(c) ? [c] : [];
+}
+
+export function frameSummary(widget: Node): { title?: string; description?: string } {
+  const titles: string[] = [];
+  const texts: string[] = [];
+  const stack: Node[] = [widget];
+  for (let seen = 0; stack.length > 0 && seen < SUMMARY_SCAN; seen += 1) {
+    const node = stack.pop();
+    if (!node) break;
+    const value = plain(node.value);
+    if (node.type === 'Title' && value) titles.push(value);
+    if (typeof node.type === 'string' && TEXT_TYPES.has(node.type) && value) texts.push(value);
+    stack.push(...childrenOf(node).reverse());
+  }
+  const title = titles[0] ?? texts[0];
+  return { title, description: texts.find((t) => t !== title) };
+}
+
+function clip(value: unknown, max: number, name: string): string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== 'string') throw bad(`send_frame ${name} must be a string`);
+  const out = value.trim().slice(0, max);
+  return out === '' ? undefined : out;
+}
+
+function parseWidget(raw: unknown): Node {
+  let widget = raw;
+  if (typeof raw === 'string') {
+    try {
+      widget = JSON.parse(raw);
+    } catch {
+      throw bad('send_frame widget is not valid JSON');
+    }
+  }
+  if (!isNode(widget) || typeof widget.type !== 'string' || widget.type === '')
+    throw bad('send_frame widget must be a ChatKit widget object with a `type` (Card, ListView or Basic)');
+  const chars = JSON.stringify(widget).length;
+  if (chars > FRAME_MAX_CHARS)
+    throw bad(`send_frame widget is ${chars} characters; the limit is ${FRAME_MAX_CHARS}`);
+  return widget;
+}
+
+export function buildFrameContent(args: Record<string, unknown>): { frame: FrameContent; title: string } {
+  const widget = parseWidget(args.widget);
+  const derived = frameSummary(widget);
+  const title = clip(args.title, MAX_TITLE, 'title') ?? derived.title?.slice(0, MAX_TITLE);
+  const description = clip(args.description, MAX_DESCRIPTION, 'description') ?? derived.description?.slice(0, MAX_DESCRIPTION);
+  const frame: FrameContent = {
+    ...(title ? { title } : {}),
+    ...(description && description !== title ? { description } : {}),
+    widget,
+  };
+  return { frame, title: title ?? 'Frame' };
+}
+
+export function asFrameAction(c: object): FrameActionContent | undefined {
+  const v = c as Partial<FrameActionContent>;
+  if (typeof v.frameId !== 'string' || !isNode(v.action) || typeof v.action.type !== 'string') return undefined;
+  const payload = isNode(v.action.payload) ? v.action.payload : undefined;
+  return {
+    frameId: v.frameId,
+    action: payload ? { type: v.action.type, payload } : { type: v.action.type },
+    ...(typeof v.label === 'string' && v.label ? { label: v.label } : {}),
+  };
+}

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

@@ -79,6 +79,46 @@ export const XMTP_TOOLS: StationTool[] = [
       return ctx.okJson(await ctx.call('ask', args));
     },
   },
+  {
+    name: 'send_frame',
+    group: 'write',
+    description:
+      'Post a frame in a Stage conversation: a small interactive view described in OpenAI ChatKit ' +
+      'widget JSON (the same nodes and props as ChatKit: a Card, ListView or Basic root with Row, Col, ' +
+      'Box, Text, Title, Caption, Markdown, Badge, Icon, Image, Button, Divider, Spacer, Form, Input, ' +
+      'Textarea, Select, DatePicker, Checkbox, RadioGroup, Table...). Stage shows it in the chat as a card ' +
+      '(title and description) that opens full screen. A tap on a Button onClickAction, a ListViewItem ' +
+      'onClickAction, a Card confirm/cancel or a Form submit comes back to you as a reply to the frame: ' +
+      '"Frame action: <type> <payload JSON>", with the values of the form fields added to the payload by ' +
+      'name. Images must be https. Args: line (required), widget (required, the ChatKit widget object, at ' +
+      'most 64K characters of JSON), title? and description? (shown on the card; taken from the first ' +
+      'Title and text in the widget when missing). xmtp-only. Returns the frame messageId.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        line: lineProp,
+        widget: {
+          type: 'object',
+          description:
+            'ChatKit widget JSON, e.g. {"type":"Card","children":[{"type":"Title","value":"Deploy?"},' +
+            '{"type":"Button","label":"Ship it","onClickAction":{"type":"deploy","payload":{"env":"prod"}}}]}.',
+          additionalProperties: true,
+        },
+        title: { type: 'string', description: 'Card title in the chat (200 characters at most).' },
+        description: { type: 'string', description: 'Card description in the chat (1000 characters at most).' },
+      },
+      required: ['line', 'widget'],
+    },
+    async handle(a, ctx) {
+      const line = str(a.line);
+      if (!line) return ctx.err('send_frame requires `line`');
+      if (a.widget === undefined) return ctx.err('send_frame requires `widget`');
+      const args: Record<string, unknown> = { line, widget: a.widget };
+      if (a.title !== undefined) args.title = a.title;
+      if (a.description !== undefined) args.description = a.description;
+      return ctx.okJson(await ctx.call('sendFrame', args));
+    },
+  },
   {
     name: 'dm',
     group: 'write',

package/runtime/runtime.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.1.0-beta.231"
+  "version": "0.1.0-beta.232"
 }