@underdogai/mesh-app-sdk 0.4.0 → 0.8.0

package/src/runtime.ts

@@ -12,11 +12,14 @@ import {
   EventType,
   NS,
   buildUiActionContent,
+  buildUiActionResult,
   buildUiMessageContent,
   buildUiMessageEdit,
   canPublish,
   classifySender,
   validateEvent,
+  type UiActionClient,
+  type UiActionResultContent,
   type UiCardContent,
   type WorkflowStateContent,
 } from "@underdogai/mesh-event-schemas";
@@ -49,7 +52,17 @@ export type Effect =
   // 발행 계열(외부 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> };
+  | { kind: "invoke"; actionId: string; values: Record<string, unknown>; label?: string }
+  /**
+   * 액션 한 건의 판정 결과를 **누른 사람에게** 되돌린다(0.7.0 — `org.corp.ui.action.result`).
+   *
+   * 선언은 "무엇을 말하는가"만 담는다: 수신자(`to`)·카드 이벤트·액션 참조는 **호스트가 채운다**
+   * (핸들러는 자기가 어떤 이벤트에 응답 중인지 알 필요가 없다 — `edit` 가 `cardEventId` 를 모르는 것과 같다).
+   */
+  | { kind: "result"; result: ActionResult };
+
+/** `ctx.result(...)` 가 받는 것 — 와이어에서 호스트가 채우는 네 키를 뺀 나머지. */
+export type ActionResult = Omit<UiActionResultContent, "v" | "to" | "card_event_id" | "m.relates_to">;
 
 /**
  * 호스트가 주입하는 백엔드 핸들 — 핸들러가 "권위 데이터를 읽고 → 판단 → 효과 선언"(read-then-decide)할 때 쓴다.
@@ -86,6 +99,8 @@ export interface ActionCtx {
   cardId?: string;
   /** 폼 입력(원본). 핸들러는 action.values.parse(ctx.values) 로 타입 확보. */
   values: Record<string, unknown>;
+  /** 작성 클라이언트 환경(있으면, G6) — 클라의 자기 신고라 표시·진단용이지 권위 아님(권위는 sender). */
+  client?: UiActionClient;
   /** 편집 대상 원본 카드 event_id(있으면). */
   cardEventId?: string;
   /** 호스트 주입 백엔드(있으면) — 권위 데이터 read-then-decide. 없으면 write-only(증명/오프라인). */
@@ -116,11 +131,31 @@ export interface ActionCtx {
   emit(type: string, content: Record<string, unknown>, opts?: EmitOptions): void;
   /**
    * 효과 선언 헬퍼 — 다른 앱의 액션을 이름으로 호출한다(invoke = UI 없이 org.corp.ui.action 발행).
+   * `opts.label` 은 사람이 읽는 이름(액션 로그가 action_id 대신 보인다) — 카드 버튼의 글자에 해당하는 것을 앱이 준다.
    * 받는 쪽은 버튼에서 왔는지 봇이 보냈는지 구분하지 않는다. action_id 접두사(<app>.)가 라우팅 주소다.
    */
-  invoke(actionId: string, values?: Record<string, unknown>): void;
+  invoke(actionId: string, values?: Record<string, unknown>, opts?: { label?: string }): void;
+  /**
+   * 효과 선언 헬퍼 — 이 액션의 **판정 결과를 누른 사람에게** 되돌린다(0.7.0).
+   *
+   *   ctx.result({ kind: "reject", errors: { due: "오늘 이후여야 해요" } })
+   *   ctx.result({ kind: "denied", reason: "현재 수신자만 처리할 수 있어요" })
+   *   ctx.result({ kind: "ok", message: "확인 처리됨" })
+   *   ctx.result({ kind: "options", name: "to", options: [...] })   // 동적 후보(select source:query)
+   *
+   * 🔴 **`send` 로 오류 카드를 쌓던 자리를 대신한다** — 결과가 방이 아니라 누른 사람의 그 컨트롤로 간다.
+   * ⚠️ 한 핸들러가 `result` 를 여러 번 내면 **마지막 것만** 남는다(같은 액션에 대한 판정이 여럿일 수
+   *    없다 — 클라 인덱스도 같은 규칙으로 최신 하나만 그린다). 효과 배열에는 그대로 쌓이지만
+   *    `applyEffects` 가 마지막 하나만 보낸다.
+   * ⚠️ `card_id`·`action_id` 는 안 줘도 된다 — 지금 처리 중인 액션의 것을 SDK 가 채운다.
+   */
+  result(r: PartialActionResult): void;
 }
 
