eve 0.68.0 → 0.70.0

package/dist/src/tools/schema.d.ts

@@ -1,6 +1,8 @@
 import { type FlexibleSchema } from "ai";
 import type { StandardJSONSchemaV1, StandardSchemaV1 } from "#compiled/@standard-schema/spec/index.js";
 import { type JsonObject } from "#shared/json.js";
+import { type SchemaDirection, type SchemaResult } from "#tools/schema-emission.js";
+export { serializeOutputSchema } from "#tools/schema-emission.js";
 /**
  * eve-owned schema contract for tool input and output schemas: a Standard
  * Schema validator that can also emit JSON Schema. Author schemas (Zod,
@@ -15,9 +17,6 @@ export type ToolSchema<Input = unknown, Output = Input> = StandardSchemaV1<Input
  * conversion.
  */
 export type ToolSchemaSource = StandardJSONSchemaV1 | StandardSchemaV1 | Record<string, unknown>;
-type SchemaDirection = "input" | "output";
-/** `null` and `undefined` pass through every conversion untouched. */
-type SchemaResult<TSource, TResult> = TSource extends null | undefined ? TSource : TResult;
 /**
  * Resolves a source into a live input {@link ToolSchema}. Live schemas pass
  * through unchanged; plain JSON Schema data becomes a {@link defineJsonSchema}
@@ -37,11 +36,15 @@ export declare function toOutputSchema<T extends ToolSchemaSource | null | undef
  */
 export declare function serializeInputSchema<T extends ToolSchemaSource | null | undefined>(source: T): SchemaResult<T, JsonObject>;
 /**
- * Serializes an output schema source into canonical JSON Schema data (no
- * `$schema` key) for compiled artifacts, durable state, and protocol
- * responses. `null` and `undefined` pass through untouched.
+ * Serializes an input schema into the JSON Schema eve sends a model for it.
+ * A schema from a validation library such as Zod, Valibot, or ArkType gets
+ * `additionalProperties: false` on every object that allows no other keys, as
+ * the AI SDK applies to library schemas. Plain JSON Schema is sent exactly as
+ * written. `null` and `undefined` pass through untouched.
+ *
+ * Providers can transform the schema further before the model reads it.
  */
-export declare function serializeOutputSchema<T extends ToolSchemaSource | null | undefined>(source: T): SchemaResult<T, JsonObject>;
+export declare function serializeModelInputSchema<T extends ToolSchemaSource | null | undefined>(source: T): SchemaResult<T, JsonObject>;
 /**
  * Returns whether a value implements the full {@link ToolSchema} contract:
  * Standard Schema validation plus JSON Schema emission.
@@ -63,6 +66,18 @@ export declare function isToolSchema(value: unknown): value is ToolSchema;
  * for constraints JSON Schema cannot express.
  */
 export declare function defineJsonSchema<T = unknown>(schema: JsonObject, check?: (value: T) => string | undefined): ToolSchema<T>;
+/** An optional string property added to an input schema. */
+export interface OptionalStringProperty {
+    readonly description: string;
+    readonly name: string;
+}
+/**
+ * Extends an object input schema with an optional string property that the
+ * schema itself never sees: validation splits the property off, validates the
+ * rest with `schema`, and returns the property alongside the result. A plain
+ * JSON Schema stays advertised as written.
+ */
+export declare function withOptionalStringProperty(schema: ToolSchema, property: OptionalStringProperty): ToolSchema;
 /**
  * Permissive schema lowered onto model-visible tools whose definitions
  * declare no input schema. Accepts any input — an absent schema declares no
@@ -84,4 +99,3 @@ export declare const UNSPECIFIED_INPUT_SCHEMA: ToolSchema;
  */
 export declare function toModelSchema(schema: FlexibleSchema, direction: SchemaDirection): FlexibleSchema;
 export declare function toModelSchema(schema: FlexibleSchema | undefined, direction: SchemaDirection): FlexibleSchema | undefined;
-export {};

package/dist/src/tools/schema.js

