@meistrari/chat-nuxt 1.4.0 → 1.5.0

package/dist/runtime/server/utils/conversation-agent-turn.js

@@ -0,0 +1,170 @@
+import { and, eq, isNull } from "drizzle-orm";
+import { useRuntimeConfig } from "nitropack/runtime";
+import { schema } from "#chat-runtime/server/db";
+import { buildMessageWithContext, renderSystemPrompt, truncateTitle } from "#chat-runtime/server/utils/chat-message-builder";
+import {
+  getConversationAppliedSettings,
+  getWorkspaceSettingsUpdatedAt,
+  parseWorkspaceSettingsSnapshot,
+  resolveWorkspaceSettings,
+  serializeResolvedWorkspaceSettings
+} from "#chat-runtime/server/utils/chat-workspace-settings";
+import { logger } from "#chat-runtime/server/utils/logger";
+import { getTelaAgent, runTelaAgent } from "#chat-runtime/server/utils/tela-agent-api";
+import { toTelaAgentAttachments, toTelaAgentInputSchema } from "#chat-runtime/server/utils/tela-agent-session";
+import { resolveWorkspaceCredentials } from "#chat-runtime/server/utils/workspace";
+import { resolveChatNuxtFeatures } from "#chat-runtime/utils/features";
+import { mergeFileUrls } from "#chat-runtime/utils/file";
+import { isValidModel } from "#chat-runtime/types/chat";
+function getFileVaultRef(file) {
+  return file.vaultReference?.trim() || (file.url.startsWith("vault://") ? file.url : null);
+}
+function filterMappedFiles(files, inputSchema) {
+  const mappedVaultRefs = new Set(
+    inputSchema.filter((input) => input.type === "file").map((input) => input.vaultRef)
+  );
+  if (mappedVaultRefs.size === 0)
+    return files ?? [];
+  return (files ?? []).filter((file) => {
+    const vaultRef = getFileVaultRef(file);
+    return !vaultRef || !mappedVaultRefs.has(vaultRef);
+  });
+}
+export async function buildTelaAgentTurnPayload(event, conversation, content, files, agentInputs) {
+  let inputSchema = agentInputs ?? [];
+  let attachmentFiles = filterMappedFiles(files, inputSchema);
+  if (inputSchema.length === 0 && conversation.telaAgentId && files?.length) {
+    const agentResult = await getTelaAgent(event, conversation.telaAgentId);
+    if (agentResult.success) {
+      const fileInputCount = agentResult.data.inputSchema.filter((input) => input.type === "file" && input.name.trim()).length;
+      inputSchema = toTelaAgentInputSchema(files, agentResult.data.inputSchema);
+      if (inputSchema.length > 0) {
+        attachmentFiles = [];
+      } else if (fileInputCount > 1) {
+        logger.warn({
+          agentId: conversation.telaAgentId,
+          fileInputCount
+        }, "Tela agent file input auto-mapping skipped");
+      }
+    } else {
+      logger.warn({ agentId: conversation.telaAgentId, error: agentResult.error }, "Tela agent metadata fetch failed");
+    }
+  }
+  const attachments = toTelaAgentAttachments(attachmentFiles);
+  return {
+    message: content.trim(),
+    ...conversation.threadSessionId ? { sessionId: conversation.threadSessionId } : {},
+    ...inputSchema.length > 0 ? { inputSchema } : {},
+    ...attachments.length > 0 ? { attachments } : {}
+  };
+}
+export function queueTelaAgentTurn(event, db, options) {
+  const needsNewThread = options.conversation.threadSessionId === null;
+  const logContext = {
+    conversationId: options.conversationId,
+    messageId: options.assistantMessageId
+  };
+  const telaAgentId = options.conversation.telaAgentId;
+  if (!telaAgentId) {
+    logger.error(logContext, "Tela agent turn queued without agent id");
+    void db.update(schema.messages).set({
+      content: "Erro: Agente Tela n\xE3o configurado",
+      status: "failed"
+    }).where(eq(schema.messages.id, options.assistantMessageId));
+    return;
+  }
+  runTelaAgent(event, telaAgentId, options.payload).then(async (result) => {
+    if (result.success) {
+      await db.update(schema.conversations).set({
+        ...needsNewThread ? { title: truncateTitle(options.titleContent) } : {},
+        threadSessionId: result.sessionId,
+        model: null,
+        appliedSettingsAt: null,
+        appliedSettingsSnapshot: null,
+        updatedAt: /* @__PURE__ */ new Date()
+      }).where(eq(schema.conversations.id, options.conversationId));
+    } else {
+      logger.warn({ ...logContext, error: result.error }, options.operation === "retry" ? "Tela agent retry failed" : "Tela agent run failed");
+      await db.update(schema.messages).set({
+        content: `Erro: ${result.error}`,
+        status: "failed"
+      }).where(eq(schema.messages.id, options.assistantMessageId));
+    }
+  }).catch(async (error) => {
+    logger.error({ ...logContext, error: error.message }, options.operation === "retry" ? "Tela agent retry threw exception" : "Tela agent run threw exception");
+    await db.update(schema.messages).set({
+      content: "Erro: Falha ao conectar ao agente",
+      status: "failed"
+    }).where(eq(schema.messages.id, options.assistantMessageId));
+  });
+}
+export async function prepareDefaultAgentTurn(event, db, context, options) {
+  const explicitSettings = !options.conversation.appliedSettingsSnapshot && options.workspaceSettingsSnapshot !== void 0 ? parseWorkspaceSettingsSnapshot(options.workspaceSettingsSnapshot) : void 0;
+  const trustedSettings = options.conversation.appliedSettingsSnapshot || explicitSettings ? null : await resolveWorkspaceSettings(event, context, db);
+  const appliedSettings = getConversationAppliedSettings(options.conversation, trustedSettings, explicitSettings);
+  const settingsTimestamp = getWorkspaceSettingsUpdatedAt(appliedSettings);
+  const snapshotSettings = explicitSettings ?? trustedSettings;
+  if (!options.conversation.appliedSettingsSnapshot && snapshotSettings) {
+    await db.update(schema.conversations).set({
+      appliedSettingsAt: getWorkspaceSettingsUpdatedAt(snapshotSettings),
+      appliedSettingsSnapshot: serializeResolvedWorkspaceSettings(snapshotSettings),
+      updatedAt: /* @__PURE__ */ new Date()
+    }).where(and(
+      eq(schema.conversations.id, options.conversationId),
+      isNull(schema.conversations.appliedSettingsSnapshot)
+    ));
+  }
+  const needsNewThread = options.conversation.threadSessionId === null;
+  const effectiveModel = options.requestedModel ?? (isValidModel(options.conversation.model) ? options.conversation.model : void 0);
+  const content = options.content.trim();
+  const knowledgeSources = appliedSettings.knowledgeSources ?? null;
+  const hasKnowledgeSources = knowledgeSources !== null && knowledgeSources.length > 0;
+  const externalSkillRefs = appliedSettings.externalSkills?.map((skill) => skill.ref) ?? [];
+  const skills = externalSkillRefs.length > 0 ? externalSkillRefs : void 0;
+  const fileUrls = mergeFileUrls(appliedSettings.contextFiles, options.files);
+  const { vaultUrl } = useRuntimeConfig();
+  const messageWithContext = buildMessageWithContext(
+    content,
+    appliedSettings.systemMessage ?? null,
+    knowledgeSources,
+    needsNewThread,
+    needsNewThread ? renderSystemPrompt(vaultUrl) : ""
+  );
+  return {
+    needsNewThread,
+    effectiveModel,
+    settingsTimestamp,
+    messageTitle: truncateTitle(options.content),
+    createPayload: {
+      message: messageWithContext,
+      fileUrls,
+      model: effectiveModel,
+      customTools: appliedSettings.canvasTools?.length ? { canvas: appliedSettings.canvasTools } : void 0,
+      tools: hasKnowledgeSources ? { workstationQueryTool: true } : void 0,
+      skills
+    },
+    continuePayload: {
+      content,
+      fileUrls,
+      model: effectiveModel
+    }
+  };
+}
+export async function resolveDefaultAgentEnvironmentVariables(event, context, logContext, failureMessage) {
+  if (!resolveChatNuxtFeatures(useRuntimeConfig()).credentials)
+    return {};
+  try {
+    return await resolveWorkspaceCredentials(event, context.workspaceId);
+  } catch (error) {
+    logger.warn({ ...logContext, error }, failureMessage);
+    return {};
+  }
+}
+export function withEnvironmentVariables(payload, environmentVariables) {
+  if (Object.keys(environmentVariables).length === 0)
+    return payload;
+  return {
+    ...payload,
+    environmentVariables
+  };
+}

