melchizedek-agents 1.7.0 → 1.10.0

package/dist/lib/doctor.js

@@ -42,6 +42,7 @@ import { OAUTH_HOSTS_ENV } from './tools/oauthHosts.js';
 import { CREDENTIAL_HOSTS_ENV, credentialHosts } from './tools/credentialHosts.js';
 import { syndicateCredentialUses } from './tools/credentialUses.js';
 import { credentialHostEnvProblems, unboundCredentialWarning } from './a2a/oauthSetup.js';
+import { checkProject, findProject, isIgnored, ProjectManifestError, resolveAgentsDir } from './project.js';
 /** The `gateway.id` the doctor reports when `MODEL_GATEWAY` names no known gateway; the value itself is never kept. */
 const UNRECOGNISED_GATEWAY = 'unrecognised';
 function resolvable(module) {
@@ -457,10 +458,11 @@ export function flagMemoryNamespaces(syndicates) {
     }
 }
 export function runDoctor(options = {}) {
-    const agentsDir = path.resolve(options.agentsDir ??
-        process.env.MELCHIZEDEK_AGENTS_DIR ??
-        path.join(process.cwd(), 'config', 'agents'));
-    const syndicates = listSyndicateFiles(agentsDir).map((f) => diagnoseSyndicate(f, agentsDir, options.scripts));
+    const agentsDir = resolveAgentsDir(options.agentsDir);
+    const { project, report: projectReport } = projectFromCwd();
+    // The manifest's ignore list applies when the doctor reads the project's own folder.
+    const listed = listSyndicateFiles(agentsDir).filter((f) => !project || agentsDir !== project.agentsDir || !isIgnored(project, path.relative(project.root, path.join(agentsDir, f))));
+    const syndicates = listed.map((f) => diagnoseSyndicate(f, agentsDir, options.scripts));
     // Which single variable unlocks what. A syndicate counts toward a
     // variable only when that variable is ALL it is missing.
     const byEnv = new Map();
@@ -541,8 +543,22 @@ export function runDoctor(options = {}) {
         providers: providerPaths(),
         ...(serving ? { serving } : {}),
         ...(chatgpt ? { chatgpt } : {}),
+        ...(projectReport ? { project: projectReport } : {}),
     };
 }
