@mawaru/sdk 0.31.0 → 0.33.0

package/_schemas/graph.test.ts

@@ -548,6 +548,14 @@ const outByKey = (node: TestNode, key: string): GraphPort => {
 }
 
 describe("saveGraphBodySchema（kind 別ポート構成）", () => {
+  it("human の追加出口を保存できる", () => {
+    const human = humanNode()
+    human.ports.push(port("out", "notion_task"))
+    expect(() =>
+      saveGraphBodySchema.parse({ nodes: [human], connections: [] }),
+    ).not.toThrow()
+  })
+
   it("human の担当なし（human 設定の省略）を拒否する", () => {
     const { human: _human, ...noAssign } = humanNode()
     expect(() =>
@@ -900,6 +908,16 @@ describe("saveGraphBodySchema（refs：ループ変数の定義スキーマ）",
     ).toThrow(/required/)
   })
 
+  it("properties に予約キー input（run の起動入力）は置けない", () => {
+    expect(() =>
+      saveGraphBodySchema.parse({
+        nodes: [makeNode()],
+        connections: [],
+        refs: { type: "object", properties: { input: { type: "string" } } },
+      }),
+    ).toThrow(/input/)
+  })
+
   it("object 以外の type・旧「値の袋」形は拒否する", () => {
     for (const refs of [
       { type: "string" },

package/_schemas/graph.ts

@@ -20,6 +20,12 @@ import {
 export const refsBagSchema = z.record(portKeySchema, z.unknown())
 export type RefsBag = z.infer<typeof refsBagSchema>
 
+// 予約キー：run の起動入力（runs.start_payload）。Run.start が袋に写し、全 step
+// （Program の refs.json・AI のプロンプト・承認ビューの ctx）から読める。
+// ループ定義には置けず、起動指定・end のパッチでも書けない
+// （起動入力をrefsに入れて全ノードから参照できるようにする.md）
+export const REFS_INPUT_KEY = "input"
+
 // ループ変数の定義＝袋全体を表す 1 つの object JSON Schema
 // （ループ変数（refs）のJSON Schema化.md）。properties のキーが変数名、
 // default が静的なデフォルト値、required は「run 起動時に値が確定して
@@ -31,6 +37,13 @@ export const loopRefsSchema = z
     required: z.array(portKeySchema).optional(),
   })
   .superRefine((refs, ctx) => {
+    if (REFS_INPUT_KEY in refs.properties) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["properties", REFS_INPUT_KEY],
+        message: `properties のキー ${REFS_INPUT_KEY} は予約キー（run の起動入力）です`,
+      })
+    }
     for (const key of refs.required ?? []) {
       if (!(key in refs.properties)) {
         ctx.addIssue({

package/_schemas/port-spec.test.ts

@@ -90,7 +90,26 @@ describe("kindPortsViolation（kind 別ポート構成）", () => {
     ).toBeNull()
   })
 
-  it("human は in / approve / reject 固定", () => {
+  it("human は追加の出口を持てるが基本ポートは必須", () => {
+    const ports = [
+      port("in", "in"),
+      port("out", "approve"),
+      port("out", "reject"),
+      port("out", "notion_task"),
+    ]
+    expect(kindPortsViolation("human", ports)).toBeNull()
+    expect(
+      kindPortsViolation(
+        "human",
+        ports.filter((p) => p.key !== "reject"),
+      ),
+    ).toMatch(/human/)
+    expect(
+      kindPortsViolation("human", [...ports, port("in", "extra")]),
+    ).toMatch(/human/)
+  })
+
+  it("human は in / approve / reject を持つ", () => {
     expect(
       kindPortsViolation("human", [
         port("in", "in"),
@@ -132,6 +151,35 @@ describe("kindPortsViolation（kind 別ポート構成）", () => {
 })
 
 describe("型伝播（導出ポートの解決）", () => {
+  it.each([
+    "notion_task",
+    "main",
+  ])("Humanの追加出口 %s の宣言型は承認ビューの型で上書きしない", (key) => {
+    const extra = port("out", key, {
+      type: "object",
+      properties: { title: { type: "string" } },
+      required: ["title"],
+    })
+    const human = {
+      id: uuid(),
+      kind: "human",
+      ports: [
+        port("in", "in"),
+        port("out", "approve"),
+        port("out", "reject"),
+        extra,
+      ],
+    }
+    const resolved = resolvePortSchemas([human], [], {
+      viewPortSchemasOf: () => ({
+        in: { type: "string" },
+        approve: { type: "string" },
+        reject: { type: "string" },
+      }),
+    })
+    expect(resolved.get(extra.id)).toEqual(extra.schema)
+  })
+
   // 伝播テスト用の任意の宣言型（中身の形に意味はない）
   const declaredOut = {
     type: "object",

package/_schemas/port-spec.ts

@@ -139,11 +139,10 @@ export const dataFormatOf = (schema: JsonSchema): DataFormat | null => {
 }
 
 // ---- kind 別ポート構成 ----
-// human / wait は構成（数・key・io）が固定。program / ai は in 1つ＋out 1つ以上
+// wait は構成が固定。human は基本ポートを保ち追加 out を持てる。program / ai は out 自由
 // （key 自由。複数 out＝分岐。AIノードの複数出口（分岐）.md）
 
 const FIXED_PORT_KEYS: Record<string, { in: string[]; out: string[] }> = {
-  human: { in: ["in"], out: ["approve", "reject"] },
   wait: { in: ["in"], out: ["main"] },
   // start は in 1つ（run 入力契約）＋ out main 1つの恒等パススルー
   start: { in: ["in"], out: ["main"] },
@@ -199,6 +198,19 @@ export const kindPortsViolation = (
     }
     return null
   }
+  if (kind === "human") {
+    const inKeys = ports.filter((p) => p.io === "in").map((p) => p.key)
+    const outKeys = ports.filter((p) => p.io === "out").map((p) => p.key)
+    if (
+      inKeys.length !== 1 ||
+      inKeys[0] !== "in" ||
+      !outKeys.includes("approve") ||
+      !outKeys.includes("reject")
+    ) {
+      return "human のポート構成は in(in) と out(approve / reject) が必須です（out は追加できます）"
+    }
+    return null
+  }
   const fixed = FIXED_PORT_KEYS[kind]
   if (!fixed) {
     // program / ai（自由 out）：in の構成だけ固定
@@ -334,7 +346,7 @@ const MIRROR_KINDS = new Set(["program", "ai"])
 const isDerivedPort = (kind: string, port: Pick<GraphPort, "io" | "key">) =>
   DERIVED_KINDS.has(kind) &&
   (port.io === "in" ||
-    port.key === "main" ||
+    (kind !== "human" && port.key === "main") ||
     port.key === "approve" ||
     port.key === "reject")
 

package/dist/_schemas/graph.d.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 export declare const refsBagSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 export type RefsBag = z.infer<typeof refsBagSchema>;
+export declare const REFS_INPUT_KEY = "input";
 export declare const loopRefsSchema: z.ZodObject<{
     type: z.ZodLiteral<"object">;
     properties: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;

package/dist/_schemas/graph.js

@@ -6,6 +6,11 @@ import { hasInboundConflict, isSchemaSubset, kindPortsViolation, resolvePortSche
 // key はポート key と同じ規則（^[a-z][a-z0-9_]*$）。実行系ボディ
 // （run 起動の上書き・step end のパッチ）が使う契約
 export const refsBagSchema = z.record(portKeySchema, z.unknown());
+// 予約キー：run の起動入力（runs.start_payload）。Run.start が袋に写し、全 step
+// （Program の refs.json・AI のプロンプト・承認ビューの ctx）から読める。
+// ループ定義には置けず、起動指定・end のパッチでも書けない
+// （起動入力をrefsに入れて全ノードから参照できるようにする.md）
+export const REFS_INPUT_KEY = "input";
 // ループ変数の定義＝袋全体を表す 1 つの object JSON Schema
 // （ループ変数（refs）のJSON Schema化.md）。properties のキーが変数名、
 // default が静的なデフォルト値、required は「run 起動時に値が確定して
@@ -17,6 +22,13 @@ export const loopRefsSchema = z
     required: z.array(portKeySchema).optional(),
 })
     .superRefine((refs, ctx) => {
+    if (REFS_INPUT_KEY in refs.properties) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["properties", REFS_INPUT_KEY],
+            message: `properties のキー ${REFS_INPUT_KEY} は予約キー（run の起動入力）です`,
+        });
+    }
     for (const key of refs.required ?? []) {
         if (!(key in refs.properties)) {
             ctx.addIssue({

package/dist/_schemas/port-spec.js

@@ -118,10 +118,9 @@ export const dataFormatOf = (schema) => {
     return { format: "list", columns };
 };
 // ---- kind 別ポート構成 ----
-// human / wait は構成（数・key・io）が固定。program / ai は in 1つ＋out 1つ以上
+// wait は構成が固定。human は基本ポートを保ち追加 out を持てる。program / ai は out 自由
 // （key 自由。複数 out＝分岐。AIノードの複数出口（分岐）.md）
 const FIXED_PORT_KEYS = {
-    human: { in: ["in"], out: ["approve", "reject"] },
     wait: { in: ["in"], out: ["main"] },
     // start は in 1つ（run 入力契約）＋ out main 1つの恒等パススルー
     start: { in: ["in"], out: ["main"] },
@@ -166,6 +165,17 @@ export const kindPortsViolation = (kind, ports) => {
         }
         return null;
     }
+    if (kind === "human") {
+        const inKeys = ports.filter((p) => p.io === "in").map((p) => p.key);
+        const outKeys = ports.filter((p) => p.io === "out").map((p) => p.key);
+        if (inKeys.length !== 1 ||
+            inKeys[0] !== "in" ||
+            !outKeys.includes("approve") ||
+            !outKeys.includes("reject")) {
+            return "human のポート構成は in(in) と out(approve / reject) が必須です（out は追加できます）";
+        }
+        return null;
+    }
     const fixed = FIXED_PORT_KEYS[kind];
     if (!fixed) {
         // program / ai（自由 out）：in の構成だけ固定
@@ -258,7 +268,7 @@ const DERIVED_KINDS = new Set(["wait", "human", "end", "start"]);
 const MIRROR_KINDS = new Set(["program", "ai"]);
 const isDerivedPort = (kind, port) => DERIVED_KINDS.has(kind) &&
     (port.io === "in" ||
-        port.key === "main" ||
+        (kind !== "human" && port.key === "main") ||
         port.key === "approve" ||
         port.key === "reject");
 // port_id → 解決済みスキーマ。導出は接続を遡って固定点まで反復し、

package/dist/typegen.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { REFS_INPUT_KEY } from "./_schemas/graph.js";
 import { programManifestSchema, } from "./_schemas/program-manifest.js";
 // 生成ファイルに刻む config.json 内容のハッシュ。validate が drift（config を変えて
 // typegen し忘れ）の検出に使う
@@ -139,8 +140,12 @@ export const renderTypesFile = (manifest, rawConfig) => {
     const inputSchema = manifest.inputs.in ?? {};
     const outputEntries = Object.entries(manifest.outputs).map(([key, schema]) => `  ${propertyKey(key)}: ${tsTypeFromJsonSchema(schema, 1)}`);
     // refs＝ループ変数の袋（実行時に refs.json で渡される）。config の refs はループ定義
-    // からの転写（キー→推定型）なので、宣言が無ければ型も出さない
-    const refEntries = Object.entries(manifest.refs).map(([key, schema]) => `  ${propertyKey(key)}: ${tsTypeFromJsonSchema(schema, 1)}`);
+    // からの転写（キー→推定型）。予約キー input（run の起動入力）は定義に現れないが
+    // 必ず袋に載るので、宣言が無くても Refs / Ctx を出す
+    const refEntries = [
+        `  ${propertyKey(REFS_INPUT_KEY)}: unknown`,
+        ...Object.entries(manifest.refs).map(([key, schema]) => `  ${propertyKey(key)}: ${tsTypeFromJsonSchema(schema, 1)}`),
+    ];
     return [
         "// このファイルは mawaru typegen が config.json から自動生成した（手で編集しない）",
         `${CONFIG_HASH_PREFIX}${configHash(rawConfig)}`,
@@ -152,16 +157,13 @@ export const renderTypesFile = (manifest, rawConfig) => {
         "// run の戻り値：ちょうど1つの出口ポートのキーで返す { <出口キー>: 値 }",
         outputUnionType(Object.keys(manifest.outputs)),
         "",
-        ...(refEntries.length > 0
-            ? [
-                `export type Refs = {\n${refEntries.join("\n")}\n}`,
-                "",
-                "// run の第2引数：refs＝届いた袋の読み、setRefs＝袋へのパッチの宣言",
-                "// （書いたキーだけが完了時に袋へマージされ、下流のノードから読める）",
-                "export type Ctx = { refs: Refs; setRefs: (patch: Partial<Refs>) => void }",
-                "",
-            ]
-            : []),
+        `export type Refs = {\n${refEntries.join("\n")}\n}`,
+        "",
+        "// run の第2引数：refs＝届いた袋の読み、setRefs＝袋へのパッチの宣言",
+        "// （書いたキーだけが完了時に袋へマージされ、下流のノードから読める。",
+        "// input は run の起動入力＝読み専用）",
+        "export type Ctx = { refs: Refs; setRefs: (patch: Partial<Refs>) => void }",
+        "",
     ].join("\n");
 };
 // nodes/program/ 直下の各 dir の config.json から types.d.ts を生成する

package/docs/development.md

@@ -30,7 +30,9 @@ skills/<dir>/      # AI ノードが参照する skill（SKILL.md）
   - `{ <出口ポートのkey>: <データ> }` の**単一キーのオブジェクト**（どの出口から出るかを戻り値自身が運ぶ）
   - `"pending"` — 完了保留（外部イベントで後から end が届く）
 - `ctx` — ループ変数の袋の読み書き：
-  - `ctx.refs` — 届いた袋（loop に定義された変数の、この step 開始時点の値）
+  - `ctx.refs` — 届いた袋（loop に定義された変数の、この step 開始時点の値）。
+    予約キー `ctx.refs.input` は **run の起動入力**（開始ノードに渡された値。コンポーネントの
+    中ならコンポーネントの入力）。読み専用で、loop の定義には置けず `setRefs` でも書けない
   - `ctx.setRefs({ key: value })` — 袋へのパッチの宣言。**完了時にだけ**反映され、以降の
     ノードが `ctx.refs` で読める（動的な値を下流へ渡す唯一の経路）。何度呼んでもトップレベル
     キー後勝ちで畳まれる。`"pending"` を返す実行では反映されない。loop に定義の無いキーを

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mawaru/sdk",
-  "version": "0.31.0",
+  "version": "0.33.0",
   "description": "mawaru 実行 repo の開発 SDK。契約スキーマ（config.json 規約・ループ graph API）の正 ＋ typegen / validate CLI",
   "type": "module",
   "bin": {

package/skills/create-loop/SKILL.md

@@ -87,7 +87,8 @@ repo との矛盾・使用中ノードの削除は 409。**graph PUT は冪等
    - kind 別の固定ポート構成（human / wait / ai）は `port-spec.ts` の `kindPortsViolation` に従う
    - ループ変数（refs＝run 全体で読める key→値 の袋）が要るならトップレベルの `refs` に入れる。
      ノード単位の宣言やバインドは無い。handler は実行時に `refs.json` で全量を受け取り、
-     `end` の `refs` パッチで値を更新できる（config.json の `refs` はループ定義からの転写＝生成物）
+     `end` の `refs` パッチで値を更新できる（config.json の `refs` はループ定義からの転写＝生成物）。
+     キー `input` は予約（run の起動入力が自動で入る。定義に置くと 422）
    - `position_x` / `position_y` は左→右に流れる単純配置（例: x を 320 刻み、y は 240）
 5. **保存**：`PUT loops/{loopId}/graph`。400 / 422 / 409 ならメッセージを読んで直して再送。
 6. **報告**：エディタ URL `{MAWARU_APP_URL}/loops/{loopId}/edit` をユーザーに渡し、