melchizedek-agents 1.3.0 → 1.6.0

package/dist/lib/models/credentialSource.js

@@ -0,0 +1,49 @@
+/**
+ * lib/models/credentialSource.ts — where the engine reads a credential by
+ * its environment variable name (ADR 0133).
+ *
+ * By default every provider key, gateway key and embedding key is read from
+ * `process.env`. An embedding application that holds keys elsewhere (an OS
+ * keychain, a secret manager) sets a source once:
+ *
+ *   setCredentialSource((name) => keychain.get(name));
+ *
+ * and every read below asks the source first, by the same names the
+ * environment uses (ANTHROPIC_API_KEY, MODEL_GATEWAY_API_KEY, …), at the
+ * moment of use: nothing is cached, so a key the user removes stops working
+ * on the next call. A source that returns undefined for a name falls back to
+ * the environment. A dependency-free leaf, so providerMap.ts stays one.
+ */
+let source;
+/** Sets (or, with undefined, clears) the process's credential source. */
+export function setCredentialSource(next) {
+    source = next;
+}
+/** The credential named `name`: the source's, else `env`'s. A source that throws counts as holding nothing. */
+export function credentialValue(name, env = process.env) {
+    if (source) {
+        try {
+            const held = source(name);
+            if (held !== undefined && held !== '')
+                return held;
+        }
+        catch {
+            /* a broken source must not take the engine down; the environment still answers */
+        }
+    }
+    return env[name];
+}
+/**
+ * `env` as the engine's env-reading helpers see it: a read by name asks the
+ * source first. For functions that take an `env` parameter; enumeration and
+ * spreading see only `env`'s own variables.
+ */
+export function credentialEnv(env = process.env) {
+    if (!source)
+        return env;
+    return new Proxy(env, {
+        get(target, key, receiver) {
+            return typeof key === 'string' ? credentialValue(key, target) : Reflect.get(target, key, receiver);
+        },
+    });
+}

package/dist/lib/models/endpoints.js

@@ -31,6 +31,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 };
 import { PROVIDERS, providerKeyPresent } from './providerMap.js';
 import { trimTrailingSlashes } from './urls.js';
