@orchestero/codex-gateway 0.0.3

package/CHANGELOG.md

@@ -0,0 +1,54 @@
+# @orchestero/codex-gateway
+
+## 0.0.3
+### Patch Changes
+
+
+
+- [#15](https://github.com/phuctm97/orchestero/pull/15) [`b90616e`](https://github.com/phuctm97/orchestero/commit/b90616eea13712cb6c0e1610ba95419ad8f37ce6) Thanks [@phuctm97](https://github.com/phuctm97)! - Republish private packages to GitHub Packages.
+
+## 0.0.2
+### Patch Changes
+
+
+
+- [#14](https://github.com/phuctm97/orchestero/pull/14) [`872581a`](https://github.com/phuctm97/orchestero/commit/872581a23a6a4568a0bb185f6a2647098028980e) Thanks [@phuctm97](https://github.com/phuctm97)! - Republish private packages to GitHub Packages.
+
+## 0.0.1
+### Patch Changes
+
+
+
+- [#6](https://github.com/phuctm97/orchestero/pull/6) [`63837b6`](https://github.com/phuctm97/orchestero/commit/63837b643087418d5314a2fd8ed3bc84e3250f5f) Thanks [@phuctm97](https://github.com/phuctm97)! - Replace WhatsApp with Zalo in Codex Gateway and on the website.
+
+
+
+- [#11](https://github.com/phuctm97/orchestero/pull/11) [`ef77c71`](https://github.com/phuctm97/orchestero/commit/ef77c71bedd49d27535ec25253fac22d92b56722) Thanks [@phuctm97](https://github.com/phuctm97)! - Add per-agent working directories to Codex Gateway config.
+
+
+
+- [#3](https://github.com/phuctm97/orchestero/pull/3) [`f856102`](https://github.com/phuctm97/orchestero/commit/f8561025acd5bf5704a24c15c3e22531f98c8d90) Thanks [@phuctm97](https://github.com/phuctm97)! - Add Codex gateway executable for chat channel integrations.
+
+
+
+- [#4](https://github.com/phuctm97/orchestero/pull/4) [`82076cb`](https://github.com/phuctm97/orchestero/commit/82076cbac8652e60def881d73baf20996a1c61ed) Thanks [@phuctm97](https://github.com/phuctm97)! - Keep Codex app-server connections alive across chat turns.
+
+
+
+- [#13](https://github.com/phuctm97/orchestero/pull/13) [`7fc080b`](https://github.com/phuctm97/orchestero/commit/7fc080be7e83262447ec40e18c1853dc30f752d0) Thanks [@phuctm97](https://github.com/phuctm97)! - Publish private packages to GitHub Packages.
+
+
+
+- [#10](https://github.com/phuctm97/orchestero/pull/10) [`f0893ad`](https://github.com/phuctm97/orchestero/commit/f0893adb463e1372866ba9fcec6b6a92f9da78d6) Thanks [@phuctm97](https://github.com/phuctm97)! - Avoid wasted Codex Gateway resources during agent setup.
+
+
+
+- [#9](https://github.com/phuctm97/orchestero/pull/9) [`1b3fef1`](https://github.com/phuctm97/orchestero/commit/1b3fef16505282b6efbe4ded7caae4b5a2f3971d) Thanks [@phuctm97](https://github.com/phuctm97)! - Load Codex Gateway agents from file-based channel config.
+
+
+
+- [#12](https://github.com/phuctm97/orchestero/pull/12) [`623028c`](https://github.com/phuctm97/orchestero/commit/623028cfba1dd4157da56b7a31c75dd807d48250) Thanks [@phuctm97](https://github.com/phuctm97)! - Add first-party Zalo adapter support with webhook and long-polling runtime modes.
+
+
+
+- [#5](https://github.com/phuctm97/orchestero/pull/5) [`e94acc4`](https://github.com/phuctm97/orchestero/commit/e94acc43a5947699e29667a82f38fe0b5dcf3425) Thanks [@phuctm97](https://github.com/phuctm97)! - Improve Codex gateway runtime logging and chat error replies.

package/lib/agent-configs.ts

@@ -0,0 +1,191 @@
+import * as z from "zod";
+
+type AgentConfigSource = string | URL;
+
+type TelegramConfig = {
+  botToken: string;
+  secretToken?: string;
+  userName?: string;
+};
+
+type ZaloConfig = {
+  botToken: string;
+  longPolling?: ZaloLongPollingConfig;
+  mode?: ZaloMode;
+  secretToken?: string;
+  userName?: string;
+};
+
+type ZaloLongPollingConfig = {
+  deleteWebhook?: boolean;
+  retryDelayMs?: number;
+  timeout?: number;
+};
+
+type ZaloMode = "auto" | "polling" | "webhook";
+
+type AgentConfig = {
+  id: string;
+  workingDirectory?: string;
+  telegram?: TelegramConfig;
+  zalo?: ZaloConfig;
+};
+
+const defaultSource = "agents.local.json";
+const agentIdPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+function optionalStringSchema(message: string) {
+  return z
+    .string({ error: message })
+    .trim()
+    .transform((value) => value || undefined)
+    .optional();
+}
+
+function requiredStringSchema(message: string) {
+  return z.string({ error: message }).trim().min(1, { error: message });
+}
+
+const telegramConfigSchema = z.object(
+  {
+    botToken: requiredStringSchema("Expected Telegram bot token."),
+    secretToken: optionalStringSchema("Expected Telegram secret token."),
+    userName: optionalStringSchema("Expected Telegram username."),
+  },
+  { error: "Expected Telegram config." },
+);
+
+const zaloConfigSchema = z.object(
+  {
+    botToken: requiredStringSchema("Expected Zalo bot token."),
+    longPolling: z
+      .object(
+        {
+          deleteWebhook: z.boolean().optional(),
+          retryDelayMs: z
+            .number({ error: "Expected Zalo polling retry delay." })
+            .positive({ error: "Expected Zalo polling retry delay." })
+            .optional(),
+          timeout: z
+            .number({ error: "Expected Zalo polling timeout." })
+            .positive({ error: "Expected Zalo polling timeout." })
+            .optional(),
+        },
+        { error: "Expected Zalo long polling config." },
+      )
+      .optional(),
+    mode: z.enum(["auto", "polling", "webhook"]).optional(),
+    secretToken: optionalStringSchema("Expected Zalo secret token."),
+    userName: optionalStringSchema("Expected Zalo username."),
+  },
+  { error: "Expected Zalo config." },
+);
+
+const agentConfigSchema = z
+  .object(
+    {
+      id: requiredStringSchema("Expected agent id.").regex(agentIdPattern, {
+        error: "Expected agent id to be a lowercase slug.",
+      }),
+      workingDirectory: optionalStringSchema("Expected working directory."),
+      telegram: telegramConfigSchema.optional(),
+      zalo: zaloConfigSchema.optional(),
+    },
+    { error: "Expected agent id." },
+  )
+  .refine((value) => value.telegram || value.zalo, {
+    message: "Expected agent channel config.",
+  });
+
+const agentsConfigSchema = z
+  .object(
+    {
+      agents: z
+        .array(agentConfigSchema, { error: "Expected agents config." })
+        .min(1, { error: "Expected at least one agent config." }),
+    },
+    { error: "Expected agents config." },
+  )
+  .superRefine((value, context) => {
+    const ids = new Set<string>();
+
+    for (const agent of value.agents) {
+      if (ids.has(agent.id)) {
+        context.addIssue({
+          code: "custom",
+          message: `Expected unique agent id: ${agent.id}.`,
+        });
+      }
+
+      ids.add(agent.id);
+    }
+  });
+
+type ParsedTelegramConfig = z.infer<typeof telegramConfigSchema>;
+type ParsedZaloConfig = z.infer<typeof zaloConfigSchema>;
+type ParsedAgentConfig = z.infer<typeof agentConfigSchema>;
+
+function getErrorMessage(error: unknown) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return String(error);
+}
+
+function getValidationMessage(error: z.ZodError) {
+  return error.issues.map((issue) => issue.message).join("\n");
+}
+
+function normalizeTelegramConfig(config: ParsedTelegramConfig): TelegramConfig {
+  return {
+    botToken: config.botToken,
+    secretToken: config.secretToken,
+    userName: config.userName,
+  };
+}
+
+function normalizeZaloConfig(config: ParsedZaloConfig): ZaloConfig {
+  return {
+    botToken: config.botToken,
+    longPolling: config.longPolling,
+    mode: config.mode,
+    secretToken: config.secretToken,
+    userName: config.userName,
+  };
+}
+
+function normalizeAgentConfig(config: ParsedAgentConfig): AgentConfig {
+  return {
+    id: config.id,
+    workingDirectory: config.workingDirectory,
+    telegram: config.telegram
+      ? normalizeTelegramConfig(config.telegram)
+      : undefined,
+    zalo: config.zalo ? normalizeZaloConfig(config.zalo) : undefined,
+  };
+}
+
+function parse(value: unknown) {
+  const result = agentsConfigSchema.safeParse(value);
+  if (!result.success) {
+    throw new Error(getValidationMessage(result.error));
+  }
+
+  return result.data.agents.map(normalizeAgentConfig);
+}
+
+async function load(source: AgentConfigSource = defaultSource) {
+  try {
+    return parse(await Bun.file(source).json());
+  } catch (error) {
+    throw new Error(
+      `Failed to load agent config: ${source.toString()}. ${getErrorMessage(
+        error,
+      )}`,
+      { cause: error },
+    );
+  }
+}
+
+export const agentConfigs = { load, parse };

package/lib/chat-bot.ts

@@ -0,0 +1,287 @@
+import { createTelegramAdapter } from "@chat-adapter/telegram";
+import type { Adapter, Message, StateAdapter, Thread } from "chat";
+import { Chat } from "chat";
+import type { agentConfigs } from "~/lib/agent-configs";
+import { codexAppServer } from "~/lib/codex-app-server";
+import { pgState } from "~/lib/pg-state";
+import { createZaloAdapter } from "~/lib/zalo-adapter";
+
+type CodexAppServer = {
+  stream: ReturnType<typeof codexAppServer.create>["stream"];
+};
+
+type ChatBotAdapters = Partial<{
+  telegram: Adapter;
+  zalo: Adapter;
+}>;
+
+type ChatBotThreadState = {
+  codexThreadId?: string;
+};
+
+type ChatBotLogContext = Record<string, unknown>;
+
+type ChatBotLogger = {
+  error: (message: string, context?: ChatBotLogContext) => void;
+  info: (message: string, context?: ChatBotLogContext) => void;
+};
+
+type ChatBotOptions = {
+  adapters?: ChatBotAdapters;
+  codex: CodexAppServer;
+  logger?: ChatBotLogger;
+  state: StateAdapter;
+  userName?: string;
+  workingDirectory?: string;
+};
+
+type ChatBotAgentConfig = ReturnType<typeof agentConfigs.parse>[number];
+
+type ChatBotManyOptions = Omit<
+  ChatBotOptions,
+  "adapters" | "codex" | "state" | "workingDirectory"
+> & {
+  agents: ChatBotAgentConfig[];
+  codex?: CodexAppServer;
+};
+
+type RespondOptions = {
+  codex: CodexAppServer;
+  logger?: ChatBotLogger;
+  message: {
+    id?: string;
+    raw?: unknown;
+    text: string;
+    threadId?: string;
+  };
+  thread: {
+    id?: string;
+    post: (message: AsyncIterable<string>) => Promise<unknown>;
+    readonly state: Promise<ChatBotThreadState | null>;
+    setState: (state: Partial<ChatBotThreadState>) => Promise<void>;
+    startTyping: (status?: string) => Promise<unknown>;
+  };
+  workingDirectory?: string;
+};
+
+const fallbackMessage = "Sorry, I ran into an issue. Please try again.";
+const unsupportedGroupMessage = "Please send a direct message.";
+const unsupportedMessage = "Please send a text message.";
+const defaultLogger: ChatBotLogger = {
+  error(message, context) {
+    console.error(message, context);
+  },
+  info(message, context) {
+    console.info(message, context);
+  },
+};
+
+function getPlatform(threadId?: string) {
+  return threadId?.split(":", 1)[0] || "unknown";
+}
+
+function getErrorMessage(error: unknown) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return String(error);
+}
+
+function getZaloChatType(raw: unknown) {
+  const rawMessage = Reflect.get(Object(raw ?? {}), "message");
+  const chat = Reflect.get(Object(rawMessage ?? {}), "chat");
+  const chatType = Reflect.get(Object(chat ?? {}), "chat_type");
+
+  if (typeof chatType === "string") {
+    return chatType;
+  }
+}
+
+async function postText(thread: RespondOptions["thread"], message: string) {
+  await thread.post(
+    (async function* () {
+      yield message;
+    })(),
+  );
+}
+
+async function startTyping(
+  thread: RespondOptions["thread"],
+  logger: ChatBotLogger,
+  context: ChatBotLogContext,
+) {
+  try {
+    await thread.startTyping("Working...");
+  } catch (error) {
+    logger.info("Ignored chat typing failure.", {
+      ...context,
+      error: getErrorMessage(error),
+    });
+  }
+}
+
+function createAdapters(agent: ChatBotAgentConfig): ChatBotAdapters {
+  const adapters: ChatBotAdapters = {};
+
+  if (agent.telegram) {
+    adapters.telegram = createTelegramAdapter({
+      botToken: agent.telegram.botToken,
+      secretToken: agent.telegram.secretToken,
+      userName: agent.telegram.userName,
+    });
+  }
+
+  if (agent.zalo) {
+    adapters.zalo = createZaloAdapter({
+      botToken: agent.zalo.botToken,
+      longPolling: agent.zalo.longPolling,
+      mode: agent.zalo.mode,
+      secretToken: agent.zalo.secretToken,
+      userName: agent.zalo.userName,
+    });
+  }
+
+  return adapters;
+}
+
+async function respond({
+  codex,
+  logger = defaultLogger,
+  message,
+  thread,
+  workingDirectory,
+}: RespondOptions) {
+  const input = message.text.trim();
+  const threadId = message.threadId || thread.id;
+  const platform = getPlatform(threadId);
+  const zaloChatType = getZaloChatType(message.raw);
+  const logContext = {
+    messageId: message.id,
+    platform,
+    threadId,
+  };
+
+  if (platform === "zalo" && zaloChatType === "GROUP") {
+    logger.info("Ignored unsupported chat message.", logContext);
+    await postText(thread, unsupportedGroupMessage);
+    return;
+  }
+
+  if (!input) {
+    logger.info("Ignored unsupported chat message.", logContext);
+    await postText(thread, unsupportedMessage);
+    return;
+  }
+
+  const startedAt = Date.now();
+  let codexThreadId: string | undefined;
+  let resumed = false;
+
+  try {
+    const state = await thread.state;
+    codexThreadId = state?.codexThreadId;
+    resumed = Boolean(codexThreadId);
+    logger.info("Started Codex gateway turn.", {
+      ...logContext,
+      codexThreadId,
+      resumed,
+    });
+    await startTyping(thread, logger, logContext);
+    await thread.post(
+      codex.stream({
+        input,
+        onThreadId: (nextCodexThreadId) => {
+          codexThreadId = nextCodexThreadId;
+          return thread.setState({ codexThreadId: nextCodexThreadId });
+        },
+        threadId: codexThreadId,
+        workingDirectory,
+      }),
+    );
+    logger.info("Completed Codex gateway turn.", {
+      ...logContext,
+      codexThreadId,
+      durationMs: Date.now() - startedAt,
+      resumed,
+    });
+  } catch (error) {
+    logger.error("Failed Codex gateway turn.", {
+      ...logContext,
+      codexThreadId,
+      durationMs: Date.now() - startedAt,
+      error: getErrorMessage(error),
+      resumed,
+    });
+    await postText(thread, fallbackMessage);
+  }
+}
+
+function create(options: ChatBotOptions) {
+  const {
+    adapters = {},
+    codex,
+    logger = defaultLogger,
+    state,
+    userName = "orchestero",
+    workingDirectory,
+  } = options;
+  const bot = new Chat({
+    userName,
+    adapters,
+    state,
+    logger: "info",
+    concurrency: "queue",
+    fallbackStreamingPlaceholderText: "Working...",
+  });
+  const handler = (thread: Thread<ChatBotThreadState>, message: Message) =>
+    respond({ codex, logger, message, thread, workingDirectory });
+
+  bot.onDirectMessage(handler);
+
+  return bot;
+}
+
+function createMany(options: ChatBotManyOptions) {
+  const { agents, codex, ...botOptions } = options;
+  if (agents.length === 0) {
+    throw new Error("Expected at least one agent.");
+  }
+
+  const agentIds = new Set<string>();
+
+  for (const agent of agents) {
+    if (!agent.telegram && !agent.zalo) {
+      throw new Error("Expected agent channel config.");
+    }
+
+    if (agentIds.has(agent.id)) {
+      throw new Error(`Expected unique agent id: ${agent.id}.`);
+    }
+
+    agentIds.add(agent.id);
+  }
+
+  const codexRuntime = codex || codexAppServer.create();
+  const bots: Record<string, ReturnType<typeof create>> = {};
+
+  for (const agent of agents) {
+    bots[agent.id] = create({
+      ...botOptions,
+      adapters: createAdapters(agent),
+      codex: codexRuntime,
+      state: pgState.create({ keyPrefix: `agent:${agent.id}` }),
+      userName: botOptions.userName || `orchestero-${agent.id}`,
+      workingDirectory: agent.workingDirectory,
+    });
+  }
+
+  return bots;
+}
+
+export const chatBot = {
+  create,
+  createAdapters,
+  createMany,
+  respond,
+};