package/dist/runtime/server/utils/conversation-message-files.d.ts

@@ -0,0 +1,10 @@
+import type { useDb } from '#chat-runtime/server/db';
+import type { MessageFile } from '#chat-runtime/types/chat';
+type DbInstance = ReturnType<typeof useDb>;
+type MessageUpdateWithFiles = {
+    content?: string;
+    status?: string;
+    files?: MessageFile[];
+};
+export declare function attachNewAssistantFilesToMessageUpdate(db: DbInstance, conversationId: string, updateData: MessageUpdateWithFiles, authToken: string): Promise<void>;
+export {};

package/dist/runtime/server/utils/conversation-message-files.js

@@ -0,0 +1,77 @@
+import { and, eq, isNotNull } from "drizzle-orm";
+import { useRuntimeConfig } from "nitropack/runtime";
+import { APIKeyAuthStrategy, VaultFile } from "@meistrari/vault-sdk";
+import { schema } from "#chat-runtime/server/db";
+import { logger } from "#chat-runtime/server/utils/logger";
+import { detectFilesInText } from "#chat-runtime/utils/file";
+async function getExistingMessageFileUrls(db, conversationId) {
+  const messagesWithFiles = await db.select({ files: schema.messages.files }).from(schema.messages).where(and(
+    eq(schema.messages.conversationId, conversationId),
+    isNotNull(schema.messages.files)
+  ));
+  const urls = /* @__PURE__ */ new Set();
+  for (const message of messagesWithFiles) {
+    if (Array.isArray(message.files)) {
+      for (const file of message.files) {
+        if (file?.url) {
+          urls.add(file.url);
+        }
+      }
+    }
+  }
+  return urls;
+}
+async function extractAssistantFiles(content, authToken) {
+  const detected = detectFilesInText(content);
+  const vaultFiles = detected.filter((file) => file.type === "vault");
+  if (vaultFiles.length === 0)
+    return [];
+  const { vaultUrl } = useRuntimeConfig();
+  return Promise.all(
+    vaultFiles.map(async (file) => {
+      let name = file.name;
+      let mimeType = file.mimeType !== "unknown" ? file.mimeType : void 0;
+      let size;
+      if (vaultUrl) {
+        try {
+          const authStrategy = new APIKeyAuthStrategy(authToken);
+          const vaultFile = await VaultFile.fromVaultReference({
+            reference: file.reference,
+            config: { authStrategy, vaultUrl }
+          });
+          await vaultFile.populateMetadata();
+          if (vaultFile.metadata?.originalFileName) {
+            name = vaultFile.metadata.originalFileName;
+          }
+          if (vaultFile.metadata?.mimeType) {
+            mimeType = vaultFile.metadata.mimeType;
+          }
+          if (vaultFile.metadata?.size) {
+            size = vaultFile.metadata.size;
+          }
+        } catch {
+          logger.debug({ reference: file.reference }, "Vault metadata fetch failed for assistant file");
+        }
+      }
+      return {
+        url: file.reference,
+        name,
+        mimeType,
+        source: "assistant",
+        size
+      };
+    })
+  );
+}
+export async function attachNewAssistantFilesToMessageUpdate(db, conversationId, updateData, authToken) {
+  if (!updateData.content || updateData.status !== "completed")
+    return;
+  const assistantFiles = await extractAssistantFiles(updateData.content, authToken);
+  if (assistantFiles.length === 0)
+    return;
+  const existingUrls = await getExistingMessageFileUrls(db, conversationId);
+  const newFiles = assistantFiles.filter((file) => !existingUrls.has(file.url));
+  if (newFiles.length > 0) {
+    updateData.files = newFiles;
+  }
+}