+/** `ctx.result(...)` 의 인자 — `card_id`/`action_id` 는 SDK 가 채우므로 생략할 수 있다. */
+export type PartialActionResult = Omit<ActionResult, "card_id" | "action_id"> &
+  Partial<Pick<ActionResult, "card_id" | "action_id">>;
+
 export type ActionHandler = (ctx: ActionCtx) => void | Promise<void>;
 
 /** 호스트가 주입하는 권한 게이트(= appservice-agent/policy.evaluateAction 의 얇은 래퍼). */
@@ -153,6 +188,17 @@ export interface DispatchInput {
   stateReader?: (type: string, stateKey: string) => Promise<Record<string, unknown> | null>;
   /** 호스트 주입 앱 정책 설정(선택) — ctx.config 로 핸들러에 전달(예: { approvalThreshold }). */
   config?: Record<string, unknown>;
+  /**
+   * 값 검증 실패·권한 거절에 **결과 효과를 자동으로 붙일지**(기본 true, 0.7.0).
+   *
+   * 왜 기본이 켬인가: 이 두 경로는 지금까지 **핸들러에 도달조차 안 했다** — 앱 코드가 개입할 자리가
+   * 없어서 사용자는 아무 반응도 못 봤다(`ignored`) 또는 앱이 따로 오류 카드를 쌓았다. 자동으로 붙이면
+   * **앱을 한 줄도 안 고치고** 옛 앱의 거절·검증 실패가 누른 사람의 그 컨트롤로 인라인 회신된다.
+   *
+   * 끄는 경우: 결과 문구를 앱이 전부 소유하고 싶거나(전환기 중복 방지), 증명 스크립트가 효과 배열을
+   * 엄격히 재는 경우.
+   */
+  autoResult?: boolean;
 }
 
 export interface DispatchResult {
@@ -169,9 +215,14 @@ export async function dispatchAction(input: DispatchInput): Promise<DispatchResu
     return { status: "ignored", reason: "publish_forbidden", effects: [] };
   }
   // 2) 레지스트리 검증 — 스키마 불일치/알 수 없는 타입이면 무시.
+  //    🔴 status 는 그대로 "ignored" 다(핸들러는 안 돈다). 달라진 건 **말해 준다**는 것뿐이다:
+  //    스키마 불일치는 거의 항상 사용자가 채운 값의 문제라, 누른 사람의 그 필드 아래에 문장이 가야 한다.
+  //    안 그러면 지금처럼 버튼을 눌러도 화면에 아무 일도 일어나지 않는다.
   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> };
+  if (!v.ok) {
+    return { status: "ignored", reason: v.reason, effects: rejectEffects(input, v.issues) };
+  }
+  const action = v.data as { card_id: string; action_id: string; values?: Record<string, unknown>; client?: UiActionClient };
 
   // 3) 앱이 아는 액션인가.
   const def = input.app.actions.get(action.action_id);
