@mawaru/sdk 0.13.0 → 0.14.1

package/_schemas/graph.ts

@@ -6,9 +6,7 @@ import {
   portKeySchema,
 } from "./node.js"
 import {
-  AI_INSTRUCTION_PORT_KEY,
   hasInboundConflict,
-  isAiEnvelopeSchema,
   isSchemaSubset,
   kindPortsViolation,
   resolvePortSchemas,
@@ -203,6 +201,10 @@ export type HumanConfig = z.infer<typeof humanConfigSchema>
 // （docs/tasks/wip/コンポーネント（ループの部品化と再利用）.md）
 export const componentConfigSchema = z.object({
   component_loop_id: z.uuid(),
+  // 配置の設定値：子 loop の refs 定義（default/required）への上書き。
+  // 子 run 起動時の起動時指定として渡る（省略＝上書きなし。検証は保存 API と
+  // 起動時の mergeRefs が行う。コンポーネントの設定値（refs）と1ノードのコンポーネント化.md）
+  refs: z.record(z.string(), z.unknown()).optional(),
 })
 export type ComponentConfig = z.infer<typeof componentConfigSchema>
 
@@ -316,19 +318,18 @@ export const saveGraphBodySchema = z
         else outCount++
       })
       // end は「in は1つ以上」（複数ルートを別々の in で集約する）。
-      // ai は2つ（上流データの in ＋ 差し戻しの instruction）。他 kind は1つ固定。
+      // ai も1つ以上（in は自由ポート：追加・削除・key 自由）。他 kind は1つ固定。
       // key の妥当性は kindPortsViolation が別途見る
-      const expectIn = node.kind === "ai" ? 2 : 1
       const inCountOk =
-        node.kind === "end" ? inCount >= 1 : inCount === expectIn
+        node.kind === "end" || node.kind === "ai" ? inCount >= 1 : inCount === 1
       if (!inCountOk) {
         ctx.addIssue({
           code: "custom",
           path: ["nodes", i, "ports"],
           message:
-            node.kind === "end"
+            node.kind === "end" || node.kind === "ai"
               ? "in ポートが1つ以上必要です"
-              : `in ポートはちょうど${expectIn}つ必要です`,
+              : "in ポートはちょうど1つ必要です",
         })
       }
       if (outCount < 1) {
@@ -371,7 +372,8 @@ export const saveGraphBodySchema = z
         })
       }
 
-      // kind 別のポート構成（program 以外は数・key・io 固定。ポートのkind別仕様.md）
+      // kind 別のポート構成（program 以外は数・key・io 固定。ポートのkind別仕様.md）。
+      // ポートのスキーマ自体は kind によらず任意の JSON Schema（形の強制はしない）
       const violation = kindPortsViolation(node.kind, node.ports)
       if (violation) {
         ctx.addIssue({
@@ -380,21 +382,6 @@ export const saveGraphBodySchema = z
           message: violation,
         })
       }
-
-      // AI の出力宣言は封筒型 { data: T, description: string }（T は任意の JSON Schema）。
-      // 複数出口でも全出口に強制する（どの出口も human に接続できる不変条件）
-      if (node.kind === "ai") {
-        node.ports.forEach((port, j) => {
-          if (port.io === "out" && !isAiEnvelopeSchema(port.schema)) {
-            ctx.addIssue({
-              code: "custom",
-              path: ["nodes", i, "ports", j],
-              message:
-                "AI の出力は封筒型 { data, description } で宣言してください",
-            })
-          }
-        })
-      }
     })
 
     // 接続：両端がグラフ内の port を指し、from=out / to=in。
@@ -480,17 +467,15 @@ export const saveGraphBodySchema = z
         })
       }
 
