@purista/harness 1.0.0 → 1.1.0

package/dist/sessions/index.js

@@ -1,55 +1,16 @@
-import { z } from 'zod';
-import { InternalError, OperationCancelledError, OperationTimeoutError, HarnessError, SessionBusyError, StateError, ValidationError, WorkflowNotFoundError, serializeError } from '../errors/index.js';
+import { InternalError, OperationCancelledError, OperationTimeoutError, HarnessError, SessionBusyError, ValidationError, serializeError } from '../errors/index.js';
 import { ulid } from '../ulid/index.js';
 import { runDefaultAgent } from '../agents/index.js';
 import { runWorkflow } from '../workflows/index.js';
+import { createMemoryFacade, createSessionMemory } from '../ports/memory.js';
 import { loadSkillsSync } from '../skills/index.js';
 import { createModelRegistry } from '../models/registry.js';
-import { createTelemetryShim } from '../telemetry/index.js';
+import { createMetrics, createTelemetryShim } from '../telemetry/index.js';
 import { createMcpRunnerRegistry } from '../tools/mcp/runner.js';
-const MEMORY_KEY_PATTERN = /^[A-Za-z0-9_.\-:]{1,256}$/;
+const NEVER_ABORT_SIGNAL = new AbortController().signal;
 function now() {
     return new Date().toISOString();
 }