@@ -187,7 +238,23 @@ export async function dispatchAction(input: DispatchInput): Promise<DispatchResu
     capability: input.capability,
   });
   if (!decision.allowed) {
-    return { status: "denied", actionId: action.action_id, reason: decision.reason, effects: [] };
+    // 🔴 거절도 **말해 준다**. 지금까지는 status 만 denied 로 돌아가고 화면엔 아무 일도 없거나,
+    //    앱이 "수신자만 처리할 수 있어요" 카드를 방 전원에게 쌓았다. 이유는 이미 손에 있다(게이트가 준다).
+    const effects: Effect[] =
+      input.autoResult === false
+        ? []
+        : [
+            {
+              kind: "result",
+              result: {
+                card_id: action.card_id,
+                action_id: action.action_id,
+                kind: "denied",
+                reason: decision.reason,
+              },
+            },
+          ];
+    return { status: "denied", actionId: action.action_id, reason: decision.reason, effects };
   }
 
   // 5) 핸들러 실행 — 효과 수집(부작용은 호스트가 적용).
@@ -200,6 +267,7 @@ export async function dispatchAction(input: DispatchInput): Promise<DispatchResu
       entity: input.entity ?? {},
       cardId: action.card_id,
       values: action.values ?? {},
+      client: action.client,
       cardEventId: input.cardEventId,
       // backend 는 이 액션이 선언한 tools 화이트리스트로 감싼다(confused-deputy 방어, fail-closed).
       backend: guardBackend(def, input.backend),
@@ -212,12 +280,60 @@ export async function dispatchAction(input: DispatchInput): Promise<DispatchResu
       delegate: (d) => effects.push({ kind: "delegate", intent: d.intent, payload: d.payload }),
       emit: publish.emit,
       invoke: publish.invoke,
+      result: (r) =>
+        effects.push({
+          kind: "result",
+          result: { card_id: action.card_id, action_id: action.action_id, ...r },
+        }),
     };
     await handler(ctx);
   }
   return { status: "ran", actionId: action.action_id, effects };
 }
 
+/**
+ * 스키마 불일치를 **필드별 문장**으로 바꾼다(0.7.0). zod issue 의 경로가 필드 이름을 들고 있다 —
+ * 폼 값은 `values.<name>` 아래 살므로 그 한 겹을 벗긴다(`values.due: …` → `due`).
+ *
+ * 🔴 **best-effort 다.** content 자체가 스키마를 통과하지 못한 상태라 `card_id`/`action_id` 조차
+ * 믿을 수 없다 — 둘 다 문자열로 읽히지 않으면 회신을 **포기한다**(잘못된 카드에 오류를 붙이는 것보다
+ * 아무 말도 안 하는 쪽이 낫다). 경로가 `values` 아래가 아니면(예: `action_type`) 필드로 못 붙이므로
+ * `kind: "reject"` 대신 한 줄짜리 `denied` 로 떨어뜨린다 — 사람이 고칠 수 있는 게 없는 오류라서다.
+ */
+function rejectEffects(input: DispatchInput, issues: string[] | undefined): Effect[] {
+  if (input.autoResult === false) return [];
+  const c = input.actionContent as Record<string, unknown> | null | undefined;
+  const cardId = typeof c?.card_id === "string" ? c.card_id : undefined;
+  const actionId = typeof c?.action_id === "string" ? c.action_id : undefined;
+  if (!cardId || !actionId) return [];
+
+  const errors: Record<string, string> = {};
+  const rest: string[] = [];
+  for (const issue of issues ?? []) {
+    const at = issue.indexOf(": ");
+    const path = at >= 0 ? issue.slice(0, at) : "";
+    const message = at >= 0 ? issue.slice(at + 2) : issue;
+    const segments = path.split(".").filter(Boolean);
+    // `values.<name>` → 그 필드. `values` 안쪽으로 더 깊어도(배열 인덱스 등) 첫 이름이 필드다.
+    if (segments[0] === "values" && segments[1]) errors[segments[1]] ??= message;
+    else rest.push(issue);
+  }
+  if (Object.keys(errors).length) {
+    return [{ kind: "result", result: { card_id: cardId, action_id: actionId, kind: "reject", errors } }];
+  }
+  return [
+    {
+      kind: "result",
+      result: {
+        card_id: cardId,
+        action_id: actionId,
+        kind: "denied",
+        reason: rest[0] ?? "schema_mismatch",
+      },
+    },
+  ];
+}
+
 // ---------------------------------------------------------------------------
 // 발행 헬퍼(emit/invoke) — ActionCtx/EventCtx 가 공유하는 효과 수집기
 // ---------------------------------------------------------------------------
