openclaw-codex-app-server 0.0.0

package/src/openclaw-plugin-sdk.d.ts

@@ -0,0 +1,237 @@
+declare module "openclaw/plugin-sdk" {
+  export type ReplyPayload = {
+    text?: string;
+    mediaUrl?: string;
+    mediaUrls?: string[];
+    replyToId?: string;
+    replyToTag?: boolean;
+    replyToCurrent?: boolean;
+    audioAsVoice?: boolean;
+    isError?: boolean;
+    isReasoning?: boolean;
+    channelData?: Record<string, unknown>;
+  };
+
+  export type ConversationRef = {
+    channel: string;
+    accountId: string;
+    conversationId: string;
+    parentConversationId?: string;
+  };
+
+  export type PluginLogger = {
+    info: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => void;
+    debug: (message: string) => void;
+  };
+
+  export type PluginCommandContext = {
+    senderId?: string;
+    channel: string;
+    channelId?: string;
+    isAuthorizedSender: boolean;
+    args?: string;
+    commandBody: string;
+    config: unknown;
+    from?: string;
+    to?: string;
+    accountId?: string;
+    messageThreadId?: number;
+  };
+
+  export type PluginInteractiveButtons = Array<
+    Array<{ text: string; callback_data: string; style?: "danger" | "success" | "primary" }>
+  >;
+
+  export type PluginInteractiveTelegramHandlerContext = {
+    channel: "telegram";
+    accountId: string;
+    callbackId: string;
+    conversationId: string;
+    parentConversationId?: string;
+    senderId?: string;
+    senderUsername?: string;
+    threadId?: number;
+    isGroup: boolean;
+    isForum: boolean;
+    auth: { isAuthorizedSender: boolean };
+    callback: {
+      data: string;
+      namespace: string;
+      payload: string;
+      messageId: number;
+      chatId: string;
+      messageText?: string;
+    };
+    respond: {
+      reply: (params: { text: string; buttons?: PluginInteractiveButtons }) => Promise<void>;
+      editMessage: (params: { text: string; buttons?: PluginInteractiveButtons }) => Promise<void>;
+      editButtons: (params: { buttons: PluginInteractiveButtons }) => Promise<void>;
+      clearButtons: () => Promise<void>;
+      deleteMessage: () => Promise<void>;
+    };
+  };
+
+  export type PluginInteractiveDiscordHandlerContext = {
+    channel: "discord";
+    accountId: string;
+    interactionId: string;
+    conversationId: string;
+    parentConversationId?: string;
+    guildId?: string;
+    senderId?: string;
+    senderUsername?: string;
+    auth: { isAuthorizedSender: boolean };
+    interaction: {
+      kind: "button" | "select" | "modal";
+      data: string;
+      namespace: string;
+      payload: string;
+      messageId?: string;
+      values?: string[];
+      fields?: Array<{ id: string; name: string; values: string[] }>;
+    };
+    respond: {
+      acknowledge: () => Promise<void>;
+      reply: (params: { text: string; ephemeral?: boolean }) => Promise<void>;
+      followUp: (params: { text: string; ephemeral?: boolean }) => Promise<void>;
+      editMessage: (params: { text?: string; components?: unknown[] }) => Promise<void>;
+      clearComponents: (params?: { text?: string }) => Promise<void>;
+    };
+  };
+
+  export type OpenClawPluginService = {
+    id: string;
+    start: (ctx: { workspaceDir?: string }) => void | Promise<void>;
+    stop?: (ctx: { workspaceDir?: string }) => void | Promise<void>;
+  };
+
+  export type SessionBindingRecord = {
+    targetSessionKey: string;
+  };
+
+  export type OpenClawPluginApi = {
+    id: string;
+    pluginConfig?: Record<string, unknown>;
+    logger: PluginLogger;
+    runtime: {
+      state: {
+        resolveStateDir: () => string;
+      };
+      channel: {
+        bindings: {
+          bind: (input: {
+            targetSessionKey: string;
+            targetKind: "session" | "subagent";
+            conversation: ConversationRef;
+            placement?: "current" | "child";
+            metadata?: Record<string, unknown>;
+          }) => Promise<unknown>;
+          unbind: (input: {
+            targetSessionKey?: string;
+            bindingId?: string;
+            reason: string;
+          }) => Promise<unknown>;
+          resolveByConversation: (ref: ConversationRef) => SessionBindingRecord | null;
+        };
+        text: {
+          chunkText: (text: string, limit: number) => string[];
+          resolveTextChunkLimit: (
+            cfg: unknown,
+            provider?: string,
+            accountId?: string | null,
+            opts?: { fallbackLimit?: number },
+          ) => number;
+        };
+        telegram: {
+          sendMessageTelegram: (
+            to: string,
+            text: string,
+            opts?: {
+              accountId?: string;
+              messageThreadId?: number;
+              mediaUrl?: string;
+              mediaLocalRoots?: readonly string[];
+              plainText?: string;
+              textMode?: "markdown" | "html";
+              buttons?: PluginInteractiveButtons;
+            },
+          ) => Promise<unknown>;
+          typing: {
+            start: (params: {
+              to: string;
+              accountId?: string;
+              messageThreadId?: number;
+            }) => Promise<{ refresh: () => Promise<void>; stop: () => void }>;
+          };
+          conversationActions: {
+            renameTopic: (
+              chatId: string,
+              messageThreadId: number,
+              name: string,
+              opts?: { accountId?: string },
+            ) => Promise<unknown>;
+          };
+        };
+        discord: {
+          sendMessageDiscord: (
+            to: string,
+            text: string,
+            opts?: {
+              accountId?: string;
+              mediaUrl?: string;
+              mediaLocalRoots?: readonly string[];
+            },
+          ) => Promise<unknown>;
+          sendComponentMessage: (
+            to: string,
+            spec: unknown,
+            opts?: { accountId?: string },
+          ) => Promise<unknown>;
+          typing: {
+            start: (params: {
+              channelId: string;
+              accountId?: string;
+            }) => Promise<{ refresh: () => Promise<void>; stop: () => void }>;
+          };
+          conversationActions: {
+            editChannel: (
+              channelId: string,
+              params: { name?: string },
+              opts?: { accountId?: string },
+            ) => Promise<unknown>;
+          };
+        };
+      };
+    };
+    registerService: (service: OpenClawPluginService) => void;
+    registerInteractiveHandler: (registration: {
+      channel: "telegram" | "discord";
+      namespace: string;
+      handler: (ctx: any) => Promise<{ handled?: boolean } | void> | { handled?: boolean } | void;
+    }) => void;
+    registerCommand: (command: {
+      name: string;
+      description: string;
+      acceptsArgs?: boolean;
+      handler: (ctx: PluginCommandContext) => Promise<ReplyPayload> | ReplyPayload;
+    }) => void;
+    on: (
+      hookName: "inbound_claim",
+      handler: (event: {
+        content: string;
+        channel: string;
+        accountId?: string;
+        conversationId?: string;
+        parentConversationId?: string;
+        threadId?: string | number;
+      }) => Promise<{ handled: boolean }> | { handled: boolean },
+    ) => void;
+  };
+}
+
+declare module "ws" {
+  const WebSocket: any;
+  export default WebSocket;
+}