-      // 差し戻し（reject）と instruction の組み合わせは kind で縛らない：両端とも
-      // instructionSchema()（{ prompt, files }）で型が固定されているので、下の型検証だけで
-      // 「型が合う口にしか繋がらない」が成立する。差し戻し先が AI である必要はない
-      // （{ prompt, files } を受ける program へも繋げる）
+      // 差し戻し（reject）と instruction の組み合わせに kind の縛りも型固定も無い：
+      // reject の型はビューの宣言、instruction は ai の in の1つ（接続鏡映）でしかない
+      // → docs/tasks/wip/ポート型固定の撤去とセッション再開のポート属性化.md
 
       // 型検証は kind によらず常に 伝播型（out） ⊆ 伝播型（in）。
       // 未宣言は unknown＝判断できないので通す（作りかけのグラフを保存できなくしない）。
       // 接続鏡映する口（program / ai の in）とコピー宣言のビューは接続元の型を採用する
       // ので自明に通り、実質の検証対象は宣言で固定された口
-      // （component の契約・ai の instruction・宣言のあるビューの human.in）になる
-      // → docs/tasks/wip/Humanの入出力を承認ビューの宣言に一本化する.md
+      // （component の契約・宣言のあるビューの human.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)) {

package/_schemas/node.ts

@@ -47,6 +47,10 @@ export const graphPortSchema = z
     key: portKeySchema,
     name: z.string().min(1),
     schema: jsonSchemaSchema,
+    // in ポートの実行属性：true ならこの口から届いた実行は前回セッションを復元して
+    // 再開する（AI ノードで意味を持つ。key ではなくこの属性が再開を決める。
+    // ポート型固定の撤去とセッション再開のポート属性化.md）
+    resume: z.boolean().optional(),
     side: portSideSchema.optional(),
     offset: z.number().min(0).max(1).optional(),
   })

package/_schemas/port-spec.test.ts

@@ -3,12 +3,9 @@ import type { GraphPort, JsonSchema } from "./node.js"
 import {
   dataFormatOf,
   dataSchemaOf,
-  envelopeDataSchemaOf,
-  envelopeSchemaOf,
   fileSchema,
   hasInboundConflict,
   instructionSchema,
-  isAiEnvelopeSchema,
   isFileSchema,
   isSchemaSubset,
   kindPortsViolation,
@@ -77,102 +74,19 @@ describe("データフォーマットカタログ（S）", () => {
   })
 })
 
