@andreprado/agentkit 0.1.0-alpha.9 → 0.1.1

package/src/cli/commands/feedback.ts

@@ -0,0 +1,438 @@
+import { randomBytes } from "node:crypto";
+import { chmod, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { AgentKitError } from "../../runtime/errors";
+import { findAgentCapsuleRoot, loadAgentCapsule } from "../../runtime/config";
+import { readLocalDeployStateIfExists } from "../../runtime/core/deploy-state";
+import type { ParsedArgs } from "../args";
+import {
+  cloudApiRequest,
+  readCloudAuthForApiUrl,
+  resolveCloudApiUrl,
+  type FeedbackSendResponse,
+} from "../cloud-client";
+import { parseOptionalStringFlag } from "../flags";
+
+type FeedbackKind =
+  | "bug"
+  | "confusion"
+  | "missing_docs"
+  | "feature_request"
+  | "deploy_issue"
+  | "runtime_issue"
+  | "other";
+
+type FeedbackAbout = "last-run" | "deploy" | "manual";
+
+type FeedbackDraft = {
+  schema_version: "agentkit.feedback.v1";
+  client_report_id: string;
+  kind: FeedbackKind;
+  summary: string;
+  message?: string;
+  source: Record<string, unknown>;
+  context: Record<string, unknown>;
+  diagnostics: Record<string, unknown>;
+};
+
+const feedbackKinds = new Set<FeedbackKind>([
+  "bug",
+  "confusion",
+  "missing_docs",
+  "feature_request",
+  "deploy_issue",
+  "runtime_issue",
+  "other",
+]);
+
+const feedbackAboutValues = new Set<FeedbackAbout>(["last-run", "deploy", "manual"]);
+
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+
+export async function handleFeedbackCommand(args: ParsedArgs): Promise<void> {
+  const [subcommand, draftPath] = args.positional;
+
+  if (subcommand === "create") {
+    const draft = await buildFeedbackDraft(process.cwd(), args);
+    const written = await writeFeedbackDraft(process.cwd(), draft, args.flags.out);
+
+    console.log("Feedback draft created");
+    console.log(`JSON: ${relativePath(process.cwd(), written.jsonPath)}`);
+    console.log(`Markdown: ${relativePath(process.cwd(), written.markdownPath)}`);
+    console.log(`Send: agentkit feedback send ${relativePath(process.cwd(), written.jsonPath)}`);
+    return;
+  }
+
+  if (subcommand === "preview") {
+    const draft = draftPath
+      ? await readFeedbackDraft(resolve(process.cwd(), draftPath))
+      : await buildFeedbackDraft(process.cwd(), args);
+    console.log(JSON.stringify(draft, null, 2));
+    return;
+  }
+
+  if (subcommand === "send") {
+    const apiUrl = await resolveCloudApiUrl(args.flags.api);
+    const auth = await readCloudAuthForApiUrl(apiUrl);
+
+    if (!auth) {
+      throw new AgentKitError(
+        "auth_required",
+        `Log in before sending feedback: agentkit login --token <token> --api ${apiUrl}`,
+      );
+    }
+
+    const draft = draftPath
+      ? await readFeedbackDraft(resolve(process.cwd(), draftPath))
+      : await buildFeedbackDraft(process.cwd(), args);
+
+    if (!draftPath && args.flags.save === true) {
+      const written = await writeFeedbackDraft(process.cwd(), draft, args.flags.out);
+      console.log(`Feedback draft saved: ${relativePath(process.cwd(), written.jsonPath)}`);
+    }
+
+    const payload = (await cloudApiRequest(apiUrl, "/v1/feedback", {
+      method: "POST",
+      headers: {
+        "Idempotency-Key": draft.client_report_id,
+      },
+      body: JSON.stringify(feedbackDraftToSubmission(draft)),
+    })) as FeedbackSendResponse;
+
+    const feedback = payload.feedback;
+
+    if (!feedback?.id) {
+      throw new AgentKitError("feedback_response_invalid", "AgentKit Cloud returned an invalid feedback response.");
+    }
+
+    console.log("Feedback sent");
+    console.log(`ID:     ${feedback.id}`);
+    console.log(`Kind:   ${feedback.kind ?? draft.kind}`);
+    console.log(`Status: ${feedback.status ?? "new"}`);
+    return;
+  }
+
+  throw new Error(
+    "Usage: agentkit feedback create|preview|send [draft.json] [--about last-run|deploy|manual] [--kind bug|confusion|missing_docs|feature_request|deploy_issue|runtime_issue|other] [--summary <text>] [--message <text>] [--api <url>]",
+  );
+}
+
+async function buildFeedbackDraft(cwd: string, args: ParsedArgs): Promise<FeedbackDraft> {
+  const about = parseFeedbackAbout(args.flags.about);
+  const kind = parseFeedbackKind(args.flags.kind, about === "deploy" ? "deploy_issue" : "other");
+  const message = parseOptionalStringFlag(args.flags.message, "message", "agentkit feedback create --message <text>");
+  const summary =
+    parseOptionalStringFlag(args.flags.summary, "summary", "agentkit feedback create --summary <text>") ??
+    summarizeMessage(message);
+
+  if (!summary) {
+    throw new Error("Missing summary. Usage: agentkit feedback create --summary <text> [--message <text>]");
+  }
+
+  const now = new Date().toISOString();
+  const context = await collectFeedbackContext(cwd);
+  const draft: FeedbackDraft = {
+    schema_version: "agentkit.feedback.v1",
+    client_report_id: `fbdraft_${Date.now().toString(36)}_${randomBytes(6).toString("hex")}`,
+    kind,
+    summary: redactText(summary).slice(0, 200),
+    ...(message ? { message: redactText(message).slice(0, 5_000) } : {}),
+    source: {
+      channel: "cli",
+      about,
+      created_at: now,
+      agentkit_version: await readAgentKitVersion(),
+    },
+    context,
+    diagnostics: {
+      redaction: "agentkit-cli-redaction-v1",
+      note:
+        about === "last-run"
+          ? "AgentKit does not persist a last-command transcript yet; this draft includes current capsule and deploy context."
+          : "This draft includes current capsule and deploy context.",
+    },
+  };
+
+  return redactJson(draft) as FeedbackDraft;
+}
+
+async function collectFeedbackContext(cwd: string): Promise<Record<string, unknown>> {
+  const context: Record<string, unknown> = {
+    platform: {
+      node: process.version,
+      bun: (globalThis as { Bun?: { version?: string } }).Bun?.version,
+      platform: process.platform,
+      arch: process.arch,
+      package_manager: await detectPackageManager(cwd),
+    },
+  };
+
+  const root = await findAgentCapsuleRoot(cwd).catch(() => null);
+
+  if (!root) {
+    context.capsule = {
+      detected: false,
+      cwd_name: basename(cwd),
+    };
+    return redactJson(context) as Record<string, unknown>;
+  }
+
+  const capsule = await loadAgentCapsule(root).catch((error: unknown) => ({
+    error: error instanceof Error ? error.message : String(error),
+  }));
+  const deployState = await readLocalDeployStateIfExists(root).catch(() => null);
+
+  if ("config" in capsule) {
+    context.capsule = {
+      detected: true,
+      root_name: basename(root),
+      name: capsule.config.name,
+      runtime: capsule.config.runtime,
+      provider: capsule.config.provider,
+      access: capsule.config.access,
+      storage: capsule.config.storage,
+      secret_names: capsule.config.secrets,
+      tool_count: capsule.config.tools?.length ?? 0,
+      channel_count: capsule.config.channels?.length ?? 0,
+    };
+  } else {
+    context.capsule = {
+      detected: true,
+      root_name: basename(root),
+      load_error: capsule.error,
+    };
+  }
+
+  if (deployState) {
+    context.deploy = {
+      project_id: deployState.project_id,
+      deploy_id: deployState.deploy_id,
+      target: deployState.target,
+      runtime: deployState.runtime,
+      owner_state: deployState.owner_state,
+      access: deployState.access,
+      url: deployState.url,
+      created_at: deployState.created_at,
+    };
+  }
+
+  return redactJson(context) as Record<string, unknown>;
+}
+
+async function detectPackageManager(cwd: string): Promise<string> {
+  const candidates = [
+    ["bun.lock", "bun"],
+    ["bun.lockb", "bun"],
+    ["pnpm-lock.yaml", "pnpm"],
+    ["yarn.lock", "yarn"],
+    ["package-lock.json", "npm"],
+  ] as const;
+
+  for (const [file, name] of candidates) {
+    if (await pathExists(join(cwd, file))) {
+      return name;
+    }
+  }
+
+  return "unknown";
+}
+
+async function writeFeedbackDraft(
+  cwd: string,
+  draft: FeedbackDraft,
+  outFlag: string | boolean | undefined,
+): Promise<{ jsonPath: string; markdownPath: string }> {
+  const out = parseOptionalStringFlag(outFlag, "out", "agentkit feedback create --out <path>");
+  const defaultDir = join(cwd, ".agentkit", "feedback");
+  const slug = slugify(draft.summary);
+  const filename = `${new Date().toISOString().replace(/[:.]/g, "-")}-${slug}`;
+  const jsonPath = out && extname(out) === ".json" ? resolve(cwd, out) : join(out ? resolve(cwd, out) : defaultDir, `${filename}.json`);
+  const markdownPath = jsonPath.replace(/\.json$/, ".md");
+
+  await mkdir(dirname(jsonPath), { recursive: true });
+  await writeFile(jsonPath, `${JSON.stringify(draft, null, 2)}\n`, { mode: 0o600 });
+  await chmod(jsonPath, 0o600);
+  await writeFile(markdownPath, renderFeedbackMarkdown(draft), { mode: 0o600 });
+  await chmod(markdownPath, 0o600);
+
+  return { jsonPath, markdownPath };
+}
+
+async function readFeedbackDraft(path: string): Promise<FeedbackDraft> {
+  const parsed = JSON.parse(await readFile(path, "utf8")) as unknown;
+  const draft = validateFeedbackDraft(parsed);
+
+  if (!draft) {
+    throw new AgentKitError("feedback_draft_invalid", "Feedback draft must be an agentkit.feedback.v1 JSON object.");
+  }
+
+  return redactJson(draft) as FeedbackDraft;
+}
+
+function validateFeedbackDraft(value: unknown): FeedbackDraft | null {
+  if (!isRecord(value) || value.schema_version !== "agentkit.feedback.v1") {
+    return null;
+  }
+
+  if (typeof value.client_report_id !== "string" || !/^[A-Za-z0-9._:-]{1,128}$/.test(value.client_report_id)) {
+    return null;
+  }
+
+  if (!isFeedbackKind(value.kind) || typeof value.summary !== "string" || !isRecord(value.source)) {
+    return null;
+  }
+
+  return {
+    schema_version: "agentkit.feedback.v1",
+    client_report_id: value.client_report_id,
+    kind: value.kind,
+    summary: redactText(value.summary).slice(0, 200),
+    ...(typeof value.message === "string" ? { message: redactText(value.message).slice(0, 5_000) } : {}),
+    source: redactJson(value.source) as Record<string, unknown>,
+    context: isRecord(value.context) ? redactJson(value.context) as Record<string, unknown> : {},
+    diagnostics: isRecord(value.diagnostics) ? redactJson(value.diagnostics) as Record<string, unknown> : {},
+  };
+}
+
+function feedbackDraftToSubmission(draft: FeedbackDraft): Record<string, unknown> {
+  return {
+    kind: draft.kind,
+    summary: draft.summary,
+    ...(draft.message ? { message: draft.message } : {}),
+    source: draft.source,
+    context: draft.context,
+    diagnostics: draft.diagnostics,
+    client_report_id: draft.client_report_id,
+  };
+}
+
+function renderFeedbackMarkdown(draft: FeedbackDraft): string {
+  const lines = [
+    "# AgentKit Feedback Draft",
+    "",
+    `Kind: ${draft.kind}`,
+    `Summary: ${draft.summary}`,
+    `Client report: ${draft.client_report_id}`,
+    "",
+  ];
+
+  if (draft.message) {
+    lines.push("## Message", "", draft.message, "");
+  }
+
+  lines.push("## Context", "", "```json", JSON.stringify(draft.context, null, 2), "```", "");
+  lines.push("Send with the JSON path printed by `agentkit feedback create`:", "", "```sh\nagentkit feedback send <draft.json>\n```", "");
+
+  return `${lines.join("\n")}\n`;
+}
+
+function parseFeedbackKind(value: string | boolean | undefined, fallback: FeedbackKind): FeedbackKind {
+  if (value === undefined || value === false) {
+    return fallback;
+  }
+
+  if (typeof value === "string" && isFeedbackKind(value)) {
+    return value;
+  }
+
+  throw new Error("feedback --kind must be bug, confusion, missing_docs, feature_request, deploy_issue, runtime_issue, or other.");
+}
+
+function parseFeedbackAbout(value: string | boolean | undefined): FeedbackAbout {
+  if (value === undefined || value === false) {
+    return "last-run";
+  }
+
+  if (typeof value === "string" && feedbackAboutValues.has(value as FeedbackAbout)) {
+    return value as FeedbackAbout;
+  }
+
+  throw new Error("feedback --about must be last-run, deploy, or manual.");
+}
+
+function summarizeMessage(message: string | undefined): string | undefined {
+  if (!message) {
+    return undefined;
+  }
+
+  return message.replace(/\s+/g, " ").trim().slice(0, 120);
+}
+
+function isFeedbackKind(value: unknown): value is FeedbackKind {
+  return typeof value === "string" && feedbackKinds.has(value as FeedbackKind);
+}
+
+function redactJson(value: unknown, key = ""): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => redactJson(item, key));
+  }
+
+  if (!isRecord(value)) {
+    return typeof value === "string" ? redactText(value) : value;
+  }
+
+  const out: Record<string, unknown> = {};
+
+  for (const [nestedKey, nestedValue] of Object.entries(value)) {
+    if (shouldRedactKey(nestedKey)) {
+      out[nestedKey] = "[redacted]";
+      continue;
+    }
+
+    out[nestedKey] = redactJson(nestedValue, nestedKey);
+  }
+
+  return out;
+}
+
+function shouldRedactKey(key: string): boolean {
+  return /token|password|credential|api[_-]?key|private[_-]?key/i.test(key) && key !== "client_report_id";
+}
+
+function redactText(value: string): string {
+  return value
+    .replace(/Authorization:\s*Bearer\s+[A-Za-z0-9._:-]+/gi, "Authorization: Bearer [redacted]")
+    .replace(/\b(?:agk_user|agk_deploy|ak_live|bsec|whsec|sk|rk|pk)[-_A-Za-z0-9]{12,}\b/g, "[redacted-token]")
+    .replace(/\b[A-Za-z0-9_-]{24,}\.[A-Za-z0-9_-]{24,}\.[A-Za-z0-9_-]{24,}\b/g, "[redacted-token]");
+}
+
+function slugify(value: string): string {
+  const slug = value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48);
+
+  return slug || "feedback";
+}
+
+async function readAgentKitVersion(): Promise<string> {
+  try {
+    const packageJson = JSON.parse(await readFile(join(moduleDir, "..", "..", "..", "package.json"), "utf8")) as {
+      version?: unknown;
+    };
+    return typeof packageJson.version === "string" ? packageJson.version : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+async function pathExists(path: string): Promise<boolean> {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function relativePath(root: string, path: string): string {
+  const output = relative(root, path);
+  return output.startsWith("..") ? path : output || ".";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/cli/commands/provider.ts

@@ -0,0 +1,47 @@
+import { createInterface } from "node:readline/promises";
+
+import { loginOpenAICodex } from "@earendil-works/pi-ai/oauth";
+
+import { clearCodexLogin, codexLoginStatus, saveCodexLogin } from "../../providers/codex-auth";
+import { AgentKitError } from "../../runtime/errors";
+import type { ParsedArgs } from "../args";
+
+export async function handleProviderCommand(args: ParsedArgs): Promise<void> {
+  const [action, provider] = args.positional;
+  if (provider !== "openai-codex" || args.positional.length !== 2 || Object.keys(args.flags).length ||
+    !["login", "status", "logout"].includes(action)) {
+    throw new Error("Usage: agentkit provider login|status|logout openai-codex");
+  }
+  if (action === "status") {
+    console.log(JSON.stringify(await codexLoginStatus(), null, 2));
+    return;
+  }
+  if (action === "logout") {
+    await clearCodexLogin();
+    console.log("Removed the local AgentKit Codex login. This does not revoke the session at OpenAI.");
+    return;
+  }
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new AgentKitError("provider_auth_interactive_required", "Run agentkit provider login openai-codex in an interactive terminal to sign in with ChatGPT.");
+  }
+  const readline = createInterface({ input: process.stdin, output: process.stdout });
+  const abort = new AbortController();
+  readline.on("SIGINT", () => abort.abort());
+  try {
+    const credentials = await loginOpenAICodex({
+      onAuth({ url, instructions }) {
+        console.log(`Open this URL to sign in with ChatGPT:\n${url}`);
+        if (instructions) console.log(instructions);
+      },
+      onPrompt: ({ message }) => readline.question(`${message} `, { signal: abort.signal }),
+      onManualCodeInput: () => readline.question("After signing in, paste the redirect URL here if the browser callback cannot reach this terminal: ", { signal: abort.signal }),
+    }).catch(() => {
+      throw new AgentKitError("provider_auth_failed", "Codex login failed or was cancelled. Run agentkit provider login openai-codex again.");
+    });
+    await saveCodexLogin(credentials);
+    console.log('Signed in. Set provider: { name: "openai-codex", model: "gpt-5.4" } in agentkit.config.ts. No OPENAI_API_KEY is required.');
+  } finally {
+    abort.abort();
+    readline.close();
+  }
+}

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";
+}