package/dist/runtime/server/utils/conversation-message-sync.d.ts

@@ -0,0 +1,31 @@
+import type { useDb } from '#chat-runtime/server/db';
+import type { AgentApiSession, MessageStatus, ReasoningItem } from '#chat-runtime/types/agent';
+import type { ChatRuntimeContext } from '#chat-runtime/server/utils/chat-context';
+import type { Message, MessageFile } from '#chat-runtime/types/chat';
+import type { TelaAgentUsageValues } from '#chat-runtime/server/utils/tela-agent-session';
+type DbInstance = ReturnType<typeof useDb>;
+export type MessageUpdate = {
+    reasoningData?: ReasoningItem[];
+    externalUuid?: string;
+    content?: string;
+    status?: MessageStatus;
+    ttft?: string;
+    updatedAt?: Date;
+    files?: MessageFile[];
+};
+type MessageUpdateResponse = {
+    messages: Message[];
+    newFiles?: MessageFile[];
+};
+export declare function mapAgentApiSessionToMessageUpdate(agentSession: AgentApiSession, options: {
+    pendingMessage: Pick<Message, 'ttft' | 'createdAt'>;
+    lastAssistantMessage?: Pick<Message, 'externalUuid'> | null;
+    userMessage?: Pick<Message, 'createdAt'> | null;
+    now?: Date;
+}): MessageUpdate;
+export declare function hasMessageUpdate(updateData: MessageUpdate): boolean;
+export declare function isTerminalMessageUpdate(updateData: MessageUpdate): boolean;
+export declare function buildMessageUpdateResponse(messages: Message[], messageId: string, updateData: MessageUpdate): MessageUpdateResponse;
+export declare function trackTelaAgentConversationUsage(db: DbInstance, context: ChatRuntimeContext, conversationId: string, sessionId: string, usage: TelaAgentUsageValues | null): void;
+export declare function trackAgentApiConversationUsage(db: DbInstance, context: ChatRuntimeContext, conversationId: string, sessionId: string, agentSession: AgentApiSession): void;
+export {};

