@ai-agent-forge/plugin-sdk 0.85.0

package/dist/observability.d.ts

@@ -0,0 +1,354 @@
+/**
+ * Public contracts for the first-party observability plugin (event journal +
+ * problem reports + trace sink). The plugin package
+ * (`@agent-forge/plugin-observability`) is the implementation; this module is
+ * the single authoring authority for its public types and the host-facing
+ * trace adapter contract. The host re-exports the surface from its historical
+ * `plugins/observability-types.ts` path so existing imports keep resolving.
+ *
+ * Contains types only, plus the `TRACE_KINDS_V1` value mirror with its
+ * compile-time drift guards (CLI `--trace-kind` validation consumes the
+ * value).
+ */
+import type { LoggerRecord, OutputArtifactRef } from "./public-api.ts";
+export type ObservabilityLogLevel = "info" | "warn" | "error";
+/**
+ * Output projection surface carried by the problem report's whole-document
+ * projection. Authority moved from the host's `host/output-serializer.ts`
+ * (D-075 S4 second batch); the host re-exports it from there.
+ */
+export type HostOutputSurfaceV1 = "tui" | "cli-text" | "inspector";
+/** One bounded-journal record derived from a delivered lifecycle event. */
+export interface ObservabilityJournalEntryV1 {
+    readonly sequence: number;
+    readonly at: number;
+    /** Session id extracted from the event data; null when the event has none. */
+    readonly sessionId: string | null;
+    /** Lifecycle event type, e.g. "model.stream" or "tool.commit". */
+    readonly stage: string;
+    readonly level: ObservabilityLogLevel;
+    /** Event correlation id, used as the trace grouping key. */
+    readonly traceId?: string;
+    readonly summary: string;
+    /** Validated lifecycle event data, retained verbatim for diagnosis. */
+    readonly data?: unknown;
+}
+export interface ObservabilityQueryFilterV1 {
+    readonly sessionId?: string;
+    readonly stage?: string;
+    readonly level?: ObservabilityLogLevel;
+    readonly traceId?: string;
+    /** When set, returns the most recent `limit` matching entries in order. */
+    readonly limit?: number;
+}
+export interface ObservabilityTraceStepV1 {
+    readonly entry: ObservabilityJournalEntryV1;
+    /** Milliseconds since the previous step; null on the first step. */
+    readonly durationMs: number | null;
+}
+export interface ObservabilityTraceTimelineV1 {
+    readonly traceId: string;
+    readonly steps: readonly ObservabilityTraceStepV1[];
+}
+export interface ObservabilityJournalStatsV1 {
+    readonly size: number;
+    readonly dropped: number;
+}
+export interface ObservabilityProblemReportSessionV1 {
+    readonly sessionId: string;
+    readonly entryCount: number;
+    readonly firstSequence: number | null;
+    readonly lastSequence: number | null;
+}
+/** Full error envelope of the most recent error-level entry for the session. */
+export interface ObservabilityProblemReportErrorV1 {
+    readonly sequence: number;
+    readonly at: number;
+    readonly stage: string;
+    /** Lifecycle phase when the event carries one (model.stream). */
+    readonly phase?: string;
+    readonly traceId: string | null;
+    readonly code: string;
+    readonly message: string;
+}
+export interface ObservabilityProblemReportTailEntryV1 {
+    readonly sequence: number;
+    readonly at: number;
+    readonly stage: string;
+    readonly level: ObservabilityLogLevel;
+    readonly traceId: string | null;
+    readonly summary: string;
+    /**
+     * Payload rendered through the host output serializer redaction channel;
+     * internal field keys are replaced at any depth before export.
+     */
+    readonly data?: string;
+}
+export interface ObservabilityProblemReportCountsV1 {
+    readonly byStage: Readonly<Record<string, number>>;
+    readonly byLevel: Readonly<Record<string, number>>;
+}
+/** A metric the journal cannot currently source; the reason names the missing event granularity. */
+export interface MetricsNotSampledV1 {
+    readonly status: "not_sampled";
+    readonly reason: string;
+}
+/** Cancel-latency samples: delay from a cancel signal to the turn's terminal event. */
+export interface MetricsCancelLatencySampledV1 {
+    readonly status: "sampled";
+    readonly count: number;
+    readonly p50Ms: number | null;
+    readonly p95Ms: number | null;
+}
+/** Token/cost totals summed over usage-bearing journal events. */
+export interface MetricsTokensSampledV1 {
+    readonly status: "sampled";
+    readonly totalTokens: number;
+}
+/** Memory recall hit rate over `memory_recall` tool executions in the window. */
+export interface MetricsMemoryRecallSampledV1 {
+    readonly status: "sampled";
+    readonly calls: number;
+    readonly hits: number;
+    readonly hitRate: number;
+}
+export interface MetricsToolErrorsV1 {
+    readonly calls: number;
+    readonly errors: number;
+    /** `null` when no tool executions occurred in the window. */
+    readonly errorRate: number | null;
+    /** Errors per tool name, descending by count then ascending by name. */
+    readonly topErrors: readonly {
+        readonly toolName: string;
+        readonly errors: number;
+    }[];
+}
+export interface MetricsTurnsV1 {
+    readonly count: number;
+    readonly successCount: number;
+    /** `null` when no turns occurred in the window. */
+    readonly successRate: number | null;
+    readonly p50DurationMs: number | null;
+    readonly p95DurationMs: number | null;
+}
+/** Window metadata: which turns were aggregated and their time span. */
+export interface MetricsWindowV1 {
+    /** Requested turn bound; `null` when the whole journal was aggregated. */
+    readonly windowTurns: number | null;
+    readonly sampledTurns: number;
+    readonly firstAt: number | null;
+    readonly lastAt: number | null;
+}
+/**
+ * Deterministic product metrics aggregated read-only from the journal ring.
+ * Metrics the journal cannot source are reported as `not_sampled` with the
+ * reason instead of being fabricated.
+ */
+export interface MetricsSnapshotV1 {
+    readonly version: 1;
+    readonly window: MetricsWindowV1;
+    readonly turns: MetricsTurnsV1;
+    readonly tools: MetricsToolErrorsV1;
+    readonly cancelLatencyMs: MetricsCancelLatencySampledV1 | MetricsNotSampledV1;
+    readonly tokens: MetricsTokensSampledV1 | MetricsNotSampledV1;
+    readonly memoryRecall: MetricsMemoryRecallSampledV1 | MetricsNotSampledV1;
+}
+/** Aggregate options for {@link ObservabilityPlugin.getMetrics}. */
+export interface ObservabilityMetricsOptions {
+    /** Aggregate only the most recent `windowTurns` correlationId groups; omit for the whole journal. */
+    readonly windowTurns?: number;
+}
+/**
+ * Trace record kinds for `agent-forge/trace.v1`
+ * (design: docs/design/会话轨迹与日志设计.md §4.2).
+ */
+export type TraceKindV1 = "session.start" | "turn.span" | "llm.request" | "llm.response" | "tool.span" | "lifecycle" | "error" | "decision" | "plugin.log";
+/**
+ * Runtime mirror of `TraceKindV1` for value-level consumers (CLI
+ * `--trace-kind` validation), kept beside the union so the two compile-time
+ * drift guards fail the build when they diverge in either direction:
+ * - the `satisfies` below rejects a list entry the union no longer has;
+ * - `_TRACE_KINDS_EXHAUSTIVE_CHECK` rejects a union member missing from the
+ *   list (`never` is not assignable from `true`).
+ */
+export declare const TRACE_KINDS_V1: readonly ["session.start", "turn.span", "llm.request", "llm.response", "tool.span", "lifecycle", "error", "decision", "plugin.log"];
+/** One append-only JSONL trace record (design §4.2). */
+export interface TraceRecordV1 {
+    readonly v: 1;
+    readonly schema: "agent-forge/trace.v1";
+    /** Monotonic sequence within one trace file, starting at 1. */
+    readonly seq: number;
+    /** Host timestamp (epoch ms). */
+    readonly t: number;
+    /** Duration of a closed span (ms). */
+    readonly dur?: number;
+    readonly kind: TraceKindV1;
+    /** Turn/request correlation id, shared with lifecycle events and logs. */
+    readonly traceId?: string;
+    readonly level?: ObservabilityLogLevel;
+    /** Kind-specific bounded data. */
+    readonly data?: unknown;
+}
+/** Bounds for trace payload snapshots (design §4.3); each field defaults when omitted. */
+export interface TraceSinkOptionsV1 {
+    /** Strings longer than this truncate with a `…[truncated N chars]` suffix. Default 16_000. */
+    readonly maxStringChars?: number;
+    /**
+     * Serialized snapshot budget in bytes, enforced largest-string-first inside
+     * `llm.request.data.payload`. Strictly below the 512 KiB per-record budget.
+     * Default 393_216 (384 KiB).
+     */
+    readonly maxSnapshotBytes?: number;
+    /**
+     * OTLP/HTTP+JSON trace export (design §8). Omitted keeps the exporter
+     * absent: no transport, no buffering, file-sink behavior unchanged. The
+     * endpoint is the OTLP base URL (e.g. `http://localhost:4318`); the
+     * `/v1/traces` signal path is appended unless already present.
+     */
+    readonly otlp?: OtlpExportOptionsV1;
+}
+/** OTLP/HTTP+JSON exporter options; all durations/bounds are deterministic inputs. */
+export interface OtlpExportOptionsV1 {
+    /** OTLP base URL; `/v1/traces` is appended unless already present. */
+    readonly endpoint: string;
+    /**
+     * Transport injection for deterministic tests and custom hosts (proxy,
+     * in-process collector); defaults to `globalThis.fetch`. Only the fields
+     * below are consumed by the plugin.
+     */
+    readonly fetchImpl?: (url: string, init: {
+        method: "POST";
+        headers: {
+            "content-type": string;
+        };
+        body: string;
+        signal: AbortSignal;
+    }) => Promise<{
+        ok: boolean;
+        status: number;
+    }>;
+    /** Per-flush HTTP timeout in ms. Default 5_000. */
+    readonly timeoutMs?: number;
+    /** Buffered-span count that triggers an early flush. Default 64. */
+    readonly flushThreshold?: number;
+}
+/**
+ * Telemetry export seam (design §8): the single attachment point for trace
+ * exporters (first OTLP/HTTP+JSON; future Prometheus-style pull surfaces hook
+ * here instead of growing bespoke taps). Hosts inject sinks through
+ * `ObservabilityTraceConfig.exportSinks`; the plugin never reaches into host
+ * internals and never lets a sink break event delivery.
+ */
+export interface ObservabilityExportSinkV1 {
+    /** Called synchronously for every finalized trace record. Must not throw. */
+    readonly onTraceRecord: (record: TraceRecordV1) => void;
+    /** Best-effort flush; resolves after the batch is delivered or dropped. */
+    readonly flush: (reason: string) => Promise<void>;
+}
+/**
+ * Host-injected adapter for the trace sink (design §4.4). The host closure
+ * owns session-path resolution, provider payload capture, and failure
+ * reporting; the plugin never reaches into host internals.
+ */
+export interface ObservabilityHostAdapterV1 {
+    /** Trace file path for the current session, or `null` when tracing is off. */
+    getTraceFilePath(): string | null;
+    /** Host push of the finalized provider payload (sdk `onPayload` tail). */
+    captureProviderPayload(payload: unknown, model: unknown): void;
+    /** Trace write-failure channel; the host forwards to the process log. */
+    onSinkFailure(error: unknown): void;
+    /**
+     * Correlation id of the turn currently in flight, or `undefined` outside a
+     * turn. Omitted keeps the phase-1 behavior: `llm.request` and `plugin.log`
+     * records carry no traceId.
+     */
+    getTurnCorrelationId?(): string | undefined;
+    /**
+     * Session-header fact: the parent agent session id recorded at session
+     * creation (`SessionHeader.parentAgentSession`, session-manager.ts).
+     * Omitted — or returning `undefined` when the header has no such field —
+     * keeps the previous behavior: the `session.start` record carries no
+     * `parentSessionId`.
+     */
+    getParentAgentSessionId?(): string | undefined;
+    /**
+     * Session-header fact: the parent-turn correlation id that created this
+     * session (`SessionHeader.parentTraceId`, session-manager.ts; frozen at
+     * creation). Omitted — or returning `undefined` — keeps the previous
+     * behavior: the `session.start` record carries no `parentTraceId`.
+     */
+    getParentTraceId?(): string | undefined;
+    /**
+     * Plugin-to-host facade registration (D-075 S4 second batch). The plugin
+     * entry calls it once after creating the plugin instance so the host's
+     * assembly refs (provider payload capture, plugin.log mirror, /metrics
+     * source) keep their embedded-era semantics; calling it again with
+     * `undefined` on teardown clears them. Omitted on hosts that consume the
+     * facade through another channel — the entry must probe before calling.
+     */
+    registerFacade?(facade: ObservabilityPluginFacadeV1 | undefined): void;
+}
+/**
+ * The narrow plugin-facing face the host consumes through
+ * {@link ObservabilityHostAdapterV1.registerFacade}. The plugin instance is
+ * structurally assignable to it.
+ */
+export interface ObservabilityPluginFacadeV1 {
+    captureProviderPayload(payload: unknown, model: unknown): void;
+    /** Optional: present since the plugin.log mirror (design §7.2). */
+    mirrorPluginLog?(record: LoggerRecord): void;
+    getMetrics(options?: ObservabilityMetricsOptions): MetricsSnapshotV1;
+}
+/** Deterministic problem report; `reportId` is FNV-1a-32 hex over the canonical JSON of the report body. */
+export interface ProblemReportV1 {
+    readonly version: 1;
+    readonly reportId: string;
+    readonly createdAt: number;
+    readonly reason: string;
+    readonly session: ObservabilityProblemReportSessionV1;
+    readonly lastError: ObservabilityProblemReportErrorV1 | null;
+    readonly journalTail: readonly ObservabilityProblemReportTailEntryV1[];
+    readonly counts: ObservabilityProblemReportCountsV1;
+    readonly dropped: number;
+    readonly redactionApplied: boolean;
+    /** Whole-report projection rendered by the host output serializer. */
+    readonly projection: {
+        readonly surface: HostOutputSurfaceV1;
+        readonly text: string;
+    };
+    /** Present only when the host declared the `output-artifacts` feature. */
+    readonly artifact?: OutputArtifactRef;
+}
+/**
+ * The observability plugin's public behavior face (journal read side, trace
+ * explanation, deterministic metrics, problem-report export). The plugin
+ * package returns this shape from its factory; hosts consume it through
+ * {@link ObservabilityPluginFacadeV1} or their own references.
+ */
+export interface ObservabilityPlugin {
+    readonly id: string;
+    query(filter?: ObservabilityQueryFilterV1): readonly ObservabilityJournalEntryV1[];
+    explainTrace(traceId: string): ObservabilityTraceTimelineV1;
+    getMetrics(options?: ObservabilityMetricsOptions): MetricsSnapshotV1;
+    stats(): ObservabilityJournalStatsV1;
+    exportProblemReport(input: {
+        readonly sessionId: string;
+        readonly reason: string;
+    }): Promise<ProblemReportV1>;
+    /**
+     * Receives the finalized provider payload from the host adapter and emits
+     * one `llm.request` trace record with a bounded redacted snapshot (design
+     * §4.3). No-op when no trace adapter was injected.
+     */
+    captureProviderPayload(payload: unknown, model: unknown): void;
+    /**
+     * Receives one plugin LoggerAPI record forwarded by the host runtime sink
+     * (`CapabilityRuntimeOptions.onLogRecord`) and appends a `plugin.log` trace
+     * record (design §4.2/§7.2). No-op when no trace adapter was injected.
+     * Must never call `api.logger`: the host forwards logger output here, so
+     * logging from inside would recurse.
+     */
+    mirrorPluginLog(record: LoggerRecord): void;
+    dispose(): void;
+}
+//# sourceMappingURL=observability.d.ts.map

