@obov/mext 0.5.0 → 0.7.1

package/dist/inspect/audit.js

@@ -0,0 +1,133 @@
+import { DEV_AUDIT_PATH } from "../cli/dev-audit.js";
+import { readDevLock } from "../cli/dev-lock.js";
+export function auditChannel() {
+    const listeners = new Set();
+    return {
+        push(event) {
+            for (const listener of listeners)
+                listener(event);
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => void listeners.delete(listener);
+        },
+    };
+}
+/**
+ * mext dev 의 감사 tap endpoint 를 읽는 출처. 구독자가 있는 동안 연결 하나를 유지하고, 끊기면 ?after 로 이어 받는다.
+ * 토큰은 Authorization 헤더로만 보낸다 (출력하지 않는다)
+ */
+export function devAuditSource(options) {
+    const doFetch = options.fetch ?? ((input, init) => fetch(input, init));
+    const credentials = () => (typeof options.credentials === "function" ? options.credentials() : options.credentials);
+    const listeners = new Set();
+    let controller;
+    let last = 0;
+    let lastToken;
+    const pump = async (signal) => {
+        let wait = options.retryMs ?? 500;
+        while (!signal.aborted) {
+            try {
+                const current = credentials();
+                if (!current)
+                    throw new Error("mext dev is not running");
+                // 새 mext dev 실행 (토큰이 바뀜) = seq 가 1부터 다시
+                if (current.token !== lastToken)
+                    last = 0;
+                lastToken = current.token;
+                const url = new URL(DEV_AUDIT_PATH, current.url);
+                if (last > 0)
+                    url.searchParams.set("after", String(last));
+                const response = await doFetch(url, { headers: { Authorization: `Bearer ${current.token}` }, signal });
+                if (!response.ok || !response.body) {
+                    await response.body?.cancel();
+                    throw new Error(`HTTP ${response.status}`);
+                }
+                wait = options.retryMs ?? 500;
+                const decoder = new TextDecoder();
+                let buffer = "";
+                for await (const chunk of response.body) {
+                    buffer += decoder.decode(chunk, { stream: true });
+                    let i;
+                    while ((i = buffer.indexOf("\n")) >= 0) {
+                        const text = buffer.slice(0, i);
+                        buffer = buffer.slice(i + 1);
+                        if (text === "")
+                            continue;
+                        const line = JSON.parse(text);
+                        if (typeof line.seq === "number")
+                            last = line.seq;
+                        for (const listener of listeners)
+                            listener(line.event);
+                    }
+                }
+            }
+            catch {
+                // 연결 실패 · 끊김 = 잠시 뒤 다시
+            }
+            if (signal.aborted)
+                return;
+            await new Promise((resolve) => {
+                const timer = setTimeout(resolve, wait);
+                signal.addEventListener("abort", () => (clearTimeout(timer), resolve()), { once: true });
+            });
+            wait = Math.min(wait * 2, 5_000);
+        }
+    };
+    return {
+        subscribe(listener) {
+            listeners.add(listener);
+            if (!controller) {
+                controller = new AbortController();
+                void pump(controller.signal);
+            }
+            return () => {
+                listeners.delete(listener);
+                if (listeners.size === 0) {
+                    controller?.abort();
+                    controller = undefined;
+                }
+            };
+        },
+    };
+}
+/**
+ * 대상 서버의 감사 출처. 대상이 이 프로젝트의 mext dev (대상 URL = .mext/dev/lock 의 url) 일 때만 자동 연결.
+ * 그 외 = 사용 불가 + 이유 (프로그램 API 로 출처를 직접 연결할 수 있다)
+ */
+export function resolveAudit(target, cwd) {
+    const lock = readDevLock(cwd);
+    if (!lock?.url || !sameEndpoint(lock.url, target.url)) {
+        return {
+            available: false,
+            reason: "Audit events are only streamed from the mext dev server of this project. For other servers (remote, mext start), " +
+                'connect an audit source in code: createInspector({ audit }) from "@obov/mext/inspect".',
+        };
+    }
+    if (lock.auditToken === undefined) {
+        return { available: false, reason: "The running mext dev does not expose audit events (started by an older mext). Restart mext dev." };
+    }
+    const url = lock.url;
+    return {
+        available: true,
+        source: devAuditSource({
+            credentials: () => {
+                const now = readDevLock(cwd);
+                return now?.url && now.auditToken !== undefined && sameEndpoint(now.url, url) ? { url: now.url, token: now.auditToken } : undefined;
+            },
+        }),
+    };
+}
+const LOOPBACK = new Set(["localhost", "127.0.0.1", "[::1]"]);
+function sameEndpoint(a, b) {
+    try {
+        const x = new URL(a);
+        const y = new URL(b);
+        const host = (u) => (LOOPBACK.has(u.hostname) ? "loopback" : u.hostname);
+        return x.protocol === y.protocol && host(x) === host(y) && x.port === y.port && x.pathname === y.pathname;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=audit.js.map

package/dist/inspect/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../src/inspect/audit.ts"],"names":[],"mappings":"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","sourcesContent":["import type { AuditEvent } from \"../audit.ts\"\nimport { DEV_AUDIT_PATH, type DevAuditLine } from \"../cli/dev-audit.ts\"\nimport { readDevLock } from \"../cli/dev-lock.ts\"\n\n/**\n * 감사 출처 (specs/inspector.md §6): 서버의 감사 이벤트 (mext.md §11.1) 를 Inspector 로 잇는다.\n * mext dev = 감사 tap 의 endpoint (mext.md §10). 그 외 = 호출 코드가 출처를 만들어 연결한다\n */\n\nexport interface AuditSource {\n  /** 이벤트마다 listener 호출. 반환 = 구독 해제 */\n  subscribe(listener: (event: AuditEvent) => void): () => void\n}\n\n/** 같은 프로세스의 서버와 잇는 출처: mext.config.ts · startMcpHttpServer 의 audit.sink 에 push 를 넘긴다 */\nexport interface AuditChannel extends AuditSource {\n  push(event: AuditEvent): void\n}\n\nexport function auditChannel(): AuditChannel {\n  const listeners = new Set<(event: AuditEvent) => void>()\n  return {\n    push(event) {\n      for (const listener of listeners) listener(event)\n    },\n    subscribe(listener) {\n      listeners.add(listener)\n      return () => void listeners.delete(listener)\n    },\n  }\n}\n\nexport interface DevAuditCredentials {\n  /** mext dev 의 MCP 엔드포인트 (lock 의 url) */\n  url: string\n  /** lock 의 auditToken */\n  token: string\n}\n\nexport interface DevAuditSourceOptions {\n  /** 연결할 때마다 읽는다 (mext dev 를 다시 시작하면 토큰이 바뀐다). undefined = 실행 중인 dev 없음 → 잠시 뒤 다시 */\n  credentials: DevAuditCredentials | (() => DevAuditCredentials | undefined)\n  fetch?: typeof fetch\n  /** 다시 연결하기 전 대기 (기본 500ms, 실패가 이어지면 5초까지 늘어난다) */\n  retryMs?: number\n}\n\n/**\n * mext dev 의 감사 tap endpoint 를 읽는 출처. 구독자가 있는 동안 연결 하나를 유지하고, 끊기면 ?after 로 이어 받는다.\n * 토큰은 Authorization 헤더로만 보낸다 (출력하지 않는다)\n */\nexport function devAuditSource(options: DevAuditSourceOptions): AuditSource {\n  const doFetch: typeof fetch = options.fetch ?? ((input, init) => fetch(input, init))\n  const credentials = (): DevAuditCredentials | undefined => (typeof options.credentials === \"function\" ? options.credentials() : options.credentials)\n  const listeners = new Set<(event: AuditEvent) => void>()\n  let controller: AbortController | undefined\n  let last = 0\n  let lastToken: string | undefined\n\n  const pump = async (signal: AbortSignal): Promise<void> => {\n    let wait = options.retryMs ?? 500\n    while (!signal.aborted) {\n      try {\n        const current = credentials()\n        if (!current) throw new Error(\"mext dev is not running\")\n        // 새 mext dev 실행 (토큰이 바뀜) = seq 가 1부터 다시\n        if (current.token !== lastToken) last = 0\n        lastToken = current.token\n        const url = new URL(DEV_AUDIT_PATH, current.url)\n        if (last > 0) url.searchParams.set(\"after\", String(last))\n        const response = await doFetch(url, { headers: { Authorization: `Bearer ${current.token}` }, signal })\n        if (!response.ok || !response.body) {\n          await response.body?.cancel()\n          throw new Error(`HTTP ${response.status}`)\n        }\n        wait = options.retryMs ?? 500\n        const decoder = new TextDecoder()\n        let buffer = \"\"\n        for await (const chunk of response.body as unknown as AsyncIterable<Uint8Array>) {\n          buffer += decoder.decode(chunk, { stream: true })\n          let i: number\n          while ((i = buffer.indexOf(\"\\n\")) >= 0) {\n            const text = buffer.slice(0, i)\n            buffer = buffer.slice(i + 1)\n            if (text === \"\") continue\n            const line = JSON.parse(text) as DevAuditLine\n            if (typeof line.seq === \"number\") last = line.seq\n            for (const listener of listeners) listener(line.event)\n          }\n        }\n      } catch {\n        // 연결 실패 · 끊김 = 잠시 뒤 다시\n      }\n      if (signal.aborted) return\n      await new Promise<void>((resolve) => {\n        const timer = setTimeout(resolve, wait)\n        signal.addEventListener(\"abort\", () => (clearTimeout(timer), resolve()), { once: true })\n      })\n      wait = Math.min(wait * 2, 5_000)\n    }\n  }\n\n  return {\n    subscribe(listener) {\n      listeners.add(listener)\n      if (!controller) {\n        controller = new AbortController()\n        void pump(controller.signal)\n      }\n      return () => {\n        listeners.delete(listener)\n        if (listeners.size === 0) {\n          controller?.abort()\n          controller = undefined\n        }\n      }\n    },\n  }\n}\n\nexport type AuditAvailability = { available: true; source: AuditSource } | { available: false; reason: string }\n\n/**\n * 대상 서버의 감사 출처. 대상이 이 프로젝트의 mext dev (대상 URL = .mext/dev/lock 의 url) 일 때만 자동 연결.\n * 그 외 = 사용 불가 + 이유 (프로그램 API 로 출처를 직접 연결할 수 있다)\n */\nexport function resolveAudit(target: { url: string }, cwd: string): AuditAvailability {\n  const lock = readDevLock(cwd)\n  if (!lock?.url || !sameEndpoint(lock.url, target.url)) {\n    return {\n      available: false,\n      reason:\n        \"Audit events are only streamed from the mext dev server of this project. For other servers (remote, mext start), \" +\n        'connect an audit source in code: createInspector({ audit }) from \"@obov/mext/inspect\".',\n    }\n  }\n  if (lock.auditToken === undefined) {\n    return { available: false, reason: \"The running mext dev does not expose audit events (started by an older mext). Restart mext dev.\" }\n  }\n  const url = lock.url\n  return {\n    available: true,\n    source: devAuditSource({\n      credentials: () => {\n        const now = readDevLock(cwd)\n        return now?.url && now.auditToken !== undefined && sameEndpoint(now.url, url) ? { url: now.url, token: now.auditToken } : undefined\n      },\n    }),\n  }\n}\n\nconst LOOPBACK = new Set([\"localhost\", \"127.0.0.1\", \"[::1]\"])\n\nfunction sameEndpoint(a: string, b: string): boolean {\n  try {\n    const x = new URL(a)\n    const y = new URL(b)\n    const host = (u: URL): string => (LOOPBACK.has(u.hostname) ? \"loopback\" : u.hostname)\n    return x.protocol === y.protocol && host(x) === host(y) && x.port === y.port && x.pathname === y.pathname\n  } catch {\n    return false\n  }\n}\n"]}

