#1047 Action Plan — Agent Builder Integration

[ootakazuhiko]

Repo: itdojp/ae-framework • Issue: #1047

---

🇬🇧 Executive Summary

Concrete, small-batch PR plan to advance #1047 now: define internal Flow Schema (Intent→Operate), extend the Envelope, add CI schema validation, and bootstrap an Agent Builder adapter skeleton with a minimal end-to-end PoC.

🇯🇵 概要

#1047 を今すぐ前進させる小粒PR計画。内部フロースキーマ（Intent→Operate）定義、Envelope拡張、CIでのスキーマ検証、Agent Builder互換アダプタの雛形、最小E2E PoCまで一気通貫で進めます。

---

1) Milestone & Timeline / マイルストーン

• M1 (Day 0–2): Spec & CI

  • Flow Schema v0.1（JSON）
  • Envelope v1.0 schema + Ajv CI
  • Vitest snapshot baseline

• M2 (Day 3–5): Adapter Skeleton & PoC

  • agent-builder-adapter skeleton（TS）
  • Minimal PoC: Intent→Formal→Code→Verify（dummy nodes）

• M3 (Day 6–10): Trace/Docs

  • Trace correlation (runId/commit/branch)
  • Docs + examples + dashboard wiring (stub)

---

2) Workstreams & PRs / 作業ストリームとPR

PR-1: Flow Schema v0.1 + Envelope v1.0

Scope

• Add: schema/flow.schema.json (Intent→Operate)
• Add: schema/envelope.schema.json (unified)
• Add: scripts/ci/validate-json.mjs (Ajv)
• CI: validate:schemas job + Job Summary output
• Docs: docs/flow/README.md

Acceptance

• Ajv validates sample fixtures
• schemaVersion (semver) embedded in all JSONs
• Job Summary shows PASS/FAIL with paths

Example files

• fixtures/flow/sample.flow.json
• fixtures/envelope/sample.envelope.json

---

PR-2: Verify Lite → Envelope adapter

Scope

• Implement converter: packages/envelope/src/from-verify-lite.ts
• Ensure stable path: artifacts/verify-lite/verify-lite-run-summary.json
• Vitest snapshot: __snapshots__/from-verify-lite.test.snap

Acceptance

• Conversion produces envelope v1.0
• Snapshot green across 3 input variants (small/mid/edge)

---

PR-3: Agent Builder Adapter (skeleton)

Scope

• New pkg: packages/agent-builder-adapter

  • parseFlow.ts (AB flow JSON → internal graph)
  • types.ts (Node, Edge, Param, IO schemas)
  • execSimulator.ts (deterministic mock runner)

• CLI: ae flow run -f fixtures/flow/sample.flow.json

Acceptance

• Parses sample AB-like JSON (stable contract)
• Simulated run produces deterministic trace + envelope

---

PR-4: Minimal E2E PoC

Scope

• Nodes: intent2formal, tests2code(minimal), code2verify(minimal)
• Wire with adapter simulator; output envelope + junit
• Docs: docs/agent-builder/poc.md (how-to)

Acceptance

• npm run demo:ab-poc runs end-to-end
• Job Summary lists node-by-node status

---

3) File Structure Additions / 追加ファイル構成

/schema
  ├─ flow.schema.json
  └─ envelope.schema.json
/fixtures
  ├─ flow/sample.flow.json
  └─ envelope/sample.envelope.json
/packages
  ├─ envelope/src/from-verify-lite.ts
  └─ agent-builder-adapter/
      ├─ src/parseFlow.ts
      ├─ src/execSimulator.ts
      └─ src/types.ts
/scripts/ci/validate-json.mjs
/docs
  ├─ flow/README.md
  └─ agent-builder/poc.md

---

4) Schemas (Drafts) / スキーマ（ドラフト）

4.1 Envelope v1.0 (excerpt)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ae-framework/schema/envelope.schema.json",
  "title": "ae-envelope",
  "type": "object",
  "properties": {
    "schemaVersion": {"type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$"},
    "source": {"type": "string"},
    "generatedAt": {"type": "string", "format": "date-time"},
    "traceCorrelation": {
      "type": "object",
      "properties": {
        "runId": {"type": "string"},
        "commit": {"type": "string"},
        "branch": {"type": "string"}
      },
      "required": ["runId"]
    },
    "summary": {"type": "object"},
    "artifacts": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "type": {"type": "string"},
          "path": {"type": "string"}
        },
        "required": ["type", "path"]
      }
    }
  },
  "required": ["schemaVersion", "source", "generatedAt", "traceCorrelation", "summary"]
}