package/dist/observability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.d.ts","sourceRoot":"","sources":["../src/observability.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Public contracts for the first-party observability plugin (event journal +\n * problem reports + trace sink). The plugin package\n * (`@agent-forge/plugin-observability`) is the implementation; this module is\n * the single authoring authority for its public types and the host-facing\n * trace adapter contract. The host re-exports the surface from its historical\n * `plugins/observability-types.ts` path so existing imports keep resolving.\n *\n * Contains types only, plus the `TRACE_KINDS_V1` value mirror with its\n * compile-time drift guards (CLI `--trace-kind` validation consumes the\n * value).\n */\n\nimport type { LoggerRecord, OutputArtifactRef } from \"./public-api.ts\";\n\nexport type ObservabilityLogLevel = \"info\" | \"warn\" | \"error\";\n\n/**\n * Output projection surface carried by the problem report's whole-document\n * projection. Authority moved from the host's `host/output-serializer.ts`\n * (D-075 S4 second batch); the host re-exports it from there.\n */\nexport type HostOutputSurfaceV1 = \"tui\" | \"cli-text\" | \"inspector\";\n\n/** One bounded-journal record derived from a delivered lifecycle event. */\nexport interface ObservabilityJournalEntryV1 {\n\treadonly sequence: number;\n\treadonly at: number;\n\t/** Session id extracted from the event data; null when the event has none. */\n\treadonly sessionId: string | null;\n\t/** Lifecycle event type, e.g. \"model.stream\" or \"tool.commit\". */\n\treadonly stage: string;\n\treadonly level: ObservabilityLogLevel;\n\t/** Event correlation id, used as the trace grouping key. */\n\treadonly traceId?: string;\n\treadonly summary: string;\n\t/** Validated lifecycle event data, retained verbatim for diagnosis. */\n\treadonly data?: unknown;\n}\n\nexport interface ObservabilityQueryFilterV1 {\n\treadonly sessionId?: string;\n\treadonly stage?: string;\n\treadonly level?: ObservabilityLogLevel;\n\treadonly traceId?: string;\n\t/** When set, returns the most recent `limit` matching entries in order. */\n\treadonly limit?: number;\n}\n\nexport interface ObservabilityTraceStepV1 {\n\treadonly entry: ObservabilityJournalEntryV1;\n\t/** Milliseconds since the previous step; null on the first step. */\n\treadonly durationMs: number | null;\n}\n\nexport interface ObservabilityTraceTimelineV1 {\n\treadonly traceId: string;\n\treadonly steps: readonly ObservabilityTraceStepV1[];\n}\n\nexport interface ObservabilityJournalStatsV1 {\n\treadonly size: number;\n\treadonly dropped: number;\n}\n\nexport interface ObservabilityProblemReportSessionV1 {\n\treadonly sessionId: string;\n\treadonly entryCount: number;\n\treadonly firstSequence: number | null;\n\treadonly lastSequence: number | null;\n}\n\n/** Full error envelope of the most recent error-level entry for the session. */\nexport interface ObservabilityProblemReportErrorV1 {\n\treadonly sequence: number;\n\treadonly at: number;\n\treadonly stage: string;\n\t/** Lifecycle phase when the event carries one (model.stream). */\n\treadonly phase?: string;\n\treadonly traceId: string | null;\n\treadonly code: string;\n\treadonly message: string;\n}\n\nexport interface ObservabilityProblemReportTailEntryV1 {\n\treadonly sequence: number;\n\treadonly at: number;\n\treadonly stage: string;\n\treadonly level: ObservabilityLogLevel;\n\treadonly traceId: string | null;\n\treadonly summary: string;\n\t/**\n\t * Payload rendered through the host output serializer redaction channel;\n\t * internal field keys are replaced at any depth before export.\n\t */\n\treadonly data?: string;\n}\n\nexport interface ObservabilityProblemReportCountsV1 {\n\treadonly byStage: Readonly<Record<string, number>>;\n\treadonly byLevel: Readonly<Record<string, number>>;\n}\n\n/** A metric the journal cannot currently source; the reason names the missing event granularity. */\nexport interface MetricsNotSampledV1 {\n\treadonly status: \"not_sampled\";\n\treadonly reason: string;\n}\n\n/** Cancel-latency samples: delay from a cancel signal to the turn's terminal event. */\nexport interface MetricsCancelLatencySampledV1 {\n\treadonly status: \"sampled\";\n\treadonly count: number;\n\treadonly p50Ms: number | null;\n\treadonly p95Ms: number | null;\n}\n\n/** Token/cost totals summed over usage-bearing journal events. */\nexport interface MetricsTokensSampledV1 {\n\treadonly status: \"sampled\";\n\treadonly totalTokens: number;\n}\n\n/** Memory recall hit rate over `memory_recall` tool executions in the window. */\nexport interface MetricsMemoryRecallSampledV1 {\n\treadonly status: \"sampled\";\n\treadonly calls: number;\n\treadonly hits: number;\n\treadonly hitRate: number;\n}\n\nexport interface MetricsToolErrorsV1 {\n\treadonly calls: number;\n\treadonly errors: number;\n\t/** `null` when no tool executions occurred in the window. */\n\treadonly errorRate: number | null;\n\t/** Errors per tool name, descending by count then ascending by name. */\n\treadonly topErrors: readonly { readonly toolName: string; readonly errors: number }[];\n}\n\nexport interface MetricsTurnsV1 {\n\treadonly count: number;\n\treadonly successCount: number;\n\t/** `null` when no turns occurred in the window. */\n\treadonly successRate: number | null;\n\treadonly p50DurationMs: number | null;\n\treadonly p95DurationMs: number | null;\n}\n\n/** Window metadata: which turns were aggregated and their time span. */\nexport interface MetricsWindowV1 {\n\t/** Requested turn bound; `null` when the whole journal was aggregated. */\n\treadonly windowTurns: number | null;\n\treadonly sampledTurns: number;\n\treadonly firstAt: number | null;\n\treadonly lastAt: number | null;\n}\n\n/**\n * Deterministic product metrics aggregated read-only from the journal ring.\n * Metrics the journal cannot source are reported as `not_sampled` with the\n * reason instead of being fabricated.\n */\nexport interface MetricsSnapshotV1 {\n\treadonly version: 1;\n\treadonly window: MetricsWindowV1;\n\treadonly turns: MetricsTurnsV1;\n\treadonly tools: MetricsToolErrorsV1;\n\treadonly cancelLatencyMs: MetricsCancelLatencySampledV1 | MetricsNotSampledV1;\n\treadonly tokens: MetricsTokensSampledV1 | MetricsNotSampledV1;\n\treadonly memoryRecall: MetricsMemoryRecallSampledV1 | MetricsNotSampledV1;\n}\n\n/** Aggregate options for {@link ObservabilityPlugin.getMetrics}. */\nexport interface ObservabilityMetricsOptions {\n\t/** Aggregate only the most recent `windowTurns` correlationId groups; omit for the whole journal. */\n\treadonly windowTurns?: number;\n}\n\n/**\n * Trace record kinds for `agent-forge/trace.v1`\n * (design: docs/design/会话轨迹与日志设计.md §4.2).\n */\nexport type TraceKindV1 =\n\t| \"session.start\"\n\t| \"turn.span\"\n\t| \"llm.request\"\n\t| \"llm.response\"\n\t| \"tool.span\"\n\t| \"lifecycle\"\n\t| \"error\"\n\t| \"decision\"\n\t| \"plugin.log\";\n\n/**\n * Runtime mirror of `TraceKindV1` for value-level consumers (CLI\n * `--trace-kind` validation), kept beside the union so the two compile-time\n * drift guards fail the build when they diverge in either direction:\n * - the `satisfies` below rejects a list entry the union no longer has;\n * - `_TRACE_KINDS_EXHAUSTIVE_CHECK` rejects a union member missing from the\n *   list (`never` is not assignable from `true`).\n */\nexport const TRACE_KINDS_V1 = [\n\t\"session.start\",\n\t\"turn.span\",\n\t\"llm.request\",\n\t\"llm.response\",\n\t\"tool.span\",\n\t\"lifecycle\",\n\t\"error\",\n\t\"decision\",\n\t\"plugin.log\",\n] as const satisfies readonly TraceKindV1[];\n\ntype TraceKindListV1 = (typeof TRACE_KINDS_V1)[number];\nconst _TRACE_KINDS_EXHAUSTIVE_CHECK: TraceKindV1 extends TraceKindListV1 ? true : never = true;\n\n/** One append-only JSONL trace record (design §4.2). */\nexport interface TraceRecordV1 {\n\treadonly v: 1;\n\treadonly schema: \"agent-forge/trace.v1\";\n\t/** Monotonic sequence within one trace file, starting at 1. */\n\treadonly seq: number;\n\t/** Host timestamp (epoch ms). */\n\treadonly t: number;\n\t/** Duration of a closed span (ms). */\n\treadonly dur?: number;\n\treadonly kind: TraceKindV1;\n\t/** Turn/request correlation id, shared with lifecycle events and logs. */\n\treadonly traceId?: string;\n\treadonly level?: ObservabilityLogLevel;\n\t/** Kind-specific bounded data. */\n\treadonly data?: unknown;\n}\n\n/** Bounds for trace payload snapshots (design §4.3); each field defaults when omitted. */\nexport interface TraceSinkOptionsV1 {\n\t/** Strings longer than this truncate with a `…[truncated N chars]` suffix. Default 16_000. */\n\treadonly maxStringChars?: number;\n\t/**\n\t * Serialized snapshot budget in bytes, enforced largest-string-first inside\n\t * `llm.request.data.payload`. Strictly below the 512 KiB per-record budget.\n\t * Default 393_216 (384 KiB).\n\t */\n\treadonly maxSnapshotBytes?: number;\n\t/**\n\t * OTLP/HTTP+JSON trace export (design §8). Omitted keeps the exporter\n\t * absent: no transport, no buffering, file-sink behavior unchanged. The\n\t * endpoint is the OTLP base URL (e.g. `http://localhost:4318`); the\n\t * `/v1/traces` signal path is appended unless already present.\n\t */\n\treadonly otlp?: OtlpExportOptionsV1;\n}\n\n/** OTLP/HTTP+JSON exporter options; all durations/bounds are deterministic inputs. */\nexport interface OtlpExportOptionsV1 {\n\t/** OTLP base URL; `/v1/traces` is appended unless already present. */\n\treadonly endpoint: string;\n\t/**\n\t * Transport injection for deterministic tests and custom hosts (proxy,\n\t * in-process collector); defaults to `globalThis.fetch`. Only the fields\n\t * below are consumed by the plugin.\n\t */\n\treadonly fetchImpl?: (\n\t\turl: string,\n\t\tinit: { method: \"POST\"; headers: { \"content-type\": string }; body: string; signal: AbortSignal },\n\t) => Promise<{ ok: boolean; status: number }>;\n\t/** Per-flush HTTP timeout in ms. Default 5_000. */\n\treadonly timeoutMs?: number;\n\t/** Buffered-span count that triggers an early flush. Default 64. */\n\treadonly flushThreshold?: number;\n}\n\n/**\n * Telemetry export seam (design §8): the single attachment point for trace\n * exporters (first OTLP/HTTP+JSON; future Prometheus-style pull surfaces hook\n * here instead of growing bespoke taps). Hosts inject sinks through\n * `ObservabilityTraceConfig.exportSinks`; the plugin never reaches into host\n * internals and never lets a sink break event delivery.\n */\nexport interface ObservabilityExportSinkV1 {\n\t/** Called synchronously for every finalized trace record. Must not throw. */\n\treadonly onTraceRecord: (record: TraceRecordV1) => void;\n\t/** Best-effort flush; resolves after the batch is delivered or dropped. */\n\treadonly flush: (reason: string) => Promise<void>;\n}\n\n/**\n * Host-injected adapter for the trace sink (design §4.4). The host closure\n * owns session-path resolution, provider payload capture, and failure\n * reporting; the plugin never reaches into host internals.\n */\nexport interface ObservabilityHostAdapterV1 {\n\t/** Trace file path for the current session, or `null` when tracing is off. */\n\tgetTraceFilePath(): string | null;\n\t/** Host push of the finalized provider payload (sdk `onPayload` tail). */\n\tcaptureProviderPayload(payload: unknown, model: unknown): void;\n\t/** Trace write-failure channel; the host forwards to the process log. */\n\tonSinkFailure(error: unknown): void;\n\t/**\n\t * Correlation id of the turn currently in flight, or `undefined` outside a\n\t * turn. Omitted keeps the phase-1 behavior: `llm.request` and `plugin.log`\n\t * records carry no traceId.\n\t */\n\tgetTurnCorrelationId?(): string | undefined;\n\t/**\n\t * Session-header fact: the parent agent session id recorded at session\n\t * creation (`SessionHeader.parentAgentSession`, session-manager.ts).\n\t * Omitted — or returning `undefined` when the header has no such field —\n\t * keeps the previous behavior: the `session.start` record carries no\n\t * `parentSessionId`.\n\t */\n\tgetParentAgentSessionId?(): string | undefined;\n\t/**\n\t * Session-header fact: the parent-turn correlation id that created this\n\t * session (`SessionHeader.parentTraceId`, session-manager.ts; frozen at\n\t * creation). Omitted — or returning `undefined` — keeps the previous\n\t * behavior: the `session.start` record carries no `parentTraceId`.\n\t */\n\tgetParentTraceId?(): string | undefined;\n\t/**\n\t * Plugin-to-host facade registration (D-075 S4 second batch). The plugin\n\t * entry calls it once after creating the plugin instance so the host's\n\t * assembly refs (provider payload capture, plugin.log mirror, /metrics\n\t * source) keep their embedded-era semantics; calling it again with\n\t * `undefined` on teardown clears them. Omitted on hosts that consume the\n\t * facade through another channel — the entry must probe before calling.\n\t */\n\tregisterFacade?(facade: ObservabilityPluginFacadeV1 | undefined): void;\n}\n\n/**\n * The narrow plugin-facing face the host consumes through\n * {@link ObservabilityHostAdapterV1.registerFacade}. The plugin instance is\n * structurally assignable to it.\n */\nexport interface ObservabilityPluginFacadeV1 {\n\tcaptureProviderPayload(payload: unknown, model: unknown): void;\n\t/** Optional: present since the plugin.log mirror (design §7.2). */\n\tmirrorPluginLog?(record: LoggerRecord): void;\n\tgetMetrics(options?: ObservabilityMetricsOptions): MetricsSnapshotV1;\n}\n\n/** Deterministic problem report; `reportId` is FNV-1a-32 hex over the canonical JSON of the report body. */\nexport interface ProblemReportV1 {\n\treadonly version: 1;\n\treadonly reportId: string;\n\treadonly createdAt: number;\n\treadonly reason: string;\n\treadonly session: ObservabilityProblemReportSessionV1;\n\treadonly lastError: ObservabilityProblemReportErrorV1 | null;\n\treadonly journalTail: readonly ObservabilityProblemReportTailEntryV1[];\n\treadonly counts: ObservabilityProblemReportCountsV1;\n\treadonly dropped: number;\n\treadonly redactionApplied: boolean;\n\t/** Whole-report projection rendered by the host output serializer. */\n\treadonly projection: {\n\t\treadonly surface: HostOutputSurfaceV1;\n\t\treadonly text: string;\n\t};\n\t/** Present only when the host declared the `output-artifacts` feature. */\n\treadonly artifact?: OutputArtifactRef;\n}\n\n/**\n * The observability plugin's public behavior face (journal read side, trace\n * explanation, deterministic metrics, problem-report export). The plugin\n * package returns this shape from its factory; hosts consume it through\n * {@link ObservabilityPluginFacadeV1} or their own references.\n */\nexport interface ObservabilityPlugin {\n\treadonly id: string;\n\tquery(filter?: ObservabilityQueryFilterV1): readonly ObservabilityJournalEntryV1[];\n\texplainTrace(traceId: string): ObservabilityTraceTimelineV1;\n\tgetMetrics(options?: ObservabilityMetricsOptions): MetricsSnapshotV1;\n\tstats(): ObservabilityJournalStatsV1;\n\texportProblemReport(input: { readonly sessionId: string; readonly reason: string }): Promise<ProblemReportV1>;\n\t/**\n\t * Receives the finalized provider payload from the host adapter and emits\n\t * one `llm.request` trace record with a bounded redacted snapshot (design\n\t * §4.3). No-op when no trace adapter was injected.\n\t */\n\tcaptureProviderPayload(payload: unknown, model: unknown): void;\n\t/**\n\t * Receives one plugin LoggerAPI record forwarded by the host runtime sink\n\t * (`CapabilityRuntimeOptions.onLogRecord`) and appends a `plugin.log` trace\n\t * record (design §4.2/§7.2). No-op when no trace adapter was injected.\n\t * Must never call `api.logger`: the host forwards logger output here, so\n\t * logging from inside would recurse.\n\t */\n\tmirrorPluginLog(record: LoggerRecord): void;\n\tdispose(): void;\n}\n"]}

