@obov/mext 0.5.0 → 0.7.1

package/dist/inspect/profiles.js

@@ -0,0 +1,235 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { isSegment } from "../ids.js";
+/**
+ * 호출자 프로필 (specs/inspector.md §2): 토큰 · 헤더 묶음에 이름을 붙인 것.
+ * 파일에는 환경변수 이름만 적는다 (토큰 평문 금지). 값은 호출할 때마다 환경변수에서 읽고 저장 · 출력하지 않는다
+ */
+/** <프로젝트>/inspect */
+export const INSPECT_DIR = "inspect";
+export const PROFILES_FILE = "profiles.json";
+/** 프로필 파일이 없을 때의 내장 프로필 이름 · 토큰 환경변수 */
+export const DEFAULT_PROFILE = "default";
+export const DEFAULT_TOKEN_ENV = "MEXT_TOKEN";
+/** 가린 값의 표시 */
+export const REDACTED = "[redacted]";
+/** 프로필 파일 형식 오류. issues = "<경로>: <문제>" */
+export class ProfileFileError extends Error {
+    file;
+    issues;
+    constructor(file, issues) {
+        super(`${file}: invalid profiles file\n${issues.map((i) => `  ${i}`).join("\n")}`);
+        this.name = "ProfileFileError";
+        this.file = file;
+        this.issues = issues;
+    }
+}
+/** 환경변수가 없어 그 프로필로 호출할 수 없다. 호출을 보내지 않는다 */
+export class ProfileUnavailableError extends Error {
+    code = "PROFILE_UNAVAILABLE";
+    profile;
+    /** 없는 환경변수 이름 */
+    missing;
+    constructor(profile, missing) {
+        super(`Profile "${profile}" needs environment variable${missing.length === 1 ? "" : "s"} ${missing.join(", ")} (not set).`);
+        this.name = "ProfileUnavailableError";
+        this.profile = profile;
+        this.missing = missing;
+    }
+}
+/** 문자열 값을 허용하지 않는 헤더 (비밀): 환경변수 참조만 */
+const SECRET_HEADERS = new Set(["authorization", "cookie", "proxy-authorization"]);
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const HEADER_NAME = /^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/;
+/** <cwd>/inspect/profiles.json 또는 지정한 경로 */
+export function profilesPath(cwd, override) {
+    return override === undefined ? join(resolve(cwd), INSPECT_DIR, PROFILES_FILE) : resolve(cwd, override);
+}
+/**
+ * 프로필 파일 읽기. 파일 없음 = 내장 프로필 default (MEXT_TOKEN 이 있으면 그 토큰. override 로 지정한 파일이 없으면 오류).
+ * 형식 오류 = ProfileFileError (문제를 모두 모아 한 번에)
+ */
+export function loadProfiles(cwd, options = {}) {
+    const file = profilesPath(cwd, options.file);
+    if (!existsSync(file)) {
+        if (options.file !== undefined)
+            throw new ProfileFileError(file, ["file not found"]);
+        const env = options.env ?? process.env;
+        const hasToken = env[DEFAULT_TOKEN_ENV] !== undefined && env[DEFAULT_TOKEN_ENV] !== "";
+        return {
+            file: undefined,
+            default: DEFAULT_PROFILE,
+            profiles: [
+                {
+                    name: DEFAULT_PROFILE,
+                    description: hasToken ? `Token from ${DEFAULT_TOKEN_ENV}` : `No token (set ${DEFAULT_TOKEN_ENV}, or add ${INSPECT_DIR}/${PROFILES_FILE})`,
+                    ...(hasToken ? { token: { env: DEFAULT_TOKEN_ENV } } : {}),
+                    headers: {},
+                },
+            ],
+        };
+    }
+    let value;
+    try {
+        value = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        throw new ProfileFileError(file, [`not valid JSON (${error instanceof Error ? error.message : String(error)})`]);
+    }
+    return parseProfiles(value, file);
+}
+/** 프로필 파일 내용 검증 */
+export function parseProfiles(value, file) {
+    const issues = [];
+    if (!isObject(value))
+        throw new ProfileFileError(file, ['must be an object ({ "profiles": { … } })']);
+    for (const key of Object.keys(value))
+        if (key !== "profiles" && key !== "default")
+            issues.push(`${key}: unknown key`);
+    const profiles = [];
+    if (!isObject(value.profiles) || Object.keys(value.profiles).length === 0) {
+        issues.push("profiles: must be an object with at least one profile");
+    }
+    else {
+        for (const [name, raw] of Object.entries(value.profiles)) {
+            const profile = parseProfile(name, raw, issues);
+            if (profile)
+                profiles.push(profile);
+        }
+    }
+    let fallback = profiles[0]?.name ?? DEFAULT_PROFILE;
+    if (value.default !== undefined) {
+        if (typeof value.default !== "string" || !profiles.some((p) => p.name === value.default)) {
+            issues.push(`default: must be one of the profile names (${profiles.map((p) => p.name).join(", ")})`);
+        }
+        else
+            fallback = value.default;
+    }
+    if (issues.length > 0)
+        throw new ProfileFileError(file, issues);
+    return { file, default: fallback, profiles };
+}
+function parseProfile(name, raw, issues) {
+    const at = `profiles.${name}`;
+    const before = issues.length;
+    if (!isSegment(name))
+        issues.push(`${at}: profile name must be kebab-case`);
+    if (!isObject(raw)) {
+        issues.push(`${at}: must be an object`);
+        return undefined;
+    }
+    for (const key of Object.keys(raw)) {
+        if (!["description", "token", "headers", "clientInfo"].includes(key))
+            issues.push(`${at}.${key}: unknown key`);
+    }
+    const profile = { name, headers: {} };
+    if (raw.description !== undefined) {
+        if (typeof raw.description !== "string")
+            issues.push(`${at}.description: must be a string`);
+        else
+            profile.description = raw.description;
+    }
+    if (raw.token !== undefined) {
+        const ref = envRef(raw.token);
+        if (ref)
+            profile.token = ref;
+        else if (typeof raw.token === "string") {
+            issues.push(`${at}.token: must be { "env": "<variable name>" }. Do not write token values in this file`);
+        }
+        else
+            issues.push(`${at}.token: must be { "env": "<variable name>" }`);
+    }
+    if (raw.headers !== undefined) {
+        if (!isObject(raw.headers))
+            issues.push(`${at}.headers: must be an object`);
+        else {
+            for (const [header, v] of Object.entries(raw.headers)) {
+                const where = `${at}.headers.${header}`;
+                if (!HEADER_NAME.test(header))
+                    issues.push(`${where}: not a valid header name`);
+                const ref = envRef(v);
+                if (ref)
+                    profile.headers[header] = ref;
+                else if (typeof v !== "string")
+                    issues.push(`${where}: must be a string or { "env": "<variable name>" }`);
+                else if (SECRET_HEADERS.has(header.toLowerCase())) {
+                    issues.push(`${where}: must be { "env": "<variable name>" }. Do not write secret header values in this file`);
+                }
+                else
+                    profile.headers[header] = v;
+            }
+        }
+    }
+    if (raw.clientInfo !== undefined) {
+        const c = raw.clientInfo;
+        if (!isObject(c) || typeof c.name !== "string" || c.name === "" || (c.version !== undefined && typeof c.version !== "string")) {
+            issues.push(`${at}.clientInfo: must be { "name": string, "version"?: string }`);
+        }
+        else
+            profile.clientInfo = { name: c.name, version: typeof c.version === "string" ? c.version : "0.0.0" };
+    }
+    return issues.length > before ? undefined : profile;
+}
+function envRef(value) {
+    if (!isObject(value))
+        return undefined;
+    const keys = Object.keys(value);
+    return keys.length === 1 && typeof value.env === "string" && ENV_NAME.test(value.env) ? { env: value.env } : undefined;
+}
+export function findProfile(set, name) {
+    return set.profiles.find((p) => p.name === (name ?? set.default));
+}
+/** 환경변수에서 값 읽기. 없는 변수 = ProfileUnavailableError */
+export function resolveProfile(profile, env = process.env) {
+    const missing = [];
+    const secrets = [];
+    const read = (ref) => {
+        const value = env[ref.env];
+        if (value === undefined || value === "") {
+            if (!missing.includes(ref.env))
+                missing.push(ref.env);
+            return "";
+        }
+        secrets.push(value);
+        return value;
+    };
+    const token = profile.token ? read(profile.token) : undefined;
+    const headers = {};
+    for (const [name, value] of Object.entries(profile.headers))
+        headers[name] = typeof value === "string" ? value : read(value);
+    if (missing.length > 0)
+        throw new ProfileUnavailableError(profile.name, missing);
+    return { token, headers, secrets };
+}
+export function describeProfiles(set, env = process.env) {
+    const isSet = (name) => env[name] !== undefined && env[name] !== "";
+    return set.profiles.map((p) => {
+        const headers = Object.entries(p.headers).map(([name, value]) => typeof value === "string" ? { name, value } : { name, env: value.env, set: isSet(value.env) });
+        const view = {
+            name: p.name,
+            default: p.name === set.default,
+            headers,
+            available: (p.token === undefined || isSet(p.token.env)) && headers.every((h) => h.set !== false),
+        };
+        if (p.description !== undefined)
+            view.description = p.description;
+        if (p.token)
+            view.token = { env: p.token.env, set: isSet(p.token.env) };
+        if (p.clientInfo)
+            view.clientInfo = p.clientInfo;
+        return view;
+    });
+}
+/** 문자열 안의 비밀 값을 [redacted] 로 (긴 값부터: 한 값이 다른 값의 일부일 때 긴 쪽이 남지 않게) */
+export function redact(text, secrets) {
+    let out = text;
+    for (const secret of [...secrets].sort((a, b) => b.length - a.length)) {
+        if (secret !== "")
+            out = out.split(secret).join(REDACTED);
+    }
+    return out;
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=profiles.js.map

package/dist/inspect/profiles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiles.js","sourceRoot":"","sources":["../../src/inspect/profiles.ts"],"names":[],"mappings":"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","sourcesContent":["import { existsSync, readFileSync } from \"node:fs\"\nimport { join, resolve } from \"node:path\"\nimport { isSegment } from \"../ids.ts\"\n\n/**\n * 호출자 프로필 (specs/inspector.md §2): 토큰 · 헤더 묶음에 이름을 붙인 것.\n * 파일에는 환경변수 이름만 적는다 (토큰 평문 금지). 값은 호출할 때마다 환경변수에서 읽고 저장 · 출력하지 않는다\n */\n\n/** <프로젝트>/inspect */\nexport const INSPECT_DIR = \"inspect\"\nexport const PROFILES_FILE = \"profiles.json\"\n/** 프로필 파일이 없을 때의 내장 프로필 이름 · 토큰 환경변수 */\nexport const DEFAULT_PROFILE = \"default\"\nexport const DEFAULT_TOKEN_ENV = \"MEXT_TOKEN\"\n/** 가린 값의 표시 */\nexport const REDACTED = \"[redacted]\"\n\n/** 환경변수 참조 */\nexport interface EnvRef {\n  env: string\n}\n\nexport interface Profile {\n  name: string\n  description?: string\n  token?: EnvRef\n  /** 이름 → 문자열 (비밀 아님) 또는 환경변수 참조 */\n  headers: Record<string, string | EnvRef>\n  clientInfo?: { name: string; version: string }\n}\n\nexport interface ProfileSet {\n  /** 읽은 파일 (절대 경로). 없음 = 내장 프로필 */\n  file: string | undefined\n  /** 프로필을 지정하지 않은 호출이 쓰는 이름 */\n  default: string\n  /** 파일에 적힌 순서 */\n  profiles: Profile[]\n}\n\n/** 프로필 파일 형식 오류. issues = \"<경로>: <문제>\" */\nexport class ProfileFileError extends Error {\n  readonly file: string\n  readonly issues: readonly string[]\n  constructor(file: string, issues: readonly string[]) {\n    super(`${file}: invalid profiles file\\n${issues.map((i) => `  ${i}`).join(\"\\n\")}`)\n    this.name = \"ProfileFileError\"\n    this.file = file\n    this.issues = issues\n  }\n}\n\n/** 환경변수가 없어 그 프로필로 호출할 수 없다. 호출을 보내지 않는다 */\nexport class ProfileUnavailableError extends Error {\n  readonly code = \"PROFILE_UNAVAILABLE\"\n  readonly profile: string\n  /** 없는 환경변수 이름 */\n  readonly missing: readonly string[]\n  constructor(profile: string, missing: readonly string[]) {\n    super(`Profile \"${profile}\" needs environment variable${missing.length === 1 ? \"\" : \"s\"} ${missing.join(\", \")} (not set).`)\n    this.name = \"ProfileUnavailableError\"\n    this.profile = profile\n    this.missing = missing\n  }\n}\n\n/** 문자열 값을 허용하지 않는 헤더 (비밀): 환경변수 참조만 */\nconst SECRET_HEADERS = new Set([\"authorization\", \"cookie\", \"proxy-authorization\"])\nconst ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/\nconst HEADER_NAME = /^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/\n\n/** <cwd>/inspect/profiles.json 또는 지정한 경로 */\nexport function profilesPath(cwd: string, override?: string): string {\n  return override === undefined ? join(resolve(cwd), INSPECT_DIR, PROFILES_FILE) : resolve(cwd, override)\n}\n\n/**\n * 프로필 파일 읽기. 파일 없음 = 내장 프로필 default (MEXT_TOKEN 이 있으면 그 토큰. override 로 지정한 파일이 없으면 오류).\n * 형식 오류 = ProfileFileError (문제를 모두 모아 한 번에)\n */\nexport function loadProfiles(cwd: string, options: { file?: string; env?: Record<string, string | undefined> } = {}): ProfileSet {\n  const file = profilesPath(cwd, options.file)\n  if (!existsSync(file)) {\n    if (options.file !== undefined) throw new ProfileFileError(file, [\"file not found\"])\n    const env = options.env ?? process.env\n    const hasToken = env[DEFAULT_TOKEN_ENV] !== undefined && env[DEFAULT_TOKEN_ENV] !== \"\"\n    return {\n      file: undefined,\n      default: DEFAULT_PROFILE,\n      profiles: [\n        {\n          name: DEFAULT_PROFILE,\n          description: hasToken ? `Token from ${DEFAULT_TOKEN_ENV}` : `No token (set ${DEFAULT_TOKEN_ENV}, or add ${INSPECT_DIR}/${PROFILES_FILE})`,\n          ...(hasToken ? { token: { env: DEFAULT_TOKEN_ENV } } : {}),\n          headers: {},\n        },\n      ],\n    }\n  }\n  let value: unknown\n  try {\n    value = JSON.parse(readFileSync(file, \"utf8\"))\n  } catch (error) {\n    throw new ProfileFileError(file, [`not valid JSON (${error instanceof Error ? error.message : String(error)})`])\n  }\n  return parseProfiles(value, file)\n}\n\n/** 프로필 파일 내용 검증 */\nexport function parseProfiles(value: unknown, file: string): ProfileSet {\n  const issues: string[] = []\n  if (!isObject(value)) throw new ProfileFileError(file, ['must be an object ({ \"profiles\": { … } })'])\n  for (const key of Object.keys(value)) if (key !== \"profiles\" && key !== \"default\") issues.push(`${key}: unknown key`)\n  const profiles: Profile[] = []\n  if (!isObject(value.profiles) || Object.keys(value.profiles).length === 0) {\n    issues.push(\"profiles: must be an object with at least one profile\")\n  } else {\n    for (const [name, raw] of Object.entries(value.profiles)) {\n      const profile = parseProfile(name, raw, issues)\n      if (profile) profiles.push(profile)\n    }\n  }\n  let fallback = profiles[0]?.name ?? DEFAULT_PROFILE\n  if (value.default !== undefined) {\n    if (typeof value.default !== \"string\" || !profiles.some((p) => p.name === value.default)) {\n      issues.push(`default: must be one of the profile names (${profiles.map((p) => p.name).join(\", \")})`)\n    } else fallback = value.default\n  }\n  if (issues.length > 0) throw new ProfileFileError(file, issues)\n  return { file, default: fallback, profiles }\n}\n\nfunction parseProfile(name: string, raw: unknown, issues: string[]): Profile | undefined {\n  const at = `profiles.${name}`\n  const before = issues.length\n  if (!isSegment(name)) issues.push(`${at}: profile name must be kebab-case`)\n  if (!isObject(raw)) {\n    issues.push(`${at}: must be an object`)\n    return undefined\n  }\n  for (const key of Object.keys(raw)) {\n    if (![\"description\", \"token\", \"headers\", \"clientInfo\"].includes(key)) issues.push(`${at}.${key}: unknown key`)\n  }\n  const profile: Profile = { name, headers: {} }\n  if (raw.description !== undefined) {\n    if (typeof raw.description !== \"string\") issues.push(`${at}.description: must be a string`)\n    else profile.description = raw.description\n  }\n  if (raw.token !== undefined) {\n    const ref = envRef(raw.token)\n    if (ref) profile.token = ref\n    else if (typeof raw.token === \"string\") {\n      issues.push(`${at}.token: must be { \"env\": \"<variable name>\" }. Do not write token values in this file`)\n    } else issues.push(`${at}.token: must be { \"env\": \"<variable name>\" }`)\n  }\n  if (raw.headers !== undefined) {\n    if (!isObject(raw.headers)) issues.push(`${at}.headers: must be an object`)\n    else {\n      for (const [header, v] of Object.entries(raw.headers)) {\n        const where = `${at}.headers.${header}`\n        if (!HEADER_NAME.test(header)) issues.push(`${where}: not a valid header name`)\n        const ref = envRef(v)\n        if (ref) profile.headers[header] = ref\n        else if (typeof v !== \"string\") issues.push(`${where}: must be a string or { \"env\": \"<variable name>\" }`)\n        else if (SECRET_HEADERS.has(header.toLowerCase())) {\n          issues.push(`${where}: must be { \"env\": \"<variable name>\" }. Do not write secret header values in this file`)\n        } else profile.headers[header] = v\n      }\n    }\n  }\n  if (raw.clientInfo !== undefined) {\n    const c = raw.clientInfo\n    if (!isObject(c) || typeof c.name !== \"string\" || c.name === \"\" || (c.version !== undefined && typeof c.version !== \"string\")) {\n      issues.push(`${at}.clientInfo: must be { \"name\": string, \"version\"?: string }`)\n    } else profile.clientInfo = { name: c.name, version: typeof c.version === \"string\" ? c.version : \"0.0.0\" }\n  }\n  return issues.length > before ? undefined : profile\n}\n\nfunction envRef(value: unknown): EnvRef | undefined {\n  if (!isObject(value)) return undefined\n  const keys = Object.keys(value)\n  return keys.length === 1 && typeof value.env === \"string\" && ENV_NAME.test(value.env) ? { env: value.env } : undefined\n}\n\nexport function findProfile(set: ProfileSet, name: string | undefined): Profile | undefined {\n  return set.profiles.find((p) => p.name === (name ?? set.default))\n}\n\n/** 호출 직전에 읽은 값. secrets = 가려야 하는 값 (환경변수에서 읽은 것 전부) */\nexport interface ResolvedProfile {\n  token: string | undefined\n  headers: Record<string, string>\n  secrets: string[]\n}\n\n/** 환경변수에서 값 읽기. 없는 변수 = ProfileUnavailableError */\nexport function resolveProfile(profile: Profile, env: Record<string, string | undefined> = process.env): ResolvedProfile {\n  const missing: string[] = []\n  const secrets: string[] = []\n  const read = (ref: EnvRef): string => {\n    const value = env[ref.env]\n    if (value === undefined || value === \"\") {\n      if (!missing.includes(ref.env)) missing.push(ref.env)\n      return \"\"\n    }\n    secrets.push(value)\n    return value\n  }\n  const token = profile.token ? read(profile.token) : undefined\n  const headers: Record<string, string> = {}\n  for (const [name, value] of Object.entries(profile.headers)) headers[name] = typeof value === \"string\" ? value : read(value)\n  if (missing.length > 0) throw new ProfileUnavailableError(profile.name, missing)\n  return { token, headers, secrets }\n}\n\n/** 표시용 프로필 (값 없음): 토큰 환경변수 이름 · 설정 여부 · 헤더 (비밀 = 환경변수 이름) */\nexport interface ProfileView {\n  name: string\n  description?: string\n  default: boolean\n  token?: { env: string; set: boolean }\n  headers: { name: string; value?: string; env?: string; set?: boolean }[]\n  clientInfo?: { name: string; version: string }\n  /** 필요한 환경변수가 모두 있다 */\n  available: boolean\n}\n\nexport function describeProfiles(set: ProfileSet, env: Record<string, string | undefined> = process.env): ProfileView[] {\n  const isSet = (name: string): boolean => env[name] !== undefined && env[name] !== \"\"\n  return set.profiles.map((p) => {\n    const headers = Object.entries(p.headers).map(([name, value]) =>\n      typeof value === \"string\" ? { name, value } : { name, env: value.env, set: isSet(value.env) },\n    )\n    const view: ProfileView = {\n      name: p.name,\n      default: p.name === set.default,\n      headers,\n      available: (p.token === undefined || isSet(p.token.env)) && headers.every((h) => h.set !== false),\n    }\n    if (p.description !== undefined) view.description = p.description\n    if (p.token) view.token = { env: p.token.env, set: isSet(p.token.env) }\n    if (p.clientInfo) view.clientInfo = p.clientInfo\n    return view\n  })\n}\n\n/** 문자열 안의 비밀 값을 [redacted] 로 (긴 값부터: 한 값이 다른 값의 일부일 때 긴 쪽이 남지 않게) */\nexport function redact(text: string, secrets: readonly string[]): string {\n  let out = text\n  for (const secret of [...secrets].sort((a, b) => b.length - a.length)) {\n    if (secret !== \"\") out = out.split(secret).join(REDACTED)\n  }\n  return out\n}\n\nfunction isObject(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value)\n}\n"]}

