Streaming events

{
  apiVersion: "v1";
  requestId: string;  // matches the request's requestId for the whole stream
  sequence: number;   // strictly increasing within the stream
  at: string;          // ISO 8601 datetime, always with an explicit offset
  type: /* one of the 19 literals below */;
  // ...fields specific to that type
}

import type { AiPlatformEventV1 } from "@nexislabs/ai-platform";

let text = "";
const toolActivity: string[] = [];

for await (const event of client.streamChat(request, { signal: controller.signal })) {
  switch (event.type) {
    case "request.accepted":
      if (event.replayed) console.info(`replay of ${event.requestId}`);
      break;
    case "model.started":
      console.info(`model: ${event.model}`);
      break;
    case "text.delta":
      text += event.delta;
      break;
    case "reasoning.status":
      console.info(`status: ${event.status}`);
      break;
    case "tool.proposed":
      toolActivity.push(`proposed ${event.tool} (${event.toolCallId})`);
      break;
    case "approval.required":
      await parkForApproval(event); // defined below
      break;
    case "tool.started":
      toolActivity.push(`started ${event.tool}`);
      break;
    case "tool.completed":
      toolActivity.push(`completed ${event.toolCallId}`);
      break;
    case "tool.failed":
      toolActivity.push(`failed ${event.toolCallId}: ${event.code}`);
      break;
    case "memory.read":
    case "memory.write":
      break; // observability only; nothing to render by default
    case "output.structured":
      console.info(`structured output (${event.schemaId})`, event.value);
      break;
    case "ui.component":
      console.info("generative UI payload", event.component);
      break;
    case "usage":
      console.info(
        `usage: ${event.inputTokens}in/${event.outputTokens}out, ${event.modelCalls} model calls`,
      );
      break;
    case "warning":
      console.warn(`${event.code}: ${event.message}`);
      break;
    case "retry":
      console.info(`server retry #${event.attempt}: ${event.reason}`);
      break;
    case "response.final":
      console.info(`done: ${event.finishReason}`);
      break;
    case "request.cancelled":
      console.info(`cancelled: ${event.reason ?? "no reason given"}`);
      break;
    case "request.failed":
      console.error(`failed: ${event.problem.code}`, event.problem);
      break;
  }
}

import type { AiPlatformEventV1 } from "@nexislabs/ai-platform";

const pendingApprovals = new Map<string, "approved" | "denied">();

async function parkForApproval(
  event: Extract<AiPlatformEventV1, { type: "approval.required" }>,
): Promise<void> {
  // showApprovalCard is your own UI, not part of the SDK. Render event.summary
  // verbatim — it is the canonical, server-issued payload the person is
  // approving. Never paraphrase, truncate, or re-derive it for display.
  const decision = await showApprovalCard({
    approvalId: event.approvalId,
    toolCallId: event.toolCallId,
    summary: event.summary,
    expiresAt: event.expiresAt,
  });
  pendingApprovals.set(event.approvalId, decision);
}

import {
  AiPlatformChatRequestV1Schema,
  type AiPlatformChatRequestV1,
} from "@nexislabs/ai-platform";

function buildApprovalResumeRequest(
  original: AiPlatformChatRequestV1,
  approvalId: string,
  receipt: string,
): AiPlatformChatRequestV1 {
  return AiPlatformChatRequestV1Schema.parse({
    ...original,
    requestId: crypto.randomUUID(), // a new turn gets a new requestId
    approvals: [{ approvalId, receipt }],
  });
}

const resumed = buildApprovalResumeRequest(request, approvalId, receiptFromYourApprovalEndpoint);
for await (const next of client.streamChat(resumed)) {
  // ...
}