package/dist/observability.js

@@ -0,0 +1,33 @@
+/**
+ * Public contracts for the first-party observability plugin (event journal +
+ * problem reports + trace sink). The plugin package
+ * (`@agent-forge/plugin-observability`) is the implementation; this module is
+ * the single authoring authority for its public types and the host-facing
+ * trace adapter contract. The host re-exports the surface from its historical
+ * `plugins/observability-types.ts` path so existing imports keep resolving.
+ *
+ * Contains types only, plus the `TRACE_KINDS_V1` value mirror with its
+ * compile-time drift guards (CLI `--trace-kind` validation consumes the
+ * value).
+ */
+/**
+ * Runtime mirror of `TraceKindV1` for value-level consumers (CLI
+ * `--trace-kind` validation), kept beside the union so the two compile-time
+ * drift guards fail the build when they diverge in either direction:
+ * - the `satisfies` below rejects a list entry the union no longer has;
+ * - `_TRACE_KINDS_EXHAUSTIVE_CHECK` rejects a union member missing from the
+ *   list (`never` is not assignable from `true`).
+ */
+export const TRACE_KINDS_V1 = [
+    "session.start",
+    "turn.span",
+    "llm.request",
+    "llm.response",
+    "tool.span",
+    "lifecycle",
+    "error",
+    "decision",
+    "plugin.log",
+];
+const _TRACE_KINDS_EXHAUSTIVE_CHECK = true;
+//# sourceMappingURL=observability.js.map

