// ---------------------------------------------------------------------------// ToolResult — typed value-based discriminated union returned by tool// handlers and `invokeTool`. Domain success and expected failure both// resolve through Effect's success channel; only true infra defects use// the Effect failure channel.// --------------------------------------------------------------------------- import { Effect, Schema } from "effect"; export const ToolErrorSchema = Schema.Struct({  code: Schema.String,  message: Schema.String,  status: Schema.optional(Schema.Number),  details: Schema.optional(Schema.Unknown),  retryable: Schema.optional(Schema.Boolean),}); export type ToolError = typeof ToolErrorSchema.Type; export const ToolHttpMetaSchema = Schema.Struct({  status: Schema.Number,  headers: Schema.Record(Schema.String, Schema.String),}); /** * Transport metadata for HTTP-backed tools (OpenAPI). Kept beside `data` * rather than wrapped around it: `data` stays the upstream payload, while * cross-cutting transport facts (pagination Link headers, rate-limit * headers) remain reachable for callers that need them. */export type ToolHttpMeta = typeof ToolHttpMetaSchema.Type; export const ToolFileSchema = Schema.TaggedStruct("ToolFile", {  name: Schema.optional(Schema.String),  mimeType: Schema.String,  encoding: Schema.Literal("base64"),  data: Schema.String.annotate({    description: "Base64-encoded file bytes.",    contentEncoding: "base64",  }),  byteLength: Schema.Int.annotate({    description: "Raw file size in bytes before base64 encoding.",  }),}); export type ToolFile = typeof ToolFileSchema.Type; export const ToolFileJsonSchema = Schema.toJsonSchemaDocument(ToolFileSchema).schema; const matchesToolFileSchema = Schema.is(ToolFileSchema); export const isToolFile = (value: unknown): value is ToolFile => matchesToolFileSchema(value); export type ToolResult<T> =  | { readonly ok: true; readonly data: T; readonly http?: ToolHttpMeta }  | { readonly ok: false; readonly error: ToolError }; export const ToolResult = {  ok: <T>(data: T, meta?: { readonly http?: ToolHttpMeta }): ToolResult<T> => ({    ok: true,    data,    ...(meta?.http ? { http: meta.http } : {}),  }),  fail: <T = never>(error: ToolError): ToolResult<T> => ({ ok: false, error }),} as const; const ToolResultSchema = Schema.Union([  Schema.Struct({    ok: Schema.Literal(true),    data: Schema.Unknown,    http: Schema.optional(ToolHttpMetaSchema),  }),  Schema.Struct({ ok: Schema.Literal(false), error: ToolErrorSchema }),]); const isUnknownToolResult = Schema.is(ToolResultSchema); export const isToolResult = (value: unknown): value is ToolResult<unknown> =>  isUnknownToolResult(value); /** * Annotate the current span with the outcome of a tool invocation. * * `ToolResult.fail` rides the Effect *success* channel by design (expected * failures are values, not defects), which means the tracer records those * spans as healthy. Without this, "user keeps hitting 4xx walls" is invisible * to telemetry — the exact class of signal that lets us catch product issues * before they're reported. Stamped attributes: * *   - `executor.tool.outcome`      — "ok" | "fail" (always, on ToolResults) *   - `executor.tool.error_code`   — ToolError.code (fail only) *   - `executor.tool.error_status` — upstream HTTP status (fail, when present) * * Codes/statuses are enumerable identifiers, never user content — safe span * attributes. Non-ToolResult values (raw success payloads) annotate "ok". */export const annotateToolResultOutcome = (value: unknown): Effect.Effect<void> => {  if (isToolResult(value) && !value.ok) {    return Effect.annotateCurrentSpan({      "executor.tool.outcome": "fail",      "executor.tool.error_code": value.error.code,      ...(value.error.status != null ? { "executor.tool.error_status": value.error.status } : {}),    });  }  return Effect.annotateCurrentSpan({ "executor.tool.outcome": "ok" });};