melchizedek-agents 1.8.0 → 1.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +131 -1
- package/DOCUMENTATION.md +66 -4
- package/README.md +2 -0
- package/config/agents/syndicate.schema.json +69 -0
- package/config/agents/syndicateSchema.yaml +17 -0
- package/db/hardening.sql +3 -1
- package/db/migrations/0016_span_tree.sql +52 -0
- package/db/migrations/0017_cache_pricing.sql +146 -0
- package/db/migrations/0018_queue_view.sql +82 -0
- package/db/telemetry.sql +36 -8
- package/dist/lib/a2a/app.d.ts +26 -4
- package/dist/lib/a2a/app.js +41 -6
- package/dist/lib/a2a/executor.d.ts +28 -1
- package/dist/lib/a2a/executor.js +65 -2
- package/dist/lib/a2a/feedback.d.ts +121 -0
- package/dist/lib/a2a/feedback.js +219 -0
- package/dist/lib/a2a/policy.d.ts +55 -5
- package/dist/lib/a2a/policy.js +56 -12
- package/dist/lib/compile.d.ts +2 -0
- package/dist/lib/compile.js +2 -0
- package/dist/lib/compileNative.js +2 -0
- package/dist/lib/index.d.ts +5 -2
- package/dist/lib/index.js +1 -0
- package/dist/lib/loadSyndicate.d.ts +14 -0
- package/dist/lib/loadSyndicate.js +19 -1
- package/dist/lib/memory/providers.js +7 -3
- package/dist/lib/observability/lineage.d.ts +19 -0
- package/dist/lib/observability/lineage.js +31 -0
- package/dist/lib/observability/metadata.d.ts +69 -0
- package/dist/lib/observability/metadata.js +153 -0
- package/dist/lib/observability/otlpFilter.js +1 -0
- package/dist/lib/observability/supabaseSpanExporter.d.ts +31 -2
- package/dist/lib/observability/supabaseSpanExporter.js +45 -6
- package/dist/lib/observability/tracer.d.ts +17 -1
- package/dist/lib/observability/tracer.js +61 -3
- package/dist/lib/project.js +1 -1
- package/dist/lib/runtime/native/compaction.js +7 -3
- package/dist/lib/runtime/native/request.d.ts +2 -0
- package/dist/lib/runtime/native/step.js +1 -1
- package/dist/lib/runtime/native/telemetry.d.ts +10 -3
- package/dist/lib/runtime/native/telemetry.js +49 -4
- package/dist/lib/runtime/syndicateTurn.js +5 -1
- package/dist/lib/storage/postgres/index.d.ts +10 -0
- package/dist/lib/storage/postgres/index.js +6 -1
- package/dist/lib/syndicateSchema.d.ts +5 -0
- package/dist/lib/syndicateSchema.js +13 -0
- package/dist/lib/tools/taskTools.d.ts +6 -0
- package/dist/lib/tools/taskTools.js +24 -5
- package/dist/lib/workflow/toolNode.d.ts +1 -0
- package/dist/lib/workflow/toolNode.js +1 -1
- package/package.json +5 -4
|
@@ -30,8 +30,12 @@
|
|
|
30
30
|
* adapter's final response). A failed step carries none: its llm.request
|
|
31
31
|
* span carries the failed call's payload, as under ADK, where a failed
|
|
32
32
|
* call_llm never ended. With TELEMETRY_PAYLOADS=off no payload is
|
|
33
|
-
* recorded at all.
|
|
34
|
-
*
|
|
33
|
+
* recorded at all. A tool span carries its call's arguments (`tool.args`)
|
|
34
|
+
* and the start of its result (`tool.result`), each as JSON, redacted by
|
|
35
|
+
* the telemetry redactor and cut at TOOL_ATTRIBUTE_MAX_CHARS
|
|
36
|
+
* (`tool.args_truncated` / `tool.result_truncated` when cut), so the
|
|
37
|
+
* ledger's span tree shows a call without the payload tier (ADR 0139). The
|
|
38
|
+
* root span's ToolCall/ToolResponse events still hold the whole of both.
|
|
35
39
|
*
|
|
36
40
|
* The loop calls three hooks (agentLoop.ts): traceAgentInvocation around the
|
|
37
41
|
* whole run, traceModelCall around each step, traceToolCall around each call.
|
|
@@ -41,8 +45,10 @@ import type { AgentLoopContext, AgentLoopEnd } from './agentLoop.ts';
|
|
|
41
45
|
import type { NativeAgent } from './request.ts';
|
|
42
46
|
import type { ModelStepResult } from './step.ts';
|
|
43
47
|
import type { NodeResult, TracedNode } from '../../workflow/scheduler.ts';
|
|
48
|
+
/** The most a tool span's `tool.args` or `tool.result` holds: the first 8 KB of its redacted JSON (ADR 0139). */
|
|
49
|
+
export declare const TOOL_ATTRIBUTE_MAX_CHARS = 8192;
|
|
44
50
|
/** The agent's run as an `agent.invoke <name>` span, opened when the run starts. */
|
|
45
|
-
export declare function traceAgentInvocation(agent: Pick<NativeAgent, 'name' | 'description'>, ctx: Pick<AgentLoopContext, 'session' | 'invocationId'>, run: () => AsyncGenerator<TurnEvent, AgentLoopEnd>): AsyncGenerator<TurnEvent, AgentLoopEnd>;
|
|
51
|
+
export declare function traceAgentInvocation(agent: Pick<NativeAgent, 'name' | 'description' | 'metadata'>, ctx: Pick<AgentLoopContext, 'session' | 'invocationId'>, run: () => AsyncGenerator<TurnEvent, AgentLoopEnd>): AsyncGenerator<TurnEvent, AgentLoopEnd>;
|
|
46
52
|
/**
|
|
47
53
|
* One model step as a `model.call` span. `step` gets the loop's context with
|
|
48
54
|
* 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<
|
|
|
72
78
|
export declare function traceToolNodeCall<T>(call: {
|
|
73
79
|
id: string;
|
|
74
80
|
name: string;
|
|
81
|
+
args?: unknown;
|
|
75
82
|
}, tool: unknown, run: () => Promise<T>): Promise<T>;
|
|
@@ -30,8 +30,12 @@
|
|
|
30
30
|
* adapter's final response). A failed step carries none: its llm.request
|
|
31
31
|
* span carries the failed call's payload, as under ADK, where a failed
|
|
32
32
|
* call_llm never ended. With TELEMETRY_PAYLOADS=off no payload is
|
|
33
|
-
* recorded at all.
|
|
34
|
-
*
|
|
33
|
+
* recorded at all. A tool span carries its call's arguments (`tool.args`)
|
|
34
|
+
* and the start of its result (`tool.result`), each as JSON, redacted by
|
|
35
|
+
* the telemetry redactor and cut at TOOL_ATTRIBUTE_MAX_CHARS
|
|
36
|
+
* (`tool.args_truncated` / `tool.result_truncated` when cut), so the
|
|
37
|
+
* ledger's span tree shows a call without the payload tier (ADR 0139). The
|
|
38
|
+
* root span's ToolCall/ToolResponse events still hold the whole of both.
|
|
35
39
|
*
|
|
36
40
|
* The loop calls three hooks (agentLoop.ts): traceAgentInvocation around the
|
|
37
41
|
* whole run, traceModelCall around each step, traceToolCall around each call.
|
|
@@ -40,9 +44,39 @@ import { SpanStatusCode, context, trace } from '@opentelemetry/api';
|
|
|
40
44
|
import { resolveAdapter } from '../../models/registry.js';
|
|
41
45
|
import { RUNTIME_SPAN_SCOPE } from '../../observability/lineage.js';
|
|
42
46
|
import { payloadPolicyFromEnv } from '../../observability/supabaseSpanExporter.js';
|
|
47
|
+
import { telemetryRedactor } from '../../observability/redact.js';
|
|
48
|
+
import { META_AGENT_PREFIX, metaAttributes } from '../../observability/metadata.js';
|
|
43
49
|
import { startEngineSpan } from '../../observability/tracer.js';
|
|
44
50
|
/** The most a payload attribute holds, as for a failed call's (lib/observability/tracer.ts). */
|
|
45
51
|
const PAYLOAD_MAX_CHARS = 200_000;
|
|
52
|
+
/** The most a tool span's `tool.args` or `tool.result` holds: the first 8 KB of its redacted JSON (ADR 0139). */
|
|
53
|
+
export const TOOL_ATTRIBUTE_MAX_CHARS = 8_192;
|
|
54
|
+
/**
|
|
55
|
+
* Sets `key` to `value` as JSON, redacted first (so a cut never splits a
|
|
56
|
+
* secret the redactor would have caught) and then cut to the cap, with
|
|
57
|
+
* `<key>_truncated` when it was cut. Nothing on a span that records nothing.
|
|
58
|
+
*/
|
|
59
|
+
function setToolContent(span, key, value) {
|
|
60
|
+
if (!span.isRecording() || value === undefined)
|
|
61
|
+
return;
|
|
62
|
+
let json;
|
|
63
|
+
try {
|
|
64
|
+
json = typeof value === 'string' ? value : (JSON.stringify(value) ?? String(value));
|
|
65
|
+
}
|
|
66
|
+
catch {
|
|
67
|
+
json = String(value);
|
|
68
|
+
}
|
|
69
|
+
const redactor = telemetryRedactor();
|
|
70
|
+
if (redactor)
|
|
71
|
+
json = redactor(json);
|
|
72
|
+
if (json.length > TOOL_ATTRIBUTE_MAX_CHARS) {
|
|
73
|
+
span.setAttribute(key, json.slice(0, TOOL_ATTRIBUTE_MAX_CHARS));
|
|
74
|
+
span.setAttribute(`${key}_truncated`, true);
|
|
75
|
+
}
|
|
76
|
+
else {
|
|
77
|
+
span.setAttribute(key, json);
|
|
78
|
+
}
|
|
79
|
+
}
|
|
46
80
|
/** A loop span in scope melchizedek.runtime; a non-recording one in a turn that opted out of tracing. */
|
|
47
81
|
const startRuntimeSpan = (name, options) => startEngineSpan(RUNTIME_SPAN_SCOPE, name, options);
|
|
48
82
|
/** JSON that never throws and never exceeds the cap. */
|
|
@@ -93,6 +127,8 @@ export async function* traceAgentInvocation(agent, ctx, run) {
|
|
|
93
127
|
'gen_ai.agent.description': agent.description ?? '',
|
|
94
128
|
'gen_ai.conversation.id': ctx.session.id,
|
|
95
129
|
'adk.invocation_id': ctx.invocationId,
|
|
130
|
+
// The YAML's agent metadata (ADR 0141), redacted as every ledger value is.
|
|
131
|
+
...metaAttributes(agent.metadata, META_AGENT_PREFIX),
|
|
96
132
|
},
|
|
97
133
|
});
|
|
98
134
|
try {
|
|
@@ -158,8 +194,10 @@ function recordModelCall(span, result, provider) {
|
|
|
158
194
|
span.setAttribute('gen_ai.usage.input_tokens', response.usage.inputTokens);
|
|
159
195
|
span.setAttribute('gen_ai.usage.output_tokens', response.usage.outputTokens);
|
|
160
196
|
}
|
|
161
|
-
if (response?.finishReason)
|
|
197
|
+
if (response?.finishReason) {
|
|
162
198
|
span.setAttribute('gen_ai.response.finish_reasons', [response.finishReason]);
|
|
199
|
+
span.setAttribute('llm.finish_reason', response.finishReason);
|
|
200
|
+
}
|
|
163
201
|
if (result.stopped) {
|
|
164
202
|
span.setAttribute('model.call.stop_code', result.stopped.code);
|
|
165
203
|
return;
|
|
@@ -190,9 +228,12 @@ export async function traceToolCall(call, tool, run) {
|
|
|
190
228
|
...(call.id ? { 'gen_ai.tool.call.id': call.id } : {}),
|
|
191
229
|
},
|
|
192
230
|
});
|
|
231
|
+
setToolContent(span, 'tool.args', call.args ?? {});
|
|
193
232
|
try {
|
|
194
233
|
const outcome = await context.with(trace.setSpan(context.active(), span), run);
|
|
195
234
|
const response = outcome?.part?.functionResponse?.response;
|
|
235
|
+
if (response !== undefined)
|
|
236
|
+
setToolContent(span, 'tool.result', response);
|
|
196
237
|
if (!outcome?.part)
|
|
197
238
|
span.setAttribute('tool.pending', true);
|
|
198
239
|
else if (response && Object.hasOwn(response, 'error')) {
|
|
@@ -279,8 +320,12 @@ export async function traceToolNodeCall(call, tool, run) {
|
|
|
279
320
|
'gen_ai.tool.call.id': call.id,
|
|
280
321
|
},
|
|
281
322
|
});
|
|
323
|
+
if (call.args !== undefined)
|
|
324
|
+
setToolContent(span, 'tool.args', call.args);
|
|
282
325
|
try {
|
|
283
|
-
|
|
326
|
+
const result = await context.with(trace.setSpan(context.active(), span), run);
|
|
327
|
+
setToolContent(span, 'tool.result', result ?? null);
|
|
328
|
+
return result;
|
|
284
329
|
}
|
|
285
330
|
catch (error) {
|
|
286
331
|
// The tool node turns the throw into its { error } response; the span notes the failure, not the message.
|
|
@@ -85,6 +85,7 @@ import { journalsEveryCall, openRun } from '../script/journal.js';
|
|
|
85
85
|
import { toEngineAgent } from '../agentDialect.js';
|
|
86
86
|
import { ScriptFatal, runScript } from '../script/run.js';
|
|
87
87
|
import { createTurnControl, runWithTurnControl, stopCode, stopMessage } from './turnControl.js';
|
|
88
|
+
import { metaAttributes } from '../observability/metadata.js';
|
|
88
89
|
const THOUGHTS_PREVIEW_CHARS = 600;
|
|
89
90
|
const CLASSIFIER_PREAMBLE = `RECENT CONVERSATION, oldest first — context for your classification only. `
|
|
90
91
|
+ `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) {
|
|
|
397
398
|
// (a registry version, ADR 0018 item 6), else from files.
|
|
398
399
|
const compileOpts = { ...opts.compile, loadNested: opts.compile?.loadNested ?? nestedLoader(config) };
|
|
399
400
|
const subagentNames = new Set((config.subagents ?? []).map((s) => s.name));
|
|
400
|
-
const
|
|
401
|
+
const traced = opts.trace === false ? undefined : opts.trace ?? {};
|
|
402
|
+
// The YAML's metadata (ADR 0141) as `meta.<key>` on every root span; the caller's own attributes win a clash.
|
|
403
|
+
const yamlMeta = traced && config.metadata ? metaAttributes(config.metadata) : undefined;
|
|
404
|
+
const trace = traced && yamlMeta && Object.keys(yamlMeta).length ? { ...traced, attributes: { ...yamlMeta, ...traced.attributes } } : traced;
|
|
401
405
|
let parts = opts.parts.map((p) => (typeof p === 'string' ? { text: p } : p));
|
|
402
406
|
const messageText = parts.map((p) => (typeof p.text === 'string' ? p.text : '')).join('\n');
|
|
403
407
|
// What the runtime does not run fails here, before the session is touched.
|
|
@@ -19,6 +19,7 @@ import { PostgresSessionService } from './sessionService.ts';
|
|
|
19
19
|
import { PostgresTaskStore } from './taskStore.ts';
|
|
20
20
|
import type { CredentialStoreOptions } from '../../tools/credentialStore.ts';
|
|
21
21
|
import type { CredentialStore } from '../../tools/auth.ts';
|
|
22
|
+
import type { FeedbackStore } from '../../a2a/feedback.ts';
|
|
22
23
|
import type { PayloadPolicy } from '../../observability/supabaseSpanExporter.ts';
|
|
23
24
|
import type { AuditSink } from '../../observability/audit.ts';
|
|
24
25
|
import type { RlsHardeningStatus } from '../rlsStatus.ts';
|
|
@@ -119,6 +120,8 @@ export interface PostgresStorage {
|
|
|
119
120
|
rlsHardening: () => Promise<RlsHardeningStatus>;
|
|
120
121
|
/** Appends to melchizedek_audit (migration 0012, ADR 0042). */
|
|
121
122
|
audit: AuditSink;
|
|
123
|
+
/** End-user feedback into the ledger's adk_labels (POST /feedback, ADR 0140); present when `ledger` is on. */
|
|
124
|
+
feedback?: FeedbackStore;
|
|
122
125
|
/** Tool credentials, sealed (migration 0013, ADR 0072); present when `credentials` was given. */
|
|
123
126
|
credentials?: CredentialStore;
|
|
124
127
|
/**
|
|
@@ -129,6 +132,13 @@ export interface PostgresStorage {
|
|
|
129
132
|
turnLock: TurnLock;
|
|
130
133
|
/** The task tools' lists and job queue (lib/tools/taskTools.ts setTaskBackend). */
|
|
131
134
|
taskQueue: TaskBackend;
|
|
135
|
+
/**
|
|
136
|
+
* Puts a failed or cancelled background job back on the queue, attempts
|
|
137
|
+
* reset (the Retry of an operator's queue view, melchizedek_task_queue,
|
|
138
|
+
* migration 0018). Ids are per owner, so the owner names the list.
|
|
139
|
+
* 'not-found' and 'not-retryable' leave the queue as it was.
|
|
140
|
+
*/
|
|
141
|
+
retryTask: (owner: string, id: string) => Promise<'queued' | 'not-found' | 'not-retryable'>;
|
|
132
142
|
/**
|
|
133
143
|
* Task leases: renew this instance's, fail other instances' expired ones,
|
|
134
144
|
* and list this instance's running tasks a caller asked another instance
|
|
@@ -24,6 +24,8 @@ import { POSTGRES_RLS_QUERY, evaluatePostgresRls } from '../rlsStatus.js';
|
|
|
24
24
|
import { postgresAuditSink } from '../../observability/audit.js';
|
|
25
25
|
import { attachLedger } from '../../observability/tracer.js';
|
|
26
26
|
import { postgresLedgerClient } from '../../observability/supabaseSpanExporter.js';
|
|
27
|
+
import { postgresFeedbackStore } from '../../a2a/feedback.js';
|
|
28
|
+
import { applyRetry } from '../../tools/taskTools.js';
|
|
27
29
|
import { createHash, randomUUID } from 'node:crypto';
|
|
28
30
|
import { hostname } from 'node:os';
|
|
29
31
|
export { PostgresSessionService } from './sessionService.js';
|
|
@@ -114,6 +116,7 @@ export function postgresStorage(options) {
|
|
|
114
116
|
? attachLedger(postgresLedgerClient(pool), options.ledger === true ? {} : options.ledger)
|
|
115
117
|
: undefined;
|
|
116
118
|
const audit = postgresAuditSink(pool);
|
|
119
|
+
const taskQueue = postgresTaskBackend(pool, options.taskQueue);
|
|
117
120
|
const credentials = options.credentials ? postgresCredentialStore(pool, { ...options.credentials, audit }) : undefined;
|
|
118
121
|
return {
|
|
119
122
|
pool,
|
|
@@ -121,6 +124,7 @@ export function postgresStorage(options) {
|
|
|
121
124
|
turnLock,
|
|
122
125
|
...(credentials ? { credentials } : {}),
|
|
123
126
|
...(memoryService ? { memoryService } : {}),
|
|
127
|
+
...(options.ledger ? { feedback: postgresFeedbackStore(pool) } : {}),
|
|
124
128
|
taskStore: (agentId) => new PostgresTaskStore(pool, agentId, { ttlDays: options.ttlDays, ownerResolver: options.taskOwner, lease }),
|
|
125
129
|
leases: {
|
|
126
130
|
...lease,
|
|
@@ -128,7 +132,8 @@ export function postgresStorage(options) {
|
|
|
128
132
|
reap: () => reapExpiredTasks(pool),
|
|
129
133
|
cancelRequested: () => cancelRequestedTasks(pool, lease),
|
|
130
134
|
},
|
|
131
|
-
taskQueue
|
|
135
|
+
taskQueue,
|
|
136
|
+
retryTask: (owner, id) => taskQueue.mutate(owner, (store) => applyRetry(store, id)),
|
|
132
137
|
async schemaVersion() {
|
|
133
138
|
try {
|
|
134
139
|
const r = await pool.query('SELECT max(version) AS v FROM melchizedek_schema_version');
|
|
@@ -245,6 +245,7 @@ export declare const agentSchema: z.ZodObject<{
|
|
|
245
245
|
}>>;
|
|
246
246
|
delegates: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
247
247
|
}, z.core.$strict>>;
|
|
248
|
+
metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
|
|
248
249
|
}, z.core.$strict>;
|
|
249
250
|
/**
|
|
250
251
|
* Model and instruction are optional at the type level because a nested
|
|
@@ -462,6 +463,7 @@ export declare const subagentSchema: z.ZodObject<{
|
|
|
462
463
|
}>>;
|
|
463
464
|
delegates: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
464
465
|
}, z.core.$strict>>;
|
|
466
|
+
metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
|
|
465
467
|
description: z.ZodString;
|
|
466
468
|
model: z.ZodOptional<z.ZodString>;
|
|
467
469
|
instruction: z.ZodOptional<z.ZodString>;
|
|
@@ -685,6 +687,7 @@ export declare const syndicateSchema: z.ZodObject<{
|
|
|
685
687
|
}>>;
|
|
686
688
|
delegates: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
687
689
|
}, z.core.$strict>>;
|
|
690
|
+
metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
|
|
688
691
|
}, z.core.$strict>;
|
|
689
692
|
subagents: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
690
693
|
name: z.ZodString;
|
|
@@ -896,6 +899,7 @@ export declare const syndicateSchema: z.ZodObject<{
|
|
|
896
899
|
}>>;
|
|
897
900
|
delegates: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
898
901
|
}, z.core.$strict>>;
|
|
902
|
+
metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
|
|
899
903
|
description: z.ZodString;
|
|
900
904
|
model: z.ZodOptional<z.ZodString>;
|
|
901
905
|
instruction: z.ZodOptional<z.ZodString>;
|
|
@@ -945,6 +949,7 @@ export declare const syndicateSchema: z.ZodObject<{
|
|
|
945
949
|
model_errors: z.ZodOptional<z.ZodNumber>;
|
|
946
950
|
tool_errors: z.ZodOptional<z.ZodNumber>;
|
|
947
951
|
}, z.core.$strict>>;
|
|
952
|
+
metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
|
|
948
953
|
variables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
|
|
949
954
|
memory_system: z.ZodOptional<z.ZodEnum<{
|
|
950
955
|
"internal-only": "internal-only";
|
|
@@ -27,6 +27,7 @@ import { isSecretShapedEnvName } from './tools/skills/env.js';
|
|
|
27
27
|
import { OAUTH_SCOPE, PROVIDER_NAME } from './tools/auth.js';
|
|
28
28
|
import { V2_AGENT_KEYS, conflictMessage, conflictsOf, toEngineAgent } from './agentDialect.js';
|
|
29
29
|
import { MCP_TRANSPORTS } from './tools/mcpTransports.js';
|
|
30
|
+
import { MAX_META_KEYS, MAX_META_VALUE_CHARS, META_KEY } from './observability/metadata.js';
|
|
30
31
|
// ── Leaf rules ───────────────────────────────────────────────────────────────
|
|
31
32
|
/**
|
|
32
33
|
* ADK's agent-name rule (validateAgentName in ADK's base_agent), kept: checked here
|
|
@@ -337,6 +338,12 @@ const openapiEntry = z
|
|
|
337
338
|
.describe('Credentials, always from the environment, never written in YAML.'),
|
|
338
339
|
})
|
|
339
340
|
.describe('An HTTP API as tools, from its OpenAPI spec (lib/tools/openapiTools.ts).');
|
|
341
|
+
// ── Metadata (ADR 0141) ──────────────────────────────────────────────────────
|
|
342
|
+
/** Static labels copied onto the turn's spans as `meta.*` attributes (lib/observability/metadata.ts). */
|
|
343
|
+
const metadataSchema = (where) => z
|
|
344
|
+
.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()]))
|
|
345
|
+
.refine((m) => Object.keys(m).length <= MAX_META_KEYS, { message: `at most ${MAX_META_KEYS} metadata keys` })
|
|
346
|
+
.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).`);
|
|
340
347
|
// ── Agents ───────────────────────────────────────────────────────────────────
|
|
341
348
|
const agentFields = {
|
|
342
349
|
name: agentName,
|
|
@@ -440,6 +447,7 @@ const agentFields = {
|
|
|
440
447
|
delegates: z.array(z.string()).optional(),
|
|
441
448
|
})
|
|
442
449
|
.optional(),
|
|
450
|
+
metadata: metadataSchema('Each becomes `meta.agent.<key>` on this agent\'s agent.invoke span.').optional(),
|
|
443
451
|
};
|
|
444
452
|
export const agentSchema = z
|
|
445
453
|
.strictObject(agentFields)
|
|
@@ -583,6 +591,7 @@ export const syndicateSchema = z
|
|
|
583
591
|
})
|
|
584
592
|
.optional()
|
|
585
593
|
.describe('Self-correction on model and tool errors: the engine\'s reflect-and-retry. On by default.'),
|
|
594
|
+
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(),
|
|
586
595
|
variables: z
|
|
587
596
|
.record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
|
|
588
597
|
.optional()
|
|
@@ -1391,6 +1400,10 @@ export function syndicateJsonSchema() {
|
|
|
1391
1400
|
if (ctx.zodSchema === samplingSchema || ctx.zodSchema === outputSchemaV2) {
|
|
1392
1401
|
ctx.jsonSchema.minProperties = 1;
|
|
1393
1402
|
}
|
|
1403
|
+
// metadata: (ADR 0141): the key-count refinement, which JSON Schema says as maxProperties.
|
|
1404
|
+
if (ctx.jsonSchema.propertyNames?.pattern === META_KEY.source) {
|
|
1405
|
+
ctx.jsonSchema.maxProperties = MAX_META_KEYS;
|
|
1406
|
+
}
|
|
1394
1407
|
if (ctx.zodSchema === modelOverrideEntry) {
|
|
1395
1408
|
ctx.jsonSchema.oneOf = [{ required: ['instruction'] }, { required: ['instruction_append'] }];
|
|
1396
1409
|
}
|
|
@@ -180,6 +180,12 @@ export declare function claimNextJob(): TaskRecord | null;
|
|
|
180
180
|
export declare function finishJob(id: string, outcome: JobOutcome): void;
|
|
181
181
|
/** The outcome rule, on a snapshot (every backend). */
|
|
182
182
|
export declare function applyFinish(store: TaskStore, id: string, outcome: JobOutcome): void;
|
|
183
|
+
/**
|
|
184
|
+
* The retry rule (every backend; an operator's Retry and task_update's
|
|
185
|
+
* `queued` alike): a failed or cancelled background job goes back to the
|
|
186
|
+
* queue with its attempts reset. Anything else is left alone.
|
|
187
|
+
*/
|
|
188
|
+
export declare function applyRetry(store: TaskStore, id: string): 'queued' | 'not-found' | 'not-retryable';
|
|
183
189
|
/** The interrupted-job rule for one record: back to the queue, or failed. */
|
|
184
190
|
export declare function applyInterrupted(t: TaskRecord): 'requeued' | 'failed';
|
|
185
191
|
/** The single-user JSON file, its checkpoints capped by `options` (the default backend is fileTaskBackend). */
|
|
@@ -282,6 +282,28 @@ export function applyFinish(store, id, outcome) {
|
|
|
282
282
|
job.error = outcome.error.slice(0, 1_000);
|
|
283
283
|
}
|
|
284
284
|
}
|
|
285
|
+
/** A failed or cancelled job made new again: no attempts, no error, no finish time. */
|
|
286
|
+
function resetForRetry(t) {
|
|
287
|
+
t.attempts = 0;
|
|
288
|
+
delete t.error;
|
|
289
|
+
delete t.finished_at;
|
|
290
|
+
}
|
|
291
|
+
/**
|
|
292
|
+
* The retry rule (every backend; an operator's Retry and task_update's
|
|
293
|
+
* `queued` alike): a failed or cancelled background job goes back to the
|
|
294
|
+
* queue with its attempts reset. Anything else is left alone.
|
|
295
|
+
*/
|
|
296
|
+
export function applyRetry(store, id) {
|
|
297
|
+
const job = store.tasks.find((t) => t.id === id);
|
|
298
|
+
if (!job)
|
|
299
|
+
return 'not-found';
|
|
300
|
+
if (job.kind !== 'background' || !['failed', 'cancelled'].includes(job.status))
|
|
301
|
+
return 'not-retryable';
|
|
302
|
+
resetForRetry(job);
|
|
303
|
+
job.status = 'queued';
|
|
304
|
+
job.updated_at = now();
|
|
305
|
+
return 'queued';
|
|
306
|
+
}
|
|
285
307
|
/** The interrupted-job rule for one record: back to the queue, or failed. */
|
|
286
308
|
export function applyInterrupted(t) {
|
|
287
309
|
t.updated_at = now();
|
|
@@ -470,11 +492,8 @@ export const taskUpdateContract = defineTool({
|
|
|
470
492
|
if (status === 'queued' && !['failed', 'cancelled'].includes(task.status)) {
|
|
471
493
|
return `Error: only a failed or cancelled job can be queued again; ${id} is ${task.status}.`;
|
|
472
494
|
}
|
|
473
|
-
if (status === 'queued')
|
|
474
|
-
task
|
|
475
|
-
delete task.error;
|
|
476
|
-
delete task.finished_at;
|
|
477
|
-
}
|
|
495
|
+
if (status === 'queued')
|
|
496
|
+
resetForRetry(task);
|
|
478
497
|
}
|
|
479
498
|
task.status = status;
|
|
480
499
|
}
|
|
@@ -161,7 +161,7 @@ export async function runToolNode(node, run, context) {
|
|
|
161
161
|
let error;
|
|
162
162
|
const invoke = () => runOwnTool(resolved.own, args, call);
|
|
163
163
|
try {
|
|
164
|
-
response = await (context.traceCall ? context.traceCall({ id: functionCallId, name: resolved.name }, resolved.own, invoke) : invoke());
|
|
164
|
+
response = await (context.traceCall ? context.traceCall({ id: functionCallId, name: resolved.name, args }, resolved.own, invoke) : invoke());
|
|
165
165
|
}
|
|
166
166
|
catch (e) {
|
|
167
167
|
// handleFunctionCallList: an Error's message, any other throw as it is.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "melchizedek-agents",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.10.0",
|
|
4
4
|
"description": "A multi-model, multi-agent orchestration framework — YAML-defined syndicates on the engine's own agent loop, Supabase or Postgres session persistence, pgvector long-term memory. Companion repo to the lyceumagents.com curriculum.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -30,6 +30,7 @@
|
|
|
30
30
|
"./a2a/remote": "./dist/lib/a2a/remoteAgent.js",
|
|
31
31
|
"./a2a/identity": "./dist/lib/a2a/identity.js",
|
|
32
32
|
"./a2a/policy": "./dist/lib/a2a/policy.js",
|
|
33
|
+
"./a2a/feedback": "./dist/lib/a2a/feedback.js",
|
|
33
34
|
"./a2a/limits": "./dist/lib/a2a/redisLimits.js",
|
|
34
35
|
"./mcp": "./dist/lib/mcp/server.js",
|
|
35
36
|
"./registry": "./dist/lib/registry.js",
|
|
@@ -149,13 +150,13 @@
|
|
|
149
150
|
},
|
|
150
151
|
"dependencies": {
|
|
151
152
|
"@a2a-js/sdk": "^1.3.0",
|
|
152
|
-
"@anthropic-ai/sdk": "^0.
|
|
153
|
+
"@anthropic-ai/sdk": "^0.135.0",
|
|
153
154
|
"@google/genai": "2.27.0",
|
|
154
155
|
"@jitl/quickjs-wasmfile-release-sync": "0.32.0",
|
|
155
156
|
"@modelcontextprotocol/sdk": "^1.32.1",
|
|
156
157
|
"@opentelemetry/api": "^1.9.1",
|
|
157
158
|
"@opentelemetry/core": "^2.8.0",
|
|
158
|
-
"@opentelemetry/exporter-trace-otlp-http": "^0.
|
|
159
|
+
"@opentelemetry/exporter-trace-otlp-http": "^0.223.0",
|
|
159
160
|
"@opentelemetry/resources": "^2.7.1",
|
|
160
161
|
"@opentelemetry/sdk-trace-base": "^2.7.1",
|
|
161
162
|
"@opentelemetry/sdk-trace-node": "^2.7.1",
|
|
@@ -167,7 +168,7 @@
|
|
|
167
168
|
"pg": "^8.23.1",
|
|
168
169
|
"quickjs-emscripten-core": "0.32.0",
|
|
169
170
|
"yaml": "^2.9.0",
|
|
170
|
-
"zod": "4.6.
|
|
171
|
+
"zod": "^4.6.7"
|
|
171
172
|
},
|
|
172
173
|
"devDependencies": {
|
|
173
174
|
"@electric-sql/pglite": "^0.5.10",
|