@andreprado/agentkit 0.1.0-alpha.16 → 0.1.0-alpha.18

package/docs/llms.txt

@@ -16,13 +16,12 @@ Task guides:
 - Build container artifact: `agentkit build --target container`
 - Generate VPS handoff: `agentkit deploy --target vps --host agent.example.com --dry-run`
 - Add hosted channels: `docs/guides/add-channel.md`
+- Add AgentKit-managed Composio: `docs/guides/add-managed-composio.md`
 - Buffer rapid channel messages: `docs/guides/add-channel.md#buffer-bursty-messages`
 - Connect Telegram: `docs/guides/connect-telegram.md`
 - Connect WhatsApp through Zapster: `docs/guides/connect-whatsapp-zapster.md`
 - Follow channel webhook and delivery-log safety rules: `docs/guides/channel-security.md`
-- Prepare Channels for production: `docs/guides/channels-production-handoff.md`
 - Follow secret, access, and tool safety rules: `docs/guides/security-rules.md`
-- Plan repo-local skills for coding agents: `docs/guides/agentkit-skills-architecture.md`
 
 Current local commands:
 
@@ -43,12 +42,19 @@ agentkit knowledge search <query> [--top-k <number>]
 agentkit eval run
 agentkit conversations list
 agentkit conversations show <conversation-id>
+agentkit conversations trace <conversation-id> [--deploy]
 agentkit channels list
 agentkit channels add telegram support-telegram
 agentkit channels setup support-telegram
 agentkit channels status support-telegram
 agentkit channels test support-telegram --message "hello"
+agentkit channels test-audio support-telegram --fixture voice-note
+agentkit transcribe smoke --provider groq
 agentkit channels deliveries list support-telegram
+agentkit integrations status [--toolkit googlecalendar]
+agentkit integrations connect composio --toolkit gmail
+agentkit skills status
+agentkit skills sync
 agentkit login --token agk_user_...
 agentkit deploy doctor
 agentkit deploy --smoke "hello"
@@ -69,6 +75,8 @@ Generated capsules include `AGENTKIT.md`, `AGENTS.md`, and a repo-local `skills/
 
 UI testing is part of the handoff. For local UI testing, run `agentkit dev`, open the printed `Chat:` URL, and tell the owner the exact URL. After hosted deploy, run `agentkit chat-ui --deploy`, open the printed `Chat:` URL, and tell the owner it is connected to the deploy.
 
+Hosted Chat UI shows the current conversation id, tool calls, tool errors, and a new-conversation control. Use `agentkit conversations trace <conversation-id> --deploy` to pull the hosted trace from the last deploy.
+
 `test/fake` is deterministic and validates scaffold, direct tool calls, and fake-provider evals. It does not validate natural conversation quality. Before claiming real conversation behavior has been tested, ask the owner which provider to use: OpenRouter, OpenAI, Anthropic, or another supported provider. Do not choose for them.
 
 AgentKit injects the current ISO timestamp, local date, weekday, local date/time, and timezone dynamically into every chat run. Set `timeZone` in `agentkit.config.ts` for scheduling agents so "today", "tomorrow", and weekdays resolve in the business/user timezone; otherwise AgentKit falls back to `AGENTKIT_TIME_ZONE`, valid `TZ`, then the runtime default. Do not hardcode today's date in prompts.
@@ -80,6 +88,7 @@ GET  /_agentkit
 POST /v1/chat
 GET  /v1/conversations
 GET  /v1/conversations/:id
+GET  /v1/conversations/:id/trace
 ```
 
 Local `.env` is for development only. Use `.env.schema` as the committed secret-name contract; local AgentKit commands load `.env` directly. Hosted alpha deploys require `cloudflare_deploy_alpha` through `agentkit login --token ...`; production uses managed secrets in the hosted contract.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andreprado/agentkit",