package/dist/observability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.js","sourceRoot":"","sources":["../src/observability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAuLH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC7B,eAAe;IACf,WAAW;IACX,aAAa;IACb,cAAc;IACd,WAAW;IACX,WAAW;IACX,OAAO;IACP,UAAU;IACV,YAAY;CAC8B,CAAC;AAG5C,MAAM,6BAA6B,GAAuD,IAAI,CAAC","sourcesContent":["/**\n * Public contracts for the first-party observability plugin (event journal +\n * problem reports + trace sink). The plugin package\n * (`@agent-forge/plugin-observability`) is the implementation; this module is\n * the single authoring authority for its public types and the host-facing\n * trace adapter contract. The host re-exports the surface from its historical\n * `plugins/observability-types.ts` path so existing imports keep resolving.\n *\n * Contains types only, plus the `TRACE_KINDS_V1` value mirror with its\n * compile-time drift guards (CLI `--trace-kind` validation consumes the\n * value).\n */\n\nimport type { LoggerRecord, OutputArtifactRef } from \"./public-api.ts\";\n\nexport type ObservabilityLogLevel = \"info\" | \"warn\" | \"error\";\n\n/**\n * Output projection surface carried by the problem report's whole-document\n * projection. Authority moved from the host's `host/output-serializer.ts`\n * (D-075 S4 second batch); the host re-exports it from there.\n */\nexport type HostOutputSurfaceV1 = \"tui\" | \"cli-text\" | \"inspector\";\n\n/** One bounded-journal record derived from a delivered lifecycle event. */\nexport interface ObservabilityJournalEntryV1 {\n\treadonly sequence: number;\n\treadonly at: number;\n\t/** Session id extracted from the event data; null when the event has none. */\n\treadonly sessionId: string | null;\n\t/** Lifecycle event type, e.g. \"model.stream\" or \"tool.commit\". */\n\treadonly stage: string;\n\treadonly level: ObservabilityLogLevel;\n\t/** Event correlation id, used as the trace grouping key. */\n\treadonly traceId?: string;\n\treadonly summary: string;\n\t/** Validated lifecycle event data, retained verbatim for diagnosis. */\n\treadonly data?: unknown;\n}\n\nexport interface ObservabilityQueryFilterV1 {\n\treadonly sessionId?: string;\n\treadonly stage?: string;\n\treadonly level?: ObservabilityLogLevel;\n\treadonly traceId?: string;\n\t/** When set, returns the most recent `limit` matching entries in order. */\n\treadonly limit?: number;\n}\n\nexport interface ObservabilityTraceStepV1 {\n\treadonly entry: ObservabilityJournalEntryV1;\n\t/** Milliseconds since the previous step; null on the first step. */\n\treadonly durationMs: number | null;\n}\n\nexport interface ObservabilityTraceTimelineV1 {\n\treadonly traceId: string;\n\treadonly steps: readonly ObservabilityTraceStepV1[];\n}\n\nexport interface ObservabilityJournalStatsV1 {\n\treadonly size: number;\n\treadonly dropped: number;\n}\n\nexport interface ObservabilityProblemReportSessionV1 {\n\treadonly sessionId: string;\n\treadonly entryCount: number;\n\treadonly firstSequence: number | null;\n\treadonly lastSequence: number | null;\n}\n\n/** Full error envelope of the most recent error-level entry for the session. */\nexport interface ObservabilityProblemReportErrorV1 {\n\treadonly sequence: number;\n\treadonly at: number;\n\treadonly stage: string;\n\t/** Lifecycle phase when the event carries one (model.stream). */\n\treadonly phase?: string;\n\treadonly traceId: string | null;\n\treadonly code: string;\n\treadonly message: string;\n}\n\nexport interface ObservabilityProblemReportTailEntryV1 {\n\treadonly sequence: number;\n\treadonly at: number;\n\treadonly stage: string;\n\treadonly level: ObservabilityLogLevel;\n\treadonly traceId: string | null;\n\treadonly summary: string;\n\t/**\n\t * Payload rendered through the host output serializer redaction channel;\n\t * internal field keys are replaced at any depth before export.\n\t */\n\treadonly data?: string;\n}\n\nexport interface ObservabilityProblemReportCountsV1 {\n\treadonly byStage: Readonly<Record<string, number>>;\n\treadonly byLevel: Readonly<Record<string, number>>;\n}\n\n/** A metric the journal cannot currently source; the reason names the missing event granularity. */\nexport interface MetricsNotSampledV1 {\n\treadonly status: \"not_sampled\";\n\treadonly reason: string;\n}\n\n/** Cancel-latency samples: delay from a cancel signal to the turn's terminal event. */\nexport interface MetricsCancelLatencySampledV1 {\n\treadonly status: \"sampled\";\n\treadonly count: number;\n\treadonly p50Ms: number | null;\n\treadonly p95Ms: number | null;\n}\n\n/** Token/cost totals summed over usage-bearing journal events. */\nexport interface MetricsTokensSampledV1 {\n\treadonly status: \"sampled\";\n\treadonly totalTokens: number;\n}\n\n/** Memory recall hit rate over `memory_recall` tool executions in the window. */\nexport interface MetricsMemoryRecallSampledV1 {\n\treadonly status: \"sampled\";\n\treadonly calls: number;\n\treadonly hits: number;\n\treadonly hitRate: number;\n}\n\nexport interface MetricsToolErrorsV1 {\n\treadonly calls: number;\n\treadonly errors: number;\n\t/** `null` when no tool executions occurred in the window. */\n\treadonly errorRate: number | null;\n\t/** Errors per tool name, descending by count then ascending by name. */\n\treadonly topErrors: readonly { readonly toolName: string; readonly errors: number }[];\n}\n\nexport interface MetricsTurnsV1 {\n\treadonly count: number;\n\treadonly successCount: number;\n\t/** `null` when no turns occurred in the window. */\n\treadonly successRate: number | null;\n\treadonly p50DurationMs: number | null;\n\treadonly p95DurationMs: number | null;\n}\n\n/** Window metadata: which turns were aggregated and their time span. */\nexport interface MetricsWindowV1 {\n\t/** Requested turn bound; `null` when the whole journal was aggregated. */\n\treadonly windowTurns: number | null;\n\treadonly sampledTurns: number;\n\treadonly firstAt: number | null;\n\treadonly lastAt: number | null;\n}\n\n/**\n * Deterministic product metrics aggregated read-only from the journal ring.\n * Metrics the journal cannot source are reported as `not_sampled` with the\n * reason instead of being fabricated.\n */\nexport interface MetricsSnapshotV1 {\n\treadonly version: 1;\n\treadonly window: MetricsWindowV1;\n\treadonly turns: MetricsTurnsV1;\n\treadonly tools: MetricsToolErrorsV1;\n\treadonly cancelLatencyMs: MetricsCancelLatencySampledV1 | MetricsNotSampledV1;\n\treadonly tokens: MetricsTokensSampledV1 | MetricsNotSampledV1;\n\treadonly memoryRecall: MetricsMemoryRecallSampledV1 | MetricsNotSampledV1;\n}\n\n/** Aggregate options for {@link ObservabilityPlugin.getMetrics}. */\nexport interface ObservabilityMetricsOptions {\n\t/** Aggregate only the most recent `windowTurns` correlationId groups; omit for the whole journal. */\n\treadonly windowTurns?: number;\n}\n\n/**\n * Trace record kinds for `agent-forge/trace.v1`\n * (design: docs/design/会话轨迹与日志设计.md §4.2).\n */\nexport type TraceKindV1 =\n\t| \"session.start\"\n\t| \"turn.span\"\n\t| \"llm.request\"\n\t| \"llm.response\"\n\t| \"tool.span\"\n\t| \"lifecycle\"\n\t| \"error\"\n\t| \"decision\"\n\t| \"plugin.log\";\n\n/**\n * Runtime mirror of `TraceKindV1` for value-level consumers (CLI\n * `--trace-kind` validation), kept beside the union so the two compile-time\n * drift guards fail the build when they diverge in either direction:\n * - the `satisfies` below rejects a list entry the union no longer has;\n * - `_TRACE_KINDS_EXHAUSTIVE_CHECK` rejects a union member missing from the\n *   list (`never` is not assignable from `true`).\n */\nexport const TRACE_KINDS_V1 = [\n\t\"session.start\",\n\t\"turn.span\",\n\t\"llm.request\",\n\t\"llm.response\",\n\t\"tool.span\",\n\t\"lifecycle\",\n\t\"error\",\n\t\"decision\",\n\t\"plugin.log\",\n] as const satisfies readonly TraceKindV1[];\n\ntype TraceKindListV1 = (typeof TRACE_KINDS_V1)[number];\nconst _TRACE_KINDS_EXHAUSTIVE_CHECK: TraceKindV1 extends TraceKindListV1 ? true : never = true;\n\n/** One append-only JSONL trace record (design §4.2). */\nexport interface TraceRecordV1 {\n\treadonly v: 1;\n\treadonly schema: \"agent-forge/trace.v1\";\n\t/** Monotonic sequence within one trace file, starting at 1. */\n\treadonly seq: number;\n\t/** Host timestamp (epoch ms). */\n\treadonly t: number;\n\t/** Duration of a closed span (ms). */\n\treadonly dur?: number;\n\treadonly kind: TraceKindV1;\n\t/** Turn/request correlation id, shared with lifecycle events and logs. */\n\treadonly traceId?: string;\n\treadonly level?: ObservabilityLogLevel;\n\t/** Kind-specific bounded data. */\n\treadonly data?: unknown;\n}\n\n/** Bounds for trace payload snapshots (design §4.3); each field defaults when omitted. */\nexport interface TraceSinkOptionsV1 {\n\t/** Strings longer than this truncate with a `…[truncated N chars]` suffix. Default 16_000. */\n\treadonly maxStringChars?: number;\n\t/**\n\t * Serialized snapshot budget in bytes, enforced largest-string-first inside\n\t * `llm.request.data.payload`. Strictly below the 512 KiB per-record budget.\n\t * Default 393_216 (384 KiB).\n\t */\n\treadonly maxSnapshotBytes?: number;\n\t/**\n\t * OTLP/HTTP+JSON trace export (design §8). Omitted keeps the exporter\n\t * absent: no transport, no buffering, file-sink behavior unchanged. The\n\t * endpoint is the OTLP base URL (e.g. `http://localhost:4318`); the\n\t * `/v1/traces` signal path is appended unless already present.\n\t */\n\treadonly otlp?: OtlpExportOptionsV1;\n}\n\n/** OTLP/HTTP+JSON exporter options; all durations/bounds are deterministic inputs. */\nexport interface OtlpExportOptionsV1 {\n\t/** OTLP base URL; `/v1/traces` is appended unless already present. */\n\treadonly endpoint: string;\n\t/**\n\t * Transport injection for deterministic tests and custom hosts (proxy,\n\t * in-process collector); defaults to `globalThis.fetch`. Only the fields\n\t * below are consumed by the plugin.\n\t */\n\treadonly fetchImpl?: (\n\t\turl: string,\n\t\tinit: { method: \"POST\"; headers: { \"content-type\": string }; body: string; signal: AbortSignal },\n\t) => Promise<{ ok: boolean; status: number }>;\n\t/** Per-flush HTTP timeout in ms. Default 5_000. */\n\treadonly timeoutMs?: number;\n\t/** Buffered-span count that triggers an early flush. Default 64. */\n\treadonly flushThreshold?: number;\n}\n\n/**\n * Telemetry export seam (design §8): the single attachment point for trace\n * exporters (first OTLP/HTTP+JSON; future Prometheus-style pull surfaces hook\n * here instead of growing bespoke taps). Hosts inject sinks through\n * `ObservabilityTraceConfig.exportSinks`; the plugin never reaches into host\n * internals and never lets a sink break event delivery.\n */\nexport interface ObservabilityExportSinkV1 {\n\t/** Called synchronously for every finalized trace record. Must not throw. */\n\treadonly onTraceRecord: (record: TraceRecordV1) => void;\n\t/** Best-effort flush; resolves after the batch is delivered or dropped. */\n\treadonly flush: (reason: string) => Promise<void>;\n}\n\n/**\n * Host-injected adapter for the trace sink (design §4.4). The host closure\n * owns session-path resolution, provider payload capture, and failure\n * reporting; the plugin never reaches into host internals.\n */\nexport interface ObservabilityHostAdapterV1 {\n\t/** Trace file path for the current session, or `null` when tracing is off. */\n\tgetTraceFilePath(): string | null;\n\t/** Host push of the finalized provider payload (sdk `onPayload` tail). */\n\tcaptureProviderPayload(payload: unknown, model: unknown): void;\n\t/** Trace write-failure channel; the host forwards to the process log. */\n\tonSinkFailure(error: unknown): void;\n\t/**\n\t * Correlation id of the turn currently in flight, or `undefined` outside a\n\t * turn. Omitted keeps the phase-1 behavior: `llm.request` and `plugin.log`\n\t * records carry no traceId.\n\t */\n\tgetTurnCorrelationId?(): string | undefined;\n\t/**\n\t * Session-header fact: the parent agent session id recorded at session\n\t * creation (`SessionHeader.parentAgentSession`, session-manager.ts).\n\t * Omitted — or returning `undefined` when the header has no such field —\n\t * keeps the previous behavior: the `session.start` record carries no\n\t * `parentSessionId`.\n\t */\n\tgetParentAgentSessionId?(): string | undefined;\n\t/**\n\t * Session-header fact: the parent-turn correlation id that created this\n\t * session (`SessionHeader.parentTraceId`, session-manager.ts; frozen at\n\t * creation). Omitted — or returning `undefined` — keeps the previous\n\t * behavior: the `session.start` record carries no `parentTraceId`.\n\t */\n\tgetParentTraceId?(): string | undefined;\n\t/**\n\t * Plugin-to-host facade registration (D-075 S4 second batch). The plugin\n\t * entry calls it once after creating the plugin instance so the host's\n\t * assembly refs (provider payload capture, plugin.log mirror, /metrics\n\t * source) keep their embedded-era semantics; calling it again with\n\t * `undefined` on teardown clears them. Omitted on hosts that consume the\n\t * facade through another channel — the entry must probe before calling.\n\t */\n\tregisterFacade?(facade: ObservabilityPluginFacadeV1 | undefined): void;\n}\n\n/**\n * The narrow plugin-facing face the host consumes through\n * {@link ObservabilityHostAdapterV1.registerFacade}. The plugin instance is\n * structurally assignable to it.\n */\nexport interface ObservabilityPluginFacadeV1 {\n\tcaptureProviderPayload(payload: unknown, model: unknown): void;\n\t/** Optional: present since the plugin.log mirror (design §7.2). */\n\tmirrorPluginLog?(record: LoggerRecord): void;\n\tgetMetrics(options?: ObservabilityMetricsOptions): MetricsSnapshotV1;\n}\n\n/** Deterministic problem report; `reportId` is FNV-1a-32 hex over the canonical JSON of the report body. */\nexport interface ProblemReportV1 {\n\treadonly version: 1;\n\treadonly reportId: string;\n\treadonly createdAt: number;\n\treadonly reason: string;\n\treadonly session: ObservabilityProblemReportSessionV1;\n\treadonly lastError: ObservabilityProblemReportErrorV1 | null;\n\treadonly journalTail: readonly ObservabilityProblemReportTailEntryV1[];\n\treadonly counts: ObservabilityProblemReportCountsV1;\n\treadonly dropped: number;\n\treadonly redactionApplied: boolean;\n\t/** Whole-report projection rendered by the host output serializer. */\n\treadonly projection: {\n\t\treadonly surface: HostOutputSurfaceV1;\n\t\treadonly text: string;\n\t};\n\t/** Present only when the host declared the `output-artifacts` feature. */\n\treadonly artifact?: OutputArtifactRef;\n}\n\n/**\n * The observability plugin's public behavior face (journal read side, trace\n * explanation, deterministic metrics, problem-report export). The plugin\n * package returns this shape from its factory; hosts consume it through\n * {@link ObservabilityPluginFacadeV1} or their own references.\n */\nexport interface ObservabilityPlugin {\n\treadonly id: string;\n\tquery(filter?: ObservabilityQueryFilterV1): readonly ObservabilityJournalEntryV1[];\n\texplainTrace(traceId: string): ObservabilityTraceTimelineV1;\n\tgetMetrics(options?: ObservabilityMetricsOptions): MetricsSnapshotV1;\n\tstats(): ObservabilityJournalStatsV1;\n\texportProblemReport(input: { readonly sessionId: string; readonly reason: string }): Promise<ProblemReportV1>;\n\t/**\n\t * Receives the finalized provider payload from the host adapter and emits\n\t * one `llm.request` trace record with a bounded redacted snapshot (design\n\t * §4.3). No-op when no trace adapter was injected.\n\t */\n\tcaptureProviderPayload(payload: unknown, model: unknown): void;\n\t/**\n\t * Receives one plugin LoggerAPI record forwarded by the host runtime sink\n\t * (`CapabilityRuntimeOptions.onLogRecord`) and appends a `plugin.log` trace\n\t * record (design §4.2/§7.2). No-op when no trace adapter was injected.\n\t * Must never call `api.logger`: the host forwards logger output here, so\n\t * logging from inside would recurse.\n\t */\n\tmirrorPluginLog(record: LoggerRecord): void;\n\tdispose(): void;\n}\n"]}

