@mawaru/sdk 0.38.0 → 0.40.0

package/dist/_cli/previewCommand.js

@@ -1,21 +1,23 @@
-import { existsSync } from "node:fs";
+import { existsSync, watch } from "node:fs";
 import { join } from "node:path";
 import { parseArgs } from "node:util";
 import { requireCredentials } from "./credentials.js";
+import { openBrowser } from "./openBrowser.js";
 import { expectOk, mawaruApiFor } from "./previewApi.js";
-import { readViewFiles, resolveView } from "./previewFiles.js";
+import { kindRoot, readViewFiles, resolveView, } from "./previewFiles.js";
 import { previewSlack, SLACK_SURFACES, } from "./previewSlack.js";
-// `mawaru preview <種類>/<名前> [--case <ケース名>] [--surface running|completed] [--channel <#名前|ID>]`
+// `mawaru preview <種類>/<名前> [--case <ケース名>] [--surface running|completed] [--channel <#名前|ID>] [--once]`
 // （実行 repo のルートで実行）
 //
 // views/<種類>/<名前>/ のビューを、push せずに手元のファイルのまま確かめる。描画は mawaru API がやるので、
 // `mawaru login` のセッション（web と同じ membership）と、どのテナントのつもりで描くかの
 // MAWARU_TENANT_ID（repo の .env。create-loop スキルと同じ）が要る。
-// ファイルの集め方・cases.ts の評価・ケースの絞り込みは種類をまたいで共通で、種類ごとに「確かめ方」
-// （Slack は送る。承認ビューは repo へ移すときに足す）だけを差し替える
-// （docs/tasks/wip/Slackビューの顧客repo配置.md の「手元プレビュー」）
-const USAGE = "使い方: npx mawaru preview <種類>/<名前> [--case <ケース名>] [--surface running|completed] [--channel <#名前|チャンネル ID>]\n" +
-    "  例: npx mawaru preview slack/pr-review（views/slack/pr-review/ の cases.ts の全ケースを Slack に送る）";
+// ファイルの集め方・認証は種類をまたいで共通で、種類ごとに「確かめ方」だけを差し替える
+// （Slack は cases.ts の全ケースを Slack に送る。承認ビューは本番と同じ承認画面で開き、保存するたびに送り直す）
+// （docs/tasks/done/Slackビューの顧客repo配置.md・docs/tasks/wip/承認ビューの顧客repo配置.md の「手元プレビュー」）
+const USAGE = "使い方: npx mawaru preview <種類>/<名前> [--case <ケース名>] [--surface running|completed] [--channel <#名前|チャンネル ID>] [--once]\n" +
+    "  例: npx mawaru preview slack/pr-review（views/slack/pr-review/ の cases.ts の全ケースを Slack に送る）\n" +
+    "      npx mawaru preview human/invoice-review（承認画面で開き、保存するたびに送り直す。--once は1回送って終わる）";
 export const parsePreviewArgs = (args) => {
     const { values, positionals } = parseArgs({
         args,
@@ -24,6 +26,7 @@ export const parsePreviewArgs = (args) => {
             case: { type: "string" },
             surface: { type: "string" },
             channel: { type: "string" },
+            once: { type: "boolean" },
         },
     });
     const [target, ...extra] = positionals;
@@ -40,35 +43,12 @@ export const parsePreviewArgs = (args) => {
             ? { surface: values.surface }
             : {}),
         ...(values.channel !== undefined ? { channel: values.channel } : {}),
+        ...(values.once ? { once: true } : {}),
     };
 };