package/dist/inspect/compare.d.ts

@@ -0,0 +1,12 @@
+/** 기대와 실제의 일부 비교 (specs/inspector.md §4 expect). 시나리오 · 에이전트 단계가 같이 쓴다 */
+export interface Failure {
+    /** 다른 곳 (ok · value.status · error.code · commands.hidden · input · save.<변수> · audit.<n> · none.<n> · agent) */
+    path: string;
+    expected: unknown;
+    actual: unknown;
+}
+/** 일부 비교: 객체 = 적은 키만 (재귀) · 배열 = 길이와 각 요소 · 그 외 = 같은 값 */
+export declare function partial(expected: unknown, actual: unknown, path: string, failures: Failure[]): void;
+/** 일부 비교가 통과하는가 */
+export declare function matches(expected: unknown, actual: unknown): boolean;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/inspect/compare.js

@@ -0,0 +1,31 @@
+/** 기대와 실제의 일부 비교 (specs/inspector.md §4 expect). 시나리오 · 에이전트 단계가 같이 쓴다 */
+/** 일부 비교: 객체 = 적은 키만 (재귀) · 배열 = 길이와 각 요소 · 그 외 = 같은 값 */
+export function partial(expected, actual, path, failures) {
+    if (Array.isArray(expected)) {
+        if (!Array.isArray(actual))
+            return void failures.push({ path, expected, actual });
+        if (actual.length !== expected.length)
+            return void failures.push({ path: `${path}.length`, expected: expected.length, actual: actual.length });
+        expected.forEach((item, i) => partial(item, actual[i], `${path}.${i}`, failures));
+        return;
+    }
+    if (isRecord(expected)) {
+        if (!isRecord(actual))
+            return void failures.push({ path, expected, actual });
+        for (const [key, value] of Object.entries(expected))
+            partial(value, actual[key], `${path}.${key}`, failures);
+        return;
+    }
+    if (!Object.is(expected, actual))
+        failures.push({ path, expected, actual });
+}
+/** 일부 비교가 통과하는가 */
+export function matches(expected, actual) {
+    const failures = [];
+    partial(expected, actual, "", failures);
+    return failures.length === 0;
+}
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=compare.js.map