@@ -1 +1 @@
-import{TypeValidationError,asSchema,jsonSchema}from"ai";import{isObject}from"#shared/guards.js";import{toErrorMessage}from"#shared/errors.js";import{parseJsonObject}from"#shared/json.js";import{Validator}from"#compiled/@cfworker/json-schema/index.js";function toInputSchema(e){return toSchema(e,`input`)}function toOutputSchema(e){return toSchema(e,`output`)}function serializeInputSchema(e){return serializeSchema(e,`input`)}function serializeOutputSchema(e){return serializeSchema(e,`output`)}function isToolSchema(e){let t=getStandardSchemaProperties(e);if(t===void 0)return!1;let n=t.jsonSchema;return typeof t.validate==`function`&&typeof n==`object`&&!!n&&typeof n.input==`function`&&typeof n.output==`function`}function defineJsonSchema(e,t){let emit=()=>structuredClone(e),n={"~standard":{version:1,vendor:`eve`,validate:createJsonSchemaValidator(e,t),jsonSchema:{input:emit,output:emit}}};return plainJsonSchemas.add(n),n}const plainJsonSchemas=new WeakSet,UNSPECIFIED_INPUT_SCHEMA=defineJsonSchema({});function toModelSchema(e,t){if(e===void 0||typeof e==`function`||!(`~standard`in e))return e;let n=e,r=plainJsonSchemas.has(n);return jsonSchema(()=>{let e=serializeSchema(n,t);return r?e:closeObjectSchemas(e)},{validate:async e=>{let t=await n[`~standard`].validate(e);return t.issues===void 0?{success:!0,value:t.value}:{success:!1,error:new TypeValidationError({value:e,cause:t.issues})}}})}function closeObjectSchemas(e){if(!isObject(e))return e;let t={...e},{type:n}=t;(n===`object`||Array.isArray(n)&&n.includes(`object`))&&(t.additionalProperties=isObject(t.additionalProperties)?closeObjectSchemas(t.additionalProperties):!1,isObject(t.properties)&&(t.properties=mapValues(t.properties,closeObjectSchemas))),Array.isArray(t.items)?t.items=t.items.map(closeObjectSchemas):isObject(t.items)&&(t.items=closeObjectSchemas(t.items));for(let e of[`allOf`,`anyOf`,`oneOf`]){let n=t[e];Array.isArray(n)&&(t[e]=n.map(closeObjectSchemas))}return isObject(t.definitions)&&(t.definitions=mapValues(t.definitions,closeObjectSchemas)),t}function mapValues(e,t){return Object.fromEntries(Object.entries(e).map(([e,n])=>[e,t(n)]))}function toSchema(e,t){return e==null||isToolSchema(e)?e:defineJsonSchema(toJsonObject(e,t))}function serializeSchema(e,t){return e==null?e:toJsonObject(e,t)}function toJsonObject(e,t){let n=getStandardSchemaProperties(e),r=n?.jsonSchema,i=typeof r==`object`&&r?r[t]:void 0,a=typeof n?.vendor==`string`?n.vendor:`unknown`;if(n!==void 0&&typeof i!=`function`&&a===`zod`){if(t===`input`){let t=asSchema(e),{$schema:n,...r}=parseJsonObject(t.jsonSchema);return r}throw Error(`Zod 3 cannot emit an output JSON Schema. Upgrade to Zod 4 or provide a plain JSON Schema object.`)}if(n!==void 0&&typeof i!=`function`)throw Error(`Standard Schema vendor "${a}" does not support JSON Schema conversion. Provide a Standard Schema implementation with JSON Schema conversion or a plain JSON Schema object.`);let{$schema:o,...s}=parseJsonObject(n===void 0?e:i({target:`draft-07`}));return s}function getStandardSchemaProperties(e){if(typeof e!=`object`||!e||!(`~standard`in e))return;let t=e[`~standard`];return typeof t==`object`&&t?t:void 0}function createJsonSchemaValidator(e,t){let n,r=!1,passThrough=(e,t)=>(r||(r=!0,console.warn(`[eve] Tool schema cannot validate values locally; passing them through unvalidated: ${t}`)),{value:e});return r=>{if(n===void 0){let t=buildValidator(e);if(typeof t==`string`)return n=null,passThrough(r,t);n=t}if(n===null)return{value:r};let i;try{i=n.validate(r)}catch(e){return r===void 0?{issues:[{message:`Expected a JSON value.`}]}:passThrough(r,toErrorMessage(e))}if(!i.valid)return{issues:toIssues(i.errors)};let a=applyDefaults(e,e,r),o=t?.(a);return o===void 0?{value:a}:{issues:[{message:o}]}}}function applyDefaults(e,t,n){let r=n;for(let n of followRefs(e,t)){let{items:t,properties:i}=n;if(isObject(r)&&isObject(i))r=fillProperties(e,i,r);else if(Array.isArray(r)&&isObject(t)){let n=r,i=n.map(n=>applyDefaults(e,t,n));i.some((e,t)=>e!==n[t])&&(r=i)}}return r}function fillProperties(e,t,n){let r=n;for(let[i,a]of Object.entries(t)){let t=Object.hasOwn(n,i)?n[i]:void 0,o=t===void 0?findDefault(e,a):applyDefaults(e,a,t);o!==t&&(r===n&&(r={...n}),r[i]=o)}return r}function findDefault(e,t){for(let n of followRefs(e,t))if(`default`in n)return structuredClone(n.default)}function*followRefs(e,t){let n=new Set,r=t;for(;isObject(r)&&!n.has(r);)n.add(r),yield r,r=resolveLocalRef(e,r.$ref)}function resolveLocalRef(e,t){if(typeof t!=`string`||t!==`#`&&!t.startsWith(`#/`))return;let n=e;for(let e of decodePointer(t)){if(typeof n!=`object`||!n||!Object.hasOwn(n,e))return;n=n[e]}return n}function buildValidator(e){try{let t=structuredClone(e);return prepareForValidation(t)??new Validator(t,`2020-12`,!1)}catch(e){return toErrorMessage(e)}}const JSON_TYPES=new Set([`array`,`boolean`,`integer`,`null`,`number`,`object`,`string`]),EXCLUSIVE_BOUNDS=[[`exclusiveMinimum`,`minimum`],[`exclusiveMaximum`,`maximum`]],SUBSCHEMA_KEYWORDS=[`additionalItems`,`additionalProperties`,`contains`,`else`,`if`,`not`,`propertyNames`,`then`,`unevaluatedItems`,`unevaluatedProperties`],SUBSCHEMA_LIST_KEYWORDS=[`allOf`,`anyOf`,`oneOf`,`prefixItems`],SUBSCHEMA_MAP_KEYWORDS=[`$defs`,`definitions`,`dependencies`,`dependentSchemas`,`patternProperties`,`properties`];function prepareForValidation(e){if(typeof e==`boolean`)return;if(typeof e!=`object`||!e||Array.isArray(e))return`a subschema is neither an object nor a boolean`;let t=e;delete t.format;for(let[e,n]of EXCLUSIVE_BOUNDS)typeof t[e]==`boolean`&&(t[e]&&typeof t[n]==`number`?(t[e]=t[n],delete t[n]):delete t[e]);let{enum:n,pattern:r,required:i,type:a}=t;if(a!==void 0&&!(Array.isArray(a)?a.every(isJsonType):isJsonType(a)))return`unsupported type ${JSON.stringify(a)}`;if(n!==void 0&&!Array.isArray(n))return"`enum` is not an array";if(i!==void 0&&!(Array.isArray(i)&&i.every(e=>typeof e==`string`)))return"`required` is not an array of strings";if(r!==void 0&&!isRegExpSource(r))return`invalid pattern ${JSON.stringify(r)}`;for(let e of SUBSCHEMA_KEYWORDS)if(e in t){let n=prepareForValidation(t[e]);if(n!==void 0)return n}let o=t.items;for(let e of Array.isArray(o)?o:o===void 0?[]:[o]){let t=prepareForValidation(e);if(t!==void 0)return t}for(let e of SUBSCHEMA_LIST_KEYWORDS){let n=t[e];if(n!==void 0){if(!Array.isArray(n))return`\`${e}\` is not an array`;for(let e of n){let t=prepareForValidation(e);if(t!==void 0)return t}}}for(let e of SUBSCHEMA_MAP_KEYWORDS){let n=t[e];if(n!==void 0){if(typeof n!=`object`||!n||Array.isArray(n))return`\`${e}\` is not an object`;for(let[t,r]of Object.entries(n)){if(e===`patternProperties`&&!isRegExpSource(t))return`invalid pattern ${JSON.stringify(t)}`;if(e===`dependencies`&&Array.isArray(r))continue;let n=prepareForValidation(r);if(n!==void 0)return n}}}}function isJsonType(e){return typeof e==`string`&&JSON_TYPES.has(e)}function isRegExpSource(e){if(typeof e!=`string`)return!1;try{return new RegExp(e,`u`),!0}catch{return!1}}const CLOSED_OBJECT_KEYWORD=/\/(?:additional|unevaluated)Properties$/;function toIssues(e){let t=[];for(let n=0;n<e.length;n++){let r=e[n],i=e[n+1];if(CLOSED_OBJECT_KEYWORD.test(r.keywordLocation)&&i?.keyword===`false`){let e=decodePointer(i.instanceLocation).at(-1);t.push({keyword:`false`,location:i.instanceLocation,message:`Unrecognized key: ${JSON.stringify(e)}`,object:r.instanceLocation}),n++}else t.push({keyword:r.keyword,location:r.instanceLocation,message:r.error})}let n=t.filter(e=>e.object===void 0||!t.some(t=>t.object===void 0&&(t.location===e.location||t.location.startsWith(`${e.location}/`))));return n.filter((e,t)=>{let r=n[t+1];return r===void 0?!0:r.location.startsWith(`${e.location}/`)?!1:e.keyword!==`$ref`||r.location!==e.location}).map(({location:e,message:t,object:n})=>{let r=decodePointer(n??e);return r.length===0?{message:t}:{message:t,path:r}})}function decodePointer(e){return e.split(`/`).slice(1).map(e=>{let t=e;try{t=decodeURIComponent(e)}catch{}return t.replaceAll(`~1`,`/`).replaceAll(`~0`,`~`)})}export{UNSPECIFIED_INPUT_SCHEMA,defineJsonSchema,isToolSchema,serializeInputSchema,serializeOutputSchema,toInputSchema,toModelSchema,toOutputSchema};
+import{TypeValidationError,asSchema,jsonSchema}from"ai";import{isObject}from"#shared/guards.js";import{toErrorMessage}from"#shared/errors.js";import{parseJsonObject}from"#shared/json.js";import{emitJsonSchema,getStandardSchemaProperties,readJsonSchemaEmitter,serializeOutputSchema}from"#tools/schema-emission.js";import{Validator}from"#compiled/@cfworker/json-schema/index.js";function toInputSchema(e){return toSchema(e,`input`)}function toOutputSchema(e){return toSchema(e,`output`)}function serializeInputSchema(e){return serializeSchema(e,`input`)}function serializeModelInputSchema(e){let t=toSchema(e,`input`);return t==null?t:toModelJsonSchema(t,`input`)}function isToolSchema(e){let t=getStandardSchemaProperties(e);if(t===void 0)return!1;let n=t.jsonSchema;return typeof t.validate==`function`&&typeof n==`object`&&!!n&&typeof n.input==`function`&&typeof n.output==`function`}function defineJsonSchema(e,t){let emit=()=>structuredClone(e),n={"~standard":{version:1,vendor:`eve`,validate:createJsonSchemaValidator(e,t),jsonSchema:{input:emit,output:emit}}};return plainJsonSchemas.add(n),n}const plainJsonSchemas=new WeakSet;function withOptionalStringProperty(e,t){let emit=()=>addOptionalStringProperty(serializeInputSchema(e),t),n={"~standard":{version:1,vendor:`eve`,validate:n=>validateWithProperty(e,t.name,n),jsonSchema:{input:emit,output:emit}}};return plainJsonSchemas.has(e)&&plainJsonSchemas.add(n),n}function addOptionalStringProperty(e,t){let n=isObject(e.properties)?e.properties:{};return{...e,type:e.type??`object`,properties:{...n,[t.name]:{description:t.description,type:`string`}}}}async function validateWithProperty(e,t,n){if(!isObject(n)||!(t in n))return await e[`~standard`].validate(n);let{[t]:r,...i}=n;if(typeof r!=`string`)return{issues:[{message:`Expected "${t}" to be a string.`,path:[t]}]};let a=await e[`~standard`].validate(i);return a.issues!==void 0||!isObject(a.value)?a:{value:{...a.value,[t]:r}}}const UNSPECIFIED_INPUT_SCHEMA=defineJsonSchema({});function toModelSchema(e,t){if(e===void 0||typeof e==`function`||!(`~standard`in e))return e;let n=e;return jsonSchema(()=>toModelJsonSchema(n,t),{validate:async e=>{let t=await n[`~standard`].validate(e);return t.issues===void 0?{success:!0,value:t.value}:{success:!1,error:new TypeValidationError({value:e,cause:t.issues})}}})}function toModelJsonSchema(e,t){let n=serializeSchema(e,t);return plainJsonSchemas.has(e)?n:closeObjectSchemas(n)}function closeObjectSchemas(e){if(!isObject(e))return e;let t={...e},{type:n}=t;(n===`object`||Array.isArray(n)&&n.includes(`object`))&&(t.additionalProperties=isObject(t.additionalProperties)?closeObjectSchemas(t.additionalProperties):!1,isObject(t.properties)&&(t.properties=mapValues(t.properties,closeObjectSchemas))),Array.isArray(t.items)?t.items=t.items.map(closeObjectSchemas):isObject(t.items)&&(t.items=closeObjectSchemas(t.items));for(let e of[`allOf`,`anyOf`,`oneOf`]){let n=t[e];Array.isArray(n)&&(t[e]=n.map(closeObjectSchemas))}return isObject(t.definitions)&&(t.definitions=mapValues(t.definitions,closeObjectSchemas)),t}function mapValues(e,t){return Object.fromEntries(Object.entries(e).map(([e,n])=>[e,t(n)]))}function toSchema(e,t){return e==null||isToolSchema(e)?e:defineJsonSchema(toJsonObject(e,t))}function serializeSchema(e,t){return e==null?e:toJsonObject(e,t)}function toJsonObject(e,t){if(t===`input`&&isLegacyZodSchema(e)){let t=asSchema(e),{$schema:n,...r}=parseJsonObject(t.jsonSchema);return r}return emitJsonSchema(e,t)}function isLegacyZodSchema(e){let t=getStandardSchemaProperties(e);return t!==void 0&&t.vendor===`zod`&&readJsonSchemaEmitter(t,`input`)===void 0}function createJsonSchemaValidator(e,t){let n,r=!1,passThrough=(e,t)=>(r||(r=!0,console.warn(`[eve] Tool schema cannot validate values locally; passing them through unvalidated: ${t}`)),{value:e});return r=>{if(n===void 0){let t=buildValidator(e);if(typeof t==`string`)return n=null,passThrough(r,t);n=t}if(n===null)return{value:r};let i;try{i=n.validate(r)}catch(e){return r===void 0?{issues:[{message:`Expected a JSON value.`}]}:passThrough(r,toErrorMessage(e))}if(!i.valid)return{issues:toIssues(i.errors)};let a=applyDefaults(e,e,r),o=t?.(a);return o===void 0?{value:a}:{issues:[{message:o}]}}}function applyDefaults(e,t,n){let r=n;for(let n of followRefs(e,t)){let{items:t,properties:i}=n;if(isObject(r)&&isObject(i))r=fillProperties(e,i,r);else if(Array.isArray(r)&&isObject(t)){let n=r,i=n.map(n=>applyDefaults(e,t,n));i.some((e,t)=>e!==n[t])&&(r=i)}}return r}function fillProperties(e,t,n){let r=n;for(let[i,a]of Object.entries(t)){let t=Object.hasOwn(n,i)?n[i]:void 0,o=t===void 0?findDefault(e,a):applyDefaults(e,a,t);o!==t&&(r===n&&(r={...n}),r[i]=o)}return r}function findDefault(e,t){for(let n of followRefs(e,t))if(`default`in n)return structuredClone(n.default)}function*followRefs(e,t){let n=new Set,r=t;for(;isObject(r)&&!n.has(r);)n.add(r),yield r,r=resolveLocalRef(e,r.$ref)}function resolveLocalRef(e,t){if(typeof t!=`string`||t!==`#`&&!t.startsWith(`#/`))return;let n=e;for(let e of decodePointer(t)){if(typeof n!=`object`||!n||!Object.hasOwn(n,e))return;n=n[e]}return n}function buildValidator(e){try{let t=structuredClone(e);return prepareForValidation(t)??new Validator(t,`2020-12`,!1)}catch(e){return toErrorMessage(e)}}const JSON_TYPES=new Set([`array`,`boolean`,`integer`,`null`,`number`,`object`,`string`]),EXCLUSIVE_BOUNDS=[[`exclusiveMinimum`,`minimum`],[`exclusiveMaximum`,`maximum`]],SUBSCHEMA_KEYWORDS=[`additionalItems`,`additionalProperties`,`contains`,`else`,`if`,`not`,`propertyNames`,`then`,`unevaluatedItems`,`unevaluatedProperties`],SUBSCHEMA_LIST_KEYWORDS=[`allOf`,`anyOf`,`oneOf`,`prefixItems`],SUBSCHEMA_MAP_KEYWORDS=[`$defs`,`definitions`,`dependencies`,`dependentSchemas`,`patternProperties`,`properties`];function prepareForValidation(e){if(typeof e==`boolean`)return;if(typeof e!=`object`||!e||Array.isArray(e))return`a subschema is neither an object nor a boolean`;let t=e;delete t.format;for(let[e,n]of EXCLUSIVE_BOUNDS)typeof t[e]==`boolean`&&(t[e]&&typeof t[n]==`number`?(t[e]=t[n],delete t[n]):delete t[e]);let{enum:n,pattern:r,required:i,type:a}=t;if(a!==void 0&&!(Array.isArray(a)?a.every(isJsonType):isJsonType(a)))return`unsupported type ${JSON.stringify(a)}`;if(n!==void 0&&!Array.isArray(n))return"`enum` is not an array";if(i!==void 0&&!(Array.isArray(i)&&i.every(e=>typeof e==`string`)))return"`required` is not an array of strings";if(r!==void 0&&!isRegExpSource(r))return`invalid pattern ${JSON.stringify(r)}`;for(let e of SUBSCHEMA_KEYWORDS)if(e in t){let n=prepareForValidation(t[e]);if(n!==void 0)return n}let o=t.items;for(let e of Array.isArray(o)?o:o===void 0?[]:[o]){let t=prepareForValidation(e);if(t!==void 0)return t}for(let e of SUBSCHEMA_LIST_KEYWORDS){let n=t[e];if(n!==void 0){if(!Array.isArray(n))return`\`${e}\` is not an array`;for(let e of n){let t=prepareForValidation(e);if(t!==void 0)return t}}}for(let e of SUBSCHEMA_MAP_KEYWORDS){let n=t[e];if(n!==void 0){if(typeof n!=`object`||!n||Array.isArray(n))return`\`${e}\` is not an object`;for(let[t,r]of Object.entries(n)){if(e===`patternProperties`&&!isRegExpSource(t))return`invalid pattern ${JSON.stringify(t)}`;if(e===`dependencies`&&Array.isArray(r))continue;let n=prepareForValidation(r);if(n!==void 0)return n}}}}function isJsonType(e){return typeof e==`string`&&JSON_TYPES.has(e)}function isRegExpSource(e){if(typeof e!=`string`)return!1;try{return new RegExp(e,`u`),!0}catch{return!1}}const CLOSED_OBJECT_KEYWORD=/\/(?:additional|unevaluated)Properties$/;function toIssues(e){let t=[];for(let n=0;n<e.length;n++){let r=e[n],i=e[n+1];if(CLOSED_OBJECT_KEYWORD.test(r.keywordLocation)&&i?.keyword===`false`){let e=decodePointer(i.instanceLocation).at(-1);t.push({keyword:`false`,location:i.instanceLocation,message:`Unrecognized key: ${JSON.stringify(e)}`,object:r.instanceLocation}),n++}else t.push({keyword:r.keyword,location:r.instanceLocation,message:r.error})}let n=t.filter(e=>e.object===void 0||!t.some(t=>t.object===void 0&&(t.location===e.location||t.location.startsWith(`${e.location}/`))));return n.filter((e,t)=>{let r=n[t+1];return r===void 0?!0:r.location.startsWith(`${e.location}/`)?!1:e.keyword!==`$ref`||r.location!==e.location}).map(({location:e,message:t,object:n})=>{let r=decodePointer(n??e);return r.length===0?{message:t}:{message:t,path:r}})}function decodePointer(e){return e.split(`/`).slice(1).map(e=>{let t=e;try{t=decodeURIComponent(e)}catch{}return t.replaceAll(`~1`,`/`).replaceAll(`~0`,`~`)})}export{UNSPECIFIED_INPUT_SCHEMA,defineJsonSchema,isToolSchema,serializeInputSchema,serializeModelInputSchema,serializeOutputSchema,toInputSchema,toModelSchema,toOutputSchema,withOptionalStringProperty};