@@ -276,14 +392,14 @@ function makePublishHelpers(
         ...(form === "state" ? { stateKey: opts?.stateKey ?? "" } : {}),
       });
     },
-    invoke(actionId, values) {
+    invoke(actionId, values, opts) {
       // 주소(<app>. 접두사) 없는 id 는 라우팅될 수 없다 — assertActionNamespace 가 보장하는 형태를 요구한다.
       if (!actionId.includes(".")) {
         throw new Error(
           `[app-sdk] invoke: action_id '${actionId}' 는 '<app>.<action>' 형태여야 합니다(접두사 = 라우팅 주소).`,
         );
       }
-      effects.push({ kind: "invoke", actionId, values: values ?? {} });
+      effects.push({ kind: "invoke", actionId, values: values ?? {}, ...(opts?.label ? { label: opts.label } : {}) });
     },
   };
 }
@@ -359,7 +475,7 @@ export interface EventCtx {
   /** 효과 선언 헬퍼 — 자기 사실을 발행한다(규칙은 ActionCtx.emit 과 동일). */
   emit(type: string, content: Record<string, unknown>, opts?: EmitOptions): void;
   /** 효과 선언 헬퍼 — 다른 앱의 액션을 호출한다(규칙은 ActionCtx.invoke 와 동일). */
-  invoke(actionId: string, values?: Record<string, unknown>): void;
+  invoke(actionId: string, values?: Record<string, unknown>, opts?: { label?: string }): void;
 }
 
 export type EventHandler = (ctx: EventCtx) => void | Promise<void>;