package/dist/inspect/compare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.js","sourceRoot":"","sources":["../../src/inspect/compare.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAS1E,0DAA0D;AAC1D,MAAM,UAAU,OAAO,CAAC,QAAiB,EAAE,MAAe,EAAE,IAAY,EAAE,QAAmB;IAC3F,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YAAE,OAAO,KAAK,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAA;QACjF,IAAI,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM;YAAE,OAAO,KAAK,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,GAAG,IAAI,SAAS,EAAE,QAAQ,EAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAA;QAC9I,QAAQ,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,IAAI,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAA;QACjF,OAAM;IACR,CAAC;IACD,IAAI,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACvB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;YAAE,OAAO,KAAK,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAA;QAC5E,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC;YAAE,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI,IAAI,GAAG,EAAE,EAAE,QAAQ,CAAC,CAAA;QAC5G,OAAM;IACR,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAA;AAC7E,CAAC;AAED,mBAAmB;AACnB,MAAM,UAAU,OAAO,CAAC,QAAiB,EAAE,MAAe;IACxD,MAAM,QAAQ,GAAc,EAAE,CAAA;IAC9B,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,CAAC,CAAA;IACvC,OAAO,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAA;AAC9B,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;AAC7E,CAAC","sourcesContent":["/** 기대와 실제의 일부 비교 (specs/inspector.md §4 expect). 시나리오 · 에이전트 단계가 같이 쓴다 */\n\nexport interface Failure {\n  /** 다른 곳 (ok · value.status · error.code · commands.hidden · input · save.<변수> · audit.<n> · none.<n> · agent) */\n  path: string\n  expected: unknown\n  actual: unknown\n}\n\n/** 일부 비교: 객체 = 적은 키만 (재귀) · 배열 = 길이와 각 요소 · 그 외 = 같은 값 */\nexport function partial(expected: unknown, actual: unknown, path: string, failures: Failure[]): void {\n  if (Array.isArray(expected)) {\n    if (!Array.isArray(actual)) return void failures.push({ path, expected, actual })\n    if (actual.length !== expected.length) return void failures.push({ path: `${path}.length`, expected: expected.length, actual: actual.length })\n    expected.forEach((item, i) => partial(item, actual[i], `${path}.${i}`, failures))\n    return\n  }\n  if (isRecord(expected)) {\n    if (!isRecord(actual)) return void failures.push({ path, expected, actual })\n    for (const [key, value] of Object.entries(expected)) partial(value, actual[key], `${path}.${key}`, failures)\n    return\n  }\n  if (!Object.is(expected, actual)) failures.push({ path, expected, actual })\n}\n\n/** 일부 비교가 통과하는가 */\nexport function matches(expected: unknown, actual: unknown): boolean {\n  const failures: Failure[] = []\n  partial(expected, actual, \"\", failures)\n  return failures.length === 0\n}\n\nexport function isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value)\n}\n"]}