+/** The project at or above the working directory, checked; a broken manifest becomes a problem, not a throw. */
+function projectFromCwd() {
+    try {
+        const project = findProject();
+        return project ? { project, report: checkProject(project) } : {};
+    }
+    catch (e) {
+        if (!(e instanceof ProjectManifestError))
+            throw e;
+        const problem = `melchizedek.json: ${e.issues.join('; ')}`;
+        return { report: { root: path.dirname(e.file), error: problem, problems: [problem], warnings: [] } };
+    }
+}
 /**
  * The Sign in with ChatGPT line (ADR 0126), when a credential file is present
  * or one of its variables is set. `served`: a serving variable is set, so
@@ -613,6 +629,8 @@ export function checkProblems(result) {
         problems.push(`credentials: ${p}`);
     for (const p of result.chatgpt?.problems ?? [])
         problems.push(`chatgpt: ${p}`);
+    for (const p of result.project?.problems ?? [])
+        problems.push(`project: ${p}`);
     for (const s of result.syndicates) {
         for (const g of s.grants ?? [])
             for (const p of g.hostProblems ?? [])
@@ -635,6 +653,17 @@ export function renderDoctor(result, opts = {}) {
             : `${c.green}${text}${c.reset}`;
     lines.push(`${c.bold}melchizedek doctor${c.reset} ${c.dim}· ${result.agentsDir}${c.reset}`);
     lines.push('');
+    // The project manifest (ADR 0138): the engine pin, and what in it is stale.
+    if (result.project) {
+        const p = result.project;
+        const pin = 'engine' in p ? `${p.engine.matches ? c.green + '✓' : c.red + '✗'}${c.reset} engine ${p.engine.pinned}${p.engine.matches ? '' : `${c.red}, ${p.engine.running} running${c.reset}`} · ${p.syndicates.length} syndicate(s) ` : '';
+        lines.push(`project     ${pin}${c.dim}${p.root}${c.reset}`);
+        for (const x of p.problems)
+            if (!x.startsWith('engine:'))
+                lines.push(`            ${c.red}✗ ${x}${c.reset}`);
+        for (const x of p.warnings)
+            lines.push(`            ${c.yellow}! ${x}${c.reset}`);
+    }
     // The runtime a turn would run on, and where that came from (ADR 0107).
     if (result.runtime) {
         const rt = result.runtime;

package/dist/lib/index.d.ts

@@ -38,15 +38,18 @@ export { RUN_CODE, runCodeTool } from './tools/runCodeTool.ts';
 export type { CodeRun, RunCodeOutput } from './tools/runCodeTool.ts';
 export { createA2AApp, compileAgentCard, currentRequestContext } from './a2a/app.ts';
 export type { A2AApp, A2AAppOptions, RequestIdentity } from './a2a/app.ts';
-export type { A2AContext } from './a2a/executor.ts';
+export type { A2AContext, TaskStateName, TaskStateRecord } from './a2a/executor.ts';
 export { callerTokens, firstOf, hashCallerToken, jwtIdentity, parseCallers, scopeSegment, sharedSecret, trustedHeader, } from './a2a/identity.ts';
 export type { Authenticator, CallerEntry, IdentityScheme, JwtIdentityOptions } from './a2a/identity.ts';
 export { budgets, memoryUsageStore, parseBudgets, postgresUsageStore, supabaseUsageStore } from './a2a/policy.ts';
-export type { BudgetConfig, BudgetLimits, DailyUsage, Policy, PolicyDecision, PolicySubject, UsageStore } from './a2a/policy.ts';
+export type { BudgetConfig, BudgetLevel, BudgetLimits, BudgetOptions, BudgetState, DailyUsage, HardStop, Policy, PolicyDecision, PolicySubject, UsageStore, } from './a2a/policy.ts';
+export { END_USER_LABELER, feedbackRow, parseFeedback, postgresFeedbackStore } from './a2a/feedback.ts';
+export type { FeedbackRow, FeedbackScore, FeedbackStore, FeedbackTurn } from './a2a/feedback.ts';
 export { createMetrics } from './observability/metrics.ts';
 export type { Metrics, TaskRecord } from './observability/metrics.ts';
 export { patternRedactor, redactRow, setTelemetryRedactor, telemetryRedactor } from './observability/redact.ts';
 export type { Redactor } from './observability/redact.ts';
+export type { Metadata, MetadataValue } from './observability/metadata.ts';
 export { RemoteA2AAgent, remoteAgentTool } from './a2a/remoteAgent.ts';
 export type { RemoteAnswer } from './a2a/remoteAgent.ts';
 export { resolveTools, registerTool, registeredToolNames } from './toolRegistry.ts';
@@ -67,3 +70,4 @@ export { PROVIDERS, providerForModel, providerKeyPresent, providerStatuses, logP
 export { loadEnv } from './loadEnv.ts';
 export { setCredentialSource, credentialValue } from './models/credentialSource.ts';
 export type { CredentialSource } from './models/credentialSource.ts';
+export { PROJECT_MANIFEST, projectManifestSchema, ProjectManifestError, findProject, findProjectRoot, loadProject, parseProjectManifest, resolveAgentsDir, listProjectSyndicates, checkProject, type Project, type ProjectManifest, type ProjectCheck, } from './project.ts';

package/dist/lib/index.js

@@ -32,6 +32,7 @@ export { RUN_CODE, runCodeTool } from './tools/runCodeTool.js';
 export { createA2AApp, compileAgentCard, currentRequestContext } from './a2a/app.js';
 export { callerTokens, firstOf, hashCallerToken, jwtIdentity, parseCallers, scopeSegment, sharedSecret, trustedHeader, } from './a2a/identity.js';
 export { budgets, memoryUsageStore, parseBudgets, postgresUsageStore, supabaseUsageStore } from './a2a/policy.js';
+export { END_USER_LABELER, feedbackRow, parseFeedback, postgresFeedbackStore } from './a2a/feedback.js';
 export { createMetrics } from './observability/metrics.js';
 export { patternRedactor, redactRow, setTelemetryRedactor, telemetryRedactor } from './observability/redact.js';
 export { RemoteA2AAgent, remoteAgentTool } from './a2a/remoteAgent.js';
@@ -55,3 +56,5 @@ describeCapabilities, capabilitySummary, planTransport, gatewayConfig, gatewayPr
 export { loadEnv } from './loadEnv.js';
 // Where credentials are read, by environment variable name (ADR 0133).
 export { setCredentialSource, credentialValue } from './models/credentialSource.js';
+// Project manifest, melchizedek.json (ADR 0138).
+export { PROJECT_MANIFEST, projectManifestSchema, ProjectManifestError, findProject, findProjectRoot, loadProject, parseProjectManifest, resolveAgentsDir, listProjectSyndicates, checkProject, } from './project.js';

package/dist/lib/loadSyndicate.d.ts

@@ -13,6 +13,7 @@ import type { ReasoningSetting } from './models/contract.ts';
 export type { WorkflowConfig } from './workflowConfig.ts';
 export type { ScriptConfig } from './script/config.ts';
 import type { ScriptConfig } from './script/config.ts';
+import type { Metadata } from './observability/metadata.ts';
 export interface ThinkingConfig {
     /** Token budget for internal reasoning. 0 = off, -1 = dynamic. */
     thinkingBudget?: number;