-function makeMemory(sessionId, sandboxSession) {
-    return {
-        async read(key) {
-            validateMemoryKey(key);
-            const path = `/memory/${key}.json`;
-            if (!(await sandboxSession.exists(path))) {
-                return undefined;
-            }
-            return JSON.parse(await sandboxSession.readText(path));
-        },
-        async write(key, value) {
-            validateMemoryKey(key);
-            let encoded;
-            try {
-                encoded = JSON.stringify(value);
-            }
-            catch (error) {
-                throw new ValidationError('Memory value must be JSON-serializable.', { where: 'memory_value', issues: { key } }, error);
-            }
-            await sandboxSession.write(`/memory/${key}.json`, encoded);
-        },
-        async delete(key) {
-            validateMemoryKey(key);
-            await sandboxSession.remove(`/memory/${key}.json`).catch(() => undefined);
-        },
-        async list() {
-            const entries = await sandboxSession.list('/memory').catch(() => []);
-            return entries
-                .filter((entry) => entry.kind === 'file' && entry.name.endsWith('.json'))
-                .map((entry) => entry.name.slice(0, -5))
-                .sort();
-        }
-    };
-}
-function validateMemoryKey(key) {
-    if (!MEMORY_KEY_PATTERN.test(key)) {
-        throw new ValidationError('Invalid session memory key.', { where: 'memory_key', issues: { key } });
-    }
-}
 function validateInvokeOptions(opts) {
     if (opts?.historyWindow !== undefined && opts.historyWindow < 0) {
         throw new ValidationError('Invoke options are invalid.', { where: 'invoke_options', issues: { historyWindow: opts.historyWindow } });
@@ -69,11 +30,15 @@ function normalizeMessage(message, sessionId) {
 export function createSessionHarness(definition) {
     const resolvedSkills = loadSkillsSync(definition.skills);
     const sessionStates = new Map();
-    const telemetry = definition.telemetryShim ?? createTelemetryShim();
+    const contentCaptureMode = resolveContentCaptureMode(definition.telemetry);
+    const telemetry = withTelemetryFlavor(definition.telemetryShim ?? createTelemetryShim(), definition.telemetry);
+    const adapterMetrics = createMetrics(telemetry, { 'harness.name': definition.name });
     const adapterContext = {
         harnessName: definition.name,
         logger: definition.logger,
         telemetry,
+        metrics: adapterMetrics,
+        contentCaptureMode,
         defaults: {
             agentMaxIterations: definition.defaults.agentMaxIterations ?? 16,
             runTimeoutMs: definition.defaults.runTimeoutMs ?? 600_000,
@@ -83,10 +48,9 @@ export function createSessionHarness(definition) {
             ...(definition.defaults.historyWindow !== undefined ? { historyWindow: definition.defaults.historyWindow } : {})
         }
     };
-    configureHarnessAdapters(adapterContext, definition.models, definition.state, definition.sandbox, definition.tools);
+    configureHarnessAdapters(adapterContext, definition.models, definition.state, definition.sandbox, definition.memory, definition.tools);
     const modelRegistry = createModelRegistry(definition.models, { telemetry, harnessName: definition.name });
     const mcpRegistry = createMcpRunnerRegistry();
-    const captureContent = definition.telemetry?.captureContent === true;
     async function ensureSessionRecord(sessionId) {
         const existing = await definition.state.getSession(sessionId);
         if (existing) {
@@ -120,6 +84,63 @@ export function createSessionHarness(definition) {
             definition.logger.error('Failed to persist run events.', { harness: definition.name, run_id: runId, error: serializeError(error) });
         }
     }
+    async function getRunSummary(runId) {
+        const run = await definition.state.getRun(runId);
+        if (!run)
+            return undefined;
+        const events = await definition.state.listEvents(runId);
+        const tokenTotals = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+        let modelCalls = 0;
+        let toolCalls = 0;
+        let agentCalls = 0;
+        for (const event of events) {
+            if (event.type === 'agent.started')
+                agentCalls += 1;
+            if (event.type === 'tool.started')
+                toolCalls += 1;
+            if (event.type.startsWith('model.') && event.type.endsWith('.completed'))
+                modelCalls += 1;
+            if (event.type === 'model.object')
+                modelCalls += 1;
+            const payload = event.payload;
+            if (isJsonRecord(payload) && isTokenUsage(payload['usage'])) {
+                tokenTotals.inputTokens += payload['usage'].inputTokens;
+                tokenTotals.outputTokens += payload['usage'].outputTokens;
+                tokenTotals.totalTokens += payload['usage'].totalTokens;
+            }
+        }
+        return {
+            runId: run.id,
+            sessionId: run.sessionId,
+            status: run.status,
+            startedAt: run.startedAt,
+            ...(run.finishedAt ? { finishedAt: run.finishedAt } : {}),
+            tokenTotals,
+            modelCalls,
+            toolCalls,
+            agentCalls,
+            ...(run.error ? { error: normalizeSerializedRunError(run.error) } : {})
+        };
+    }
+    function memoryOptions(sessionId, sandboxSession, signal, opts = {}) {
+        return {
+            adapter: definition.memory,
+            logger: definition.logger,
+            telemetry,
+            contentCaptureMode,
+            signal,
+            sandbox: sandboxSession,
+            harnessName: definition.name,
+            sessionId,
+            ...(opts.runId ? { runId: opts.runId } : {}),
+            ...(opts.agentId ? { agentId: opts.agentId } : {}),
+            ...(opts.workflowId ? { workflowId: opts.workflowId } : {}),
+            metadata: opts.metadata ?? {}
+        };
+    }
+    function memoryFacade(opts) {
+        return createMemoryFacade(memoryOptions(opts.sessionId, opts.sandboxSession, opts.signal, opts));
+    }
     return {
         inspect() {
             return definition.inspection;
@@ -127,7 +148,7 @@ export function createSessionHarness(definition) {
         async getSession(sessionId) {
             await ensureSessionRecord(sessionId);
             const state = await getSessionState(sessionId);
-            const memory = makeMemory(sessionId, state.sandboxSession);
+            const memory = createSessionMemory(memoryOptions(sessionId, state.sandboxSession, NEVER_ABORT_SIGNAL), { kind: 'session', sessionId });
             const workflowEntries = Object.entries(definition.workflows).map(([workflowId, workflow]) => {
                 const invoker = {
                     prompt: (input, opts) => runWorkflowCall(sessionId, workflowId, workflow, input, opts),
@@ -160,6 +181,9 @@ export function createSessionHarness(definition) {
                 history: {
                     list: (opts) => definition.state.listMessages(sessionId, opts)
                 },
+                async getRunSummary(runId) {
+                    return getRunSummary(runId);
+                },
                 async clearHistory() {
                     if (state.busy) {
                         throw new SessionBusyError('Session is busy.', { session_id: sessionId, reason: 'history_clear_during_run' });
@@ -213,6 +237,12 @@ export function createSessionHarness(definition) {
             catch (error) {
                 errors.push(error instanceof HarnessError ? error : new InternalError('Failed to close state store.', undefined, error));
             }
+            try {
+                await definition.memory.close?.();
+            }
+            catch (error) {
+                errors.push(error instanceof HarnessError ? error : new InternalError('Failed to close memory adapter.', undefined, error));
+            }
             return { errors };
         },
         $infer: {}
@@ -268,13 +298,20 @@ export function createSessionHarness(definition) {
         }
         const runSignal = createRunSignal(opts?.signal, opts?.timeoutMs ?? definition.defaults.runTimeoutMs);
         const state = await getSessionState(sessionId);
-        const memory = makeMemory(sessionId, state.sandboxSession);
         if (state.busy) {
             throw new SessionBusyError('Session is busy.', { session_id: sessionId, reason: 'concurrent_run' });
         }
         state.busy = true;
         const startedAt = now();
         const runId = ulid();
+        const memory = memoryFacade({
+            sessionId,
+            runId,
+            agentId,
+            signal: runSignal.signal,
+            sandboxSession: state.sandboxSession,
+            metadata: opts?.metadata ?? {}
+        });
         const runRecord = {
             id: runId,
             sessionId,
@@ -287,7 +324,7 @@ export function createSessionHarness(definition) {
         const emit = async (event) => {
             const eventAt = 'at' in event ? event.at : now();
             await onEvent?.(event);
-            await appendEvents(runId, [{ id: ulid(), runId, at: eventAt, type: event.type, payload: sanitizeEventForPersistence(event, captureContent) }]);
+            await appendEvents(runId, [{ id: ulid(), runId, at: eventAt, type: event.type, payload: sanitizeEventForPersistence(event) }]);
         };
         try {
             await definition.state.createRun(runRecord);
@@ -297,11 +334,13 @@ export function createSessionHarness(definition) {
             throw error;
         }
         try {
-            const result = await telemetry.span('harness.session.agent_prompt', {
+            const result = await withIncomingTraceContext(telemetry, opts, definition.logger, async () => telemetry.span('harness.session.agent_prompt', {
                 'harness.name': definition.name,
                 'harness.session.id': sessionId,
                 'harness.run.id': runId,
-                'harness.agent.id': agentId
+                'harness.agent.id': agentId,
+                'harness.telemetry.content_capture_mode': contentCaptureMode,
+                ...metadataSpanAttrs(opts?.metadata)
             }, async () => {
                 await emit({ type: 'run.started', runId, at: startedAt });
                 const resolvedHistoryWindow = opts?.historyWindow ?? definition.defaults.historyWindow;
@@ -326,13 +365,14 @@ export function createSessionHarness(definition) {
                     toolTimeoutMs: definition.defaults.toolTimeoutMs ?? 120_000,
                     logger: definition.logger,
                     telemetry,
-                    emitEvent: emit
+                    emitEvent: emit,
+                    metadata: opts?.metadata ?? {}
                 });
                 if (run.emitted.length > 0) {
                     await definition.state.appendMessages(sessionId, run.emitted);
                 }
                 return run.output;
-            });
+            }));
             const finishedAt = now();
             await emit({ type: 'run.finished', runId, at: finishedAt, output: result });
             await definition.state.finishRun(runId, { status: 'succeeded', finishedAt, output: result });
@@ -428,13 +468,20 @@ export function createSessionHarness(definition) {
         }
         const runSignal = createRunSignal(opts?.signal, opts?.timeoutMs ?? definition.defaults.runTimeoutMs);
         const state = await getSessionState(sessionId);
-        const memory = makeMemory(sessionId, state.sandboxSession);
         if (state.busy) {
             throw new SessionBusyError('Session is busy.', { session_id: sessionId, reason: 'concurrent_run' });
         }
         state.busy = true;
         const startedAt = now();
         const runId = ulid();
+        const memory = memoryFacade({
+            sessionId,
+            runId,
+            workflowId,
+            signal: runSignal.signal,
+            sandboxSession: state.sandboxSession,
+            metadata: opts?.metadata ?? {}
+        });
         const runRecord = {
             id: runId,
             sessionId,
@@ -447,7 +494,7 @@ export function createSessionHarness(definition) {
         const emit = async (event) => {
             const eventAt = 'at' in event ? event.at : now();
             await onEvent?.(event);
-            await appendEvents(runId, [{ id: ulid(), runId, at: eventAt, type: event.type, payload: sanitizeEventForPersistence(event, captureContent) }]);
+            await appendEvents(runId, [{ id: ulid(), runId, at: eventAt, type: event.type, payload: sanitizeEventForPersistence(event) }]);
         };
         try {
             await definition.state.createRun(runRecord);
@@ -457,14 +504,22 @@ export function createSessionHarness(definition) {
             throw error;
         }
         try {
-            const result = await telemetry.span('harness.session.prompt', {
+            const result = await withIncomingTraceContext(telemetry, opts, definition.logger, async () => telemetry.span('harness.session.prompt', {
                 'harness.name': definition.name,
                 'harness.session.id': sessionId,
                 'harness.run.id': runId,
-                'harness.workflow.id': workflowId
+                'harness.workflow.id': workflowId,
+                'harness.telemetry.content_capture_mode': contentCaptureMode,
+                ...metadataSpanAttrs(opts?.metadata)
             }, async () => {
                 const runStarted = { type: 'run.started', runId, at: startedAt };
                 await emit(runStarted);
+                const workflowMetrics = createMetrics(telemetry, {
+                    'harness.name': definition.name,
+                    'harness.session.id': sessionId,
+                    'harness.run.id': runId,
+                    'harness.workflow.id': workflowId
+                });
                 const workflowArgs = {
                     workflowId,
                     workflow,
@@ -474,12 +529,25 @@ export function createSessionHarness(definition) {
                         runId,
                         sessionId,
                         models: modelRegistry,
+                        metadata: opts?.metadata ?? {},
+                        metrics: workflowMetrics,
+                        memory,
                         agents: Object.fromEntries(Object.entries(definition.agents).map(([agentId, agent]) => [
                             agentId,
                             async (agentInput, agentOpts) => {
                                 const agentSignal = combineSignals(runSignal.signal, agentOpts?.signal);
                                 try {
                                     const resolvedHistoryWindow = agentOpts?.historyWindow ?? opts?.historyWindow ?? definition.defaults.historyWindow;
+                                    const agentMetadata = { ...(opts?.metadata ?? {}), ...(agentOpts?.metadata ?? {}) };
+                                    const agentMemory = memoryFacade({
+                                        sessionId,
+                                        runId,
+                                        workflowId,
+                                        agentId,
+                                        signal: agentSignal.signal,
+                                        sandboxSession: state.sandboxSession,
+                                        metadata: agentMetadata
+                                    });
                                     const run = await runDefaultAgent({
                                         harnessName: definition.name,
                                         agentId,
@@ -494,7 +562,7 @@ export function createSessionHarness(definition) {
                                         customTools: definition.tools,
                                         mcpRegistry,
                                         session: state.sandboxSession,
-                                        memory,
+                                        memory: agentMemory,
                                         mountedSkills: state.mountedSkills,
                                         ...(resolvedHistoryWindow !== undefined ? { historyWindow: resolvedHistoryWindow } : {}),
                                         maxSteps: definition.defaults.agentMaxIterations ?? 16,
@@ -502,7 +570,8 @@ export function createSessionHarness(definition) {
                                         toolTimeoutMs: definition.defaults.toolTimeoutMs ?? 120_000,
                                         logger: definition.logger,
                                         telemetry,
-                                        emitEvent: emit
+                                        emitEvent: emit,
+                                        metadata: agentMetadata
                                     });
                                     if (run.emitted.length > 0) {
                                         await definition.state.appendMessages(sessionId, run.emitted);
@@ -520,12 +589,13 @@ export function createSessionHarness(definition) {
                     'harness.name': definition.name,
                     'harness.session.id': sessionId,
                     'harness.run.id': runId,
-                    'harness.workflow.id': workflowId
+                    'harness.workflow.id': workflowId,
+                    ...metadataSpanAttrs(opts?.metadata)
                 }, async () => runWorkflow({
                     ...workflowArgs,
                     ...(opts ? { opts: { ...opts, signal: runSignal.signal } } : { opts: { signal: runSignal.signal } })
                 }));
-            });
+            }));
             const finishedAt = now();
             const runFinished = { type: 'run.finished', runId, at: finishedAt, output: result };
             await emit(runFinished);
@@ -598,13 +668,14 @@ export function createSessionHarness(definition) {
         }
     }
 }
-function configureHarnessAdapters(context, models, state, sandbox, tools) {
+function configureHarnessAdapters(context, models, state, sandbox, memory, tools) {
     const seen = new Set();
     for (const alias of Object.values(models)) {
         configureOne(alias.provider, context, seen);
     }
     configureOne(state, context, seen);
     configureOne(sandbox, context, seen);
+    configureOne(memory, context, seen);
     for (const tool of Object.values(tools)) {
         configureOne(tool, context, seen);
     }
@@ -616,6 +687,124 @@ function configureOne(adapter, context, seen) {
     configurable.configureHarnessContext(context);
     seen.add(adapter);
 }
+function withTelemetryFlavor(telemetry, options) {
+    const flavor = options?.flavor ?? process.env['PURISTA_TELEMETRY_FLAVOR'] ?? 'dual';
+    if (flavor === 'dual')
+        return telemetry;
+    const filtered = {
+        span: (name, attrs, fn) => telemetry.span(name, filterTelemetryAttrs(attrs, flavor), (span) => fn(filterSpanAttrs(span, flavor))),
+        recordHistogram: (name, value, attrs) => telemetry.recordHistogram(name, value, filterTelemetryAttrs(attrs, flavor)),
+        recordCounter: (name, value, attrs) => telemetry.recordCounter(name, value, filterTelemetryAttrs(attrs, flavor)),
+        currentTraceparent: () => telemetry.currentTraceparent()
+    };
+    if (telemetry.withTraceContext) {
+        filtered.withTraceContext = (carrier, fn) => telemetry.withTraceContext?.(carrier, fn) ?? fn();
+    }
+    return filtered;
+}
+async function withIncomingTraceContext(telemetry, opts, logger, fn) {
+    if (!opts?.traceparent)
+        return fn();
+    if (!isValidTraceparent(opts.traceparent) || (opts.tracestate !== undefined && !isValidTracestate(opts.tracestate))) {
+        logger.warn('Invalid Trace Context ignored.', {
+            'harness.warning.code': 'INVALID_TRACE_CONTEXT',
+            traceparent: opts.traceparent,
+            tracestate: opts.tracestate
+        });
+        return fn();
+    }
+    return telemetry.withTraceContext?.({ traceparent: opts.traceparent, ...(opts.tracestate ? { tracestate: opts.tracestate } : {}) }, fn) ?? fn();
+}
+function resolveContentCaptureMode(options) {
+    if (options?.contentCaptureMode !== undefined)
+        return options.contentCaptureMode;
+    const envValue = process.env['OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT'];
+    if (envValue === 'true')
+        return 'SPAN_AND_EVENT';
+    if (envValue === 'false')
+        return 'NO_CONTENT';
+    if (envValue === 'NO_CONTENT' || envValue === 'SPAN_ONLY' || envValue === 'EVENT_ONLY' || envValue === 'SPAN_AND_EVENT')
+        return envValue;
+    return 'NO_CONTENT';
+}
+function metadataSpanAttrs(metadata) {
+    const attrs = {};
+    for (const [key, value] of Object.entries(metadata ?? {})) {
+        if (!/^[a-zA-Z][a-zA-Z0-9_.-]{0,63}$/.test(key))
+            continue;
+        if (typeof value === 'string') {
+            if (value.length <= 256)
+                attrs[`harness.metadata.${key}`] = value;
+            continue;
+        }
+        if (typeof value === 'number' && Number.isFinite(value)) {
+            attrs[`harness.metadata.${key}`] = value;
+            continue;
+        }
+        if (typeof value === 'boolean') {
+            attrs[`harness.metadata.${key}`] = value;
+        }
+    }
+    return attrs;
+}
+function isValidTraceparent(traceparent) {
+    const match = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/.exec(traceparent);
+    if (!match)
+        return false;
+    const [, version, traceId, parentId] = match;
+    return version !== 'ff' && traceId !== '00000000000000000000000000000000' && parentId !== '0000000000000000';
+}
+function isValidTracestate(tracestate) {
+    return tracestate.length <= 512 && !/[\r\n]/.test(tracestate);
+}
+function filterSpanAttrs(span, flavor) {
+    const target = span;
+    return new Proxy(span, {
+        get(value, property, receiver) {
+            if (property === 'setAttribute' && target.setAttribute) {
+                return (key, attrValue) => {
+                    const filtered = filterTelemetryAttrs({ [key]: attrValue }, flavor);
+                    if (Object.keys(filtered).length === 0)
+                        return span;
+                    target.setAttribute?.(key, attrValue);
+                    return span;
+                };
+            }
+            if (property === 'setAttributes' && target.setAttributes) {
+                return (attrs) => {
+                    target.setAttributes?.(filterTelemetryAttrs(attrs, flavor));
+                    return span;
+                };
+            }
+            return Reflect.get(value, property, receiver);
+        }
+    });
+}
+function filterTelemetryAttrs(attrs, flavor) {
+    const out = {};
+    for (const [key, value] of Object.entries(attrs)) {
+        if (value === undefined)
+            continue;
+        if (flavor === 'gen_ai_only' && isOpenInferenceAttr(key))
+            continue;
+        if (flavor === 'openinference_only' && key.startsWith('gen_ai.'))
+            continue;
+        out[key] = value;
+    }
+    return out;
+}
+function isOpenInferenceAttr(key) {
+    return key === 'openinference.span.kind'
+        || key.startsWith('llm.')
+        || key.startsWith('tool.')
+        || key.startsWith('retrieval.')
+        || key.startsWith('embedding.')
+        || key.startsWith('reranker.')
+        || key.startsWith('guardrail.')
+        || key.startsWith('evaluator.')
+        || key === 'input.value'
+        || key === 'output.value';
+}
 function normalizeRunError(error, signal) {
     if (!signal.aborted)
         return error;
@@ -625,11 +814,7 @@ function normalizeRunError(error, signal) {
         return error;
     return new OperationCancelledError('Run was cancelled.', { scope: 'run' }, signal.reason ?? error);
 }
-function sanitizeEventForPersistence(event, captureContent) {
-    if (captureContent) {
-        const { runId: _runId, at: _at, type: _type, ...payload } = event;
-        return payload;
-    }
+function sanitizeEventForPersistence(event) {
     switch (event.type) {
         case 'run.started':
             return {};
@@ -663,7 +848,11 @@ function sanitizeEventForPersistence(event, captureContent) {
         case 'model.object.partial':
             return { ...(event.agentId ? { agentId: event.agentId } : {}), partial: '[redacted]' };
         case 'model.object':
-            return { ...(event.agentId ? { agentId: event.agentId } : {}), object: '[redacted]' };
+            return {
+                ...(event.agentId ? { agentId: event.agentId } : {}),
+                object: '[redacted]',
+                ...(event.usage ? { usage: event.usage } : {})
+            };
         case 'model.embedding.completed':
             return {
                 ...(event.agentId ? { agentId: event.agentId } : {}),
@@ -682,6 +871,24 @@ function sanitizeEventForPersistence(event, captureContent) {
             return { dropped: event.dropped };
     }
 }
+function isJsonRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function isTokenUsage(value) {
+    return isJsonRecord(value)
+        && typeof value['inputTokens'] === 'number'
+        && typeof value['outputTokens'] === 'number'
+        && typeof value['totalTokens'] === 'number';
+}
+function normalizeSerializedRunError(error) {
+    return {
+        code: error?.code ?? 'UNKNOWN',
+        category: error?.category ?? 'internal',
+        retriable: error?.retriable ?? false,
+        message: error?.message ?? 'Unknown error',
+        ...(error?.meta ? { meta: error.meta } : {})
+    };
+}
 function createRunSignal(parent, timeoutMs) {
     const controller = new AbortController();
     const relay = () => controller.abort(parent?.reason);

package/dist/telemetry/shim.d.ts

@@ -1,5 +1,14 @@
 /** Attributes accepted by telemetry span/metric helpers. */
 export type SpanAttrs = Record<string, string | number | boolean | string[] | undefined>;
+/** Developer-facing metric helper exposed in handler contexts. */
+export interface Metrics {
+    /** Adds to a counter instrument. */
+    counter(name: string, value?: number, attrs?: SpanAttrs): void;
+    /** Records a histogram sample. */
+    histogram(name: string, value: number, attrs?: SpanAttrs): void;
+    /** Records the duration of an async operation in seconds. */
+    duration<T>(name: string, attrs: SpanAttrs | undefined, fn: () => Promise<T>): Promise<T>;
+}
 /** Minimal telemetry abstraction used by harness internals and integrations. */
 export interface TelemetryShim {
     /** Creates a span, executes `fn`, and closes the span with success/error status. */
@@ -10,6 +19,11 @@ export interface TelemetryShim {
     recordCounter(name: string, value: number, attrs: SpanAttrs): void;
     /** Injects the current active trace context into a W3C traceparent carrier. */
     currentTraceparent(): string | undefined;
+    /** Runs `fn` with the supplied W3C Trace Context as the active parent context. */
+    withTraceContext?<T>(carrier: {
+        traceparent: string;
+        tracestate?: string;
+    }, fn: () => Promise<T>): Promise<T>;
 }
 /** OpenTelemetry-backed implementation of {@link TelemetryShim}. */
 export declare class OtelTelemetryShim implements TelemetryShim {
@@ -21,6 +35,12 @@ export declare class OtelTelemetryShim implements TelemetryShim {
     recordHistogram(name: string, value: number, attrs: SpanAttrs): void;
     recordCounter(name: string, value: number, attrs: SpanAttrs): void;
     currentTraceparent(): string | undefined;
+    withTraceContext<T>(carrier: {
+        traceparent: string;
+        tracestate?: string;
+    }, fn: () => Promise<T>): Promise<T>;
 }
 /** Creates the default telemetry shim instance. */
 export declare function createTelemetryShim(): TelemetryShim;
+/** Creates a scoped metrics helper with default attributes merged into every metric. */
+export declare function createMetrics(telemetry: TelemetryShim, defaultAttrs?: SpanAttrs): Metrics;

package/dist/telemetry/shim.js

@@ -113,8 +113,36 @@ export class OtelTelemetryShim {
         propagation.inject(context.active(), carrier);
         return carrier['traceparent'];
     }
+    async withTraceContext(carrier, fn) {
+        const extracted = propagation.extract(context.active(), {
+            traceparent: carrier.traceparent,
+            ...(carrier.tracestate ? { tracestate: carrier.tracestate } : {})
+        });
+        return context.with(extracted, fn);
+    }
 }
 /** Creates the default telemetry shim instance. */
 export function createTelemetryShim() {
     return new OtelTelemetryShim();
 }
+/** Creates a scoped metrics helper with default attributes merged into every metric. */
+export function createMetrics(telemetry, defaultAttrs = {}) {
+    const merge = (attrs) => ({ ...defaultAttrs, ...(attrs ?? {}) });
+    return {
+        counter(name, value = 1, attrs) {
+            telemetry.recordCounter(name, value, merge(attrs));
+        },
+        histogram(name, value, attrs) {
+            telemetry.recordHistogram(name, value, merge(attrs));
+        },
+        async duration(name, attrs, fn) {
+            const started = Date.now();
+            try {
+                return await fn();
+            }
+            finally {
+                telemetry.recordHistogram(name, (Date.now() - started) / 1000, merge(attrs));
+            }
+        }
+    };
+}

package/dist/testing/fakeMemoryAdapter.d.ts

@@ -0,0 +1,16 @@
+import type { MemoryAdapter, MemoryOpenContext, MemoryScope, MemoryStore } from '../ports/memory.js';
+/** Deterministic in-memory adapter for unit tests and adapter contract examples. */
+export declare class FakeMemoryAdapter implements MemoryAdapter {
+    readonly info: {
+        id: string;
+        packageName: string;
+        capabilities: readonly ["memory.kv", "memory.list", "memory.delete", "memory.search", "memory.run", "memory.session", "memory.agent", "memory.user", "memory.tenant", "memory.persistent"];
+    };
+    readonly capabilities: readonly ["memory.kv", "memory.list", "memory.delete", "memory.search", "memory.run", "memory.session", "memory.agent", "memory.user", "memory.tenant", "memory.persistent"];
+    readonly openedScopes: MemoryScope[];
+    private readonly values;
+    configureHarnessContext(): void;
+    open(scope: MemoryScope, _ctx: MemoryOpenContext): Promise<MemoryStore>;
+}
+/** Shared contract for memory adapters. */
+export declare function memoryAdapterContract(make: () => MemoryAdapter | Promise<MemoryAdapter>): void;