package/dist/inspect/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @obov/mext/inspect — inspector 의 프로그램 API (specs/inspector.md). Node.js · Bun 전용 (파일 · 환경변수를 읽는다).
+ * mext inspect CLI 가 쓰는 것과 같은 객체: 호출자 프로필 · Inspector (프로필별 호출 · 호출 기록) · 시나리오.
+ * @obov/mext (.) 와 mext start · 고객 CLI 는 이 entry 를 import 하지 않는다
+ */
+export { AGENT_SETTLE_MS, AGENT_TIMEOUT_MS, checkAudit, connectAgent, instructAgent, isAgentClient, summarizeAudit } from "./agent.ts";
+export type { AgentClient, AgentEvent, AgentExpect, AgentMessage, AgentObservation, AgentPlugin, AgentPluginContext, AgentToolCall, InstructOptions, } from "./agent.ts";
+export { auditChannel, devAuditSource, resolveAudit } from "./audit.ts";
+export type { AuditAvailability, AuditChannel, AuditSource, DevAuditCredentials, DevAuditSourceOptions } from "./audit.ts";
+export { startUiServer, UI_DEFAULT_PORT, UI_TOKEN_HEADER } from "./ui-server.ts";
+export type { UiServer, UiServerOptions } from "./ui-server.ts";
+export { createInspector, InspectUsageError, outcomeOf, redactValue, resolveTarget } from "./inspector.ts";
+export type { Answers, CallOutcome, CallRecord, ErrorBody, Exchange, InputRecord, InspectCallOptions, Inspector, InspectorEvent, InspectorOptions, InspectTarget, } from "./inspector.ts";
+export { DEFAULT_PROFILE, DEFAULT_TOKEN_ENV, describeProfiles, findProfile, INSPECT_DIR, loadProfiles, parseProfiles, ProfileFileError, PROFILES_FILE, profilesPath, ProfileUnavailableError, redact, REDACTED, resolveProfile, } from "./profiles.ts";
+export type { EnvRef, Profile, ProfileSet, ProfileView, ResolvedProfile } from "./profiles.ts";
+export { appendStep, compare, loadScenario, parseScenario, runScenario, ScenarioFileError, scenarioFiles, SCENARIOS_DIR, stepFromRecord, } from "./scenario.ts";
+export type { AgentStep, CallStep, CommandsStep, Expect, Failure, RunScenarioOptions, Scenario, ScenarioResult, ScenarioStep, StepResult, } from "./scenario.ts";