package/dist/inspect/scenario.d.ts

@@ -0,0 +1,126 @@
+import { type AgentClient, type AgentExpect, type AgentObservation } from "./agent.ts";
+import { type Failure } from "./compare.ts";
+import { type Answers, type CallOutcome, type CallRecord, type ErrorBody, type Inspector } from "./inspector.ts";
+import { type ProfileSet } from "./profiles.ts";
+/**
+ * 시나리오 (specs/inspector.md §4): 호출 순서 + 기대 결과를 적은 JSON 파일. 사람 · CLI · 웹 UI · 에이전트가 같은 파일을 쓴다.
+ * 코드 실행 없음 (값 비교만)
+ */
+/** <프로젝트>/inspect/scenarios */
+export declare const SCENARIOS_DIR = "scenarios";
+export interface Expect {
+    /** true = 성공해야 한다 · false = 오류여야 한다 */
+    ok?: boolean;
+    /** 성공 값의 일부 */
+    value?: unknown;
+    /** 오류 code, 또는 오류 본문의 일부 */
+    error?: string | Record<string, unknown>;
+    /** 이 호출의 감사 이벤트 목록 (trace ID 가 같은 것) 의 일부 비교 */
+    audit?: Record<string, unknown>[];
+}
+export interface CallStep {
+    name?: string;
+    as?: string;
+    call: string;
+    input?: Record<string, unknown>;
+    confirmed?: boolean;
+    answers?: Answers;
+    decline?: boolean;
+    expect?: Expect;
+    /** 변수 → 성공 값의 점 구분 경로 */
+    save?: Record<string, string>;
+}
+export interface CommandsStep {
+    name?: string;
+    as?: string;
+    commands: {
+        visible?: string[];
+        hidden?: string[];
+    };
+}
+/** 에이전트에게 지시하고 서버의 감사 이벤트를 비교 (§7) */
+export interface AgentStep {
+    name?: string;
+    /** 지시문 ({{변수}} 치환) */
+    agent: string;
+    /** 이 에이전트의 호출을 가려내는 조건 (이벤트의 일부) */
+    from?: Record<string, unknown>;
+    expect?: AgentExpect;
+    timeoutMs?: number;
+}
+export type ScenarioStep = CallStep | CommandsStep | AgentStep;
+/** agent 단계 결과의 as */
+export declare const AGENT_AS = "agent";
+export interface Scenario {
+    /** 읽은 파일 (절대 경로) */
+    file?: string;
+    name: string;
+    description?: string;
+    as?: string;
+    steps: ScenarioStep[];
+}
+export type { Failure };
+export interface StepResult {
+    /** 1부터 */
+    step: number;
+    name: string;
+    as: string;
+    pass: boolean;
+    durationMs: number;
+    /** call = 성공 값 또는 오류 본문 · commands = 보인 명령어 ID · agent = 관찰 (감사 이벤트 · 에이전트의 말) */
+    outcome: CallOutcome | {
+        ok: true;
+        commands: string[];
+    } | AgentObservation | undefined;
+    failures: Failure[];
+    /** call 단계의 호출 기록 ID (Inspector.history) */
+    record?: number;
+}
+export interface ScenarioResult {
+    name: string;
+    file?: string;
+    pass: boolean;
+    durationMs: number;
+    steps: StepResult[];
+}
+/** 시나리오 파일 형식 오류. issues = "<위치>: <문제>" */
+export declare class ScenarioFileError extends Error {
+    readonly file: string;
+    readonly issues: readonly string[];
+    constructor(file: string, issues: readonly string[]);
+}
+/** 경로 · 폴더 → 시나리오 파일 목록 (폴더 = 그 안의 *.json, 이름 순). 경로 없음 = <cwd>/inspect/scenarios */
+export declare function scenarioFiles(cwd: string, paths: readonly string[]): string[];
+/** 파일 읽기 + 검증. profiles 를 주면 없는 프로필 이름도 오류 */
+export declare function loadScenario(file: string, profiles?: ProfileSet): Scenario;
+/** 시나리오 내용 검증 (문제를 모두 모아 한 번에) */
+export declare function parseScenario(value: unknown, file: string, profiles?: ProfileSet): Scenario;
+export interface RunScenarioOptions {
+    /** 첫 실패에서 멈춤 */
+    bail?: boolean;
+    signal?: AbortSignal;
+    onStep?: (result: StepResult) => void;
+    /** 단계를 시작할 때 (오래 걸리는 agent 단계의 진행 표시) */
+    onStepStart?: (info: {
+        step: number;
+        name: string;
+        as: string;
+    }) => void;
+    /** agent 단계가 지시할 에이전트 (§7). 없음 = agent 단계 실패 (AGENT_UNAVAILABLE). close 는 만든 쪽이 한다 */
+    agent?: AgentClient;
+    /** agent 단계: idle 뒤 감사 이벤트를 기다리는 시간 (기본 500ms) */
+    agentSettleMs?: number;
+}
+/** 단계 순서대로 실행. 실패한 단계가 있어도 끝까지 (bail 제외) */
+export declare function runScenario(inspector: Inspector, scenario: Scenario, options?: RunScenarioOptions): Promise<ScenarioResult>;
+/** 목록 조회 실패 → 오류 본문 */
+export declare function listErrorBody(error: unknown): ErrorBody;
+/** 기대 결과 비교 (expect 없음 = 통과) */
+export declare function compare(expect: Expect | undefined, outcome: CallOutcome, failures: Failure[]): void;
+/** 호출 기록 → 시나리오 단계 (관찰한 결과를 기대 결과로). 오류 = code · reason 만 */
+export declare function stepFromRecord(record: CallRecord, options?: {
+    answers?: Answers;
+    decline?: boolean;
+}): CallStep;
+/** 시나리오 파일 끝에 단계를 덧붙인다 (파일이 없으면 만든다). 반환 = 단계 수 */
+export declare function appendStep(file: string, step: ScenarioStep): number;