#!/usr/bin/env node
// observed-agent.mjs —— ハーネスに観測レイヤーを組み込む（構造化ログ + トレースツリー + メトリクスサマリー）
// 使い方: node observed-agent.mjs --version v-good|v-bug|v-fixed
// 依存ゼロ、素の node で走る。モデル呼び出しは固定レスポンスキューのスタブクライアントが駆動し、3バージョンの差分は下の VERSIONS テーブルにある。
import fs from "node:fs";
import path from "node:path";
import crypto from "node:crypto";
const MODEL = "claude-sonnet-4-5";
const MAX_TOKENS = 4096;
const MAX_ROUNDS = 12; // ループの上限。超えたら暴走とみなし、非ゼロで終了する
const HEAD_CHARS = 60; // ログに残す内容抜粋の最大文字数。0 にすれば1文字も記録しない
// ============ 1. 対象タスク: data/ から売上 CSV を数本読み、地域ごとに集計して summary.md を書く ============
const CSV_FILES = {
"2026-q1-east.csv":
"region,month,amount\nEast China,2026-01,182400\nEast China,2026-02,161250\nEast China,2026-03,204900\n",
"2026-q1-south.csv":
"region,month,amount\nSouth China,2026-01,97300\nSouth China,2026-02,88600\nSouth China,2026-03,120450\n",
"2026-q1-north.csv":
"region,month,amount\nNorth China,2026-01,143000\nNorth China,2026-02,150700\nNorth China,2026-03,138900\n",
};
function setupWorkspace(root) {
fs.rmSync(root, { recursive: true, force: true });
fs.mkdirSync(path.join(root, "data"), { recursive: true });
for (const [name, body] of Object.entries(CSV_FILES)) {
fs.writeFileSync(path.join(root, "data", name), body);
}
}
// ============ 2. 3つのツール（本当にディスクを読み書きし、エラーも本物のエラー） ============
const tools = [
{
name: "list_files",
description: "ディレクトリ内のファイル名を辞書順にソートし、1行に1件で返す。",
input_schema: {
type: "object",
properties: { dir: { type: "string", description: "作業ディレクトリからの相対パス。例: data" } },
required: ["dir"],
},
},
{
name: "read_file",
description: "パスを指定してテキストファイルを読み、全文を返す。パスは list_files が返した元のファイル名を使うこと。",
input_schema: {
type: "object",
properties: { path: { type: "string", description: "作業ディレクトリからの相対ファイルパス" } },
required: ["path"],
},
},
{
name: "write_file",
description: "指定したパスにテキストを書き込む。同名のファイルは上書きする。",
input_schema: {
type: "object",
properties: {
path: { type: "string", description: "作業ディレクトリからの相対ファイルパス" },
content: { type: "string", description: "書き込む完全なテキスト" },
},
required: ["path", "content"],
},
},
];
function resolveInRoot(root, p) {
const abs = path.resolve(root, p);
if (abs !== root && !abs.startsWith(root + path.sep)) {
throw new Error(`パスが境界の外に出ています。アクセスを拒否します: ${p}`);
}
return abs;
}
const impls = {
list_files({ dir }, ctx) {
const abs = resolveInRoot(ctx.root, dir);
return fs.readdirSync(abs).sort().join("\n");
},
read_file({ path: p }, ctx) {
const abs = resolveInRoot(ctx.root, p);
if (fs.existsSync(abs)) return fs.readFileSync(abs, "utf8");
// 同じ「ファイルが存在しない」に対して、2種類の文面。v-fixed は実行可能な助言つきのほうを使う。
if (ctx.errorStyle === "actionable") {
const available = fs
.readdirSync(path.join(ctx.root, "data"))
.sort()
.map((f) => `data/${f}`)
.join(", ");
throw new Error(
`ファイル ${p} が見つかりません。現在 data/ にあるのは: ${available}。` +
`list_files が返した元のファイル名でリトライしてください。必要なデータが本当に存在しないなら、` +
`処理を止めて、どのファイルが足りないかをユーザーに伝えてください。欠けている数字を自分で見積もらないでください。`
);
}
throw new Error(`ENOENT: no such file or directory, open '${p}'`);
},
write_file({ path: p, content }, ctx) {
const abs = resolveInRoot(ctx.root, p);
fs.mkdirSync(path.dirname(abs), { recursive: true });
fs.writeFileSync(abs, content);
return `${p} を書き込みました（${content.length} 文字）`;
},
};
// ============ 3. スタブクライアント: 固定レスポンスキュー ============
const SUMMARY_CORRECT = `# 2026年Q1 地域別売上サマリー
| 地域 | 合計 (¥) |
| --- | --- |
| East China | 548550 |
| South China | 306350 |
| North China | 432600 |
| 総計 | 1287500 |
データソース: data/2026-q1-east.csv, data/2026-q1-south.csv, data/2026-q1-north.csv
`;
const SUMMARY_FABRICATED = `# 2026年Q1 地域別売上サマリー
| 地域 | 合計 (¥) |
| --- | --- |
| East China | 548550 |
| Central China | 208000 |
| North China | 432600 |
| 総計 | 1189150 |
データソース: data/ ディレクトリの CSV ファイル
`;
const say = (text) => ({ type: "text", text });
const call = (id, name, input) => ({ type: "tool_use", id, name, input });
const turn = (stop_reason, content, input_tokens, output_tokens) => ({
id: `msg_stub_${crypto.randomBytes(3).toString("hex")}`,
model: MODEL,
stop_reason,
content,
usage: { input_tokens, output_tokens },
});
const READ_EAST = call("toolu_e", "read_file", { path: "data/2026-q1-east.csv" });
const READ_NORTH = call("toolu_n", "read_file", { path: "data/2026-q1-north.csv" });
const READ_SOUTH = call("toolu_s", "read_file", { path: "data/2026-q1-south.csv" });
const READ_TYPO = call("toolu_x", "read_file", { path: "data/2026-q1-sourth.csv" });
const VERSIONS = {
// 順風満帆: CSV 3本とも読めて、集計も正しい。
"v-good": {
errorStyle: "opaque",
queue: [
turn("tool_use", [say("まず data/ に何のファイルがあるか見ます。"), call("toolu_l", "list_files", { dir: "data" })], 812, 96),
turn("tool_use", [say("地域別の CSV が3本あるので、まとめて読みます。"), READ_EAST, READ_SOUTH, READ_NORTH], 946, 218),
turn("tool_use", [say("3地域とも揃ったので、集計を書き出します。"), call("toolu_w", "write_file", { path: "summary.md", content: SUMMARY_CORRECT })], 1584, 342),
turn("end_turn", [say("summary.md を書き出しました: East China 548550、South China 306350、North China 432600、合計 1287500。")], 1961, 74),
],
},
// バグ版: 2本目の CSV のファイル名を打ち間違え、ツールは不透明なエラーを返し、モデルは止まらずに地域をでっち上げて書き進める。
"v-bug": {
errorStyle: "opaque",
queue: [
turn("tool_use", [say("まず data/ に何のファイルがあるか見ます。"), call("toolu_l", "list_files", { dir: "data" })], 812, 96),
turn("tool_use", [say("地域別の CSV が3本あるので、まとめて読みます。"), READ_EAST, READ_TYPO, READ_NORTH], 946, 218),
turn("tool_use", [say("データは揃ったので、集計を書き出します。"), call("toolu_w", "write_file", { path: "summary.md", content: SUMMARY_FABRICATED })], 1602, 355),
turn("end_turn", [say("summary.md を書き出しました: East China 548550、Central China 208000、North China 432600、合計 1189150。")], 1990, 81),
],
},
// 修正版: 打ち間違いは同じだが、エラーメッセージを実行可能な助言つきに差し替えたので、モデルはでっち上げずにリトライする。
"v-fixed": {
errorStyle: "actionable",
queue: [
turn("tool_use", [say("まず data/ に何のファイルがあるか見ます。"), call("toolu_l", "list_files", { dir: "data" })], 812, 96),
turn("tool_use", [say("地域別の CSV が3本あるので、まとめて読みます。"), READ_EAST, READ_TYPO, READ_NORTH], 946, 218),
turn("tool_use", [say("ファイル名を sourth と打ち間違えていました。エラーメッセージにある元のファイル名で読み直します。"), READ_SOUTH], 1688, 64),
turn("tool_use", [say("3地域とも揃ったので、集計を書き出します。"), call("toolu_w", "write_file", { path: "summary.md", content: SUMMARY_CORRECT })], 1849, 342),
turn("end_turn", [say("summary.md を書き出しました: East China 548550、South China 306350、North China 432600、合計 1287500。補足: 最初にファイル名を data/2026-q1-sourth.csv と打ち間違えたので、list_files が返した元の名前でリトライしました。data/ の外に他の地域のデータがあるなら、どこにファイルがあるか教えてください。数字を自分で埋めることはしません。")], 2226, 118),
],
},
};
function makeStubClient(queue) {
let i = 0;
return {
messages: {
async create(req) {
if (!req.model || !req.max_tokens) {
throw new Error("スタブクライアント: create には model と max_tokens が必要です");
}
if (i >= queue.length) {
const err = new Error(`スタブキューを使い切りました: ${i + 1} 回目のリクエストに対応する事前定義レスポンスがありません`);
err.code = "STUB_QUEUE_EXHAUSTED";
throw err;
}
return queue[i++];
},
},
};
}
// ============ 4. 観測レイヤーその1: 構造化ログ（JSON Lines） ============
const newId = (prefix) => `${prefix}-${crypto.randomBytes(4).toString("hex")}`;
function shapeOf(value) {
if (value === null || value === undefined) return "null";
if (Array.isArray(value)) return `array(${value.length})`;
if (typeof value === "string") return `string(${value.length})`;
if (typeof value === "object") return `object{${Object.keys(value).join(",")}}`;
return typeof value;
}
// デフォルトでは形状 + 長さ + 先頭 HEAD_CHARS 文字の抜粋だけを記録し、全文は記録しない。
function summarize(value) {
const text = typeof value === "string" ? value : JSON.stringify(value ?? null);
const out = { shape: shapeOf(value), chars: text.length };
if (HEAD_CHARS > 0) {
const flat = text.replace(/\s+/g, " ").trim();
out.head = flat.length > HEAD_CHARS ? `${flat.slice(0, HEAD_CHARS)}…` : flat;
}
return out;
}
function createLogger(logPath, traceId) {
fs.writeFileSync(logPath, "");
return {
record(fields) {
const line = { ts: new Date().toISOString(), trace_id: traceId, ...fields };
fs.appendFileSync(logPath, `${JSON.stringify(line)}\n`);
},
};
}
// ============ 5. 観測レイヤーその2: JSONL からトレースツリーを再構築する ============
function buildTree(records) {
const byId = new Map(records.map((r) => [r.span_id, { ...r, children: [] }]));
const roots = [];
for (const node of byId.values()) {
const parent = node.parent_id ? byId.get(node.parent_id) : null;
if (parent) parent.children.push(node);
else roots.push(node);
}
return roots;
}
const clip = (s, n) => (s.length > n ? `${s.slice(0, n)}…` : s);
function labelOf(n) {
const name = n.name.padEnd(13);
const dur = `${String(n.duration_ms).padStart(3)}ms`;
if (n.kind === "agent_run") return `agent_run ${name}${dur} trace_id=${n.trace_id}`;
if (n.kind === "model_call") {
const t = n.tokens;
return `model_call ${name}${dur} in=${t.input} out=${t.output} stop=${n.stop_reason}`;
}
if (n.kind === "harness_error") return `harness_err ${name}${dur} ${n.error.head ?? n.error.shape}`;
const inHead = clip(n.tool_input.head ?? n.tool_input.shape, 34);
const out = n.error ? `ERROR ${clip(n.error.head ?? n.error.shape, 44)}` : `ok ${n.tool_result.shape}`;
return `tool_call ${name}${dur} in=${inHead} ${out}`;
}
function renderTree(nodes, prefix, lines) {
nodes.forEach((node, idx) => {
const last = idx === nodes.length - 1;
lines.push(prefix === null ? labelOf(node) : `${prefix}${last ? "└─ " : "├─ "}${labelOf(node)}`);
const childPrefix = prefix === null ? "" : `${prefix}${last ? " " : "│ "}`;
renderTree(node.children, childPrefix, lines);
});
return lines;
}
// ============ 6. 観測レイヤーその3: メトリクスサマリー ============
function metricsOf(records) {
const model = records.filter((r) => r.kind === "model_call");
const tool = records.filter((r) => r.kind === "tool_call");
const root = records.find((r) => r.kind === "agent_run");
return {
// このハーネスでは1ラウンド = 1回のモデルリクエストなので、rounds はそのまま model_calls を取る。
// スタブキューを使い切って harness_error を投げた場合、最後のラウンドには対応する model_call がない——その実行ではこの2つの数字が1つずれる
rounds: model.length,
model_calls: model.length,
tool_calls: tool.length,
errors: records.filter((r) => r.error).length,
tokens_in: model.reduce((s, r) => s + r.tokens.input, 0),
tokens_out: model.reduce((s, r) => s + r.tokens.output, 0),
wall_ms: root ? root.duration_ms : 0,
};
}
// ============ 7. 観測されるハーネスループ ============
async function runToolUses(content, ctx) {
const results = [];
for (const block of content) {
if (block.type !== "tool_use") continue;
const spanId = newId("span");
const startedAt = Date.now();
const base = {
span_id: spanId,
parent_id: ctx.parentId,
kind: "tool_call",
name: block.name,
tool_input: summarize(block.input),
};
try {
const impl = impls[block.name];
if (!impl) throw new Error(`未知のツール: ${block.name}`);
const result = impl(block.input, ctx);
ctx.log.record({ ...base, duration_ms: Date.now() - startedAt, tool_result: summarize(result), error: null });
results.push({ type: "tool_result", tool_use_id: block.id, content: result });
} catch (e) {
ctx.log.record({ ...base, duration_ms: Date.now() - startedAt, tool_result: null, error: summarize(e.message) });
results.push({ type: "tool_result", tool_use_id: block.id, content: e.message, is_error: true });
}
}
return results;
}
async function main() {
const argv = process.argv.slice(2);
const version = argv[argv.indexOf("--version") + 1];
if (!argv.includes("--version") || !VERSIONS[version]) {
console.error("使い方: node observed-agent.mjs --version v-good|v-bug|v-fixed");
process.exit(2);
}
const root = path.resolve(process.cwd(), "runs", version);
setupWorkspace(root);
const traceId = newId("tr");
const log = createLogger(path.join(root, "run.log.jsonl"), traceId);
const rootSpan = newId("span");
const runStartedAt = Date.now();
const { queue, errorStyle } = VERSIONS[version];
const client = makeStubClient(queue);
const ctx = { root, errorStyle, log, parentId: rootSpan };
const messages = [
{
role: "user",
content: "data/ ディレクトリの売上 CSV を地域ごとの合計に集計し、summary.md に書き出してください。ファイルに実在するデータだけを使ってください。",
},
];
let rounds = 0;
let exitCode = 0;
const callModel = async () => {
const spanId = newId("span");
const startedAt = Date.now();
rounds += 1;
const response = await client.messages.create({ model: MODEL, max_tokens: MAX_TOKENS, tools, messages });
log.record({
span_id: spanId,
parent_id: rootSpan,
kind: "model_call",
name: `turn-${rounds}`,
duration_ms: Date.now() - startedAt,
stop_reason: response.stop_reason,
tokens: { input: response.usage.input_tokens, output: response.usage.output_tokens },
error: null,
});
ctx.parentId = spanId;
return response;
};
try {
let response = await callModel();
while (response.stop_reason === "tool_use") {
if (rounds >= MAX_ROUNDS) throw new Error(`MAX_ROUNDS=${MAX_ROUNDS} を超過しました。暴走と判断します`);
messages.push({ role: "assistant", content: response.content });
const toolResults = await runToolUses(response.content, ctx);
messages.push({ role: "user", content: toolResults });
response = await callModel();
}
} catch (e) {
log.record({
span_id: newId("span"),
parent_id: rootSpan,
kind: "harness_error",
name: e.code ?? "harness_error",
duration_ms: 0,
error: summarize(e.message),
});
console.error(`ハーネスが中断しました: ${e.message}`);
exitCode = 2;
}
log.record({
span_id: rootSpan,
parent_id: null,
kind: "agent_run",
name: "sales-summary",
duration_ms: Date.now() - runStartedAt,
error: null,
});
// 実行が終わった後、ディスク上の JSONL だけからビューを再構築する——メモリ上のコピーは数に入れない。
const records = fs
.readFileSync(path.join(root, "run.log.jsonl"), "utf8")
.split("\n")
.filter(Boolean)
.map((l) => JSON.parse(l));
const m = metricsOf(records);
console.log(`\n=== トレースツリー（${version}、run.log.jsonl から再構築）===`);
console.log(renderTree(buildTree(records), null, []).join("\n"));
console.log(
`\n=== メトリクスサマリー（${version}）===\n` +
`rounds=${m.rounds} model_calls=${m.model_calls} tool_calls=${m.tool_calls} ` +
`errors=${m.errors} tokens_in=${m.tokens_in} tokens_out=${m.tokens_out} ` +
`tokens_total=${m.tokens_in + m.tokens_out} wall=${m.wall_ms}ms`
);
console.log(`ログ: runs/${version}/run.log.jsonl 成果物: runs/${version}/summary.md`);
process.exit(exitCode);
}
main();