+import { credentialEnv } from './credentialSource.js';
 export const PLATFORMS_FOR = {
     gemini: ['direct', 'vertex'],
     anthropic: ['direct', 'bedrock', 'vertex'],
@@ -81,7 +82,7 @@ export function platformFromEnv(provider, env = process.env) {
     return raw;
 }
 /** A provider's endpoint as the environment configures it. */
-export function endpointFromEnv(provider, env = process.env) {
+export function endpointFromEnv(provider, env = credentialEnv()) {
     const platform = platformFromEnv(provider, env);
     const mapEnv = MODEL_MAP_ENV[provider];
     const models = mapEnv ? parseModelMap(env[mapEnv], mapEnv) : undefined;

package/dist/lib/models/gateway.js

@@ -41,6 +41,7 @@ import { chatGptSignInRoutesOpenAi } from '../chatgpt/state.js';
 import { providerReady } from './endpoints.js';
 import { PROVIDERS, providerForModel } from './providerMap.js';
 import { trimTrailingSlashes } from './urls.js';
+import { credentialValue } from './credentialSource.js';
 export const GATEWAY_ENV = 'MODEL_GATEWAY';
 export const GATEWAY_KEY_ENV = 'MODEL_GATEWAY_API_KEY';
 export const GATEWAY_BASE_URL_ENV = 'MODEL_GATEWAY_BASE_URL';
@@ -78,7 +79,7 @@ export function gatewayConfig() {
     return {
         gateway,
         baseUrl: trimTrailingSlashes(override || gateway.baseUrl),
-        keyPresent: !!process.env[GATEWAY_KEY_ENV],
+        keyPresent: !!credentialValue(GATEWAY_KEY_ENV),
     };
 }
 /** A human-readable misconfiguration, or undefined when the gateway is

package/dist/lib/models/gatewayAdapter.js

@@ -31,6 +31,7 @@
 import { ChatCompletionsAdapter } from './chatCompletionsAdapter.js';
 import { GATEWAY_ENV, GATEWAY_KEY_ENV, GATEWAY_MODEL_MAP_ENV, gatewayConfig, gatewayWireModel } from './gateway.js';
 import { providerForModel } from './providerMap.js';
+import { credentialValue } from './credentialSource.js';
 export class GatewayAdapter extends ChatCompletionsAdapter {
     /** Attribution stays with the upstream provider named by the YAML id. */
     provider;
@@ -47,7 +48,7 @@ export class GatewayAdapter extends ChatCompletionsAdapter {
         return `${this.#cfg?.baseUrl ?? ''}/chat/completions`;
     }
     headers() {
-        return { Authorization: `Bearer ${process.env[GATEWAY_KEY_ENV] ?? ''}` };
+        return { Authorization: `Bearer ${credentialValue(GATEWAY_KEY_ENV) ?? ''}` };
     }
     wireModelName(model) {
         return this.#cfg ? gatewayWireModel(model, this.#cfg.gateway) : model;

package/dist/lib/models/geminiAdapter.js

@@ -52,6 +52,7 @@ import { currentTurnStart, providerStateOf } from './providerState.js';
 import { classifyError, errorStatus, retryUntilFirstYield } from './retry.js';
 import { isAboveHigh, reasoningConfig } from './reasoning.js';
 import { setLlmSpanAttribute } from '../observability/tracer.js';
+import { credentialValue } from './credentialSource.js';
 /**
  * The provider id this adapter reports and writes its state under, and the
  * providerState kind for a Gemini thought signature (ADR 0046). Defined once
@@ -846,7 +847,7 @@ function nonEmpty(value) {
 }
 /** The Gemini API key from the environment, in ADK's order. */
 function envApiKey() {
-    return nonEmpty(process.env.GOOGLE_GENAI_API_KEY) ?? nonEmpty(process.env.GOOGLE_API_KEY) ?? nonEmpty(process.env.GEMINI_API_KEY);
+    return nonEmpty(credentialValue('GOOGLE_GENAI_API_KEY')) ?? nonEmpty(credentialValue('GOOGLE_API_KEY')) ?? nonEmpty(credentialValue('GEMINI_API_KEY'));
 }
 function messageOf(err) {
     return err instanceof Error ? err.message : String(err);

package/dist/lib/models/gptAdapter.js

@@ -48,6 +48,7 @@ import { currentTurnStart, providerStateOf } from './providerState.js';
 import { effortWord } from './reasoning.js';
 import { toContractJsonSchema } from './schemaNormalize.js';
 import { setLlmSpanAttribute } from '../observability/tracer.js';
+import { credentialValue } from './credentialSource.js';
 /** The providerState kind the Responses adapters write: the reasoning output items that preceded a part (ADR 0046, ADR 0050). */
 export const REASONING_STATE_KIND = 'reasoning_items';
 /** The `include` value that returns reasoning items with their encrypted content. */
@@ -410,7 +411,7 @@ export class GptAdapter {
         return undefined;
     }
     apiKeyFromEnv() {
-        return process.env.OPENAI_API_KEY;
+        return credentialValue('OPENAI_API_KEY');
     }
     missingKeyMessage() {
         return 'OPENAI_API_KEY is not set in environment.';
@@ -755,6 +756,10 @@ export class GptAdapter {
         let completed;
         let streamedThoughts = false;
         const text = [];
+        // Each finished output item, by its index. The plan-usage route (Sign in
+        // with ChatGPT, store: false) sends response.completed with an empty
+        // output: the items arrive only here, so the final is built from them.
+        const doneItems = [];
         for await (const ev of untilAborted(events, signal)) {
             const delta = streamEventDelta(ev);
             if (delta) {
@@ -765,7 +770,10 @@ export class GptAdapter {
                 yield { partial: true, parts: [delta.thought ? { type: 'thinking', text: delta.text } : { type: 'text', text: delta.text }] };
                 continue;
             }
-            if (ev?.type === 'response.completed' && ev.response) {
+            if (ev?.type === 'response.output_item.done' && ev.item && typeof ev.item === 'object') {
+                doneItems.push({ index: typeof ev.output_index === 'number' ? ev.output_index : doneItems.length, item: ev.item });
+            }
+            else if (ev?.type === 'response.completed' && ev.response) {
                 completed = ev.response;
             }
             else if (ev?.type === 'response.failed' || ev?.type === 'error') {
@@ -775,6 +783,9 @@ export class GptAdapter {
             }
         }
         if (completed) {
+            if ((!Array.isArray(completed.output) || completed.output.length === 0) && doneItems.length > 0) {
+                completed = { ...completed, output: doneItems.sort((x, y) => x.index - y.index).map((d) => d.item) };
+            }
             const { thinking, final } = this.finalOf(completed, model, { skipThoughts: streamedThoughts });
             if (thinking)
                 yield thinking;

package/dist/lib/models/grokAdapter.js

@@ -29,6 +29,7 @@ import { GptAdapter } from './gptAdapter.js';
 import { effortWord } from './reasoning.js';
 import { collectionIdsFromEnv, collectionsMaxResultsFromEnv, xaiWebSearchParamsFromEnv, xSearchParamsFromEnv, } from '../tools/xaiSearchParams.js';
 import { setLlmSpanAttribute } from '../observability/tracer.js';
+import { credentialValue } from './credentialSource.js';
 export const XAI_BASE_URL = 'https://api.x.ai/v1';
 /**
  * The ids that take a reasoning effort and return encrypted reasoning:
@@ -60,7 +61,7 @@ export class GrokAdapter extends GptAdapter {
         return XAI_BASE_URL;
     }
     apiKeyFromEnv() {
-        return process.env.XAI_API_KEY;
+        return credentialValue('XAI_API_KEY');
     }
     missingKeyMessage() {
         return 'XAI_API_KEY is not set in environment.';

package/dist/lib/models/kimiAdapter.js

@@ -120,6 +120,7 @@
 import { DEFAULT_KIMI_REASONING_EFFORT } from '../config.js';
 import { ChatCompletionsAdapter, reasonsNotAtAll } from './chatCompletionsAdapter.js';
 import { trimTrailingSlashes } from './urls.js';
+import { credentialValue } from './credentialSource.js';
 export const MOONSHOT_BASE_URL = 'https://api.moonshot.ai/v1';
 /** The flagship takes `reasoning_effort`; the K2 generation takes a `thinking` switch. */
 export function isKimiK3(model) {
@@ -153,7 +154,7 @@ export class KimiAdapter extends ChatCompletionsAdapter {
         return `${this.#baseUrl}/chat/completions`;
     }
     #key() {
-        return this.#apiKey ?? process.env.MOONSHOT_API_KEY;
+        return this.#apiKey ?? credentialValue('MOONSHOT_API_KEY');
     }
     headers() {
         return { Authorization: `Bearer ${this.#key() ?? ''}` };

package/dist/lib/models/providerMap.js

@@ -13,6 +13,7 @@
  *   grok-*     → xai           ollama/<model>    → ollama (local, keyless)
  *   kimi-*     → moonshot      everything else   → gemini (the default)
  */
+import { credentialValue } from './credentialSource.js';
 export const PROVIDERS = {
     gemini: { keyEnv: 'GOOGLE_GENAI_API_KEY', label: 'Google Gemini' },
     anthropic: { keyEnv: 'ANTHROPIC_API_KEY', label: 'Anthropic Claude' },
@@ -43,9 +44,9 @@ export function providerKeyPresent(provider) {
         return true;
     // Gemini historically accepts either env name.
     if (provider === 'gemini') {
-        return realValue(process.env.GOOGLE_GENAI_API_KEY) || realValue(process.env.GEMINI_API_KEY);
+        return realValue(credentialValue('GOOGLE_GENAI_API_KEY')) || realValue(credentialValue('GEMINI_API_KEY'));
     }
-    return realValue(process.env[keyEnv]);
+    return realValue(credentialValue(keyEnv));
 }
 /** Set, and not a `.env.example` placeholder (`your_..._here`, `<...>`).
  *  Inlined rather than imported: this module stays a dependency-free leaf. */

package/dist/lib/observability/embeddings.js

@@ -10,6 +10,7 @@
  */
 import { EMBEDDING_DIMENSIONS, EMBEDDING_MODEL } from '../config.js';
 import { memoryProvidersFromEnv } from '../memory/providers.js';
+import { credentialValue } from '../models/credentialSource.js';
 const MAX_CHARS = 8_000;
 /**
  * Embeds each text with the SAME embedder long-term memory uses, so the two
@@ -20,7 +21,7 @@ const MAX_CHARS = 8_000;
 export async function embedTexts(texts, options = {}) {
     let embedder = options.embedder;
     if (!embedder) {
-        const apiKey = options.apiKey ?? process.env.GOOGLE_GENAI_API_KEY ?? process.env.GEMINI_API_KEY;
+        const apiKey = options.apiKey ?? credentialValue('GOOGLE_GENAI_API_KEY') ?? credentialValue('GEMINI_API_KEY');
         const provider = (process.env.MEMORY_EMBEDDING_PROVIDER?.trim() || 'gemini').toLowerCase();
         if (provider === 'gemini' && !apiKey)
             throw new Error('GOOGLE_GENAI_API_KEY is required for Gemini embeddings');

package/dist/lib/observability/lineage.js

@@ -26,6 +26,7 @@ import { createHash } from 'node:crypto';
 import { execSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { enginePackageRoot } from '../paths.js';
 /** Schema version stamped on every ledger row (adk_turns / adk_payloads). */
 export const TELEMETRY_SCHEMA_VERSION = 2;
 // ── Span lineage: the names spans are given ──────────────────────────────────
@@ -105,8 +106,10 @@ export function engineVersion() {
         return cachedEngineVersion;
     let pkgVersion = '0.0.0';
     try {
-        const pkgPath = join(process.cwd(), 'package.json');
-        if (existsSync(pkgPath)) {
+        // The engine's own package.json, not the embedding application's.
+        const root = enginePackageRoot();
+        const pkgPath = root ? join(root, 'package.json') : '';
+        if (pkgPath && existsSync(pkgPath)) {
             pkgVersion = String(JSON.parse(readFileSync(pkgPath, 'utf-8')).version ?? pkgVersion);
         }
     }
@@ -116,7 +119,12 @@ export function engineVersion() {
     let commit = process.env.SOURCE_VERSION ?? process.env.HEROKU_SLUG_COMMIT ?? process.env.GIT_COMMIT ?? '';
     if (!commit) {
         try {
-            commit = execSync('git rev-parse --short HEAD', { stdio: ['ignore', 'pipe', 'ignore'] })
+            // Only from the engine's own checkout: an installed package inside an
+            // application's repository would otherwise report the application's commit.
+            const root = enginePackageRoot();
+            if (!root || !existsSync(join(root, '.git')))
+                throw new Error('not a checkout');
+            commit = execSync('git rev-parse --short HEAD', { cwd: root, stdio: ['ignore', 'pipe', 'ignore'] })
                 .toString()
                 .trim();
         }

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

@@ -174,7 +174,8 @@ export interface ExportStats {
     deadLettered: number;
     payloadsDropped: number;
 }
-interface SupabaseLikeClient {
+/** Where the exporter writes: supabase-js, or `postgresLedgerClient` on a pg pool. */
+export interface LedgerClient {
     from(table: string): {
         insert(rows: unknown[]): PromiseLike<{
             error: {
@@ -183,6 +184,23 @@ interface SupabaseLikeClient {
         }>;
     };
 }
+type SupabaseLikeClient = LedgerClient;
+/** The tables the exporter writes; nothing else is ever named in its SQL. */
+export declare const LEDGER_TABLES: readonly ['adk_telemetry', 'adk_turns', 'adk_payloads'];
+/** The subset of a pg Pool the ledger client needs. */
+export interface LedgerPool {
+    query(text: string, values?: unknown[]): Promise<unknown>;
+}
+/**
+ * The ledger over a direct Postgres connection (ADR 0131): the same rows the
+ * Supabase sink writes, through one parameterised statement per batch. The
+ * rows go in as one JSON array and `jsonb_populate_recordset` gives each
+ * value its column's type, so JSON, arrays and timestamps need no mapping
+ * here. Only the columns the rows carry are named, so the rest keep their
+ * defaults. The table must be one of LEDGER_TABLES and every column name
+ * comes from the row builders above, never from span content.
+ */
+export declare function postgresLedgerClient(pool: LedgerPool): LedgerClient;
 export interface ExporterOptions {
     /** Injected client (tests); default: lazily created supabase-js client. */
     client?: SupabaseLikeClient;

package/dist/lib/observability/supabaseSpanExporter.js

@@ -43,6 +43,7 @@ const { ExportResultCode } = core;
 import { hasSupabaseCredentials } from '../persistence/supabaseProvider.js';
 import { TELEMETRY_SCHEMA_VERSION, isModelCallSpan } from './lineage.js';
 import { redactRow, telemetryRedactor } from './redact.js';
+import { outputsDir } from '../paths.js';
 /**
  * TELEMETRY_PAYLOADS: off | errors | sample (default) | all
  * TELEMETRY_PAYLOAD_SAMPLE: 0..1, default 0.10
@@ -300,7 +301,42 @@ export function telemetrySinkEnabled() {
     return process.env.TELEMETRY_SUPABASE === 'true' && hasSupabaseCredentials();
 }
 export function deadLetterPath() {
-    return join(process.env.OUTPUTS_DIR ?? join(process.cwd(), 'outputs'), 'telemetry-deadletter.ndjson');
+    return join(outputsDir(), 'telemetry-deadletter.ndjson');
+}
+/** The tables the exporter writes; nothing else is ever named in its SQL. */
+export const LEDGER_TABLES = ['adk_telemetry', 'adk_turns', 'adk_payloads'];
+const quoteIdent = (name) => `"${name.replace(/"/g, '""')}"`;
+/**
+ * The ledger over a direct Postgres connection (ADR 0131): the same rows the
+ * Supabase sink writes, through one parameterised statement per batch. The
+ * rows go in as one JSON array and `jsonb_populate_recordset` gives each
+ * value its column's type, so JSON, arrays and timestamps need no mapping
+ * here. Only the columns the rows carry are named, so the rest keep their
+ * defaults. The table must be one of LEDGER_TABLES and every column name
+ * comes from the row builders above, never from span content.
+ */
+export function postgresLedgerClient(pool) {
+    return {
+        from(table) {
+            return {
+                async insert(rows) {
+                    if (!LEDGER_TABLES.includes(table))
+                        return { error: { message: `not a ledger table: ${table}` } };
+                    const columns = [...new Set(rows.flatMap((r) => Object.entries(r).filter(([, v]) => v !== undefined).map(([k]) => k)))];
+                    if (!columns.length)
+                        return { error: null };
+                    const list = columns.map(quoteIdent).join(', ');
+                    try {
+                        await pool.query(`INSERT INTO ${quoteIdent(table)} (${list}) SELECT ${list} FROM jsonb_populate_recordset(NULL::${quoteIdent(table)}, $1::jsonb)`, [JSON.stringify(rows)]);
+                        return { error: null };
+                    }
+                    catch (err) {
+                        return { error: { message: err instanceof Error ? err.message : String(err) } };
+                    }
+                },
+            };
+        },
+    };
 }
 const PENDING_TTL_MS = 10 * 60 * 1000;
 const DECISION_TTL_MS = 30 * 60 * 1000;

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

@@ -3,6 +3,7 @@ import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
 import type { LlmResponse } from '../models/genaiMapping.ts';
 import type { TurnEvent as Event } from '../runtime/events.ts';
 import type { ModelRequest } from '../models/contract.ts';
+import type { ExporterOptions, LedgerClient } from './supabaseSpanExporter.ts';
 /**
  * Optional OTLP export for a live trace viewer (Phoenix, Langfuse, Grafana
  * Tempo, Jaeger — anything that speaks OTLP/HTTP). Set
@@ -15,6 +16,14 @@ import type { ModelRequest } from '../models/contract.ts';
  * Supabase stays the system of record; this is a viewer.
  */
 export declare function otlpEndpoint(): string | undefined;
+/**
+ * Writes the ledger (adk_turns, adk_telemetry, adk_payloads) through
+ * `client`, batched off the turn's path, with the same rows, payload policy
+ * and redaction as the Supabase sink. One ledger is attached at a time;
+ * attaching another replaces it. Returns a detach that flushes what is
+ * buffered first.
+ */
+export declare function attachLedger(client: LedgerClient, options?: Omit<ExporterOptions, 'client'>): () => Promise<void>;
 /**
  * Flushes buffered span processors (console is synchronous; the Supabase
  * batch sink is not). Call before process exit in short-lived scripts so
@@ -36,8 +45,17 @@ interface TraceStats {
     toolMs: number;
     llmCalls: number;
     models: Set<string>;
+    /** Each model's calls and tokens, input summed per call (what a provider bills), for `syndicate.usage` (ADR 0136). */
+    usage: Map<string, ModelUsage>;
     startedAt: number;
 }
+/** One model's share of a turn: what the ledger prices it from (model_pricing, ADR 0136). */
+export interface ModelUsage {
+    calls: number;
+    input: number;
+    output: number;
+    thinking: number;
+}
 /** Read-and-forget the stats for a finished trace. */
 export declare function takeTraceStats(traceId: string): TraceStats | undefined;
 /** Name of the agent of the nearest enclosing agent span (ADK's `invoke_agent`, the loop's `agent.invoke`), or null. */

package/dist/lib/observability/tracer.js

@@ -51,6 +51,49 @@ function otlpProcessor() {
 let isOtelInitialized = false;
 let tracerProvider;
 let telemetryExporter;
+/**
+ * The ledger an embedding application attaches at run time (ADR 0131):
+ * `attachLedger` (or `postgresStorage({ ledger: true })`) sets it, before or
+ * after tracing starts. The processor below is always registered and does
+ * nothing until then.
+ */
+let attachedLedger;
+class AttachedLedgerProcessor {
+    onStart() { }
+    onEnd(span) {
+        attachedLedger?.processor.onEnd(span);
+    }
+    forceFlush() {
+        return attachedLedger ? attachedLedger.processor.forceFlush().then(() => attachedLedger?.exporter.forceFlush()) : Promise.resolve();
+    }
+    shutdown() {
+        return this.forceFlush();
+    }
+}
+/**
+ * Writes the ledger (adk_turns, adk_telemetry, adk_payloads) through
+ * `client`, batched off the turn's path, with the same rows, payload policy
+ * and redaction as the Supabase sink. One ledger is attached at a time;
+ * attaching another replaces it. Returns a detach that flushes what is
+ * buffered first.
+ */
+export function attachLedger(client, options = {}) {
+    if (telemetrySinkEnabled()) {
+        console.warn('[TELEMETRY] ⚠ a ledger is attached while TELEMETRY_SUPABASE=true: every row is written twice. Use one sink.');
+    }
+    const exporter = new SupabaseSpanExporter({ ...options, client });
+    const entry = { exporter, processor: new sdkBase.BatchSpanProcessor(exporter) };
+    const previous = attachedLedger;
+    attachedLedger = entry;
+    void previous?.processor.shutdown();
+    initializeTracing();
+    return async () => {
+        if (attachedLedger === entry)
+            attachedLedger = undefined;
+        await entry.processor.forceFlush();
+        await entry.exporter.shutdown();
+    };
+}
 /**
  * Flushes buffered span processors (console is synchronous; the Supabase
  * batch sink is not). Call before process exit in short-lived scripts so
@@ -59,6 +102,7 @@ let telemetryExporter;
 export async function flushTracing() {
     await tracerProvider?.forceFlush?.();
     await telemetryExporter?.forceFlush?.();
+    await attachedLedger?.exporter.forceFlush();
 }
 // ── In-process span listeners ────────────────────────────────────────────────
 // Lets a script (e.g. scripts/demo_model_optionality.ts) read finished spans
@@ -150,7 +194,7 @@ const TRACE_STATS_TTL_MS = 60 * 60 * 1000;
 function statsFor(traceId) {
     let s = traceStats.get(traceId);
     if (!s) {
-        s = { modelMs: 0, toolMs: 0, llmCalls: 0, models: new Set(), startedAt: Date.now() };
+        s = { modelMs: 0, toolMs: 0, llmCalls: 0, models: new Set(), usage: new Map(), startedAt: Date.now() };
         traceStats.set(traceId, s);
         if (traceStats.size > 2_000) {
             const cutoff = Date.now() - TRACE_STATS_TTL_MS;
@@ -200,8 +244,19 @@ class SpanLineageProcessor {
             s.modelMs += spanDurationMs(span);
             s.llmCalls += 1;
             const model = span.attributes['llm.model'];
-            if (typeof model === 'string' && model)
+            if (typeof model === 'string' && model) {
                 s.models.add(model);
+                const tokens = (key) => {
+                    const v = span.attributes[key];
+                    return typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : 0;
+                };
+                const u = s.usage.get(model) ?? { calls: 0, input: 0, output: 0, thinking: 0 };
+                u.calls += 1;
+                u.input += tokens('llm.tokens.input');
+                u.output += tokens('llm.tokens.output');
+                u.thinking += tokens('llm.tokens.thinking');
+                s.usage.set(model, u);
+            }
         }
         else if (isToolSpanName(span.name)) {
             statsFor(traceId).toolMs += spanDurationMs(span);
@@ -231,6 +286,7 @@ export function initializeTracing() {
     const spanProcessors = [
         new SpanLineageProcessor(),
         new SimpleSpanProcessor(new JsonConsoleExporter()),
+        new AttachedLedgerProcessor(),
     ];
     // Optional durable sink (TELEMETRY_SUPABASE=true + Supabase credentials):
     // llm.request and Syndicate Execution spans also land in adk_telemetry.
@@ -501,6 +557,8 @@ export async function* traceAgentRun(stream, metadata) {
             span.setAttribute('syndicate.latency.tool_ms', Math.round(stats.toolMs));
             span.setAttribute('syndicate.llm_calls', stats.llmCalls);
             span.setAttribute('syndicate.models', [...stats.models].sort().join(','));
+            // The ledger prices the turn from this, per model (melchizedek_usage_cost, ADR 0136).
+            span.setAttribute('syndicate.usage', JSON.stringify(Object.fromEntries([...stats.usage].sort(([a], [b]) => a.localeCompare(b)))));
         }
         try {
             for (const [key, value] of Object.entries(metadata.onEnd?.() ?? {})) {

package/dist/lib/paths.d.ts

@@ -0,0 +1,31 @@
+/**
+ * lib/paths.ts — where the engine writes on disk (ADR 0134).
+ *
+ * Each location keeps its own variable, which wins. Without one, the
+ * default is under MELCHIZEDEK_DATA_DIR when that is set, so an embedding
+ * application points every location at its own data directory with one
+ * variable; with neither, the defaults are the historical ones (the working
+ * directory's outputs/, and ~/.melchizedek for the ChatGPT sign-in).
+ *
+ *   location               own variable                     with MELCHIZEDEK_DATA_DIR   default
+ *   generated files, spool OUTPUTS_DIR                      <data>/outputs              <cwd>/outputs
+ *   task lists and jobs    MELCHIZEDEK_TASKS_FILE           <data>/outputs/tasks.json   <cwd>/outputs/tasks.json
+ *   ChatGPT sign-in        MELCHIZEDEK_CHATGPT_SIGNIN_FILE  <data>/chatgpt-signin.json  ~/.melchizedek/chatgpt-signin.json
+ *
+ * Read at each call, never cached. Imports only node built-ins.
+ */
+export declare const DATA_DIR_ENV = "MELCHIZEDEK_DATA_DIR";
+/** MELCHIZEDEK_DATA_DIR, resolved; undefined when unset. */
+export declare function dataDir(env?: NodeJS.ProcessEnv): string | undefined;
+/** Where generated files (images) and the telemetry spool go. */
+export declare function outputsDir(env?: NodeJS.ProcessEnv): string;
+/** The task tools' JSON file, when tasks are not in Postgres. */
+export declare function tasksFile(env?: NodeJS.ProcessEnv): string;
+/** The local Sign in with ChatGPT credential file. */
+export declare function chatGptSignInFile(env?: NodeJS.ProcessEnv): string;
+/**
+ * The engine's own package root (the directory of its package.json named
+ * melchizedek-agents), found from this module's location, whatever the
+ * working directory is; undefined if it cannot be found.
+ */
+export declare function enginePackageRoot(from?: string): string | undefined;

package/dist/lib/paths.js

@@ -0,0 +1,76 @@
+/**
+ * lib/paths.ts — where the engine writes on disk (ADR 0134).
+ *
+ * Each location keeps its own variable, which wins. Without one, the
+ * default is under MELCHIZEDEK_DATA_DIR when that is set, so an embedding
+ * application points every location at its own data directory with one
+ * variable; with neither, the defaults are the historical ones (the working
+ * directory's outputs/, and ~/.melchizedek for the ChatGPT sign-in).
+ *
+ *   location               own variable                     with MELCHIZEDEK_DATA_DIR   default
+ *   generated files, spool OUTPUTS_DIR                      <data>/outputs              <cwd>/outputs
+ *   task lists and jobs    MELCHIZEDEK_TASKS_FILE           <data>/outputs/tasks.json   <cwd>/outputs/tasks.json
+ *   ChatGPT sign-in        MELCHIZEDEK_CHATGPT_SIGNIN_FILE  <data>/chatgpt-signin.json  ~/.melchizedek/chatgpt-signin.json
+ *
+ * Read at each call, never cached. Imports only node built-ins.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const DATA_DIR_ENV = 'MELCHIZEDEK_DATA_DIR';
+const set = (env, name) => env[name]?.trim() || undefined;
+/** MELCHIZEDEK_DATA_DIR, resolved; undefined when unset. */
+export function dataDir(env = process.env) {
+    const d = set(env, DATA_DIR_ENV);
+    return d ? resolve(d) : undefined;
+}
+/** Where generated files (images) and the telemetry spool go. */
+export function outputsDir(env = process.env) {
+    const own = set(env, 'OUTPUTS_DIR');
+    if (own)
+        return resolve(own);
+    const data = dataDir(env);
+    return data ? join(data, 'outputs') : join(process.cwd(), 'outputs');
+}
+/** The task tools' JSON file, when tasks are not in Postgres. */
+export function tasksFile(env = process.env) {
+    const own = set(env, 'MELCHIZEDEK_TASKS_FILE');
+    if (own)
+        return resolve(own);
+    const data = dataDir(env);
+    return data ? join(data, 'outputs', 'tasks.json') : join(process.cwd(), 'outputs', 'tasks.json');
+}
+/** The local Sign in with ChatGPT credential file. */
+export function chatGptSignInFile(env = process.env) {
+    const own = set(env, 'MELCHIZEDEK_CHATGPT_SIGNIN_FILE');
+    if (own)
+        return resolve(own);
+    const data = dataDir(env);
+    return data ? join(data, 'chatgpt-signin.json') : join(homedir(), '.melchizedek', 'chatgpt-signin.json');
+}
+/**
+ * The engine's own package root (the directory of its package.json named
+ * melchizedek-agents), found from this module's location, whatever the
+ * working directory is; undefined if it cannot be found.
+ */
+export function enginePackageRoot(from = fileURLToPath(import.meta.url)) {
+    let dir = dirname(from);
+    for (let i = 0; i < 6; i++) {
+        const pkg = join(dir, 'package.json');
+        if (existsSync(pkg)) {
+            try {
+                if (JSON.parse(readFileSync(pkg, 'utf-8')).name === 'melchizedek-agents')
+                    return dir;
+            }
+            catch {
+                /* not ours; keep climbing */
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}

package/dist/lib/runtime/credentials.d.ts

@@ -57,6 +57,27 @@ export declare function consentFrom(author: string | undefined, call: {
  * message a grant (as pendingQuestion reads ask_user).
  */
 export declare function pendingConsent(events: readonly Event[]): PendingConsent | undefined;
+/**
+ * The `adk_request_credential` call a pending request stands for, rebuilt
+ * from what the request carries (ADR 0128): the shape consentFrom reads,
+ * with the request's id, the paused call's id, the provider, the
+ * authorization URL, the state and the scopes. A workflow node raises it
+ * again on its caller's walk when the request itself waits below it (in a
+ * delegated call, or in a nested dispatch syndicate's conversation). It
+ * carries what the stored request carries and nothing more: no client
+ * secret, no code verifier.
+ */
+export declare function credentialRequestCall(consent: PendingConsent): {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+};
+/**
+ * Whether `value`, a walk's answer to a credential request, is a grant's
+ * answer (credentialResponsePart's response): `{ credentialKey, granted: true }`.
+ * A plain-text message the walk read as the answer is not one.
+ */
+export declare function isGrantAnswer(value: unknown): boolean;
 /**
  * The message part that answers request `id` once the grant is stored. It
  * names the provider and carries no credential: the grant is in the