package/dist/operation.d.ts

@@ -0,0 +1,60 @@
+import { type ArtifactRefV1 } from "./artifact.ts";
+import { type JsonValue } from "./common.ts";
+export type PluginOperationStatusV1 = "queued" | "running" | "succeeded" | "failed" | "cancelled" | "needs_user" | "unsupported";
+export declare const PLUGIN_OPERATION_TERMINAL_STATUSES_V1: readonly PluginOperationStatusV1[];
+export interface PluginOperationV1 {
+    readonly version: 1;
+    readonly operationId: string;
+    readonly pluginId: string;
+    readonly kind: string;
+    readonly status: PluginOperationStatusV1;
+    readonly inputArtifacts?: readonly ArtifactRefV1[];
+    readonly outputArtifacts?: readonly ArtifactRefV1[];
+    readonly startedAt?: string;
+    readonly endedAt?: string;
+}
+export type EvidenceKindV1 = "screenshot" | "dom" | "render" | "diff" | "log" | "assertion" | "trace" | "network" | "structure";
+export interface EvidenceRefV1 {
+    readonly version: 1;
+    readonly evidenceId: string;
+    readonly kind: EvidenceKindV1;
+    readonly operationId: string;
+    readonly artifactRef?: ArtifactRefV1;
+    readonly summary?: string;
+    readonly observedAt?: string;
+}
+export interface VerificationV1 {
+    readonly version: 1;
+    readonly status: "passed" | "failed" | "unknown";
+    readonly checks: readonly string[];
+}
+export interface PluginErrorV1 {
+    readonly version: 1;
+    readonly code: string;
+    readonly message: string;
+    readonly causeCode?: string;
+    readonly diagnosticRef?: ArtifactRefV1;
+}
+export type PluginResultStatusV1 = Exclude<PluginOperationStatusV1, "queued" | "running">;
+export interface PluginResultV1 {
+    readonly version: 1;
+    readonly operationId: string;
+    readonly status: PluginResultStatusV1;
+    readonly summary: string;
+    readonly artifacts: readonly ArtifactRefV1[];
+    readonly evidence: readonly EvidenceRefV1[];
+    readonly verification?: VerificationV1;
+    readonly error?: PluginErrorV1;
+}
+export declare function validatePluginOperationV1(value: unknown, label?: string): PluginOperationV1;
+export declare function buildPluginOperationV1(input: PluginOperationV1): PluginOperationV1;
+export declare function validateEvidenceRefV1(value: unknown, label?: string): EvidenceRefV1;
+export declare function buildEvidenceRefV1(input: EvidenceRefV1): EvidenceRefV1;
+export declare function validateVerificationV1(value: unknown, label?: string): VerificationV1;
+export declare function buildVerificationV1(input: VerificationV1): VerificationV1;
+export declare function validatePluginErrorV1(value: unknown, label?: string): PluginErrorV1;
+export declare function buildPluginErrorV1(input: PluginErrorV1): PluginErrorV1;
+export declare function validatePluginResultV1(value: unknown, label?: string): PluginResultV1;
+export declare function buildPluginResultV1(input: PluginResultV1): PluginResultV1;
+export declare function assertJsonResultInputV1(value: unknown, label?: string): JsonValue;
+//# sourceMappingURL=operation.d.ts.map