@@ -439,6 +555,14 @@ export interface ApplyEffectsInput {
   entity?: { type?: string; id?: string };
   /** workflow.updated_by 로 기록할 주체(보통 액션 발신자). */
   sender?: string;
+  /**
+   * `result` 효과의 **수신자**(0.7.0) — 이 액션을 누른 사람의 MXID. 없으면 결과를 보낼 곳이 없으므로
+   * 경고 후 건너뛴다(throw 하지 않는다 — 결과 회신은 부가 기능이고, 그것 때문에 뒤따르는 카드 편집이
+   * 취소되면 더 나쁘다. `workflow` 가 로그 후 계속하는 것과 같은 판단).
+   */
+  actor?: string;
+  /** `result` 효과가 가리킬 **액션** 이벤트 id(0.7.0). 없으면 `m.relates_to` 없이 보낸다(card_id 로 붙는다). */
+  actionEventId?: string;
   /**
    * delegate 효과 콜백 — stateful·교차에이전트(A2A) 프로토콜은 호스트가 소유한다. 미주입 호스트(1회 발행·
    * 단순 봇)에서 delegate 가 나오면 경고 후 무시한다(조용한 유실 방지 로그).
@@ -449,17 +573,38 @@ export interface ApplyEffectsInput {
   error?: (msg: string) => void;
 }
 
+/**
+ * 권한 거부(403 / M_FORBIDDEN) 판정 — 전송 클라이언트는 **호스트가 주입**하므로 오류 모양이 하나가 아니다
+ * (serve() 의 MatrixApiError 는 `.status`, matrix-bot-sdk 는 `body.errcode`). 어느 쪽도 못 읽으면 메시지
+ * 문자열로 떨어진다. 오판해도 손해는 "조치 문구가 안 붙는다" 뿐이라 관대하게 본다.
+ */
+function isForbidden(err: unknown): boolean {
+  const e = err as { status?: unknown; statusCode?: unknown; errcode?: unknown; body?: { errcode?: unknown } };
+  if (e?.status === 403 || e?.statusCode === 403) return true;
+  if (e?.errcode === "M_FORBIDDEN" || e?.body?.errcode === "M_FORBIDDEN") return true;
+  return /\b403\b|M_FORBIDDEN/.test(err instanceof Error ? err.message : String(err));
+}
+
 /**
  * 핸들러가 선언한 효과를 Matrix 로 적용한다 — 호스트 무관(AS 에이전트·봇 계정·증명 스크립트가 같은 코드 사용).
- * 배열 순서대로 적용한다. edit/send/emit/invoke 전송 실패는 throw(호스트가 회복 정책 소유),
- * workflow 는 상태 이벤트 특성상 로그 후 계속(agent 레거시 동작 보존 — 카드 갱신을 막지 않는다).
+ * 배열 순서대로 적용한다. edit/send/emit/invoke 전송 실패는 throw(호스트가 회복 정책 소유).
+ *
+ * `workflow` 만 예외로 **로그 후 계속**한다. 이건 관대함이 아니라 순서의 문제다: workflow 는 보통 카드
+ * 편집 **뒤에** 오는 부기(bookkeeping)라, 여기서 throw 하면 이미 사용자 화면에 반영된 작업의 나머지 효과가
+ * 취소된다 — 진짜 일(머지·승인)은 이미 끝났는데 후속 효과만 잃는 게 더 나쁘다.
+ *
+ * 대신 **조용하지는 않게** 한다: 403(봇 PL 부족)은 가장 흔한 원인이자 유일하게 사람이 고칠 수 있는
+ * 원인이라, 로그가 원인과 **조치 두 갈래**를 같이 적는다(로그만 보고 판단할 수 있게).
  */
 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) {
+  // 같은 액션의 판정은 하나뿐이다 — 핸들러가 result 를 여러 번 내면 **마지막 것만** 보낸다
+  // (클라 인덱스도 같은 규칙으로 최신 하나만 그린다. 여러 장을 보내면 화면에서 서로를 덮어 깜빡인다).
+  const lastResult = input.effects.reduce<number>((at, e, i) => (e.kind === "result" ? i : at), -1);
+  for (const [i, e] of input.effects.entries()) {
     switch (e.kind) {
       case "edit": {
         // 편집 대상 카드가 있으면 m.replace, 없으면(참조 유실) 새 카드로 graceful.
@@ -485,7 +630,17 @@ export async function applyEffects(input: ApplyEffectsInput): Promise<void> {
         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)}`);
+          // 403 은 거의 항상 "봇 PL 0 < 방 state_default 50". 원인만 찍으면 로그를 읽는 사람이 다시 추적해야 하니
+          // 조치를 같이 적는다 — 그리고 **끄는 쪽도 조치다**: 방이 엔티티 하나가 아니면(레포·팀 채널 등) 방 상태에
+          // 남길 이유가 없고, state_key 가 엔티티마다 쌓여 방 상태가 무한히 자란다.
+          const hint = isForbidden(err)
+            ? " — 봇에 방 상태 쓰기 권한이 없습니다(보통 봇 PL 0 < state_default 50)." +
+              ` 남길 값이면 방 ${input.roomId} 의 m.room.power_levels 에 events["${EventType.WorkflowState}"] 를 낮추거나 봇 PL 을 올리고,` +
+              " 아니라면 핸들러의 ctx.workflow(...) 를 지우는 쪽이 맞습니다(방=엔티티가 아닌 방에선 후자)."
+            : "";
+          error(
+            `[app-sdk] workflow.state 게시 실패 (${input.entity.id}, ${e.status}): ${err instanceof Error ? err.message : String(err)}${hint}`,
+          );
         }
         break;
       }
@@ -514,12 +669,38 @@ export async function applyEffects(input: ApplyEffectsInput): Promise<void> {
         const content = buildUiActionContent({
           card_id: `invoke:${input.app.app}`,
           action_id: e.actionId,
+          label: e.label,
           action_type: "submit",
           values: e.values,
         });
         await input.client.sendEvent(input.roomId, EventType.UiAction, content as unknown as Record<string, unknown>);
         break;
       }
+      case "result": {
+        if (i !== lastResult) break; // 마지막 판정만 나간다(위 주석).
+        if (!input.actor) {
+          // 보낼 곳을 모르면 그냥 건너뛴다 — throw 하면 이미 화면에 반영된 카드 편집까지 취소된다.
+          warn(
+            `[app-sdk] result 효과 생략 — 수신자(actor) 미해석 (action_id=${e.result.action_id}, kind=${e.result.kind}).` +
+              " 호스트가 applyEffects 에 actor(액션 발신자)를 넘겨야 합니다.",
+          );
+          break;
+        }
+        const content: UiActionResultContent = buildUiActionResult({
+          ...e.result,
+          to: input.actor,
+          ...(input.cardEventId ? { card_event_id: input.cardEventId } : {}),
+          ...(input.actionEventId
+            ? { "m.relates_to": { rel_type: "m.reference" as const, event_id: input.actionEventId } }
+            : {}),
+        });
+        await input.client.sendEvent(
+          input.roomId,
+          EventType.UiActionResult,
+          content as unknown as Record<string, unknown>,
+        );
+        break;
+      }
     }
   }
 }

package/src/serve.ts

@@ -523,15 +523,26 @@ export async function serve(app: App, opts: ServeOptions): Promise<void> {
             .catch(() => null),
         config: opts.config,
       });
+      // `actor`/`actionEventId` — `result` 효과(0.7.0)가 "누구에게, 어느 액션의 답으로" 가는지.
+      // 안 넘기면 결과 회신이 조용히 생략된다(applyEffects 가 경고만 하고 건너뛴다).
+      const effectInput = {
+        client, app, roomId, cardEventId, entity,
+        sender: ev.sender, actor: ev.sender, actionEventId: ev.event_id,
+        onDelegate: opts.onDelegate,
+      };
       // 자기 것이 아니면(unknown_action 등 ignored) 아무것도 발행하지 않는다 — 외부 앱 공존의 반쪽(§1.5의 역).
       if (res.status === "ran" && res.effects.length) {
-        await applyEffects({
-          client, app, roomId, cardEventId, entity,
-          sender: ev.sender, effects: res.effects, onDelegate: opts.onDelegate,
-        });
+        await applyEffects({ ...effectInput, effects: res.effects });
         log(`[app-sdk] 액션 실행 (${res.actionId}, effects=${res.effects.length})`);
       } else if (res.status === "denied") {
-        log(`[app-sdk] 액션 거부 (${res.actionId}): ${res.reason}`); // 거부 카드 발행 여부는 앱 정책 — 기본은 로그만.
+        // 🔴 거부도 **누른 사람에게는 말해 준다**(0.7.0) — dispatchAction 이 붙인 `result` 효과만 적용한다.
+        //    방에 거부 *카드*를 쌓을지는 여전히 앱 정책이다(기본은 안 쌓는다). 그 경계가 이 채널의 요점이다.
+        await applyEffects({ ...effectInput, effects: res.effects.filter((e) => e.kind === "result") });
+        log(`[app-sdk] 액션 거부 (${res.actionId}): ${res.reason}`);
+      } else if (res.effects.some((e) => e.kind === "result")) {
+        // 값 검증 실패(schema_mismatch) — 핸들러는 안 돌았지만 사용자는 왜 아무 일도 안 일어났는지 알아야 한다.
+        await applyEffects({ ...effectInput, effects: res.effects.filter((e) => e.kind === "result") });
+        log(`[app-sdk] 액션 무시 (${res.reason}) — 결과 회신만 보냈다`);
       }
       return;
     }