melchizedek-agents 1.4.0 → 1.5.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.';

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

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
@@ -231,6 +275,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.

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/storage/postgres/index.d.ts

@@ -19,6 +19,7 @@ import { PostgresSessionService } from './sessionService.ts';
 import { PostgresTaskStore } from './taskStore.ts';
 import type { CredentialStoreOptions } from '../../tools/credentialStore.ts';
 import type { CredentialStore } from '../../tools/auth.ts';
+import type { PayloadPolicy } from '../../observability/supabaseSpanExporter.ts';
 import type { AuditSink } from '../../observability/audit.ts';
 import type { RlsHardeningStatus } from '../rlsStatus.ts';
 import type { TaskBackend, TaskBackendOptions } from '../../tools/taskTools.ts';
@@ -28,6 +29,8 @@ export { PostgresSessionService } from './sessionService.ts';
 export { PostgresTaskStore } from './taskStore.ts';
 export { postgresMemoryStore } from './memoryStore.ts';
 export { postgresCredentialRows, postgresCredentialStore } from './credentialStore.ts';
+export { inProcessTurnLock } from '../../a2a/turnLock.ts';
+export type { TurnLock } from '../../a2a/turnLock.ts';
 export interface PostgresStorageOptions {
     /** A Postgres URL. Ignored when `pool` is given. */
     connectionString?: string;
@@ -54,6 +57,28 @@ export interface PostgresStorageOptions {
     };
     /** Owner of an A2A call, for the task store. Default: the SDK's user scope. */
     taskOwner?: PostgresTaskStoreOptions['ownerResolver'];
+    /**
+     * The turn lock to use instead of the advisory lock below. The advisory
+     * lock is what makes several instances on one database take turns; it
+     * needs a database that gives each connection its own session. Embedded
+     * Postgres (PGlite behind pglite-socket) runs every connection in ONE
+     * session, where an advisory lock is re-entrant and so excludes nothing:
+     * there, one process owns the database, and `inProcessTurnLock()`
+     * (exported here) is the correct lock. When given, no turn-lock
+     * pool is opened.
+     */
+    turnLock?: TurnLock;
+    /**
+     * Write the telemetry ledger (adk_turns, adk_telemetry, adk_payloads) to
+     * this database (ADR 0131): the rows the Supabase sink writes, with the
+     * same payload policy (TELEMETRY_PAYLOADS, or `policy`) and redaction.
+     * Needs db/telemetry.sql applied. `close()` flushes and detaches it.
+     * Default off.
+     */
+    ledger?: boolean | {
+        policy?: PayloadPolicy;
+        deadLetterFile?: string;
+    };
     /**
      * Connections reserved for turn locks: each running turn holds one for its
      * length, apart from the main pool so a long turn never starves queries.

package/dist/lib/storage/postgres/index.js

@@ -22,12 +22,16 @@ import { postgresCredentialStore } from './credentialStore.js';
 import { searchPathOption } from '../schema.js';
 import { POSTGRES_RLS_QUERY, evaluatePostgresRls } from '../rlsStatus.js';
 import { postgresAuditSink } from '../../observability/audit.js';
+import { attachLedger } from '../../observability/tracer.js';
+import { postgresLedgerClient } from '../../observability/supabaseSpanExporter.js';
 import { createHash, randomUUID } from 'node:crypto';
 import { hostname } from 'node:os';
 export { PostgresSessionService } from './sessionService.js';
 export { PostgresTaskStore } from './taskStore.js';
 export { postgresMemoryStore } from './memoryStore.js';
 export { postgresCredentialRows, postgresCredentialStore } from './credentialStore.js';
+// The single-process turn lock, for an embedded database (`turnLock` below).
+export { inProcessTurnLock } from '../../a2a/turnLock.js';
 /**
  * A pool emits 'error' when an idle connection dies (a database restart, a
  * failover, an administrator's terminate); unhandled, that event crashes the
@@ -69,7 +73,7 @@ export function postgresStorage(options) {
         ...(options.pool ? options.pool.options : { connectionString: options.connectionString, ...options.poolConfig }),
         max: options.lockPoolMax ?? 20,
     }), 'turn-lock pool'));
-    const turnLock = async (key, { waitMs, signal }) => {
+    const advisoryTurnLock = async (key, { waitMs, signal }) => {
         const lockId = advisoryLockId(key);
         const client = await locks().connect();
         const deadline = Date.now() + Math.max(0, waitMs);
@@ -105,6 +109,10 @@ export function postgresStorage(options) {
         };
         return release;
     };
+    const turnLock = options.turnLock ?? advisoryTurnLock;
+    const detachLedger = options.ledger
+        ? attachLedger(postgresLedgerClient(pool), options.ledger === true ? {} : options.ledger)
+        : undefined;
     const audit = postgresAuditSink(pool);
     const credentials = options.credentials ? postgresCredentialStore(pool, { ...options.credentials, audit }) : undefined;
     return {
@@ -160,6 +168,7 @@ export function postgresStorage(options) {
             return counts;
         },
         async close() {
+            await detachLedger?.();
             if (lockPool)
                 await lockPool.end();
             if (owned)