package/dist/inspect/index.js

@@ -0,0 +1,12 @@
+/**
+ * @obov/mext/inspect — inspector 의 프로그램 API (specs/inspector.md). Node.js · Bun 전용 (파일 · 환경변수를 읽는다).
+ * mext inspect CLI 가 쓰는 것과 같은 객체: 호출자 프로필 · Inspector (프로필별 호출 · 호출 기록) · 시나리오.
+ * @obov/mext (.) 와 mext start · 고객 CLI 는 이 entry 를 import 하지 않는다
+ */
+export { AGENT_SETTLE_MS, AGENT_TIMEOUT_MS, checkAudit, connectAgent, instructAgent, isAgentClient, summarizeAudit } from "./agent.js";
+export { auditChannel, devAuditSource, resolveAudit } from "./audit.js";
+export { startUiServer, UI_DEFAULT_PORT, UI_TOKEN_HEADER } from "./ui-server.js";
+export { createInspector, InspectUsageError, outcomeOf, redactValue, resolveTarget } from "./inspector.js";
+export { DEFAULT_PROFILE, DEFAULT_TOKEN_ENV, describeProfiles, findProfile, INSPECT_DIR, loadProfiles, parseProfiles, ProfileFileError, PROFILES_FILE, profilesPath, ProfileUnavailableError, redact, REDACTED, resolveProfile, } from "./profiles.js";
+export { appendStep, compare, loadScenario, parseScenario, runScenario, ScenarioFileError, scenarioFiles, SCENARIOS_DIR, stepFromRecord, } from "./scenario.js";
+//# sourceMappingURL=index.js.map