-  "version": "0.1.0-alpha.16",
+  "version": "0.1.0-alpha.18",
   "private": false,
   "type": "module",
   "repository": {
@@ -18,8 +18,6 @@
     "!src/**/*.test.ts",
     "!src/runtime/fixtures",
     "docs",
-    "!docs/guides/backend-contracts.md",
-    "!docs/guides/debug-channel.md",
     "README.md"
   ],
   "publishConfig": {

package/src/cli/cloud-client.ts

@@ -39,6 +39,18 @@ export type CloudLimitsResponse = {
   };
 };
 
+export type CloudManagedComposioResponse = {
+  managed_composio?: {
+    entitlement?: "active" | "missing" | string;
+    api_key?: "set" | "missing" | string;
+    toolkits?: Array<{
+      toolkit?: string;
+      auth_config_env?: string;
+      auth_config?: "set" | "missing" | string;
+    }>;
+  };
+};
+
 export type CloudProjectResolveResponse = {
   project?: {
     id?: string;

package/src/cli/commands/channels.ts

@@ -162,8 +162,10 @@ export async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
     let channel = created.channel;
     printChannelStatus(channel);
     printSecretRepairHint(channel);
+    console.log("Channel resource: created_or_updated");
 
     if (hasMissingRequiredSecrets(channel)) {
+      console.log("Secrets: missing");
       console.log("");
       console.log("Connect blocked: set the missing managed secrets, then rerun this same command.");
       console.log("Run: npm run agentkit -- secret sync --from-local");
@@ -171,31 +173,40 @@ export async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
       return;
     }
 
+    console.log("Secrets: validated");
+
     if (channel.type === "telegram") {
       const setup = await applyTelegramWebhook(channel, args.flags.api);
       channel = setup.channel ?? channel;
+      console.log("Telegram setWebhook: OK");
       console.log("Telegram webhook confirmed.");
       if (setup.setup?.get_webhook_info) {
         console.log(`Telegram pending updates: ${setup.setup.get_webhook_info.pending_update_count}`);
       }
 
-      const smoke = await runChannelSmoke(channel, args.flags.api, args.flags.message);
-      console.log(`Smoke: ${smoke.status}${smoke.delivery_id ? ` (${smoke.delivery_id})` : ""}`);
+      const smoke = await runConnectSmoke(() => runChannelSmoke(channel, args.flags.api, args.flags.message));
       printTelegramHumanNextStep(channel.name, setup.setup?.bot_username);
+      if (!smoke) {
+        process.exitCode = 1;
+      }
       return;
     }
 
     if (channel.type === "whatsapp" && channel.provider === "zapster") {
-      const smoke = await runChannelSmoke(channel, args.flags.api, args.flags.message);
-      console.log(`Webhook smoke: ${smoke.status}${smoke.delivery_id ? ` (${smoke.delivery_id})` : ""}`);
+      const smoke = await runConnectSmoke(() => runChannelSmoke(channel, args.flags.api, args.flags.message));
       console.log(`Next human step: paste ${channel.webhook_url} into ${channel.provider}'s webhook settings.`);
+      if (!smoke) {
+        process.exitCode = 1;
+      }
     } else if (channel.type === "whatsapp") {
       console.log("Smoke: skipped until the provider webhook is configured.");
       console.log(`Next human step: paste ${channel.webhook_url} into ${channel.provider}'s webhook settings.`);
     } else {
-      const smoke = await runChannelSmoke(channel, args.flags.api, args.flags.message);
-      console.log(`Smoke: ${smoke.status}${smoke.delivery_id ? ` (${smoke.delivery_id})` : ""}`);
+      const smoke = await runConnectSmoke(() => runChannelSmoke(channel, args.flags.api, args.flags.message));
       console.log(`Next human step: use ${channel.webhook_url} from your website client.`);
+      if (!smoke) {
+        process.exitCode = 1;
+      }
     }
     return;
   }
@@ -274,6 +285,25 @@ export async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
     return;
   }
 