package/dist/src/tools/workflow-definition.d.ts

@@ -1,115 +1,217 @@
 import type { StandardJSONSchemaV1, StandardSchemaV1 } from "#compiled/@standard-schema/spec/index.js";
 import type { Approval } from "#approval/definition.js";
-import type { JsonObject, JsonValue } from "#shared/json.js";
-import { type PublicToolDefinition, type ToolContext, type ToolInputRequest, type ToolInputResponse } from "#tools/definition.js";
+import type { MessageResult, SendTurnOptions } from "#client/types.js";
+import type { JsonObject } from "#shared/json.js";
+import { type PublicToolDefinition, type ToolContext, type ToolInputRequest, type ToolInputRequestOptions, type ToolInputResponse } from "#tools/definition.js";
 import type { ToolModelOutput } from "#tools/model-output.js";
-/** Fixed acknowledgement returned when a background task is admitted. */
-export interface TaskReceipt {
-    readonly status: "working";
-    readonly taskId: string;
-}
-export interface AgentInput {
-    readonly agentId?: string;
-    readonly message: string;
-    readonly outputSchema?: JsonObject;
-}
-type JsonSchemaProperties = Readonly<Record<string, JsonObject>>;
-type JsonSchemaRequiredKeys<TProperties extends JsonSchemaProperties, TRequired> = TRequired extends readonly string[] ? Extract<TRequired[number], keyof TProperties> : never;
-type Simplify<TValue> = {
-    [TKey in keyof TValue]: TValue[TKey];
-};
-type JsonSchemaObjectOutput<TProperties extends JsonSchemaProperties, TRequired> = Simplify<{
-    -readonly [TKey in JsonSchemaRequiredKeys<TProperties, TRequired>]-?: JsonSchemaOutput<TProperties[TKey]>;
-} & {
-    -readonly [TKey in Exclude<keyof TProperties, JsonSchemaRequiredKeys<TProperties, TRequired>>]?: JsonSchemaOutput<TProperties[TKey]>;
-}>;
-type JsonSchemaOutput<TSchema> = TSchema extends {
-    readonly const: infer TValue;
-} ? Extract<TValue, JsonValue> : TSchema extends {
-    readonly enum: readonly (infer TValue)[];
-} ? Extract<TValue, JsonValue> : TSchema extends {
-    readonly type: "object";
-    readonly properties: infer TProperties extends JsonSchemaProperties;
-    readonly required?: infer TRequired;
-} ? JsonSchemaObjectOutput<TProperties, TRequired> : TSchema extends {
-    readonly type: "array";
-    readonly items: infer TItems extends JsonObject;
-} ? JsonSchemaOutput<TItems>[] : TSchema extends {
-    readonly type: "string";
-} ? string : TSchema extends {
-    readonly type: "integer" | "number";
-} ? number : TSchema extends {
-    readonly type: "boolean";
-} ? boolean : TSchema extends {
-    readonly type: "null";
-} ? null : JsonValue;
+import { type WorkflowToolEntryPoint } from "#tools/workflow-entry-point.js";
+export type { WorkflowToolEntryPoint };
 export interface WorkflowAgentMetadata {
     readonly description: string;
 }
 /** Context capabilities available inside an authored `"use step"` helper. */
 export type WorkflowStepToolContext = Pick<ToolContext, "abortSignal" | "callId" | "session" | "toolName" | "getToken" | "requireAuth">;