-const PREVIEWERS = {
-    slack: {
-        casesPath: "/slack-views/cases",
-        run: ({ name, files, cases, options, api, log }) => {
-            const channel = options.channel ?? process.env.MAWARU_PREVIEW_CHANNEL;
-            if (!channel) {
-                throw new Error("送り先のチャンネルを --channel か repo の .env の MAWARU_PREVIEW_CHANNEL で指定してください（#名前 かチャンネル ID）");
-            }
-            return previewSlack({
-                name,
-                files,
-                cases: cases,
-                surfaces: options.surface ? [options.surface] : SLACK_SURFACES,
-                channel,
-                api,
-                log,
-            });
-        },
-    },
-};
-// 終了コードを返す（描画に失敗したものがあれば 1）。テストはここを呼ぶ
-export const runPreviewWith = async (params) => {
-    const { root, options, api, log } = params;
-    const view = resolveView(root, options.target);
-    const files = readViewFiles(root, view);
-    const previewer = PREVIEWERS[view.kind];
-    const { cases } = expectOk("ケースの読み込み", await api("POST", previewer.casesPath, { files }));
+// Slack ビュー：cases.ts を mawaru API で評価し、絞り込んだケース×面を Slack に送る
+const previewSlackView = async ({ view, files, options, api, log, }) => {
+    const { cases } = expectOk("ケースの読み込み", await api("POST", "/views/slack/cases", { files }));
     const picked = options.case === undefined
         ? cases
         : cases.filter((c) => c.name === options.case);
@@ -77,15 +57,92 @@ export const runPreviewWith = async (params) => {
             ? "cases.ts にケースがありません"
             : `ケース「${options.case}」がありません（ある: ${cases.map((c) => c.name).join(", ")}）`);
     }
-    const failed = await previewer.run({
+    const channel = options.channel ?? process.env.MAWARU_PREVIEW_CHANNEL;
+    if (!channel) {
+        throw new Error("送り先のチャンネルを --channel か repo の .env の MAWARU_PREVIEW_CHANNEL で指定してください（#名前 かチャンネル ID）");
+    }
+    return previewSlack({
         name: view.name,
         files,
         cases: picked,
+        surfaces: options.surface ? [options.surface] : SLACK_SURFACES,
+        channel,
+        api,
+        log,
+    });
+};
+// human ノードの実装（承認画面）：ファイルを mawaru に置いて、本番と同じ承認画面（sandbox iframe）で開く。
+// cases.ts の評価は画面を開いたときに mawaru がやる。保存するたびに置き直し、開いている画面が読み直す
+const previewHuman = async ({ root, view, files, options, api, log, env, }) => {
+    const created = expectOk("プレビューの用意", await api("POST", "/previews", {
+        kind: "human",
+        name: view.name,
+        files,
+    }));
+    if (created.error) {
+        log(`✘ human/${view.name} をまとめられません\n${created.error}`);
+        return 1;
+    }
+    const url = `${env.appUrl.replace(/\/$/, "")}/previews/${created.id}?tenant=${env.tenantId}`;
+    log(`✔ human/${view.name} を開きます: ${url}`);
+    env.openUrl(url);
+    if (options.once)
+        return 0;
+    log("保存するたびに送り直します（Ctrl-C で終わる）");
+    await env.watch(kindRoot(root, "human"), async () => {
+        const res = await api("PUT", `/previews/${created.id}`, {
+            files: readViewFiles(root, view),
+        });
+        if (res.status >= 300) {
+            log(`✘ 送り直せませんでした（${res.status}）`);
+            return;
+        }
+        const { error } = res.body;
+        log(error ? `✘ まとめられません\n${error}` : "✔ 送り直しました");
+    });
+    return 0;
+};
+const PREVIEWERS = {
+    slack: previewSlackView,
+    human: previewHuman,
+};
+// 保存の監視：まとめて保存されることがあるので少し待ってから1回送る
+const watchFiles = (dir, onChange) => new Promise((resolve) => {
+    let timer;
+    let running = Promise.resolve();
+    const watcher = watch(dir, { recursive: true }, () => {
+        clearTimeout(timer);
+        timer = setTimeout(() => {
+            running = running.then(onChange);
+        }, 300);
+    });
+    process.once("SIGINT", () => {
+        watcher.close();
+        resolve();
+    });
+});
+// 終了コードを返す（描画・まとめに失敗したものがあれば 1）。テストはここを呼ぶ
+export const runPreviewWith = async (params) => {
+    const { root, options, api, log } = params;
+    const view = resolveView(root, options.target);
+    const files = readViewFiles(root, view);
+    const failed = await PREVIEWERS[view.kind]({
+        root,
+        view,
+        files,
         options,
         api,
         log,
+        env: {
+            tenantId: params.env?.tenantId ?? "",
+            appUrl: params.env?.appUrl ??
+                process.env.MAWARU_APP_URL ??
+                "https://app.mawaru.ai",
+            openUrl: params.env?.openUrl ?? openBrowser,
+            watch: params.env?.watch ?? watchFiles,
+        },
     });
-    if (failed > 0)
+    if (view.kind === "slack" && failed > 0)
         log(`失敗 ${failed} 件`);
     return failed > 0 ? 1 : 0;
 };
@@ -105,5 +162,6 @@ export const runPreview = async (args) => {
         options,
         api: mawaruApiFor(credentials, tenantId),
         log: (line) => console.log(line),
+        env: { tenantId },
     });
 };

