melchizedek-agents 1.0.3 → 1.2.0

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

@@ -13,8 +13,12 @@
  *
  * THE REQUEST, in the order ADK built it:
  *   1. The agent's generateContentConfig, and its output schema when it has
- *      no tools (or the model takes a schema beside tools: Gemini 2 and
- *      later on Vertex AI).
+ *      no tools, or when every model the step may call (its own and its
+ *      fallback_model) takes a schema beside tools in one request: Claude
+ *      from Opus 4.8, Sonnet 5 and Haiku 5.5 on, OpenAI, Gemini 2 and later
+ *      on Vertex AI (outputSchemaBesideTools, lib/models/capabilities.ts,
+ *      ADR 0109). That is how an orchestrator that delegates answers in a
+ *      schema without a set_model_response call.
  *   2. The system prompt, each piece joined to the last by a blank line:
  *      - the identity lines ("You are an agent. Your internal name is …"),
  *        unless the agent may transfer to no one (an output schema rules
@@ -66,6 +70,7 @@
  * and defineTool, as registerTool refuses one (ADR 0107).
  */
 import { contentsToMessages, reasoningOf, samplingOf, systemText, toolChoiceOf } from '../../models/genaiMapping.js';
+import { outputSchemaBesideTools } from '../../models/capabilities.js';
 import { providerForModel } from '../../models/providerMap.js';
 import { contractToolDeclaration, nativeToolOf, toContractJsonSchema } from '../../models/schemaNormalize.js';
 import { createToolContext, instructionToolOf, isTool, toolOf } from '../../tools/tool.js';
@@ -131,10 +136,26 @@ function vertexAi() {
         return envFlag('GOOGLE_GENAI_USE_ENTERPRISE');
     return envFlag('GOOGLE_GENAI_USE_VERTEXAI');
 }
-/** Whether the model takes an output schema beside tools in one request (ADK: Vertex AI, Gemini 2 and later). */
+/**
+ * ADK's rule for whether the model takes an output schema beside tools in one
+ * request (Vertex AI, Gemini 2 and later). `mode: task` keeps it as it is,
+ * for the instruction line ADK's processor writes there.
+ */
 export function outputSchemaWithTools(model) {
     return vertexAi() && isGemini2OrAbove(model);
 }
+/**
+ * Whether the agent's output schema travels beside its tools as the
+ * provider's own structured-output field (ADR 0109): on every model the step
+ * may call, its own and its fallback_model, since a fallback answers the same
+ * request. ADK's Gemini rule still holds; the capability matrix's
+ * `structured_output_with_tools` adds Claude's current generations and
+ * OpenAI. Anywhere else the schema is the set_model_response tool.
+ */
+function schemaBesideTools(agent) {
+    const models = agent.fallbackModel ? [agent.model, agent.fallbackModel] : [agent.model];
+    return models.every((m) => outputSchemaWithTools(m) || outputSchemaBesideTools(m));
+}
 // ── Session state in an instruction (ADK's injectSessionState) ───────────────
 const STATE_PREFIXES = ['app:', 'user:', 'temp:'];
 const ARTIFACT_PREFIX = 'artifact.';
@@ -437,7 +458,10 @@ export async function buildModelRequest(agent, ctx) {
         throw new Error('Response schema must be set via LlmAgent.output_schema.');
     const listed = agent.tools ?? [];
     const taskMode = agent.mode === 'task';
-    const schemaWithTools = !!agent.outputSchema && listed.length > 0 && !outputSchemaWithTools(model);
+    // An output schema beside tools: set_model_response unless the step's models take both in one request
+    // (ADR 0109). Task mode keeps ADK's rule: finish_task carries the schema there.
+    const besideTools = !!agent.outputSchema && listed.length > 0;
+    const schemaWithTools = besideTools && !(taskMode ? outputSchemaWithTools(model) : schemaBesideTools(agent));
     // 1. Basic: the config, and the output schema where the model takes it (never in task mode: finish_task carries it).
     if (agent.outputSchema && !schemaWithTools && !taskMode) {
         cfg.responseSchema = agent.outputSchema;

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

@@ -40,10 +40,11 @@ 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 { initializeTracing } from '../../observability/tracer.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;
-const runtimeTracer = () => trace.getTracer(RUNTIME_SPAN_SCOPE);
+/** 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. */
 function payloadJson(value) {
     let json;
@@ -85,8 +86,7 @@ function failed(span, error) {
 }
 /** The agent's run as an `agent.invoke <name>` span, opened when the run starts. */
 export async function* traceAgentInvocation(agent, ctx, run) {
-    initializeTracing();
-    const span = runtimeTracer().startSpan(`agent.invoke ${agent.name}`, {
+    const span = startRuntimeSpan(`agent.invoke ${agent.name}`, {
         attributes: {
             'gen_ai.operation.name': 'invoke_agent',
             'gen_ai.agent.name': agent.name,
@@ -116,8 +116,7 @@ export async function* traceAgentInvocation(agent, ctx, run) {
  * provider that answered (the fallback's, when a fallback answered).
  */
 export async function* traceModelCall(agent, ctx, step) {
-    initializeTracing();
-    const span = runtimeTracer().startSpan('model.call', {
+    const span = startRuntimeSpan('model.call', {
         attributes: {
             'gen_ai.operation.name': 'chat',
             'gen_ai.agent.name': agent.name,
@@ -173,7 +172,7 @@ function recordModelCall(span, result, provider) {
         span.setAttribute('llm.error_code', String(response.error.code));
         return;
     }
-    if (payloadPolicyFromEnv().mode === 'off')
+    if (!span.isRecording() || payloadPolicyFromEnv().mode === 'off')
         return;
     const { signal: _signal, ...request } = result.request;
     span.setAttribute('llm.payload.request', payloadJson(request));
@@ -181,10 +180,9 @@ function recordModelCall(span, result, provider) {
 }
 /** One tool call as a `tool.execute <name>` span, under the agent's. */
 export async function traceToolCall(call, tool, run) {
-    initializeTracing();
     const name = call.name || '<unnamed>';
     const description = tool && typeof tool === 'object' ? tool.description : undefined;
-    const span = runtimeTracer().startSpan(`tool.execute ${name}`, {
+    const span = startRuntimeSpan(`tool.execute ${name}`, {
         attributes: {
             'gen_ai.operation.name': 'execute_tool',
             'gen_ai.tool.name': name,
@@ -221,8 +219,7 @@ export async function traceToolCall(call, tool, run) {
 // attributes each model call to the node's agent, as on ADK.
 /** The walk as a `workflow.invoke <name>` span; every node span opens under it. */
 export async function traceWorkflowInvocation(workflow, ctx, run) {
-    initializeTracing();
-    const span = runtimeTracer().startSpan(`workflow.invoke ${workflow.name}`, {
+    const span = startRuntimeSpan(`workflow.invoke ${workflow.name}`, {
         attributes: {
             'gen_ai.operation.name': 'invoke_workflow',
             'gen_ai.conversation.id': ctx.sessionId,
@@ -248,8 +245,7 @@ export async function traceWorkflowInvocation(workflow, ctx, run) {
  * attempts the run made.
  */
 export async function traceNodeExecution(node, run) {
-    initializeTracing();
-    const span = runtimeTracer().startSpan(`node.execute ${node.name}`, {
+    const span = startRuntimeSpan(`node.execute ${node.name}`, {
         attributes: {
             'gen_ai.operation.name': 'execute_node',
             'adk.node.path': node.path,
@@ -274,9 +270,8 @@ export async function traceNodeExecution(node, run) {
 }
 /** A tool node's call as a `tool.execute <name>` span, under its node's (ToolNodeContext.traceCall). */
 export async function traceToolNodeCall(call, tool, run) {
-    initializeTracing();
     const description = tool && typeof tool === 'object' ? tool.description : undefined;
-    const span = runtimeTracer().startSpan(`tool.execute ${call.name}`, {
+    const span = startRuntimeSpan(`tool.execute ${call.name}`, {
         attributes: {
             'gen_ai.operation.name': 'execute_tool',
             'gen_ai.tool.name': call.name,

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

@@ -17,10 +17,13 @@
  * (lib/workflow.ts) and an approval (ADR 0028); a client handles all three
  * by showing `result.input` (or the approval) and sending the next message.
  *
- * WHERE: only on an agent the turn runs directly (the orchestrator, or a
- * plan-dispatch route), as with approval gates: inside a delegated
- * subagent the pause cannot reach the person. Not inside a workflow node
- * yet. The schema refuses both.
+ * WHERE: on any agent of a delegate or dispatch syndicate, as with approval
+ * gates. Inside a delegated subagent the question waits in the child's
+ * session, below the call its caller left open, and reaches the person
+ * with the agent path (`result.input.path`, ADR 0110); the next message is
+ * stored as the answer and carried down to the child
+ * (lib/runtime/native/interrupts.ts). Not inside a workflow node yet; the
+ * schema refuses it there.
  *
  * RESUME: the answer is an ordinary function response, so the loop resumes
  * a question ADK opened before 1.0.0 as one it opened itself (ADR 0079); no

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

@@ -37,7 +37,7 @@
 import type { TurnEvent } from './events.ts';
 /** A conversation's address. Stores key it as `<appName>:<userId>:<sessionId>`. */
 export interface SessionKey {
-    /** The syndicate (or, for a DELEGATE subagent's own row, the subagent's name). */
+    /** The syndicate (or, for a DELEGATE subagent's own row, its agent path: lib/runtime/native/delegate.ts childAppName). */
     appName: string;
     userId: string;
     sessionId: string;

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

@@ -144,7 +144,13 @@ export interface SyndicateTurnOptions {
     maxLlmCalls?: number;
     /** Ask adapters for token-by-token partial events (the REPL's live view). */
     streaming?: boolean;
-    /** Root-span metadata; `false` disables tracing for the turn. */
+    /**
+     * Root-span metadata. `false` disables tracing for the turn: it records no
+     * span, so no row reaches the ledger (adk_telemetry, adk_turns,
+     * adk_payloads), the console exporter, the in-process listeners or an OTLP
+     * endpoint, and the turn does not start the tracer. The step budget and
+     * the usage in the result are unaffected. Default: traced.
+     */
     trace?: TraceOptions | false;
     events?: TurnEvents;
     /**
@@ -152,7 +158,8 @@ export interface SyndicateTurnOptions {
      * the native runtime. The store is pinned to `appName`; a tool reads the
      * grant of `userId` only. With `consent`, a call whose provider the user
      * has not granted pauses the turn input-required (`result.consent`), and
-     * the next message after the grant resumes it. Omitted: tools have no
+     * the next message after the grant resumes it; inside a delegated
+     * subagent too, with `consent.path` set (ADR 0118). Omitted: tools have no
      * `accessToken`, as before.
      */
     toolCredentials?: ToolCredentials;
@@ -223,7 +230,8 @@ export interface SyndicateTurnResult {
     input?: PendingInput;
     /** The OAuth grant a paused call waits for, when status is input-required
      *  (ADR 0085): the person opens `consent.authUri`; their next message after
-     *  the grant is stored resumes the call. */
+     *  the grant is stored resumes the call. `consent.path` is set for a call
+     *  inside a delegated subagent (ADR 0118). */
     consent?: PendingConsent;
     /** The text the user receives (relay fallback and guards applied). */
     text: string;