package/dist/inspect/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/inspect/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAYtI,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAEvE,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAEhF,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,SAAS,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAc1G,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,YAAY,EACZ,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,uBAAuB,EACvB,MAAM,EACN,QAAQ,EACR,cAAc,GACf,MAAM,eAAe,CAAA;AAEtB,OAAO,EACL,UAAU,EACV,OAAO,EACP,YAAY,EACZ,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,aAAa,EACb,cAAc,GACf,MAAM,eAAe,CAAA","sourcesContent":["/**\n * @obov/mext/inspect — inspector 의 프로그램 API (specs/inspector.md). Node.js · Bun 전용 (파일 · 환경변수를 읽는다).\n * mext inspect CLI 가 쓰는 것과 같은 객체: 호출자 프로필 · Inspector (프로필별 호출 · 호출 기록) · 시나리오.\n * @obov/mext (.) 와 mext start · 고객 CLI 는 이 entry 를 import 하지 않는다\n */\nexport { AGENT_SETTLE_MS, AGENT_TIMEOUT_MS, checkAudit, connectAgent, instructAgent, isAgentClient, summarizeAudit } from \"./agent.ts\"\nexport type {\n  AgentClient,\n  AgentEvent,\n  AgentExpect,\n  AgentMessage,\n  AgentObservation,\n  AgentPlugin,\n  AgentPluginContext,\n  AgentToolCall,\n  InstructOptions,\n} from \"./agent.ts\"\nexport { auditChannel, devAuditSource, resolveAudit } from \"./audit.ts\"\nexport type { AuditAvailability, AuditChannel, AuditSource, DevAuditCredentials, DevAuditSourceOptions } from \"./audit.ts\"\nexport { startUiServer, UI_DEFAULT_PORT, UI_TOKEN_HEADER } from \"./ui-server.ts\"\nexport type { UiServer, UiServerOptions } from \"./ui-server.ts\"\nexport { createInspector, InspectUsageError, outcomeOf, redactValue, resolveTarget } from \"./inspector.ts\"\nexport type {\n  Answers,\n  CallOutcome,\n  CallRecord,\n  ErrorBody,\n  Exchange,\n  InputRecord,\n  InspectCallOptions,\n  Inspector,\n  InspectorEvent,\n  InspectorOptions,\n  InspectTarget,\n} from \"./inspector.ts\"\nexport {\n  DEFAULT_PROFILE,\n  DEFAULT_TOKEN_ENV,\n  describeProfiles,\n  findProfile,\n  INSPECT_DIR,\n  loadProfiles,\n  parseProfiles,\n  ProfileFileError,\n  PROFILES_FILE,\n  profilesPath,\n  ProfileUnavailableError,\n  redact,\n  REDACTED,\n  resolveProfile,\n} from \"./profiles.ts\"\nexport type { EnvRef, Profile, ProfileSet, ProfileView, ResolvedProfile } from \"./profiles.ts\"\nexport {\n  appendStep,\n  compare,\n  loadScenario,\n  parseScenario,\n  runScenario,\n  ScenarioFileError,\n  scenarioFiles,\n  SCENARIOS_DIR,\n  stepFromRecord,\n} from \"./scenario.ts\"\nexport type {\n  AgentStep,\n  CallStep,\n  CommandsStep,\n  Expect,\n  Failure,\n  RunScenarioOptions,\n  Scenario,\n  ScenarioResult,\n  ScenarioStep,\n  StepResult,\n} from \"./scenario.ts\"\n"]}