4.2 Flow Schema v0.1 (excerpt)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ae-framework/schema/flow.schema.json",
  "title": "ae-flow",
  "type": "object",
  "properties": {
    "schemaVersion": {"type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$"},
    "nodes": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {"type": "string"},
          "kind": {"type": "string", "enum": [
            "intent2formal","formal2tests","tests2code","code2verify","verify2operate"
          ]},
          "params": {"type": "object"},
          "input": {"type": "array"},
          "output": {"type": "array"}
        },
        "required": ["id","kind"]
      }
    },
    "edges": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "from": {"type": "string"},
          "to": {"type": "string"}
        },
        "required": ["from","to"]
      }
    },
    "metadata": {"type": "object"}
  },
  "required": ["schemaVersion","nodes","edges"]
}

---

5) CI Snippets / CI 追加スニペット

scripts/ci/validate-json.mjs (Ajv runner)

import { readFileSync } from 'node:fs';
import Ajv from 'ajv';
import addFormats from 'ajv-formats';

const ajv = new Ajv({ allErrors: true, strict: false });
addFormats(ajv);

const schema = JSON.parse(readFileSync('schema/envelope.schema.json','utf8'));
const data = JSON.parse(readFileSync('fixtures/envelope/sample.envelope.json','utf8'));

const validate = ajv.compile(schema);
const ok = validate(data);
if (!ok) {
  console.error(JSON.stringify(validate.errors, null, 2));
  process.exit(1);
}
console.log('Envelope schema validation: OK');

GitHub Actions step (excerpt)

- name: Validate Envelope schema
  run: node scripts/ci/validate-json.mjs

---

6) Vitest Snapshot Example / スナップショット例

import { describe, it, expect } from 'vitest';
import { fromVerifyLite } from '../src/from-verify-lite';
import sample from '../../fixtures/verify-lite/sample.json';

describe('fromVerifyLite', () => {
  it('produces stable envelope', () => {
    const env = fromVerifyLite(sample);
    // scrub volatile fields
    env.generatedAt = '1970-01-01T00:00:00Z';
    expect(env).toMatchSnapshot();
  });
});

---

7) Sample Flow / Envelope Fixtures / サンプル

fixtures/flow/sample.flow.json (mini)

{
  "schemaVersion": "0.1.0",
  "nodes": [
    {"id":"n1","kind":"intent2formal","params":{"lang":"en"}},
    {"id":"n2","kind":"tests2code","params":{"language":"ts"}},
    {"id":"n3","kind":"code2verify","params":{"runner":"vitest"}}
  ],
  "edges": [
    {"from":"n1","to":"n2"},
    {"from":"n2","to":"n3"}
  ],
  "metadata": {"name":"mini-poc"}
}

fixtures/envelope/sample.envelope.json (mini)

{
  "schemaVersion": "1.0.0",
  "source": "verify-lite",
  "generatedAt": "2025-10-06T00:00:00Z",
  "traceCorrelation": {"runId": "demo-run", "commit": "HEAD", "branch": "feat/ab-poc"},
  "summary": {"cases": 7, "passed": 7},
  "artifacts": [{"type":"json","path":"artifacts/verify-lite/verify-lite-run-summary.json"}]
}

---

8) Commands / コマンド例

# Run schema validation
npm run ci:validate:envelope

# Simulate AB flow execution (local)
npm run flow:run -- -f fixtures/flow/sample.flow.json

# Demo E2E
npm run demo:ab-poc

---

9) Owner & Labels / 担当とラベル

• Owners: @ootakazuhiko (P), @contrib-A (S)
• Labels: feature, architecture, ai-agent, good-first-pr (PR-1 only)

---

10) Risks & Checks / リスクとチェック

• Schema drift → snapshot + semver
• Adapter instability → versioned mapping table
• Non-determinism → scrub timestamps/ids in tests

---

11) Definition of Done / 完了基準

• CI validates Envelope/Flow fixtures;
• Adapter parses & simulates sample flow;
• PoC runs end-to-end and produces an Envelope;
• Docs published under /docs/agent-builder.

[ootakazuhiko]

Agent Builder vs Codex SDK — Integration Choice for ae-framework

Summary

We previously considered Agent Builder as the orchestration layer for ae-framework. After further analysis, we propose prioritizing Codex SDK for the glue/integration layer and treating Agent Builder as optional/adjacent. The SDK path better fits ae’s requirement for deterministic pipelines (Intent → Formal → Tests → Code → Verify → Operate), stronger programmatic control, and CLI非依存の単体アプリ化。

---

Decision (TL;DR)

• Primary: Adopt Codex SDK for core pipeline integration and execution control.
• Optional: Use Agent Builder only for rapid prototypes, demo workflows, or when a hosted UI-driven assembly of tools is explicitly beneficial.

---

Comparison Table

Aspect	Agent Builder	Codex SDK
Integration Style	Low/No-code orchestration UI; hosted	TypeScript library; embed directly in app
Control & Determinism	Medium (GUI-first, opinionated)	High (full programmatic control, versioned code)
State/Session Handling	Provided, but tool-driven	Explicit control via SDK threads/sessions
CI/CD & GitOps	Indirect; export/import flows	First-class via code; unit tests & code reviews
Extensibility	Plugins/connectors via UI	Any Node ecosystem pkg; custom adapters
Security & Sandboxing	Depends on hosted/runtime model	App-defined boundaries, least-privilege possible
Observability	UI-centric	Code-centric (structured logs/metrics/trace)
Vendor Lock-in Surface	Higher (flow definitions in platform)	Lower (flows live as code in repo)
Team Workflow	Good for non-devs	Best for devs; PR reviews & traceability
Offline/On-prem Story	Limited	Feasible (SDK + internal runners)