-interface WorkflowAgent {
-    <const TOutputSchema extends JsonObject>(target: string, input: AgentInput & {
-        readonly outputSchema: TOutputSchema;
-    }): Promise<JsonSchemaOutput<TOutputSchema>>;
-    (target: string, input: AgentInput): Promise<JsonValue>;
+/** Options for one message to a `ctx.agent` session. */
+export interface AgentSendOptions<TOutput = unknown> {
+    /** Structured output for the turn, as on the client's `send`. */
+    readonly outputSchema?: SendTurnOptions<TOutput>["outputSchema"];
+    /** Aborting cancels the turn this message started or joined; the turn still reports. */
+    readonly signal?: AbortSignal;
 }
 /**
- * Context supplied to a workflow tool body. When passed directly to a step,
- * eve replaces it with {@link WorkflowStepToolContext}.
+ * How one agent turn ended, as the client's `MessageResult` reports it:
+ * `"waiting"` when the session waits for its next message, including after a
+ * cancelled turn, which carries neither `data` nor `message`; `"completed"`
+ * when the session ended with the turn; and `"failed"` when the turn failed,
+ * with the reason in `error`.
  */
-export type WorkflowToolContext = Pick<ToolContext, "abortSignal" | "callId" | "session" | "toolName" | "getToken" | "requireAuth"> & {
-    /** Invoke an agent by its invocation name. */
-    agent: WorkflowAgent;
+export type AgentMessageResult<TOutput = unknown> = Pick<MessageResult<TOutput>, "data" | "message" | "status"> & {
+    /** Why the turn failed, present only when `status` is `"failed"`. */
+    readonly error?: {
+        readonly message: string;
+    };
+};
+/** The response to one message sent to a `ctx.agent` session. */
+export interface AgentResponse<TOutput = unknown> {
+    /** Resolves when the turn the message started or joined ends. */
+    result(): Promise<AgentMessageResult<TOutput>>;
+}
+/**
+ * A session the workflow run owns, opened by its first `send` and ended when
+ * the run finishes. Only the run can address it.
+ */
+export interface AgentSession {
+    /**
+     * Delivers a message. It joins the session's running turn, whose result the
+     * response resolves, or starts the next turn when the session is idle or the
+     * running turn ends before the agent reads it.
+     */
+    send<TOutput = unknown>(message: string, options?: AgentSendOptions<TOutput>): Promise<AgentResponse<TOutput>>;
+}
+/** Members the context of every workflow tool entry point shares. */
+export type WorkflowSharedContext = Pick<ToolContext, "session" | "toolName" | "getToken" | "requireAuth"> & {
+    /**
+     * Returns a new session with the agent of this invocation name. Nothing
+     * starts until the first `send`.
+     */
+    agent(name: string): AgentSession;
     /** Metadata for agents callable by this workflow, including hidden agents. */
     agents: Readonly<Record<string, WorkflowAgentMetadata>>;
-    /** Ask the human on the session's channel; awaiting the answer suspends the run. */
-    ask(request: ToolInputRequest): PromiseLike<ToolInputResponse>;
+    /**
+     * Ask the human on the session's channel; awaiting the answer suspends the
+     * run. The request is withdrawn, resolving as `cancelled`, when
+     * `options.signal` or the call's `abortSignal` aborts.
+     */
+    ask(request: ToolInputRequest, options?: ToolInputRequestOptions): PromiseLike<ToolInputResponse>;
+};
+/**
+ * Context of an `execute(input, ctx)` or `task(input, ctx)` call. When passed
+ * directly to a step, eve replaces it with {@link WorkflowStepToolContext}.
+ */
+export type WorkflowToolContext = WorkflowSharedContext & Pick<ToolContext, "callId"> & {
+    /**
+     * Aborts when the call's work should stop: the call is cancelled, by
+     * `task_cancel`, `session.cancel()`, a failed turn, or the end of the
+     * session, or, for an `execute` call, a steering message arrives while the
+     * turn waits on it. Stop and return what you have. After a steering
+     * message the call settles with what the body returns, or with
+     * `{ interrupted: true }` if it rejects; a cancelled call's result is
+     * discarded. A task never sees a steering message.
+     */
+    readonly abortSignal: AbortSignal;
+};
+/**
+ * One call a `serve` body receives: the call that started the task, or a
+ * later call the model made with the task's `taskId`.
+ */
+export interface WorkflowServeCall<TInput = unknown> {
+    readonly callId: string;
+    /** The call's input, validated by the tool's `inputSchema`. */
+    readonly input: TInput;
+    /**
+     * Aborts when the task's current stretch of work is cancelled or the
+     * session ends. A stretch starts when a call reaches an idle task and ends
+     * when a reply or a cancel settles its calls; calls that arrive during it
+     * share its signal, and the next stretch gets a new one.
+     */
+    readonly abortSignal: AbortSignal;
+}
+/**
+ * Resolves with the task's next call. The first `receive()` resolves at once
+ * with the call that started the task; each later one with the next call made
+ * with the task's `taskId`, in arrival order. A pending `receive()` is shared:
+ * calling it again returns the same promise. A call counts as received once its
+ * promise resolves, even if that promise lost a `Promise.race`, and the next
+ * `ctx.reply()` settles it, so keep a raced promise until you read its call.
+ * It rejects when the session ends.
+ */
+export type WorkflowServeReceive<TInput = unknown> = () => Promise<WorkflowServeCall<TInput>>;
+/**
+ * Context of a `serve(receive, ctx)` task. Each call brings its own `callId`
+ * and `abortSignal` from `receive()`, and steering never interrupts a task, so
+ * the context has neither. `session` (its turn and auth) and `agents`
+ * describe the latest call received, the call the body serves now. A session
+ * opened with `agent()` is the child of the call served when it opens, and
+ * each message sent to it carries the auth of the call served when it is sent.
+ * `ctx.ask` throws while no call is
+ * waiting for a result. When passed directly to a step, eve replaces it with
+ * {@link WorkflowStepToolContext} for the latest call waiting for a result.
+ */
+export type WorkflowServeContext<TOutput = unknown> = WorkflowSharedContext & {
+    /**
+     * Settles every call received so far with `output`, and the task goes idle
+     * until its next call. A reply with no call left to settle, including one
+     * after a cancel, is dropped.
+     */
+    reply(output: TOutput): void;
 };
 declare const WORKFLOW_TOOL_BRAND: unique symbol;
-/** A static tool whose executor runs as a durable workflow. Its executor must start with "use workflow". */
-export interface BlockingWorkflowToolDefinition<TInput = unknown, TOutput = unknown> extends PublicToolDefinition<TInput, TOutput> {
+interface WorkflowToolDefinitionBase<TInput, TOutput> extends PublicToolDefinition<TInput, TOutput> {
     readonly [WORKFLOW_TOOL_BRAND]: true;
-    readonly execution?: never;
-    execute(input: TInput, ctx: WorkflowToolContext): Promise<TOutput> | AsyncIterable<TOutput>;
     approval?: Approval<unknown extends TInput ? Record<string, unknown> : TInput>;
     toModelOutput?: (output: TOutput) => ToolModelOutput | Promise<ToolModelOutput>;
 }
-export type BackgroundWorkflowToolDefinition<TInput, TOutput> = PublicToolDefinition<TInput, TaskReceipt> & {
-    readonly [WORKFLOW_TOOL_BRAND]: true;
-    readonly execution: "background";
-    execute(input: TInput, ctx: WorkflowToolContext): Promise<TOutput> | AsyncIterable<unknown>;
-    approval?: Approval<unknown extends TInput ? Record<string, unknown> : TInput>;
-    toModelOutput?: (output: TaskReceipt) => ToolModelOutput | Promise<ToolModelOutput>;
-};
-/** A static tool whose executor runs as a durable workflow. */
-export type WorkflowToolDefinition<TInput = unknown, TOutput = unknown> = BlockingWorkflowToolDefinition<TInput, TOutput> | BackgroundWorkflowToolDefinition<TInput, TOutput>;
+/** A workflow tool whose calls are ordinary tool calls: the turn waits until each settles. */
+export interface WorkflowExecuteToolDefinition<TInput = unknown, TOutput = unknown> extends WorkflowToolDefinitionBase<TInput, TOutput> {
+    execute(input: TInput, ctx: WorkflowToolContext): Promise<TOutput> | AsyncIterable<TOutput>;
+    task?: never;
+    serve?: never;
+}
+/**
+ * A workflow tool whose every call runs as a task: the model gets a receipt at
+ * once and the conversation continues, and the result arrives later in a
+ * `task.result` message.
+ */
+export interface WorkflowTaskToolDefinition<TInput = unknown, TOutput = unknown> extends WorkflowToolDefinitionBase<TInput, TOutput> {
+    task(input: TInput, ctx: WorkflowToolContext): Promise<TOutput> | AsyncIterable<TOutput>;
+    execute?: never;
+    serve?: never;
+}
+/**
+ * A workflow tool whose calls reach resumable tasks. A call without `taskId`
+ * starts a task, whose body runs once and gets that call and every later call
+ * made with its `taskId` from `receive()`; each `ctx.reply()` delivers a
+ * result. eve adds the optional `taskId` to the tool's model input, so
+ * `inputSchema` must not declare its own. Returning settles the calls still
+ * waiting and ends the task; throwing fails them.
+ */
+export interface WorkflowServeToolDefinition<TInput = unknown, TOutput = unknown> extends WorkflowToolDefinitionBase<TInput, TOutput> {
+    serve(receive: WorkflowServeReceive<TInput>, ctx: WorkflowServeContext<TOutput>): Promise<TOutput>;
+    execute?: never;
+    task?: never;
+}
+/**
+ * A static tool whose entry point runs as a durable workflow and must start
+ * with "use workflow". It defines exactly one entry point.
+ */
+export type WorkflowToolDefinition<TInput = unknown, TOutput = unknown> = WorkflowExecuteToolDefinition<TInput, TOutput> | WorkflowTaskToolDefinition<TInput, TOutput> | WorkflowServeToolDefinition<TInput, TOutput>;
 type Unbranded<T> = T extends unknown ? Omit<T, typeof WORKFLOW_TOOL_BRAND> : never;
-type BackgroundReturn<T> = T extends AsyncGenerator<unknown, infer Output> ? Output : T extends AsyncIterable<unknown> ? null : Awaited<T>;
-type BackgroundDefinition<TInput, TReturn> = Omit<BackgroundWorkflowToolDefinition<TInput, BackgroundReturn<TReturn>>, typeof WORKFLOW_TOOL_BRAND | "execute"> & {
-    execute(input: TInput, ctx: WorkflowToolContext): TReturn;
-};
 type WorkflowReturn<T> = T extends AsyncIterable<infer Output> ? Output : Awaited<T>;
 type Schema = StandardSchemaV1<unknown, unknown> | StandardJSONSchemaV1<unknown, unknown>;
-type Definition<TInput, TReturn> = Omit<BlockingWorkflowToolDefinition<TInput, WorkflowReturn<TReturn>>, typeof WORKFLOW_TOOL_BRAND | "execute"> & {
+type EntryPointReturn<TOutput> = Promise<TOutput> | AsyncIterable<TOutput>;
+type InferOutput<TSchema extends StandardJSONSchemaV1<unknown, unknown>> = StandardJSONSchemaV1.InferOutput<TSchema>;
+type InferInput<TSchema extends Schema> = StandardSchemaV1.InferOutput<TSchema>;
+type DefinitionFields<TInput, TOutput> = Omit<WorkflowToolDefinitionBase<TInput, TOutput>, typeof WORKFLOW_TOOL_BRAND>;
+type ExecuteDefinition<TInput, TReturn> = DefinitionFields<TInput, WorkflowReturn<TReturn>> & {
     execute(input: TInput, ctx: WorkflowToolContext): TReturn;
+    task?: never;
+    serve?: never;
+};
+type TaskDefinition<TInput, TReturn> = DefinitionFields<TInput, WorkflowReturn<TReturn>> & {
+    task(input: TInput, ctx: WorkflowToolContext): TReturn;
+    execute?: never;
+    serve?: never;
 };
-export declare function defineWorkflowTool<TInputSchema extends Schema, TOutputSchema extends StandardJSONSchemaV1<unknown, unknown>, TReturn extends Promise<StandardJSONSchemaV1.InferOutput<TOutputSchema>> | AsyncIterable<StandardJSONSchemaV1.InferOutput<TOutputSchema>>>(definition: Omit<Definition<StandardSchemaV1.InferOutput<TInputSchema>, TReturn>, "inputSchema" | "outputSchema"> & {
+type ServeDefinition<TInput, TOutput> = DefinitionFields<TInput, TOutput> & {
+    serve(receive: WorkflowServeReceive<TInput>, ctx: WorkflowServeContext<TOutput>): Promise<TOutput>;
+    execute?: never;
+    task?: never;
+};
+type WithSchemas<TDefinition, TInputSchema, TOutputSchema> = Omit<TDefinition, "inputSchema" | "outputSchema"> & {
     inputSchema: TInputSchema;
     outputSchema: TOutputSchema;
-}): BlockingWorkflowToolDefinition<StandardSchemaV1.InferOutput<TInputSchema>, StandardJSONSchemaV1.InferOutput<TOutputSchema>>;
-export declare function defineWorkflowTool<TSchema extends Schema, TReturn extends Promise<unknown> | AsyncIterable<unknown>>(definition: Omit<BackgroundDefinition<StandardSchemaV1.InferOutput<TSchema>, TReturn>, "inputSchema"> & {
+};
+type WithInputSchema<TDefinition, TSchema> = Omit<TDefinition, "inputSchema"> & {
     inputSchema: TSchema;
-}): BackgroundWorkflowToolDefinition<StandardSchemaV1.InferOutput<TSchema>, BackgroundReturn<TReturn>>;
-export declare function defineWorkflowTool<TReturn extends Promise<unknown> | AsyncIterable<unknown>>(definition: BackgroundDefinition<Record<string, unknown>, TReturn> & {
+};
+export declare function defineWorkflowTool<TInputSchema extends Schema, TOutputSchema extends StandardJSONSchemaV1<unknown, unknown>, TReturn extends EntryPointReturn<InferOutput<TOutputSchema>>>(definition: WithSchemas<ExecuteDefinition<InferInput<TInputSchema>, TReturn>, TInputSchema, TOutputSchema>): WorkflowExecuteToolDefinition<InferInput<TInputSchema>, InferOutput<TOutputSchema>>;
+export declare function defineWorkflowTool<TInputSchema extends Schema, TOutputSchema extends StandardJSONSchemaV1<unknown, unknown>, TReturn extends EntryPointReturn<InferOutput<TOutputSchema>>>(definition: WithSchemas<TaskDefinition<InferInput<TInputSchema>, TReturn>, TInputSchema, TOutputSchema>): WorkflowTaskToolDefinition<InferInput<TInputSchema>, InferOutput<TOutputSchema>>;
+export declare function defineWorkflowTool<TInputSchema extends Schema, TOutputSchema extends StandardJSONSchemaV1<unknown, unknown>>(definition: WithSchemas<ServeDefinition<InferInput<TInputSchema>, InferOutput<TOutputSchema>>, TInputSchema, TOutputSchema>): WorkflowServeToolDefinition<InferInput<TInputSchema>, InferOutput<TOutputSchema>>;
+export declare function defineWorkflowTool<TSchema extends Schema, TReturn extends EntryPointReturn<unknown>>(definition: WithInputSchema<ExecuteDefinition<InferInput<TSchema>, TReturn>, TSchema>): WorkflowExecuteToolDefinition<InferInput<TSchema>, WorkflowReturn<TReturn>>;
+export declare function defineWorkflowTool<TSchema extends Schema, TReturn extends EntryPointReturn<unknown>>(definition: WithInputSchema<TaskDefinition<InferInput<TSchema>, TReturn>, TSchema>): WorkflowTaskToolDefinition<InferInput<TSchema>, WorkflowReturn<TReturn>>;
+export declare function defineWorkflowTool<TSchema extends Schema>(definition: WithInputSchema<ServeDefinition<InferInput<TSchema>, unknown>, TSchema>): WorkflowServeToolDefinition<InferInput<TSchema>>;
+export declare function defineWorkflowTool<TReturn extends EntryPointReturn<unknown>>(definition: ExecuteDefinition<Record<string, unknown>, TReturn> & {
     inputSchema: JsonObject;
-}): BackgroundWorkflowToolDefinition<Record<string, unknown>, BackgroundReturn<TReturn>>;
-export declare function defineWorkflowTool<TSchema extends Schema, TReturn extends Promise<unknown> | AsyncIterable<unknown>>(definition: Omit<Definition<StandardSchemaV1.InferOutput<TSchema>, TReturn>, "inputSchema"> & {
-    inputSchema: TSchema;
-}): BlockingWorkflowToolDefinition<StandardSchemaV1.InferOutput<TSchema>, WorkflowReturn<TReturn>>;
-export declare function defineWorkflowTool<TReturn extends Promise<unknown> | AsyncIterable<unknown>>(definition: Definition<Record<string, unknown>, TReturn> & {
+}): WorkflowExecuteToolDefinition<Record<string, unknown>, WorkflowReturn<TReturn>>;
+export declare function defineWorkflowTool<TReturn extends EntryPointReturn<unknown>>(definition: TaskDefinition<Record<string, unknown>, TReturn> & {
+    inputSchema: JsonObject;
+}): WorkflowTaskToolDefinition<Record<string, unknown>, WorkflowReturn<TReturn>>;
+export declare function defineWorkflowTool(definition: ServeDefinition<Record<string, unknown>, unknown> & {
     inputSchema: JsonObject;
-}): BlockingWorkflowToolDefinition<Record<string, unknown>, WorkflowReturn<TReturn>>;
-export declare function defineWorkflowTool<TInput = unknown, TOutput = unknown>(definition: Unbranded<WorkflowToolDefinition<TInput, TOutput>>): WorkflowToolDefinition<TInput, TOutput>;
+}): WorkflowServeToolDefinition<Record<string, unknown>>;
+export declare function defineWorkflowTool<TInput = unknown, TOutput = unknown>(definition: Unbranded<WorkflowExecuteToolDefinition<TInput, TOutput>>): WorkflowExecuteToolDefinition<TInput, TOutput>;
+export declare function defineWorkflowTool<TInput = unknown, TOutput = unknown>(definition: Unbranded<WorkflowTaskToolDefinition<TInput, TOutput>>): WorkflowTaskToolDefinition<TInput, TOutput>;
+export declare function defineWorkflowTool<TInput = unknown, TOutput = unknown>(definition: Unbranded<WorkflowServeToolDefinition<TInput, TOutput>>): WorkflowServeToolDefinition<TInput, TOutput>;
 export declare function isWorkflowToolDefinition(value: unknown): boolean;
-export {};
+/** The entry points a definition defines; a workflow tool defines exactly one. */
+export declare function readWorkflowToolEntryPoints(definition: object): WorkflowToolEntryPoint[];

package/dist/src/tools/workflow-definition.js

@@ -1 +1 @@
-import{stampToolDefinition}from"#tools/definition.js";const WORKFLOW_TOOL_BRAND=Symbol.for(`eve:workflow-tool-brand`);function defineWorkflowTool(e){return stampToolDefinition(e,`defineWorkflowTool`),Object.assign(e,{[WORKFLOW_TOOL_BRAND]:!0})}function isWorkflowToolDefinition(e){return typeof e==`object`&&!!e&&Reflect.get(e,WORKFLOW_TOOL_BRAND)===!0}export{defineWorkflowTool,isWorkflowToolDefinition};
+import{stampToolDefinition}from"#tools/definition.js";import{WORKFLOW_TOOL_ENTRY_POINTS}from"#tools/workflow-entry-point.js";const WORKFLOW_TOOL_BRAND=Symbol.for(`eve:workflow-tool-brand`);function defineWorkflowTool(e){if(`execution`in e)throw Error(`"execution" was replaced by task(). Define task(input, ctx) to run each call as a task.`);return assertOneEntryPoint(e),stampToolDefinition(e,`defineWorkflowTool`),Object.assign(e,{[WORKFLOW_TOOL_BRAND]:!0})}function isWorkflowToolDefinition(e){return typeof e==`object`&&!!e&&Reflect.get(e,WORKFLOW_TOOL_BRAND)===!0}function readWorkflowToolEntryPoints(e){return WORKFLOW_TOOL_ENTRY_POINTS.filter(t=>Reflect.get(e,t)!==void 0)}const ENTRY_POINT_LIST=new Intl.ListFormat(`en`,{type:`conjunction`});function assertOneEntryPoint(e){let t=readWorkflowToolEntryPoints(e);if(t.length===1)return;let n=t.length===0?`none`:ENTRY_POINT_LIST.format(t);throw Error(`Define exactly one of execute(input, ctx), task(input, ctx), or serve(receive, ctx); this tool defines ${n}.`)}export{defineWorkflowTool,isWorkflowToolDefinition,readWorkflowToolEntryPoints};

package/dist/src/tools/workflow-entry-point.d.ts

@@ -0,0 +1,3 @@
+/** The method a workflow tool defines, which decides how its calls run. */
+export type WorkflowToolEntryPoint = "execute" | "task" | "serve";
+export declare const WORKFLOW_TOOL_ENTRY_POINTS: readonly WorkflowToolEntryPoint[];

package/dist/src/tools/workflow-entry-point.js

@@ -0,0 +1 @@
+const WORKFLOW_TOOL_ENTRY_POINTS=[`execute`,`task`,`serve`];export{WORKFLOW_TOOL_ENTRY_POINTS};

package/dist/src/tracing/agent-action-instrumentation.d.ts

@@ -1,13 +1,11 @@
 import { type Context, type SpanContext, type Tracer } from "#compiled/@opentelemetry/api/index.js";
-import type { InstrumentationActionStartedEvent, InstrumentationAttemptScope, InstrumentationProviderDefinition, InstrumentationSessionTransitionEvent } from "#instrumentation/lifecycle.js";
+import type { InstrumentationActionStartedEvent, InstrumentationAttemptScope, InstrumentationProviderDefinition } from "#instrumentation/lifecycle.js";
 import type { AgentSpanIdGenerator } from "#tracing/agent-span-id-generator.js";
 import type { AgentTraceStateStore } from "#tracing/agent-trace-state.js";
 interface AgentActionInstrumentation {
     readonly events: Pick<NonNullable<InstrumentationProviderDefinition["events"]>, "action.completed" | "action.failed" | "action.started">;
     deleteForSession(sessionId: string): void | PromiseLike<void>;
     failForAttempt(scope: InstrumentationAttemptScope, error: unknown): Promise<void>;
-    flushSettledInvocations(): Promise<void>;
-    flushForSessionTransition(event: InstrumentationSessionTransitionEvent): Promise<void>;
     contextFor(sessionId: string, turnId: string, callId: string): Promise<AgentActionContext | undefined>;
 }
 export interface AgentActionContext {

package/dist/src/tracing/agent-action-instrumentation.js

@@ -1 +1 @@
-import{normalizeChannelAudience}from"#shared/channel-audience.js";import{AGENT_SPAN_NAMES,workflowInvocationSpanName}from"#tracing/agent-span-contract.js";import{isSampledTrace}from"#tracing/sampled-trace.js";import{ROOT_CONTEXT,SpanKind,trace}from"#compiled/@opentelemetry/api/index.js";import{actionIdempotencyKey,attemptIdempotencyKey}from"#instrumentation/lifecycle.js";import{agentSpanNamingAttributes}from"#tracing/agent-span-naming.js";import{contentAttribute,textContentAttribute}from"#tracing/agent-otel-content.js";import{recordAgentSpanError}from"#tracing/agent-span-error.js";import{agentTraceIdentityAttributes}from"#tracing/agent-otel-attributes.js";import{setAgentUsage}from"#tracing/agent-otel-usage.js";import{withChannelAudience}from"#tracing/channel-audience-context.js";function createAgentActionInstrumentation(e){let t=new Map,onStarted=async n=>{let r=await e.resolveTraceContext(n);if(r===void 0||!isSampledTrace(r))return;let i=await e.stateStore.getAction(n.idempotencyKey)??{attemptIndex:n.scope.attemptIndex,callId:n.callId,channelAudience:normalizeChannelAudience(n.scope.channelAudience),inputAttribute:e.recordInputs?contentAttribute(n.input):void 0,isWorkflowTool:n.isWorkflowTool===!0,kind:n.kind,name:n.name,parent:{spanId:e.idGenerator.deriveSpanId(attemptIdempotencyKey(n.scope)),traceFlags:r.traceFlags,traceId:r.traceId},rootSessionId:n.scope.rootSessionId??n.scope.sessionId,sessionId:n.scope.sessionId,spanId:e.idGenerator.deriveSpanId(`action:${n.idempotencyKey}`),startTimeMs:Date.now(),stepIndex:n.scope.stepIndex,turnId:n.scope.turnId};await e.stateStore.setAction(n.idempotencyKey,i),n.isWorkflowTool===!0&&await e.stateStore.setActionAnchor(n.idempotencyKey,i);let a=t.get(n.scope.attemptId)??new Set;a.add(n.idempotencyKey),t.set(n.scope.attemptId,a)},onTerminal=async t=>{let n=await e.stateStore.getAction(t.idempotencyKey);if(n!==void 0)try{finishActionSpan(n,t)}finally{await e.stateStore.deleteAction(t.idempotencyKey),forget(t.idempotencyKey)}},startSpan=t=>{let n=isAgentInvocation(t.kind),r=t.kind===`tool-call`?t.workflowName:void 0,i=r===void 0?AGENT_SPAN_NAMES.action:workflowInvocationSpanName(r),a=e.idGenerator.withSpanId(t.spanId,()=>e.tracer.startSpan(AGENT_SPAN_NAMES.action,{attributes:{"agent.action.call_id":t.callId,"agent.action.kind":t.kind,"agent.action.name":t.name,"agent.framework.name":`eve`,"agent.framework.version":e.frameworkVersion,"agent.step.attempt":t.attemptIndex,"agent.step.index":t.stepIndex,"agent.turn.id":t.turnId,...agentSpanNamingAttributes(i,r===void 0?void 0:`invoke_workflow`),...agentTraceIdentityAttributes({rootSessionId:t.rootSessionId,sessionId:t.sessionId}),...r===void 0?void 0:{"gen_ai.operation.name":`invoke_workflow`,"gen_ai.workflow.name":r},...n?{"gen_ai.agent.name":t.name,"agent.invocation.role":`caller`}:void 0},kind:t.kind===`remote-agent-call`?SpanKind.CLIENT:SpanKind.INTERNAL,startTime:t.startTimeMs},contextFromActionState(t)));return r!==void 0&&updateSpanName(a,i),!n&&t.inputAttribute!==void 0&&a.setAttribute(`gen_ai.tool.call.arguments`,t.inputAttribute),a};return{async contextFor(t,n,r){let i=actionIdempotencyKey(t,n,r),a=await e.stateStore.getAction(i);if(a!==void 0)return actionContext(a);let o=await e.stateStore.findAction(t,r);return o===void 0?void 0:actionContext(o)},async deleteForSession(t){await e.stateStore.deleteActions(t),await e.stateStore.deleteActionAnchors(t),await e.stateStore.deleteInvocations(t)},async failForAttempt(n,r){let i=t.get(n.attemptId);if(i!==void 0){t.delete(n.attemptId);for(let t of i){let n=await e.stateStore.getAction(t);if(n===void 0)continue;let i=startSpan(n);recordAgentSpanError(i,r),i.end(),await e.stateStore.deleteAction(t)}}},flushSettledInvocations:()=>flushInvocations(),async flushForSessionTransition(e){let t=e.type===`session.completed`?{outcome:`abandoned`}:e.type===`session.failed`?{error:e.error,outcome:`failed`}:void 0;await flushInvocations(e.sessionId,t)},events:{"action.completed":onTerminal,"action.failed":onTerminal,"action.started":onStarted}};async function flushInvocations(t,n){for(let r of await e.stateStore.findInvocations(t)){let t=r.terminal??n;t!==void 0&&(finishInvocationSpan(r,t),await e.stateStore.deleteInvocation(actionIdempotencyKey(r.sessionId,r.turnId,r.callId)))}}function forget(e){for(let[n,r]of t)r.delete(e),r.size===0&&t.delete(n)}function finishActionSpan(t,n){let r=startSpan(t);if(r.setAttribute(`agent.action.outcome`,n.outcome),n.type===`action.failed`)n.errorCode!==void 0&&r.setAttribute(`agent.action.error.code`,n.errorCode),recordActionError(r,n.error,n.errorCode);else if(n.output.type===`error`)recordActionError(r,n.output.error);else if(n.usage!==void 0&&setAgentUsage(r,n.usage),e.recordOutputs&&!isAgentInvocation(t.kind)){let e=contentAttribute(n.output.output);e!==void 0&&r.setAttribute(`gen_ai.tool.call.result`,e)}r.end(n.acceptedAtMs)}function finishInvocationSpan(t,n){let r=startSpan(t);r.setAttribute(`agent.action.outcome`,n.outcome),n.usage!==void 0&&setAgentUsage(r,n.usage),n.outcome===`failed`&&recordAgentSpanError(r,e.recordOutputs&&t.recordOutputs===!0?n.error:void 0),r.end(n.acceptedAtMs)}}function actionContext(e){let t={isRemote:!1,spanId:e.spanId,traceFlags:e.parent.traceFlags,traceId:e.parent.traceId};return{context:withChannelAudience(trace.setSpan(ROOT_CONTEXT,trace.wrapSpanContext(t)),e.channelAudience),spanContext:t}}function contextFromActionState(e){return withChannelAudience(trace.setSpan(ROOT_CONTEXT,trace.wrapSpanContext({...e.parent,isRemote:!1})),e.channelAudience)}function isAgentInvocation(e){return e===`subagent-call`||e===`remote-agent-call`}function updateSpanName(e,t){let n=Reflect.get(e,`updateName`);typeof n==`function`&&Reflect.apply(n,e,[t])}function recordActionError(e,t,n){if(t instanceof Error||t===void 0){recordAgentSpanError(e,t,n);return}let r=serializedErrorDetail(t);if(r===void 0){recordAgentSpanError(e,void 0,n);return}let i=Error(r);n!==void 0&&(i.name=n),recordAgentSpanError(e,i,n)}function serializedErrorDetail(e){if(typeof e==`string`)return textContentAttribute(e);let t=contentAttribute(e);if(typeof e!=`object`||!e||Array.isArray(e))return t;let n=Reflect.get(e,`message`);return typeof n==`string`?textContentAttribute(t===void 0?n:`${n}\n${t}`):t}export{createAgentActionInstrumentation};
+import{normalizeChannelAudience}from"#shared/channel-audience.js";import{AGENT_SPAN_NAMES}from"#tracing/agent-span-contract.js";import{isSampledTrace}from"#tracing/sampled-trace.js";import{ROOT_CONTEXT,SpanKind,trace}from"#compiled/@opentelemetry/api/index.js";import{actionIdempotencyKey,attemptIdempotencyKey}from"#instrumentation/lifecycle.js";import{agentSpanNamingAttributes}from"#tracing/agent-span-naming.js";import{contentAttribute,textContentAttribute}from"#tracing/agent-otel-content.js";import{recordAgentSpanError}from"#tracing/agent-span-error.js";import{agentTraceIdentityAttributes,traceSessionIdOf}from"#tracing/agent-otel-attributes.js";import{setAgentUsage}from"#tracing/agent-otel-usage.js";import{withChannelAudience}from"#tracing/channel-audience-context.js";function createAgentActionInstrumentation(e){let t=new Map,onStarted=async n=>{let r=await e.resolveTraceContext(n);if(r===void 0||!isSampledTrace(r))return;let i=await e.stateStore.getAction(n.idempotencyKey)??{attemptIndex:n.scope.attemptIndex,callId:n.callId,channelAudience:normalizeChannelAudience(n.scope.channelAudience),inputAttribute:e.recordInputs?contentAttribute(n.input):void 0,kind:n.kind,name:n.name,parent:{spanId:e.idGenerator.deriveSpanId(attemptIdempotencyKey(n.scope)),traceFlags:r.traceFlags,traceId:r.traceId},rootSessionId:n.scope.rootSessionId??n.scope.sessionId,traceSessionId:traceSessionIdOf(n.scope),sessionId:n.scope.sessionId,spanId:e.idGenerator.deriveSpanId(`action:${n.idempotencyKey}`),startTimeMs:Date.now(),stepIndex:n.scope.stepIndex,turnId:n.scope.turnId};await e.stateStore.setAction(n.idempotencyKey,i),n.isWorkflowTool===!0&&await e.stateStore.setActionAnchor(n.idempotencyKey,i);let a=t.get(n.scope.attemptId)??new Set;a.add(n.idempotencyKey),t.set(n.scope.attemptId,a)},onTerminal=async t=>{let n=await e.stateStore.getAction(t.idempotencyKey);if(n!==void 0)try{finishActionSpan(n,t)}finally{await e.stateStore.deleteAction(t.idempotencyKey),forget(t.idempotencyKey)}},startSpan=t=>{let n=isAgentInvocation(t.kind),r=e.idGenerator.withSpanId(t.spanId,()=>e.tracer.startSpan(AGENT_SPAN_NAMES.action,{attributes:{"agent.action.call_id":t.callId,"agent.action.kind":t.kind,"agent.action.name":t.name,"agent.framework.name":`eve`,"agent.framework.version":e.frameworkVersion,"agent.step.attempt":t.attemptIndex,"agent.step.index":t.stepIndex,"agent.turn.id":t.turnId,...agentSpanNamingAttributes(AGENT_SPAN_NAMES.action),...agentTraceIdentityAttributes({rootSessionId:t.rootSessionId,traceSessionId:t.traceSessionId,sessionId:t.sessionId}),...n?{"gen_ai.agent.name":t.name,"agent.invocation.role":`caller`}:void 0},kind:t.kind===`remote-agent-call`?SpanKind.CLIENT:SpanKind.INTERNAL,startTime:t.startTimeMs},contextFromActionState(t)));return!n&&t.inputAttribute!==void 0&&r.setAttribute(`gen_ai.tool.call.arguments`,t.inputAttribute),r};return{async contextFor(t,n,r){let i=actionIdempotencyKey(t,n,r),a=await e.stateStore.getAction(i);if(a!==void 0)return actionContext(a);let o=await e.stateStore.findAction(t,r);return o===void 0?void 0:actionContext(o)},async deleteForSession(t){await e.stateStore.deleteActions(t),await e.stateStore.deleteActionAnchors(t)},async failForAttempt(n,r){let i=t.get(n.attemptId);if(i!==void 0){t.delete(n.attemptId);for(let t of i){let n=await e.stateStore.getAction(t);if(n===void 0)continue;let i=startSpan(n);recordAgentSpanError(i,r),i.end(),await e.stateStore.deleteAction(t)}}},events:{"action.completed":onTerminal,"action.failed":onTerminal,"action.started":onStarted}};function forget(e){for(let[n,r]of t)r.delete(e),r.size===0&&t.delete(n)}function finishActionSpan(t,n){let r=startSpan(t);if(r.setAttribute(`agent.action.outcome`,n.outcome),n.usage!==void 0&&setAgentUsage(r,n.usage),n.type===`action.failed`)n.errorCode!==void 0&&r.setAttribute(`agent.action.error.code`,n.errorCode),recordActionError(r,n.error,n.errorCode);else if(n.output.type===`error`)recordActionError(r,n.output.error);else if(e.recordOutputs&&!isAgentInvocation(t.kind)){let e=contentAttribute(n.output.output);e!==void 0&&r.setAttribute(`gen_ai.tool.call.result`,e)}r.end(n.acceptedAtMs)}}function actionContext(e){let t={isRemote:!1,spanId:e.spanId,traceFlags:e.parent.traceFlags,traceId:e.parent.traceId};return{context:withChannelAudience(trace.setSpan(ROOT_CONTEXT,trace.wrapSpanContext(t)),e.channelAudience),spanContext:t}}function contextFromActionState(e){return withChannelAudience(trace.setSpan(ROOT_CONTEXT,trace.wrapSpanContext({...e.parent,isRemote:!1})),e.channelAudience)}function isAgentInvocation(e){return e===`subagent-call`||e===`remote-agent-call`}function recordActionError(e,t,n){if(t instanceof Error||t===void 0){recordAgentSpanError(e,t,n);return}let r=serializedErrorDetail(t);if(r===void 0){recordAgentSpanError(e,void 0,n);return}let i=Error(r);n!==void 0&&(i.name=n),recordAgentSpanError(e,i,n)}function serializedErrorDetail(e){if(typeof e==`string`)return textContentAttribute(e);let t=contentAttribute(e);if(typeof e!=`object`||!e||Array.isArray(e))return t;let n=Reflect.get(e,`message`);return typeof n==`string`?textContentAttribute(t===void 0?n:`${n}\n${t}`):t}export{createAgentActionInstrumentation};

package/dist/src/tracing/agent-approval-instrumentation.js

@@ -1 +1 @@
-import{normalizeChannelAudience}from"#shared/channel-audience.js";import{AGENT_SPAN_NAMES}from"#tracing/agent-span-contract.js";import{ROOT_CONTEXT,trace}from"#compiled/@opentelemetry/api/index.js";import{agentSpanNamingAttributes}from"#tracing/agent-span-naming.js";import{contentAttribute}from"#tracing/agent-otel-content.js";import{recordAgentSpanError}from"#tracing/agent-span-error.js";import{agentTraceIdentityAttributes}from"#tracing/agent-otel-attributes.js";import{withChannelAudience}from"#tracing/channel-audience-context.js";function createAgentApprovalInstrumentation(e){return{"input.requested":async(t,n)=>{if(t.kind!==`tool-approval`||readState(n.state.get())!==void 0)return;let r=await e.actionContextFor(t.scope.sessionId,t.scope.turnId,t.action.callId);if(r===void 0)return;let i={actionCallId:t.action.callId,actionName:t.action.name,attemptIndex:t.scope.attemptIndex,channelAudience:normalizeChannelAudience(t.scope.channelAudience),parent:{spanId:r.spanContext.spanId,traceFlags:r.spanContext.traceFlags,traceId:r.spanContext.traceId},requestId:t.requestId,rootSessionId:t.scope.rootSessionId??t.scope.sessionId,sessionId:t.scope.sessionId,startTimeMs:Date.now(),stepIndex:t.scope.stepIndex,turnId:t.scope.turnId},a=contentAttribute(t.request);a!==void 0&&(i.requestAttribute=a),n.state.set(i)},"input.resolved":(t,n)=>{let r=readState(n.state.get());if(r===void 0)return;let i=e.idGenerator.withSpanId(e.idGenerator.deriveSpanId(`approval:${t.idempotencyKey}`),()=>e.tracer.startSpan(AGENT_SPAN_NAMES.approval,{attributes:{"agent.action.call_id":r.actionCallId,"agent.action.name":r.actionName,"agent.approval.kind":`tool-approval`,"agent.approval.outcome":t.outcome,"agent.approval.request_id":r.requestId,"agent.framework.name":`eve`,"agent.framework.version":e.frameworkVersion,"agent.step.attempt":r.attemptIndex,"agent.step.index":r.stepIndex,"agent.turn.id":r.turnId,...agentSpanNamingAttributes(`agent.approval`),...agentTraceIdentityAttributes({rootSessionId:r.rootSessionId,sessionId:r.sessionId})},startTime:r.startTimeMs},withChannelAudience(trace.setSpan(ROOT_CONTEXT,trace.wrapSpanContext({...r.parent,isRemote:!1})),r.channelAudience)));if(r.requestAttribute!==void 0&&i.setAttribute(`agent.approval.request`,r.requestAttribute),t.response!==void 0){let e=contentAttribute(t.response);e!==void 0&&i.setAttribute(`agent.approval.response`,e)}t.outcome===`failed`&&recordAgentSpanError(i,t.error),i.end()}}}function readState(e){if(typeof e!=`object`||!e||Array.isArray(e))return;let t=e,n=t.parent;if(typeof n!=`object`||!n||Array.isArray(n))return;let r=n;if(typeof t.actionCallId!=`string`||typeof t.actionName!=`string`||typeof t.attemptIndex!=`number`||typeof r.spanId!=`string`||typeof r.traceFlags!=`number`||typeof r.traceId!=`string`||typeof t.requestId!=`string`||typeof t.rootSessionId!=`string`||typeof t.sessionId!=`string`||typeof t.startTimeMs!=`number`||typeof t.stepIndex!=`number`||typeof t.turnId!=`string`)return;let i=t.requestAttribute;if(i===void 0||typeof i==`string`)return{actionCallId:t.actionCallId,actionName:t.actionName,attemptIndex:t.attemptIndex,channelAudience:normalizeChannelAudience(t.channelAudience),parent:{isRemote:!1,spanId:r.spanId,traceFlags:r.traceFlags,traceId:r.traceId},requestAttribute:i,requestId:t.requestId,rootSessionId:t.rootSessionId,sessionId:t.sessionId,startTimeMs:t.startTimeMs,stepIndex:t.stepIndex,turnId:t.turnId}}export{createAgentApprovalInstrumentation};
+import{normalizeChannelAudience}from"#shared/channel-audience.js";import{AGENT_SPAN_NAMES}from"#tracing/agent-span-contract.js";import{ROOT_CONTEXT,trace}from"#compiled/@opentelemetry/api/index.js";import{agentSpanNamingAttributes}from"#tracing/agent-span-naming.js";import{contentAttribute}from"#tracing/agent-otel-content.js";import{recordAgentSpanError}from"#tracing/agent-span-error.js";import{agentTraceIdentityAttributes,traceSessionIdOf}from"#tracing/agent-otel-attributes.js";import{withChannelAudience}from"#tracing/channel-audience-context.js";import{decodeTraceSessionId}from"#tracing/agent-trace-context-codec.js";function createAgentApprovalInstrumentation(e){return{"input.requested":async(t,n)=>{if(t.kind!==`tool-approval`||readState(n.state.get())!==void 0)return;let r=await e.actionContextFor(t.scope.sessionId,t.scope.turnId,t.action.callId);if(r===void 0)return;let i={actionCallId:t.action.callId,actionName:t.action.name,attemptIndex:t.scope.attemptIndex,channelAudience:normalizeChannelAudience(t.scope.channelAudience),parent:{spanId:r.spanContext.spanId,traceFlags:r.spanContext.traceFlags,traceId:r.spanContext.traceId},requestId:t.requestId,rootSessionId:t.scope.rootSessionId??t.scope.sessionId,traceSessionId:traceSessionIdOf(t.scope),sessionId:t.scope.sessionId,startTimeMs:Date.now(),stepIndex:t.scope.stepIndex,turnId:t.scope.turnId},a=contentAttribute(t.request);a!==void 0&&(i.requestAttribute=a),n.state.set(i)},"input.resolved":(t,n)=>{let r=readState(n.state.get());if(r===void 0)return;let i=e.idGenerator.withSpanId(e.idGenerator.deriveSpanId(`approval:${t.idempotencyKey}`),()=>e.tracer.startSpan(AGENT_SPAN_NAMES.approval,{attributes:{"agent.action.call_id":r.actionCallId,"agent.action.name":r.actionName,"agent.approval.kind":`tool-approval`,"agent.approval.outcome":t.outcome,"agent.approval.request_id":r.requestId,"agent.framework.name":`eve`,"agent.framework.version":e.frameworkVersion,"agent.step.attempt":r.attemptIndex,"agent.step.index":r.stepIndex,"agent.turn.id":r.turnId,...agentSpanNamingAttributes(`agent.approval`),...agentTraceIdentityAttributes({rootSessionId:r.rootSessionId,traceSessionId:r.traceSessionId,sessionId:r.sessionId})},startTime:r.startTimeMs},withChannelAudience(trace.setSpan(ROOT_CONTEXT,trace.wrapSpanContext({...r.parent,isRemote:!1})),r.channelAudience)));if(r.requestAttribute!==void 0&&i.setAttribute(`agent.approval.request`,r.requestAttribute),t.response!==void 0){let e=contentAttribute(t.response);e!==void 0&&i.setAttribute(`agent.approval.response`,e)}t.outcome===`failed`&&recordAgentSpanError(i,t.error),i.end()}}}function readState(e){if(typeof e!=`object`||!e||Array.isArray(e))return;let t=e,n=t.parent;if(typeof n!=`object`||!n||Array.isArray(n))return;let r=n;if(typeof t.actionCallId!=`string`||typeof t.actionName!=`string`||typeof t.attemptIndex!=`number`||typeof r.spanId!=`string`||typeof r.traceFlags!=`number`||typeof r.traceId!=`string`||typeof t.requestId!=`string`||typeof t.rootSessionId!=`string`||typeof t.sessionId!=`string`||typeof t.startTimeMs!=`number`||typeof t.stepIndex!=`number`||typeof t.turnId!=`string`)return;let i=t.requestAttribute;if(i===void 0||typeof i==`string`)return{actionCallId:t.actionCallId,actionName:t.actionName,attemptIndex:t.attemptIndex,channelAudience:normalizeChannelAudience(t.channelAudience),parent:{isRemote:!1,spanId:r.spanId,traceFlags:r.traceFlags,traceId:r.traceId},requestAttribute:i,requestId:t.requestId,rootSessionId:t.rootSessionId,traceSessionId:decodeTraceSessionId(t),sessionId:t.sessionId,startTimeMs:t.startTimeMs,stepIndex:t.stepIndex,turnId:t.turnId}}export{createAgentApprovalInstrumentation};

package/dist/src/tracing/agent-invocation-coordinator.d.ts

@@ -1,29 +1,20 @@
 import type { SessionTraceContext } from "#channel/types.js";
-import type { RuntimeSubagentResult } from "#shared/action-types.js";
-import type { SessionStateMap } from "#harness/types.js";
-import { type ChannelAudience } from "#shared/channel-audience.js";
+import type { ChannelAudience } from "#shared/channel-audience.js";
 import type { ConversationContext } from "#shared/conversation-context.js";
 export interface AgentChildTraceDispatch {
     readonly conversationId?: string;
     readonly originAudience: ChannelAudience;
     readonly parentTraceContext?: SessionTraceContext;
 }
-export declare function prepareAgentInvocationTrace(input: {
+/**
+ * The trace dispatch for sessions opened with `ctx.agent` while a run serves
+ * one workflow tool call: the call's tool span in the calling turn, read from
+ * the calling session when it admits the call.
+ */
+export declare function resolveToolCallAgentTrace(input: {
+    readonly callId: string;
     readonly conversation?: ConversationContext;
-    readonly invocation: {
-        readonly callId: string;
-        readonly kind: "remote-agent-call" | "subagent-call";
-        readonly name: string;
-    };
-    readonly ownerId: string;
     readonly serializedContext: Record<string, unknown>;
     readonly sessionId: string;
-    readonly sessionState?: SessionStateMap;
-    readonly startTimeMs: number;
-    readonly taskId?: string;
     readonly turnId: string;
-}): {
-    readonly dispatch: AgentChildTraceDispatch;
-    fail(result: RuntimeSubagentResult): Record<string, unknown>;
-    readonly serializedContext: Record<string, unknown>;
-};
+}): AgentChildTraceDispatch;

package/dist/src/tracing/agent-invocation-coordinator.js

@@ -1 +1 @@
-import"#shared/channel-audience.js";import{applyLiveDeliveryAudienceCeiling,readForwardedTraceAssertion}from"#shared/forwarded-trace-policy.js";import{ConversationIdKey}from"#context/keys.js";import{getBlockingWorkflowToolRuns}from"#harness/workflow-tool-runs.js";import{readActionTraceContext,readTaskActionTrace,readTurnTraceContext,recordActionInvocationKind,recordNestedAgentInvocation}from"#tracing/agent-trace-context-store.js";import{readConversationId}from"#shared/conversation-identity.js";import{invocationError,recordNestedAgentInvocationTerminal}from"#tracing/agent-invocation-terminal.js";import{deriveAgentActionSpanId}from"#tracing/agent-span-id-generator.js";function prepareAgentInvocationTrace(e){let t=readConversationId(e.serializedContext[ConversationIdKey.name]),n=e.taskId===void 0?void 0:readTaskActionTrace(e.serializedContext,e.sessionId,e.taskId),r=e.taskId===void 0?getBlockingWorkflowToolRuns(e.sessionState).find(t=>t.address.runId===e.ownerId)?.callId:n?.callId,i=n?.turnId??e.turnId,a=readTurnTraceContext(e.serializedContext,e.sessionId,i),o=e.conversation,s=o?.audience??`unknown`,c=o?.environment??`production`,l=(r===void 0?void 0:readActionTraceContext(e.serializedContext,e.sessionId,i,r))??a,u=l?.decision===void 0?void 0:applyLiveDeliveryAudienceCeiling(l.decision,s,l.forwardedTracePolicy,c),d=r===void 0?e.serializedContext:r===e.invocation.callId?recordActionInvocationKind({callId:e.invocation.callId,kind:e.invocation.kind,serializedContext:e.serializedContext,sessionId:e.sessionId,turnId:i}):recordNestedAgentInvocation({callId:e.invocation.callId,kind:e.invocation.kind,name:e.invocation.name,outerCallId:r,recordOutputs:u?.action===`record`&&u.recordOutputs,serializedContext:e.serializedContext,sessionId:e.sessionId,spanId:deriveAgentActionSpanId(e.sessionId,i,e.invocation.callId),startTimeMs:e.startTimeMs,turnId:i}),f=readActionTraceContext(d,e.sessionId,i,e.invocation.callId)??l,p=readForwardedTraceAssertion(f?.forwardedTracePolicy),m=f?.decision===void 0?f:{...f,decision:applyLiveDeliveryAudienceCeiling(f.decision,s,p,c)};return{dispatch:{conversationId:t,originAudience:p?.originAudience??s,parentTraceContext:m},fail:t=>recordNestedAgentInvocationTerminal({callId:e.invocation.callId,serializedContext:d,sessionId:e.sessionId,terminal:{acceptedAtMs:Date.now(),error:invocationError(t.output),outcome:`failed`},turnId:i}),serializedContext:d}}export{prepareAgentInvocationTrace};
+import{applyLiveDeliveryAudienceCeiling,readForwardedTraceAssertion}from"#shared/forwarded-trace-policy.js";import{ConversationIdKey}from"#context/keys.js";import{readConversationId}from"#shared/conversation-identity.js";import{readActionTraceContext,readTurnTraceContext}from"#tracing/agent-trace-context-store.js";function resolveToolCallAgentTrace(e){let{serializedContext:t,sessionId:n,turnId:r}=e;return toChildTraceDispatch({conversation:e.conversation,conversationId:readConversationId(t[ConversationIdKey.name]),stored:readActionTraceContext(t,n,r,e.callId)??readTurnTraceContext(t,n,r)})}function toChildTraceDispatch(e){let{stored:t}=e,n=e.conversation?.audience??`unknown`,r=e.conversation?.environment??`production`,i=readForwardedTraceAssertion(t?.forwardedTracePolicy),a=t?.decision===void 0?t:{...t,decision:applyLiveDeliveryAudienceCeiling(t.decision,n,i,r)};return{conversationId:e.conversationId,originAudience:i?.originAudience??n,parentTraceContext:a}}export{resolveToolCallAgentTrace};

package/dist/src/tracing/agent-memory-instrumentation.js

@@ -1 +1 @@
-import{normalizeChannelAudience}from"#shared/channel-audience.js";import{applyLiveDeliveryAudienceCeiling,resolveForwardedTraceSeed}from"#shared/forwarded-trace-policy.js";import{contextStorage}from"#context/container.js";import{SessionTraceSeedKey}from"#context/keys.js";import{isSampledTrace}from"#tracing/sampled-trace.js";import{ROOT_CONTEXT,SpanKind,context,trace}from"#compiled/@opentelemetry/api/index.js";import{isAgentTraceContext,markAgentTraceContext}from"#tracing/agent-trace-context.js";import{withErrorContent}from"#tracing/error-content-context.js";import{agentSpanNamingAttributes}from"#tracing/agent-span-naming.js";import{genAiMemoryRecordsAttribute}from"#tracing/agent-otel-content.js";import{recordAgentSpanError}from"#tracing/agent-span-error.js";import{agentTraceIdentityAttributes}from"#tracing/agent-otel-attributes.js";import{withChannelAudience}from"#tracing/channel-audience-context.js";import{suppressTracing}from"#tracing/suppress-tracing.js";function createAgentMemoryInstrumentation(e){let t=e.recordOutputs??!1,n=new Map,parentContext=async t=>{let n=context.active();if(isAgentTraceContext(n))return n;let r=await e.stateStore.getSession(t.sessionId);if(t.turnId!==void 0){let n=await e.stateStore.getTurn(t.sessionId,t.turnId);if(n!==void 0)return withChannelAudience(contextFromSpanContext(n.context),r?.channelAudience)}return r===void 0?void 0:withChannelAudience(contextFromSpanContext(r.context),r.channelAudience)},onStarted=async t=>{if(n.has(t.idempotencyKey))return;let r=await parentContext(t),i=r===void 0?void 0:trace.getSpan(r)?.spanContext();if(r===void 0||i===void 0||!isSampledTrace(i))return;let a=e.tracer.startSpan(t.operationName,{attributes:memorySpanAttributes(t),kind:SpanKind.CLIENT},r);n.set(t.idempotencyKey,{context:trace.setSpan(r,a),span:a})},onTerminal=e=>{let t=n.get(e.idempotencyKey);t!==void 0&&(n.delete(e.idempotencyKey),updateMemorySpan(t.span,e),t.span.end())};return{events:{"memory.operation.completed":onTerminal,"memory.operation.failed":onTerminal,"memory.operation.started":onStarted},async runInContext(r,i){let a=await e.stateStore.getSession(r.sessionId),o=n.get(r.idempotencyKey)?.context;if(o===void 0&&r.turnId!==void 0){let t=await e.stateStore.getTurn(r.sessionId,r.turnId);t!==void 0&&(o=withChannelAudience(contextFromSpanContext(t.context),a?.channelAudience),isSampledTrace(t.context)||(o=suppressTracing(o)))}o===void 0&&a!==void 0&&(o=withChannelAudience(contextFromSpanContext(a.context),a.channelAudience),isSampledTrace(a.context)||(o=suppressTracing(o)));let s=resolveForwardedTraceSeed(contextStorage.getStore()?.get(SessionTraceSeedKey)),c=s?.decision??a?.decision,l=c===void 0?void 0:applyLiveDeliveryAudienceCeiling(c,normalizeChannelAudience(a?.channelAudience),s?.forwardedTracePolicy,e.environment);return o===void 0?await i():await context.with(markAgentTraceContext(withErrorContent(o,t&&l?.action===`record`&&l.recordOutputs)),i)}}}function memorySpanAttributes(e){let t={"agent.memory.phase":e.phase,"agent.memory.slot":e.slot,"gen_ai.memory.store.id":e.storeId,"gen_ai.operation.name":e.operationName,...agentSpanNamingAttributes(e.operationName,e.operationName),...agentTraceIdentityAttributes({rootSessionId:e.rootSessionId,sessionId:e.sessionId})};return e.turnId!==void 0&&(t[`agent.turn.id`]=e.turnId),t}function updateMemorySpan(e,t){if(t.type===`memory.operation.failed`)recordAgentSpanError(e,t.error);else{t.recordCount!==void 0&&e.setAttribute(`gen_ai.memory.record.count`,t.recordCount);let n=genAiMemoryRecordsAttribute(t.outputRecords??[]);n!==void 0&&t.outputRecords!==void 0&&e.setAttribute(`gen_ai.memory.records`,n)}}function contextFromSpanContext(e){return trace.setSpan(ROOT_CONTEXT,trace.wrapSpanContext(e))}export{createAgentMemoryInstrumentation};
+import{normalizeChannelAudience}from"#shared/channel-audience.js";import{applyLiveDeliveryAudienceCeiling,resolveForwardedTraceSeed}from"#shared/forwarded-trace-policy.js";import{contextStorage}from"#context/container.js";import{SessionTraceSeedKey}from"#context/keys.js";import{withOperationConversation}from"#tracing/conversation-context.js";import{isSampledTrace}from"#tracing/sampled-trace.js";import{ROOT_CONTEXT,SpanKind,context,trace}from"#compiled/@opentelemetry/api/index.js";import{isAgentTraceContext,markAgentTraceContext}from"#tracing/agent-trace-context.js";import{withErrorContent}from"#tracing/error-content-context.js";import{agentSpanNamingAttributes}from"#tracing/agent-span-naming.js";import{genAiMemoryRecordsAttribute}from"#tracing/agent-otel-content.js";import{recordAgentSpanError}from"#tracing/agent-span-error.js";import{agentTraceIdentityAttributes,traceSessionIdOf}from"#tracing/agent-otel-attributes.js";import{withChannelAudience}from"#tracing/channel-audience-context.js";import{suppressTracing}from"#tracing/suppress-tracing.js";function createAgentMemoryInstrumentation(e){let t=e.recordOutputs??!1,n=new Map,parentContext=async t=>{let n=context.active();if(isAgentTraceContext(n))return n;let r=await e.stateStore.getSession(t.sessionId);if(t.turnId!==void 0){let n=await e.stateStore.getTurn(t.sessionId,t.turnId);if(n!==void 0)return withChannelAudience(contextFromSpanContext(n.context),r?.channelAudience)}return r===void 0?void 0:withChannelAudience(contextFromSpanContext(r.context),r.channelAudience)},onStarted=async t=>{if(n.has(t.idempotencyKey))return;let r=await parentContext(t),i=r===void 0?void 0:trace.getSpan(r)?.spanContext();if(r===void 0||i===void 0||!isSampledTrace(i))return;let a=e.tracer.startSpan(t.operationName,{attributes:memorySpanAttributes(t),kind:SpanKind.CLIENT},r);n.set(t.idempotencyKey,{context:trace.setSpan(r,a),span:a})},onTerminal=e=>{let t=n.get(e.idempotencyKey);t!==void 0&&(n.delete(e.idempotencyKey),updateMemorySpan(t.span,e),t.span.end())};return{events:{"memory.operation.completed":onTerminal,"memory.operation.failed":onTerminal,"memory.operation.started":onStarted},async runInContext(r,i){let a=await e.stateStore.getSession(r.sessionId),o=n.get(r.idempotencyKey)?.context;if(o===void 0&&r.turnId!==void 0){let t=await e.stateStore.getTurn(r.sessionId,r.turnId);t!==void 0&&(o=withChannelAudience(contextFromSpanContext(t.context),a?.channelAudience),isSampledTrace(t.context)||(o=suppressTracing(o)))}o===void 0&&a!==void 0&&(o=withChannelAudience(contextFromSpanContext(a.context),a.channelAudience),isSampledTrace(a.context)||(o=suppressTracing(o)));let s=resolveForwardedTraceSeed(contextStorage.getStore()?.get(SessionTraceSeedKey)),c=s?.decision??a?.decision,l=c===void 0?void 0:applyLiveDeliveryAudienceCeiling(c,normalizeChannelAudience(a?.channelAudience),s?.forwardedTracePolicy,e.environment);return o===void 0?await i():await context.with(markAgentTraceContext(withErrorContent(withOperationConversation(o,{rootSessionId:a?.rootSessionId,sessionId:r.sessionId}),t&&l?.action===`record`&&l.recordOutputs)),i)}}}function memorySpanAttributes(e){let t={"agent.memory.phase":e.phase,"agent.memory.slot":e.slot,"gen_ai.memory.store.id":e.storeId,"gen_ai.operation.name":e.operationName,...agentSpanNamingAttributes(e.operationName,e.operationName),...agentTraceIdentityAttributes({rootSessionId:e.rootSessionId,traceSessionId:traceSessionIdOf(e),sessionId:e.sessionId})};return e.turnId!==void 0&&(t[`agent.turn.id`]=e.turnId),t}function updateMemorySpan(e,t){if(t.type===`memory.operation.failed`)recordAgentSpanError(e,t.error);else{t.recordCount!==void 0&&e.setAttribute(`gen_ai.memory.record.count`,t.recordCount);let n=genAiMemoryRecordsAttribute(t.outputRecords??[]);n!==void 0&&t.outputRecords!==void 0&&e.setAttribute(`gen_ai.memory.records`,n)}}function contextFromSpanContext(e){return trace.setSpan(ROOT_CONTEXT,trace.wrapSpanContext(e))}export{createAgentMemoryInstrumentation};

package/dist/src/tracing/agent-otel-attributes.d.ts

@@ -1,4 +1,10 @@
+export declare function traceSessionIdOf(scope: {
+    readonly traceSessionId?: string;
+    readonly rootSessionId?: string;
+    readonly sessionId: string;
+}): string;
 export declare function agentTraceIdentityAttributes(input: {
     readonly rootSessionId: string;
     readonly sessionId: string;
+    readonly traceSessionId: string;
 }): Record<string, string | number>;

package/dist/src/tracing/agent-otel-attributes.js

@@ -1 +1 @@
-import{AGENT_TRACE_SCHEMA_VERSION}from"#tracing/agent-span-contract.js";import{resolveConversationId}from"#shared/conversation-identity.js";function agentTraceIdentityAttributes(e){let t=resolveConversationId(e.rootSessionId),n={"agent.run.id":e.sessionId,"agent.trace.schema.version":AGENT_TRACE_SCHEMA_VERSION,"gen_ai.conversation.id":t};return process.env.VERCEL_ENV!==void 0&&(n[`vercel.session_id`]=e.rootSessionId),n}export{agentTraceIdentityAttributes};
+import{AGENT_TRACE_SCHEMA_VERSION}from"#tracing/agent-span-contract.js";import{operationConversationId}from"#tracing/conversation-context.js";function traceSessionIdOf(e){return e.traceSessionId??e.rootSessionId??e.sessionId}function agentTraceIdentityAttributes(e){let t=operationConversationId(e),n={"agent.run.id":e.sessionId,"agent.trace.schema.version":AGENT_TRACE_SCHEMA_VERSION,"gen_ai.conversation.id":t};return process.env.VERCEL_ENV!==void 0&&(n[`vercel.session_id`]=e.traceSessionId),n}export{agentTraceIdentityAttributes,traceSessionIdOf};

package/dist/src/tracing/agent-otel-content.d.ts

@@ -24,7 +24,5 @@ export declare function genAiMemoryRecordsAttribute(records: readonly unknown[])
  * instead of cutting the JSON mid-string.
  */
 export declare function toolResultsContentAttribute(results: readonly Record<string, unknown>[]): string | undefined;
-/** Normalizes the AI SDK's `instructions` prompt to plain text for `ai.prompt.system`. */
-export declare function systemPromptAttribute(instructions: unknown): string | undefined;
 /** Caps plain text, marking the cut. */
 export declare function textContentAttribute(text: string): string | undefined;