package/dist/operation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation.d.ts","sourceRoot":"","sources":["../src/operation.ts"],"names":[],"mappings":"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","sourcesContent":["import { type ArtifactRefV1, validateArtifactRefV1 } from \"./artifact.ts\";\nimport {\n\tassertExactKeys,\n\tassertJsonValue,\n\tassertNonEmptyString,\n\tassertOptionalString,\n\tassertPlainRecord,\n\tdetachedFreeze,\n\ttype JsonValue,\n\tsortByKey,\n} from \"./common.ts\";\n\nexport type PluginOperationStatusV1 =\n\t| \"queued\"\n\t| \"running\"\n\t| \"succeeded\"\n\t| \"failed\"\n\t| \"cancelled\"\n\t| \"needs_user\"\n\t| \"unsupported\";\n\nexport const PLUGIN_OPERATION_TERMINAL_STATUSES_V1: readonly PluginOperationStatusV1[] = [\n\t\"succeeded\",\n\t\"failed\",\n\t\"cancelled\",\n\t\"needs_user\",\n\t\"unsupported\",\n];\n\nexport interface PluginOperationV1 {\n\treadonly version: 1;\n\treadonly operationId: string;\n\treadonly pluginId: string;\n\treadonly kind: string;\n\treadonly status: PluginOperationStatusV1;\n\treadonly inputArtifacts?: readonly ArtifactRefV1[];\n\treadonly outputArtifacts?: readonly ArtifactRefV1[];\n\treadonly startedAt?: string;\n\treadonly endedAt?: string;\n}\n\nexport type EvidenceKindV1 =\n\t| \"screenshot\"\n\t| \"dom\"\n\t| \"render\"\n\t| \"diff\"\n\t| \"log\"\n\t| \"assertion\"\n\t| \"trace\"\n\t| \"network\"\n\t| \"structure\";\n\nexport interface EvidenceRefV1 {\n\treadonly version: 1;\n\treadonly evidenceId: string;\n\treadonly kind: EvidenceKindV1;\n\treadonly operationId: string;\n\treadonly artifactRef?: ArtifactRefV1;\n\treadonly summary?: string;\n\treadonly observedAt?: string;\n}\n\nexport interface VerificationV1 {\n\treadonly version: 1;\n\treadonly status: \"passed\" | \"failed\" | \"unknown\";\n\treadonly checks: readonly string[];\n}\n\nexport interface PluginErrorV1 {\n\treadonly version: 1;\n\treadonly code: string;\n\treadonly message: string;\n\treadonly causeCode?: string;\n\treadonly diagnosticRef?: ArtifactRefV1;\n}\n\nexport type PluginResultStatusV1 = Exclude<PluginOperationStatusV1, \"queued\" | \"running\">;\n\nexport interface PluginResultV1 {\n\treadonly version: 1;\n\treadonly operationId: string;\n\treadonly status: PluginResultStatusV1;\n\treadonly summary: string;\n\treadonly artifacts: readonly ArtifactRefV1[];\n\treadonly evidence: readonly EvidenceRefV1[];\n\treadonly verification?: VerificationV1;\n\treadonly error?: PluginErrorV1;\n}\n\nconst EVIDENCE_KINDS_V1: readonly EvidenceKindV1[] = [\n\t\"screenshot\",\n\t\"dom\",\n\t\"render\",\n\t\"diff\",\n\t\"log\",\n\t\"assertion\",\n\t\"trace\",\n\t\"network\",\n\t\"structure\",\n];\nconst OPERATION_STATUSES_V1: readonly PluginOperationStatusV1[] = [\n\t\"queued\",\n\t\"running\",\n\t\"succeeded\",\n\t\"failed\",\n\t\"cancelled\",\n\t\"needs_user\",\n\t\"unsupported\",\n];\nconst RESULT_STATUSES_V1: readonly PluginResultStatusV1[] = [\n\t\"succeeded\",\n\t\"failed\",\n\t\"cancelled\",\n\t\"needs_user\",\n\t\"unsupported\",\n];\n\nfunction validateStatus(value: unknown, label: string, values: readonly string[]): string {\n\tif (typeof value !== \"string\" || !values.includes(value)) throw new Error(`${label} is invalid`);\n\treturn value;\n}\n\nfunction validateIsoLike(value: unknown, label: string): string | undefined {\n\tif (value === undefined) return undefined;\n\tassertNonEmptyString(value, label);\n\treturn value;\n}\n\nfunction validateArtifactArray(value: unknown, label: string): readonly ArtifactRefV1[] {\n\tif (!Array.isArray(value)) throw new Error(`${label} must be an array`);\n\tconst result = value.map((item, index) => validateArtifactRefV1(item, `${label}[${index}]`));\n\tif (new Set(result.map((item) => item.artifactRef)).size !== result.length) {\n\t\tthrow new Error(`${label} must not contain duplicate artifactRef values`);\n\t}\n\treturn Object.freeze(sortByKey(result, (item) => item.artifactRef));\n}\n\nexport function validatePluginOperationV1(value: unknown, label = \"Plugin operation\"): PluginOperationV1 {\n\tassertPlainRecord(value, label);\n\tassertExactKeys(\n\t\tvalue,\n\t\t[\"version\", \"operationId\", \"pluginId\", \"kind\", \"status\"],\n\t\t[\"inputArtifacts\", \"outputArtifacts\", \"startedAt\", \"endedAt\"],\n\t\tlabel,\n\t);\n\tif (value.version !== 1) throw new Error(`${label}.version must be 1`);\n\tassertNonEmptyString(value.operationId, `${label}.operationId`);\n\tassertNonEmptyString(value.pluginId, `${label}.pluginId`);\n\tassertNonEmptyString(value.kind, `${label}.kind`);\n\tconst status = validateStatus(value.status, `${label}.status`, OPERATION_STATUSES_V1) as PluginOperationStatusV1;\n\tconst inputArtifacts =\n\t\tvalue.inputArtifacts === undefined\n\t\t\t? undefined\n\t\t\t: validateArtifactArray(value.inputArtifacts, `${label}.inputArtifacts`);\n\tconst outputArtifacts =\n\t\tvalue.outputArtifacts === undefined\n\t\t\t? undefined\n\t\t\t: validateArtifactArray(value.outputArtifacts, `${label}.outputArtifacts`);\n\tconst startedAt = validateIsoLike(value.startedAt, `${label}.startedAt`);\n\tconst endedAt = validateIsoLike(value.endedAt, `${label}.endedAt`);\n\tif (endedAt !== undefined && startedAt === undefined) throw new Error(`${label}.endedAt requires startedAt`);\n\tif (status === \"running\" && endedAt !== undefined) throw new Error(`${label}.running must not have endedAt`);\n\treturn detachedFreeze({\n\t\tversion: 1,\n\t\toperationId: value.operationId,\n\t\tpluginId: value.pluginId,\n\t\tkind: value.kind,\n\t\tstatus,\n\t\t...(inputArtifacts === undefined ? {} : { inputArtifacts }),\n\t\t...(outputArtifacts === undefined ? {} : { outputArtifacts }),\n\t\t...(startedAt === undefined ? {} : { startedAt }),\n\t\t...(endedAt === undefined ? {} : { endedAt }),\n\t});\n}\n\nexport function buildPluginOperationV1(input: PluginOperationV1): PluginOperationV1 {\n\treturn validatePluginOperationV1(input);\n}\n\nexport function validateEvidenceRefV1(value: unknown, label = \"Evidence reference\"): EvidenceRefV1 {\n\tassertPlainRecord(value, label);\n\tassertExactKeys(\n\t\tvalue,\n\t\t[\"version\", \"evidenceId\", \"kind\", \"operationId\"],\n\t\t[\"artifactRef\", \"summary\", \"observedAt\"],\n\t\tlabel,\n\t);\n\tif (value.version !== 1) throw new Error(`${label}.version must be 1`);\n\tassertNonEmptyString(value.evidenceId, `${label}.evidenceId`);\n\tconst kind = validateStatus(value.kind, `${label}.kind`, EVIDENCE_KINDS_V1) as EvidenceKindV1;\n\tassertNonEmptyString(value.operationId, `${label}.operationId`);\n\tconst artifactRef =\n\t\tvalue.artifactRef === undefined ? undefined : validateArtifactRefV1(value.artifactRef, `${label}.artifactRef`);\n\tassertOptionalString(value.summary, `${label}.summary`);\n\tconst observedAt = validateIsoLike(value.observedAt, `${label}.observedAt`);\n\treturn detachedFreeze({\n\t\tversion: 1,\n\t\tevidenceId: value.evidenceId,\n\t\tkind,\n\t\toperationId: value.operationId,\n\t\t...(artifactRef === undefined ? {} : { artifactRef }),\n\t\t...(value.summary === undefined ? {} : { summary: value.summary }),\n\t\t...(observedAt === undefined ? {} : { observedAt }),\n\t});\n}\n\nexport function buildEvidenceRefV1(input: EvidenceRefV1): EvidenceRefV1 {\n\treturn validateEvidenceRefV1(input);\n}\n\nexport function validateVerificationV1(value: unknown, label = \"Verification\"): VerificationV1 {\n\tassertPlainRecord(value, label);\n\tassertExactKeys(value, [\"version\", \"status\", \"checks\"], [], label);\n\tif (value.version !== 1) throw new Error(`${label}.version must be 1`);\n\tconst status = validateStatus(value.status, `${label}.status`, [\n\t\t\"passed\",\n\t\t\"failed\",\n\t\t\"unknown\",\n\t]) as VerificationV1[\"status\"];\n\tif (!Array.isArray(value.checks) || value.checks.some((item) => typeof item !== \"string\" || item.trim() === \"\")) {\n\t\tthrow new Error(`${label}.checks must contain non-empty strings`);\n\t}\n\tif (new Set(value.checks).size !== value.checks.length)\n\t\tthrow new Error(`${label}.checks must not contain duplicates`);\n\treturn detachedFreeze({ version: 1, status, checks: [...value.checks].sort() });\n}\n\nexport function buildVerificationV1(input: VerificationV1): VerificationV1 {\n\treturn validateVerificationV1(input);\n}\n\nexport function validatePluginErrorV1(value: unknown, label = \"Plugin error\"): PluginErrorV1 {\n\tassertPlainRecord(value, label);\n\tassertExactKeys(value, [\"version\", \"code\", \"message\"], [\"causeCode\", \"diagnosticRef\"], label);\n\tif (value.version !== 1) throw new Error(`${label}.version must be 1`);\n\tassertNonEmptyString(value.code, `${label}.code`);\n\tassertNonEmptyString(value.message, `${label}.message`);\n\tassertOptionalString(value.causeCode, `${label}.causeCode`);\n\tconst diagnosticRef =\n\t\tvalue.diagnosticRef === undefined\n\t\t\t? undefined\n\t\t\t: validateArtifactRefV1(value.diagnosticRef, `${label}.diagnosticRef`);\n\treturn detachedFreeze({\n\t\tversion: 1,\n\t\tcode: value.code,\n\t\tmessage: value.message,\n\t\t...(value.causeCode === undefined ? {} : { causeCode: value.causeCode }),\n\t\t...(diagnosticRef === undefined ? {} : { diagnosticRef }),\n\t});\n}\n\nexport function buildPluginErrorV1(input: PluginErrorV1): PluginErrorV1 {\n\treturn validatePluginErrorV1(input);\n}\n\nexport function validatePluginResultV1(value: unknown, label = \"Plugin result\"): PluginResultV1 {\n\tassertPlainRecord(value, label);\n\tassertExactKeys(\n\t\tvalue,\n\t\t[\"version\", \"operationId\", \"status\", \"summary\", \"artifacts\", \"evidence\"],\n\t\t[\"verification\", \"error\"],\n\t\tlabel,\n\t);\n\tif (value.version !== 1) throw new Error(`${label}.version must be 1`);\n\tassertNonEmptyString(value.operationId, `${label}.operationId`);\n\tconst status = validateStatus(value.status, `${label}.status`, RESULT_STATUSES_V1) as PluginResultStatusV1;\n\tassertNonEmptyString(value.summary, `${label}.summary`);\n\tconst artifacts = validateArtifactArray(value.artifacts, `${label}.artifacts`);\n\tif (!Array.isArray(value.evidence)) throw new Error(`${label}.evidence must be an array`);\n\tconst evidence = value.evidence.map((item, index) => validateEvidenceRefV1(item, `${label}.evidence[${index}]`));\n\tif (new Set(evidence.map((item) => item.evidenceId)).size !== evidence.length)\n\t\tthrow new Error(`${label}.evidence must not contain duplicate evidenceId values`);\n\tconst orderedEvidence = Object.freeze(sortByKey(evidence, (item) => item.evidenceId));\n\tconst verification =\n\t\tvalue.verification === undefined\n\t\t\t? undefined\n\t\t\t: validateVerificationV1(value.verification, `${label}.verification`);\n\tconst error = value.error === undefined ? undefined : validatePluginErrorV1(value.error, `${label}.error`);\n\tif (status !== \"succeeded\" && error === undefined)\n\t\tthrow new Error(`${label}.error is required for status ${status}`);\n\tif (status === \"succeeded\" && error !== undefined) throw new Error(`${label}.succeeded must not include error`);\n\tif (status === \"succeeded\" && verification?.status === \"failed\")\n\t\tthrow new Error(`${label}.succeeded cannot have failed verification`);\n\treturn detachedFreeze({\n\t\tversion: 1,\n\t\toperationId: value.operationId,\n\t\tstatus,\n\t\tsummary: value.summary,\n\t\tartifacts,\n\t\tevidence: orderedEvidence,\n\t\t...(verification === undefined ? {} : { verification }),\n\t\t...(error === undefined ? {} : { error }),\n\t});\n}\n\nexport function buildPluginResultV1(input: PluginResultV1): PluginResultV1 {\n\treturn validatePluginResultV1(input);\n}\n\nexport function assertJsonResultInputV1(value: unknown, label = \"Result input\"): JsonValue {\n\tassertJsonValue(value, label);\n\treturn detachedFreeze(value);\n}\n"]}