@andreprado/agentkit 0.1.0-alpha.20 → 0.1.0-alpha.22

package/src/cli/index.ts

@@ -109,6 +109,8 @@ async function main() {
     throw new Error("Usage: agentkit help [commands]");
   }
 
+  warnIfUnsupportedNode();
+
   if (args.command === "new") {
     const [name] = args.positional;
     const template = String(args.flags.template ?? "blank");
@@ -136,8 +138,8 @@ async function main() {
       console.log("  npm install");
     }
     console.log("  open this folder in Codex or Claude Code");
-    console.log("  coding agents start at skills/agentkit-capsule/SKILL.md");
-    console.log('  ask: "Develop an appointment and intake agent for an ophthalmology office"');
+    console.log('  ask Codex: "Develop an appointment and intake agent for an ophthalmology office"');
+    console.log("  Codex starts at skills/agentkit-capsule/SKILL.md and treats your request as the brief");
     console.log('  npm run chat -- --message "hello"');
     console.log("  npm run dev");
     console.log("  npm run agentkit -- deploy");
@@ -187,16 +189,25 @@ async function main() {
       throw new Error("Usage: agentkit chat-ui --deploy [--port <number>] [--token-file <path>]");
     }
 
-    const port = parsePort(args.flags.port, "agentkit chat-ui --deploy --port <number>") ?? 4124;
+    const requestedPort = parsePort(args.flags.port, "agentkit chat-ui --deploy --port <number>");
+    const port = requestedPort ?? 4124;
     const tokenFile = parseOptionalStringFlag(
       args.flags["token-file"],
       "token-file",
       "agentkit chat-ui --deploy --token-file <path>",
     );
-    const server = await startDeployChatUiServer(process.cwd(), { port, tokenFile });
+    const server = await startDeployChatUiServer(process.cwd(), {
+      port,
+      tokenFile,
+      autoPort: requestedPort === undefined,
+    });
 
     console.log("AgentKit hosted chat UI running");
     console.log("");
+    if (server.portConflict) {
+      console.log(`Port ${server.portConflict.port} is already used. Started hosted chat UI at ${server.url}.`);
+      console.log("");
+    }
     console.log(`Chat:       ${server.url}`);
     console.log(`Production: ${server.deployUrl}`);
     console.log(`Token:      ${server.tokenSource}`);
@@ -936,14 +947,16 @@ async function main() {
       return;
     }
 
+    let readinessReport: Awaited<ReturnType<typeof checkDeployReadiness>> | null = null;
+
     if (!args.flags["dry-run"] && !args.flags["local-wrangler"]) {
-      const report = await checkDeployReadiness({
+      readinessReport = await checkDeployReadiness({
         apiUrl: await resolveCloudApiUrl(args.flags.api),
         requireLogin: !anonymous,
       });
 
-      if (!report.ok) {
-        printDeployReadinessReport(report);
+      if (!readinessReport.ok) {
+        printDeployReadinessReport(readinessReport);
         throw new AgentKitError(
           "deploy_readiness_failed",
           "Fix deploy readiness failures before running agentkit deploy.",
@@ -1016,6 +1029,14 @@ async function main() {
             : undefined,
       });
     }
+    printDeployProductionHandoff({
+      deployUrl: deploy.deploy.url,
+      statePath,
+      chatAccess,
+      databaseSchemaPath: result.tursoSchemaPath,
+      readinessReport,
+      smokeMessage,
+    });
     return;
   }
 
@@ -1362,7 +1383,7 @@ Rules:
 - Edit the agent contract in agentkit.config.ts.
 - Add TypeScript tools under tools/.
 - Keep the first useful version runnable with test/fake unless the owner has already chosen a real provider.
-- Before testing real conversation behavior, ask the owner to choose OpenRouter, OpenAI, Anthropic, or another supported provider. Do not choose for them.
+- Before testing real conversation behavior, ask the owner to choose OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go, or another supported provider. Do not choose for them.
 - Keep local secrets in .env only.
 - Do not commit or print secret values.
 - Do not edit .agentkit/ directly.
@@ -1402,6 +1423,84 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+function warnIfUnsupportedNode(): void {
+  const major = majorNodeVersion(process.versions.node);
+
+  if (major !== null && major < 24) {
+    console.warn(
+      `Warning: @andreprado/agentkit requires Node >=24; current Node is ${process.versions.node}. Use Node 24+ before relying on local runtime or deploy commands.`,
+    );
+  }
+}
+
+function majorNodeVersion(version: string): number | null {
+  const [major] = version.split(".");
+  const parsed = Number(major);
+  return Number.isInteger(parsed) ? parsed : null;
+}
+
+function printDeployProductionHandoff(input: {
+  deployUrl: string;
+  statePath: string;
+  chatAccess: Awaited<ReturnType<typeof ensureDeployChatAccessToken>>;
+  databaseSchemaPath: string | null;
+  readinessReport: Awaited<ReturnType<typeof checkDeployReadiness>> | null;
+  smokeMessage?: string;
+}): void {
+  const context = input.readinessReport?.context;
+  const userSecrets = context?.userManagedSecrets ?? [];
+  const managedSecrets = context?.agentKitManagedSecrets ?? [];
+  const composio = context?.integrations.managedComposio;
+
+  console.log("");
+  console.log("Production handoff");
+  console.log(`URL:          ${input.deployUrl}`);
+  console.log(`UI:           npm run agentkit -- chat-ui --deploy`);
+  console.log(`State:        ${input.statePath}`);
+  console.log(
+    `Secrets:      ${
+      userSecrets.length > 0
+        ? `user-managed set (${userSecrets.join(", ")})`
+        : "no user-managed hosted secrets required"
+    }${managedSecrets.length > 0 ? `; AgentKit-managed: ${managedSecrets.join(", ")}` : ""}`,
+  );
+  console.log(
+    `Database:     ${
+      input.databaseSchemaPath
+        ? `AgentKit-managed; schema artifact ${input.databaseSchemaPath}`
+        : "AgentKit-managed; no application schema artifact"
+    }`,
+  );
+
+  if (composio?.enabled) {
+    console.log(`Integrations: managed Composio configured for ${composio.toolkits.join(", ")}`);
+    for (const toolkit of composio.toolkits) {
+      console.log(`Connect:      npm run agentkit -- integrations connect composio --toolkit ${toolkit}`);
+    }
+  } else {
+    console.log("Integrations: none configured");
+  }
+
+  if (input.smokeMessage) {
+    console.log(`Smoke:        verified with ${JSON.stringify(input.smokeMessage)}`);
+  } else {
+    console.log('Smoke:        not run; next check: npm run agentkit -- deploy smoke --message "hello"');
+  }
+
+  if (input.chatAccess.status === "ready") {
+    console.log(`Chat token:   ${relativePath(process.cwd(), input.chatAccess.path)}`);
+  } else if (input.chatAccess.status === "skipped") {
+    console.log("Chat token:   not created for anonymous deploy");
+  } else {
+    console.log(`Chat token:   failed; run npm run agentkit -- access token create ${defaultDeployChatAccessTokenName} --out ${defaultDeployChatAccessTokenPath}`);
+  }
+
+  const nextCommand = composio?.enabled && composio.toolkits.length > 0
+    ? `npm run agentkit -- integrations connect composio --toolkit ${composio.toolkits[0]}`
+    : "npm run agentkit -- chat-ui --deploy";
+  console.log(`Next:         ${nextCommand}`);
+}
+
 async function ensureDeployChatAccessToken(options: {
   apiUrl: string;
   root: string;

package/src/index.ts

@@ -1,10 +1,10 @@
 export type AgentRuntime = "local" | "edge";
-export type AgentProviderName = "test" | "openai" | "anthropic" | "openrouter" | "custom";
+export type AgentProviderName = "test" | "openai" | "anthropic" | "openrouter" | "opencode" | "opencode-go" | "custom";
 export type AccessMode = "private" | "token" | "public";
 export type ToolVisibility = "user" | "internal";
-export type ChannelType = "website" | "telegram" | "whatsapp" | "discord" | "slack";
-export type ChannelProvider = "agentkit" | "telegram" | "zapster" | "meta" | "discord" | "slack";
-export type WhatsappChannelProvider = "zapster" | "meta";
+export type ChannelType = "website" | "telegram" | "whatsapp" | "discord" | "slack" | "webhook";
+export type ChannelProvider = "agentkit" | "telegram" | "zapster" | "meta" | "uazapi" | "evolution" | "discord" | "slack" | "generic";
+export type WhatsappChannelProvider = "zapster" | "meta" | "uazapi" | "evolution";
 export type DiscordChannelMode = "interactions" | "bot";
 export type TelegramAllowedUpdate = "message";
 export type ChannelAudioMode = "off" | "reject" | "transcribe";
@@ -180,12 +180,30 @@ export type SlackChannelConfig = {
   audio?: never;
 };
 
+export type GenericWebhookChannelInput = {
+  name: string;
+  secrets?: string[];
+  limits?: ChannelLimits;
+  buffer?: ChannelBufferInput;
+};
+
+export type GenericWebhookChannelConfig = {
+  type: "webhook";
+  provider: "generic";
+  name: string;
+  secrets: string[];
+  limits?: ChannelLimits;
+  buffer?: ChannelBufferConfig;
+  audio?: never;
+};
+
 export type AgentChannel =
   | WebsiteChannelConfig
   | TelegramChannelConfig
   | WhatsappChannelConfig
   | DiscordChannelConfig
-  | SlackChannelConfig;
+  | SlackChannelConfig
+  | GenericWebhookChannelConfig;
 
 export type IntegrationTagsConfig = {
   enable?: string[];
@@ -495,6 +513,17 @@ export function slackChannel(input: SlackChannelInput): SlackChannelConfig {
   };
 }
 
+export function webhookChannel(input: GenericWebhookChannelInput): GenericWebhookChannelConfig {
+  return {
+    type: "webhook",
+    provider: "generic",
+    name: input.name,
+    secrets: normalizeChannelSecrets(input.secrets ?? ["AGENTKIT_WEBHOOK_SECRET"], "generic webhook channel"),
+    ...(input.limits ? { limits: input.limits } : {}),
+    ...(input.buffer ? { buffer: normalizeChannelBuffer(input.buffer, "generic webhook channel") } : {}),
+  };
+}
+
 function defaultDiscordChannelSecrets(mode: DiscordChannelMode): string[] {
   return mode === "bot" ? ["DISCORD_BOT_TOKEN"] : ["DISCORD_PUBLIC_KEY"];
 }
@@ -504,6 +533,14 @@ function defaultWhatsappChannelSecrets(provider: WhatsappChannelProvider): strin
     return ["ZAPSTER_API_KEY", "ZAPSTER_INSTANCE_ID", "ZAPSTER_WEBHOOK_ID"];
   }
 
+  if (provider === "uazapi") {
+    return ["UAZAPI_BASE_URL", "UAZAPI_TOKEN"];
+  }
+
+  if (provider === "evolution") {
+    return ["EVOLUTION_API_BASE_URL", "EVOLUTION_API_KEY", "EVOLUTION_INSTANCE_NAME", "EVOLUTION_WEBHOOK_TOKEN"];
+  }
+
   return ["META_WHATSAPP_ACCESS_TOKEN", "META_WHATSAPP_APP_SECRET", "META_WHATSAPP_VERIFY_TOKEN"];
 }
 

package/src/providers/pi.ts

@@ -17,7 +17,7 @@ import type { AgentProviderName, AgentTool } from "../index";
 import { AgentKitError } from "../runtime/errors";
 import type { ProviderAdapter, ProviderRunInput, ProviderRunResult } from "./types";
 
-const PI_PROVIDER_NAMES = ["openai", "anthropic", "openrouter"] as const satisfies AgentProviderName[];
+const PI_PROVIDER_NAMES = ["openai", "anthropic", "openrouter", "opencode", "opencode-go"] as const satisfies AgentProviderName[];
 const MAX_TOOL_TURNS = 8;
 const OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1";
 const UNKNOWN_OPENROUTER_CONTEXT_WINDOW = 128000;
@@ -159,7 +159,13 @@ async function runPiTurn(
 }
 
 function toPiProvider(provider: string): Provider {
-  if (provider === "openai" || provider === "anthropic" || provider === "openrouter") {
+  if (
+    provider === "openai" ||
+    provider === "anthropic" ||
+    provider === "openrouter" ||
+    provider === "opencode" ||
+    provider === "opencode-go"
+  ) {
     return provider;
   }
 
@@ -181,6 +187,10 @@ function requireProviderApiKey(provider: Provider, env: Record<string, string |
 }
 
 function defaultProviderSecretNames(provider: Provider): string[] {
+  if (provider === "opencode" || provider === "opencode-go") {
+    return ["OPENCODE_API_KEY"];
+  }
+
   return [`${provider.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_API_KEY`];
 }
 

package/src/runtime/channel-test-harness.ts

@@ -15,11 +15,24 @@ export type ChannelFixtureName =
   | "zapster-audio-message"
   | "zapster-duplicate-message"
   | "zapster-unsupported-media"
+  | "uazapi-message"
+  | "uazapi-audio-message"
+  | "uazapi-duplicate-message"
+  | "uazapi-unsupported-media"
+  | "uazapi-was-sent-by-api"
+  | "evolution-message"
+  | "evolution-audio-message"
+  | "evolution-captioned-media"
+  | "evolution-duplicate-message"
+  | "evolution-from-me"
+  | "evolution-unsupported-media"
   | "discord-command"
   | "discord-message-create"
   | "discord-ping"
   | "slack-app-mention"
-  | "slack-direct-message";
+  | "slack-direct-message"
+  | "generic-webhook-message"
+  | "generic-webhook-duplicate";
 
 export type ChannelFixture = {
   name: ChannelFixtureName;

package/src/runtime/channels/generic-webhook.ts

@@ -0,0 +1,225 @@
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+
+import type { ChannelAdapter, ChannelSendInput, RawWebhookEvent } from "../channels";
+import { AgentKitError } from "../errors";
+
+const DEFAULT_SECRET_NAME = "AGENTKIT_WEBHOOK_SECRET";
+
+export const genericWebhookChannelAdapter: ChannelAdapter = {
+  type: "webhook",
+  provider: "generic",
+  requiredSecrets: [DEFAULT_SECRET_NAME],
+  verifyWebhook(input) {
+    const expected = input.secrets[DEFAULT_SECRET_NAME];
+
+    if (!expected) {
+      return {
+        ok: false,
+        code: "channel_secret_missing",
+        message: `Secret ${DEFAULT_SECRET_NAME} is not set for this channel.`,
+      };
+    }
+
+    const signature = input.headers.get("x-agentkit-webhook-signature") ?? input.headers.get("x-agentkit-signature");
+
+    if (signature) {
+      const expectedSignature = `sha256=${createHmac("sha256", expected).update(input.rawBody).digest("hex")}`;
+
+      if (constantTimeEqual(signature.trim(), expectedSignature)) {
+        return { ok: true };
+      }
+
+      return {
+        ok: false,
+        code: "channel_signature_invalid",
+        message: "Generic webhook HMAC signature did not match.",
+      };
+    }
+
+    const bearer = readBearerToken(input.headers.get("authorization"));
+    const headerToken =
+      input.headers.get("x-agentkit-webhook-secret") ??
+      input.headers.get("x-agentkit-channel-token") ??
+      input.headers.get("x-agentkit-webhook-token");
+
+    if (constantTimeEqual(bearer, expected) || constantTimeEqual(headerToken ?? "", expected)) {
+      return { ok: true };
+    }
+
+    return {
+      ok: false,
+      code: "channel_signature_invalid",
+      message: "Generic webhook token did not match.",
+    };
+  },
+  normalizeInbound(input) {
+    const body = parseJsonObject(input);
+    const eventId = readFirstScalar(body, ["event_id", "eventId", "id"]) ?? readNestedMessageId(body);
+
+    if (!eventId) {
+      throw new AgentKitError("channel_payload_invalid", "Generic webhook payload is missing event_id.");
+    }
+
+    const text = readMessageText(body);
+    const identitySource =
+      readFirstScalar(body, [
+        "external_id",
+        "externalId",
+        "user_id",
+        "userId",
+        "contact_id",
+        "contactId",
+        "conversation_id",
+        "conversationId",
+        "client_id",
+        "clientId",
+        "visitor_id",
+        "visitorId",
+        "source_id",
+        "sourceId",
+      ]) ?? `event:${eventId}`;
+    const identityKey = `webhook:generic:identity:${sha256(identitySource).slice(0, 32)}`;
+    const base = {
+      type: "webhook" as const,
+      provider: "generic" as const,
+      providerEventId: eventId,
+      dedupeKey: `webhook:generic:${input.channelId}:${eventId}`,
+      externalIdentity: {
+        key: identityKey,
+        redactedDisplay: identityKey,
+      },
+      receivedAt: input.receivedAt,
+    };
+
+    if (!text) {
+      return [
+        {
+          ...base,
+          kind: "unsupported" as const,
+          unsupportedReason: "unsupported_message_type:missing_text",
+        },
+      ];
+    }
+
+    return [
+      {
+        ...base,
+        kind: "message" as const,
+        message: {
+          role: "user" as const,
+          contentType: "text" as const,
+          content: text,
+          providerMessageId: readNestedMessageId(body) ?? eventId,
+        },
+      },
+    ];
+  },
+  async sendMessage(input) {
+    return {
+      ok: true,
+      status: "stubbed",
+      providerRequestId: buildGenericWebhookProviderRequestId(input),
+    };
+  },
+  getStatus() {
+    return {
+      status: "connected",
+      checkedAt: new Date().toISOString(),
+      providerMetadata: {
+        outbound: "stubbed",
+      },
+    };
+  },
+};
+
+function buildGenericWebhookProviderRequestId(input: ChannelSendInput): string {
+  return `webhook:generic:${input.channelId}:${input.conversationId}`;
+}
+
+function parseJsonObject(input: RawWebhookEvent): Record<string, unknown> {
+  const contentType = input.headers.get("content-type") ?? "";
+
+  if (contentType && !contentType.toLowerCase().includes("application/json")) {
+    throw new AgentKitError("channel_payload_invalid", "Generic webhook payload must use content-type application/json.");
+  }
+
+  try {
+    const parsed = JSON.parse(input.rawBody) as unknown;
+
+    if (isRecord(parsed)) {
+      return parsed;
+    }
+  } catch (error) {
+    throw new AgentKitError("channel_payload_invalid", "Generic webhook payload must be valid JSON.", {
+      cause: error,
+    });
+  }
+
+  throw new AgentKitError("channel_payload_invalid", "Generic webhook payload must be a JSON object.");
+}
+
+function readMessageText(body: Record<string, unknown>): string | undefined {
+  const message = body.message;
+
+  if (typeof message === "string") {
+    return normalizeNonEmpty(message);
+  }
+
+  if (isRecord(message)) {
+    return readFirstScalar(message, ["text", "content", "body"]);
+  }
+
+  return readFirstScalar(body, ["text", "content", "prompt", "input"]);
+}
+
+function readNestedMessageId(body: Record<string, unknown>): string | undefined {
+  const message = body.message;
+  return isRecord(message) ? readFirstScalar(message, ["id", "message_id", "messageId"]) : undefined;
+}
+
+function readFirstScalar(value: Record<string, unknown>, keys: string[]): string | undefined {
+  for (const key of keys) {
+    const field = value[key];
+
+    if (typeof field === "string") {
+      const normalized = normalizeNonEmpty(field);
+
+      if (normalized) {
+        return normalized;
+      }
+    }
+
+    if (typeof field === "number" && Number.isFinite(field)) {
+      return String(field);
+    }
+  }
+
+  return undefined;
+}
+
+function normalizeNonEmpty(value: string): string | undefined {
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function readBearerToken(value: string | null): string {
+  if (!value?.startsWith("Bearer ")) {
+    return "";
+  }
+
+  return value.slice("Bearer ".length).trim();
+}
+
+function constantTimeEqual(left: string, right: string): boolean {
+  const leftDigest = createHash("sha256").update(left).digest();
+  const rightDigest = createHash("sha256").update(right).digest();
+  return timingSafeEqual(leftDigest, rightDigest) && left === right;
+}
+
+function sha256(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}