package/dist/inspect/inspector.d.ts

@@ -0,0 +1,168 @@
+import type { AuditEvent } from "../audit.ts";
+import { CallError } from "../client/typed.ts";
+import type { CommandInfo, CommandList, InputAnswer, InputRequestInfo, ProgressUpdate, ServerInfo, TaskStatus } from "../client/types.ts";
+import type { AuditSource } from "./audit.ts";
+import { type Profile, type ProfileSet, type ProfileView } from "./profiles.ts";
+/**
+ * Inspector (specs/inspector.md): 호출자 프로필별 타입 client · 호출 기록 (원시 요청 · 응답, 비밀 값 가림).
+ * CLI · 웹 UI · 시나리오 실행이 같은 객체를 쓴다. 호출 코드는 타입 client 하나 (별도 MCP 클라이언트 구현 없음)
+ */
+export interface InspectTarget {
+    url: string;
+    /** flag = --url · env = MEXT_URL · dev = 이 프로젝트의 mext dev (.mext/dev/lock) */
+    source: "flag" | "env" | "dev";
+}
+/** 대상 서버를 정할 수 없다 · URL 형식 오류 · 없는 프로필 (CLI = exit 2) */
+export declare class InspectUsageError extends Error {
+    constructor(message: string);
+}
+/** --url > MEXT_URL > 실행 중인 mext dev. 셋 다 없음 = InspectUsageError */
+export declare function resolveTarget(options: {
+    url?: string;
+    env?: Record<string, string | undefined>;
+    cwd: string;
+}): InspectTarget;
+/** HTTP 왕복 하나 (원시 요청 · 응답). 비밀 값은 [redacted] */
+export interface Exchange {
+    /** JSON-RPC method (tools/call · tools/list · server/discover · tasks/get …) */
+    rpc?: string;
+    request: {
+        method: string;
+        url: string;
+        headers: Record<string, string>;
+        body: unknown;
+    };
+    /** body = JSON 응답 · SSE 메시지 배열 (text/event-stream) · 그 외 텍스트 */
+    response?: {
+        status: number;
+        headers: Record<string, string>;
+        body: unknown;
+    };
+    /** 응답을 받지 못함 (연결 실패 · 취소) */
+    error?: string;
+    durationMs: number;
+}
+/** 오류 본문 { code, message, ...details } */
+export type ErrorBody = Record<string, unknown> & {
+    code: string;
+    message: string;
+};
+export type CallOutcome = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    error: ErrorBody;
+};
+export interface InputRecord {
+    kind: InputRequestInfo["kind"];
+    message: string;
+    /** 보낸 답 (true · false · { action, content }). 답 없음 = undefined */
+    answer?: InputAnswer;
+}
+/** 호출 하나의 기록 */
+export interface CallRecord {
+    /** 이 Inspector 안에서 1부터 */
+    id: number;
+    /** 시작 시각 (ISO) */
+    at: string;
+    profile: string;
+    command: string;
+    input: Record<string, unknown>;
+    confirmed: boolean;
+    ok: boolean;
+    /** ok = 반환값 */
+    value?: unknown;
+    /** ok 아님 = 오류 본문 */
+    error?: ErrorBody;
+    durationMs: number;
+    progress: ProgressUpdate[];
+    inputs: InputRecord[];
+    /** task 로 실행됐으면 마지막 상태 */
+    task?: TaskStatus;
+    /**
+     * 이 호출의 tools/call 요청에 실은 trace ID (params._meta.traceparent, W3C trace context).
+     * 서버의 감사 이벤트 traceId 와 같다 = 호출과 이벤트를 잇는 값
+     */
+    traceId: string;
+    exchanges: Exchange[];
+}
+/** 입력 요청의 답 (종류별). 적지 않은 종류 = INPUT_UNAVAILABLE */
+export interface Answers {
+    confirm?: boolean;
+    /** 값 객체 = 수락 · false = 거절 */
+    form?: Record<string, unknown> | false;
+    url?: boolean;
+}
+export interface InspectCallOptions {
+    /** 프로필 이름. 생략 = 프로필 파일의 default */
+    profile?: string;
+    /** 사람이 확인했다는 표시 (client.md §2.2): 확인 표시 전송 + confirm 입력 요청 승인 */
+    confirmed?: boolean;
+    answers?: Answers;
+    /** 입력 · 확인 요청을 모두 거절 */
+    decline?: boolean;
+    /** 입력 요청을 직접 처리 (웹 UI). answers · decline 보다 먼저 */
+    onInput?: (request: InputRequestInfo) => InputAnswer | Promise<InputAnswer>;
+    onProgress?: (update: ProgressUpdate) => void;
+    onTask?: (task: TaskStatus) => void;
+    signal?: AbortSignal;
+}
+export interface InspectorOptions {
+    /** 대상 서버의 MCP 엔드포인트 */
+    url: string;
+    profiles: ProfileSet;
+    /** 프로필 값을 읽을 환경변수 (기본 process.env) */
+    env?: Record<string, string | undefined>;
+    fetch?: typeof fetch;
+    /** 보관할 호출 기록 수 (기본 200. 넘으면 오래된 것부터 버린다) */
+    historyLimit?: number;
+    /** 호출 기록이 추가될 때 */
+    onRecord?: (record: CallRecord) => void;
+    /** 감사 출처 (§6). 없음 = 감사 이벤트 없음 */
+    audit?: AuditSource;
+    /** 보관할 감사 이벤트 수 (기본 500) */
+    auditLimit?: number;
+}
+/** Inspector 가 알리는 일: 호출 기록 추가 · 감사 이벤트 수신 */
+export type InspectorEvent = {
+    type: "record";
+    record: CallRecord;
+} | {
+    type: "audit";
+    event: AuditEvent;
+};
+export interface Inspector {
+    readonly url: string;
+    readonly profileSet: ProfileSet;
+    /** 표시용 프로필 목록 (값 없음) */
+    profiles(): ProfileView[];
+    /** 이름 확인 (생략 = default). 없는 이름 = InspectUsageError */
+    profile(name?: string): Profile;
+    /** 그 프로필에게 보이는 목록 (매번 서버에서 다시 읽는다). 실패 = CallError · ProfileUnavailableError */
+    commands(profile?: string): Promise<CommandList>;
+    describe(id: string, profile?: string): Promise<CommandInfo>;
+    server(profile?: string): Promise<ServerInfo>;
+    /** 호출. 호출 오류 · 프로필 값 없음 · 취소도 던지지 않고 기록 (ok: false) 으로 돌려준다 */
+    call(id: string, input?: Record<string, unknown>, options?: InspectCallOptions): Promise<CallRecord>;
+    /** 오래된 것부터 */
+    history(): CallRecord[];
+    clearHistory(): void;
+    /** 감사 출처가 연결돼 있는지 */
+    readonly auditConnected: boolean;
+    /** 받은 감사 이벤트 (오래된 것부터, 프로필의 비밀 값은 [redacted]) */
+    auditEvents(): AuditEvent[];
+    /** 값 안의 문자열에서 지금 읽을 수 있는 모든 프로필의 비밀 값을 가린다 (기록 · 이벤트와 같은 규칙) */
+    redact<T>(value: T): T;
+    /** 호출 기록 · 감사 이벤트 구독. 반환 = 해제 */
+    subscribe(listener: (event: InspectorEvent) => void): () => void;
+    /** 감사 출처 연결 해제 */
+    close(): void;
+}
+export declare function createInspector(options: InspectorOptions): Inspector;
+/** 결과 요약 (기록 → 성공 값 또는 오류 본문) */
+export declare function outcomeOf(record: CallRecord): CallOutcome;
+/** 오류 본문. code · message 를 앞에 (출력 · 기록에서 먼저 보이게) */
+export declare function orderedBody(error: CallError): ErrorBody;
+/** 값 안의 문자열에서 비밀 값을 가린다 (객체 · 배열 재귀) */
+export declare function redactValue(value: unknown, secrets: readonly string[]): unknown;