@obov/mext 0.5.0 → 0.7.1

package/dist/instrumentation.d.ts

@@ -61,6 +61,11 @@ interface OtelTracer {
     }, context: unknown, fn: (span: OtelSpan) => T): T;
 }
 interface OtelSpan {
+    /** 없는 구현 (테스트 대역) 도 허용 */
+    spanContext?(): {
+        traceId?: unknown;
+        spanId?: unknown;
+    } | undefined;
     setAttribute(key: string, value: string): unknown;
     setStatus(status: {
         code: number;
@@ -79,6 +84,11 @@ export declare function loadProjectInstrumentation(cwd?: string, options?: LoadI
  * source 없음 = hooks 없이 span 만. 빌드 산출물 (.mext/server/instrumentation.js) 도 같은 함수.
  */
 export declare function loadInstrumentation(source?: string | URL | InstrumentationModule, options?: LoadInstrumentationOptions): Promise<Instrumentation>;
+/** span 식별자 (감사 이벤트의 traceId · spanId, §11.1). 유효하지 않은 (전부 0) 값은 넘기지 않는다 */
+export interface TraceIds {
+    traceId: string;
+    spanId?: string;
+}
 export interface ObserveOptions {
     instrumentation?: Instrumentation;
     transport?: Transport;
@@ -91,13 +101,14 @@ export interface ObserveOptions {
  * 속성 = mext.command.id · mext.transport · mext.principal.kind. 인자 · 결과 · 토큰은 기록하지 않는다.
  * 실패: status ERROR + mext.error.code. 핸들러 예외만 recordException (MextError · CommandError 메시지는 입력 일부를 담을 수 있어 제외).
  * 취소 (signal abort · MRTR 대기) = status 없음.
+ * fn 인자 = span 의 traceId · spanId (span 없음 = undefined)
  */
-export declare function observeCommand<T>(command: string, options: ObserveOptions, signal: () => AbortSignal | undefined, fn: () => Promise<T>): Promise<T>;
+export declare function observeCommand<T>(command: string, options: ObserveOptions, signal: () => AbortSignal | undefined, fn: (trace?: TraceIds) => Promise<T>): Promise<T>;
 /**
  * observeCommand 의 일반형 (자원 = `mext.resource <uri 템플릿>`, §12.3).
  * attributes 에 mext.transport · mext.principal.kind 를 더한다. 실패 · 취소 처리는 observeCommand 와 같다
  */
-export declare function observeSpan<T>(name: string, attributes: Record<string, string>, options: ObserveOptions, signal: () => AbortSignal | undefined, fn: () => Promise<T>): Promise<T>;
+export declare function observeSpan<T>(name: string, attributes: Record<string, string>, options: ObserveOptions, signal: () => AbortSignal | undefined, fn: (trace?: TraceIds) => Promise<T>): Promise<T>;
 /**
  * 핸들러 예외 → onCommandError (await). MextError · CommandError · 취소 · MRTR 대기는 보고하지 않는다.
  * onCommandError 자체의 예외 = onerror (기본 stderr), 호출자에게 전파하지 않는다.

package/dist/instrumentation.js

@@ -97,6 +97,7 @@ const TRACER_NAME = "@obov/mext";
  * 속성 = mext.command.id · mext.transport · mext.principal.kind. 인자 · 결과 · 토큰은 기록하지 않는다.
  * 실패: status ERROR + mext.error.code. 핸들러 예외만 recordException (MextError · CommandError 메시지는 입력 일부를 담을 수 있어 제외).
  * 취소 (signal abort · MRTR 대기) = status 없음.
+ * fn 인자 = span 의 traceId · spanId (span 없음 = undefined)
  */
 export function observeCommand(command, options, signal, fn) {
     return observeSpan(`mext.command ${command}`, { "mext.command.id": command }, options, signal, fn);
@@ -118,7 +119,7 @@ export function observeSpan(name, attributes, options, signal, fn) {
     const tracer = otel.trace.getTracer(TRACER_NAME);
     return tracer.startActiveSpan(name, { attributes: all }, parent, async (span) => {
         try {
-            return await fn();
+            return await fn(traceIds(span));
         }
         catch (error) {
             if (!signal()?.aborted) {
@@ -139,6 +140,15 @@ export function observeSpan(name, attributes, options, signal, fn) {
         }
     });
 }
+/** span 의 traceId · spanId. SDK 미등록 (non-recording span, 전부 0) · 형식 오류 = undefined */
+function traceIds(span) {
+    const context = span.spanContext?.();
+    const traceId = context?.traceId;
+    if (typeof traceId !== "string" || traceId === "" || /^0+$/.test(traceId))
+        return undefined;
+    const spanId = context?.spanId;
+    return typeof spanId === "string" && spanId !== "" && !/^0+$/.test(spanId) ? { traceId, spanId } : { traceId };
+}
 /**
  * 핸들러 예외 → onCommandError (await). MextError · CommandError · 취소 · MRTR 대기는 보고하지 않는다.
  * onCommandError 자체의 예외 = onerror (기본 stderr), 호출자에게 전파하지 않는다.

package/dist/instrumentation.js.map

@@ -1 +1 @@
-{"version":3,"file":"instrumentation.js","sourceRoot":"","sources":["../src/instrumentation.ts"],"names":[],"mappings":"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","sourcesContent":["import { existsSync } from \"node:fs\"\nimport { isAbsolute, join, resolve } from \"node:path\"\nimport { pathToFileURL } from \"node:url\"\nimport { isDeclaredError } from \"./errors.ts\"\nimport type { Principal } from \"./principal.ts\"\n\n/**\n * instrumentation.ts (프로젝트 루트, 선택) · OpenTelemetry span (§11).\n * register() = 프로세스당 1회, 첫 명령어 실행 전. onCommandError = 핸들러 예외 보고.\n * span = @opentelemetry/api (선택 peer) 가 있을 때만. 없으면 no-op (실패한 import 1회 캐시).\n */\n\nexport const INSTRUMENTATION_FILE = \"instrumentation.ts\"\n\n/** 핸들러를 실행한 어댑터. 원격 CLI 는 핸들러를 실행하지 않으므로 없다 */\nexport type Transport = \"http\" | \"stdio\" | \"local\"\n\nexport interface CommandErrorInfo {\n  /** 정식 명령어 ID. 자원 핸들러 (read · list · complete) 오류 = 자원 uri (템플릿 원문), 프롬프트 핸들러 오류 = 프롬프트 이름 */\n  command: string\n  /** 자원 핸들러 오류일 때 자원 uri (템플릿 원문, §12.3) */\n  resource?: string\n  /** 프롬프트 핸들러 (render · complete) 오류일 때 프롬프트 이름 (§12.3) */\n  prompt?: string\n  transport: Transport\n  /** scopes · claims 는 넘기지 않는다 */\n  principal: { id: string; kind: Principal[\"kind\"] }\n}\n\n/** instrumentation.ts 의 export */\nexport interface InstrumentationModule {\n  register?: () => unknown\n  onCommandError?: (error: unknown, info: CommandErrorInfo) => unknown\n}\n\n/** 어댑터가 InvokeOptions.instrumentation 으로 넘기는 로드 결과 */\nexport interface Instrumentation {\n  /** 핸들러 예외 (MextError 외, 취소 · MRTR 대기 제외). 자체 예외는 stderr 로 보고하고 응답은 바꾸지 않는다 */\n  onCommandError?: (error: unknown, info: CommandErrorInfo) => unknown\n  /** @opentelemetry/api. undefined = span 없음 */\n  otel?: OtelApi\n  /** onCommandError 의 예외 보고. 기본 stderr */\n  onerror?: (error: unknown) => void\n}\n\nexport interface LoadInstrumentationOptions {\n  /** @opentelemetry/api 로더 (테스트 주입). 기본 = 동적 import, 결과는 프로세스당 캐시 */\n  importOtel?: () => Promise<unknown>\n  onerror?: (error: unknown) => void\n}\n\n/** mext 가 쓰는 @opentelemetry/api 의 부분 (타입 의존 없이) */\nexport interface OtelApi {\n  trace: { getTracer(name: string, version?: string): OtelTracer }\n  context: { active(): unknown }\n  propagation: { extract(context: unknown, carrier: unknown): unknown }\n  SpanStatusCode: { ERROR: number }\n}\n\ninterface OtelTracer {\n  startActiveSpan<T>(name: string, options: { attributes: Record<string, string> }, context: unknown, fn: (span: OtelSpan) => T): T\n}\n\ninterface OtelSpan {\n  setAttribute(key: string, value: string): unknown\n  setStatus(status: { code: number; message?: string }): unknown\n  recordException(exception: unknown): unknown\n  end(): void\n}\n\n/** cwd 의 instrumentation.ts 절대 경로. 없으면 undefined */\nexport function findInstrumentation(cwd: string = process.cwd()): string | undefined {\n  const file = join(resolve(cwd), INSTRUMENTATION_FILE)\n  return existsSync(file) ? file : undefined\n}\n\n/** findInstrumentation(cwd) → loadInstrumentation. mext dev · mext run (로컬) · stdio 용 */\nexport function loadProjectInstrumentation(\n  cwd: string = process.cwd(),\n  options: LoadInstrumentationOptions = {},\n): Promise<Instrumentation> {\n  return loadInstrumentation(findInstrumentation(cwd), options)\n}\n\nconst loaded = new Map<string, Promise<InstrumentationModule>>()\nconst loadedModules = new WeakMap<object, Promise<InstrumentationModule>>()\n\n/**\n * instrumentation 모듈 (파일 경로 · URL · import 된 모듈) 을 프로세스당 1회 import 하고 register() 를 await.\n * 같은 모듈의 두 번째 호출 = register 재호출 없이 같은 hooks. register 실패 = reject (다음 호출에서 재시도).\n * source 없음 = hooks 없이 span 만. 빌드 산출물 (.mext/server/instrumentation.js) 도 같은 함수.\n */\nexport async function loadInstrumentation(\n  source?: string | URL | InstrumentationModule,\n  options: LoadInstrumentationOptions = {},\n): Promise<Instrumentation> {\n  const [mod, otel] = await Promise.all([\n    source === undefined ? Promise.resolve<InstrumentationModule>({}) : registerOnce(source),\n    options.importOtel ? resolveOtel(options.importOtel) : defaultOtel(),\n  ])\n  return {\n    ...(mod.onCommandError ? { onCommandError: mod.onCommandError } : {}),\n    ...(otel ? { otel } : {}),\n    ...(options.onerror ? { onerror: options.onerror } : {}),\n  }\n}\n\nfunction registerOnce(source: string | URL | InstrumentationModule): Promise<InstrumentationModule> {\n  if (typeof source === \"string\" || source instanceof URL) {\n    const isPath = typeof source === \"string\" && (isAbsolute(source) || !/^[a-z][a-z0-9+.-]+:/i.test(source))\n    const href = isPath ? pathToFileURL(resolve(source as string)).href : String(source)\n    return memo(loaded, href, () => import(href).then((m: unknown) => register(m, href)))\n  }\n  return memo(loadedModules, source, () => register(source, \"instrumentation\"))\n}\n\nfunction memo<K>(\n  cache: { get(k: K): Promise<InstrumentationModule> | undefined; set(k: K, v: Promise<InstrumentationModule>): unknown; delete(k: K): unknown },\n  key: K,\n  load: () => Promise<InstrumentationModule>,\n): Promise<InstrumentationModule> {\n  let pending = cache.get(key)\n  if (!pending) {\n    pending = load().catch((error: unknown) => {\n      cache.delete(key)\n      throw error\n    })\n    cache.set(key, pending)\n  }\n  return pending\n}\n\nasync function register(value: unknown, label: string): Promise<InstrumentationModule> {\n  const mod = (value ?? {}) as Record<string, unknown>\n  for (const key of [\"register\", \"onCommandError\"]) {\n    if (mod[key] !== undefined && typeof mod[key] !== \"function\") {\n      throw new TypeError(`${label}: export ${key} must be a function`)\n    }\n  }\n  const hooks = mod as InstrumentationModule\n  await hooks.register?.()\n  return hooks\n}\n\n/* @opentelemetry/api (선택 peer). 번들러가 해석 · 포함하지 않도록 specifier 는 변수 (R5) */\n\nconst OTEL_API = \"@opentelemetry/api\"\nlet otelDefault: Promise<OtelApi | undefined> | undefined\n\nfunction defaultOtel(): Promise<OtelApi | undefined> {\n  otelDefault ??= resolveOtel(() => import(OTEL_API))\n  return otelDefault\n}\n\nasync function resolveOtel(importer: () => Promise<unknown>): Promise<OtelApi | undefined> {\n  try {\n    const mod = (await importer()) as Partial<OtelApi> & { default?: Partial<OtelApi> }\n    const api = mod.trace ? mod : mod.default\n    return api?.trace && api.context && api.propagation && api.SpanStatusCode ? (api as OtelApi) : undefined\n  } catch {\n    return undefined\n  }\n}\n\n/* invoke 에서 사용 */\n\nconst TRACER_NAME = \"@obov/mext\"\n\nexport interface ObserveOptions {\n  instrumentation?: Instrumentation\n  transport?: Transport\n  principal: Principal\n  /** W3C trace context carrier (MCP params._meta 의 traceparent · tracestate) */\n  traceContext?: Record<string, unknown>\n}\n\n/**\n * 명령어 실행 1회를 `mext.command <id>` span 으로 감싼다 (otel 있을 때만, 없으면 fn 그대로).\n * 속성 = mext.command.id · mext.transport · mext.principal.kind. 인자 · 결과 · 토큰은 기록하지 않는다.\n * 실패: status ERROR + mext.error.code. 핸들러 예외만 recordException (MextError · CommandError 메시지는 입력 일부를 담을 수 있어 제외).\n * 취소 (signal abort · MRTR 대기) = status 없음.\n */\nexport function observeCommand<T>(\n  command: string,\n  options: ObserveOptions,\n  signal: () => AbortSignal | undefined,\n  fn: () => Promise<T>,\n): Promise<T> {\n  return observeSpan(`mext.command ${command}`, { \"mext.command.id\": command }, options, signal, fn)\n}\n\n/**\n * observeCommand 의 일반형 (자원 = `mext.resource <uri 템플릿>`, §12.3).\n * attributes 에 mext.transport · mext.principal.kind 를 더한다. 실패 · 취소 처리는 observeCommand 와 같다\n */\nexport function observeSpan<T>(\n  name: string,\n  attributes: Record<string, string>,\n  options: ObserveOptions,\n  signal: () => AbortSignal | undefined,\n  fn: () => Promise<T>,\n): Promise<T> {\n  const otel = options.instrumentation?.otel\n  if (!otel) return fn()\n  const parent = options.traceContext ? otel.propagation.extract(otel.context.active(), options.traceContext) : otel.context.active()\n  const all = {\n    ...attributes,\n    \"mext.transport\": options.transport ?? \"local\",\n    \"mext.principal.kind\": options.principal.kind,\n  }\n  const tracer = otel.trace.getTracer(TRACER_NAME)\n  return tracer.startActiveSpan(name, { attributes: all }, parent, async (span) => {\n    try {\n      return await fn()\n    } catch (error) {\n      if (!signal()?.aborted) {\n        if (isDeclaredError(error)) {\n          span.setAttribute(\"mext.error.code\", error.code)\n          span.setStatus({ code: otel.SpanStatusCode.ERROR, message: error.code })\n        } else {\n          span.setAttribute(\"mext.error.code\", \"EXECUTION_ERROR\")\n          span.recordException(error)\n          span.setStatus({ code: otel.SpanStatusCode.ERROR, message: error instanceof Error ? error.message : String(error) })\n        }\n      }\n      throw error\n    } finally {\n      span.end()\n    }\n  })\n}\n\n/**\n * 핸들러 예외 → onCommandError (await). MextError · CommandError · 취소 · MRTR 대기는 보고하지 않는다.\n * onCommandError 자체의 예외 = onerror (기본 stderr), 호출자에게 전파하지 않는다.\n */\nexport async function reportCommandError(\n  error: unknown,\n  command: string,\n  options: ObserveOptions,\n  signal: AbortSignal | undefined,\n  extra: { resource?: string; prompt?: string } = {},\n): Promise<void> {\n  const hook = options.instrumentation?.onCommandError\n  if (!hook || isDeclaredError(error) || signal?.aborted) return\n  const info: CommandErrorInfo = {\n    command,\n    ...extra,\n    transport: options.transport ?? \"local\",\n    principal: { id: options.principal.id, kind: options.principal.kind },\n  }\n  try {\n    await hook(error, info)\n  } catch (hookError) {\n    const onerror = options.instrumentation?.onerror ?? defaultOnError\n    try {\n      onerror(hookError)\n    } catch {\n      // 보고는 응답을 바꾸지 않는다\n    }\n  }\n}\n\nfunction defaultOnError(error: unknown): void {\n  const message = error instanceof Error ? (error.stack ?? error.message) : String(error)\n  process.stderr.write(`mext: onCommandError threw: ${message}\\n`)\n}\n"]}
+{"version":3,"file":"instrumentation.js","sourceRoot":"","sources":["../src/instrumentation.ts"],"names":[],"mappings":"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","sourcesContent":["import { existsSync } from \"node:fs\"\nimport { isAbsolute, join, resolve } from \"node:path\"\nimport { pathToFileURL } from \"node:url\"\nimport { isDeclaredError } from \"./errors.ts\"\nimport type { Principal } from \"./principal.ts\"\n\n/**\n * instrumentation.ts (프로젝트 루트, 선택) · OpenTelemetry span (§11).\n * register() = 프로세스당 1회, 첫 명령어 실행 전. onCommandError = 핸들러 예외 보고.\n * span = @opentelemetry/api (선택 peer) 가 있을 때만. 없으면 no-op (실패한 import 1회 캐시).\n */\n\nexport const INSTRUMENTATION_FILE = \"instrumentation.ts\"\n\n/** 핸들러를 실행한 어댑터. 원격 CLI 는 핸들러를 실행하지 않으므로 없다 */\nexport type Transport = \"http\" | \"stdio\" | \"local\"\n\nexport interface CommandErrorInfo {\n  /** 정식 명령어 ID. 자원 핸들러 (read · list · complete) 오류 = 자원 uri (템플릿 원문), 프롬프트 핸들러 오류 = 프롬프트 이름 */\n  command: string\n  /** 자원 핸들러 오류일 때 자원 uri (템플릿 원문, §12.3) */\n  resource?: string\n  /** 프롬프트 핸들러 (render · complete) 오류일 때 프롬프트 이름 (§12.3) */\n  prompt?: string\n  transport: Transport\n  /** scopes · claims 는 넘기지 않는다 */\n  principal: { id: string; kind: Principal[\"kind\"] }\n}\n\n/** instrumentation.ts 의 export */\nexport interface InstrumentationModule {\n  register?: () => unknown\n  onCommandError?: (error: unknown, info: CommandErrorInfo) => unknown\n}\n\n/** 어댑터가 InvokeOptions.instrumentation 으로 넘기는 로드 결과 */\nexport interface Instrumentation {\n  /** 핸들러 예외 (MextError 외, 취소 · MRTR 대기 제외). 자체 예외는 stderr 로 보고하고 응답은 바꾸지 않는다 */\n  onCommandError?: (error: unknown, info: CommandErrorInfo) => unknown\n  /** @opentelemetry/api. undefined = span 없음 */\n  otel?: OtelApi\n  /** onCommandError 의 예외 보고. 기본 stderr */\n  onerror?: (error: unknown) => void\n}\n\nexport interface LoadInstrumentationOptions {\n  /** @opentelemetry/api 로더 (테스트 주입). 기본 = 동적 import, 결과는 프로세스당 캐시 */\n  importOtel?: () => Promise<unknown>\n  onerror?: (error: unknown) => void\n}\n\n/** mext 가 쓰는 @opentelemetry/api 의 부분 (타입 의존 없이) */\nexport interface OtelApi {\n  trace: { getTracer(name: string, version?: string): OtelTracer }\n  context: { active(): unknown }\n  propagation: { extract(context: unknown, carrier: unknown): unknown }\n  SpanStatusCode: { ERROR: number }\n}\n\ninterface OtelTracer {\n  startActiveSpan<T>(name: string, options: { attributes: Record<string, string> }, context: unknown, fn: (span: OtelSpan) => T): T\n}\n\ninterface OtelSpan {\n  /** 없는 구현 (테스트 대역) 도 허용 */\n  spanContext?(): { traceId?: unknown; spanId?: unknown } | undefined\n  setAttribute(key: string, value: string): unknown\n  setStatus(status: { code: number; message?: string }): unknown\n  recordException(exception: unknown): unknown\n  end(): void\n}\n\n/** cwd 의 instrumentation.ts 절대 경로. 없으면 undefined */\nexport function findInstrumentation(cwd: string = process.cwd()): string | undefined {\n  const file = join(resolve(cwd), INSTRUMENTATION_FILE)\n  return existsSync(file) ? file : undefined\n}\n\n/** findInstrumentation(cwd) → loadInstrumentation. mext dev · mext run (로컬) · stdio 용 */\nexport function loadProjectInstrumentation(\n  cwd: string = process.cwd(),\n  options: LoadInstrumentationOptions = {},\n): Promise<Instrumentation> {\n  return loadInstrumentation(findInstrumentation(cwd), options)\n}\n\nconst loaded = new Map<string, Promise<InstrumentationModule>>()\nconst loadedModules = new WeakMap<object, Promise<InstrumentationModule>>()\n\n/**\n * instrumentation 모듈 (파일 경로 · URL · import 된 모듈) 을 프로세스당 1회 import 하고 register() 를 await.\n * 같은 모듈의 두 번째 호출 = register 재호출 없이 같은 hooks. register 실패 = reject (다음 호출에서 재시도).\n * source 없음 = hooks 없이 span 만. 빌드 산출물 (.mext/server/instrumentation.js) 도 같은 함수.\n */\nexport async function loadInstrumentation(\n  source?: string | URL | InstrumentationModule,\n  options: LoadInstrumentationOptions = {},\n): Promise<Instrumentation> {\n  const [mod, otel] = await Promise.all([\n    source === undefined ? Promise.resolve<InstrumentationModule>({}) : registerOnce(source),\n    options.importOtel ? resolveOtel(options.importOtel) : defaultOtel(),\n  ])\n  return {\n    ...(mod.onCommandError ? { onCommandError: mod.onCommandError } : {}),\n    ...(otel ? { otel } : {}),\n    ...(options.onerror ? { onerror: options.onerror } : {}),\n  }\n}\n\nfunction registerOnce(source: string | URL | InstrumentationModule): Promise<InstrumentationModule> {\n  if (typeof source === \"string\" || source instanceof URL) {\n    const isPath = typeof source === \"string\" && (isAbsolute(source) || !/^[a-z][a-z0-9+.-]+:/i.test(source))\n    const href = isPath ? pathToFileURL(resolve(source as string)).href : String(source)\n    return memo(loaded, href, () => import(href).then((m: unknown) => register(m, href)))\n  }\n  return memo(loadedModules, source, () => register(source, \"instrumentation\"))\n}\n\nfunction memo<K>(\n  cache: { get(k: K): Promise<InstrumentationModule> | undefined; set(k: K, v: Promise<InstrumentationModule>): unknown; delete(k: K): unknown },\n  key: K,\n  load: () => Promise<InstrumentationModule>,\n): Promise<InstrumentationModule> {\n  let pending = cache.get(key)\n  if (!pending) {\n    pending = load().catch((error: unknown) => {\n      cache.delete(key)\n      throw error\n    })\n    cache.set(key, pending)\n  }\n  return pending\n}\n\nasync function register(value: unknown, label: string): Promise<InstrumentationModule> {\n  const mod = (value ?? {}) as Record<string, unknown>\n  for (const key of [\"register\", \"onCommandError\"]) {\n    if (mod[key] !== undefined && typeof mod[key] !== \"function\") {\n      throw new TypeError(`${label}: export ${key} must be a function`)\n    }\n  }\n  const hooks = mod as InstrumentationModule\n  await hooks.register?.()\n  return hooks\n}\n\n/* @opentelemetry/api (선택 peer). 번들러가 해석 · 포함하지 않도록 specifier 는 변수 (R5) */\n\nconst OTEL_API = \"@opentelemetry/api\"\nlet otelDefault: Promise<OtelApi | undefined> | undefined\n\nfunction defaultOtel(): Promise<OtelApi | undefined> {\n  otelDefault ??= resolveOtel(() => import(OTEL_API))\n  return otelDefault\n}\n\nasync function resolveOtel(importer: () => Promise<unknown>): Promise<OtelApi | undefined> {\n  try {\n    const mod = (await importer()) as Partial<OtelApi> & { default?: Partial<OtelApi> }\n    const api = mod.trace ? mod : mod.default\n    return api?.trace && api.context && api.propagation && api.SpanStatusCode ? (api as OtelApi) : undefined\n  } catch {\n    return undefined\n  }\n}\n\n/* invoke 에서 사용 */\n\nconst TRACER_NAME = \"@obov/mext\"\n\n/** span 식별자 (감사 이벤트의 traceId · spanId, §11.1). 유효하지 않은 (전부 0) 값은 넘기지 않는다 */\nexport interface TraceIds {\n  traceId: string\n  spanId?: string\n}\n\nexport interface ObserveOptions {\n  instrumentation?: Instrumentation\n  transport?: Transport\n  principal: Principal\n  /** W3C trace context carrier (MCP params._meta 의 traceparent · tracestate) */\n  traceContext?: Record<string, unknown>\n}\n\n/**\n * 명령어 실행 1회를 `mext.command <id>` span 으로 감싼다 (otel 있을 때만, 없으면 fn 그대로).\n * 속성 = mext.command.id · mext.transport · mext.principal.kind. 인자 · 결과 · 토큰은 기록하지 않는다.\n * 실패: status ERROR + mext.error.code. 핸들러 예외만 recordException (MextError · CommandError 메시지는 입력 일부를 담을 수 있어 제외).\n * 취소 (signal abort · MRTR 대기) = status 없음.\n * fn 인자 = span 의 traceId · spanId (span 없음 = undefined)\n */\nexport function observeCommand<T>(\n  command: string,\n  options: ObserveOptions,\n  signal: () => AbortSignal | undefined,\n  fn: (trace?: TraceIds) => Promise<T>,\n): Promise<T> {\n  return observeSpan(`mext.command ${command}`, { \"mext.command.id\": command }, options, signal, fn)\n}\n\n/**\n * observeCommand 의 일반형 (자원 = `mext.resource <uri 템플릿>`, §12.3).\n * attributes 에 mext.transport · mext.principal.kind 를 더한다. 실패 · 취소 처리는 observeCommand 와 같다\n */\nexport function observeSpan<T>(\n  name: string,\n  attributes: Record<string, string>,\n  options: ObserveOptions,\n  signal: () => AbortSignal | undefined,\n  fn: (trace?: TraceIds) => Promise<T>,\n): Promise<T> {\n  const otel = options.instrumentation?.otel\n  if (!otel) return fn()\n  const parent = options.traceContext ? otel.propagation.extract(otel.context.active(), options.traceContext) : otel.context.active()\n  const all = {\n    ...attributes,\n    \"mext.transport\": options.transport ?? \"local\",\n    \"mext.principal.kind\": options.principal.kind,\n  }\n  const tracer = otel.trace.getTracer(TRACER_NAME)\n  return tracer.startActiveSpan(name, { attributes: all }, parent, async (span) => {\n    try {\n      return await fn(traceIds(span))\n    } catch (error) {\n      if (!signal()?.aborted) {\n        if (isDeclaredError(error)) {\n          span.setAttribute(\"mext.error.code\", error.code)\n          span.setStatus({ code: otel.SpanStatusCode.ERROR, message: error.code })\n        } else {\n          span.setAttribute(\"mext.error.code\", \"EXECUTION_ERROR\")\n          span.recordException(error)\n          span.setStatus({ code: otel.SpanStatusCode.ERROR, message: error instanceof Error ? error.message : String(error) })\n        }\n      }\n      throw error\n    } finally {\n      span.end()\n    }\n  })\n}\n\n/** span 의 traceId · spanId. SDK 미등록 (non-recording span, 전부 0) · 형식 오류 = undefined */\nfunction traceIds(span: OtelSpan): TraceIds | undefined {\n  const context = span.spanContext?.()\n  const traceId = context?.traceId\n  if (typeof traceId !== \"string\" || traceId === \"\" || /^0+$/.test(traceId)) return undefined\n  const spanId = context?.spanId\n  return typeof spanId === \"string\" && spanId !== \"\" && !/^0+$/.test(spanId) ? { traceId, spanId } : { traceId }\n}\n\n/**\n * 핸들러 예외 → onCommandError (await). MextError · CommandError · 취소 · MRTR 대기는 보고하지 않는다.\n * onCommandError 자체의 예외 = onerror (기본 stderr), 호출자에게 전파하지 않는다.\n */\nexport async function reportCommandError(\n  error: unknown,\n  command: string,\n  options: ObserveOptions,\n  signal: AbortSignal | undefined,\n  extra: { resource?: string; prompt?: string } = {},\n): Promise<void> {\n  const hook = options.instrumentation?.onCommandError\n  if (!hook || isDeclaredError(error) || signal?.aborted) return\n  const info: CommandErrorInfo = {\n    command,\n    ...extra,\n    transport: options.transport ?? \"local\",\n    principal: { id: options.principal.id, kind: options.principal.kind },\n  }\n  try {\n    await hook(error, info)\n  } catch (hookError) {\n    const onerror = options.instrumentation?.onerror ?? defaultOnError\n    try {\n      onerror(hookError)\n    } catch {\n      // 보고는 응답을 바꾸지 않는다\n    }\n  }\n}\n\nfunction defaultOnError(error: unknown): void {\n  const message = error instanceof Error ? (error.stack ?? error.message) : String(error)\n  process.stderr.write(`mext: onCommandError threw: ${message}\\n`)\n}\n"]}

package/dist/invoke.d.ts

@@ -1,4 +1,8 @@
 import * as z from "zod";
+import { type ApprovalConfig } from "./approval.ts";
+import { type ContentBlock } from "./content.ts";
+import { type AuditConfig } from "./audit.ts";
+import { type ReportedClient } from "./caller.ts";
 import type { CommandContext, InputSchema, MextApp, ProgressUpdate } from "./command.ts";
 import { MextError } from "./errors.ts";
 import { type Instrumentation, type Transport } from "./instrumentation.ts";
@@ -34,31 +38,55 @@ export interface InvokeOptions {
     app?: MextApp;
     /** readOnly 명령어만 허용 (split 의 query 도구). 그 외 = PERMISSION_DENIED */
     readOnly?: boolean;
+    /**
+     * 응답을 기다리게 하지 않을 작업 (숨긴 명령어 호출 시도의 감사 전달, §11.1) 을 넘겨받는다. MCP 어댑터 = waitUntil 또는 그대로 둠.
+     * 없음 = invoke 가 끝까지 기다린다 (로컬 실행: 프로세스가 곧 끝난다)
+     */
+    background?: (work: Promise<void>) => void;
     /** loadInstrumentation 결과. onCommandError · mext.command span. 기본 = 없음 */
     instrumentation?: Instrumentation;
-    /** 실행 어댑터 (onCommandError · span 속성). 기본 "local" */
+    /** 실행 어댑터 (onCommandError · span 속성 · ctx.caller.transport · 기본 표면). 기본 "local" */
     transport?: Transport;
+    /** 클라이언트가 신고한 clientInfo (ctx.caller.client). 자가 신고 값. 기본 = 없음 */
+    client?: ReportedClient;
     /** W3C trace context carrier (MCP params._meta 의 traceparent · tracestate). span 의 부모 */
     traceContext?: Record<string, unknown>;
     /** ctx.resourceUpdated (§12.5). 기본 = no-op */
     resourceUpdated?: (uri: string) => Promise<void>;
     /**
-     * tasks 확장 (§12.6). 입력 검증 · 권한 · requiresConfirmation 통과 후 execute 직전에 호출.
+     * tasks 확장 (§12.6). 입력 검증 · 권한 · 승인 (§4) 통과 후 execute 직전에 호출.
      * 반환 = 분리 실행: invoke 는 handle 로 바로 resolve, execute 는 반환된 signal · ask · progress 로 계속 실행 후 settle.
      * undefined = 동기 실행 (지금과 같음). span · onCommandError 는 분리 실행 전체를 덮는다
      */
     detach?: (entry: RegisteredCommand) => Promise<DetachedExecution | undefined>;
+    /** 감사 (config.audit, §11.1). 없음 = 이벤트 없음 */
+    audit?: AuditConfig;
+    /** 승인의 표면별 확인 방식 (config.approval, §4 승인). 없음 = 모든 표면 ask */
+    approval?: ApprovalConfig;
+    /**
+     * 요청에 확인 표시가 실려 있음 (MCP params._meta["dev.mext/approval"] = { confirmed: true }). 클라이언트가 실은 값이다:
+     * client 방식 표면 + 서버가 정한 행위자 human 일 때만 인정한다. 기본 false
+     */
+    confirmed?: boolean;
+    /**
+     * 이 호출이 입력 대기로 끝났는지 (MRTR 라운드: 답 없는 ctx.ask 가 있어 결과를 버리고 InputRequiredResult 를 돌려준다).
+     * true = 감사 이벤트 없음 (답을 받아 끝난 라운드가 1건)
+     */
+    pendingInput?: () => boolean;
 }
 /** detach 의 반환. execute 의 ctx 를 요청과 분리한다 (R2: 응답 종료 ≠ 취소) */
 export interface DetachedExecution {
     /** invoke 결과의 detached (MCP = CreateTaskResult) */
     handle: unknown;
+    /** 감사 이벤트의 taskId (§11.1) */
+    taskId?: string;
     signal: AbortSignal;
     ask: AskHandler;
     progress: (update: ProgressUpdate) => void;
     /** execute 종료. 값 = output 검증 후, 예외 = onCommandError 보고 후. 거부하지 않는다 */
     settle(outcome: {
         value: unknown;
+        content?: ContentBlock[];
     } | {
         error: unknown;
     }): Promise<void>;
@@ -67,14 +95,17 @@ export interface InvokeResult {
     /** 정식 ID (별칭으로 호출해도) */
     command: string;
     value: unknown;
+    /** 결과 콘텐츠 (image · audio · resource_link, spec §4). 없으면 생략 */
+    content?: ContentBlock[];
     /** detach 로 분리 실행됨: DetachedExecution.handle (value 는 undefined) */
     detached?: unknown;
 }
 /**
- * 어댑터 공통 실행기: ID 해석 (별칭 포함) → 권한 → (lazy 면 모듈 import) → Zod safeParse 1회 → 확인 (requiresConfirmation) → execute.
- * 실패는 MextError (UNKNOWN_COMMAND · PERMISSION_DENIED · INVALID_ARGUMENT · INPUT_UNAVAILABLE · INPUT_DECLINED).
+ * 어댑터 공통 실행기: ID 해석 (별칭 포함. 주체의 표면에서 숨긴 명령어 = 없는 ID, §4 expose) → 권한 → (lazy 면 모듈 import) → Zod safeParse 1회 → 가드 (authorize, §4) → 승인 (needsApproval · requiresConfirmation, §4) → execute.
+ * 실패는 MextError (UNKNOWN_COMMAND · PERMISSION_DENIED · INVALID_ARGUMENT · APPROVAL_REQUIRED · INPUT_UNAVAILABLE · INPUT_DECLINED).
  * 핸들러 예외는 그대로 전파 (instrumentation 있으면 onCommandError 보고 후).
  * instrumentation.otel 있으면 findCommand 뒤 전체를 `mext.command <id>` span 으로 감싼다.
+ * options.audit 있으면 호출 1건 = 감사 이벤트 1건 (§11.1. UNKNOWN_COMMAND · 입력 검증 실패 · 입력 대기 라운드 제외).
  */
 export declare function invoke(registry: Registry, id: string, rawInput: unknown, options: InvokeOptions): Promise<InvokeResult>;
 /** ID · 별칭 → 명령어. 없으면 UNKNOWN_COMMAND (suggested · usage). 구현 = lookup.ts (help · 고객 CLI 공용) */
@@ -96,7 +127,7 @@ export declare class OutputValidationError extends Error {
 export declare function createContext(entry: RegisteredCommand, options: InvokeOptions): CommandContext;
 /** ctx.resourceUpdated uri: 비어 있지 않은 문자열. 아니면 TypeError (핸들러 버그) */
 export declare function assertResourceUri(uri: unknown): asserts uri is string;
-/** requiresConfirmation 확인 문구. 검증된 입력을 포함 (무엇을 승인하는지) */
+/** 승인 확인 문구 (ask 방식). 검증된 입력을 포함 (무엇을 승인하는지) */
 export declare function confirmationMessage(entry: RegisteredCommand, input: unknown): string;
 /** INVALID_ARGUMENT (missing_fields · issues · expected_schema · examples). 프롬프트 인자 (§12.3) 도 사용 */
 export declare function invalidArgument(command: string, raw: unknown, zodIssues: readonly z.core.$ZodIssue[], expectedSchema: JsonSchema, examples: unknown[]): MextError<"INVALID_ARGUMENT">;

package/dist/invoke.js

@@ -1,60 +1,114 @@
 import * as z from "zod";
-import { inputDeclined, MextError } from "./errors.js";
+import { approvalModeOf } from "./approval.js";
+import { splitResult } from "./content.js";
+import { auditHidden, startAudit } from "./audit.js";
+import { callerOf, surfaceOf } from "./caller.js";
+import { approvalRequired, inputDeclined, isCommandError, isMextError, MextError } from "./errors.js";
+import { exposedRegistry } from "./expose.js";
 import { observeCommand, reportCommandError } from "./instrumentation.js";
 import { findCommand } from "./lookup.js";
 import { hasScope } from "./principal.js";
-import { loadCommand } from "./registry.js";
+import { loadCommand, resolveCommand } from "./registry.js";
 /**
- * 어댑터 공통 실행기: ID 해석 (별칭 포함) → 권한 → (lazy 면 모듈 import) → Zod safeParse 1회 → 확인 (requiresConfirmation) → execute.
- * 실패는 MextError (UNKNOWN_COMMAND · PERMISSION_DENIED · INVALID_ARGUMENT · INPUT_UNAVAILABLE · INPUT_DECLINED).
+ * 어댑터 공통 실행기: ID 해석 (별칭 포함. 주체의 표면에서 숨긴 명령어 = 없는 ID, §4 expose) → 권한 → (lazy 면 모듈 import) → Zod safeParse 1회 → 가드 (authorize, §4) → 승인 (needsApproval · requiresConfirmation, §4) → execute.
+ * 실패는 MextError (UNKNOWN_COMMAND · PERMISSION_DENIED · INVALID_ARGUMENT · APPROVAL_REQUIRED · INPUT_UNAVAILABLE · INPUT_DECLINED).
  * 핸들러 예외는 그대로 전파 (instrumentation 있으면 onCommandError 보고 후).
  * instrumentation.otel 있으면 findCommand 뒤 전체를 `mext.command <id>` span 으로 감싼다.
+ * options.audit 있으면 호출 1건 = 감사 이벤트 1건 (§11.1. UNKNOWN_COMMAND · 입력 검증 실패 · 입력 대기 라운드 제외).
  */
 export async function invoke(registry, id, rawInput, options) {
-    const entry = findCommand(registry, id);
+    // expose (§4): 주체의 표면에서 보이는 명령어만. 숨긴 명령어 = UNKNOWN_COMMAND (없는 ID 와 같은 본문)
+    const view = exposedRegistry(registry, surfaceOf(options.principal, options.transport ?? "local"));
+    let entry;
+    try {
+        entry = findCommand(view, id);
+    }
+    catch (error) {
+        // 숨긴 명령어의 호출 시도 기록 (audit.includeHidden, §11.1). 응답 = 이 오류 그대로. 꺼져 있으면 찾지 않는다
+        if (options.audit?.includeHidden === true && view !== registry) {
+            const hidden = resolveCommand(registry, id);
+            const work = hidden && auditHidden(hidden, options);
+            if (work) {
+                if (options.background)
+                    options.background(work);
+                else
+                    await work;
+            }
+        }
+        throw error;
+    }
     // span 의 취소 판정 signal. 분리 실행 후 = task signal
     let signal = options.signal;
     let handoff;
     const handedOff = options.detach ? new Promise((resolve) => (handoff = resolve)) : undefined;
-    const run = observeCommand(entry.id, options, () => signal, async () => {
+    // 감사 (§11.1). sink 없음 · 대상 아님 = undefined
+    const trail = startAudit(entry, options);
+    const body = async () => {
         authorize(entry, options.principal, { readOnly: options.readOnly });
         // lazy Registry (mext start) = 여기서 명령어 모듈 import. 권한 · ID 오류는 import 없이
         const command = await loadCommand(entry);
-        const input = await parseInput(entry, rawInput);
+        let input;
+        try {
+            input = await parseInput(entry, rawInput);
+        }
+        catch (error) {
+            // 입력 검증 실패 = 감사 이벤트 없음
+            trail?.skip();
+            throw error;
+        }
+        trail?.validated(command, input);
         const ctx = createContext(entry, options);
         ctx.signal.throwIfAborted();
-        if (entry.command.requiresConfirmation) {
-            // 확인은 ctx.ask 경유 (CLI = 프롬프트 · --yes, MCP = MRTR). ask 미주입 = INPUT_UNAVAILABLE
-            const confirmed = await ctx.ask({ kind: "confirm", message: confirmationMessage(entry, input) });
-            if (!confirmed)
-                throw inputDeclined(entry.id, "confirm");
-            ctx.signal.throwIfAborted();
-        }
+        // 가드 = 로드한 명령어의 authorize (lazy Registry 의 메타데이터 명령어에는 함수가 없다)
+        await guard(entry, command, input, ctx, options);
+        await approve(entry, command, input, ctx, options, trail);
         const detached = await options.detach?.(entry);
         if (detached) {
             signal = detached.signal;
             handoff({ command: entry.id, value: undefined, detached: detached.handle });
             const taskCtx = createContext(entry, { ...options, signal: detached.signal, ask: detached.ask, progress: detached.progress });
+            trail?.task(detached.taskId);
+            // 감사 = 분리 실행의 실제 종료 시점, task 결과 기록 (settle) 전
             try {
-                const value = await parseOutput(entry.id, command, await command.execute(input, taskCtx));
-                await detached.settle({ value });
-                return { command: entry.id, value };
+                const { value, content } = await settleOutput(entry.id, command, await command.execute(input, taskCtx));
+                await trail?.finish({ value }, false);
+                await detached.settle(content ? { value, content } : { value });
+                return { command: entry.id, value, ...(content ? { content } : {}) };
             }
             catch (error) {
                 await reportCommandError(error, entry.id, options, taskCtx.signal);
+                await trail?.finish({ error }, taskCtx.signal.aborted);
                 await detached.settle({ error });
                 throw error;
             }
         }
         try {
-            const value = await parseOutput(entry.id, command, await command.execute(input, ctx));
-            return { command: entry.id, value };
+            const { value, content } = await settleOutput(entry.id, command, await command.execute(input, ctx));
+            return { command: entry.id, value, ...(content ? { content } : {}) };
         }
         catch (error) {
             await reportCommandError(error, entry.id, options, ctx.signal);
             throw error;
         }
-    });
+    };
+    const run = observeCommand(entry.id, options, () => signal, !trail
+        ? body
+        : async (trace) => {
+            trail.trace(trace);
+            try {
+                const result = await body();
+                if (options.pendingInput?.())
+                    trail.skip();
+                await trail.finish({ value: result.value }, false);
+                return result;
+            }
+            catch (error) {
+                if (options.pendingInput?.())
+                    trail.skip();
+                await trail.finish({ error }, signal?.aborted === true);
+                throw error;
+            }
+        });
     // 분리 실행 = handoff 로 먼저 resolve. 이후 run 의 거부는 race 가 받는다 (미처리 거부 없음)
     return handedOff ? Promise.race([handedOff, run]) : run;
 }
@@ -81,6 +135,86 @@ export function authorize(entry, principal, options = {}) {
     if (missing.length > 0)
         deny("scope", `${entry.id} requires scopes: ${missing.join(", ")}.`);
 }
+/**
+ * 실행 가드 (defineCommand authorize, §4). true 만 통과. 그 외 반환값 (undefined 포함) · 예외 = PERMISSION_DENIED (reason "authorize").
+ * CommandError = 그 message 로 거부. 그 외 예외 = 거부 + onCommandError 보고 (message 는 응답에 싣지 않는다).
+ * 취소 · mext 오류 (ctx.ask 의 INPUT_UNAVAILABLE 등) · 입력 대기 중의 예외는 바꾸지 않는다
+ */
+async function guard(entry, command, input, ctx, options) {
+    if (!command.authorize)
+        return;
+    const denied = (message, cause) => {
+        const error = new MextError("PERMISSION_DENIED", message, {
+            command: entry.id,
+            reason: "authorize",
+            required_scopes: [...entry.command.scopes],
+            held_scopes: [...options.principal.scopes],
+        });
+        // 원인은 서버 쪽 디버깅용 (응답 본문 = toJSON 에는 없다)
+        if (cause !== undefined)
+            error.cause = cause;
+        return error;
+    };
+    let verdict;
+    try {
+        verdict = await command.authorize(input, ctx);
+    }
+    catch (error) {
+        if (ctx.signal.aborted || isMextError(error) || options.pendingInput?.())
+            throw error;
+        await reportCommandError(error, entry.id, options, ctx.signal);
+        throw denied(isCommandError(error) && error.message !== "" ? error.message : GUARD_DENIED(entry.id), error);
+    }
+    if (verdict !== true)
+        throw denied(GUARD_DENIED(entry.id));
+}
+/**
+ * 승인 (defineCommand needsApproval · requiresConfirmation, §4 승인). 승인이 필요한 호출을 표면의 확인 방식 한 곳에서 확인한다.
+ *   행위자 agent              = 승인 불가 (APPROVAL_REQUIRED human_required). 묻지 않는다
+ *   client 방식 표면          = 요청의 확인 표시 + 행위자 human 일 때만 통과. 묻지 않는다
+ *   ask 방식 표면 (기본)      = ctx.ask confirm (CLI = 프롬프트 · --yes, MCP = MRTR). ask 미주입 = INPUT_UNAVAILABLE. 확인 표시는 보지 않는다
+ * 승인 대상이 아닌 명령어 = 아무것도 하지 않는다
+ */
+async function approve(entry, command, input, ctx, options, trail) {
+    if (!command.requiresConfirmation) {
+        if (!command.needsApproval)
+            return;
+        if (!(await approvalNeeded(entry, command, input, ctx, options))) {
+            trail?.approval({ required: false });
+            return;
+        }
+    }
+    const method = approvalModeOf(options.approval, ctx.caller.surface);
+    const actor = options.principal.actor?.kind;
+    trail?.approval({ required: true, method, confirmed: false });
+    if (actor === "agent" || (method === "client" && actor !== "human")) {
+        throw approvalRequired(entry.id, "human_required", { agent: actor === "agent" });
+    }
+    if (method === "client") {
+        if (options.confirmed !== true)
+            throw approvalRequired(entry.id, "unconfirmed");
+    }
+    else {
+        const confirmed = await ctx.ask({ kind: "confirm", message: confirmationMessage(entry, input) });
+        if (!confirmed)
+            throw inputDeclined(entry.id, "confirm");
+        ctx.signal.throwIfAborted();
+    }
+    trail?.approval({ required: true, method, confirmed: true });
+}
+/** needsApproval 조건식. false 만 승인 불필요. 그 외 반환값 · 예외 = 필요 (예외는 onCommandError 보고). 취소 · 입력 대기 중의 예외는 전파 */
+async function approvalNeeded(entry, command, input, ctx, options) {
+    try {
+        return (await command.needsApproval(input, ctx)) !== false;
+    }
+    catch (error) {
+        if (ctx.signal.aborted || options.pendingInput?.())
+            throw error;
+        await reportCommandError(error, entry.id, options, ctx.signal);
+        return true;
+    }
+}
+const GUARD_DENIED = (id) => `${id} is not permitted for this caller.`;
 /** Zod safeParse 1회. 실패 = INVALID_ARGUMENT (missing_fields · issues · expected_schema · examples) */
 export async function parseInput(entry, rawInput) {
     const raw = rawInput === undefined ? {} : rawInput;
@@ -93,6 +227,12 @@ export async function parseInput(entry, rawInput) {
  * output 이 있으면 반환값 safeParse (모든 어댑터 · 노출 방식, §12.2). 결과 = 파싱된 값 (outputSchema 와 같은 모양).
  * 실패 = OutputValidationError (핸들러 예외와 같이 EXECUTION_ERROR · onCommandError 보고). 던진 오류는 검증하지 않는다
  */
+/** execute 반환값 → 값 · 콘텐츠 (spec §4 결과 콘텐츠). output 검증 = 값만 */
+async function settleOutput(id, command, raw) {
+    const { value, content } = splitResult(raw);
+    const parsed = await parseOutput(id, command, value);
+    return content ? { value: parsed, content } : { value: parsed };
+}
 async function parseOutput(id, command, value) {
     if (!command.output)
         return value;
@@ -145,6 +285,7 @@ export function createContext(entry, options) {
     };
     return {
         principal: options.principal,
+        caller: callerOf(options.principal, options.transport ?? "local", options.client),
         signal: options.signal ?? new AbortController().signal,
         progress: options.progress ?? (() => { }),
         ask: ask,
@@ -168,7 +309,7 @@ function assertAskUrl(url) {
         throw new TypeError(`ctx.ask url must be an absolute http(s) URL: ${JSON.stringify(url)}`);
     }
 }
-/** requiresConfirmation 확인 문구. 검증된 입력을 포함 (무엇을 승인하는지) */
+/** 승인 확인 문구 (ask 방식). 검증된 입력을 포함 (무엇을 승인하는지) */
 export function confirmationMessage(entry, input) {
     let args;
     try {