package/dist/runtime/server/utils/conversation-message-sync.js

@@ -0,0 +1,132 @@
+import { schema } from "#chat-runtime/server/db";
+import { extractContentFromSession } from "#chat-runtime/server/utils/agent-api";
+import { logger } from "#chat-runtime/server/utils/logger";
+function toMilliseconds(timestamp) {
+  if (typeof timestamp !== "number" || !Number.isFinite(timestamp))
+    return null;
+  return timestamp < 1e10 ? timestamp * 1e3 : timestamp;
+}
+export function mapAgentApiSessionToMessageUpdate(agentSession, options) {
+  const updateData = {};
+  const lastSyncedUuid = options.lastAssistantMessage?.externalUuid;
+  const lastSyncedIndex = lastSyncedUuid ? agentSession.reasoning?.findIndex((item) => item.uuid === lastSyncedUuid) ?? -1 : -1;
+  const newReasoning = agentSession.reasoning?.slice(lastSyncedIndex + 1);
+  const hasNewReasoning = newReasoning && newReasoning.length > 0;
+  const sessionUpdatedAtMs = toMilliseconds(agentSession.updatedAt);
+  const terminalSessionBelongsToPendingMessage = hasNewReasoning || !options.lastAssistantMessage || sessionUpdatedAtMs !== null && sessionUpdatedAtMs >= options.pendingMessage.createdAt.getTime();
+  if (hasNewReasoning) {
+    updateData.reasoningData = newReasoning;
+    const lastReasoningItem = newReasoning.at(-1);
+    if (lastReasoningItem?.uuid) {
+      updateData.externalUuid = lastReasoningItem.uuid;
+    }
+    if (!options.pendingMessage.ttft && options.userMessage) {
+      const now = options.now ?? /* @__PURE__ */ new Date();
+      updateData.ttft = String(now.getTime() - options.userMessage.createdAt.getTime());
+    }
+  }
+  if (agentSession.status === "completed" || agentSession.status === "waiting_messages") {
+    if (terminalSessionBelongsToPendingMessage) {
+      updateData.content = extractContentFromSession(agentSession);
+      updateData.status = "completed";
+      updateData.updatedAt = options.now ?? /* @__PURE__ */ new Date();
+    }
+  } else if (agentSession.status === "failed") {
+    const errorContent = agentSession.error || "Agent execution failed";
+    updateData.content = `Error: ${errorContent}`;
+    updateData.status = "failed";
+    updateData.updatedAt = options.now ?? /* @__PURE__ */ new Date();
+  }
+  return updateData;
+}
+export function hasMessageUpdate(updateData) {
+  return Object.keys(updateData).length > 0;
+}
+export function isTerminalMessageUpdate(updateData) {
+  return updateData.status === "completed" || updateData.status === "failed";
+}
+export function buildMessageUpdateResponse(messages, messageId, updateData) {
+  const updatedMessages = messages.map(
+    (message) => message.id === messageId ? { ...message, ...updateData } : message
+  );
+  if (updateData.files && updateData.files.length > 0) {
+    return {
+      messages: updatedMessages,
+      newFiles: updateData.files
+    };
+  }
+  return { messages: updatedMessages };
+}
+export function trackTelaAgentConversationUsage(db, context, conversationId, sessionId, usage) {
+  if (!usage)
+    return;
+  void db.insert(schema.conversationUsage).values({
+    workspaceId: context.workspaceId,
+    conversationId,
+    ...usage,
+    userId: context.user.id,
+    userEmail: context.user.email ?? null,
+    sessionId
+  }).onConflictDoUpdate({
+    target: schema.conversationUsage.conversationId,
+    set: {
+      ...usage,
+      updatedAt: /* @__PURE__ */ new Date()
+    }
+  }).catch((error) => {
+    logger.warn({ conversationId, error }, "Failed to track conversation usage");
+  });
+}
+export function trackAgentApiConversationUsage(db, context, conversationId, sessionId, agentSession) {
+  const usage = agentSession.result?.usage;
+  if (!usage)
+    return;
+  const breakdown = agentSession.result?.usageBreakdown;
+  const serverToolUse = breakdown?.serverToolUse;
+  const webSearchRequests = typeof serverToolUse?.web_search_requests === "number" ? serverToolUse.web_search_requests : null;
+  const webFetchRequests = typeof serverToolUse?.web_fetch_requests === "number" ? serverToolUse.web_fetch_requests : null;
+  void db.insert(schema.conversationUsage).values({
+    workspaceId: context.workspaceId,
+    conversationId,
+    promptTokens: usage.promptTokens ?? 0,
+    completionTokens: usage.completionTokens ?? 0,
+    totalTokens: usage.totalTokens ?? 0,
+    promptCost: String(usage.promptCost ?? 0),
+    completionCost: String(usage.completionCost ?? 0),
+    totalCost: String(usage.totalCost ?? 0),
+    durationMs: usage.duration ?? null,
+    turns: usage.turns ?? null,
+    userId: context.user.id,
+    userEmail: context.user.email ?? null,
+    model: agentSession.model ?? null,
+    sessionId,
+    cacheReadInputTokens: breakdown?.cacheReadInputTokens ?? null,
+    cacheCreationInputTokens: breakdown?.cacheCreationInputTokens ?? null,
+    modelUsage: breakdown?.modelUsage ?? null,
+    durationApiMs: breakdown?.durationApiMs ?? null,
+    webSearchRequests,
+    webFetchRequests
+  }).onConflictDoUpdate({
+    target: schema.conversationUsage.conversationId,
+    set: {
+      promptTokens: usage.promptTokens ?? 0,
+      completionTokens: usage.completionTokens ?? 0,
+      totalTokens: usage.totalTokens ?? 0,
+      promptCost: String(usage.promptCost ?? 0),
+      completionCost: String(usage.completionCost ?? 0),
+      totalCost: String(usage.totalCost ?? 0),
+      durationMs: usage.duration ?? null,
+      turns: usage.turns ?? null,
+      model: agentSession.model ?? null,
+      cacheReadInputTokens: breakdown?.cacheReadInputTokens ?? null,
+      cacheCreationInputTokens: breakdown?.cacheCreationInputTokens ?? null,
+      modelUsage: breakdown?.modelUsage ?? null,
+      durationApiMs: breakdown?.durationApiMs ?? null,
+      webSearchRequests,
+      webFetchRequests,
+      updatedAt: /* @__PURE__ */ new Date()
+    }
+  }).catch((error) => {
+    logger.warn({ conversationId, error }, "Failed to track conversation usage");
+  });
+}

