STEP 1639 — Agent connector Phase 2 3 tool 実装 test 88/88 verify defer

2026-09-01 · STEP 1634 Phase 1 pinout 実測 (4/6 pass + 2/6 fail) 受けて Phase 2 実装 · src/agent-connector/ 6 file (~500 line) · test test/step1639-agent-connector-test.ts 88/88 PASS · npm test:step1639

Overview — Phase 2 の位置と産物

Phase 1 (STEP 1634) recommendation: 「detect / pinout / invoke = 実装可、 verify tool は defer 妥当 (spec 化できない、 Phase 2.5 で別 arc 起動提案)、 pin 3+4 は caller 責任で config 事前準備 (connector が config 変換責任を負わない decoupling)」

Phase 2 done: 上記 recommendation そのまま 3 tool 実装、 verify defer。副作用は invoke({ mode: 'execute' }) のみ (subprocess spawn)、 mode は required で default なし = 呼出側が毎回明示的に選択する強制 (STEP 1345 SafetyGate + STEP 1625 陰性対照と同族の safety discipline)。

1. Module 構成

File	役割	Side effect
`src/agent-connector/types.ts`	AgentName / Pin / PinoutResult / DetectResult / InvokeOptions / InvokeResult 型定義 (全 readonly)	なし
`src/agent-connector/pins-data.ts`	Phase 1 (STEP 1634) の 6 pin data を `PINS_PHASE1` const で encode + `PHASE1_HONEST_SCOPE`	なし (static data)
`src/agent-connector/detect.ts`	`detect(agent)` + `detectAll()` — `execFile('claude', ['--version'])` で CLI 検出、 semver-ish regex で version 抽出、 `where`/`which` で CLI path 抽出	subprocess spawn (read-only: --version + which 呼出のみ)
`src/agent-connector/pinout.ts`	`pinout()` + `pinById(id)` + `pinsByVerdict(v)` + `pinsWithInformationLoss()` — pins-data.ts を programmatic API 化	なし (pure function)
`src/agent-connector/invoke.ts`	`invoke(agent, opts)` — dryRun mode で command argv 返却、 execute mode で subprocess spawn + timeout + stdout/stderr/exitCode 返却	subprocess spawn (execute mode のみ、 dryRun mode はなし)
`src/agent-connector/index.ts`	Public re-export	なし

2. API examples

2.1 detect

import { detect, detectAll } from './agent-connector/index.js';

const d = await detect('claude');
// {
//   agent: 'claude',
//   isAvailable: true,
//   cliPath: 'C:\\Users\\user\\.local\\bin\\claude.exe',
//   version: '2.1.251',
//   rawVersionOutput: '2.1.251 (Claude Code)',
//   detectedAt: '2026-09-01T00:47:...Z'
// }

const all = await detectAll();
// { claude: {...isAvailable:true}, codex: {...isAvailable:false, error:'...'} }

2.2 pinout

import { pinout, pinById, pinsByVerdict } from './agent-connector/index.js';

const p = pinout();
// {
//   pins: [ ...6 pin ],
//   summary: { total: 6, pass: 3, partial: 1, fail: 2, falsificationRate: 0.333 },
//   generatedAt: '...',
//   phase1Ref: 'https://rei-aios.pages.dev/tools/step-1634-agent-pinout-phase1/',
//   honestScope: [ ...6 items ]
// }

const mcpPin = pinById('mcp_config');
// { id: 'mcp_config', verdict: 'fail', informationLoss: { direction: 'bidirectional', ... } }

const failPins = pinsByVerdict('fail'); // [mcp_config, permission]

2.3 invoke (dryRun / execute)

import { invoke } from './agent-connector/index.js';

// dryRun mode = argv を 返すのみ、 spawn しない
const dry = await invoke('claude', {
  mode: 'dryRun',
  prompt: 'summarize this',
  outputFormat: 'stream-json',
  extraArgs: ['--verbose'],
});
// {
//   agent: 'claude', mode: 'dryRun',
//   command: ['claude', '-p', '--output-format', 'stream-json', '--verbose', 'summarize this']
// }

// execute mode = 実 CLI spawn (billable + side-effect)
const exec = await invoke('claude', {
  mode: 'execute',       // ★ REQUIRED、 default なし
  prompt: 'ping',
  timeoutMs: 30_000,
});
// { agent, mode: 'execute', command, stdout, stderr, exitCode, elapsedMs, timedOut }

3. Safety discipline

mode required: InvokeOptions.mode: 'dryRun' | 'execute' は型レベルで required、 TypeScript の型検査で呼出側が毎回明示することを強制。「うっかり execute」を型で防ぐ。
timeout min 1000ms: 極端に短い timeout での意図せぬ子 process 大量 spawn を防ぐ (default 60s、 caller 指定は max(specified, 1000ms))。
Pin 3+4 は passthrough しない: MCP config (pin 3) + permission (pin 4) は connector で変換せず、 caller が extraArgs で provider 別 flag を直接渡す前提。 Phase 1 「decoupling」 principle の実装体現。
execute test は opt-in: STEP1639_RUN_EXECUTE=1 env var でのみ execute mode test 実行、 default では skip。 dryRun で argv 構築の正しさ十分検証、 execute は billable + side-effect で CI 化避け。
shell: false: spawn(cmd, args, { shell: false }) = shell interpolation なし = injection 防止。