---

Why Agent Builder is less useful for ae-framework

1. Pipeline as Codeが必須：ae は厳密な検証（BDD/TLA+、OPA等）を前提とし、差分適用やリトライ戦略を「コードで」厳密化したい。GUI主導のフローでは再現性/差分管理が弱くなる。
2. 監査・再現性：Issue/PR/レビューで管理したい。フロー定義と履歴がGitにあることが重要。SDKならフルにGitOpsへ寄せられる。
3. 安全な適用：生成パッチのdry-run、署名付きコミット、権限分離実行（Podman/WSL/Runner）などを細かく設計したい。SDKは境界の設計自由度が高い。
4. オンプレ/閉域対応：自治体/研究機関案件での閉域運用に合わせやすい。
5. 拡張負債の抑制：UIベースの分岐や例外ハンドリングが膨らむとメンテが難しい。SDKで共通ミドル層をコード化した方が長期保守に向く。

---

When Agent Builder still helps

• デモ/PoC：社内外向けに短時間で“動くもの”を見せる。
• ノンエンジニア協業：一時的に運用部門と要件をすり合わせるUI。
• タスクランナー的に：既存コネクタを使う軽量業務フロー。

ただし本番の ae pipeline では、Agent Builder を中核に据えず、SDK 実装を正として最小限併用に留める。

---

Architecture (Proposed)

ae-app (Node/TS)
  ├─ ae-pipeline/ (Intent→Formal→Tests→Code→Verify→Operate as code)
  ├─ adapters/
  │   ├─ codex-sdk/  ← primary execution & code edits
  │   ├─ vcs/ (git, PR, review, signing)
  │   ├─ sandbox/ (podman, fs perms, rate limits)
  │   └─ verify/ (TLA+, OPA, test runners)
  └─ observability/ (jsonl logs, traces, metrics)

---

Migration Plan (Agent Builder → SDK)

1. Carve-out minimal core：Formal→Tests の1経路を SDK 化（thread管理・構造化出力・パッチ適用）。
2. Safety Rails：dry-run, diff gate, OPA policy、ロールバック戦略を標準化。
3. Verify-first：生成物は必ず BDD/TLA+/単体テストで検証→合格時のみcommit。
4. Observability：JSON Lines/trace-idで全処理を相関可能に。
5. Sunset UI flows：Agent Builderで作った一時フローは、段階的にSDKのコードへ反映し廃止。

---

Example (TypeScript skeleton)

import { Codex } from '@openai/codex-sdk';
import { planTasks, makePatch, applyPatchDryRun, commitIfClean } from './ae-core';

const codex = new Codex({ /* auth */ });

export async function runFormalToTests(repo: string, feature: string) {
  const thread = await codex.startThread({ repo });
  await thread.run(`Create BDD spec for: ${feature}`);
  const { patches, notes } = await thread.run('Generate tests; summarize risks as JSON');
  const dry = await applyPatchDryRun(repo, patches);
  if (dry.clean) await commitIfClean(repo, patches, `feat(test): add tests for ${feature}`);
  return { notes };
}

---

Risk & Mitigation

• API/SDK変更：SemVer監視と契約テスト。SDKラッパ層を用意。
• コスト/レート：キュー＆バッチング、リトライ/指数バックオフ、優先度制御。
• 誤編集：dry-run→レビュー→署名コミット→CI必須化。
• 閉域制約：キャッシュ、プロキシ、ミラー、runner分離。

---

Action Items

• SDKラッパ層 packages/ae-codex-adapter を雛形作成
• PoC: Formal→Tests ステージをSDK化（diff-gate付き）
• JSONLロギング＆trace-id規約を docs/observability.md に定義
• OPA/TLA+ 検証ゲートを verify:conformance に統合
• Agent Builder 既存フローの棚卸し→コード化計画を作成

---

日本語まとめ（最終判断）

• 結論：ae-framework では Codex SDK を主軸に採用し、Agent Builderは補助的利用にとどめる。
• 理由：再現性・監査性・安全適用・オンプレ対応・長期保守の観点で、Pipeline as Codeが適しているため。
• 次の一手：SDK PoCを直ちに着手し、成功後にハイブリッド期→全面移行へ。

#1071 Evaluate Codex SDK Integration into ae-framework

[ootakazuhiko]

Flow/Envelope スキーマ (PR #1184) と Verify Lite → Envelope 変換プラン (docs/verify-lite-envelope-plan) を準備済みです。次は packages/envelope を新設し、from-verify-lite.ts 実装に着手します。