@@ -191,6 +192,12 @@ export interface AgentYamlConfig {
         role?: 'primary' | 'sub-agent';
         delegates?: string[];
     };
+    /**
+     * Static labels for the ledger (ADR 0141): each becomes `meta.agent.<key>`
+     * on this agent's `agent.invoke` span. At most 32 keys; a credential-shaped
+     * value is dropped at load with a warning.
+     */
+    metadata?: Metadata;
 }
 export interface SubagentYamlConfig extends Partial<AgentYamlConfig> {
     /** Required when used as AgentTool — orchestrator reads this to delegate. */
@@ -254,6 +261,13 @@ export interface SyndicateYamlConfig {
     script?: ScriptConfig;
     /** Optional default variable definitions for {{token}} interpolation. */
     variables?: VariableMap;
+    /**
+     * Static labels for the ledger (ADR 0141): each becomes `meta.<key>` on
+     * every root span of a turn, so on its adk_turns row. At most 32 keys; a
+     * credential-shaped value is dropped at load with a warning. A key named
+     * here cannot be set by an A2A caller's request metadata.
+     */
+    metadata?: Metadata;
     /** Defines the persistence and semantic memory layer for the syndicate. */
     memory_system?: 'internal-only' | 'session-only' | 'long-term';
     /**

package/dist/lib/loadSyndicate.js

@@ -5,6 +5,8 @@ import { createClient } from '@supabase/supabase-js';
 import { hasSupabaseCredentials } from './persistence/supabaseProvider.js';
 import { validateSyndicateConfig } from './syndicateSchema.js';
 import { v1SpellingsOf } from './agentDialect.js';
+import { resolveAgentsDir } from './project.js';
+import { dropSecretMetadata } from './observability/metadata.js';
 // ── Variable Injection (private) ──────────────────────────
 const TOKEN_RE = /\{\{(\w+)\}\}/g;
 const FULL_TOKEN_RE = /^\{\{(\w+)\}\}$/;
@@ -100,7 +102,7 @@ function resolveAndValidate(raw, label, options) {
     }
     const valid = validateSyndicateConfig(bundle !== undefined && isPlainObject(interpolated) ? { ...interpolated, bundled_references: bundle } : interpolated, label);
     const { variables: _stripped, ...clean } = valid;
-    let config = clean;
+    let config = withoutSecretMetadata(clean, label, options.onWarning);
     // The script reads the bound variables (ADR 0137 item 6): the YAML's, then the caller's bindings, as {{token}} resolves them.
     if (config.script) {
         const yamlBound = isPlainObject(interpolated) && isPlainObject(interpolated.variables) ? interpolated.variables : {};
@@ -111,6 +113,23 @@ function resolveAndValidate(raw, label, options) {
     }
     return config;
 }
+/**
+ * `metadata:` with every credential-shaped value dropped (ADR 0141), on the
+ * syndicate and on each agent, one warning per key naming the file and the
+ * key path, never the value. A `{{token}}` that resolved to a key is caught
+ * too: this runs on the interpolated config.
+ */
+function withoutSecretMetadata(config, label, onWarning = console.warn) {
+    const meta = dropSecretMetadata(config.metadata, `${label}: metadata`, onWarning);
+    const agent = (a, path) => {
+        const m = dropSecretMetadata(a.metadata, `${label}: ${path}.metadata`, onWarning);
+        return m === a.metadata ? a : { ...a, metadata: m };
+    };
+    const orchestrator = agent(config.orchestrator, 'orchestrator');
+    const subagents = (config.subagents ?? []).map((s, i) => agent(s, `subagents.${i}`));
+    const changed = meta !== config.metadata || orchestrator !== config.orchestrator || subagents.some((s, i) => s !== config.subagents?.[i]);
+    return changed ? { ...config, ...(meta ? { metadata: meta } : {}), orchestrator, subagents } : config;
+}
 /** Labels already warned about, so a server loading one file per request warns once per process. */
 const warnedV1 = new Set();
 /**
@@ -290,10 +309,8 @@ export function readSyndicateFile(filename, options = {}) {
     // Security: confine reads to the agents root. `filename` can originate from
     // a network-controlled path segment (see a2a_server dynamic routes), so we
     // must reject any value that resolves outside that root (e.g. "../../.env").
-    // The root itself is trusted configuration: option → env → cwd default.
-    const agentsDir = path.resolve(options.agentsDir ??
-        process.env.MELCHIZEDEK_AGENTS_DIR ??
-        path.join(process.cwd(), 'config', 'agents'));
+    // The root itself is trusted configuration: option → env → project manifest → cwd default (lib/project.ts).
+    const agentsDir = resolveAgentsDir(options.agentsDir);
     let filePath = path.resolve(agentsDir, filename);
     if (filePath !== agentsDir && !filePath.startsWith(agentsDir + path.sep)) {
         throw new Error(`Invalid syndicate path: '${filename}' resolves outside the agents directory`);

package/dist/lib/memory/providers.js

@@ -59,12 +59,16 @@ export function modelExtractor(opts = {}) {
                 toolsDict: {},
             };
             const request = llmRequestToModelRequest(llmRequest, { model, stream: false });
+            const sources = new WeakMap();
             async function* inner() {
-                for await (const response of adapter.generate(request))
-                    yield modelResponseToLlmResponse(response);
+                for await (const response of adapter.generate(request)) {
+                    const mapped = modelResponseToLlmResponse(response);
+                    sources.set(mapped, response);
+                    yield mapped;
+                }
             }
             let text = '';
-            for await (const response of traceLlmGeneration({ provider: adapter.provider, model, request }, inner())) {
+            for await (const response of traceLlmGeneration({ provider: adapter.provider, model, request, source: (r) => sources.get(r) }, inner())) {
                 if (response.errorCode) {
                     throw new Error(`${model}: ${response.errorCode}${response.errorMessage ? ` — ${response.errorMessage}` : ''}`);
                 }

package/dist/lib/observability/lineage.d.ts

@@ -35,6 +35,25 @@ export declare function agentOfSpanName(name: string): string | null;
 export declare function isToolSpanName(name: string): boolean;
 /** True for one agent step's model-call span: ADK's `call_llm`, the loop's `model.call`. */
 export declare function isModelCallSpan(name: string, scope: string): boolean;
+/** What a span the ledger keeps is, as `adk_telemetry.kind` records it (ADR 0139). */
+export type LedgerSpanKind = 'turn' | 'agent' | 'model' | 'tool' | 'script' | 'node';
+/**
+ * The kind of a span the ledger keeps a row for, from its name, else null:
+ * the turn's root (`Syndicate Execution: <name>`), an agent's run
+ * (`agent.invoke`), a model step and each provider call in it (`model.call`,
+ * `llm.request`), a tool call (`tool.execute`), a script's run and calls
+ * (`script.invoke`, `script.call`), and a workflow's walk and node runs
+ * (`workflow.invoke`, `node.execute`). Every other span (a credential
+ * refresh, a library's own) stays out of the ledger.
+ */
+export declare function ledgerSpanKind(name: string): LedgerSpanKind | null;
+/**
+ * The attribute a span carries when its parent in the ledger is not its
+ * direct parent: the nearest ancestor the ledger keeps, which the tracer
+ * reads from its span lineage when the span starts, while every ancestor is
+ * still open (ADR 0139).
+ */
+export declare const LEDGER_PARENT_ATTRIBUTE = "ledger.parent_span_id";
 /** JSON with object keys sorted at every depth — stable across reloads. */
 export declare function stableStringify(value: unknown): string;
 /** The config with every `yaml_reference` replaced by the loaded syndicate. */

package/dist/lib/observability/lineage.js

@@ -58,6 +58,37 @@ export function isToolSpanName(name) {
 export function isModelCallSpan(name, scope) {
     return (name === 'call_llm' && scope === ADK_SPAN_SCOPE) || (name === 'model.call' && scope === RUNTIME_SPAN_SCOPE);
 }
+/**
+ * The kind of a span the ledger keeps a row for, from its name, else null:
+ * the turn's root (`Syndicate Execution: <name>`), an agent's run
+ * (`agent.invoke`), a model step and each provider call in it (`model.call`,
+ * `llm.request`), a tool call (`tool.execute`), a script's run and calls
+ * (`script.invoke`, `script.call`), and a workflow's walk and node runs
+ * (`workflow.invoke`, `node.execute`). Every other span (a credential
+ * refresh, a library's own) stays out of the ledger.
+ */
+export function ledgerSpanKind(name) {
+    if (name.startsWith('Syndicate Execution: '))
+        return 'turn';
+    if (name === 'llm.request' || name === 'model.call')
+        return 'model';
+    if (name.startsWith('agent.invoke '))
+        return 'agent';
+    if (name.startsWith('tool.execute '))
+        return 'tool';
+    if (name.startsWith('script.invoke ') || name.startsWith('script.call '))
+        return 'script';
+    if (name.startsWith('workflow.invoke ') || name.startsWith('node.execute '))
+        return 'node';
+    return null;
+}
+/**
+ * The attribute a span carries when its parent in the ledger is not its
+ * direct parent: the nearest ancestor the ledger keeps, which the tracer
+ * reads from its span lineage when the span starts, while every ancestor is
+ * still open (ADR 0139).
+ */
+export const LEDGER_PARENT_ATTRIBUTE = 'ledger.parent_span_id';
 /** JSON with object keys sorted at every depth — stable across reloads. */
 export function stableStringify(value) {
     if (value === null || typeof value !== 'object')

package/dist/lib/observability/metadata.d.ts

@@ -0,0 +1,69 @@
+/**
+ * lib/observability/metadata.ts — labels a turn carries into the ledger as
+ * `meta.<key>` root-span attributes (ADR 0141): static ones from the YAML
+ * (`metadata:` on the syndicate, and on an agent as `meta.agent.<key>` on its
+ * agent span), and per-request ones an A2A caller sends (the message's
+ * `metadata` object and the `X-Melch-Meta-*` headers).
+ *
+ * The limits are one set wherever metadata comes from: a key is letters,
+ * digits and `_ . : -` (at most 64, not starting with a punctuation mark), a
+ * value is a string (at most 256 characters), a finite number or a boolean,
+ * and a turn carries at most 32 keys. A value shaped like a credential
+ * (REDACTION_PATTERNS.secret) is never kept: metadata is a label, and a key
+ * pasted into one is dropped with a warning that names the key, never the
+ * value. String values then pass through the telemetry redactor in force.
+ */
+import type { Redactor } from './redact.ts';
+export type MetadataValue = string | number | boolean;
+export type Metadata = Record<string, MetadataValue>;
+/** The attribute prefix: `meta.<key>` on the root span, `meta.agent.<key>` on an agent span. */
+export declare const META_PREFIX = "meta.";
+export declare const META_AGENT_PREFIX = "meta.agent.";
+export declare const MAX_META_KEYS = 32;
+export declare const MAX_META_KEY_CHARS = 64;
+export declare const MAX_META_VALUE_CHARS = 256;
+/** A metadata key: the same rule the desktop app's filters check before a key reaches SQL. */
+export declare const META_KEY: RegExp;
+/** The request header family: `X-Melch-Meta-<key>: <value>` (Node lowercases header names, so the key arrives lowercase). */
+export declare const META_HEADER_PREFIX = "x-melch-meta-";
+/** True when the value looks like a credential (the redactor's `secret` pattern). */
+export declare function isSecretShaped(value: string): boolean;
+/** Why one entry is not metadata, or undefined when it is. Never quotes the value. */
+export declare function metadataEntryProblem(key: string, value: unknown): string | undefined;
+/**
+ * The entries whose value looks like a credential, dropped: the rest, and
+ * one warning per dropped key (`where` names the place, e.g. a file and key path).
+ */
+export declare function dropSecretMetadata(meta: Metadata | undefined, where: string, warn: (message: string) => void): Metadata | undefined;
+/** Metadata as span attributes under `prefix`, string values through the telemetry redactor in force. */
+export declare function metaAttributes(meta: Metadata | undefined, prefix?: string, redactor?: Redactor | undefined): Record<string, MetadataValue>;
+/**
+ * The `X-Melch-Meta-*` headers as metadata, or why the request is refused.
+ * A header is an explicit act of this API, so a malformed one is refused
+ * rather than dropped (as X-Surface is): a key outside the rule, a value
+ * over the limit, more than 32 of them. A credential-shaped value is
+ * dropped, its key listed in `dropped`, for the caller to warn about once
+ * the request is authenticated (an anonymous request must not write logs).
+ */
+export declare function headerMetadata(headers: Record<string, string | string[] | undefined>): {
+    meta?: Metadata;
+    dropped?: string[];
+    error?: string;
+};
+/** The warning for a header `headerMetadata` dropped: the key, never the value. */
+export declare const droppedHeaderWarning: (key: string) => string;
+/**
+ * A request's metadata from its sources, in precedence order (the first to
+ * name a key wins): only scalar entries that pass the rules, never a key in
+ * `reserved` (the YAML's own: a caller cannot relabel an operator's
+ * metadata), never one starting `agent.`, at most `room` keys. A2A's
+ * `Message.metadata` is shared by protocol extensions, so an entry that is
+ * not metadata (a nested object, a long value, a key outside the rule) is
+ * skipped, not refused; the warning counts what was skipped and names valid
+ * keys only.
+ */
+export declare function requestMetadata(sources: ReadonlyArray<unknown>, options?: {
+    reserved?: ReadonlySet<string>;
+    room?: number;
+    warn?: (message: string) => void;
+}): Metadata;

package/dist/lib/observability/metadata.js

@@ -0,0 +1,153 @@
+/**
+ * lib/observability/metadata.ts — labels a turn carries into the ledger as
+ * `meta.<key>` root-span attributes (ADR 0141): static ones from the YAML
+ * (`metadata:` on the syndicate, and on an agent as `meta.agent.<key>` on its
+ * agent span), and per-request ones an A2A caller sends (the message's
+ * `metadata` object and the `X-Melch-Meta-*` headers).
+ *
+ * The limits are one set wherever metadata comes from: a key is letters,
+ * digits and `_ . : -` (at most 64, not starting with a punctuation mark), a
+ * value is a string (at most 256 characters), a finite number or a boolean,
+ * and a turn carries at most 32 keys. A value shaped like a credential
+ * (REDACTION_PATTERNS.secret) is never kept: metadata is a label, and a key
+ * pasted into one is dropped with a warning that names the key, never the
+ * value. String values then pass through the telemetry redactor in force.
+ */
+import { REDACTION_PATTERNS, telemetryRedactor } from './redact.js';
+/** The attribute prefix: `meta.<key>` on the root span, `meta.agent.<key>` on an agent span. */
+export const META_PREFIX = 'meta.';
+export const META_AGENT_PREFIX = 'meta.agent.';
+export const MAX_META_KEYS = 32;
+export const MAX_META_KEY_CHARS = 64;
+export const MAX_META_VALUE_CHARS = 256;
+/** A metadata key: the same rule the desktop app's filters check before a key reaches SQL. */
+export const META_KEY = /^[A-Za-z0-9_][A-Za-z0-9_.:-]{0,63}$/;
+/** The request header family: `X-Melch-Meta-<key>: <value>` (Node lowercases header names, so the key arrives lowercase). */
+export const META_HEADER_PREFIX = 'x-melch-meta-';
+/** True when the value looks like a credential (the redactor's `secret` pattern). */
+export function isSecretShaped(value) {
+    // A fresh, non-global copy: the shared pattern carries the `g` flag, whose lastIndex would make .test() stateful.
+    return new RegExp(REDACTION_PATTERNS.secret.source).test(value);
+}
+/** Why one entry is not metadata, or undefined when it is. Never quotes the value. */
+export function metadataEntryProblem(key, value) {
+    if (!META_KEY.test(key))
+        return `a metadata key is letters, digits and _ . : - (at most ${MAX_META_KEY_CHARS}, not starting with . : -)`;
+    if (typeof value === 'string') {
+        if (value.length > MAX_META_VALUE_CHARS)
+            return `metadata.${key} is longer than ${MAX_META_VALUE_CHARS} characters`;
+        return undefined;
+    }
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? undefined : `metadata.${key} is not a finite number`;
+    if (typeof value === 'boolean')
+        return undefined;
+    return `metadata.${key} must be a string, a number or a boolean`;
+}
+/**
+ * The entries whose value looks like a credential, dropped: the rest, and
+ * one warning per dropped key (`where` names the place, e.g. a file and key path).
+ */
+export function dropSecretMetadata(meta, where, warn) {
+    if (!meta)
+        return meta;
+    let out;
+    for (const [key, value] of Object.entries(meta)) {
+        if (typeof value === 'string' && isSecretShaped(value)) {
+            out ??= { ...meta };
+            delete out[key];
+            warn(`⚠ ${where}.${key} looks like a key or token and is dropped: metadata is a label, never a credential.`);
+        }
+    }
+    return out ?? meta;
+}
+/** Metadata as span attributes under `prefix`, string values through the telemetry redactor in force. */
+export function metaAttributes(meta, prefix = META_PREFIX, redactor = telemetryRedactor()) {
+    const out = {};
+    for (const [key, value] of Object.entries(meta ?? {})) {
+        if (metadataEntryProblem(key, value) || (typeof value === 'string' && isSecretShaped(value)))
+            continue;
+        out[`${prefix}${key}`] = typeof value === 'string' && redactor ? redactor(value) : value;
+    }
+    return out;
+}
+/**
+ * The `X-Melch-Meta-*` headers as metadata, or why the request is refused.
+ * A header is an explicit act of this API, so a malformed one is refused
+ * rather than dropped (as X-Surface is): a key outside the rule, a value
+ * over the limit, more than 32 of them. A credential-shaped value is
+ * dropped, its key listed in `dropped`, for the caller to warn about once
+ * the request is authenticated (an anonymous request must not write logs).
+ */
+export function headerMetadata(headers) {
+    const meta = {};
+    const dropped = [];
+    let count = 0;
+    for (const [name, raw] of Object.entries(headers)) {
+        if (!name.toLowerCase().startsWith(META_HEADER_PREFIX) || raw === undefined)
+            continue;
+        const key = name.slice(META_HEADER_PREFIX.length).toLowerCase();
+        const value = Array.isArray(raw) ? raw.join(', ') : raw;
+        const problem = metadataEntryProblem(key, value);
+        if (problem)
+            return { error: `Invalid X-Melch-Meta-* header: ${problem.replace(/^metadata\.[^ ]+/, 'its value')}` };
+        if (key.startsWith('agent.'))
+            return { error: 'Invalid X-Melch-Meta-* header: keys starting "agent." are reserved for agent spans' };
+        if (++count > MAX_META_KEYS)
+            return { error: `Too many X-Melch-Meta-* headers: at most ${MAX_META_KEYS}` };
+        if (isSecretShaped(value)) {
+            dropped.push(key);
+            continue;
+        }
+        meta[key] = value;
+    }
+    return count ? { meta, ...(dropped.length ? { dropped } : {}) } : {};
+}
+/** The warning for a header `headerMetadata` dropped: the key, never the value. */
+export const droppedHeaderWarning = (key) => `⚠ X-Melch-Meta-${key} looks like a key or token and is dropped: metadata is a label, never a credential.`;
+/**
+ * A request's metadata from its sources, in precedence order (the first to
+ * name a key wins): only scalar entries that pass the rules, never a key in
+ * `reserved` (the YAML's own: a caller cannot relabel an operator's
+ * metadata), never one starting `agent.`, at most `room` keys. A2A's
+ * `Message.metadata` is shared by protocol extensions, so an entry that is
+ * not metadata (a nested object, a long value, a key outside the rule) is
+ * skipped, not refused; the warning counts what was skipped and names valid
+ * keys only.
+ */
+export function requestMetadata(sources, options = {}) {
+    const room = Math.max(0, Math.min(MAX_META_KEYS, options.room ?? MAX_META_KEYS));
+    const out = {};
+    let kept = 0;
+    let skipped = 0;
+    let overflow = 0;
+    for (const source of sources) {
+        if (!source || typeof source !== 'object' || Array.isArray(source))
+            continue;
+        for (const [key, value] of Object.entries(source)) {
+            if (Object.prototype.hasOwnProperty.call(out, key))
+                continue;
+            if (options.reserved?.has(key))
+                continue;
+            if (metadataEntryProblem(key, value) || key.startsWith('agent.')) {
+                skipped++;
+                continue;
+            }
+            if (typeof value === 'string' && isSecretShaped(value)) {
+                options.warn?.(`⚠ Request metadata ${key} looks like a key or token and is dropped: metadata is a label, never a credential.`);
+                continue;
+            }
+            if (kept >= room) {
+                overflow++;
+                continue;
+            }
+            out[key] = value;
+            kept++;
+        }
+    }
+    if (skipped)
+        options.warn?.(`Request metadata: ${skipped} entr${skipped === 1 ? 'y is' : 'ies are'} not metadata (a key outside [A-Za-z0-9_.:-]{1,64}, a value that is not a short string, number or boolean) and skipped.`);
+    if (overflow)
+        options.warn?.(`Request metadata: ${overflow} key(s) over the limit of ${MAX_META_KEYS} per turn skipped.`);
+    return out;
+}

package/dist/lib/observability/otlpFilter.js

@@ -27,6 +27,7 @@ export const CONTENT_ATTRIBUTES = new Set([
     'llm.thinking',
     'llm.error_message',
     'tool.args',
+    'tool.result',
     'tool.data_gathered',
 ]);
 const CONTENT_PREFIXES = ['llm.payload.'];

package/dist/lib/observability/supabaseSpanExporter.d.ts

@@ -13,7 +13,11 @@
  *                    tool calls WITH their responses, the ids that join it to
  *                    the session (session_id, invocation_id) and the task,
  *                    and provenance (config_hash, engine_version).
- *     adk_telemetry  one row per span — llm.request and root spans, raw.
+ *     adk_telemetry  one row per span the ledger keeps — the turn's root, each
+ *                    agent run, model step and provider call, tool call,
+ *                    script run and call, workflow walk and node run — each
+ *                    with its parent among them and its kind, so a turn's
+ *                    span tree is stored (ADR 0139).
  *     adk_payloads   full request/response per model call, captured by
  *                    POLICY and expiring. ADK's own call_llm spans carry the
  *                    assembled prompt and raw response, and the native
@@ -37,6 +41,7 @@
  *     payloads or none, and a re-run of the same policy keeps the same set.
  */
 import type { SpanExporter, ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import type { LedgerSpanKind } from './lineage.ts';
 /** Row shape for adk_telemetry (raw spans). */
 export interface TelemetryRow {
     ts: string;
@@ -50,11 +55,19 @@ export interface TelemetryRow {
     input_tokens: number | null;
     output_tokens: number | null;
     thinking_tokens: number | null;
+    /** The parts of input_tokens read from and written to the provider's prompt cache; null when unreported. */
+    cache_read_tokens: number | null;
+    cache_write_tokens: number | null;
     latency_ms: number;
     session_id: string | null;
     user_id: string | null;
     task_id: string | null;
     invocation_id: string | null;
+    /** The nearest ancestor span the ledger keeps (ADR 0139); null for a span with no parent. */
+    parent_span_id: string | null;
+    kind: LedgerSpanKind | null;
+    /** The span failed: an error status, an error code, a tool's error response. */
+    error: boolean;
     schema_version: number;
     span: Record<string, unknown>;
 }
@@ -87,6 +100,9 @@ export interface TurnRow {
     input_tokens: number | null;
     output_tokens: number | null;
     thinking_tokens: number | null;
+    /** Cache tokens summed over the turn's calls (a provider bills each call's). */
+    cache_read_tokens: number | null;
+    cache_write_tokens: number | null;
     latency_ms: number;
     model_ms: number | null;
     tool_ms: number | null;
@@ -144,13 +160,26 @@ export interface TurnFacts {
 }
 /** Which payloads of a turn to keep, given the policy and the turn's outcome. */
 export declare function payloadDecision(policy: PayloadPolicy, traceId: string, facts: TurnFacts): PayloadReason | null;
+/**
+ * The spans that get an adk_telemetry row: every span ledgerSpanKind names
+ * (ADR 0139). A model step's row (`model.call`) leaves its payload to
+ * adk_payloads (spanJson drops `llm.payload.*`) and its tokens to its
+ * llm.request rows, so a trace's rows sum without counting a call twice. A
+ * script's own spans (ADR 0137 item 16) carry its run, its calls' kinds,
+ * names, sequence and status, never an argument or a result.
+ */
+export declare function isLedgerSpan(span: ReadableSpan): boolean;
 export declare function isRootSpan(span: ReadableSpan): boolean;
 export declare function isPayloadSpan(span: ReadableSpan): boolean;
 /** `syndicate.input` is JSON.stringify of either a string or A2A parts. */
 export declare function parseInputText(raw: unknown): string;
+/** The span's parent in the ledger: the ancestor the tracer recorded at start, else its direct parent. */
+export declare function ledgerParentOf(span: ReadableSpan): string | null;
+/** Whether a span failed: its status, an error code it records, or a tool's error response. */
+export declare function spanFailed(span: ReadableSpan): boolean;
 /** Span attributes minus the payload capture (`llm.payload.*`). */
 export declare function withoutPayloadAttributes(attrs: Record<string, unknown>): Record<string, unknown>;
-/** Flatten an llm.request or root span into one adk_telemetry row. */
+/** Flatten a span the ledger keeps (isLedgerSpan) into one adk_telemetry row. */
 export declare function toTelemetryRow(span: ReadableSpan): TelemetryRow;
 /** Project a root span into the adk_turns system-of-record row. */
 export declare function toTurnRow(span: ReadableSpan): TurnRow;