4. Test 結果 88/88 PASS

Section	test 内容	件数
1. detect	claude available + codex not-installed + detectAll 挙動	10 assert
2. pinout	6 pin 返却 + summary (pass 3 / partial 1 / fail 2 / falsification rate 2/6)	14 assert
3. pinout helpers	pinById / pinsByVerdict / pinsWithInformationLoss / unknown 挙動	10 assert
4. invoke dryRun	argv 構築正確、 claude -p / codex exec / --output-format / extraArgs passthrough	13 assert
5. invoke execute	opt-in mode の skip 動作 (STEP1639_RUN_EXECUTE=1 で実行)	0 assert (skip 状態確認のみ)
6. error handling	codex execute → ENOENT (graceful error return、 throw しない)	3 assert
7. pin data invariants	6 pin 全て refutation ≥3 + source valid + fail pin 全て informationLoss あり	38 assert

Total: 88 assert PASS / 0 fail。実行: npm run test:step1639。

5. 実測 detect 出力 (本 PC)

=== Section 1: detect ===
  claude: v2.1.251 at C:\Users\user\.local\bin\claude.exe
  codex: not installed on this PC (expected on Windows dev box)

Phase 1 環境非対称性 (Codex CLI 未 install) を connector が正しく handle: detect('codex') は isAvailable=false + error message + throw なし、 invoke('codex', {mode:'execute'}) は ENOENT を error field に収める。

6. Phase 1 pin data の Phase 2 反映

Phase 2 では Phase 1 の pin 4 field をそのまま encode:

pin 3 (MCP config): verdict='fail'、 informationLoss.direction='bidirectional' (JSON vs TOML、 lossless 変換未定義)
pin 4 (permission): verdict='fail'、 informationLoss.direction='bidirectional' (fine-grained allowlist vs 3-tier sandbox、双方向情報損失)

pinsWithInformationLoss() で上記 2 pin を一覧取得可能。 caller はこれを見て「直接 pass-through しない、 provider 別 config を事前準備」の判断ができる。

7. Verify tool (Phase 2.5) defer 理由

Phase 1 で verify tool の spec 化不能と判明:

Verify の定義自体が pin 4 (permission) の意味論差に依存 (sandbox 違反 = 何を「違反」とするかが provider 依存)
Pin 6 (exit code) の semantics が両側 fetch 未達 (permission denied / sandbox 違反 / SIGINT の exit code 未確認)
「invoke 成功 = verify pass」も「exit code 0 = 実質成功」も保証できない (Claude Code は exit code semantics 未公式化、 Codex は required MCP fail のみ documented)

Phase 2.5 別 arc で defer、前提条件: (a) 両 CLI の exit code semantics 実測 (b) sandbox / permission 意味論の cross-provider 共通 subset 定義 (c) 「verify pass」の定義自体を rei stack のどの verdict vocabulary (TRUE / NEITHER / N/A) に落とすかの判断。

8. Honest scope (Phase 2 で意図的にやっていないこと)

❌ MCP server として expose (本 Phase 2 は TypeScript library のみ、 src/mcp/ への tool 追加は別 STEP)。 rei-aios MCP に register するなら invoke の execute mode は SafetyGate 越しラッピング必要。
❌ Codex 側実 execute mode 検証 (本 PC 未 install、 dryRun mode の argv 構築が Codex 公式 CLI と一致するかの実測は未達、 codex --help 出力 vs buildArgv() の突合せは別 STEP)。
❌ MCP config + permission の変換 helper (Phase 1 decoupling principle 準拠、 pin 3+4 は caller 責任、変換 helper は別 spec が必要 = Phase 3 or 別 arc)。
❌ Version 差対応 (Claude Code v2.1.251 で動作確認、古い version / 新 version の flag 差は pins-data.ts の update で対応、 auto-detect version 別 argv builder は未実装)。
❌ Codex CLI 実 install (藤本さん judgment 待ち、 install すれば pin 全部実測化可能 + Phase 2 execute mode の双方向実測 + Phase 2.5 verify spec の前提条件拡充)。

9. 次 STEP candidate

Phase 2.5 GO 判断 (藤本さん): verify tool spec 化の前提条件 (exit code semantics 実測 + cross-provider verdict vocabulary 定義) を別 arc で詰めるか。
rei-aios MCP register: src/mcp/agent-connector-mcp.ts で detect / pinout tool を expose (invoke は SafetyGate 越しラッピング必要、 or defer)。
Codex CLI install (藤本さん judgment): 本 PC に codex install で Phase 2 execute mode の双方向実測可、 Phase 1 反証条件 tightening も進む。
Phase 3 Archify IR emit spike: agent-connector と独立進行可、 rei-aios connector-inventory / comparator JSON から Archify IR 直接生成の PoC (Phase 2 完了の後前提なし)。

Overview — Phase 2 の 位置と 産物