@andreprado/agentkit 0.1.0-alpha.7 → 0.1.0-alpha.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andreprado/agentkit",
-  "version": "0.1.0-alpha.7",
+  "version": "0.1.0-alpha.9",
   "private": false,
   "type": "module",
   "repository": {

package/src/cli/commands/channels.ts

@@ -2,10 +2,11 @@ import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 
 import type { ParsedArgs } from "../args";
-import { cloudFetch, cloudGet, cloudPost } from "../cloud-client";
+import { cloudFetch, cloudGet, cloudPost, readCloudError } from "../cloud-client";
 import { parseCloudApiUrl } from "../flags";
 import { loadAgentCapsule } from "../../runtime/config";
 import { readLocalDeployStateIfExists, type LocalDeployState } from "../../runtime/core/deploy-state";
+import { loadCapsuleEnv } from "../../runtime/env";
 import type { AgentChannel } from "../../index";
 
 type DeployState = LocalDeployState;
@@ -30,9 +31,51 @@ type CloudDelivery = {
     event_id?: string;
   };
   received_at: string;
+  updated_at?: string;
+  error?: {
+    code: string;
+    message: string;
+  };
+  events?: Array<{
+    state: string;
+    message: string;
+    created_at: string;
+  }>;
+};
+
+type ChannelSetupResponse = {
+  channel: CloudChannel;
+  setup?: {
+    provider: "telegram";
+    webhook_url: string;
+    status: "configured";
+    bot_username?: string;
+    get_webhook_info?: {
+      url: string;
+      pending_update_count: number;
+    };
+  };
+};
+
+type ChannelDoctorReport = {
+  channel: CloudChannel;
+  checks: Array<{
+    name: string;
+    status: "ok" | "warn" | "fail" | "unknown";
+    message: string;
+    fix?: string;
+  }>;
+  last_delivery: {
+    inbound: CloudDelivery | null;
+    outbound: CloudDelivery | null;
+  };
+  probable_error: string | null;
+  suggested_fix: string | null;
 };
 
 export async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
+  await loadLocalEnvIntoProcess(process.cwd());
+
   const [subcommand, first, second] = args.positional;
 
   if (subcommand === "list") {
@@ -70,23 +113,55 @@ export async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
       throw new Error("Usage: agentkit channels add <website|telegram|whatsapp> <name> [--provider zapster|meta]");
     }
 
-    const deployState = await readDeployStateRequired(process.cwd());
-    const provider = channelProviderForCli(type, args.flags.provider);
-    const localChannel = await readLocalChannelConfig(process.cwd(), type, provider, name);
-    const payload = {
-      name,
-      type,
-      provider,
-      secrets: localChannel?.secrets ?? defaultChannelSecretsForCli(type, provider),
-      ...(localChannel?.limits ? { limits: channelLimitsForApi(localChannel.limits) } : {}),
-      ...(localChannel?.buffer ? { buffer: localChannel.buffer } : {}),
-    };
-    const response = await cloudPost<{ channel: CloudChannel }>(
-      parseCloudApiUrl(args.flags.api),
-      `/v1/deploys/${encodeURIComponent(deployState.deploy_id)}/channels`,
-      payload,
-    );
+    const response = await createHostedChannel(type, name, args.flags.provider, args.flags.api);
     printChannelStatus(response.channel);
+    printSecretRepairHint(response.channel);
+    return;
+  }
+
+  if (subcommand === "connect") {
+    const type = first;
+    const name = second;
+
+    if (!type || !name || (type !== "website" && type !== "telegram" && type !== "whatsapp")) {
+      throw new Error("Usage: agentkit channels connect <website|telegram|whatsapp> <name> [--provider zapster|meta]");
+    }
+
+    const created = await createHostedChannel(type, name, args.flags.provider, args.flags.api);
+    let channel = created.channel;
+    printChannelStatus(channel);
+    printSecretRepairHint(channel);
+
+    if (hasMissingRequiredSecrets(channel)) {
+      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");
+      process.exitCode = 1;
+      return;
+    }
+
+    if (channel.type === "telegram") {
+      const setup = await applyTelegramWebhook(channel, args.flags.api);
+      channel = setup.channel ?? channel;
+      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})` : ""}`);
+      printTelegramHumanNextStep(channel.name, setup.setup?.bot_username);
+      return;
+    }
+
+    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})` : ""}`);
+      console.log(`Next human step: use ${channel.webhook_url} from your website client.`);
+    }
     return;
   }
 