-describe("封筒型 { data: T, description: string }", () => {
-  it("envelopeSchemaOf：任意の data スキーマを包み、data / description とも必須", () => {
-    const text = envelopeSchemaOf({ type: "string" })
-    expect(text).toEqual({
-      type: "object",
-      properties: {
-        data: { type: "string" },
-        description: { type: "string" },
-      },
-      required: ["data", "description"],
-    })
-    // カタログ外の任意型も包める
-    const custom = {
-      type: "object",
-      properties: { title: { type: "string" }, count: { type: "number" } },
-      required: ["title"],
-    }
-    expect(envelopeSchemaOf(custom).properties).toMatchObject({ data: custom })
-  })
-
-  it("envelopeDataSchemaOf：封筒型なら data のサブスキーマ、そうでなければ null", () => {
-    const dataSchema = { type: "array", items: { type: "string" } }
-    expect(envelopeDataSchemaOf(envelopeSchemaOf(dataSchema))).toEqual(
-      dataSchema,
-    )
-    // data キーが無い / optional / object でない
-    expect(envelopeDataSchemaOf({ type: "object", properties: {} })).toBeNull()
+describe("kindPortsViolation（kind 別ポート構成）", () => {
+  it("ai は in / out とも key 自由（構成の固定なし。口数は graph 側が見る）", () => {
     expect(
-      envelopeDataSchemaOf({
-        type: "object",
-        properties: { data: { type: "string" } },
-      }),
+      kindPortsViolation("ai", [port("in", "in"), port("out", "main")]),
     ).toBeNull()
-    expect(envelopeDataSchemaOf({ type: "string" })).toBeNull()
-    expect(envelopeDataSchemaOf(UNDECLARED_SCHEMA)).toBeNull()
-  })
-
-  it("isAiEnvelopeSchema：data と description: string の両方が必須のときだけ true", () => {
-    expect(isAiEnvelopeSchema(envelopeSchemaOf({ type: "string" }))).toBe(true)
-    expect(isAiEnvelopeSchema(envelopeSchemaOf({ type: "object" }))).toBe(true)
-    // description が無い / optional / string でない
-    expect(
-      isAiEnvelopeSchema({
-        type: "object",
-        properties: { data: { type: "string" } },
-        required: ["data"],
-      }),
-    ).toBe(false)
-    expect(
-      isAiEnvelopeSchema({
-        type: "object",
-        properties: {
-          data: { type: "string" },
-          description: { type: "string" },
-        },
-        required: ["data"],
-      }),
-    ).toBe(false)
-    expect(
-      isAiEnvelopeSchema({
-        type: "object",
-        properties: {
-          data: { type: "string" },
-          description: { type: "number" },
-        },
-        required: ["data", "description"],
-      }),
-    ).toBe(false)
-    expect(isAiEnvelopeSchema(UNDECLARED_SCHEMA)).toBe(false)
-  })
-})
-
-describe("kindPortsViolation（kind 別ポート構成）", () => {
-  it("ai は out の key 自由・複数可。in は in / instruction の2口固定（AI の複数出口）", () => {
-    const ins = [port("in", "in"), port("in", "instruction")]
-    expect(kindPortsViolation("ai", [...ins, port("out", "main")])).toBeNull()
-    expect(kindPortsViolation("ai", [...ins, port("out", "reply")])).toBeNull()
     expect(
       kindPortsViolation("ai", [
-        ...ins,
+        port("in", "task"),
+        port("in", "feedback"),
         port("out", "spam"),
         port("out", "sales"),
-        port("out", "support"),
       ]),
     ).toBeNull()
-    // instruction が無い・key が違うのは違反
-    expect(
-      kindPortsViolation("ai", [port("in", "in"), port("out", "main")]),
-    ).toMatch(/instruction/)
-    expect(
-      kindPortsViolation("ai", [
-        port("in", "input"),
-        port("in", "instruction"),
-        port("out", "main"),
-      ]),
-    ).toMatch(/ai/)
   })
 
   it("human は in / approve / reject 固定", () => {
@@ -217,13 +131,18 @@ describe("kindPortsViolation（kind 別ポート構成）", () => {
 })
 
 describe("型伝播（導出ポートの解決）", () => {
-  const envelope = envelopeSchemaOf({ type: "string" })
+  // 伝播テスト用の任意の宣言型（中身の形に意味はない）
+  const declaredOut = {
+    type: "object",
+    properties: { text: { type: "string" } },
+    required: ["text"],
+  }
 
-  // human の in / approve はビューの宣言をそのまま転写する（上流の kind は見ない）。
+  // human の in / approve / reject はビューの宣言をそのまま転写する（上流の kind は見ない）。
   // sdk はカタログを知らないので、呼び出し元が viewPortSchemasOf で解決して渡す
-  // → docs/tasks/wip/Humanの入出力を承認ビューの宣言に一本化する.md
-  it("ai → human 直結（コピー宣言）：in も approve も上流の out と同型、reject は指示エンベロープ", () => {
-    const aiOut = port("out", "main", envelope)
+  // → docs/tasks/wip/ポート型固定の撤去とセッション再開のポート属性化.md
+  it("ai → human 直結（コピー宣言）：in も approve も上流の out と同型、reject はビューの宣言型", () => {
+    const aiOut = port("out", "main", declaredOut)
     const ai = {
       id: uuid(),
       kind: "ai",
@@ -240,11 +159,17 @@ describe("型伝播（導出ポートの解決）", () => {
     const resolved = resolvePortSchemas(
       [ai, human],
       [{ from_port_id: aiOut.id, to_port_id: humanIn.id }],
-      { viewPortSchemasOf: () => ({ in: "T", out: "T" }) },
+      {
+        viewPortSchemasOf: () => ({
+          in: "T",
+          approve: "T",
+          reject: instructionSchema(),
+        }),
+      },
     )
     // 上流が AI でも中身を取り出さない：AI の出力形式がそのまま下流へ流れる
-    expect(resolved.get(humanIn.id)).toEqual(envelope)
-    expect(resolved.get(approve.id)).toEqual(envelope)
+    expect(resolved.get(humanIn.id)).toEqual(declaredOut)
+    expect(resolved.get(approve.id)).toEqual(declaredOut)
     expect(resolved.get(reject.id)).toEqual(instructionSchema())
   })
 
@@ -266,6 +191,12 @@ describe("型伝播（導出ポートの解決）", () => {
       properties: { prs: { type: "array", items: { type: "object" } } },
       required: ["prs"],
     }
+    // reject もビューの宣言（具体型のみ。コピー指示は意味を持たない）
+    const viewReject = {
+      type: "object",
+      properties: { reason: { type: "string" } },
+      required: ["reason"],
+    }
     const build = (upstreamKind: string, upstreamOut: JsonSchema) => {
       const out = port("out", "main", upstreamOut)
       const upstream = {
@@ -275,65 +206,97 @@ describe("型伝播（導出ポートの解決）", () => {
       }
       const humanIn = port("in", "in")
       const approve = port("out", "approve")
+      const reject = port("out", "reject")
       const human = {
         id: uuid(),
         kind: "human",
-        ports: [humanIn, approve, port("out", "reject")],
+        ports: [humanIn, approve, reject],
       }
-      return { upstream, human, out, humanIn, approve }
+      return { upstream, human, out, humanIn, approve, reject }
     }
 
     it("宣言のあるビューは上流の kind に依らず同じ型になる", () => {
       for (const kind of ["ai", "program"]) {
-        const { upstream, human, out, humanIn, approve } = build(kind, envelope)
+        const { upstream, human, out, humanIn, approve, reject } = build(
+          kind,
+          declaredOut,
+        )
         const resolved = resolvePortSchemas(
           [upstream, human],
           [{ from_port_id: out.id, to_port_id: humanIn.id }],
-          { viewPortSchemasOf: () => ({ in: viewIn, out: viewOut }) },
+          {
+            viewPortSchemasOf: () => ({
+              in: viewIn,
+              approve: viewOut,
+              reject: viewReject,
+            }),
+          },
         )
         expect(resolved.get(humanIn.id)).toEqual(viewIn)
         expect(resolved.get(approve.id)).toEqual(viewOut)
+        expect(resolved.get(reject.id)).toEqual(viewReject)
       }
     })
 
     it("上流の out は書き換えない（逆伝播しない）", () => {
-      const { upstream, human, out, humanIn } = build("ai", envelope)
+      const { upstream, human, out, humanIn } = build("ai", declaredOut)
       const resolved = resolvePortSchemas(
         [upstream, human],
         [{ from_port_id: out.id, to_port_id: humanIn.id }],
-        { viewPortSchemasOf: () => ({ in: viewIn, out: viewOut }) },
+        {
+          viewPortSchemasOf: () => ({
+            in: viewIn,
+            approve: viewOut,
+            reject: viewReject,
+          }),
+        },
       )
-      expect(resolved.get(out.id)).toEqual(envelope)
+      expect(resolved.get(out.id)).toEqual(declaredOut)
     })
 
     it("コピー宣言（標準ビュー）は上流の型をそのまま in と approve へ流す", () => {
-      const { upstream, human, out, humanIn, approve } = build("ai", envelope)
+      const { upstream, human, out, humanIn, approve } = build(
+        "ai",
+        declaredOut,
+      )
       const resolved = resolvePortSchemas(
         [upstream, human],
         [{ from_port_id: out.id, to_port_id: humanIn.id }],
-        { viewPortSchemasOf: () => ({ in: "T", out: "T" }) },
+        {
+          viewPortSchemasOf: () => ({
+            in: "T",
+            approve: "T",
+            reject: viewReject,
+          }),
+        },
       )
-      expect(resolved.get(humanIn.id)).toEqual(envelope)
-      expect(resolved.get(approve.id)).toEqual(envelope)
+      expect(resolved.get(humanIn.id)).toEqual(declaredOut)
+      expect(resolved.get(approve.id)).toEqual(declaredOut)
     })
 
     it("未接続でも宣言で固定される", () => {
       const humanIn = port("in", "in")
       const approve = port("out", "approve")
+      const reject = port("out", "reject")
       const human = {
         id: uuid(),
         kind: "human",
-        ports: [humanIn, approve, port("out", "reject")],
+        ports: [humanIn, approve, reject],
       }
       const resolved = resolvePortSchemas([human], [], {
-        viewPortSchemasOf: () => ({ in: viewIn, out: viewOut }),
+        viewPortSchemasOf: () => ({
+          in: viewIn,
+          approve: viewOut,
+          reject: viewReject,
+        }),
       })
       expect(resolved.get(humanIn.id)).toEqual(viewIn)
       expect(resolved.get(approve.id)).toEqual(viewOut)
+      expect(resolved.get(reject.id)).toEqual(viewReject)
     })
   })
 
-  it("ai → wait → human：素通しで封筒型が伝播し、reject は指示エンベロープのまま", () => {
+  it("ai → wait → human：素通しで上流の宣言型が伝播し、reject はビュー宣言が無ければ未宣言", () => {
     // ai の in は宣言型（nodes/ai/<dir>/config.json の inputs.in 由来。実行repoの構造見直し）
     const aiInSchema = {
       type: "object",
@@ -341,7 +304,7 @@ describe("型伝播（導出ポートの解決）", () => {
       required: ["inquiry"],
     }
     const aiIn = port("in", "in", aiInSchema)
-    const aiOut = port("out", "main", envelope)
+    const aiOut = port("out", "main", declaredOut)
     const waitIn = port("in", "in")
     const waitOut = port("out", "main")
     const humanIn = port("in", "in")
@@ -363,16 +326,41 @@ describe("型伝播（導出ポートの解決）", () => {
       { from_port_id: waitOut.id, to_port_id: humanIn.id },
     ]
     const resolved = resolvePortSchemas([ai, wait, human], conns)
-    expect(resolved.get(waitIn.id)).toEqual(envelope)
-    expect(resolved.get(waitOut.id)).toEqual(envelope)
-    expect(resolved.get(humanIn.id)).toEqual(envelope)
-    // 封筒剥がしは「in の直接の接続元が AI ノード」のときだけ。wait 越しは素通し
-    expect(resolved.get(approve.id)).toEqual(envelope)
-    expect(resolved.get(reject.id)).toEqual(instructionSchema())
+    expect(resolved.get(waitIn.id)).toEqual(declaredOut)
+    expect(resolved.get(waitOut.id)).toEqual(declaredOut)
+    expect(resolved.get(humanIn.id)).toEqual(declaredOut)
+    // approve は in と同型（上流の kind による中身の取り出しはしない）
+    expect(resolved.get(approve.id)).toEqual(declaredOut)
+    // reject はビューの宣言でのみ決まる（sdk 単体＝カタログ無しでは未宣言。型固定は廃止）
+    expect(resolved.get(reject.id)).toEqual(UNDECLARED_SCHEMA)
     // ai の in は宣言型がそのまま残る（const 扱いは廃止）
     expect(resolved.get(aiIn.id)).toEqual(aiInSchema)
   })
 
+  it("ai の in はどの口も接続鏡映される（instruction の特別扱い＝型固定は廃止）", () => {
+    const progOut = port("out", "main", declaredOut)
+    const program = {
+      id: uuid(),
+      kind: "program",
+      ports: [port("in", "in"), progOut],
+    }
+    // 宣言はデフォルトの指示型。接続すると接続元の型に同期される（他の in と同じ）
+    const instruction = port("in", "instruction", instructionSchema())
+    const ai = {
+      id: uuid(),
+      kind: "ai",
+      ports: [port("in", "in"), instruction, port("out", "main")],
+    }
+    const resolved = resolvePortSchemas(
+      [program, ai],
+      [{ from_port_id: progOut.id, to_port_id: instruction.id }],
+    )
+    expect(resolved.get(instruction.id)).toEqual(declaredOut)
+    // 未接続なら宣言（デフォルト型）を維持する
+    const kept = resolvePortSchemas([ai], [])
+    expect(kept.get(instruction.id)).toEqual(instructionSchema())
+  })
+
   it("未接続の導出ポート・純パラメトリック閉路は any", () => {
     const in1 = port("in", "in")
     const out1 = port("out", "main")
@@ -398,7 +386,7 @@ describe("型伝播（導出ポートの解決）", () => {
       properties: { inquiry: { type: "string" } },
       required: ["inquiry"],
     }
-    const aiOut = port("out", "main", envelope)
+    const aiOut = port("out", "main", declaredOut)
     const ai = {
       id: uuid(),
       kind: "ai",
@@ -414,7 +402,7 @@ describe("型伝播（導出ポートの解決）", () => {
       [ai, program],
       [{ from_port_id: aiOut.id, to_port_id: progIn.id }],
     )
-    expect(resolved.get(progIn.id)).toEqual(envelope)
+    expect(resolved.get(progIn.id)).toEqual(declaredOut)
   })
 
   it("ai の in も接続鏡映（sticky）：具体型の接続元だけ上書きする", () => {
@@ -422,7 +410,7 @@ describe("型伝播（導出ポートの解決）", () => {
       type: "object",
       properties: { topic: { type: "string" } },
     }
-    const progOut = port("out", "main", envelope)
+    const progOut = port("out", "main", declaredOut)
     const program = {
       id: uuid(),
       kind: "program",
@@ -439,7 +427,7 @@ describe("型伝播（導出ポートの解決）", () => {
       [program, ai],
       [{ from_port_id: progOut.id, to_port_id: aiIn.id }],
     )
-    expect(resolved.get(aiIn.id)).toEqual(envelope)
+    expect(resolved.get(aiIn.id)).toEqual(declaredOut)
     // 接続元が any（源泉の無い wait）→ 宣言を維持
     const waitOut = port("out", "main")
     const wait = {
@@ -491,7 +479,7 @@ describe("型伝播（導出ポートの解決）", () => {
   })
 
   it("program の in：wait 越しでも具体型が鏡映される（固定点反復）", () => {
-    const aiOut = port("out", "main", envelope)
+    const aiOut = port("out", "main", declaredOut)
     const ai = {
       id: uuid(),
       kind: "ai",
@@ -513,7 +501,7 @@ describe("型伝播（導出ポートの解決）", () => {
         { from_port_id: waitOut.id, to_port_id: progIn.id },
       ],
     )
-    expect(resolved.get(progIn.id)).toEqual(envelope)
+    expect(resolved.get(progIn.id)).toEqual(declaredOut)
   })
 
   // start の run 入力契約は接続先から導出する
@@ -624,7 +612,7 @@ describe("型伝播（導出ポートの解決）", () => {
   })
 
   it("propagateDerivedPorts：schema を書き戻し、変化のないノードは同じ参照を返す", () => {
-    const progOut = port("out", "main", envelope)
+    const progOut = port("out", "main", declaredOut)
     const program = {
       id: uuid(),
       kind: "program",
@@ -641,7 +629,10 @@ describe("型伝播（導出ポートの解決）", () => {
       [{ from_port_id: progOut.id, to_port_id: waitIn.id }],
     )
     expect(next[0]).toBe(program) // 宣言のみ＝無変更
-    expect(next[1]?.ports.map((p) => p.schema)).toEqual([envelope, envelope])
+    expect(next[1]?.ports.map((p) => p.schema)).toEqual([
+      declaredOut,
+      declaredOut,
+    ])
     // 接続を消すと any に戻る
     const cleared = propagateDerivedPorts(next, [])
     expect(cleared[1]?.ports.map((p) => p.schema)).toEqual([
@@ -652,7 +643,7 @@ describe("型伝播（導出ポートの解決）", () => {
 
   it("propagateDerivedPorts：side / offset（表示位置）を落とさない", () => {
     const progOut = {
-      ...port("out", "main", envelope),
+      ...port("out", "main", declaredOut),
       side: "top" as const,
       offset: 0.3,
     }