package/dist/_cli/previewFiles.d.ts

@@ -1,5 +1,6 @@
-export declare const VIEW_KINDS: readonly ["slack"];
+export declare const VIEW_KINDS: readonly ["slack", "human"];
 export type ViewKind = (typeof VIEW_KINDS)[number];
+export declare const kindRoot: (root: string, kind: ViewKind) => string;
 export type ViewTarget = {
     kind: ViewKind;
     name: string;

package/dist/_cli/previewFiles.js

@@ -1,11 +1,16 @@
 import { readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-// 手元プレビュー（`mawaru preview`）が読む、実行 repo の views/<種類>/<名前>/ のファイル。
-// 描画は mawaru API がやるので、ここは「対象を決めてファイルを集める」だけで、種類をまたいで共通
-// （docs/tasks/wip/Slackビューの顧客repo配置.md の「手元プレビュー」）
-// 手元プレビューできるビューの種類（views/ 直下のディレクトリ名）。承認ビューを repo へ移すときに
-// "approval" を足す（previewCommand.ts の振り分けにも足す）
-export const VIEW_KINDS = ["slack"];
+// 手元プレビュー（`mawaru preview`）が読む、実行 repo のファイル：Slack ビューは views/slack/<名前>/、
+// human ノードの実装（承認画面）は nodes/human/<名前>/。描画は mawaru API がやるので、ここは
+// 「対象を決めてファイルを集める」だけで、種類をまたいで共通
+// （docs/tasks/wip/Slackビューの顧客repo配置.md・承認ビューの顧客repo配置.md の「手元プレビュー」）
+// 手元プレビューできる種類（previewCommand.ts の振り分けと揃える）と、その置き場
+export const VIEW_KINDS = ["slack", "human"];
+const KIND_ROOTS = {
+    slack: ["views", "slack"],
+    human: ["nodes", "human"],
+};
+export const kindRoot = (root, kind) => join(root, ...KIND_ROOTS[kind]);
 const dirsIn = (dir) => {
     try {
         return readdirSync(dir, { withFileTypes: true })
@@ -17,15 +22,17 @@ const dirsIn = (dir) => {
         return [];
     }
 };
-// views/<種類>/ 直下のディレクトリ（＝ビュー）。無ければ空
-export const listViews = (root) => VIEW_KINDS.flatMap((kind) => dirsIn(join(root, "views", kind)).map((name) => ({ kind, name })));
+// 種類ごとの置き場の直下のディレクトリ（`_` 始まりは部品の置き場で対象ではない）。無ければ空
+export const listViews = (root) => VIEW_KINDS.flatMap((kind) => dirsIn(kindRoot(root, kind))
+    .filter((name) => !name.startsWith("_"))
+    .map((name) => ({ kind, name })));
 const labelOf = (view) => `${view.kind}/${view.name}`;
-// 指定（views/slack/pr・slack/pr・pr）をビューに決める。一覧にあるものだけを受ける
-// （../ でディレクトリの外を読ませない）。決まらなければ、あるビューを添えて失敗する
+// 指定（views/slack/pr・slack/pr・nodes/human/review・human/review・pr）を対象に決める。一覧にあるものだけを受ける
+// （../ でディレクトリの外を読ませない）。決まらなければ、ある対象を添えて失敗する
 export const resolveView = (root, spec) => {
     const normalized = spec
         .replace(/^\.\//, "")
-        .replace(/^views\//, "")
+        .replace(/^(views|nodes)\//, "")
         .replace(/\/+$/, "");
     const views = listViews(root);
     const found = normalized.includes("/")
@@ -34,17 +41,14 @@ export const resolveView = (root, spec) => {
     if (found.length === 1 && found[0])
         return found[0];
     const known = views.length === 0
-        ? "views/ にビューがありません"
+        ? "views/slack/・nodes/human/ に対象がありません"
         : `ある対象: ${views.map(labelOf).join(", ")}`;
     throw new Error(found.length > 1
         ? `${spec} は複数の種類にあります。<種類>/<名前> で指定してください（${found.map(labelOf).join(", ")}）`
         : `${spec} が見つかりません（${known}）`);
 };
-// mawaru API へ送る files（{ ビューのディレクトリからの相対パス（/ 区切り）: 中身 }）。
-// .ts だけをサブディレクトリまで集める（上限の検証は API 側）
-export const readViewFiles = (root, view) => {
-    const dir = join(root, "views", view.kind, view.name);
-    const files = {};
+// dir の下の、拡張子が extensions のファイル（サブディレクトリも）。キーは prefix からの相対パス
+const collect = (dir, prefix, extensions, files) => {
     const walk = (relative) => {
         for (const entry of readdirSync(join(dir, relative), {
             withFileTypes: true,
@@ -54,11 +58,30 @@ export const readViewFiles = (root, view) => {
             const path = relative ? `${relative}/${entry.name}` : entry.name;
             if (entry.isDirectory())
                 walk(path);
-            else if (entry.isFile() && entry.name.endsWith(".ts")) {
-                files[path] = readFileSync(join(dir, path), "utf8");
+            else if (entry.isFile() &&
+                extensions.some((ext) => entry.name.endsWith(ext))) {
+                files[`${prefix}${path}`] = readFileSync(join(dir, path), "utf8");
             }
         }
     };
     walk("");
+};
+// mawaru API へ送る files（上限の検証は API 側）。
+// - Slack ビュー：ビューのディレクトリの .ts（キーはビューのディレクトリからの相対パス）
+// - human ノードの実装：nodes/human/<名前>/ と nodes/human/_<部品>/ の .ts / .tsx（キーは nodes/human/ からの相対パス。
+//   本番と同じく、部品は複数の human ノードで共有できる）
+export const readViewFiles = (root, view) => {
+    const kindDir = kindRoot(root, view.kind);
+    const files = {};
+    if (view.kind === "slack") {
+        collect(join(kindDir, view.name), "", [".ts"], files);
+        return files;
+    }
+    for (const dir of [
+        view.name,
+        ...dirsIn(kindDir).filter((name) => name.startsWith("_")),
+    ]) {
+        collect(join(kindDir, dir), `${dir}/`, [".ts", ".tsx"], files);
+    }
     return files;
 };

package/dist/_cli/previewSlack.d.ts

@@ -1,4 +1,4 @@
-import type { SlackViewCase } from "../slack-view.js";
+import type { SlackViewCase } from "../views/slack.js";
 import { type MawaruApi } from "./previewApi.js";
 export type SlackSurface = "running" | "completed";
 export declare const SLACK_SURFACES: SlackSurface[];

package/dist/_cli/previewSlack.js

@@ -42,7 +42,7 @@ export const previewSlack = async (params) => {
     let failed = 0;
     for (const testCase of cases) {
         for (const surface of surfaces) {
-            const result = expectOk("Slack への送信", await api("POST", "/slack-views/test-post", {
+            const result = expectOk("Slack への送信", await api("POST", "/views/slack/test-post", {
                 ...previewBodyOf(files, testCase, surface),
                 channel_id: channelId,
                 ...(thread

package/dist/_schemas/ai-manifest.d.ts

@@ -49,6 +49,7 @@ export declare const agentOfModel: (model: AiModel) => AiAgentId;
 export declare const aiInputDeclSchema: z.ZodObject<{
     schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     resume: z.ZodOptional<z.ZodBoolean>;
+    flexible: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type AiInputDecl = z.infer<typeof aiInputDeclSchema>;
 export declare const aiManifestSchema: z.ZodObject<{
@@ -87,9 +88,11 @@ export declare const aiManifestSchema: z.ZodObject<{
     inputs: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
         schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         resume: z.ZodOptional<z.ZodBoolean>;
+        flexible: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>, z.ZodPipe<z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodTransform<{
         schema: Record<string, unknown>;
         resume?: boolean | undefined;
+        flexible?: boolean | undefined;
     }, Record<string, unknown>>>]>>;
     outputs: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;

package/dist/_schemas/ai-manifest.js

@@ -65,6 +65,8 @@ export const agentOfModel = (model) => model.startsWith("claude-") ? "claude" :
 export const aiInputDeclSchema = z.object({
     schema: jsonSchemaSchema,
     resume: z.boolean().optional(),
+    // 推奨型を維持して任意の型を受ける（接続で上書きされず、適合チェックもしない）
+    flexible: z.boolean().optional(),
 });
 // 旧形式（値が素の JSON Schema）は { schema: 値 } として読む。判別は「schema キーを
 // 持つか」：JSON Schema のトップレベルに "schema" キーは現れない（メタスキーマ参照は

package/dist/_schemas/graph.d.ts

@@ -51,7 +51,13 @@ export declare const RUN_STARTER = "run_starter";
 export declare const assignMemberSchema: z.ZodUnion<readonly [z.ZodUUID, z.ZodLiteral<"run_starter">]>;
 export type AssignMember = z.infer<typeof assignMemberSchema>;
 export declare const humanConfigSchema: z.ZodObject<{
-    view: z.ZodOptional<z.ZodString>;
+    human_dir: z.ZodOptional<z.ZodString>;
+    ref: z.ZodOptional<z.ZodString>;
+    declaration: z.ZodOptional<z.ZodObject<{
+        in: z.ZodUnion<readonly [z.ZodLiteral<"T">, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+        approve: z.ZodUnion<readonly [z.ZodLiteral<"T">, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+        reject: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>>;
     assignment: z.ZodObject<{
         strategy: z.ZodDefault<z.ZodEnum<{
             fixed: "fixed";
@@ -152,6 +158,7 @@ export declare const graphNodeSchema: z.ZodObject<{
         name: z.ZodString;
         schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         resume: z.ZodOptional<z.ZodBoolean>;
+        flexible: z.ZodOptional<z.ZodBoolean>;
         side: z.ZodOptional<z.ZodEnum<{
             top: "top";
             right: "right";
@@ -193,7 +200,13 @@ export declare const graphNodeSchema: z.ZodObject<{
         ref: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     human: z.ZodOptional<z.ZodObject<{
-        view: z.ZodOptional<z.ZodString>;
+        human_dir: z.ZodOptional<z.ZodString>;
+        ref: z.ZodOptional<z.ZodString>;
+        declaration: z.ZodOptional<z.ZodObject<{
+            in: z.ZodUnion<readonly [z.ZodLiteral<"T">, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+            approve: z.ZodUnion<readonly [z.ZodLiteral<"T">, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+            reject: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strip>>;
         assignment: z.ZodObject<{
             strategy: z.ZodDefault<z.ZodEnum<{
                 fixed: "fixed";
@@ -252,6 +265,7 @@ export declare const saveGraphBodySchema: z.ZodObject<{
             name: z.ZodString;
             schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
             resume: z.ZodOptional<z.ZodBoolean>;
+            flexible: z.ZodOptional<z.ZodBoolean>;
             side: z.ZodOptional<z.ZodEnum<{
                 top: "top";
                 right: "right";
@@ -293,7 +307,13 @@ export declare const saveGraphBodySchema: z.ZodObject<{
             ref: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         human: z.ZodOptional<z.ZodObject<{
-            view: z.ZodOptional<z.ZodString>;
+            human_dir: z.ZodOptional<z.ZodString>;
+            ref: z.ZodOptional<z.ZodString>;
+            declaration: z.ZodOptional<z.ZodObject<{
+                in: z.ZodUnion<readonly [z.ZodLiteral<"T">, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+                approve: z.ZodUnion<readonly [z.ZodLiteral<"T">, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+                reject: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            }, z.core.$strip>>;
             assignment: z.ZodObject<{
                 strategy: z.ZodDefault<z.ZodEnum<{
                     fixed: "fixed";

package/dist/_schemas/graph.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
+import { humanDeclarationSchema } from "./human-manifest.js";
 import { graphPortSchema, jsonSchemaSchema, nodeKindSchema, portKeySchema, } from "./node.js";
-import { hasInboundConflict, isSchemaSubset, kindPortsViolation, resolvePortSchemas, UNDECLARED_SCHEMA, } from "./port-spec.js";
+import { connectionAccepted, hasInboundConflict, kindPortsViolation, resolvePortSchemas, UNDECLARED_SCHEMA, } from "./port-spec.js";
 // refs＝ループ変数の袋（key→任意の JSON 値。上流出力の参照（refs）.md）。
 // run 開始時に定義から複製され、全 step に全量差し込まれる。
 // key はポート key と同じ規則（^[a-z][a-z0-9_]*$）。実行系ボディ
@@ -116,10 +117,20 @@ export const assignMemberSchema = z.union([z.uuid(), z.literal(RUN_STARTER)]);
 // メンバーが tenant の membership であることの検証は保存 API 側で行う
 // （docs/tasks/backlog/Human担当者の高度化（複数人承認とラウンドロビン）.md）
 export const humanConfigSchema = z.object({
-    // 承認 UI（承認ビュー）の識別子。program_dir / ai_dir と同じ「不透明なキー」で、
-    // どのキーが実在するか・そのテナントが選べるかは保存時に mawaru 側が検証する
-    // （カタログは非公開。@mawaru/common の approval-view.ts）。省略時は標準ビュー
-    view: z.string().min(1).optional(),
+    // 実装（承認画面と入出力の宣言）の置き場所：実行 repo の nodes/human/ 直下のディレクトリ名。
+    // program_dir / ai_dir と同じ。省略時は mawaru 内蔵の標準の承認画面
+    // （docs/tasks/wip/承認ビューの顧客repo配置.md の「human ノードの実装として置く」）
+    human_dir: z
+        .string()
+        .min(1)
+        .refine((v) => !v.includes("/") && !v.includes("\\") && v !== "." && v !== "..", "human_dir は nodes/human/ 直下のディレクトリ名で指定してください")
+        .optional(),
+    // 読むブランチ（省略時はデフォルトブランチ）。publish でその先頭の commit に固定する
+    ref: z.string().min(1).optional(),
+    // 宣言の写し（in / approve / reject の型）。伝播はこれを読む。human_dir を選んだときに
+    // 一覧 API（GET /tenants/:id/github/humans）の宣言を入れる。省略すると保存時に mawaru が repo の
+    // config.json から読む（下書きに同じ human_dir の同じノードがあればその写しを保つ）
+    declaration: humanDeclarationSchema.optional(),
     assignment: z
         .object({
         strategy: z.enum(["fixed", "round_robin"]).default("fixed"),
@@ -236,8 +247,8 @@ export const graphNodeSchema = z.object({
     // 表示アイコン（全 kind 共通の任意設定。human はフロントが担当から導出するので通常設定しない）
     icon: nodeIconSchema.optional(),
     // Slack ビュー（全 kind 共通の任意設定。実行中（human は承認待ち）・完了メッセージの見せ方）。
-    // human の view と同じ「不透明なキー」で、選べる key は GET slack-views が返す。
-    // <slug>/<name> は実行 repo の views/slack/<name>/（@mawaru/sdk/slack-view の契約で書く）。
+    // human の view と同じ「不透明なキー」で、選べる key は GET views/slack が返す。
+    // <slug>/<name> は実行 repo の views/slack/<name>/（@mawaru/sdk/views/slack の契約で書く）。
     // 保存時に mawaru が見るのは common/* の実在と <slug>/* の可視性だけ。
     // 省略＝承認待ちは承認ボタンだけ・完了は ✅ の1行（データは出さない）。
     // ポートの型には一切影響しない
@@ -473,9 +484,10 @@ export const saveGraphBodySchema = z
         // 接続鏡映する口（program / ai の in）とコピー宣言のビューは接続元の型を採用する
         // ので自明に通り、実質の検証対象は宣言で固定された口
         // （component の契約・宣言のあるビューの human.in）になる
+        // flexible な in（AI の宣言 in・契約で焼き込まれた component の in）は型を問わない
         const fromSchema = resolved.get(conn.from_port_id) ?? from.schema;
         const toSchema = resolved.get(conn.to_port_id) ?? to.schema;
-        if (!isSchemaSubset(fromSchema, toSchema)) {
+        if (!connectionAccepted(fromSchema, { ...to, schema: toSchema })) {
             ctx.addIssue({
                 code: "custom",
                 path: ["connections", i, "to_port_id"],

package/dist/_schemas/human-manifest.d.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import { type JsonSchema } from "./node.js";
+import { type DeclaredPortSchema } from "./port-spec.js";
+export type HumanDeclaration = {
+    in: DeclaredPortSchema;
+    approve: DeclaredPortSchema;
+    reject: JsonSchema;
+};
+export declare const humanDeclarationSchema: z.ZodObject<{
+    in: z.ZodUnion<readonly [z.ZodLiteral<"T">, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+    approve: z.ZodUnion<readonly [z.ZodLiteral<"T">, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
+    reject: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export declare const STANDARD_HUMAN_DECLARATION: HumanDeclaration;
+export declare const humanManifestSchema: z.ZodObject<{
+    inputs: z.ZodOptional<z.ZodObject<{
+        in: z.ZodOptional<z.ZodObject<{
+            schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    outputs: z.ZodOptional<z.ZodObject<{
+        approve: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        reject: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type HumanManifest = z.infer<typeof humanManifestSchema>;
+export declare const humanDeclarationOfManifest: (config: HumanManifest) => HumanDeclaration;

package/dist/_schemas/human-manifest.js

@@ -0,0 +1,121 @@
+import { z } from "zod";
+import { jsonSchemaSchema } from "./node.js";
+import { COPY_UPSTREAM_SCHEMA, instructionSchema, } from "./port-spec.js";
+// 宣言に書ける type。file は x-mawaru-type マーカー付きの object
+const DECLARED_TYPES = [
+    "object",
+    "array",
+    "string",
+    "number",
+    "integer",
+    "boolean",
+];
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+// JSON Schema の形の崩れを場所つきで返す。接続の比較（schemaFit）が扱える形だけを通す：
+// 顧客 repo の宣言は mawaru のレビューを通らないので、壊れた型がノードに写る前に止める
+const schemaIssues = (schema, path) => {
+    const issues = [];
+    const { type, properties, required, items } = schema;
+    if (Array.isArray(type)) {
+        issues.push({
+            path: [...path, "type"],
+            message: "配列（nullable）は使えません。任意の値は required から外してください",
+        });
+    }
+    else if (type !== undefined &&
+        !DECLARED_TYPES.includes(type)) {
+        issues.push({
+            path: [...path, "type"],
+            message: `type は ${DECLARED_TYPES.join(" / ")} のどれかにしてください（${String(type)}）`,
+        });
+    }
+    else if (type === undefined &&
+        (properties !== undefined || items !== undefined)) {
+        issues.push({
+            path: [...path, "type"],
+            message: "properties / items を書くときは type も書いてください",
+        });
+    }
+    if (properties !== undefined) {
+        if (!isPlainObject(properties)) {
+            issues.push({
+                path: [...path, "properties"],
+                message: "properties はオブジェクトで書いてください",
+            });
+        }
+        else {
+            for (const [key, child] of Object.entries(properties)) {
+                if (!isPlainObject(child)) {
+                    issues.push({
+                        path: [...path, "properties", key],
+                        message: "スキーマはオブジェクトで書いてください",
+                    });
+                    continue;
+                }
+                issues.push(...schemaIssues(child, [...path, "properties", key]));
+            }
+        }
+    }
+    if (required !== undefined &&
+        !(Array.isArray(required) && required.every((r) => typeof r === "string"))) {
+        issues.push({
+            path: [...path, "required"],
+            message: "required は文字列の配列で書いてください",
+        });
+    }
+    if (items !== undefined) {
+        if (!isPlainObject(items)) {
+            issues.push({
+                path: [...path, "items"],
+                message: "items はスキーマ（オブジェクト）で書いてください",
+            });
+        }
+        else {
+            issues.push(...schemaIssues(items, [...path, "items"]));
+        }
+    }
+    return issues;
+};
+// 宣言に書く1つの型（検査つき）
+const checkedSchema = jsonSchemaSchema.superRefine((schema, ctx) => {
+    for (const issue of schemaIssues(schema, []))
+        ctx.addIssue({ code: "custom", ...issue });
+});
+const declaredPortSchema = z.union([
+    z.literal(COPY_UPSTREAM_SCHEMA),
+    checkedSchema,
+]);
+export const humanDeclarationSchema = z.object({
+    in: declaredPortSchema,
+    approve: declaredPortSchema,
+    reject: checkedSchema,
+});
+// 標準ビュー（common/standard）の宣言：上流の型をそのまま受けて出し、差し戻しは標準の指示フォーム
+export const STANDARD_HUMAN_DECLARATION = {
+    in: COPY_UPSTREAM_SCHEMA,
+    approve: COPY_UPSTREAM_SCHEMA,
+    reject: instructionSchema(),
+};
+// ---- 顧客 repo の nodes/human/<dir>/config.json ----
+// 形は AI の config.json に揃える（inputs の値は { schema }、outputs の値は素の JSON Schema）。
+// 口は in / approve / reject 固定。省略した口は STANDARD_HUMAN_DECLARATION と同じ扱い
+export const humanManifestSchema = z
+    .object({
+    inputs: z
+        .object({ in: z.object({ schema: checkedSchema }).strict().optional() })
+        .strict()
+        .optional(),
+    outputs: z
+        .object({
+        approve: checkedSchema.optional(),
+        reject: checkedSchema.optional(),
+    })
+        .strict()
+        .optional(),
+})
+    .strict();
+export const humanDeclarationOfManifest = (config) => ({
+    in: config.inputs?.in?.schema ?? COPY_UPSTREAM_SCHEMA,
+    approve: config.outputs?.approve ?? COPY_UPSTREAM_SCHEMA,
+    reject: config.outputs?.reject ?? instructionSchema(),
+});

package/dist/_schemas/node.d.ts

@@ -39,6 +39,7 @@ export declare const graphPortSchema: z.ZodObject<{
     name: z.ZodString;
     schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     resume: z.ZodOptional<z.ZodBoolean>;
+    flexible: z.ZodOptional<z.ZodBoolean>;
     side: z.ZodOptional<z.ZodEnum<{
         top: "top";
         right: "right";

package/dist/_schemas/node.js

@@ -43,6 +43,10 @@ export const graphPortSchema = z
     // 再開する（AI ノードで意味を持つ。key ではなくこの属性が再開を決める。
     // ポート型固定の撤去とセッション再開のポート属性化.md）
     resume: z.boolean().optional(),
+    // in ポートの型属性：true なら宣言（推奨型）を維持し、接続元の型による上書き・
+    // 適合チェックをしない（AI の in で設定。start / component へは導出で流れる。
+    // AIノード入力のflexible属性（任意の型で呼べるループ）.md）
+    flexible: z.boolean().optional(),
     side: portSideSchema.optional(),
     offset: z.number().min(0).max(1).optional(),
 })