package/src/pending-input.test.ts

@@ -0,0 +1,298 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildPendingQuestionnaireResponse,
+  buildPendingPromptText,
+  buildPendingUserInputActions,
+  createPendingInputState,
+  formatPendingQuestionnairePrompt,
+  parseCodexUserInput,
+  parsePendingQuestionnaire,
+  questionnaireCurrentQuestionHasAnswer,
+  questionnaireIsComplete,
+  requestToken,
+} from "./pending-input.js";
+
+describe("pending-input helpers", () => {
+  it("parses numeric option replies", () => {
+    expect(parseCodexUserInput("2", 3)).toEqual({ kind: "option", index: 1 });
+    expect(parseCodexUserInput("option 1", 3)).toEqual({ kind: "option", index: 0 });
+    expect(parseCodexUserInput("hello", 3)).toEqual({ kind: "text", text: "hello" });
+  });
+
+  it("builds approval actions from request decisions", () => {
+    const actions = buildPendingUserInputActions({
+      method: "turn/requestApproval",
+      requestParams: {
+        availableDecisions: ["accept", "acceptForSession", "decline", "cancel"],
+      },
+    });
+    expect(actions.map((action) => action.label)).toEqual([
+      "Approve Once",
+      "Approve for Session",
+      "Decline",
+      "Cancel",
+      "Tell Codex What To Do",
+    ]);
+  });
+
+  it("defaults file change approvals to approve and decline actions", () => {
+    const actions = buildPendingUserInputActions({
+      method: "item/fileChange/requestApproval",
+      requestParams: {
+        threadId: "019cd368-7eda-7863-86ba-6586598bc5a3",
+        turnId: "turn-1",
+        itemId: "item-1",
+      },
+    });
+    expect(actions.map((action) => action.label)).toEqual([
+      "Approve File Changes",
+      "Decline",
+      "Tell Codex What To Do",
+    ]);
+  });
+
+  it("does not treat ids as shell commands for file change approvals", () => {
+    const text = buildPendingPromptText({
+      method: "item/fileChange/requestApproval",
+      requestId: "req-file-1",
+      requestParams: {
+        threadId: "019cd368-7eda-7863-86ba-6586598bc5a3",
+        turnId: "turn-1",
+        itemId: "item-1",
+        reason: "Codex wants to apply the proposed patch.",
+      },
+      options: [],
+      actions: buildPendingUserInputActions({
+        method: "item/fileChange/requestApproval",
+        requestParams: {
+          threadId: "019cd368-7eda-7863-86ba-6586598bc5a3",
+          turnId: "turn-1",
+          itemId: "item-1",
+          reason: "Codex wants to apply the proposed patch.",
+        },
+      }),
+      expiresAt: Date.now() + 60_000,
+    });
+
+    expect(text).toContain("Codex file change approval requested");
+    expect(text).toContain("Codex wants to apply the proposed patch.");
+    expect(text).not.toContain("Command:");
+    expect(text).not.toContain("019cd368-7eda-7863-86ba-6586598bc5a3");
+  });
+
+  it("lists changed files for file change approvals", () => {
+    const text = buildPendingPromptText({
+      method: "item/fileChange/requestApproval",
+      requestId: "req-file-2",
+      requestParams: {
+        threadId: "thread-1",
+        turnId: "turn-1",
+        itemId: "item-1",
+        filePaths: ["src/app.ts", "README.md", "/tmp/outside.txt"],
+      },
+      options: [],
+      actions: buildPendingUserInputActions({
+        method: "item/fileChange/requestApproval",
+        requestParams: {
+          threadId: "thread-1",
+          turnId: "turn-1",
+          itemId: "item-1",
+        },
+      }),
+      expiresAt: Date.now() + 60_000,
+    });
+
+    expect(text).toContain("Files:");
+    expect(text).toContain("`src/app.ts`");
+    expect(text).toContain("`README.md`");
+    expect(text).toContain("`/tmp/outside.txt`");
+  });
+
+  it("creates a stable request token", () => {
+    expect(requestToken("abc")).toBe(requestToken("abc"));
+    expect(requestToken("abc")).not.toBe(requestToken("def"));
+  });
+
+  it("creates a prompt text for pending input", () => {
+    const state = createPendingInputState({
+      method: "item/tool/requestUserInput",
+      requestId: "req-1",
+      requestParams: {
+        question: "Pick one",
+      },
+      options: ["A", "B"],
+      expiresAt: Date.now() + 60_000,
+    });
+    expect(state.promptText).toContain("Codex input requested");
+    expect(state.promptText).toContain("Choices:");
+  });
+
+  it("truncates oversized pending request prompts for chat delivery", () => {
+    const text = buildPendingPromptText({
+      method: "item/tool/requestUserInput",
+      requestId: "req-2",
+      requestParams: {
+        prompt: "A".repeat(5000),
+      },
+      options: ["A", "B"],
+      actions: [],
+      expiresAt: Date.now() + 60_000,
+    });
+    expect(text.length).toBeLessThan(2400);
+    expect(text).toContain("[Request details truncated.");
+  });
+
+  it("parses multi-question plan prompts into a questionnaire state", () => {
+    const questionnaire = parsePendingQuestionnaire(`
+1. What do you want the final artifact to be?
+
+• A Single static binary
+• B Normal runtime-managed CLI
+
+Guidance:
+• A points toward Go or Rust.
+
+2. What do you care about more: delivery speed or long-term rigor?
+
+• A Fastest rewrite
+• B Balanced
+    `);
+
+    expect(questionnaire?.questions).toHaveLength(2);
+    expect(questionnaire?.questions[0]).toMatchObject({
+      id: "q1",
+      prompt: "What do you want the final artifact to be?",
+      options: [
+        { key: "A", label: "Single static binary" },
+        { key: "B", label: "Normal runtime-managed CLI" },
+      ],
+    });
+    expect(formatPendingQuestionnairePrompt(questionnaire!)).toContain("Codex plan question 1 of 2");
+  });
+
+  it("renders a compact questionnaire reply once all answers are filled in", () => {
+    const questionnaire = parsePendingQuestionnaire(`
+1. What do you want the final artifact to be?
+• A Single static binary
+• B Normal runtime-managed CLI
+
+2. What do you care about more?
+• A Fastest rewrite
+• B Balanced
+    `)!;
+    questionnaire.answers[0] = {
+      kind: "option",
+      optionKey: "A",
+      optionLabel: "Single static binary",
+    };
+    questionnaire.answers[1] = {
+      kind: "text",
+      text: "Balanced, but only if we keep the migration simple.",
+    };
+    expect(questionnaireIsComplete(questionnaire)).toBe(true);
+    expect(buildPendingQuestionnaireResponse(questionnaire)).toBe(
+      "1A 2: Balanced, but only if we keep the migration simple.",
+    );
+  });
+
+  it("requires an answer before advancing to the next questionnaire question", () => {
+    const questionnaire = parsePendingQuestionnaire(`
+1. What do you want the final artifact to be?
+• A Single static binary
+• B Normal runtime-managed CLI
+
+2. What do you care about more?
+• A Fastest rewrite
+• B Balanced
+    `)!;
+
+    expect(questionnaireCurrentQuestionHasAnswer(questionnaire)).toBe(false);
+
+    questionnaire.answers[0] = {
+      kind: "option",
+      optionKey: "A",
+      optionLabel: "Single static binary",
+    };
+
+    expect(questionnaireCurrentQuestionHasAnswer(questionnaire)).toBe(true);
+  });
+
+  it("parses structured request_user_input questions into questionnaire state", () => {
+    const state = createPendingInputState({
+      method: "item/tool/requestUserInput",
+      requestId: "req-3",
+      requestParams: {
+        questions: [
+          {
+            id: "runtime",
+            header: "Runtime",
+            question: "Which runtime shape should we optimize for?",
+            isOther: true,
+            options: [
+              {
+                label: "Long-lived service (Recommended)",
+                description: "Best fit for stateful flows.",
+              },
+              {
+                label: "Mostly serverless",
+                description: "Best fit for stateless handlers.",
+              },
+            ],
+          },
+          {
+            id: "db",
+            header: "DB",
+            question: "What kind of database migration do you want from SQLite?",
+            options: [{ label: "Postgres (Recommended)" }, { label: "Firestore" }],
+          },
+        ],
+      },
+      options: [],
+      expiresAt: Date.now() + 60_000,
+    });
+
+    expect(state.questionnaire?.questions).toHaveLength(2);
+    expect(state.questionnaire?.questions[0]).toMatchObject({
+      id: "runtime",
+      header: "Runtime",
+      prompt: "Which runtime shape should we optimize for?",
+      allowFreeform: true,
+      options: [
+        {
+          key: "A",
+          label: "Long-lived service (Recommended)",
+          description: "Best fit for stateful flows.",
+          recommended: true,
+        },
+        {
+          key: "B",
+          label: "Mostly serverless",
+          description: "Best fit for stateless handlers.",
+          recommended: false,
+        },
+      ],
+    });
+    expect(formatPendingQuestionnairePrompt(state.questionnaire!)).toContain(
+      "Runtime: Which runtime shape should we optimize for?",
+    );
+    expect(formatPendingQuestionnairePrompt(state.questionnaire!)).toContain(
+      "Other: You can reply with free text.",
+    );
+    state.questionnaire!.answers[0] = {
+      kind: "option",
+      optionKey: "A",
+      optionLabel: "Long-lived service (Recommended)",
+    };
+    state.questionnaire!.answers[1] = {
+      kind: "option",
+      optionKey: "A",
+      optionLabel: "Postgres (Recommended)",
+    };
+    expect(buildPendingQuestionnaireResponse(state.questionnaire!)).toEqual({
+      answers: {
+        runtime: { answers: ["Long-lived service (Recommended)"] },
+        db: { answers: ["Postgres (Recommended)"] },
+      },
+    });
+  });
+});