+  if (subcommand === "test-audio") {
+    if (!first) {
+      throw new Error("Usage: agentkit channels test-audio <name> [--fixture voice-note|audio-file|<path>]");
+    }
+
+    const channel = await resolveCloudChannelByName(first, args.flags.api);
+    const apiUrl = parseCloudApiUrl(args.flags.api);
+    const body = await channelAudioTestBody(channel, args.flags.fixture);
+    const signed = await runServerSignedChannelTest(channel, apiUrl, body);
+    const response = signed.response;
+    const payload = signed.payload;
+
+    console.log(JSON.stringify(payload, null, 2));
+    if (!response.ok) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
   if (subcommand === "deliveries") {
     if (first === "list") {
       if (!second) {
@@ -367,7 +397,7 @@ export async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
   }
 
   throw new Error(
-    "Usage: agentkit channels list | add | connect | setup | status | doctor | test | deliveries list | deliveries show | buffers list | buffers show | buffers flush | buffers clear | buffers retry",
+    "Usage: agentkit channels list | add | connect | setup | status | doctor | test | test-audio | deliveries list | deliveries show | buffers list | buffers show | buffers flush | buffers clear | buffers retry",
   );
 }
 
@@ -419,6 +449,20 @@ async function runChannelSmoke(
   return { status: "unknown" };
 }
 
+async function runConnectSmoke(
+  run: () => Promise<{ status: string; delivery_id?: string }>,
+): Promise<{ status: string; delivery_id?: string } | null> {
+  try {
+    const smoke = await run();
+    console.log(`Synthetic smoke: ${smoke.status}${smoke.delivery_id ? ` (${smoke.delivery_id})` : ""}`);
+    return smoke;
+  } catch (error) {
+    console.log("Synthetic smoke: failed");
+    console.log(`  ${formatCommandError(error)}`);
+    return null;
+  }
+}
+
 async function runServerSignedChannelTest(
   channel: CloudChannel,
   apiUrl: string,
@@ -601,6 +645,10 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 
+function formatCommandError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
 async function readDeployStateIfExists(cwd: string): Promise<DeployState | null> {
   return readLocalDeployStateIfExists(cwd);
 }
@@ -974,6 +1022,70 @@ async function channelTestBody(
   });
 }
 
+async function channelAudioTestBody(
+  channel: CloudChannel,
+  fixtureFlag: string | boolean | undefined,
+): Promise<string> {
+  if (typeof fixtureFlag === "string" && isExplicitFixturePath(fixtureFlag)) {
+    return readFile(resolve(process.cwd(), fixtureFlag), "utf8");
+  }
+
+  const fixture = typeof fixtureFlag === "string" ? fixtureFlag : "voice-note";
+
+  if (channel.type === "telegram") {
+    if (fixture !== "voice-note" && fixture !== "telegram-voice-note" && fixture !== "telegram-audio-message") {
+      throw new Error('Telegram audio smoke supports --fixture voice-note or --fixture telegram-voice-note.');
+    }
+
+    return JSON.stringify({
+      update_id: Date.now(),
+      message: {
+        message_id: 1,
+        date: Math.floor(Date.now() / 1000),
+        chat: { id: 456, type: "private" },
+        from: { id: 123, first_name: "AgentKit" },
+        voice: {
+          file_id: `agentkit_voice_${Date.now()}`,
+          file_unique_id: `agentkit_voice_unique_${Date.now()}`,
+          duration: 12,
+          mime_type: "audio/ogg",
+          file_size: 42,
+        },
+      },
+    });
+  }
+
+  if (channel.type === "whatsapp" && channel.provider === "zapster") {
+    if (fixture !== "voice-note" && fixture !== "audio-file" && fixture !== "zapster-audio" && fixture !== "zapster-audio-message") {
+      throw new Error('Zapster audio smoke supports --fixture voice-note, --fixture audio-file, or --fixture zapster-audio.');
+    }
+
+    return JSON.stringify({
+      event_id: `zap_evt_audio_${Date.now()}`,
+      instance_id: "local",
+      message: {
+        id: `wamid.audio.${Date.now()}`,
+        from: "5511999999999",
+        type: "audio",
+        audio: {
+          id: `media_audio_${Date.now()}`,
+          url: `https://api.zapsterapi.com/media/audio/media_audio_${Date.now()}.ogg`,
+          mime_type: "audio/ogg",
+          duration: 12,
+          file_size: 42,
+          ...(fixture === "voice-note" ? { ptt: "true" } : {}),
+        },
+      },
+    });
+  }
+
+  throw new Error(`Audio smoke is not supported for ${channel.type}/${channel.provider}.`);
+}
+
+function isExplicitFixturePath(value: string): boolean {
+  return value.includes("/") || value.startsWith(".") || value.endsWith(".json");
+}
+
 function channelTestHeaders(channel: CloudChannel): Headers {
   const headers = new Headers({ "Content-Type": "application/json" });
 

package/src/cli/commands/transcribe.ts

@@ -0,0 +1,171 @@
+import { readFile } from "node:fs/promises";
+import { basename, extname, resolve } from "node:path";
+
+import type { TranscriptionProviderName } from "../../index";
+import { findAgentCapsuleRoot, loadAgentCapsule } from "../../runtime/config";
+import { loadCapsuleEnv } from "../../runtime/env";
+import {
+  defaultTranscriptionSecret,
+  resolveTranscriptionConfig,
+  transcribeAudio,
+  type ResolvedTranscriptionConfig,
+} from "../../runtime/transcription";
+import type { ParsedArgs } from "../args";
+
+type SmokeFixture = {
+  audio: Uint8Array;
+  filename: string;
+  mimeType: string;
+  source: string;
+};
+
+const defaultModels: Record<TranscriptionProviderName, string> = {
+  test: "fake",
+  openai: "gpt-4o-mini-transcribe",
+  groq: "whisper-large-v3-turbo",
+};
+
+// Short macOS-generated spoken "hello" sample encoded as M4A. M4A is supported by OpenAI and Groq.
+const builtinSmokeM4aBase64 =
+  "AAAAHGZ0eXBNNEEgAAAAAE00QSBtcDQyaXNvbQAAA3ptb292AAAAbG12aGQAAAAA5kTZseZE2bEAAFYiAAA4AAABAAABAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAAACDHRyYWsAAABcdGtoZAAAAAfmRNmx5kTZsQAAAAEAAAAAAAA4AAAAAAAAAAAAAAAAAAEAAAAAAQAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAahtZGlhAAAAIG1kaGQAAAAA5kTZseZE2bEAAFYiAAA4AAAAAAAAAAAiaGRscgAAAAAAAAAAc291bgAAAAAAAAAAAAAAAAAAAAABXm1pbmYAAAAQc21oZAAAAAAAAAAAAAAAJGRpbmYAAAAcZHJlZgAAAAAAAAABAAAADHVybCAAAAABAAABInN0YmwAAAB2c3RzZAAAAAAAAAABAAAAZm1wNGEAAAAAAAAAAQAAAAAAAAAAAAIAEAAAAABWIgAAAAAAM2VzZHMAAAAAA4CAgCIAAAAEgICAFEAUABgAAAAU+AAAfQAFgICAAhOIBoCAgAECAAAAD3NidGQAAAAASTE2AAAAGHN0dHMAAAAAAAAAAQAAAA4AAAQAAAAAKHN0c2MAAAAAAAAAAgAAAAEAAAALAAAAAQAAAAIAAAADAAAAAQAAAExzdHN6AAAAAAAAAAAAAAAOAAAABAAAAbkAAADiAAAA0wAAAL8AAADLAAAAzAAAAJMAAACmAAAA5wAAALcAAACnAAAAtgAAADoAAAAYc3RjbwAAAAAAAAACAAAQAAAAGJ8AAAD6dWR0YQAAAPJtZXRhAAAAAAAAACJoZGxyAAAAAAAAAABtZGlyYXBwbAAAAAAAAAAAAAAAAADEaWxzdAAAALwtLS0tAAAAHG1lYW4AAAAAY29tLmFwcGxlLmlUdW5lcwAAABRuYW1lAAAAAGlUdW5TTVBCAAAAhGRhdGEAAAABAAAAACAwMDAwMDAwMCAwMDAwMDg0MCAwMDAwMDEwOCAwMDAwMDAwMDAwMDAyRUI4IDAwMDAwMDAwIDAwMDAwMDAwIDAwMDAwMDAwIDAwMDAwMDAwIDAwMDAwMDAwIDAwMDAwMDAwIDAwMDAwMDAwIDAwMDAwMDAwAAAMYmZyZWUAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA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";
+
+export async function handleTranscribeCommand(args: ParsedArgs): Promise<void> {
+  const [subcommand] = args.positional;
+
+  if (subcommand !== "smoke") {
+    throw new Error("Usage: agentkit transcribe smoke [--provider test|openai|groq] [--model <model>] [--fixture <audio-file>]");
+  }
+
+  const root = await findAgentCapsuleRoot(process.cwd());
+  const capsule = await loadAgentCapsule(root);
+  const env = compactEnv(await loadCapsuleEnv(root, process.env));
+  const configured = resolveTranscriptionConfig(capsule.config.transcription);
+  const provider = parseProviderFlag(args.flags.provider, configured);
+  const model = typeof args.flags.model === "string" ? args.flags.model : configured.enabled && configured.provider === provider ? configured.model : defaultModels[provider];
+  const secret = typeof args.flags.secret === "string"
+    ? args.flags.secret
+    : configured.enabled && configured.provider === provider
+      ? configured.secret
+      : defaultTranscriptionSecret(provider);
+  const fixture = await loadSmokeFixture(provider, args.flags.fixture);
+
+  const config: ResolvedTranscriptionConfig = {
+    enabled: true,
+    provider,
+    model,
+    secret,
+    language: typeof args.flags.language === "string" ? args.flags.language : configured.enabled ? configured.language : null,
+    prompt: typeof args.flags.prompt === "string" ? args.flags.prompt : configured.enabled ? configured.prompt : null,
+    limits: configured.enabled ? configured.limits : {},
+    rawAudioTtlSeconds: configured.enabled ? configured.rawAudioTtlSeconds : 3600,
+  };
+  const result = await transcribeAudio({
+    config,
+    secrets: env,
+    audio: fixture.audio,
+    filename: fixture.filename,
+    mimeType: fixture.mimeType,
+  });
+
+  console.log("Transcription smoke");
+  console.log(`Provider: ${provider}`);
+  console.log(`Model: ${model}`);
+  console.log(`Fixture: ${fixture.source} (${fixture.mimeType})`);
+
+  if (result.ok) {
+    console.log("Status: ok");
+    console.log(`Transcript: ${JSON.stringify(result.text)}`);
+    return;
+  }
+
+  console.log("Status: failed");
+  console.log(`Code: ${result.code}`);
+  console.log(`Message: ${result.message}`);
+  process.exitCode = 1;
+}
+
+function parseProviderFlag(
+  value: string | boolean | undefined,
+  configured: ResolvedTranscriptionConfig,
+): TranscriptionProviderName {
+  if (value === undefined || value === false) {
+    return configured.enabled ? configured.provider : "groq";
+  }
+
+  if (value === "test" || value === "openai" || value === "groq") {
+    return value;
+  }
+
+  throw new Error("Usage: agentkit transcribe smoke [--provider test|openai|groq] [--model <model>] [--fixture <audio-file>]");
+}
+
+function compactEnv(env: Record<string, string | undefined>): Record<string, string> {
+  const compact: Record<string, string> = {};
+
+  for (const [name, value] of Object.entries(env)) {
+    if (value !== undefined) {
+      compact[name] = value;
+    }
+  }
+
+  return compact;
+}
+
+async function loadSmokeFixture(
+  provider: TranscriptionProviderName,
+  fixtureFlag: string | boolean | undefined,
+): Promise<SmokeFixture> {
+  if (typeof fixtureFlag === "string") {
+    const filename = resolve(process.cwd(), fixtureFlag);
+    return {
+      audio: new Uint8Array(await readFile(filename)),
+      filename: basename(filename),
+      mimeType: mimeTypeForFilename(filename),
+      source: fixtureFlag,
+    };
+  }
+
+  if (provider === "test") {
+    return {
+      audio: new TextEncoder().encode("hello"),
+      filename: "agentkit-smoke.ogg",
+      mimeType: "audio/ogg",
+      source: "built-in text fixture",
+    };
+  }
+
+  return {
+    audio: new Uint8Array(Buffer.from(builtinSmokeM4aBase64, "base64")),
+    filename: "agentkit-transcribe-smoke.m4a",
+    mimeType: "audio/m4a",
+    source: "built-in spoken hello",
+  };
+}
+
+function mimeTypeForFilename(filename: string): string {
+  const extension = extname(filename).toLowerCase();
+
+  if (extension === ".ogg" || extension === ".opus") {
+    return "audio/ogg";
+  }
+  if (extension === ".mp3" || extension === ".mpeg" || extension === ".mpga") {
+    return "audio/mpeg";
+  }
+  if (extension === ".m4a") {
+    return "audio/m4a";
+  }
+  if (extension === ".mp4") {
+    return "audio/mp4";
+  }
+  if (extension === ".wav") {
+    return "audio/wav";
+  }
+  if (extension === ".webm") {
+    return "audio/webm";
+  }
+  if (extension === ".flac") {
+    return "audio/flac";
+  }
+
+  return "application/octet-stream";
+}

package/src/cli/deploy-chat-ui.ts

@@ -70,6 +70,27 @@ export async function startDeployChatUiServer(
         return;
       }
 
+      if (
+        request.method === "GET" &&
+        (requestUrl.pathname === "/v1/conversations" ||
+          /^\/v1\/conversations\/[^/]+(?:\/trace)?$/.test(requestUrl.pathname))
+      ) {
+        const token = await readDeployAccessTokenForUi(tokenPath);
+        const upstream = await fetch(new URL(requestUrl.pathname, deployUrl).href, {
+          method: "GET",
+          headers: {
+            Authorization: `Bearer ${token}`,
+          },
+        });
+        const text = await upstream.text();
+
+        response.writeHead(upstream.status, {
+          "content-type": upstream.headers.get("content-type") ?? "application/json",
+        });
+        response.end(text);
+        return;
+      }
+
       sendJson(response, 404, { error: { code: "not_found", message: "Route not found." } });
     } catch (error) {
       sendJson(response, 500, {
@@ -196,6 +217,8 @@ function renderDeployChatUi(input: { deployUrl: string }): string {
       header {
         border-bottom: 1px solid var(--line);
         padding: 18px 22px;
+        display: grid;
+        gap: 10px;
       }
 
       h1 {
@@ -204,12 +227,27 @@ function renderDeployChatUi(input: { deployUrl: string }): string {
         line-height: 1.2;
       }
 
+      .topline {
+        display: flex;
+        align-items: start;
+        justify-content: space-between;
+        gap: 12px;
+      }
+
       code {
         color: var(--muted);
         font-size: 12px;
         overflow-wrap: anywhere;
       }
 
+      .meta {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 8px 14px;
+        color: var(--muted);
+        font-size: 12px;
+      }
+
       #messages {
         padding: 22px;
         overflow: auto;
@@ -255,6 +293,39 @@ function renderDeployChatUi(input: { deployUrl: string }): string {
         background: #fff6f6;
       }
 
+      #trace {
+        border-top: 1px solid var(--line);
+        padding: 12px 22px;
+        display: grid;
+        gap: 8px;
+        background: #fbfbfa;
+      }
+
+      .tool-call {
+        border: 1px solid var(--line);
+        border-radius: 8px;
+        padding: 10px 12px;
+        display: grid;
+        gap: 6px;
+        font-size: 12px;
+      }
+
+      .tool-head {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 8px;
+        align-items: center;
+        color: var(--muted);
+        font-weight: 700;
+      }
+
+      .tool-call pre {
+        margin: 0;
+        max-height: 180px;
+        overflow: auto;
+        white-space: pre-wrap;
+      }
+
       form {
         border-top: 1px solid var(--line);
         padding: 14px;
@@ -286,6 +357,13 @@ function renderDeployChatUi(input: { deployUrl: string }): string {
         cursor: pointer;
       }
 
+      button.secondary {
+        min-height: 34px;
+        color: var(--ink);
+        background: #eef1ee;
+        border: 1px solid var(--line);
+      }
+
       button:disabled {
         cursor: wait;
         opacity: 0.65;
@@ -305,10 +383,20 @@ function renderDeployChatUi(input: { deployUrl: string }): string {
   <body>
     <main>
       <header>
-        <h1>AgentKit Hosted Chat</h1>
-        <code>${deployUrl}</code>
+        <div class="topline">
+          <div>
+            <h1>AgentKit Hosted Chat</h1>
+            <code>${deployUrl}</code>
+          </div>
+          <button class="secondary" id="new-conversation" type="button">New conversation</button>
+        </div>
+        <div class="meta">
+          <span>Conversation: <code id="conversation-id">none</code></span>
+          <span>Tool calls: <code id="tool-count">0</code></span>
+        </div>
       </header>
       <section id="messages" aria-live="polite"></section>
+      <section id="trace" aria-live="polite"></section>
       <form id="form">
         <textarea id="message" name="message" placeholder="Type a message" required autofocus></textarea>
         <button id="send" type="submit">Send</button>
@@ -319,6 +407,10 @@ function renderDeployChatUi(input: { deployUrl: string }): string {
       const textarea = document.querySelector("#message");
       const send = document.querySelector("#send");
       const messages = document.querySelector("#messages");
+      const trace = document.querySelector("#trace");
+      const conversationLabel = document.querySelector("#conversation-id");
+      const toolCount = document.querySelector("#tool-count");
+      const newConversation = document.querySelector("#new-conversation");
       let conversationId = null;
 
       function addMessage(role, content, className = "") {
@@ -335,6 +427,55 @@ function renderDeployChatUi(input: { deployUrl: string }): string {
         messages.scrollTop = messages.scrollHeight;
       }
 
+      function setConversationId(value) {
+        conversationId = value || null;
+        conversationLabel.textContent = conversationId || "none";
+      }
+
+      function renderTrace(payload) {
+        const calls = [];
+        for (const run of payload.runs || []) {
+          for (const call of run.toolCalls || []) {
+            calls.push(call);
+          }
+        }
+
+        toolCount.textContent = String(calls.length);
+        trace.innerHTML = "";
+
+        for (const call of calls.slice(-8)) {
+          const item = document.createElement("article");
+          item.className = "tool-call";
+          const head = document.createElement("div");
+          head.className = "tool-head";
+          head.textContent = [call.name, call.status, call.errorMessage].filter(Boolean).join(" · ");
+          const input = document.createElement("pre");
+          input.textContent = JSON.stringify(call.input || {}, null, 2);
+          item.append(head, input);
+          trace.append(item);
+        }
+      }
+
+      async function refreshTrace() {
+        if (!conversationId) {
+          toolCount.textContent = "0";
+          trace.innerHTML = "";
+          return;
+        }
+
+        const response = await fetch("/v1/conversations/" + encodeURIComponent(conversationId) + "/trace");
+        const payload = await response.json();
+        if (response.ok) renderTrace(payload);
+      }
+
+      newConversation.addEventListener("click", () => {
+        setConversationId(null);
+        messages.innerHTML = "";
+        trace.innerHTML = "";
+        toolCount.textContent = "0";
+        textarea.focus();
+      });
+
       textarea.addEventListener("keydown", (event) => {
         if (event.key !== "Enter" || event.shiftKey || event.isComposing) return;
         event.preventDefault();
@@ -363,10 +504,12 @@ function renderDeployChatUi(input: { deployUrl: string }): string {
             throw new Error(payload.error?.message || "Request failed");
           }
 
-          conversationId = payload.conversationId || conversationId;
+          setConversationId(payload.conversationId || conversationId);
           addMessage("assistant", payload.message?.content || "");
+          await refreshTrace();
         } catch (error) {
           addMessage("error", error instanceof Error ? error.message : String(error), "error");
+          await refreshTrace().catch(() => {});
         } finally {
           send.disabled = false;
           textarea.focus();