package/dist/runtime/server/utils/conversation-scope.d.ts

@@ -0,0 +1,2 @@
+import type { ChatRuntimeContext } from '#chat-runtime/server/utils/chat-context';
+export declare function conversationScopeConditions(context: ChatRuntimeContext, conversationId?: string): import("drizzle-orm").SQL<unknown> | undefined;

package/dist/runtime/server/utils/conversation-scope.js

@@ -0,0 +1,12 @@
+import { and, eq, isNull } from "drizzle-orm";
+import { schema } from "#chat-runtime/server/db";
+export function conversationScopeConditions(context, conversationId) {
+  const conditions = [
+    eq(schema.conversations.workspaceId, context.workspaceId),
+    context.telaAgentId ? eq(schema.conversations.telaAgentId, context.telaAgentId) : isNull(schema.conversations.telaAgentId)
+  ];
+  if (conversationId) {
+    conditions.unshift(eq(schema.conversations.id, conversationId));
+  }
+  return and(...conditions);
+}

package/dist/runtime/server/utils/tela-agent-api.d.ts

@@ -0,0 +1,29 @@
+import type { H3Event } from 'h3';
+import type { TelaAgent, TelaAgentRunPayload, TelaAgentSession } from '#chat-runtime/types/tela-agent';
+export declare function runTelaAgent(event: H3Event, agentId: string, payload: TelaAgentRunPayload): Promise<{
+    success: true;
+    sessionId: string;
+} | {
+    success: false;
+    error: string;
+}>;
+export declare function getTelaAgent(event: H3Event, agentId: string): Promise<{
+    success: true;
+    data: TelaAgent;
+} | {
+    success: false;
+    error: string;
+}>;
+export declare function getTelaAgentSession(event: H3Event, sessionId: string): Promise<{
+    success: true;
+    data: TelaAgentSession;
+} | {
+    success: false;
+    error: string;
+}>;
+export declare function endTelaAgentSession(event: H3Event, sessionId: string): Promise<{
+    success: true;
+} | {
+    success: false;
+    error: string;
+}>;