@@ -99,8 +174,10 @@ export async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
     printChannelStatus(channel);
     if (channel.type === "telegram") {
       if (args.flags.apply) {
-        await applyTelegramWebhook(channel, args.flags.api);
-        console.log("Telegram webhook updated.");
+        const setup = await applyTelegramWebhook(channel, args.flags.api);
+        console.log("Telegram webhook confirmed.");
+        printChannelStatus(setup.channel ?? channel);
+        printTelegramHumanNextStep(channel.name, setup.setup?.bot_username);
       } else {
         console.log(`Setup: call Telegram setWebhook with ${channel.webhook_url}`);
         console.log("Use --apply to mutate Telegram webhook settings.");
@@ -125,6 +202,24 @@ export async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
     return;
   }
 
+  if (subcommand === "doctor") {
+    if (!first) {
+      throw new Error("Usage: agentkit channels doctor <name>");
+    }
+
+    const channel = await resolveCloudChannelByName(first, args.flags.api);
+    const report = await cloudGet<{ doctor: ChannelDoctorReport }>(
+      parseCloudApiUrl(args.flags.api),
+      `/v1/channels/${encodeURIComponent(channel.id)}/doctor`,
+    );
+    printChannelDoctor(report.doctor);
+
+    if (report.doctor.checks.some((check) => check.status === "fail")) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
   if (subcommand === "test") {
     if (!first) {
       throw new Error('Usage: agentkit channels test <name> [--message "hello"] [--fixture <path>]');
@@ -133,14 +228,9 @@ export async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
     const channel = await resolveCloudChannelByName(first, args.flags.api);
     const apiUrl = parseCloudApiUrl(args.flags.api);
     const body = await channelTestBody(channel, args.flags.message, args.flags.fixture);
-    const path = new URL(channel.webhook_url).pathname;
-    const headers = channelTestHeaders(channel);
-    const response = await cloudFetch(apiUrl, path, {
-      method: channel.type === "whatsapp" && channel.provider === "meta" ? "POST" : "POST",
-      headers,
-      body,
-    });
-    const payload = await response.json();
+    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) {
@@ -197,21 +287,113 @@ export async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
   }
 
   throw new Error(
-    "Usage: agentkit channels list | add | setup | status | test | deliveries list | deliveries show",
+    "Usage: agentkit channels list | add | connect | setup | status | doctor | test | deliveries list | deliveries show",
+  );
+}
+
+async function createHostedChannel(
+  type: "website" | "telegram" | "whatsapp",
+  name: string,
+  providerFlag: string | boolean | undefined,
+  apiFlag: string | boolean | undefined,
+): Promise<{ channel: CloudChannel }> {
+  const deployState = await readDeployStateRequired(process.cwd());
+  const provider = channelProviderForCli(type, providerFlag);
+  const localChannel = await readLocalChannelConfig(process.cwd(), type, provider, name);
+  const payload = {
+    name,
+    type,
+    provider,
+    secrets: localChannel?.secrets ?? defaultChannelSecretsForCli(type, provider),
+    ...(localChannel?.limits ? { limits: channelLimitsForApi(localChannel.limits) } : {}),
+    ...(localChannel?.buffer ? { buffer: localChannel.buffer } : {}),
+  };
+
+  return cloudPost<{ channel: CloudChannel }>(
+    parseCloudApiUrl(apiFlag),
+    `/v1/deploys/${encodeURIComponent(deployState.deploy_id)}/channels`,
+    payload,
+  );
+}
+
+async function runChannelSmoke(
+  channel: CloudChannel,
+  apiFlag: string | boolean | undefined,
+  messageFlag: string | boolean | undefined,
+): Promise<{ status: string; delivery_id?: string }> {
+  const body = await channelTestBody(channel, messageFlag, undefined);
+  const { response, payload } = await runServerSignedChannelTest(channel, parseCloudApiUrl(apiFlag), body);
+
+  if (!response.ok) {
+    throw new Error(readCloudError(payload, response.status));
+  }
+
+  if (isRecord(payload) && typeof payload.status === "string") {
+    return {
+      status: payload.status,
+      ...(typeof payload.delivery_id === "string" ? { delivery_id: payload.delivery_id } : {}),
+    };
+  }
+
+  return { status: "unknown" };
+}
+
+async function runServerSignedChannelTest(
+  channel: CloudChannel,
+  apiUrl: string,
+  rawBody: string,
+): Promise<{ response: Response; payload: unknown }> {
+  const response = await cloudFetch(apiUrl, `/v1/channels/${encodeURIComponent(channel.id)}/test`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ raw_body: rawBody }),
+  });
+  const payload = await response.json().catch(() => null);
+
+  if (!response.ok && isUnsupportedChannelTestRoute(payload)) {
+    return runLocallySignedChannelTest(channel, apiUrl, rawBody);
+  }
+
+  return { response, payload };
+}
+
+async function runLocallySignedChannelTest(
+  channel: CloudChannel,
+  apiUrl: string,
+  rawBody: string,
+): Promise<{ response: Response; payload: unknown }> {
+  const path = new URL(channel.webhook_url).pathname;
+  const headers = channelTestHeaders(channel);
+  const response = await cloudFetch(apiUrl, path, {
+    method: "POST",
+    headers,
+    body: rawBody,
+  });
+  const payload = await response.json().catch(() => null);
+
+  return { response, payload };
+}
+
+function isUnsupportedChannelTestRoute(payload: unknown): boolean {
+  return (
+    isRecord(payload) &&
+    isRecord(payload.error) &&
+    (payload.error.code === "not_found" ||
+      payload.error.code === "channel_store_not_configured" ||
+      payload.error.code === "channel_delivery_not_found")
   );
 }
 
 async function applyTelegramWebhook(
   channel: CloudChannel,
   apiFlag: string | boolean | undefined,
-): Promise<void> {
+): Promise<ChannelSetupResponse> {
   try {
-    await cloudPost(
+    return await cloudPost<ChannelSetupResponse>(
       parseCloudApiUrl(apiFlag),
       `/v1/channels/${encodeURIComponent(channel.id)}/setup`,
       {},
     );
-    return;
   } catch (error) {
     if (!shouldFallbackToLocalTelegramSetup(error)) {
       throw error;
@@ -226,9 +408,10 @@ async function applyTelegramWebhook(
   }
 
   let response: Response;
+  const apiBaseUrl = telegramApiBaseUrlFromEnv();
 
   try {
-    response = await fetch(`https://api.telegram.org/bot${botToken}/setWebhook`, {
+    response = await fetch(new URL(`/bot${botToken}/setWebhook`, apiBaseUrl).href, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
@@ -246,6 +429,40 @@ async function applyTelegramWebhook(
   if (!response.ok || !isTelegramOk(payload)) {
     throw new Error(readTelegramSetupError(payload, response.status));
   }
+
+  const webhookInfo = await fetch(new URL(`/bot${botToken}/getWebhookInfo`, apiBaseUrl).href)
+    .then((telegramResponse) => telegramResponse.json())
+    .catch(() => null);
+  const webhookUrl =
+    webhookInfo &&
+    typeof webhookInfo === "object" &&
+    "result" in webhookInfo &&
+    webhookInfo.result &&
+    typeof webhookInfo.result === "object" &&
+    "url" in webhookInfo.result &&
+    typeof webhookInfo.result.url === "string"
+      ? webhookInfo.result.url
+      : "";
+
+  if (webhookUrl !== channel.webhook_url) {
+    throw new Error(`Telegram getWebhookInfo returned ${webhookUrl || "no webhook URL"} instead of ${channel.webhook_url}.`);
+  }
+
+  return {
+    channel: {
+      ...channel,
+      status: "connected",
+    },
+    setup: {
+      provider: "telegram",
+      webhook_url: channel.webhook_url,
+      status: "configured",
+      get_webhook_info: {
+        url: webhookUrl,
+        pending_update_count: 0,
+      },
+    },
+  };
 }
 
 function shouldFallbackToLocalTelegramSetup(error: unknown): boolean {
@@ -270,6 +487,33 @@ function readTelegramSetupError(payload: unknown, status: number): string {
   return `Telegram setWebhook failed with HTTP ${status}.`;
 }
 
+function telegramApiBaseUrlFromEnv(): string {
+  return process.env.AGENTKIT_TELEGRAM_API_BASE_URL ?? "https://api.telegram.org";
+}
+
+async function loadLocalEnvIntoProcess(cwd: string): Promise<void> {
+  const env = await loadCapsuleEnv(cwd, process.env);
+
+  for (const [key, value] of Object.entries(env)) {
+    if (value !== undefined && process.env[key] === undefined) {
+      process.env[key] = value;
+    }
+  }
+}
+
+function printTelegramHumanNextStep(channelName: string, botUsername: string | undefined): void {
+  console.log("");
+  console.log("Next human step:");
+  console.log(`  Open ${botUsername ? `@${botUsername}` : "your Telegram bot"} in Telegram`);
+  console.log("  Send /start");
+  console.log('  Send "hello"');
+  console.log(`  Then run: npm run agentkit -- channels deliveries list ${channelName}`);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
 async function readDeployStateIfExists(cwd: string): Promise<DeployState | null> {
   return readLocalDeployStateIfExists(cwd);
 }
@@ -308,8 +552,14 @@ function printChannelStatus(channel: CloudChannel): void {
     console.log(`Webhook URL: ${channel.webhook_url}`);
   }
   console.log("Required secrets:");
-  for (const secret of channel.required_secrets) {
-    console.log(`  ${secret.name}: ${secret.status}`);
+  if (channel.required_secrets.length === 0 && defaultChannelSecretsForCli(channel.type, channel.provider).length > 0) {
+    console.log(
+      `  control-plane channel metadata bug: required_secrets is empty for ${channel.type}/${channel.provider}`,
+    );
+  } else {
+    for (const secret of channel.required_secrets) {
+      console.log(`  ${secret.name}: ${secret.status}`);
+    }
   }
   if (channel.buffer) {
     if (channel.buffer.mode === "off") {
@@ -322,6 +572,26 @@ function printChannelStatus(channel: CloudChannel): void {
   }
 }
 
+function printSecretRepairHint(channel: CloudChannel): void {
+  if (channel.required_secrets.length > 0 || defaultChannelSecretsForCli(channel.type, channel.provider).length === 0) {
+    return;
+  }
+
+  console.log(
+    "Hint: control-plane channel metadata bug. Rerun add/connect against the updated control-plane to repair required_secrets.",
+  );
+}
+
+function hasMissingRequiredSecrets(channel: CloudChannel): boolean {
+  const expected = defaultChannelSecretsForCli(channel.type, channel.provider);
+
+  if (channel.required_secrets.length === 0 && expected.length > 0) {
+    return true;
+  }
+
+  return channel.required_secrets.some((secret) => secret.status !== "set");
+}
+
 async function printChannelDeliverySummary(
   channel: CloudChannel,
   apiFlag: string | boolean | undefined,
@@ -339,6 +609,51 @@ async function printChannelDeliverySummary(
   console.log("Provider health: not_checked");
 }
 
+function printChannelDoctor(report: ChannelDoctorReport): void {
+  console.log(`Channel doctor: ${report.channel.name}`);
+  console.log("");
+  console.log("Checks:");
+  for (const check of report.checks) {
+    console.log(`  ${formatCheckStatus(check.status)} ${check.name}: ${check.message}`);
+    if (check.fix) {
+      console.log(`    Fix: ${check.fix}`);
+    }
+  }
+
+  console.log("");
+  console.log("Last delivery:");
+  console.log(
+    `  Inbound: ${report.last_delivery.inbound ? `${report.last_delivery.inbound.status} ${report.last_delivery.inbound.updated_at ?? report.last_delivery.inbound.received_at}` : "none"}`,
+  );
+  console.log(
+    `  Outbound: ${report.last_delivery.outbound ? `${report.last_delivery.outbound.status} ${report.last_delivery.outbound.updated_at ?? report.last_delivery.outbound.received_at}` : "none"}`,
+  );
+
+  if (report.probable_error) {
+    console.log("");
+    console.log(`Probable error: ${report.probable_error}`);
+  }
+  if (report.suggested_fix) {
+    console.log(`Suggested fix: ${report.suggested_fix}`);
+  }
+}
+
+function formatCheckStatus(status: ChannelDoctorReport["checks"][number]["status"]): string {
+  if (status === "ok") {
+    return "OK";
+  }
+
+  if (status === "warn") {
+    return "WARN";
+  }
+
+  if (status === "fail") {
+    return "FAIL";
+  }
+
+  return "UNKNOWN";
+}
+
 async function resolveCloudChannelByName(name: string, apiFlag: string | boolean | undefined): Promise<CloudChannel> {
   const deployState = await readDeployStateRequired(process.cwd());
   const response = await cloudGet<{ channels: CloudChannel[] }>(

package/src/cli/help.ts

@@ -77,8 +77,10 @@ Usage:
   agentkit conversations trace <conversation-id>
   agentkit channels list
   agentkit channels add <website|telegram|whatsapp> <name> [--provider zapster|meta] [--api <url>]
+  agentkit channels connect <website|telegram|whatsapp> <name> [--provider zapster|meta] [--api <url>]
   agentkit channels setup <name> [--apply] [--api <url>]
   agentkit channels status <name> [--api <url>]
+  agentkit channels doctor <name> [--api <url>]
   agentkit channels test <name> [--message <text>] [--fixture <path>] [--api <url>]
   agentkit channels deliveries list <name> [--api <url>]
   agentkit channels deliveries show <delivery-id> [--api <url>]

package/src/runtime/channels/telegram.ts

@@ -112,18 +112,7 @@ export const telegramChannelAdapter: ChannelAdapter = {
     ];
   },
   async sendMessage(input) {
-    const request = buildTelegramSendMessageRequest(input);
-
-    return {
-      ok: true,
-      status: "sent",
-      providerRequestId: request.idempotencyKey,
-      providerMetadata: {
-        method: request.method,
-        url: request.url,
-        body: request.body,
-      },
-    };
+    return sendTelegramMessage(input);
   },
   getStatus(input) {
     if (!input.secrets.TELEGRAM_BOT_TOKEN) {
@@ -152,7 +141,130 @@ export type TelegramSendMessageRequest = {
   idempotencyKey: string;
 };
 
+type TelegramFetch = (url: string, init: RequestInit) => Promise<Response>;
+
 export function buildTelegramSendMessageRequest(input: ChannelSendInput): TelegramSendMessageRequest {
+  return buildTelegramSendMessageRequestInternal(input, "<redacted>");
+}
+
+export async function sendTelegramMessage(
+  input: ChannelSendInput,
+  fetcher: TelegramFetch = fetch,
+): Promise<Awaited<ReturnType<ChannelAdapter["sendMessage"]>>> {
+  if (input.secrets.AGENTKIT_CHANNEL_SEND_DRY_RUN === "1") {
+    const request = buildTelegramSendMessageRequest(input);
+
+    return {
+      ok: true,
+      status: "sent",
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: {
+        method: request.method,
+        url: request.url,
+        body: request.body,
+      },
+    };
+  }
+
+  const token = input.secrets.TELEGRAM_BOT_TOKEN;
+
+  if (!token) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_secret_missing",
+      message: "Secret TELEGRAM_BOT_TOKEN is not set for this channel.",
+    };
+  }
+
+  let request: TelegramSendMessageRequest;
+  let actualRequest: TelegramSendMessageRequest;
+
+  try {
+    request = buildTelegramSendMessageRequest(input);
+    actualRequest = buildTelegramSendMessageRequestInternal(input, token);
+  } catch (error) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_send_failed",
+      message: error instanceof Error ? error.message : String(error),
+    };
+  }
+
+  let response: Response;
+
+  try {
+    response = await fetcher(actualRequest.url, {
+      method: actualRequest.method,
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(actualRequest.body),
+    });
+  } catch (error) {
+    const errorMessage = (error instanceof Error ? error.message : String(error)).replace(token, "<redacted>");
+
+    return {
+      ok: false,
+      retryable: true,
+      code: "channel_provider_unavailable",
+      message: `Telegram sendMessage request failed before a response: ${errorMessage}`,
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: {
+        method: request.method,
+        url: request.url,
+        body: request.body,
+      },
+    };
+  }
+
+  const payload = await response.json().catch(() => null);
+
+  if (!response.ok || !isRecord(payload) || payload.ok !== true) {
+    const description =
+      isRecord(payload) && typeof payload.description === "string"
+        ? payload.description
+        : `Telegram sendMessage returned HTTP ${response.status}.`;
+    const syntheticExpectedFailure = isSyntheticTelegramChatId(request.body.chat_id) && /chat not found/i.test(description);
+
+    return {
+      ok: false,
+      retryable: syntheticExpectedFailure ? false : response.status === 429 || response.status >= 500,
+      code: syntheticExpectedFailure ? "synthetic_expected_failure" : "channel_send_failed",
+      message: syntheticExpectedFailure
+        ? "Synthetic Telegram smoke reached AgentKit. Telegram correctly rejected the fake chat ID."
+        : description,
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: {
+        method: request.method,
+        url: request.url,
+        body: request.body,
+      },
+    };
+  }
+
+  const result = isRecord(payload.result) ? payload.result : undefined;
+  const messageId = readNumberishString(result ?? {}, "message_id");
+
+  return {
+    ok: true,
+    status: "sent",
+    providerRequestId: request.idempotencyKey,
+    ...(messageId ? { providerMessageId: messageId } : {}),
+    providerMetadata: {
+      method: request.method,
+      url: request.url,
+      body: request.body,
+    },
+  };
+}
+
+function isSyntheticTelegramChatId(chatId: string): boolean {
+  return chatId === "456" || chatId.startsWith("agentkit-synthetic-");
+}
+
+function buildTelegramSendMessageRequestInternal(input: ChannelSendInput, token: string): TelegramSendMessageRequest {
   const chatId = input.externalIdentity.key.match(/:chat:([^:]+)$/)?.[1];
 
   if (!chatId) {
@@ -161,7 +273,7 @@ export function buildTelegramSendMessageRequest(input: ChannelSendInput): Telegr
 
   return {
     method: "POST",
-    url: "https://api.telegram.org/bot<redacted>/sendMessage",
+    url: `https://api.telegram.org/bot${token}/sendMessage`,
     body: {
       chat_id: chatId,
       text: input.message.content,

package/src/runtime/channels.ts

@@ -5,12 +5,17 @@ export type ChannelMessageContentType = "text";
 export type ChannelEventKind = "message" | "delivery_status" | "unsupported";
 export type ChannelDeliveryDirection = "inbound" | "outbound";
 export type ChannelDeliveryState =
+  | "webhook_received"
   | "received"
   | "validated"
   | "duplicate"
   | "buffered"
   | "queued"
   | "running"
+  | "agent_completed"
+  | "outbound_sent"
+  | "provider_failed"
+  | "synthetic_expected_failure"
   | "sent"
   | "delivered"
   | "failed"
@@ -90,7 +95,7 @@ export type ChannelSendResult =
   | {
       ok: false;
       retryable: boolean;
-      code: "channel_secret_missing" | "channel_provider_unavailable" | "channel_send_failed";
+      code: "channel_secret_missing" | "channel_provider_unavailable" | "channel_send_failed" | "synthetic_expected_failure";
       message: string;
       providerRequestId?: string;
       providerMetadata?: Record<string, unknown>;

package/src/templates/skills/agentkit-channels/SKILL.md

@@ -12,9 +12,9 @@ Channels receive user messages. Tools let the agent call external systems. Keep
 1. Add channel helpers in `agentkit.config.ts`.
 2. Keep `runtime: "edge"` and `storage.driver: "agentkit"`.
 3. Deploy before hosted channel creation.
-4. Add channel resources through the CLI.
-5. Configure provider secrets as managed secrets.
-6. Test and inspect delivery logs.
+4. Configure provider secrets as managed secrets.
+5. Connect channel resources through the CLI.
+6. Test, doctor, and inspect delivery logs.
 
 ## Buffering
 
@@ -43,9 +43,9 @@ npm run agentkit -- inspect
 npm run agentkit -- deploy
 npm run agentkit -- channels list
 npm run agentkit -- channels add website website-chat
-npm run agentkit -- channels add telegram support-telegram
+npm run agentkit -- channels connect telegram support-telegram
 npm run agentkit -- channels add whatsapp support-whatsapp --provider zapster
-npm run agentkit -- channels setup support-telegram
+npm run agentkit -- channels doctor support-telegram
 npm run agentkit -- channels test support-telegram --message "hello"
 npm run agentkit -- channels deliveries list support-telegram
 ```

package/src/templates/skills/agentkit-channels/references/channel-buffering.md

@@ -53,6 +53,6 @@ Expected delivery states:
 buffered
 queued
 running
-sent
+agent_completed
+outbound_sent
 ```
-

package/src/templates/skills/agentkit-channels/references/channel-debugging.md

@@ -5,6 +5,7 @@ Start with:
 ```sh
 agentkit channels list
 agentkit channels status <name>
+agentkit channels doctor <name>
 agentkit channels test <name> --message "hello"
 agentkit channels deliveries list <name> --since 24h
 agentkit channels deliveries show <delivery-id>
@@ -13,15 +14,17 @@ agentkit channels deliveries show <delivery-id>
 Common states:
 
 ```txt
-received
+webhook_received
 validated
 duplicate
 buffered
 queued
 running
-sent
+agent_completed
+outbound_sent
 delivered
-failed
+provider_failed
+synthetic_expected_failure
 dead_lettered
 skipped
 ```
@@ -34,4 +37,5 @@ Common errors:
 - `channel_payload_invalid`: malformed or unsupported provider payload.
 - `channel_event_duplicate`: provider retry; do not create a second run.
 - `channel_limit_exceeded`: backpressure skipped the message.
+- `synthetic_expected_failure`: a synthetic test reached AgentKit, but the provider correctly rejected a fake test recipient.
 - `buffered` delivery state: message is waiting for the channel quiet window or max wait before one coalesced agent run is queued.

package/src/templates/skills/agentkit-channels/references/telegram.md

@@ -11,15 +11,16 @@ Commands:
 
 ```sh
 agentkit deploy
-agentkit channels add telegram support-telegram
-agentkit channels setup support-telegram
-agentkit channels setup support-telegram --apply
+agentkit secret set TELEGRAM_BOT_TOKEN --stdin
+agentkit secret set TELEGRAM_WEBHOOK_SECRET --stdin
+agentkit channels connect telegram support-telegram
+agentkit channels doctor support-telegram
 agentkit channels status support-telegram
 agentkit channels test support-telegram --message "hello"
 agentkit channels deliveries list support-telegram
 ```
 
-`setup --apply` calls Telegram `setWebhook`. Use it only when real Telegram secrets are present.
+`connect` creates or reuses the hosted channel, validates managed secrets, calls Telegram `setWebhook`, confirms `getWebhookInfo`, runs a synthetic smoke, and prints the human Telegram steps. Use `setup --apply` only when you need to repeat webhook registration without running smoke.
 
 Buffer rapid Telegram messages: