@underdogai/mesh-app-sdk 0.1.0

package/src/runtime.ts

@@ -0,0 +1,462 @@
+/**
+ * 액션 라우터 — 들어온 org.corp.ui.action 을 (멱등은 호스트가) → 발행자격(SEC-3) → 레지스트리 검증
+ * → 권한 게이트 → 핸들러 실행(효과 수집) 으로 흘린다.
+ *
+ * 보안 게이트(evaluateAction)는 SDK 가 소유하지 않고 **호스트가 주입**한다(의존성 역전) — SDK 는
+ * "어떤 액션이 어떤 scope/destructive 인지"만 게이트에 데이터로 넘긴다(보안의 권위는 서버 policy 에 그대로).
+ *
+ * 핸들러는 부작용을 직접 실행하지 않고 "효과(Effect)"를 선언한다 → 실 AS 는 matrix client 로 적용,
+ * 증명 스크립트는 효과 배열을 검사한다(같은 SDK 코드를 양쪽에서 검증 = 테스트성).
+ */
+import {
+  EventType,
+  NS,
+  buildUiActionContent,
+  buildUiMessageContent,
+  buildUiMessageEdit,
+  canPublish,
+  classifySender,
+  validateEvent,
+  type UiCardContent,
+  type WorkflowStateContent,
+} from "@underdogai/mesh-event-schemas";
+import type { App } from "./app.js";
+import type { AppAction } from "./action.js";
+
+/**
+ * 발행 형태 — 같은 사실을 어떤 Matrix 형태로 보낼지(킥오프 §2.3).
+ *  - "message": m.room.message + 카드(사람용 — 타임라인에 남고 알림도 간다). events 에 선언된 view 가 그린다.
+ *  - "event"(기본): 커스텀 이벤트 타입 그대로(기계가 읽을 사실·봇 사이 연쇄 — 남지만 조용하다).
+ *  - "state": 상태 이벤트(최신값 하나 — 방 구성·현재 상태).
+ */
+export type EmitForm = "message" | "event" | "state";
+
+export interface EmitOptions {
+  /** 발행 형태(기본 "event"). */
+  form?: EmitForm;
+  /** form:"state" 의 state_key(기본 ""). 다른 form 에선 무시된다. */
+  stateKey?: string;
+}
+
+/** 핸들러가 선언하는 효과 — 호스트가 matrix 로 적용한다. */
+export type Effect =
+  | { kind: "edit"; card: UiCardContent } // 원본 카드 m.replace 편집
+  | { kind: "send"; card: UiCardContent } // 새 카드 전송
+  | { kind: "workflow"; status: string } // org.corp.workflow.state 갱신
+  // 다른 에이전트에게 위임(예: 2차 승인 A2A). 동기 effect 모델로 표현 못 하는 stateful·교차에이전트
+  // 프로토콜(pending/timeout/result 매칭)은 호스트가 소유하고, 핸들러는 "위임한다"는 의도+페이로드만 선언한다.
+  | { kind: "delegate"; intent: string; payload: Record<string, unknown> }
+  // 발행 계열(외부 SDK Phase 1) — emit(자기 사실 발행)/invoke(타 앱 액션 호출 = UI 없는 org.corp.ui.action).
+  // 형태는 데이터로 남고, 실제 전송은 호스트가 applyEffects 로 적용한다(테스트/증명은 배열만 검사).
+  | { kind: "emit"; type: string; content: Record<string, unknown>; form: EmitForm; stateKey?: string }
+  | { kind: "invoke"; actionId: string; values: Record<string, unknown> };
+
+/**
+ * 호스트가 주입하는 백엔드 핸들 — 핸들러가 "권위 데이터를 읽고 → 판단 → 효과 선언"(read-then-decide)할 때 쓴다.
+ * SDK 는 호출 형태(도구 이름 + 구조화 인자)만 정의하고, 구현(MCP 도구/HTTP)·권한 스코프는 호스트가 소유한다
+ * (GateFn 과 같은 의존성 역전). 앱은 ctx.backend 가 있으면 권위 재조회로 쓰고, 없으면(증명/오프라인) 분기로 처리한다.
+ * ⚠️ 카드/이벤트의 ctx.values 는 신뢰하지 말고, 여기로 권위 데이터를 다시 읽는 것이 시스템-오브-레코드 원칙.
+ */
+export interface ActionBackend {
+  call<T = unknown>(tool: string, args?: Record<string, unknown>): Promise<T>;
+}
+
+export interface ActionCtx {
+  /** 홈서버가 귀속한 발신자 MXID(권위). */
+  sender: string;
+  /** 카드 context.entity (있으면) — 핸들러가 권위 데이터 재조회 키로 사용. */
+  entity: { type?: string; id?: string };
+  /** 원본 카드의 논리 card_id(action.card_id) — 편집 카드가 같은 card_id 를 유지해 같은 카드를 m.replace 하도록. */
+  cardId?: string;
+  /** 폼 입력(원본). 핸들러는 action.values.parse(ctx.values) 로 타입 확보. */
+  values: Record<string, unknown>;
+  /** 편집 대상 원본 카드 event_id(있으면). */
+  cardEventId?: string;
+  /** 호스트 주입 백엔드(있으면) — 권위 데이터 read-then-decide. 없으면 write-only(증명/오프라인). */
+  backend?: ActionBackend;
+  /**
+   * 호스트가 주입하는 앱 정책 설정(읽기 전용 데이터) — 예: finance 승인 임계값(approvalThreshold).
+   * 배포 설정(env 등)을 핸들러로 흘리는 의존성 주입 채널. 핸들러는 ctx.config?.<key> 로 읽는다(없으면 undefined).
+   */
+  config?: Record<string, unknown>;
+  /** 효과 선언 헬퍼 — 원본 카드를 편집한다(m.replace). */
+  editCard(card: UiCardContent): void;
+  /** 효과 선언 헬퍼 — 새 카드를 보낸다. */
+  send(card: UiCardContent): void;
+  /** 효과 선언 헬퍼 — 엔티티 워크플로 상태를 갱신한다. */
+  workflow(status: string): void;
+  /** 효과 선언 헬퍼 — 다른 에이전트에게 위임(intent + payload). 호스트가 A2A 프로토콜로 실행한다. */
+  delegate(d: { intent: string; payload: Record<string, unknown> }): void;
+  /**
+   * 효과 선언 헬퍼 — 사실을 커스텀 이벤트로 발행한다(emit). 자기 앱 네임스페이스(org.corp.<app>.) 밖 타입은
+   * throw(소유 강제 — 남의 사실 위조 금지, 구독은 on 으로). events 에 선언된 타입이면 스키마를 outbound-strict
+   * 로 검증하고(불일치 throw), form:"message" 는 선언된 view 가 있어야 한다.
+   */
+  emit(type: string, content: Record<string, unknown>, opts?: EmitOptions): void;
+  /**
+   * 효과 선언 헬퍼 — 다른 앱의 액션을 이름으로 호출한다(invoke = UI 없이 org.corp.ui.action 발행).
+   * 받는 쪽은 버튼에서 왔는지 봇이 보냈는지 구분하지 않는다. action_id 접두사(<app>.)가 라우팅 주소다.
+   */
+  invoke(actionId: string, values?: Record<string, unknown>): void;
+}
+
+export type ActionHandler = (ctx: ActionCtx) => void | Promise<void>;
+
+/** 호스트가 주입하는 권한 게이트(= appservice-agent/policy.evaluateAction 의 얇은 래퍼). */
+export type GateFn = (input: {
+  senderId: string;
+  actionId: string;
+  requiredScope: string;
+  destructive: boolean;
+  powerLevels: unknown;
+  capability: unknown;
+}) => { allowed: boolean; reason: string };
+
+export interface DispatchInput {
+  app: App;
+  /** 들어온 org.corp.ui.action 의 content. */
+  actionContent: unknown;
+  /** 홈서버가 귀속한 발신자 MXID(권위 — 본문 from_* 아님). */
+  sender: string;
+  powerLevels?: unknown;
+  capability?: unknown;
+  cardEventId?: string;
+  entity?: { type?: string; id?: string };
+  gate: GateFn;
+  /** 호스트 주입 백엔드(선택) — 핸들러가 권위 데이터를 읽고 분기할 때 ctx.backend 로 전달된다. */
+  backend?: ActionBackend;
+  /** 호스트 주입 앱 정책 설정(선택) — ctx.config 로 핸들러에 전달(예: { approvalThreshold }). */
+  config?: Record<string, unknown>;
+}
+
+export interface DispatchResult {
+  status: "ran" | "denied" | "ignored";
+  actionId?: string;
+  reason?: string;
+  effects: Effect[];
+}
+
+/** 액션 한 건을 라우팅한다. 게이트는 호스트가 주입(보안 권위는 서버). 효과는 호스트가 적용. */
+export async function dispatchAction(input: DispatchInput): Promise<DispatchResult> {
+  // 1) 발행 자격(SEC-3) — ui.action 은 human/agent 만(브리지 위조 거부). 서명된 sender 분류로 강제.
+  if (!canPublish(EventType.UiAction, classifySender(input.sender))) {
+    return { status: "ignored", reason: "publish_forbidden", effects: [] };
+  }
+  // 2) 레지스트리 검증 — 스키마 불일치/알 수 없는 타입이면 무시.
+  const v = validateEvent(EventType.UiAction, input.actionContent);
+  if (!v.ok) return { status: "ignored", reason: v.reason, effects: [] };
+  const action = v.data as { card_id: string; action_id: string; values?: Record<string, unknown> };
+
+  // 3) 앱이 아는 액션인가.
+  const def = input.app.actions.get(action.action_id);
+  if (!def) return { status: "ignored", reason: "unknown_action", effects: [] };
+
+  // 4) 권한 재검증 — 호스트 게이트에 액션 정의의 scope/destructive 를 데이터로 주입(서버가 최종 결정).
+  const decision = input.gate({
+    senderId: input.sender,
+    actionId: action.action_id,
+    requiredScope: def.scope,
+    destructive: def.destructive,
+    powerLevels: input.powerLevels,
+    capability: input.capability,
+  });
+  if (!decision.allowed) {
+    return { status: "denied", actionId: action.action_id, reason: decision.reason, effects: [] };
+  }
+
+  // 5) 핸들러 실행 — 효과 수집(부작용은 호스트가 적용).
+  const handler = input.app.handlers.get(action.action_id);
+  const effects: Effect[] = [];
+  if (handler) {
+    const publish = makePublishHelpers(input.app, effects);
+    const ctx: ActionCtx = {
+      sender: input.sender,
+      entity: input.entity ?? {},
+      cardId: action.card_id,
+      values: action.values ?? {},
+      cardEventId: input.cardEventId,
+      // backend 는 이 액션이 선언한 tools 화이트리스트로 감싼다(confused-deputy 방어, fail-closed).
+      backend: guardBackend(def, input.backend),
+      config: input.config,
+      editCard: (c) => effects.push({ kind: "edit", card: c }),
+      send: (c) => effects.push({ kind: "send", card: c }),
+      workflow: (status) => effects.push({ kind: "workflow", status }),
+      delegate: (d) => effects.push({ kind: "delegate", intent: d.intent, payload: d.payload }),
+      emit: publish.emit,
+      invoke: publish.invoke,
+    };
+    await handler(ctx);
+  }
+  return { status: "ran", actionId: action.action_id, effects };
+}
+
+// ---------------------------------------------------------------------------
+// 발행 헬퍼(emit/invoke) — ActionCtx/EventCtx 가 공유하는 효과 수집기
+// ---------------------------------------------------------------------------
+
+/**
+ * emit/invoke 효과 수집기를 만든다 — 두 컨텍스트(액션 핸들러·구독 핸들러)가 같은 규칙을 공유한다.
+ * emit 은 정의 시점이 아니라 *핸들러 실행 시점*에만 검증할 수 있으므로(타입/내용이 동적) 여기서 fail-fast throw
+ * 한다(outbound-strict — buildUiMessageContent 가 잘못된 블록을 거부하는 것과 같은 자세).
+ */
+function makePublishHelpers(
+  app: App,
+  effects: Effect[],
+): { emit: ActionCtx["emit"]; invoke: ActionCtx["invoke"] } {
+  return {
+    emit(type, content, opts) {
+      const form: EmitForm = opts?.form ?? "event";
+      // 소유 강제 — 이벤트 등록(register)·액션 id(assertActionNamespace)와 같은 규칙을 emit 에도 건다.
+      const prefix = `${NS}.${app.app}.`;
+      if (!type.startsWith(prefix)) {
+        throw new Error(
+          `[app-sdk] 앱 '${app.app}': emit 타입 '${type}' 가 앱 네임스페이스 '${prefix}' 밖입니다 — ` +
+            `자기 사실만 발행할 수 있습니다(남의 이벤트에 반응하려면 on 구독을 쓰세요).`,
+        );
+      }
+      const declared = app.events[type];
+      let out = content;
+      if (declared) {
+        // 선언된 타입은 outbound-strict — 스키마 불일치를 발행 전에 잡는다(구독자가 쓰레기를 받지 않게).
+        const parsed = declared.schema.safeParse(content);
+        if (!parsed.success) {
+          throw new Error(
+            `[app-sdk] 앱 '${app.app}': emit('${type}') content 가 선언 스키마와 불일치 — ${parsed.error.issues
+              .map((i) => `${i.path.join(".")}: ${i.message}`)
+              .join("; ")}`,
+          );
+        }
+        out = parsed.data as Record<string, unknown>;
+      } else if (form === "message") {
+        // message 형태는 카드를 그릴 view 가 필요하다 — 선언 없는 타입이면 그릴 방법이 없으니 즉시 알린다.
+        throw new Error(
+          `[app-sdk] 앱 '${app.app}': emit('${type}', { form: "message" }) 는 events 에 선언된(view 있는) 타입만 가능합니다.`,
+        );
+      }
+      effects.push({
+        kind: "emit",
+        type,
+        content: out,
+        form,
+        ...(form === "state" ? { stateKey: opts?.stateKey ?? "" } : {}),
+      });
+    },
+    invoke(actionId, values) {
+      // 주소(<app>. 접두사) 없는 id 는 라우팅될 수 없다 — assertActionNamespace 가 보장하는 형태를 요구한다.
+      if (!actionId.includes(".")) {
+        throw new Error(
+          `[app-sdk] invoke: action_id '${actionId}' 는 '<app>.<action>' 형태여야 합니다(접두사 = 라우팅 주소).`,
+        );
+      }
+      effects.push({ kind: "invoke", actionId, values: values ?? {} });
+    },
+  };
+}
+
+/**
+ * 액션이 선언한 tools 화이트리스트로 호스트 backend 를 감싼다(confused-deputy 방어).
+ * 핸들러가 ctx.backend.call(tool) 로 부를 수 있는 도구를 def.tools 로만 좁힌다 — 미선언/빈 배열이면
+ * 어떤 도구도 거부(fail-closed). 선언 밖 도구를 부르면 throw(1st-party 핸들러의 도구 드리프트/사고를 즉시 가시화).
+ * 강제는 SDK 가 기계적으로(선언 일치 검사), 도구 구현·권한은 호스트가 소유(의존성 역전, GateFn 과 같은 자세).
+ */
+function guardBackend(def: AppAction, raw: ActionBackend | undefined): ActionBackend | undefined {
+  if (!raw) return undefined;
+  const allowed = new Set(def.tools ?? []);
+  return {
+    call(tool, args) {
+      if (!allowed.has(tool)) {
+        throw new Error(
+          `[app-sdk] 액션 '${def.id}' 가 미선언 도구 '${tool}' 를 호출했습니다 — ` +
+            `defineAction({ tools: [...] }) 에 선언해야 합니다(confused-deputy 방지, fail-closed).`,
+        );
+      }
+      return raw.call(tool, args);
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// 구독 디스패치 (on) — "남이 낸 이벤트를 듣는다"
+// ---------------------------------------------------------------------------
+
+/** 구독 핸들러가 받는 컨텍스트 — 반응은 효과(send/emit/invoke)로만 선언한다(부작용은 호스트가 적용). */
+export interface EventCtx {
+  /** 구독한 이벤트 타입. */
+  type: string;
+  /** 이벤트가 발생한 방. */
+  roomId: string;
+  /** 홈서버가 귀속한 발신자 MXID(권위 — 본문 from_* 아님). */
+  sender: string;
+  /** 이벤트 content(레지스트리가 아는 타입이면 파싱된 값, 모르면 원본). 구독 앱이 자기 스키마로 parse 해 타입 확보. */
+  content: Record<string, unknown>;
+  /** 원본 이벤트 id(있으면). */
+  eventId?: string;
+  /** 효과 선언 헬퍼 — 새 카드를 보낸다. */
+  send(card: UiCardContent): void;
+  /** 효과 선언 헬퍼 — 자기 사실을 발행한다(규칙은 ActionCtx.emit 과 동일). */
+  emit(type: string, content: Record<string, unknown>, opts?: EmitOptions): void;
+  /** 효과 선언 헬퍼 — 다른 앱의 액션을 호출한다(규칙은 ActionCtx.invoke 와 동일). */
+  invoke(actionId: string, values?: Record<string, unknown>): void;
+}
+
+export type EventHandler = (ctx: EventCtx) => void | Promise<void>;
+
+export interface DispatchEventInput {
+  app: App;
+  /** 들어온 이벤트 타입. */
+  type: string;
+  /** 들어온 이벤트 content. */
+  content: unknown;
+  /** 홈서버가 귀속한 발신자 MXID. */
+  sender: string;
+  roomId: string;
+  eventId?: string;
+}
+
+export interface DispatchEventResult {
+  status: "ran" | "ignored";
+  reason?: string;
+  effects: Effect[];
+}
+
+/**
+ * 구독 이벤트 한 건을 라우팅한다 — 구독하지 않은 타입은 조용히 넘긴다(ignored, 거부 메시지 없음).
+ *
+ * 검증은 "로컬 지식 한정": 이 프로세스의 레지스트리가 아는 타입이면 스키마 불일치를 거르고(schema_mismatch),
+ * 모르는 타입(외부 앱의 사실)은 원본 그대로 핸들러에 넘긴다 — Matrix 는 임의 이벤트를 막지 못하므로 레지스트리는
+ * 강제가 아니라 합의 도구다(킥오프 §5). 발행 자격(canPublish) 게이트도 걸지 않는다 — 외부 봇은 human 으로
+ * 분류되어 정당한 연쇄가 막히기 때문에, 발신자 신뢰 판단은 sender 를 보고 호스트/핸들러가 한다.
+ *
+ * ⚠️ 루프 방지는 호스트 책임 — 자기(봇 계정)가 보낸 이벤트는 dispatchEvent 에 넣지 말 것(emit→on 무한 연쇄).
+ */
+export async function dispatchEvent(input: DispatchEventInput): Promise<DispatchEventResult> {
+  const handler = input.app.on.get(input.type);
+  if (!handler) return { status: "ignored", reason: "not_subscribed", effects: [] };
+  const v = validateEvent(input.type, input.content);
+  if (!v.ok && v.reason !== "unknown_type") return { status: "ignored", reason: v.reason, effects: [] };
+  const effects: Effect[] = [];
+  const publish = makePublishHelpers(input.app, effects);
+  const ctx: EventCtx = {
+    type: input.type,
+    roomId: input.roomId,
+    sender: input.sender,
+    content: (v.ok ? v.data : input.content) as Record<string, unknown>,
+    eventId: input.eventId,
+    send: (c) => effects.push({ kind: "send", card: c }),
+    emit: publish.emit,
+    invoke: publish.invoke,
+  };
+  await handler(ctx);
+  return { status: "ran", effects };
+}
+
+// ---------------------------------------------------------------------------
+// 효과 적용기 — 호스트 무관 순수 배선(agent.ts 에서 추출, Phase 1)
+// ---------------------------------------------------------------------------
+
+/**
+ * 호스트가 주입하는 최소 Matrix 전송 핸들 — matrix-bot-sdk 의 MatrixClient(및 Intent.underlyingClient)가
+ * 구조적으로 그대로 만족한다. SDK 는 이 두 메서드 외 어떤 클라이언트 능력도 요구하지 않는다.
+ */
+export interface MatrixSendClient {
+  sendEvent(roomId: string, eventType: string, content: Record<string, unknown>): Promise<unknown>;
+  sendStateEvent(roomId: string, eventType: string, stateKey: string, content: Record<string, unknown>): Promise<unknown>;
+}
+
+export interface ApplyEffectsInput {
+  /** 전송 핸들(호스트 주입) — 봇 계정 클라이언트든 AS Intent 든 무관. */
+  client: MatrixSendClient;
+  /** 효과를 선언한 앱 — emit(form:"message") 의 view 해석과 invoke 의 발신 표기(card_id)에 쓴다. */
+  app: App;
+  roomId: string;
+  effects: Effect[];
+  /** edit 효과의 원본 카드 event_id — 없으면 새 카드로 graceful(참조 유실 대비). */
+  cardEventId?: string;
+  /** workflow 효과의 엔티티(state_key=entity.id). id 없으면 workflow 는 경고 후 생략. */
+  entity?: { type?: string; id?: string };
+  /** workflow.updated_by 로 기록할 주체(보통 액션 발신자). */
+  sender?: string;
+  /**
+   * delegate 효과 콜백 — stateful·교차에이전트(A2A) 프로토콜은 호스트가 소유한다. 미주입 호스트(1회 발행·
+   * 단순 봇)에서 delegate 가 나오면 경고 후 무시한다(조용한 유실 방지 로그).
+   */
+  onDelegate?: (eff: Extract<Effect, { kind: "delegate" }>) => void | Promise<void>;
+  /** 진단 로그 훅(기본 console.warn/error) — 증명/테스트가 경고 경로를 관찰할 때 주입. */
+  warn?: (msg: string) => void;
+  error?: (msg: string) => void;
+}
+
+/**
+ * 핸들러가 선언한 효과를 Matrix 로 적용한다 — 호스트 무관(AS 에이전트·봇 계정·증명 스크립트가 같은 코드 사용).
+ * 배열 순서대로 적용한다. edit/send/emit/invoke 전송 실패는 throw(호스트가 회복 정책 소유),
+ * workflow 는 상태 이벤트 특성상 로그 후 계속(agent 레거시 동작 보존 — 카드 갱신을 막지 않는다).
+ */
+export async function applyEffects(input: ApplyEffectsInput): Promise<void> {
+  // SDK 는 런타임 환경을 가정하지 않는다(lib 에 console 없음) — 기본 로그는 globalThis.console 이 있을 때만.
+  const g = globalThis as { console?: { warn(m: string): void; error(m: string): void } };
+  const warn = input.warn ?? ((m: string) => g.console?.warn(m));
+  const error = input.error ?? ((m: string) => g.console?.error(m));
+  for (const e of input.effects) {
+    switch (e.kind) {
+      case "edit": {
+        // 편집 대상 카드가 있으면 m.replace, 없으면(참조 유실) 새 카드로 graceful.
+        const msg = input.cardEventId ? buildUiMessageEdit(input.cardEventId, e.card) : buildUiMessageContent(e.card);
+        await input.client.sendEvent(input.roomId, "m.room.message", msg);
+        break;
+      }
+      case "send":
+        await input.client.sendEvent(input.roomId, "m.room.message", buildUiMessageContent(e.card));
+        break;
+      case "workflow": {
+        if (!input.entity?.id) {
+          warn(`[app-sdk] workflow 효과 생략 — 엔티티 id 미해석 (status=${e.status})`);
+          break;
+        }
+        const content: WorkflowStateContent = {
+          v: 1,
+          status: e.status,
+          entity: { type: input.entity.type ?? "entity", id: input.entity.id },
+          updated_by: input.sender,
+          updated_at: Date.now(),
+        };
+        try {
+          await input.client.sendStateEvent(input.roomId, EventType.WorkflowState, input.entity.id, content);
+        } catch (err) {
+          error(`[app-sdk] workflow.state 게시 실패 (${input.entity.id}, ${e.status}): ${err instanceof Error ? err.message : String(err)}`);
+        }
+        break;
+      }
+      case "delegate":
+        if (input.onDelegate) await input.onDelegate(e);
+        else warn(`[app-sdk] delegate 효과 무시 — 호스트가 onDelegate 를 주입하지 않았습니다 (intent=${e.intent})`);
+        break;
+      case "emit": {
+        if (e.form === "message") {
+          // 선언 view 로 카드를 그려 m.room.message 로 — emit 시점 검증을 통과한 content 라 보통 성공한다.
+          const msg = input.app.messageForEvent(e.type, e.content);
+          if (!msg) {
+            warn(`[app-sdk] emit(message) 생략 — '${e.type}' 의 view/스키마 해석 실패`);
+            break;
+          }
+          await input.client.sendEvent(input.roomId, "m.room.message", msg);
+        } else if (e.form === "state") {
+          await input.client.sendStateEvent(input.roomId, e.type, e.stateKey ?? "", e.content);
+        } else {
+          await input.client.sendEvent(input.roomId, e.type, e.content);
+        }
+        break;
+      }
+      case "invoke": {
+        // UI 없는 호출 — 카드가 없으므로 card_id 는 발신 앱 표기(수신 라우팅은 action_id 접두사가 한다).
+        const content = buildUiActionContent({
+          card_id: `invoke:${input.app.app}`,
+          action_id: e.actionId,
+          action_type: "submit",
+          values: e.values,
+        });
+        await input.client.sendEvent(input.roomId, EventType.UiAction, content as unknown as Record<string, unknown>);
+        break;
+      }
+    }
+  }
+}