Something went wrong. Try again.
A local-first event pipeline for independent agents, built on Jazz.
Something went wrong. Try again.
54 kB · 1424 lines
TypeScript
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425import { CloudManagedSandboxExpiredError, LettaAgentClient, type LettaCodeClientSessionOptions, type LettaCodeSession, type LettaConversation, type ListMessagesResult, type MessageContentItem, type SDKMessage, type SDKResultMessage, type SendMessage,} from "@letta-ai/letta-agent-sdk";import { createHash } from "node:crypto";import { stableKey } from "../core/ids.js";import type { JsonObject } from "../core/json.js";import { resolveImageArtifact } from "../connectors/telegram-images.js";import type { InferenceUsage } from "../store/types.js";import type { LettaConversationBinding } from "../store/types.js";import { createOutputContractRegistry, outputContractForDeclaration, outputContractIdentityJson, OutputContractValidationError, PUBLIC_KNOWLEDGE_PROPOSED_DIFF_OUTPUT_CONTRACT_ID, PUBLIC_KNOWLEDGE_RECOMMENDATION_OUTPUT_CONTRACT_ID, type PublicKnowledgeProposedDiffOutput, type PublicKnowledgeRecommendationOutput, type ObservationOutput, type OutputContractRegistry,} from "./output-contracts.js";import { AgentRunFailure, type AgentOutput, type AgentRunInput, type AgentRunner, type RunnerTrace, type ThoughtAgentDeclaration,} from "./types.js";import { validatePublicKnowledgeProposedDiffAgainstContext, validatePublicKnowledgeRecommendationAgainstContext,} from "../public-knowledge/context.js";import { PUBLIC_KNOWLEDGE_PROPOSAL_TOOL_NAME, PublicKnowledgeProposalToolCapture, type PublicKnowledgeProposalToolSnapshot,} from "../public-knowledge/proposal-tool.js";
export const LETTA_AGENT_SDK_ADAPTER_REVISION = "letta-agent-sdk-conversations-v5";export const LETTA_AGENT_SDK_PACKAGE_VERSION = "0.5.7";
const MAX_FINAL_JSON_CHARS = 64_000;const MAX_CONVERSATION_TEXT_CHARS = 2_000;const HISTORY_PAGE_SIZE = 100;const MAX_HISTORY_PAGES = 10;const DEFAULT_RECONCILIATION_DELAY_MS = 1_500;const LETTA_CLOUD_API_BASE_URL = "https://api.letta.com";const RUN_USAGE_TIMEOUT_MS = 3_000;const MAX_USAGE_RUN_IDS = 20;const RUN_ID_PATTERN = /^run-[A-Za-z0-9-]{1,200}$/;
export interface LettaAgentSdkClient { createSession?(id: string, options?: LettaCodeClientSessionOptions): LettaCodeSession; resumeSession(id: string, options?: LettaCodeClientSessionOptions): LettaCodeSession; conversations?: { list(options?: { agentId?: string; limit?: number; summarySearch?: string }): Promise<LettaConversation[]>; create(options: { agentId: string; summary?: string; description?: string; model?: string; hidden?: boolean; }): Promise<LettaConversation>; retrieve(conversationId: string): Promise<LettaConversation>; };}
export interface LettaConversationBindingStore { getLettaConversationBinding(id: string): Promise<LettaConversationBinding | undefined>; upsertLettaConversationBinding(binding: LettaConversationBinding): Promise<LettaConversationBinding>;}
export interface LettaRunUsageClient { retrieve(runId: string): Promise<InferenceUsage | undefined>;}
export interface LettaAgentSdkRunnerOptions { client?: LettaAgentSdkClient; apiKey?: string | undefined; environment?: NodeJS.ProcessEnv; historyPages?: number; reconciliationDelayMs?: number; sleep?: (milliseconds: number) => Promise<void>; outputContracts?: OutputContractRegistry; runUsageClient?: LettaRunUsageClient; fetch?: typeof fetch; conversationStore?: LettaConversationBindingStore | undefined; artifactRoot?: string | undefined;}
interface HistoryToolCall { id: string; name: string; input: unknown;}
interface HistoryToolResult { id: string; isError: boolean;}
interface HistoryToolActivity { calls: HistoryToolCall[]; results: HistoryToolResult[];}
type HistoryReconciliation = | { status: "missing" } | { status: "pending" } | { status: "inconclusive" } | { status: "completed"; text: string; tools: HistoryToolActivity };
class LettaAgentSdkTimeoutError extends Error { constructor() { super("Letta Agent SDK turn timed out"); this.name = "LettaAgentSdkTimeoutError"; }}
export class LettaAgentSdkRunner implements AgentRunner { readonly mode = "letta-agent-sdk" as const; private readonly outputContracts: OutputContractRegistry; private readonly historyPages: number; private readonly reconciliationDelayMs: number; private readonly sleep: (milliseconds: number) => Promise<void>; private readonly clients = new Map<"cloud" | "local", LettaAgentSdkClient>(); private runUsageClient: LettaRunUsageClient | undefined; private runUsageClientResolved = false;
constructor(private readonly options: LettaAgentSdkRunnerOptions = {}) { this.outputContracts = options.outputContracts ?? createOutputContractRegistry(); this.historyPages = options.historyPages ?? MAX_HISTORY_PAGES; this.reconciliationDelayMs = options.reconciliationDelayMs ?? DEFAULT_RECONCILIATION_DELAY_MS; this.sleep = options.sleep ?? ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds))); if (!Number.isSafeInteger(this.historyPages) || this.historyPages < 1 || this.historyPages > MAX_HISTORY_PAGES) { throw new Error(`historyPages must be an integer from 1 through ${MAX_HISTORY_PAGES}`); } if (!Number.isSafeInteger(this.reconciliationDelayMs) || this.reconciliationDelayMs < 0 || this.reconciliationDelayMs > 30_000) { throw new Error("reconciliationDelayMs must be an integer from 0 through 30000"); } if (options.client) { this.clients.set("cloud", options.client); this.clients.set("local", options.client); } this.runUsageClient = options.runUsageClient; }
async run(input: AgentRunInput, onTrace: (trace: RunnerTrace) => Promise<void>): Promise<AgentOutput> { const declaration = input.declaration; const config = declaration.lettaAgent; if (!config || !["cloud", "local"].includes(config.backend) || !config.agentId) { throw new AgentRunFailure("Letta Agent SDK declaration is not runnable", { advanceProgress: false, diagnostic: { code: "letta-sdk-config-invalid", stage: "sdk-setup", backend: config?.backend ?? "missing", agentConfigured: Boolean(config?.agentId), }, }); }
const client = this.resolveClient(declaration); const turnKey = lettaTurnKey(declaration, input.event.id); const proposalCapture = config.proposalTool === "public-knowledge-diff" ? new PublicKnowledgeProposalToolCapture(input.context) : undefined; const options = sessionOptions( declaration, this.options.environment ?? process.env, proposalCapture, ); const conversation = await this.resolveConversation(client, input); const session = client.resumeSession(conversation.sessionId, options); let sent = false; let acceptTraces = true; const emitTrace = async (trace: RunnerTrace): Promise<void> => { if (acceptTraces) await onTrace(trace); }; try { return await this.withTimeout(session, declaration.timeoutMs, async () => { await emitTrace({ kind: "letta.session.opened", data: { backend: config.backend, executionAdapterRevision: LETTA_AGENT_SDK_ADAPTER_REVISION, sdkVersion: LETTA_AGENT_SDK_PACKAGE_VERSION, agentId: config.agentId!, conversation: config.conversation, outputOnly: config.outputOnly, proposalTool: config.proposalTool ?? "none", ...(conversation.bindingId ? { bindingId: conversation.bindingId } : {}), }, });
let reconciliation = await reconcileHistory(session, turnKey, this.historyPages); if (reconciliation.status === "inconclusive") throw inconclusiveHistoryFailure(session, turnKey); if (reconciliation.status === "completed") { await emitTrace({ kind: "letta.turn.recovered", data: { turnKey, conversationId: session.conversationId ?? "", text: textMetadata(reconciliation.text), }, }); return this.outputFromReconciliation(input, reconciliation, proposalCapture); } if (reconciliation.status === "pending") { reconciliation = await this.delayedReconciliation(session, turnKey); if (reconciliation.status === "completed") { await emitTrace({ kind: "letta.turn.recovered", data: { turnKey, conversationId: session.conversationId ?? "", text: textMetadata(reconciliation.text), }, }); return this.outputFromReconciliation(input, reconciliation, proposalCapture); } if (reconciliation.status === "inconclusive") throw inconclusiveHistoryFailure(session, turnKey); throw pendingTurnFailure(session, turnKey); }
if ((input.attempt ?? 1) > 1) { reconciliation = await this.delayedReconciliation(session, turnKey); if (reconciliation.status === "completed") { await emitTrace({ kind: "letta.turn.recovered", data: { turnKey, conversationId: session.conversationId ?? "", text: textMetadata(reconciliation.text), }, }); return this.outputFromReconciliation(input, reconciliation, proposalCapture); } if (reconciliation.status === "inconclusive") throw inconclusiveHistoryFailure(session, turnKey); if (reconciliation.status === "pending") throw pendingTurnFailure(session, turnKey); }
const messageText = buildLettaTurnMessage(input, turnKey, this.outputContracts); const message = await buildLettaSendMessage(input, messageText, this.options.artifactRoot, emitTrace); await emitTrace({ kind: "letta.prompt", data: { ...textMetadata(messageText), imageCount: input.context.imageArtifacts?.length ?? 0, }, }); await session.send(message); sent = true; await emitTrace({ kind: "letta.turn.sent", data: { turnKey, agentId: session.agentId ?? config.agentId!, conversationId: session.conversationId ?? "", }, });
let result: SDKResultMessage | undefined; const traces = new SdkTraceAccumulator(); try { for await (const messageEvent of session.stream()) { traces.add(messageEvent); if (messageEvent.type === "result") { result = messageEvent; break; } } } finally { await traces.flush(emitTrace); } if (!result) { throw new AgentRunFailure("Letta Agent SDK stream ended without a terminal result", { advanceProgress: false, diagnostic: { code: "letta-sdk-stream-closed", stage: "sdk-stream", turnKey, sent: true, }, }); } const usage = await this.reportedUsage(result, emitTrace, declaration); if (config.outputOnly && !proposalCapture && traces.hasToolActivity()) { throw invalidSdkOutput("unexpected-tool-activity", result.result ?? "", declaration, undefined, usage); } if (!result.success) throw terminalSdkFailure(result, turnKey, usage); let output: AgentOutput; try { if (proposalCapture) { output = this.outputFromProposalCapture(input, proposalCapture, traces.proposalToolActivity()); } else { if (typeof result.result !== "string" || result.result.trim().length === 0) { throw invalidSdkOutput("empty-final-text", result.result ?? "", declaration); } output = this.parseOutput(input, result.result); } } catch (error) { if (error instanceof AgentRunFailure && usage) { throw new AgentRunFailure(error.message, { advanceProgress: error.advanceProgress, ...(error.diagnostic ? { diagnostic: error.diagnostic } : {}), usage, }); } throw error; } return { ...output, ...(usage ? { usage } : {}), }; }, () => { acceptTraces = false; }); } catch (error) { if (error instanceof AgentRunFailure) throw error; if (error instanceof LettaAgentSdkTimeoutError) { throw new AgentRunFailure("Letta Agent SDK turn timed out", { advanceProgress: false, diagnostic: { code: "letta-sdk-timeout", stage: sent ? "sdk-stream" : "sdk-setup", turnKey, sent, }, }); } if (error instanceof CloudManagedSandboxExpiredError) { throw new AgentRunFailure("Letta Cloud managed sandbox expired before the turn", { advanceProgress: false, diagnostic: { code: "letta-cloud-sandbox-expired", stage: "sdk-setup", turnKey, sent: false, }, }); } throw new AgentRunFailure(sent ? "Letta Agent SDK turn entered ambiguous recovery" : "Letta Agent SDK session could not start", { advanceProgress: false, diagnostic: { code: sent ? "letta-sdk-turn-ambiguous" : "letta-sdk-session-unavailable", stage: sent ? "sdk-stream" : "sdk-setup", turnKey, sent, errorClass: safeErrorClass(error), }, }); } finally { acceptTraces = false; session.close(); } }
private async resolveConversation( client: LettaAgentSdkClient, input: AgentRunInput, ): Promise<{ sessionId: string; bindingId?: string }> { const config = input.declaration.lettaAgent!; if (config.conversation === "main") return { sessionId: config.agentId! }; const store = this.options.conversationStore; if (!store || !client.conversations) { throw new AgentRunFailure("Per-document Letta conversation storage is unavailable", { advanceProgress: false, diagnostic: { code: "letta-conversation-store-missing", stage: "sdk-setup" }, }); } const documentId = requiredEventString(input.event, "documentId"); const currentPath = requiredEventString(input.event, "path"); const bindingId = lettaDocumentConversationBindingId(input.declaration, input.event); const remoteMarker = lettaDocumentConversationRemoteMarker(bindingId); const existing = await store.getLettaConversationBinding(bindingId); if (existing) { const remote = await client.conversations.retrieve(existing.conversationId); if (remote.id !== existing.conversationId || remote.agent_id !== existing.agentId || remote.summary !== existing.remoteMarker || existing.remoteMarker !== remoteMarker) { throw new AgentRunFailure("Per-document Letta conversation binding no longer matches remote state", { advanceProgress: false, diagnostic: { code: "letta-conversation-binding-drift", stage: "sdk-setup", bindingId }, }); } await store.upsertLettaConversationBinding({ ...existing, declarationVersion: input.declaration.version, currentPath, updatedAt: new Date().toISOString(), }); return { sessionId: existing.conversationId, bindingId }; }
const matches = (await client.conversations.list({ agentId: config.agentId!, summarySearch: remoteMarker, limit: 10, })).filter((conversation) => ( conversation.summary === remoteMarker && conversation.agent_id === config.agentId )); if (matches.length > 1) { throw new AgentRunFailure("Per-document Letta conversation marker is ambiguous", { advanceProgress: false, diagnostic: { code: "letta-conversation-marker-ambiguous", stage: "sdk-setup", bindingId, matchCount: matches.length, }, }); } const conversation = matches[0] ?? await client.conversations.create({ agentId: config.agentId!, summary: remoteMarker, description: "thought stream private file-scoped Public Knowledge recommendation conversation.", ...(input.declaration.model ? { model: input.declaration.model } : {}), hidden: true, }); if (!conversation.id || conversation.agent_id !== config.agentId) { throw new AgentRunFailure("Per-document Letta conversation identity is invalid", { advanceProgress: false, diagnostic: { code: "letta-conversation-identity-invalid", stage: "sdk-setup", bindingId }, }); } const now = new Date().toISOString(); await store.upsertLettaConversationBinding({ id: bindingId, declarationId: input.declaration.id, declarationVersion: input.declaration.version, agentId: config.agentId!, source: input.event.source, scopeType: "document", scopeKey: documentId, conversationId: conversation.id, remoteMarker, currentPath, createdAt: now, updatedAt: now, }); return { sessionId: conversation.id, bindingId }; }
private resolveClient(declaration: ThoughtAgentDeclaration): LettaAgentSdkClient { const backend = declaration.lettaAgent!.backend; const cached = this.clients.get(backend); if (cached) return cached; const environment = this.options.environment ?? process.env; if (backend === "local") { const client = new LettaAgentClient({ backend: "local", appServer: { harnessBackend: "api" } }); this.clients.set("local", client); return client; } const apiKey = this.options.apiKey ?? environment.LETTA_API_KEY; if (!apiKey) { throw new AgentRunFailure("Letta Cloud API credential is unavailable", { advanceProgress: false, diagnostic: { code: "letta-cloud-credential-missing", stage: "sdk-setup" }, }); } const client = new LettaAgentClient({ backend: "cloud", apiKey }); this.clients.set("cloud", client); return client; }
private async reportedUsage( result: SDKResultMessage, emitTrace: (trace: RunnerTrace) => Promise<void>, declaration: ThoughtAgentDeclaration, ): Promise<InferenceUsage | undefined> { const usage: InferenceUsage = {}; const costMicrousd = usdToMicrousd(result.totalCostUsd); if (costMicrousd !== undefined) usage.costMicrousd = costMicrousd;
const sdkRunIds = [...new Set(result.runIds ?? [])]; const validRunIds = sdkRunIds.filter((runId) => RUN_ID_PATTERN.test(runId)); const runSetComplete = validRunIds.length === sdkRunIds.length && validRunIds.length <= MAX_USAGE_RUN_IDS; const client = declaration.lettaAgent?.backend === "cloud" ? this.resolveRunUsageClient() : undefined; let retrievedRunCount = 0; if (client && runSetComplete && validRunIds.length > 0) { const results = await Promise.all(validRunIds.map(async (runId) => { try { return await client.retrieve(runId); } catch { return undefined; } })); retrievedRunCount = results.filter((value): value is InferenceUsage => value !== undefined).length; if (retrievedRunCount === validRunIds.length) { const inputTokens = sumReportedDimension(results, "inputTokens"); const outputTokens = sumReportedDimension(results, "outputTokens"); if (inputTokens !== undefined) usage.inputTokens = inputTokens; if (outputTokens !== undefined) usage.outputTokens = outputTokens; } }
const tokenUsageReported = usage.inputTokens !== undefined || usage.outputTokens !== undefined; await emitTrace({ kind: "letta.usage", data: { sdkRunCount: sdkRunIds.length, validRunCount: validRunIds.length, runSetComplete, retrievedRunCount, inputTokensReported: usage.inputTokens !== undefined, outputTokensReported: usage.outputTokens !== undefined, costReported: usage.costMicrousd !== undefined, source: tokenUsageReported ? "run-usage-api" : retrievedRunCount > 0 ? "run-usage-api-partial" : costMicrousd !== undefined ? "sdk-result" : "unavailable", }, }); return Object.keys(usage).length > 0 ? usage : undefined; }
private resolveRunUsageClient(): LettaRunUsageClient | undefined { if (this.runUsageClientResolved) return this.runUsageClient; this.runUsageClientResolved = true; if (this.runUsageClient) return this.runUsageClient; const environment = this.options.environment ?? process.env; const apiKey = this.options.apiKey ?? environment.LETTA_API_KEY; if (!apiKey) return undefined; this.runUsageClient = new LettaCloudRunUsageClient(apiKey, this.options.fetch ?? fetch); return this.runUsageClient; }
private outputFromReconciliation( input: AgentRunInput, reconciliation: Extract<HistoryReconciliation, { status: "completed" }>, proposalCapture: PublicKnowledgeProposalToolCapture | undefined, ): AgentOutput { if (!proposalCapture) return this.parseOutput(input, reconciliation.text); const call = reconciliation.tools.calls[0]; if (reconciliation.tools.calls.length === 1 && call?.name === PUBLIC_KNOWLEDGE_PROPOSAL_TOOL_NAME) { proposalCapture.recover(call.input); } return this.outputFromProposalCapture(input, proposalCapture, reconciliation.tools); }
private outputFromProposalCapture( input: AgentRunInput, proposalCapture: PublicKnowledgeProposalToolCapture, activity: HistoryToolActivity, ): AgentOutput { const snapshot = proposalCapture.snapshot(); const call = activity.calls[0]; const result = activity.results[0]; if (snapshot.failure) { throw invalidProposalToolOutput(snapshot.failure, input.declaration, snapshot, activity); } if (activity.calls.length !== 1 || call?.name !== PUBLIC_KNOWLEDGE_PROPOSAL_TOOL_NAME) { throw invalidProposalToolOutput( activity.calls.length === 0 ? "missing-tool-call" : "unexpected-tool-call", input.declaration, snapshot, activity, ); } if (activity.results.length !== 1 || result?.id !== call.id || result.isError) { throw invalidProposalToolOutput( activity.results.length === 0 ? "missing-tool-result" : "invalid-tool-result", input.declaration, snapshot, activity, ); } if (snapshot.calls !== 1 || snapshot.failure || !snapshot.accepted) { throw invalidProposalToolOutput( snapshot.failure ?? (snapshot.calls === 0 ? "callback-not-invoked" : "proposal-not-captured"), input.declaration, snapshot, activity, ); } return this.withModelIdentity(input.declaration, snapshot.accepted); }
private withModelIdentity(declaration: ThoughtAgentDeclaration, output: AgentOutput): AgentOutput { const config = declaration.lettaAgent!; return { ...output, model: { provider: declaration.provider ?? `letta-${config.backend}`, id: declaration.model ?? "agent-default", revision: `${LETTA_AGENT_SDK_PACKAGE_VERSION}/${LETTA_AGENT_SDK_ADAPTER_REVISION}`, }, }; }
private async delayedReconciliation(session: LettaCodeSession, turnKey: string): Promise<HistoryReconciliation> { if (this.reconciliationDelayMs > 0) await this.sleep(this.reconciliationDelayMs); return reconcileHistory(session, turnKey, this.historyPages); }
private parseOutput(input: AgentRunInput, text: string): AgentOutput { const declaration = input.declaration; const identity = outputContractForDeclaration(declaration); const config = declaration.lettaAgent!; let parsed: AgentOutput; if (responseModeForInput(input) === "conversation-text") { const summary = text.trim(); if (!summary) throw invalidSdkOutput("empty-final-text", text, declaration); if (summary.length > MAX_CONVERSATION_TEXT_CHARS) { throw invalidSdkOutput("final-text-too-large", text, declaration); } try { parsed = this.outputContracts.validate(identity, { summary, tags: ["conversation"], importance: "normal", confidence: 0.5, }); } catch (error) { if (!(error instanceof OutputContractValidationError)) throw error; throw invalidSdkOutput("output-contract-invalid", text, declaration, error); } } else { if (text.length > MAX_FINAL_JSON_CHARS) throw invalidSdkOutput("final-text-too-large", text, declaration); let value: unknown; try { value = JSON.parse(text); } catch { throw invalidSdkOutput("invalid-json", text, declaration); } try { parsed = this.outputContracts.validate(identity, value); } catch (error) { if (!(error instanceof OutputContractValidationError)) throw error; throw invalidSdkOutput("output-contract-invalid", text, declaration, error); } if (identity.id === PUBLIC_KNOWLEDGE_RECOMMENDATION_OUTPUT_CONTRACT_ID) { try { validatePublicKnowledgeRecommendationAgainstContext( parsed as PublicKnowledgeRecommendationOutput, input.context, ); } catch { throw invalidSdkOutput("context-bound-output-invalid", text, declaration); } } if (identity.id === PUBLIC_KNOWLEDGE_PROPOSED_DIFF_OUTPUT_CONTRACT_ID) { try { validatePublicKnowledgeProposedDiffAgainstContext( parsed as PublicKnowledgeProposedDiffOutput, input.context, ); } catch { throw invalidSdkOutput("context-bound-output-invalid", text, declaration); } } } return this.withModelIdentity(declaration, parsed); }
private async withTimeout<T>( session: LettaCodeSession, timeoutMs: number, operation: () => Promise<T>, onTimeout: () => void, ): Promise<T> { let timer: NodeJS.Timeout | undefined; const timeout = new Promise<never>((_resolve, reject) => { timer = setTimeout(() => { onTimeout(); void session.abort().catch(() => {}); session.close(); reject(new LettaAgentSdkTimeoutError()); }, timeoutMs); }); try { return await Promise.race([operation(), timeout]); } finally { if (timer) clearTimeout(timer); } }}
export function lettaTurnKey(declaration: ThoughtAgentDeclaration, eventId: string): string { return stableKey("letta-agent-sdk-turn", declaration.id, String(declaration.version), eventId);}
export function lettaDocumentConversationBindingId( declaration: ThoughtAgentDeclaration, event: AgentRunInput["event"],): string { const agentId = declaration.lettaAgent?.agentId; if (!agentId) throw new Error("Document conversation binding requires a resolved agent id"); return stableKey( "letta-conversation", declaration.id, agentId, event.source, requiredEventString(event, "documentId"), );}
export function lettaDocumentConversationRemoteMarker(bindingId: string): string { return `thoughtstream:coil:${createHash("sha256").update(bindingId).digest("hex")}`;}
export function buildLettaTurnMessage( input: AgentRunInput, turnKey: string, contracts: OutputContractRegistry = createOutputContractRegistry(),): string { const config = input.declaration.lettaAgent; if (!config) throw new Error("Letta Agent SDK configuration is missing"); const finalInstruction = config.proposalTool === "public-knowledge-diff" ? `Call ${PUBLIC_KNOWLEDGE_PROPOSAL_TOOL_NAME} exactly once. Set raw to one JSON-encoded object satisfying the complete proposed-diff contract. Do not call any other tool. After the tool accepts the proposal, return only PROPOSAL_CAPTURED.` : responseModeForInput(input) === "conversation-text" ? input.event.type === "stream.thought.source.telegram.message" ? "Return only your reply to Cameron." : input.event.type === "stream.thought.derived.event.batch" ? "Return only one concise private internal ATProto batch observation. This is not a reply to Cameron." : "Return only a concise private internal observation." : contracts.resolve(outputContractForDeclaration(input.declaration)).prompt; return [ `<thoughtstream-turn key="${turnKey}" input-event-id="${input.event.id}" authority="trusted-runtime-metadata" />`, "<thoughtstream-task-instructions authority=\"trusted\">", input.declaration.systemPrompt, "</thoughtstream-task-instructions>", ...(input.context.systemText ? [ "<thoughtstream-subscribed-context authority=\"trusted\">", input.context.systemText, "</thoughtstream-subscribed-context>", ] : []), input.context.text, "<thoughtstream-final-response authority=\"trusted\">", finalInstruction, "</thoughtstream-final-response>", ].join("\n");}
async function buildLettaSendMessage( input: AgentRunInput, text: string, artifactRoot: string | undefined, onTrace: (trace: RunnerTrace) => Promise<void>,): Promise<SendMessage> { const artifacts = input.context.imageArtifacts ?? []; if (artifacts.length === 0) return text; if (input.event.type !== "stream.thought.source.telegram.message" || artifacts.length !== 1) { throw unauthorizedImageArtifactFailure(); } if (!artifactRoot) throw invalidImageArtifactFailure();
const content: MessageContentItem[] = [{ type: "text", text }]; for (const artifact of artifacts) { try { const image = await resolveImageArtifact(artifact, artifactRoot); content.push({ type: "image", source: { type: "base64", media_type: image.mimeType, data: image.data, }, }); await onTrace({ kind: "letta.image_resolved", data: { sha256: artifact.sha256, mimeType: artifact.mimeType, sizeBytes: artifact.sizeBytes, }, }); } catch (error) { await onTrace({ kind: "letta.image_resolution_failed", data: { sha256: artifact.sha256, code: "image-artifact-invalid" }, }); throw invalidImageArtifactFailure(error); } } return content;}
function invalidImageArtifactFailure(cause?: unknown): AgentRunFailure { return new AgentRunFailure("Current-turn image artifact could not be validated", { ...(cause ? { cause } : {}), advanceProgress: false, diagnostic: { code: "letta-sdk-image-invalid", stage: "trusted-evidence-resolution", }, });}
function unauthorizedImageArtifactFailure(): AgentRunFailure { return new AgentRunFailure("Image content is outside this SDK turn's authority", { advanceProgress: false, diagnostic: { code: "letta-sdk-image-not-authorized", stage: "effect-boundary", }, });}
function responseModeForInput(input: AgentRunInput): "strict-json" | "conversation-text" { const config = input.declaration.lettaAgent; if (!config) throw new Error("Letta Agent SDK configuration is missing"); return input.event.type === "stream.thought.derived.event.batch" && config.batchResponseMode ? config.batchResponseMode : config.responseMode;}
export async function reconcileHistory( session: LettaCodeSession, turnKey: string, maxPages = MAX_HISTORY_PAGES,): Promise<HistoryReconciliation> { const history = await loadBoundedHistory(session, maxPages); const reconciliation = findTurnInHistory(history.messages, turnKey); return reconciliation.status === "missing" && !history.complete ? { status: "inconclusive" } : reconciliation;}
export function findTurnInHistory(messagesNewestFirst: unknown[], turnKey: string): HistoryReconciliation { const chronological = [...messagesNewestFirst].reverse(); let markerIndex = -1; for (let index = chronological.length - 1; index >= 0; index -= 1) { const message = chronological[index]; if (historyRole(message) === "user" && historyText(message).includes(turnKey)) { markerIndex = index; break; } } if (markerIndex < 0) return { status: "missing" }; const assistant: string[] = []; const tools: HistoryToolActivity = { calls: [], results: [] }; for (let index = markerIndex + 1; index < chronological.length; index += 1) { const message = chronological[index]; const role = historyRole(message); if (role === "user") break; if (role === "assistant") { const text = historyText(message); if (text) assistant.push(text); } tools.calls.push(...historyToolCalls(message)); tools.results.push(...historyToolResults(message)); } const text = assistant.join("").trim(); return text ? { status: "completed", text, tools } : { status: "pending" };}
async function loadBoundedHistory( session: LettaCodeSession, maxPages: number,): Promise<{ messages: unknown[]; complete: boolean }> { const messages: unknown[] = []; const seen = new Set<string>(); let before: string | undefined; let complete = false; for (let page = 0; page < maxPages; page += 1) { const result: ListMessagesResult = await session.listMessages({ order: "desc", limit: HISTORY_PAGE_SIZE, ...(before ? { before } : {}), }); for (const message of result.messages) { const id = historyMessageId(message); if (id && seen.has(id)) continue; if (id) seen.add(id); messages.push(message); } if (result.hasMore !== true) { complete = true; break; } if (!result.nextBefore || result.messages.length === 0) { throw new AgentRunFailure("Letta Cloud history pagination was internally inconsistent", { advanceProgress: false, diagnostic: { code: "letta-sdk-history-pagination-invalid", stage: "history-reconciliation", hasMore: true, cursorPresent: Boolean(result.nextBefore), pageMessageCount: result.messages.length, }, }); } before = result.nextBefore; } return { messages, complete };}
class RedactedTextAccumulator { private readonly hash = createHash("sha256"); private chars = 0; private parts = 0;
add(value: string): void { this.hash.update(value); this.chars += value.length; this.parts += 1; }
metadata(): JsonObject { return { chars: this.chars, parts: this.parts, sha256: this.hash.digest("hex"), redacted: true }; }
get empty(): boolean { return this.parts === 0; }}
class SdkTraceAccumulator { private readonly assistant = new RedactedTextAccumulator(); private readonly reasoning = new RedactedTextAccumulator(); private readonly toolCalls = new Map<string, JsonObject>(); private readonly toolResults = new Map<string, { metadata: RedactedTextAccumulator; isError: boolean; runId: string }>(); private readonly streamEventTypes = new Map<string, number>(); private readonly errors: JsonObject[] = []; private retries = 0; private maximumQueueLength = 0; private latestLoopStatus = ""; private init: JsonObject | undefined; private result: SDKResultMessage | undefined;
hasToolActivity(): boolean { return this.toolCalls.size > 0 || this.toolResults.size > 0; }
proposalToolActivity(): HistoryToolActivity { return { calls: [...this.toolCalls.values()].map((call) => ({ id: String(call.toolCallId ?? ""), name: String(call.toolName ?? ""), input: undefined, })), results: [...this.toolResults].map(([id, result]) => ({ id, isError: result.isError })), }; }
add(message: SDKMessage): void { switch (message.type) { case "assistant": this.assistant.add(message.content); return; case "reasoning": this.reasoning.add(message.content); return; case "tool_call": { const key = message.toolCallId || message.uuid; const prior = this.toolCalls.get(key); const keys = new Set<string>(Array.isArray(prior?.inputKeys) ? prior.inputKeys.map(String) : []); for (const inputKey of Object.keys(message.toolInput)) keys.add(inputKey); this.toolCalls.set(key, { toolCallId: message.toolCallId, toolName: message.toolName, inputKeys: [...keys].sort().slice(0, 100), argumentsRedacted: true, runId: message.runId ?? "", }); return; } case "tool_result": { const current = this.toolResults.get(message.toolCallId) ?? { metadata: new RedactedTextAccumulator(), isError: false, runId: message.runId ?? "", }; current.metadata.add(message.content); current.isError ||= message.isError; this.toolResults.set(message.toolCallId, current); return; } case "result": this.result = message; return; case "error": if (this.errors.length < 20) { this.errors.push({ errorCode: safeToken(message.errorCode), stopReason: safeToken(message.stopReason), approvalConflict: message.approvalConflict ?? false, recoverable: message.recoverable ?? false, runId: message.runId ?? "", detailRedacted: true, }); } return; case "retry": this.retries += 1; return; case "queue_update": this.maximumQueueLength = Math.max(this.maximumQueueLength, message.queue.length); return; case "loop_status": this.latestLoopStatus = safeToken(message.status); return; case "init": this.init = { agentId: message.agentId, sessionId: message.sessionId, conversationId: message.conversationId, model: message.model, toolCount: message.tools?.length ?? 0, memfsEnabled: message.memfsEnabled ?? false, }; return; case "stream_event": { const event = asRecord(message.event); const type = safeToken(event?.type ?? event?.message_type) || "unknown"; this.streamEventTypes.set(type, (this.streamEventTypes.get(type) ?? 0) + 1); return; } } }
async flush(onTrace: (trace: RunnerTrace) => Promise<void>): Promise<void> { if (this.init) await onTrace({ kind: "letta.init", data: this.init }); if (!this.reasoning.empty) await onTrace({ kind: "letta.reasoning", data: this.reasoning.metadata() }); if (!this.assistant.empty) await onTrace({ kind: "letta.assistant", data: this.assistant.metadata() }); for (const call of this.toolCalls.values()) await onTrace({ kind: "letta.tool_call", data: call }); for (const [toolCallId, result] of this.toolResults) { await onTrace({ kind: "letta.tool_result", data: { toolCallId, isError: result.isError, runId: result.runId, content: result.metadata.metadata() }, }); } if (this.streamEventTypes.size > 0) { await onTrace({ kind: "letta.stream_events", data: { counts: Object.fromEntries([...this.streamEventTypes].sort(([left], [right]) => left.localeCompare(right))) }, }); } if (this.errors.length > 0) await onTrace({ kind: "letta.errors", data: { count: this.errors.length, items: this.errors } }); if (this.retries > 0 || this.maximumQueueLength > 0 || this.latestLoopStatus) { await onTrace({ kind: "letta.runtime", data: { retries: this.retries, maximumQueueLength: this.maximumQueueLength, latestLoopStatus: this.latestLoopStatus, }, }); } if (this.result) await onTrace({ kind: "letta.result", data: resultMetadata(this.result) }); }}
function sessionOptions( declaration: ThoughtAgentDeclaration, environment: NodeJS.ProcessEnv, proposalCapture?: PublicKnowledgeProposalToolCapture,): LettaCodeClientSessionOptions { const config = declaration.lettaAgent!; if (Boolean(config.proposalTool) !== Boolean(proposalCapture)) { throw new AgentRunFailure("Letta Agent SDK proposal tool profile is inconsistent", { advanceProgress: false, diagnostic: { code: "letta-proposal-tool-config-invalid", stage: "sdk-setup" }, }); } if (config.backend === "local") { if (!config.outputOnly) { throw new AgentRunFailure("Local Agent SDK session is not explicitly output-only", { advanceProgress: false, diagnostic: { code: "letta-local-output-only-required", stage: "sdk-setup" }, }); } const memoryDir = config.memoryDirEnv ? environment[config.memoryDirEnv]?.trim() : undefined; if (!memoryDir || !memoryDir.startsWith("/")) { throw new AgentRunFailure("Local Agent SDK memory root is unavailable", { advanceProgress: false, diagnostic: { code: "letta-local-memory-root-missing", stage: "sdk-setup" }, }); } return { permissionMode: "strict", skillSources: [], allowedTools: proposalCapture ? [PUBLIC_KNOWLEDGE_PROPOSAL_TOOL_NAME] : [], ...(proposalCapture ? { tools: [proposalCapture.tool] } : {}), ...(proposalCapture ? { canUseTool: async (toolName) => toolName === PUBLIC_KNOWLEDGE_PROPOSAL_TOOL_NAME ? { behavior: "allow" as const } : { behavior: "deny" as const, message: "Tool is outside the proposal-only session", interrupt: false }, } : {}), dreaming: { trigger: "off" }, cwd: memoryDir, env: { MEMORY_DIR: memoryDir }, filesystemConfinement: "memory", ...(declaration.model ? { model: declaration.model } : {}), ...(config.reasoningEffort ? { reasoningEffort: config.reasoningEffort } : {}), }; } return { permissionMode: config.permissionMode, ...(config.skillSources ? { skillSources: config.skillSources } : {}), dreaming: { trigger: config.dreaming.trigger, ...(config.dreaming.stepCount ? { stepCount: config.dreaming.stepCount } : {}), }, sandbox: config.sandbox, ...(declaration.model ? { model: declaration.model } : {}), ...(config.reasoningEffort ? { reasoningEffort: config.reasoningEffort } : {}), };}
function requiredEventString(event: AgentRunInput["event"], field: string): string { const value = event.payload[field]; if (typeof value !== "string" || !value) { throw new AgentRunFailure(`Per-document Letta event ${field} is invalid`, { advanceProgress: true, diagnostic: { code: "letta-document-scope-invalid", stage: "sdk-setup", field }, }); } return value;}
function pendingTurnFailure(session: LettaCodeSession, turnKey: string): AgentRunFailure { return new AgentRunFailure("Letta Cloud turn exists without a terminal assistant result", { advanceProgress: false, diagnostic: { code: "letta-sdk-turn-pending", stage: "history-reconciliation", turnKey, conversationId: session.conversationId ?? "", }, });}
function inconclusiveHistoryFailure(session: LettaCodeSession, turnKey: string): AgentRunFailure { return new AgentRunFailure("Letta Cloud turn marker was outside the bounded history window", { advanceProgress: false, diagnostic: { code: "letta-sdk-history-inconclusive", stage: "history-reconciliation", turnKey, conversationId: session.conversationId ?? "", }, });}
function terminalSdkFailure( result: SDKResultMessage, turnKey: string, usage?: InferenceUsage,): AgentRunFailure { const failureClass = classifySdkFailure(result); return new AgentRunFailure("Letta Agent SDK turn failed", { advanceProgress: false, diagnostic: { code: failureClass.code, stage: failureClass.stage, turnKey, errorCode: safeToken(result.errorCode), stopReason: safeToken(result.stopReason), approvalConflict: result.approvalConflict ?? false, recoverable: result.recoverable ?? false, recoveryAttempts: result.recoveryAttempts ?? 0, runIds: result.runIds?.slice(0, 20) ?? [], durationMs: nonnegativeInteger(result.durationMs) ?? 0, detailRedacted: true, }, ...(usage ? { usage } : {}), });}
function classifySdkFailure(result: SDKResultMessage): { code: string; stage: string } { const detail = [result.error, result.errorDetail, result.errorCode, result.stopReason] .filter((value): value is string => typeof value === "string") .join(" ") .toLowerCase(); if (detail.includes("insufficient credits") || detail.includes("minimum $1 in credits")) { return { code: "letta-cloud-insufficient-credits", stage: "provider-billing" }; } if (detail.includes("rate limit") || detail.includes("too many requests")) { return { code: "letta-cloud-rate-limited", stage: "provider-request" }; } if (detail.includes("unauthorized") || detail.includes("forbidden") || detail.includes("authentication")) { return { code: "letta-cloud-authorization-failed", stage: "provider-authorization" }; } return { code: "letta-sdk-turn-failed", stage: "sdk-result" };}
function invalidProposalToolOutput( reason: string, declaration: ThoughtAgentDeclaration, snapshot: PublicKnowledgeProposalToolSnapshot, activity: HistoryToolActivity,): AgentRunFailure { return new AgentRunFailure("Letta Agent SDK proposal tool output rejected", { diagnostic: { code: "invalid-proposal-tool-output", stage: "proposal-tool-validation", reason, callbackCalls: snapshot.calls, captured: Boolean(snapshot.accepted), toolCallCount: activity.calls.length, toolResultCount: activity.results.length, toolNames: activity.calls.map((call) => safeToken(call.name)).filter(Boolean).slice(0, 20), errorResultCount: activity.results.filter((result) => result.isError).length, outputContract: outputContractIdentityJson(outputContractForDeclaration(declaration)), ...(snapshot.validationIssues.length > 0 ? { validationIssues: snapshot.validationIssues.map((issue) => ({ code: issue.code, path: issue.path })), } : {}), }, });}
function invalidSdkOutput( reason: string, text: string, declaration: ThoughtAgentDeclaration, contractError?: OutputContractValidationError, usage?: InferenceUsage,): AgentRunFailure { return new AgentRunFailure("Letta Agent SDK final output rejected", { diagnostic: { code: "invalid-final-output", stage: "final-output-validation", reason, text: textMetadata(text), outputContract: outputContractIdentityJson(outputContractForDeclaration(declaration)), ...(contractError ? { validationIssues: contractError.issues.map((issue) => ({ code: issue.code, path: issue.path })), } : {}), }, ...(usage ? { usage } : {}), });}
class LettaCloudRunUsageClient implements LettaRunUsageClient { constructor( private readonly apiKey: string, private readonly fetchImpl: typeof fetch, ) {}
async retrieve(runId: string): Promise<InferenceUsage | undefined> { if (!RUN_ID_PATTERN.test(runId)) return undefined; const controller = new AbortController(); const timer = setTimeout(() => controller.abort(), RUN_USAGE_TIMEOUT_MS); try { const response = await this.fetchImpl(`${LETTA_CLOUD_API_BASE_URL}/v1/runs/${encodeURIComponent(runId)}/usage`, { method: "GET", headers: { Accept: "application/json", Authorization: `Bearer ${this.apiKey}` }, signal: controller.signal, }); if (!response.ok) return undefined; const body = asRecord(await response.json()); if (!body) return undefined; const inputTokens = nonnegativeInteger(body.prompt_tokens); const outputTokens = nonnegativeInteger(body.completion_tokens); return inputTokens === undefined && outputTokens === undefined ? undefined : { ...(inputTokens !== undefined ? { inputTokens } : {}), ...(outputTokens !== undefined ? { outputTokens } : {}), }; } catch { return undefined; } finally { clearTimeout(timer); } }}
function sumReportedDimension( values: Array<InferenceUsage | undefined>, key: "inputTokens" | "outputTokens",): number | undefined { let total = 0; for (const value of values) { const amount = value?.[key]; if (amount === undefined) return undefined; total += amount; if (!Number.isSafeInteger(total)) return undefined; } return total;}
function resultMetadata(result: SDKResultMessage): JsonObject { const costMicrousd = usdToMicrousd(result.totalCostUsd); const failureClass = result.success ? undefined : classifySdkFailure(result); return { success: result.success, ...(result.result ? { result: textMetadata(result.result) } : {}), errorCode: safeToken(result.errorCode), stopReason: safeToken(result.stopReason), approvalConflict: result.approvalConflict ?? false, recoverable: result.recoverable ?? false, recoveryAttempts: result.recoveryAttempts ?? 0, durationMs: nonnegativeInteger(result.durationMs) ?? 0, ...(costMicrousd !== undefined ? { costMicrousd } : {}), conversationId: result.conversationId ?? "", runIds: result.runIds?.slice(0, 20) ?? [], ...(failureClass ? { failureCode: failureClass.code, failureStage: failureClass.stage } : {}), detailRedacted: true, };}
function historyRole(value: unknown): "user" | "assistant" | "other" { const record = asRecord(value); const role = String(record?.role ?? "").toLowerCase(); const type = String(record?.message_type ?? record?.messageType ?? record?.type ?? "").toLowerCase(); if (role === "user" || type === "user_message" || type === "user") return "user"; if (role === "assistant" || type === "assistant_message" || type === "assistant") return "assistant"; return "other";}
function historyText(value: unknown): string { const record = asRecord(value); if (!record) return ""; for (const key of ["content", "message", "text", "assistant_message", "user_message"]) { const text = extractText(record[key]); if (text) return text; } return "";}
function extractText(value: unknown, depth = 0): string { if (depth > 5) return ""; if (typeof value === "string") return value; if (Array.isArray(value)) return value.map((item) => extractText(item, depth + 1)).join(""); const record = asRecord(value); if (!record) return ""; for (const key of ["text", "content", "message", "value"]) { const text = extractText(record[key], depth + 1); if (text) return text; } return "";}
function historyToolCalls(value: unknown): HistoryToolCall[] { const record = asRecord(value); if (!record) return []; const type = String(record.message_type ?? record.messageType ?? record.type ?? "").toLowerCase(); if (type !== "tool_call_message" && !record.tool_call && !record.tool_calls) return []; const candidates = Array.isArray(record.tool_calls) ? record.tool_calls : record.tool_call ? [record.tool_call] : record.tool_calls ? [record.tool_calls] : []; return candidates.flatMap((candidate) => { const call = asRecord(candidate); const id = call?.tool_call_id ?? call?.toolCallId ?? call?.id; const name = call?.name ?? call?.toolName; if (typeof id !== "string" || !id || typeof name !== "string" || !name) return []; let input: unknown = call?.input ?? call?.toolInput; if (input === undefined && typeof call?.arguments === "string") { try { input = JSON.parse(call.arguments); } catch { input = undefined; } } return [{ id, name, input }]; });}
function historyToolResults(value: unknown): HistoryToolResult[] { const record = asRecord(value); if (!record) return []; const type = String(record.message_type ?? record.messageType ?? record.type ?? "").toLowerCase(); if (type !== "tool_return_message" && !record.tool_return && !record.tool_returns) return []; const candidates = Array.isArray(record.tool_returns) && record.tool_returns.length > 0 ? record.tool_returns : [record]; return candidates.flatMap((candidate) => { const result = asRecord(candidate); const id = result?.tool_call_id ?? result?.toolCallId; if (typeof id !== "string" || !id) return []; const status = String(result?.status ?? "").toLowerCase(); return [{ id, isError: status === "error" || result?.is_err === true || record.is_err === true }]; });}
function historyMessageId(value: unknown): string | undefined { const record = asRecord(value); const id = record?.id ?? record?.uuid ?? record?.message_id; return typeof id === "string" && id ? id : undefined;}
function textMetadata(value: string): JsonObject { return { chars: value.length, sha256: createHash("sha256").update(value).digest("hex"), redacted: true, };}
function safeErrorClass(error: unknown): string { if (!(error instanceof Error)) return "non-error"; return /^[A-Za-z][A-Za-z0-9_.-]{0,99}$/.test(error.name) ? error.name : "Error";}
function safeToken(value: unknown): string { return typeof value === "string" && /^[A-Za-z0-9_.:-]{1,100}$/.test(value) ? value : "";}
function usdToMicrousd(value: number | undefined): number | undefined { if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) return undefined; const converted = Math.round(value * 1_000_000); return Number.isSafeInteger(converted) ? converted : undefined;}
function nonnegativeInteger(value: unknown): number | undefined { return Number.isSafeInteger(value) && Number(value) >= 0 ? Number(value) : undefined;}
function asRecord(value: unknown): Record<string, unknown> | undefined { return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;}