melchizedek-agents 1.7.0 → 1.10.0

package/dist/lib/project.js

@@ -0,0 +1,274 @@
+/**
+ * lib/project.ts — the project manifest, `melchizedek.json` (ADR 0138).
+ *
+ * A project is a folder, usually a git repository, with a `melchizedek.json`
+ * at its root. The manifest records what the engine cannot infer from the
+ * files: which folder holds the syndicates, which engine version the project
+ * is written for, and how each file ships. It holds names, never values: an
+ * `env` entry is a variable name, and no field may carry a secret.
+ *
+ * `findProject()` walks up from a directory to the nearest manifest and stops
+ * at the repository root (the first directory holding `.git`) or the home
+ * directory, so a manifest outside the repository never steers it.
+ * `resolveAgentsDir()` is the one agents-directory chain every loader and bin
+ * uses: explicit option → MELCHIZEDEK_AGENTS_DIR → the manifest's `agents` →
+ * <cwd>/config/agents. A deployed server sets the variable, so the manifest
+ * only changes what a bare command run inside a project finds.
+ *
+ * Imports only node built-ins, zod and lib/paths.ts.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { z } from 'zod';
+import { enginePackageRoot } from './paths.js';
+export const PROJECT_MANIFEST = 'melchizedek.json';
+export const MANIFEST_VERSION = 1;
+/** A path relative to the project root: no absolute paths, no `..` segments. */
+const relPath = z
+    .string()
+    .min(1)
+    .refine((p) => !/^([a-zA-Z]:)?[\\/]/.test(p) && !p.split(/[\\/]/).includes('..'), 'must be relative to the project root and stay inside it');
+const envName = z.string().regex(/^[A-Z][A-Z0-9_]{0,63}$/, 'must be an environment variable name');
+const syndicateRecord = z
+    .object({
+    deliverable: z.enum(['service', 'library', 'mcp']).optional(),
+    publish: z.object({ kind: z.literal('registry'), id: z.string().min(1) }).passthrough().optional(),
+})
+    .passthrough();
+export const projectManifestSchema = z
+    .object({
+    manifest: z.number().int().min(1),
+    engine: z.string().regex(/^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/, 'must be an exact version, e.g. 1.10.0'),
+    agents: relPath,
+    ignore: z.array(z.string().min(1)).optional(),
+    tests: relPath.optional(),
+    env: z.array(envName).optional(),
+    syndicates: z.record(z.string(), syndicateRecord).optional(),
+    registry: z
+        .object({ kind: z.literal('supabase'), url_env: envName.optional(), restart: z.string().optional() })
+        .passthrough()
+        .optional(),
+    production: z
+        .object({ ledger: z.object({ kind: z.literal('postgres'), url_env: envName }).passthrough().optional() })
+        .passthrough()
+        .optional(),
+    tools: z
+        .object({ remote: z.record(z.string(), z.object({ mcp_env: envName }).passthrough()).optional() })
+        .passthrough()
+        .optional(),
+})
+    // Unknown keys are kept: a newer writer's fields survive an older reader.
+    .passthrough();
+/** Thrown for a manifest that does not parse or validate; names the file and fields, never a value. */
+export class ProjectManifestError extends Error {
+    file;
+    issues;
+    constructor(file, issues) {
+        super(`${file}: ${issues.join('; ')}`);
+        this.file = file;
+        this.issues = issues;
+        this.name = 'ProjectManifestError';
+    }
+}
+/**
+ * The nearest folder at or above `from` holding a manifest, without crossing
+ * the repository root or the home directory. Undefined when there is none.
+ */
+export function findProjectRoot(from = process.cwd()) {
+    const home = resolve(homedir());
+    let dir = resolve(from);
+    for (;;) {
+        if (existsSync(join(dir, PROJECT_MANIFEST)))
+            return dir;
+        if (existsSync(join(dir, '.git')) || dir === home)
+            return undefined;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/** Parse and validate a manifest's text. Throws `ProjectManifestError`. */
+export function parseProjectManifest(text, file = PROJECT_MANIFEST) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        throw new ProjectManifestError(file, ['not valid JSON']);
+    }
+    const parsed = projectManifestSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new ProjectManifestError(file, parsed.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`));
+    }
+    if (parsed.data.manifest > MANIFEST_VERSION) {
+        throw new ProjectManifestError(file, [`manifest: version ${parsed.data.manifest} is newer than this engine reads (${MANIFEST_VERSION}); upgrade melchizedek-agents`]);
+    }
+    return parsed.data;
+}
+/** A path under the root, or an error when it would leave it. */
+function under(root, rel, field, file) {
+    const abs = resolve(root, rel);
+    if (abs !== root && !abs.startsWith(root + sep))
+        throw new ProjectManifestError(file, [`${field}: resolves outside the project root`]);
+    return abs;
+}
+/** Load the project rooted at `root` (the folder holding the manifest). Throws `ProjectManifestError`. */
+export function loadProject(root) {
+    const r = resolve(root);
+    const file = join(r, PROJECT_MANIFEST);
+    const manifest = parseProjectManifest(readFileSync(file, 'utf-8'), file);
+    return {
+        root: r,
+        file,
+        manifest,
+        agentsDir: under(r, manifest.agents, 'agents', file),
+        testsDir: under(r, manifest.tests ?? join('tests', 'agents'), 'tests', file),
+    };
+}
+/** The project at or above `from`, or undefined when there is none. Throws on a broken manifest. */
+export function findProject(from = process.cwd()) {
+    const root = findProjectRoot(from);
+    return root ? loadProject(root) : undefined;
+}
+// The agents-directory chain runs on every syndicate read (an A2A route
+// reads per request), so the manifest lookup is cached per working
+// directory. A broken manifest is cached as "none" and reported by
+// `melchizedek-doctor`, never by a request path.
+const agentsDirCache = new Map();
+/** Forget cached manifest lookups (tests, and an embedder that edits the manifest in-process). */
+export function clearProjectCache() {
+    agentsDirCache.clear();
+}
+function manifestAgentsDir(cwd) {
+    if (!agentsDirCache.has(cwd)) {
+        let dir = null;
+        try {
+            dir = findProject(cwd)?.agentsDir ?? null;
+        }
+        catch {
+            dir = null;
+        }
+        agentsDirCache.set(cwd, dir);
+    }
+    return agentsDirCache.get(cwd) ?? undefined;
+}
+/**
+ * The agents directory: `explicit` → MELCHIZEDEK_AGENTS_DIR → the nearest
+ * manifest's `agents` → <cwd>/config/agents. Always absolute.
+ */
+export function resolveAgentsDir(explicit, env = process.env) {
+    const fromEnv = env.MELCHIZEDEK_AGENTS_DIR?.trim();
+    const cwd = process.cwd();
+    return resolve(explicit ?? (fromEnv || undefined) ?? manifestAgentsDir(cwd) ?? join(cwd, 'config', 'agents'));
+}
+/** Glob to RegExp for `*` (one segment), `**` (any depth) and `?`, on `/`-separated paths. */
+function globToRegExp(glob) {
+    let re = '';
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob[i];
+        if (c === '*') {
+            if (glob[i + 1] === '*') {
+                i++;
+                if (glob[i + 1] === '/') {
+                    i++;
+                    re += '(?:.*/)?';
+                }
+                else
+                    re += '.*';
+            }
+            else
+                re += '[^/]*';
+        }
+        else if (c === '?')
+            re += '[^/]';
+        else
+            re += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    }
+    return new RegExp(`^${re}$`);
+}
+/** True when `relFromRoot` (a `/`-separated path relative to the project root) matches an `ignore` pattern. */
+export function isIgnored(project, relFromRoot) {
+    const p = relFromRoot.split(sep).join('/');
+    return (project.manifest.ignore ?? []).some((g) => globToRegExp(g).test(p));
+}
+/** The syndicate files directly in the agents folder, as names relative to it, minus `ignore`. */
+export function listProjectSyndicates(project) {
+    if (!existsSync(project.agentsDir))
+        return [];
+    const rel = relative(project.root, project.agentsDir);
+    return readdirSync(project.agentsDir)
+        .filter((f) => (f.endsWith('.yaml') || f.endsWith('.yml')) && f !== 'syndicateSchema.yaml')
+        .filter((f) => statSync(join(project.agentsDir, f)).isFile())
+        .filter((f) => !isIgnored(project, rel ? `${rel}/${f}` : f))
+        .sort();
+}
+/** The installed engine's package version (no commit suffix). */
+export function enginePackageVersion() {
+    try {
+        const root = enginePackageRoot();
+        if (root)
+            return String(JSON.parse(readFileSync(join(root, 'package.json'), 'utf-8')).version);
+    }
+    catch {
+        /* fall through */
+    }
+    return '0.0.0';
+}
+/** What is wrong with a project: engine pin, missing folders, stale ignores, unset env names. Never reads a value. */
+export function checkProject(project, running = enginePackageVersion(), env = process.env) {
+    const problems = [];
+    const warnings = [];
+    const pinned = project.manifest.engine;
+    const matches = pinned === running;
+    if (!matches)
+        problems.push(`engine: the project pins melchizedek-agents ${pinned}; ${running} is running`);
+    if (!existsSync(project.agentsDir))
+        problems.push(`agents: ${project.manifest.agents} does not exist`);
+    if (project.manifest.tests && !existsSync(project.testsDir))
+        problems.push(`tests: ${project.manifest.tests} does not exist`);
+    for (const g of project.manifest.ignore ?? []) {
+        if (!anyPathMatches(project.root, globToRegExp(g)))
+            warnings.push(`ignore: "${g}" matches nothing`);
+    }
+    for (const name of project.manifest.env ?? [])
+        if (!env[name]?.trim())
+            warnings.push(`env: ${name} is not set`);
+    const syndicates = listProjectSyndicates(project);
+    for (const f of Object.keys(project.manifest.syndicates ?? {})) {
+        if (!syndicates.includes(f))
+            warnings.push(`syndicates: ${f} is not in ${project.manifest.agents}`);
+    }
+    return { root: project.root, agentsDir: project.agentsDir, engine: { pinned, running, matches }, syndicates, problems, warnings };
+}
+const SKIP_DIRS = new Set(['.git', 'node_modules', 'venv', '.venv', '__pycache__', 'dist']);
+/** Whether any path under root (depth-limited, skipping vendor folders) matches. */
+function anyPathMatches(root, re, rel = '', depth = 0) {
+    if (depth > 6)
+        return false;
+    let entries;
+    try {
+        entries = readdirSync(join(root, rel));
+    }
+    catch {
+        return false;
+    }
+    for (const e of entries) {
+        if (SKIP_DIRS.has(e))
+            continue;
+        const p = rel ? `${rel}/${e}` : e;
+        if (re.test(p))
+            return true;
+        let dir = false;
+        try {
+            dir = statSync(join(root, p)).isDirectory();
+        }
+        catch {
+            /* unreadable entry */
+        }
+        if (dir && anyPathMatches(root, re, p, depth + 1))
+            return true;
+    }
+    return false;
+}

package/dist/lib/runtime/native/compaction.js

@@ -144,11 +144,15 @@ export async function summarize(events, adapter, model, options = {}) {
     const startTime = events[0].timestamp;
     const endTime = events[events.length - 1].timestamp;
     const request = summaryRequest(events, model, options.signal);
+    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;
+        }
     }
-    const responses = traceLlmGeneration({ provider: adapter.provider, model, request }, inner());
+    const responses = traceLlmGeneration({ provider: adapter.provider, model, request, source: (r) => sources.get(r) }, inner());
     // As ADK: the first response must carry text; nothing after a failure is read.
     const first = await responses.next();
     const head = first.done ? undefined : first.value.content?.parts?.[0]?.text;

package/dist/lib/runtime/native/request.d.ts

@@ -112,6 +112,8 @@ export interface NativeAgent {
     mode?: 'task';
     /** The session-state key the agent's final answer is saved under (the loop writes it, lib/runtime/native/agentLoop.ts). */
     outputKey?: string;
+    /** The YAML's `metadata:` (ADR 0141): `meta.agent.<key>` attributes on the agent's `agent.invoke` span. */
+    metadata?: Record<string, string | number | boolean>;
     /** `fallback_model:`: answers a provider-side failure of the agent's model (ADR 0044). The loop calls it as its own leaf adapter. */
     fallbackModel?: string;
     /** `context:` (ADR 0033): compact the history into a summary past a token threshold. The loop runs it before each step (compaction.ts). */

package/dist/lib/runtime/native/step.js

@@ -218,7 +218,7 @@ export async function runModelStep(options) {
         return { ...result, event: stored, error: { code, message, retryable: false } };
     }
     async function readResponses() {
-        for await (const traced of traceLlmGeneration({ provider: adapter.provider, model: request.model, request }, inner())) {
+        for await (const traced of traceLlmGeneration({ provider: adapter.provider, model: request.model, request, source: (r) => sources.get(r) }, inner())) {
             if (signal?.aborted)
                 return { ...result, stopped: stopOf() };
             const source = sources.get(traced);

package/dist/lib/runtime/native/telemetry.d.ts

@@ -30,8 +30,12 @@
  *   adapter's final response). A failed step carries none: its llm.request
  *   span carries the failed call's payload, as under ADK, where a failed
  *   call_llm never ended. With TELEMETRY_PAYLOADS=off no payload is
- *   recorded at all. Tool spans carry no arguments and no results: the root
- *   span's ToolCall/ToolResponse events are where the ledger keeps those.
+ *   recorded at all. A tool span carries its call's arguments (`tool.args`)
+ *   and the start of its result (`tool.result`), each as JSON, redacted by
+ *   the telemetry redactor and cut at TOOL_ATTRIBUTE_MAX_CHARS
+ *   (`tool.args_truncated` / `tool.result_truncated` when cut), so the
+ *   ledger's span tree shows a call without the payload tier (ADR 0139). The
+ *   root span's ToolCall/ToolResponse events still hold the whole of both.
  *
  * The loop calls three hooks (agentLoop.ts): traceAgentInvocation around the
  * whole run, traceModelCall around each step, traceToolCall around each call.
@@ -41,8 +45,10 @@ import type { AgentLoopContext, AgentLoopEnd } from './agentLoop.ts';
 import type { NativeAgent } from './request.ts';
 import type { ModelStepResult } from './step.ts';
 import type { NodeResult, TracedNode } from '../../workflow/scheduler.ts';
+/** The most a tool span's `tool.args` or `tool.result` holds: the first 8 KB of its redacted JSON (ADR 0139). */
+export declare const TOOL_ATTRIBUTE_MAX_CHARS = 8192;
 /** The agent's run as an `agent.invoke <name>` span, opened when the run starts. */
-export declare function traceAgentInvocation(agent: Pick<NativeAgent, 'name' | 'description'>, ctx: Pick<AgentLoopContext, 'session' | 'invocationId'>, run: () => AsyncGenerator<TurnEvent, AgentLoopEnd>): AsyncGenerator<TurnEvent, AgentLoopEnd>;
+export declare function traceAgentInvocation(agent: Pick<NativeAgent, 'name' | 'description' | 'metadata'>, ctx: Pick<AgentLoopContext, 'session' | 'invocationId'>, run: () => AsyncGenerator<TurnEvent, AgentLoopEnd>): AsyncGenerator<TurnEvent, AgentLoopEnd>;
 /**
  * One model step as a `model.call` span. `step` gets the loop's context with
  * an `adapterFor` that notes the adapter it hands out, so the span names the
@@ -72,4 +78,5 @@ export declare function traceNodeExecution(node: TracedNode, run: () => Promise<
 export declare function traceToolNodeCall<T>(call: {
     id: string;
     name: string;
+    args?: unknown;
 }, tool: unknown, run: () => Promise<T>): Promise<T>;

package/dist/lib/runtime/native/telemetry.js

@@ -30,8 +30,12 @@
  *   adapter's final response). A failed step carries none: its llm.request
  *   span carries the failed call's payload, as under ADK, where a failed
  *   call_llm never ended. With TELEMETRY_PAYLOADS=off no payload is
- *   recorded at all. Tool spans carry no arguments and no results: the root
- *   span's ToolCall/ToolResponse events are where the ledger keeps those.
+ *   recorded at all. A tool span carries its call's arguments (`tool.args`)
+ *   and the start of its result (`tool.result`), each as JSON, redacted by
+ *   the telemetry redactor and cut at TOOL_ATTRIBUTE_MAX_CHARS
+ *   (`tool.args_truncated` / `tool.result_truncated` when cut), so the
+ *   ledger's span tree shows a call without the payload tier (ADR 0139). The
+ *   root span's ToolCall/ToolResponse events still hold the whole of both.
  *
  * The loop calls three hooks (agentLoop.ts): traceAgentInvocation around the
  * whole run, traceModelCall around each step, traceToolCall around each call.
@@ -40,9 +44,39 @@ import { SpanStatusCode, context, trace } from '@opentelemetry/api';
 import { resolveAdapter } from '../../models/registry.js';
 import { RUNTIME_SPAN_SCOPE } from '../../observability/lineage.js';
 import { payloadPolicyFromEnv } from '../../observability/supabaseSpanExporter.js';
+import { telemetryRedactor } from '../../observability/redact.js';
+import { META_AGENT_PREFIX, metaAttributes } from '../../observability/metadata.js';
 import { startEngineSpan } from '../../observability/tracer.js';
 /** The most a payload attribute holds, as for a failed call's (lib/observability/tracer.ts). */
 const PAYLOAD_MAX_CHARS = 200_000;
+/** The most a tool span's `tool.args` or `tool.result` holds: the first 8 KB of its redacted JSON (ADR 0139). */
+export const TOOL_ATTRIBUTE_MAX_CHARS = 8_192;
+/**
+ * Sets `key` to `value` as JSON, redacted first (so a cut never splits a
+ * secret the redactor would have caught) and then cut to the cap, with
+ * `<key>_truncated` when it was cut. Nothing on a span that records nothing.
+ */
+function setToolContent(span, key, value) {
+    if (!span.isRecording() || value === undefined)
+        return;
+    let json;
+    try {
+        json = typeof value === 'string' ? value : (JSON.stringify(value) ?? String(value));
+    }
+    catch {
+        json = String(value);
+    }
+    const redactor = telemetryRedactor();
+    if (redactor)
+        json = redactor(json);
+    if (json.length > TOOL_ATTRIBUTE_MAX_CHARS) {
+        span.setAttribute(key, json.slice(0, TOOL_ATTRIBUTE_MAX_CHARS));
+        span.setAttribute(`${key}_truncated`, true);
+    }
+    else {
+        span.setAttribute(key, json);
+    }
+}
 /** A loop span in scope melchizedek.runtime; a non-recording one in a turn that opted out of tracing. */
 const startRuntimeSpan = (name, options) => startEngineSpan(RUNTIME_SPAN_SCOPE, name, options);
 /** JSON that never throws and never exceeds the cap. */
@@ -93,6 +127,8 @@ export async function* traceAgentInvocation(agent, ctx, run) {
             'gen_ai.agent.description': agent.description ?? '',
             'gen_ai.conversation.id': ctx.session.id,
             'adk.invocation_id': ctx.invocationId,
+            // The YAML's agent metadata (ADR 0141), redacted as every ledger value is.
+            ...metaAttributes(agent.metadata, META_AGENT_PREFIX),
         },
     });
     try {
@@ -158,8 +194,10 @@ function recordModelCall(span, result, provider) {
         span.setAttribute('gen_ai.usage.input_tokens', response.usage.inputTokens);
         span.setAttribute('gen_ai.usage.output_tokens', response.usage.outputTokens);
     }
-    if (response?.finishReason)
+    if (response?.finishReason) {
         span.setAttribute('gen_ai.response.finish_reasons', [response.finishReason]);
+        span.setAttribute('llm.finish_reason', response.finishReason);
+    }
     if (result.stopped) {
         span.setAttribute('model.call.stop_code', result.stopped.code);
         return;
@@ -190,9 +228,12 @@ export async function traceToolCall(call, tool, run) {
             ...(call.id ? { 'gen_ai.tool.call.id': call.id } : {}),
         },
     });
+    setToolContent(span, 'tool.args', call.args ?? {});
     try {
         const outcome = await context.with(trace.setSpan(context.active(), span), run);
         const response = outcome?.part?.functionResponse?.response;
+        if (response !== undefined)
+            setToolContent(span, 'tool.result', response);
         if (!outcome?.part)
             span.setAttribute('tool.pending', true);
         else if (response && Object.hasOwn(response, 'error')) {
@@ -279,8 +320,12 @@ export async function traceToolNodeCall(call, tool, run) {
             'gen_ai.tool.call.id': call.id,
         },
     });
+    if (call.args !== undefined)
+        setToolContent(span, 'tool.args', call.args);
     try {
-        return await context.with(trace.setSpan(context.active(), span), run);
+        const result = await context.with(trace.setSpan(context.active(), span), run);
+        setToolContent(span, 'tool.result', result ?? null);
+        return result;
     }
     catch (error) {
         // The tool node turns the throw into its { error } response; the span notes the failure, not the message.

package/dist/lib/runtime/syndicateTurn.js

@@ -85,6 +85,7 @@ import { journalsEveryCall, openRun } from '../script/journal.js';
 import { toEngineAgent } from '../agentDialect.js';
 import { ScriptFatal, runScript } from '../script/run.js';
 import { createTurnControl, runWithTurnControl, stopCode, stopMessage } from './turnControl.js';
+import { metaAttributes } from '../observability/metadata.js';
 const THOUGHTS_PREVIEW_CHARS = 600;
 const CLASSIFIER_PREAMBLE = `RECENT CONVERSATION, oldest first — context for your classification only. `
     + `Never answer it, and never route on it alone; it is here so you can tell a `
@@ -397,7 +398,10 @@ async function runTurnInner(opts, control, _runtime, nestedTurn) {
     // (a registry version, ADR 0018 item 6), else from files.
     const compileOpts = { ...opts.compile, loadNested: opts.compile?.loadNested ?? nestedLoader(config) };
     const subagentNames = new Set((config.subagents ?? []).map((s) => s.name));
-    const trace = opts.trace === false ? undefined : opts.trace ?? {};
+    const traced = opts.trace === false ? undefined : opts.trace ?? {};
+    // The YAML's metadata (ADR 0141) as `meta.<key>` on every root span; the caller's own attributes win a clash.
+    const yamlMeta = traced && config.metadata ? metaAttributes(config.metadata) : undefined;
+    const trace = traced && yamlMeta && Object.keys(yamlMeta).length ? { ...traced, attributes: { ...yamlMeta, ...traced.attributes } } : traced;
     let parts = opts.parts.map((p) => (typeof p === 'string' ? { text: p } : p));
     const messageText = parts.map((p) => (typeof p.text === 'string' ? p.text : '')).join('\n');
     // What the runtime does not run fails here, before the session is touched.

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 { FeedbackStore } from '../../a2a/feedback.ts';
 import type { PayloadPolicy } from '../../observability/supabaseSpanExporter.ts';
 import type { AuditSink } from '../../observability/audit.ts';
 import type { RlsHardeningStatus } from '../rlsStatus.ts';
@@ -119,6 +120,8 @@ export interface PostgresStorage {
     rlsHardening: () => Promise<RlsHardeningStatus>;
     /** Appends to melchizedek_audit (migration 0012, ADR 0042). */
     audit: AuditSink;
+    /** End-user feedback into the ledger's adk_labels (POST /feedback, ADR 0140); present when `ledger` is on. */
+    feedback?: FeedbackStore;
     /** Tool credentials, sealed (migration 0013, ADR 0072); present when `credentials` was given. */
     credentials?: CredentialStore;
     /**
@@ -129,6 +132,13 @@ export interface PostgresStorage {
     turnLock: TurnLock;
     /** The task tools' lists and job queue (lib/tools/taskTools.ts setTaskBackend). */
     taskQueue: TaskBackend;
+    /**
+     * Puts a failed or cancelled background job back on the queue, attempts
+     * reset (the Retry of an operator's queue view, melchizedek_task_queue,
+     * migration 0018). Ids are per owner, so the owner names the list.
+     * 'not-found' and 'not-retryable' leave the queue as it was.
+     */
+    retryTask: (owner: string, id: string) => Promise<'queued' | 'not-found' | 'not-retryable'>;
     /**
      * Task leases: renew this instance's, fail other instances' expired ones,
      * and list this instance's running tasks a caller asked another instance

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

@@ -24,6 +24,8 @@ 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 { postgresFeedbackStore } from '../../a2a/feedback.js';
+import { applyRetry } from '../../tools/taskTools.js';
 import { createHash, randomUUID } from 'node:crypto';
 import { hostname } from 'node:os';
 export { PostgresSessionService } from './sessionService.js';
@@ -114,6 +116,7 @@ export function postgresStorage(options) {
         ? attachLedger(postgresLedgerClient(pool), options.ledger === true ? {} : options.ledger)
         : undefined;
     const audit = postgresAuditSink(pool);
+    const taskQueue = postgresTaskBackend(pool, options.taskQueue);
     const credentials = options.credentials ? postgresCredentialStore(pool, { ...options.credentials, audit }) : undefined;
     return {
         pool,
@@ -121,6 +124,7 @@ export function postgresStorage(options) {
         turnLock,
         ...(credentials ? { credentials } : {}),
         ...(memoryService ? { memoryService } : {}),
+        ...(options.ledger ? { feedback: postgresFeedbackStore(pool) } : {}),
         taskStore: (agentId) => new PostgresTaskStore(pool, agentId, { ttlDays: options.ttlDays, ownerResolver: options.taskOwner, lease }),
         leases: {
             ...lease,
@@ -128,7 +132,8 @@ export function postgresStorage(options) {
             reap: () => reapExpiredTasks(pool),
             cancelRequested: () => cancelRequestedTasks(pool, lease),
         },
-        taskQueue: postgresTaskBackend(pool, options.taskQueue),
+        taskQueue,
+        retryTask: (owner, id) => taskQueue.mutate(owner, (store) => applyRetry(store, id)),
         async schemaVersion() {
             try {
                 const r = await pool.query('SELECT max(version) AS v FROM melchizedek_schema_version');

package/dist/lib/syndicateSchema.d.ts

@@ -245,6 +245,7 @@ export declare const agentSchema: z.ZodObject<{
         }>>;
         delegates: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
 }, z.core.$strict>;
 /**
  * Model and instruction are optional at the type level because a nested
@@ -462,6 +463,7 @@ export declare const subagentSchema: z.ZodObject<{
         }>>;
         delegates: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
     description: z.ZodString;
     model: z.ZodOptional<z.ZodString>;
     instruction: z.ZodOptional<z.ZodString>;
@@ -685,6 +687,7 @@ export declare const syndicateSchema: z.ZodObject<{
             }>>;
             delegates: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
     }, z.core.$strict>;
     subagents: z.ZodOptional<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -896,6 +899,7 @@ export declare const syndicateSchema: z.ZodObject<{
             }>>;
             delegates: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
         description: z.ZodString;
         model: z.ZodOptional<z.ZodString>;
         instruction: z.ZodOptional<z.ZodString>;
@@ -945,6 +949,7 @@ export declare const syndicateSchema: z.ZodObject<{
         model_errors: z.ZodOptional<z.ZodNumber>;
         tool_errors: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
     variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
     memory_system: z.ZodOptional<z.ZodEnum<{
         "internal-only": "internal-only";

package/dist/lib/syndicateSchema.js

@@ -27,6 +27,7 @@ import { isSecretShapedEnvName } from './tools/skills/env.js';
 import { OAUTH_SCOPE, PROVIDER_NAME } from './tools/auth.js';
 import { V2_AGENT_KEYS, conflictMessage, conflictsOf, toEngineAgent } from './agentDialect.js';
 import { MCP_TRANSPORTS } from './tools/mcpTransports.js';
+import { MAX_META_KEYS, MAX_META_VALUE_CHARS, META_KEY } from './observability/metadata.js';
 // ── Leaf rules ───────────────────────────────────────────────────────────────
 /**
  * ADK's agent-name rule (validateAgentName in ADK's base_agent), kept: checked here
@@ -337,6 +338,12 @@ const openapiEntry = z
         .describe('Credentials, always from the environment, never written in YAML.'),
 })
     .describe('An HTTP API as tools, from its OpenAPI spec (lib/tools/openapiTools.ts).');
+// ── Metadata (ADR 0141) ──────────────────────────────────────────────────────
+/** Static labels copied onto the turn's spans as `meta.*` attributes (lib/observability/metadata.ts). */
+const metadataSchema = (where) => z
+    .record(z.string().regex(META_KEY, 'a metadata key is letters, digits and _ . : - (at most 64, not starting with . : -)'), z.union([z.string().max(MAX_META_VALUE_CHARS), z.number(), z.boolean()]))
+    .refine((m) => Object.keys(m).length <= MAX_META_KEYS, { message: `at most ${MAX_META_KEYS} metadata keys` })
+    .describe(`Labels for the ledger: strings (at most ${MAX_META_VALUE_CHARS} characters), numbers or booleans, at most ${MAX_META_KEYS} keys. ${where} A value shaped like a key or token is dropped at load with a warning; string values pass through the telemetry redactor (ADR 0141).`);
 // ── Agents ───────────────────────────────────────────────────────────────────
 const agentFields = {
     name: agentName,
@@ -440,6 +447,7 @@ const agentFields = {
         delegates: z.array(z.string()).optional(),
     })
         .optional(),
+    metadata: metadataSchema('Each becomes `meta.agent.<key>` on this agent\'s agent.invoke span.').optional(),
 };
 export const agentSchema = z
     .strictObject(agentFields)
@@ -583,6 +591,7 @@ export const syndicateSchema = z
     })
         .optional()
         .describe('Self-correction on model and tool errors: the engine\'s reflect-and-retry. On by default.'),
+    metadata: metadataSchema('Each becomes `meta.<key>` on every turn\'s root span, so on the ledger row (adk_turns.attributes); a key the YAML names cannot be set by an A2A caller.').optional(),
     variables: z
         .record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
         .optional()
@@ -1391,6 +1400,10 @@ export function syndicateJsonSchema() {
             if (ctx.zodSchema === samplingSchema || ctx.zodSchema === outputSchemaV2) {
                 ctx.jsonSchema.minProperties = 1;
             }
+            // metadata: (ADR 0141): the key-count refinement, which JSON Schema says as maxProperties.
+            if (ctx.jsonSchema.propertyNames?.pattern === META_KEY.source) {
+                ctx.jsonSchema.maxProperties = MAX_META_KEYS;
+            }
             if (ctx.zodSchema === modelOverrideEntry) {
                 ctx.jsonSchema.oneOf = [{ required: ['instruction'] }, { required: ['instruction_append'] }];
             }

package/dist/lib/tools/taskTools.d.ts

@@ -180,6 +180,12 @@ export declare function claimNextJob(): TaskRecord | null;
 export declare function finishJob(id: string, outcome: JobOutcome): void;
 /** The outcome rule, on a snapshot (every backend). */
 export declare function applyFinish(store: TaskStore, id: string, outcome: JobOutcome): void;
+/**
+ * The retry rule (every backend; an operator's Retry and task_update's
+ * `queued` alike): a failed or cancelled background job goes back to the
+ * queue with its attempts reset. Anything else is left alone.
+ */
+export declare function applyRetry(store: TaskStore, id: string): 'queued' | 'not-found' | 'not-retryable';
 /** The interrupted-job rule for one record: back to the queue, or failed. */
 export declare function applyInterrupted(t: TaskRecord): 'requeued' | 'failed';
 /** The single-user JSON file, its checkpoints capped by `options` (the default backend is fileTaskBackend). */