@andreprado/agentkit 0.1.0-alpha.10

package/src/runtime/channels/whatsapp-zapster.ts

@@ -0,0 +1,278 @@
+import type {
+  ChannelAdapter,
+  ChannelSendInput,
+  RawWebhookEvent,
+  WebhookVerificationInput,
+  WebhookVerificationResult,
+} from "../channels";
+import { AgentKitError } from "../errors";
+
+export const zapsterWhatsappChannelAdapter: ChannelAdapter = {
+  type: "whatsapp",
+  provider: "zapster",
+  requiredSecrets: ["ZAPSTER_API_KEY", "ZAPSTER_INSTANCE_ID", "ZAPSTER_WEBHOOK_ID"],
+  verifyWebhook(input) {
+    const expectedInstanceId = input.secrets.ZAPSTER_INSTANCE_ID;
+    const expectedWebhookId = input.secrets.ZAPSTER_WEBHOOK_ID;
+
+    if (!expectedInstanceId) {
+      return {
+        ok: false,
+        code: "channel_secret_missing",
+        message: "Secret ZAPSTER_INSTANCE_ID is not set for this channel.",
+      };
+    }
+
+    if (!expectedWebhookId) {
+      return {
+        ok: false,
+        code: "channel_secret_missing",
+        message: "Secret ZAPSTER_WEBHOOK_ID is not set for this channel.",
+      };
+    }
+
+    const optionalTokenResult = verifyOptionalWebhookToken(input);
+
+    if (!optionalTokenResult.ok) {
+      return optionalTokenResult;
+    }
+
+    const instanceId = input.headers.get("x-instance-id");
+    const webhookId = input.headers.get("x-webhook-id");
+    const messageId = input.headers.get("x-message-id");
+    const attemptCount = input.headers.get("x-attempt-count");
+    const userAgent = input.headers.get("user-agent");
+
+    if (instanceId !== expectedInstanceId) {
+      return {
+        ok: false,
+        code: "channel_signature_invalid",
+        message: "Zapster instance id did not match.",
+      };
+    }
+
+    if (webhookId !== expectedWebhookId) {
+      return {
+        ok: false,
+        code: "channel_signature_invalid",
+        message: "Zapster webhook id did not match.",
+      };
+    }
+
+    if (!messageId || !isPositiveIntegerHeader(attemptCount) || !userAgent?.toLowerCase().startsWith("zapsterapi/")) {
+      return {
+        ok: false,
+        code: "channel_payload_invalid",
+        message: "Missing Zapster webhook headers.",
+      };
+    }
+
+    return { ok: true };
+  },
+  normalizeInbound(input) {
+    const body = parseJsonObject(input);
+    const message = readRecord(body, "message");
+    const instanceId = input.headers.get("x-instance-id") ?? readString(body, "instance_id") ?? "default";
+    const providerEventId = readString(body, "event_id") ?? input.headers.get("x-message-id") ?? readString(message, "id");
+
+    if (!providerEventId) {
+      throw new AgentKitError("channel_payload_invalid", "Zapster payload is missing event_id, X-Message-ID, or message.id.");
+    }
+
+    const contactId = readString(message, "from") ?? "unknown";
+    const messageType = readString(message, "type") ?? "unknown";
+    const base = {
+      type: "whatsapp" as const,
+      provider: "zapster" as const,
+      providerEventId,
+      dedupeKey: `whatsapp:zapster:${instanceId}:${providerEventId}`,
+      externalIdentity: {
+        key: `whatsapp:zapster:contact:${contactId}`,
+        display: contactId,
+        redactedDisplay: `whatsapp:zapster:contact:${redactPhone(contactId)}`,
+      },
+      receivedAt: input.receivedAt,
+      providerMetadata: {
+        instanceId,
+        messageType,
+      },
+    };
+
+    if (messageType !== "text") {
+      return [
+        {
+          ...base,
+          kind: "unsupported",
+          unsupportedReason: `unsupported_message_type:${messageType}`,
+        },
+      ];
+    }
+
+    const text = readString(readRecord(message, "text"), "body");
+
+    if (!text) {
+      return [
+        {
+          ...base,
+          kind: "unsupported",
+          unsupportedReason: "unsupported_message_type:empty_text",
+        },
+      ];
+    }
+
+    return [
+      {
+        ...base,
+        kind: "message",
+        message: {
+          role: "user",
+          contentType: "text",
+          content: text,
+          providerMessageId: readString(message, "id"),
+        },
+      },
+    ];
+  },
+  async sendMessage(input) {
+    const request = buildZapsterSendMessageRequest(input);
+
+    return {
+      ok: true,
+      status: "sent",
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: {
+        method: request.method,
+        url: request.url,
+      },
+    };
+  },
+  getStatus(input) {
+    const missingSecrets = ["ZAPSTER_API_KEY", "ZAPSTER_INSTANCE_ID", "ZAPSTER_WEBHOOK_ID"].filter(
+      (secret) => !input.secrets[secret],
+    );
+
+    if (missingSecrets.length > 0) {
+      return {
+        status: "needs_setup",
+        checkedAt: new Date().toISOString(),
+        message: `Zapster channel secrets are missing: ${missingSecrets.join(", ")}.`,
+      };
+    }
+
+    return {
+      status: "waiting_for_provider_event",
+      checkedAt: new Date().toISOString(),
+      message: "Paste the AgentKit webhook URL into Zapster webhook settings.",
+    };
+  },
+};
+
+function verifyOptionalWebhookToken(input: WebhookVerificationInput): WebhookVerificationResult {
+  const expectsToken = input.channel.secrets.includes("ZAPSTER_WEBHOOK_TOKEN");
+
+  if (!expectsToken) {
+    return { ok: true };
+  }
+
+  const expectedToken = input.secrets.ZAPSTER_WEBHOOK_TOKEN;
+
+  if (!expectedToken) {
+    return {
+      ok: false,
+      code: "channel_secret_missing",
+      message: "Secret ZAPSTER_WEBHOOK_TOKEN is not set for this channel.",
+    };
+  }
+
+  let actualToken: string | null = null;
+
+  try {
+    actualToken = new URL(input.url).searchParams.get("token");
+  } catch {
+    actualToken = null;
+  }
+
+  if (actualToken !== expectedToken) {
+    return {
+      ok: false,
+      code: "channel_signature_invalid",
+      message: "Zapster webhook token did not match.",
+    };
+  }
+
+  return { ok: true };
+}
+
+export type ZapsterSendMessageRequest = {
+  method: "POST";
+  url: string;
+  body: {
+    to: string;
+    type: "text";
+    text: {
+      body: string;
+    };
+  };
+  idempotencyKey: string;
+};
+
+export function buildZapsterSendMessageRequest(input: ChannelSendInput): ZapsterSendMessageRequest {
+  const to = input.externalIdentity.key.match(/contact:([^:]+)$/)?.[1];
+
+  if (!to) {
+    throw new AgentKitError("channel_payload_invalid", "Zapster external identity is missing contact ID.");
+  }
+
+  return {
+    method: "POST",
+    url: "https://api.zapster.example/messages",
+    body: {
+      to,
+      type: "text",
+      text: {
+        body: input.message.content,
+      },
+    },
+    idempotencyKey: `whatsapp:zapster:${input.channelId}:${input.conversationId}:${redactPhone(to)}`,
+  };
+}
+
+function parseJsonObject(input: RawWebhookEvent): Record<string, unknown> {
+  try {
+    const parsed = JSON.parse(input.rawBody) as unknown;
+
+    if (isRecord(parsed)) {
+      return parsed;
+    }
+  } catch (error) {
+    throw new AgentKitError("channel_payload_invalid", "Zapster payload must be valid JSON.", { cause: error });
+  }
+
+  throw new AgentKitError("channel_payload_invalid", "Zapster payload must be a JSON object.");
+}
+
+function readRecord(value: Record<string, unknown>, key: string): Record<string, unknown> {
+  const record = value[key];
+  return isRecord(record) ? record : {};
+}
+
+function readString(value: Record<string, unknown>, key: string): string | undefined {
+  const field = value[key];
+  return typeof field === "string" && field.length > 0 ? field : undefined;
+}
+
+function isPositiveIntegerHeader(value: string | null): value is string {
+  return typeof value === "string" && /^[1-9]\d*$/.test(value);
+}
+
+function redactPhone(value: string): string {
+  if (value.length <= 6) {
+    return "*".repeat(value.length);
+  }
+
+  return `${value.slice(0, 4)}******${value.slice(-4)}`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/runtime/channels.ts

@@ -0,0 +1,138 @@
+import type { AgentChannel, ChannelProvider, ChannelType } from "../index";
+
+export type ChannelMessageRole = "user" | "assistant";
+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"
+  | "dead_lettered"
+  | "skipped";
+
+export type ChannelAdapterId = {
+  type: ChannelType;
+  provider: ChannelProvider;
+};
+
+export type RawWebhookEvent = ChannelAdapterId & {
+  channelId: string;
+  method: string;
+  url: string;
+  headers: Headers;
+  rawBody: string;
+  receivedAt: string;
+};
+
+export type ChannelExternalIdentity = {
+  key: string;
+  display?: string;
+  redactedDisplay?: string;
+};
+
+export type NormalizedChannelMessage = {
+  role: ChannelMessageRole;
+  contentType: ChannelMessageContentType;
+  content: string;
+  providerMessageId?: string;
+};
+
+export type NormalizedChannelEvent = ChannelAdapterId & {
+  kind: ChannelEventKind;
+  providerEventId: string;
+  dedupeKey: string;
+  externalIdentity: ChannelExternalIdentity;
+  message?: NormalizedChannelMessage;
+  deliveryStatus?: ChannelDeliveryState;
+  receivedAt: string;
+  unsupportedReason?: string;
+  providerMetadata?: Record<string, unknown>;
+};
+
+export type WebhookVerificationInput = RawWebhookEvent & {
+  channel: AgentChannel;
+  secrets: Record<string, string>;
+};
+
+export type WebhookVerificationResult =
+  | {
+      ok: true;
+    }
+  | {
+      ok: false;
+      code: "channel_secret_missing" | "channel_signature_invalid" | "channel_payload_invalid";
+      message: string;
+    };
+
+export type ChannelSendInput = ChannelAdapterId & {
+  channelId: string;
+  conversationId: string;
+  externalIdentity: ChannelExternalIdentity;
+  message: NormalizedChannelMessage;
+  secrets: Record<string, string>;
+};
+
+export type ChannelSendResult =
+  | {
+      ok: true;
+      providerRequestId?: string;
+      providerMessageId?: string;
+      status: "sent" | "delivered";
+      providerMetadata?: Record<string, unknown>;
+    }
+  | {
+      ok: false;
+      retryable: boolean;
+      code: "channel_secret_missing" | "channel_provider_unavailable" | "channel_send_failed" | "synthetic_expected_failure";
+      message: string;
+      providerRequestId?: string;
+      providerMetadata?: Record<string, unknown>;
+    };
+
+export type ChannelStatusInput = ChannelAdapterId & {
+  channelId: string;
+  channel: AgentChannel;
+  secrets: Record<string, string>;
+};
+
+export type ChannelStatusResult = {
+  status: "connected" | "needs_setup" | "waiting_for_provider_event" | "failed";
+  checkedAt: string;
+  message?: string;
+  providerMetadata?: Record<string, unknown>;
+};
+
+export type ChannelAdapter = ChannelAdapterId & {
+  requiredSecrets: string[];
+  normalizeInbound(input: RawWebhookEvent): Promise<NormalizedChannelEvent[]> | NormalizedChannelEvent[];
+  sendMessage(input: ChannelSendInput): Promise<ChannelSendResult>;
+  verifyWebhook?(input: WebhookVerificationInput): Promise<WebhookVerificationResult> | WebhookVerificationResult;
+  getStatus?(input: ChannelStatusInput): Promise<ChannelStatusResult> | ChannelStatusResult;
+};
+
+export type PortableChannelRouteContract = {
+  route: "/channels/:name/:type/:provider/webhook";
+  verification: WebhookVerificationResult;
+  dedupe: {
+    key: string;
+    duplicate: boolean;
+  };
+  identity: ChannelExternalIdentity;
+  delivery: {
+    direction: ChannelDeliveryDirection;
+    state: ChannelDeliveryState;
+  };
+  outbound?: ChannelSendResult;
+};

package/src/runtime/chat.ts

@@ -0,0 +1,218 @@
+import { getProviderAdapter } from "../providers";
+import type { AgentMessage, ProviderRunResult } from "../providers";
+import type { ToolRuntimeContext } from "../index";
+import type { ConversationRecord, ConversationSummary, PersistedChatRun } from "../storage/sqlite";
+import type { LoadedAgentCapsule } from "./config";
+import { loadAgentCapsule } from "./config";
+import { openPreparedCapsuleStore } from "./database";
+import { loadCapsuleEnv } from "./env";
+import { AgentKitError, isAgentKitError } from "./errors";
+import { syncConfiguredKnowledgeSources } from "./knowledge/ingest";
+import { appendKnowledgePromptPolicy } from "./knowledge/prompt-policy";
+import { createKnowledgeSearchTool } from "./knowledge/tool";
+import { createToolRuntime } from "./tools";
+
+export type RunAgentMessageOptions = {
+  message: string;
+  conversationId?: string;
+  signal?: AbortSignal;
+  runtime?: Partial<ToolRuntimeContext>;
+};
+
+export type AgentRunResult = ProviderRunResult & PersistedChatRun;
+
+export async function runAgentMessageFromCwd(
+  cwd: string,
+  options: RunAgentMessageOptions,
+): Promise<AgentRunResult> {
+  return runAgentMessage(await loadAgentCapsule(cwd), options);
+}
+
+export async function runAgentMessage(
+  capsule: LoadedAgentCapsule,
+  options: RunAgentMessageOptions,
+): Promise<AgentRunResult> {
+  const content = options.message.trim();
+
+  if (!content) {
+    throw new AgentKitError("validation_error", "chat --message requires a non-empty message.");
+  }
+
+  const adapter = getProviderAdapter(capsule.config.provider);
+  const env = await loadCapsuleEnv(capsule.root);
+  await syncConfiguredKnowledgeSources(capsule);
+  const { store } = await openPreparedCapsuleStore(capsule);
+  const conversationId = normalizeConversationId(options.conversationId);
+  const { conversation, previousMessages } = resolveConversation(store, {
+    agentName: capsule.config.name,
+    conversationId,
+    firstMessage: content,
+  });
+  const messages: AgentMessage[] = [...previousMessages, { role: "user", content }];
+  const userMessage = store.appendMessage({
+    conversationId: conversation.id,
+    role: "user",
+    content,
+  });
+  const run = store.createRun({
+    conversationId: conversation.id,
+    provider: capsule.config.provider.name,
+    model: capsule.config.provider.model,
+  });
+  const runtimeTools = withKnowledgeTools(capsule);
+  const toolRuntime = createToolRuntime({
+    tools: runtimeTools,
+    store,
+    runId: run.id,
+    conversationId: conversation.id,
+    env,
+    signal: options.signal,
+    runtime: {
+      environment: "local",
+      invocation: "chat",
+      target: "bun",
+      database: "sqlite",
+      ...options.runtime,
+    },
+  });
+
+  try {
+    const result = await adapter.run({
+      agent: {
+        name: capsule.config.name,
+        runtime: capsule.config.runtime,
+        provider: capsule.config.provider,
+      },
+      instructions: withToolVisibilityInstructions(
+        appendKnowledgePromptPolicy(capsule.instructions, capsule.config),
+        runtimeTools,
+      ),
+      messages,
+      tools: toolRuntime.definitions,
+      toolRuntime,
+      env,
+      signal: options.signal,
+    });
+
+    const assistantMessage = store.appendMessage({
+      conversationId: conversation.id,
+      role: "assistant",
+      content: result.message.content,
+    });
+
+    store.completeRun({
+      runId: run.id,
+      status: "completed",
+      usage: result.usage,
+    });
+
+    return {
+      ...result,
+      conversationId: conversation.id,
+      runId: run.id,
+      userMessageId: userMessage.id,
+      assistantMessageId: assistantMessage.id,
+    };
+  } catch (error) {
+    store.completeRun({
+      runId: run.id,
+      status: "failed",
+      errorCode: isAgentKitError(error) ? error.code : "runtime_error",
+      errorMessage: error instanceof Error ? error.message : String(error),
+    });
+
+    throw error;
+  } finally {
+    store.close();
+  }
+}
+
+function withKnowledgeTools(capsule: LoadedAgentCapsule): NonNullable<LoadedAgentCapsule["config"]["tools"]> {
+  const tools = [...(capsule.config.tools ?? [])];
+  const knowledgeTool = createKnowledgeSearchTool(capsule);
+
+  if (knowledgeTool) {
+    return [knowledgeTool, ...tools];
+  }
+
+  return tools;
+}
+
+function resolveConversation(
+  store: Awaited<ReturnType<typeof openPreparedCapsuleStore>>["store"],
+  input: {
+    agentName: string;
+    conversationId?: string;
+    firstMessage: string;
+  },
+): { conversation: ConversationSummary; previousMessages: AgentMessage[] } {
+  if (input.conversationId) {
+    const existing = store.getConversation(input.conversationId);
+
+    if (existing) {
+      return {
+        conversation: existing,
+        previousMessages: toProviderMessages(existing),
+      };
+    }
+  }
+
+  const conversation = store.createConversation({
+    id: input.conversationId,
+    agentName: input.agentName,
+    title: titleFromMessage(input.firstMessage),
+  });
+
+  return {
+    conversation,
+    previousMessages: [],
+  };
+}
+
+function toProviderMessages(conversation: ConversationRecord): AgentMessage[] {
+  return conversation.messages.map((message) => ({
+    role: message.role,
+    content: message.content,
+  }));
+}
+
+function normalizeConversationId(value: string | undefined): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  const conversationId = value.trim();
+
+  if (!conversationId) {
+    throw new AgentKitError("validation_error", "conversationId must be a non-empty string when provided.");
+  }
+
+  return conversationId;
+}
+
+function withToolVisibilityInstructions(instructions: string, tools: LoadedAgentCapsule["config"]["tools"] = []): string {
+  const internalTools = tools.filter((tool) => tool.visibility === "internal").map((tool) => tool.name).sort();
+
+  if (internalTools.length === 0) {
+    return instructions;
+  }
+
+  return `${instructions.trimEnd()}
+
+Tool visibility rules:
+- Tool outputs marked internal are operational state for the agent, not user-facing content.
+- Use internal outputs to decide what to do next, but do not reveal raw internal labels, scores, statuses, JSON fields, or tool output objects to the user.
+- Internal tools: ${internalTools.join(", ")}.
+`;
+}
+
+function titleFromMessage(content: string): string {
+  const [firstLine = content] = content.split(/\r?\n/, 1);
+  const compactTitle = firstLine.replace(/\s+/g, " ").trim();
+
+  if (compactTitle.length <= 80) {
+    return compactTitle;
+  }
+
+  return `${compactTitle.slice(0, 77)}...`;
+}