package/dist/runtime/server/utils/tela-agent-api.js

@@ -0,0 +1,107 @@
+import { useRuntimeConfig } from "nitropack/runtime";
+import {
+  telaAgentApiResponseSchema,
+  telaAgentEndSessionApiResponseSchema,
+  telaAgentRunApiResponseSchema,
+  telaAgentSessionApiResponseSchema
+} from "#chat-runtime/types/tela-agent";
+import { getAgentDataToken } from "#chat-runtime/server/utils/agent-api";
+import { logger } from "#chat-runtime/server/utils/logger";
+function getTelaErrorMessage(body, fallback) {
+  if (body && typeof body === "object") {
+    const record = body;
+    if (typeof record.error === "string")
+      return record.error;
+    if (typeof record.message === "string")
+      return record.message;
+  }
+  return fallback;
+}
+async function readResponseBody(response) {
+  const text = await response.text();
+  if (!text)
+    return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+async function telaAgentFetch(event, path, init) {
+  const { telaApiUrl } = useRuntimeConfig();
+  const token = getAgentDataToken(event);
+  const url = `${telaApiUrl}${path}`;
+  const response = await fetch(url, {
+    ...init,
+    headers: {
+      "Content-Type": "application/json",
+      "x-data-token": token,
+      "Authorization": `Bearer ${token}`,
+      ...init.headers
+    }
+  });
+  const body = await readResponseBody(response);
+  if (!response.ok) {
+    const error = getTelaErrorMessage(body, `Tela API error: ${response.status} - ${response.statusText}`);
+    logger.warn({ status: response.status, statusText: response.statusText, path }, "Tela agent API request failed");
+    return { success: false, error };
+  }
+  return { success: true, body };
+}
+export async function runTelaAgent(event, agentId, payload) {
+  const encodedAgentId = encodeURIComponent(agentId);
+  const result = await telaAgentFetch(event, `/agent/${encodedAgentId}/run`, {
+    method: "POST",
+    body: JSON.stringify(payload)
+  });
+  if (!result.success)
+    return result;
+  const parsed = telaAgentRunApiResponseSchema.safeParse(result.body);
+  if (!parsed.success) {
+    logger.warn({ issues: parsed.error.issues }, "Tela agent run response parse error");
+    return { success: false, error: "Invalid response from Tela API" };
+  }
+  return { success: true, sessionId: parsed.data.data.sessionId };
+}
+export async function getTelaAgent(event, agentId) {
+  const encodedAgentId = encodeURIComponent(agentId);
+  const result = await telaAgentFetch(event, `/agent/${encodedAgentId}`, {
+    method: "GET"
+  });
+  if (!result.success)
+    return result;
+  const parsed = telaAgentApiResponseSchema.safeParse(result.body);
+  if (!parsed.success) {
+    logger.warn({ issues: parsed.error.issues, agentId }, "Tela agent metadata response parse error");
+    return { success: false, error: "Invalid agent metadata response from Tela API" };
+  }
+  return { success: true, data: parsed.data.data };
+}
+export async function getTelaAgentSession(event, sessionId) {
+  const encodedSessionId = encodeURIComponent(sessionId);
+  const result = await telaAgentFetch(event, `/agent/sessions/${encodedSessionId}`, {
+    method: "GET"
+  });
+  if (!result.success)
+    return result;
+  const parsed = telaAgentSessionApiResponseSchema.safeParse(result.body);
+  if (!parsed.success) {
+    logger.warn({ issues: parsed.error.issues, sessionId }, "Tela agent session response parse error");
+    return { success: false, error: "Invalid session response from Tela API" };
+  }
+  return { success: true, data: parsed.data.data };
+}
+export async function endTelaAgentSession(event, sessionId) {
+  const encodedSessionId = encodeURIComponent(sessionId);
+  const result = await telaAgentFetch(event, `/agent/sessions/${encodedSessionId}`, {
+    method: "DELETE"
+  });
+  if (!result.success)
+    return result;
+  const parsed = telaAgentEndSessionApiResponseSchema.safeParse(result.body);
+  if (!parsed.success || !parsed.data.data.success) {
+    logger.warn({ sessionId }, "Tela agent end session response parse error");
+    return { success: false, error: "Invalid end-session response from Tela API" };
+  }
+  return { success: true };
+}

package/dist/runtime/server/utils/tela-agent-session.d.ts

@@ -0,0 +1,48 @@
+import type { MessageStatus, ReasoningItem } from '#chat-runtime/types/agent';
+import type { FileUploadInput, MessageFile } from '#chat-runtime/types/chat';
+import type { TelaAgentExecutionInput, TelaAgentInputVariable, TelaAgentSession, TelaAgentStep } from '#chat-runtime/types/tela-agent';
+export type TelaAgentMessageUpdate = {
+    reasoningData?: ReasoningItem[];
+    externalUuid?: string;
+    content?: string;
+    status?: MessageStatus;
+    ttft?: string;
+    updatedAt?: Date;
+    files?: MessageFile[];
+};
+export type TelaAgentUsageValues = {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    promptCost: string;
+    completionCost: string;
+    totalCost: string;
+    durationMs: number | null;
+    turns: number | null;
+    model: string | null;
+    cacheReadInputTokens: number | null;
+    cacheCreationInputTokens: number | null;
+    modelUsage: null;
+    durationApiMs: null;
+    webSearchRequests: null;
+    webFetchRequests: null;
+};
+type TelaAgentFileInput = FileUploadInput | MessageFile;
+export declare function toTelaAgentInputSchema(files: TelaAgentFileInput[] | undefined, inputVariables: TelaAgentInputVariable[] | null | undefined): TelaAgentExecutionInput[];
+export declare function toTelaAgentAttachments(files: TelaAgentFileInput[] | undefined): {
+    vaultRef: string;
+    filename: any;
+}[];
+export declare function getTelaAgentStepSyncId(step: TelaAgentStep): string;
+export declare function normalizeTelaAgentReasoningStep(sessionId: string, step: TelaAgentStep): ReasoningItem | null;
+export declare function getNewTelaAgentSteps(session: TelaAgentSession, lastSyncedStepId: string | null | undefined): TelaAgentStep[];
+export declare function extractTelaAgentAssistantContent(session: TelaAgentSession, steps?: TelaAgentStep[]): string;
+export declare function mapTelaAgentSessionToMessageUpdate(session: TelaAgentSession, options?: {
+    lastSyncedStepId?: string | null;
+    existingReasoningData?: ReasoningItem[] | null;
+    pendingMessageTtft?: string | null;
+    userMessageCreatedAt?: Date | null;
+    now?: Date;
+}): TelaAgentMessageUpdate;
+export declare function mapTelaAgentUsage(session: TelaAgentSession): TelaAgentUsageValues | null;
+export {};