openclaw-codex-app-server 0.0.0

package/src/thread-picker.ts

@@ -0,0 +1,98 @@
+import path from "node:path";
+import type { ThreadSummary } from "./types.js";
+
+export const THREAD_PICKER_PAGE_SIZE = 8;
+
+export type ProjectSummary = {
+  name: string;
+  threadCount: number;
+  latestUpdatedAt?: number;
+};
+
+export function getProjectName(projectKey?: string): string | undefined {
+  const trimmed = projectKey?.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+  const normalized = trimmed.replace(/[\\/]+$/, "");
+  const base = path.basename(normalized);
+  return base || undefined;
+}
+
+export function filterThreadsByProjectName(
+  threads: ThreadSummary[],
+  projectName?: string,
+): ThreadSummary[] {
+  const normalized = projectName?.trim().toLowerCase();
+  if (!normalized) {
+    return [...threads];
+  }
+  return threads.filter((thread) => getProjectName(thread.projectKey)?.toLowerCase() === normalized);
+}
+
+export function listProjects(
+  threads: ThreadSummary[],
+  query = "",
+): ProjectSummary[] {
+  const filteredQuery = query.trim().toLowerCase();
+  const grouped = new Map<string, ProjectSummary>();
+
+  for (const thread of threads) {
+    const projectName = getProjectName(thread.projectKey);
+    if (!projectName) {
+      continue;
+    }
+    if (filteredQuery && !projectName.toLowerCase().includes(filteredQuery)) {
+      continue;
+    }
+    const existing = grouped.get(projectName);
+    const updatedAt = thread.updatedAt ?? thread.createdAt;
+    if (!existing) {
+      grouped.set(projectName, {
+        name: projectName,
+        threadCount: 1,
+        latestUpdatedAt: updatedAt,
+      });
+      continue;
+    }
+    existing.threadCount += 1;
+    existing.latestUpdatedAt = Math.max(existing.latestUpdatedAt ?? 0, updatedAt ?? 0) || undefined;
+  }
+
+  return [...grouped.values()].sort((left, right) => {
+    const updatedDelta = (right.latestUpdatedAt ?? 0) - (left.latestUpdatedAt ?? 0);
+    if (updatedDelta !== 0) {
+      return updatedDelta;
+    }
+    return left.name.localeCompare(right.name);
+  });
+}
+
+export function paginateItems<T>(
+  items: T[],
+  page: number,
+  pageSize = THREAD_PICKER_PAGE_SIZE,
+): {
+  items: T[];
+  page: number;
+  pageSize: number;
+  totalItems: number;
+  totalPages: number;
+  startIndex: number;
+  endIndex: number;
+} {
+  const totalItems = items.length;
+  const totalPages = Math.max(1, Math.ceil(totalItems / pageSize));
+  const safePage = Math.min(Math.max(0, page), totalPages - 1);
+  const startIndex = safePage * pageSize;
+  const pageItems = items.slice(startIndex, startIndex + pageSize);
+  return {
+    items: pageItems,
+    page: safePage,
+    pageSize,
+    totalItems,
+    totalPages,
+    startIndex,
+    endIndex: startIndex + pageItems.length,
+  };
+}

package/src/thread-selection.test.ts

@@ -0,0 +1,89 @@
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import {
+  parseThreadSelectionArgs,
+  selectThreadFromMatches,
+} from "./thread-selection.js";
+import type { ThreadSummary } from "./types.js";
+
+const THREADS: ThreadSummary[] = [
+  {
+    threadId: "thread-openclaw",
+    title: "OpenClaw work",
+    projectKey: "/workspace/openclaw",
+  },
+  {
+    threadId: "thread-home",
+    title: "Home dotfiles",
+    projectKey: "/workspace/home",
+  },
+];
+
+describe("thread selection args", () => {
+  it("parses --all without inventing a query", () => {
+    expect(parseThreadSelectionArgs("--all")).toEqual({
+      includeAll: true,
+      listProjects: false,
+      syncTopic: false,
+      cwd: undefined,
+      query: "",
+    });
+  });
+
+  it("parses em dash all from Telegram-style input", () => {
+    expect(parseThreadSelectionArgs("—all")).toEqual({
+      includeAll: true,
+      listProjects: false,
+      syncTopic: false,
+      cwd: undefined,
+      query: "",
+    });
+  });
+
+  it("parses --all with a target query", () => {
+    expect(parseThreadSelectionArgs("--all thread-home")).toEqual({
+      includeAll: true,
+      listProjects: false,
+      syncTopic: false,
+      cwd: undefined,
+      query: "thread-home",
+    });
+  });
+
+  it("parses --projects and expands a home-relative cwd", () => {
+    expect(parseThreadSelectionArgs("--projects --cwd ~/github/openclaw")).toEqual({
+      includeAll: false,
+      listProjects: true,
+      syncTopic: false,
+      cwd: path.join(os.homedir(), "github/openclaw"),
+      query: "",
+    });
+  });
+
+  it("parses --sync separately from the query text", () => {
+    expect(parseThreadSelectionArgs("—all —sync approvals")).toEqual({
+      includeAll: true,
+      listProjects: false,
+      syncTopic: true,
+      cwd: undefined,
+      query: "approvals",
+    });
+  });
+});
+
+describe("thread selection", () => {
+  it("picks an exact thread id match", () => {
+    expect(selectThreadFromMatches(THREADS, "thread-home")).toEqual({
+      kind: "unique",
+      thread: THREADS[1],
+    });
+  });
+
+  it("does not auto-pick the first fuzzy match when multiple threads exist", () => {
+    expect(selectThreadFromMatches(THREADS, "thread")).toEqual({
+      kind: "ambiguous",
+      threads: THREADS,
+    });
+  });
+});

package/src/thread-selection.ts

@@ -0,0 +1,106 @@
+import os from "node:os";
+import path from "node:path";
+import type { ThreadSummary } from "./types.js";
+
+export type ParsedThreadSelectionArgs = {
+  includeAll: boolean;
+  listProjects: boolean;
+  syncTopic: boolean;
+  cwd?: string;
+  query: string;
+};
+
+export type ThreadSelectionResult =
+  | { kind: "none" }
+  | { kind: "unique"; thread: ThreadSummary }
+  | { kind: "ambiguous"; threads: ThreadSummary[] };
+
+function normalizeOptionDashes(text: string): string {
+  return text
+    .replace(/(^|\s)[\u2010-\u2015\u2212](?=\S)/g, "$1--")
+    .replace(/[\u2010-\u2015\u2212]/g, "-");
+}
+
+export function parseThreadSelectionArgs(args: string): ParsedThreadSelectionArgs {
+  const tokens = normalizeOptionDashes(args)
+    .split(/\s+/)
+    .map((token) => token.trim())
+    .filter(Boolean);
+  let includeAll = false;
+  let listProjects = false;
+  let syncTopic = false;
+  let cwd: string | undefined;
+  const queryTokens: string[] = [];
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token === "--all" || token === "-a") {
+      includeAll = true;
+      continue;
+    }
+    if (token === "--projects" || token === "--project" || token === "-p") {
+      listProjects = true;
+      continue;
+    }
+    if (token === "--sync") {
+      syncTopic = true;
+      continue;
+    }
+    if (token === "--cwd") {
+      const next = tokens[index + 1]?.trim();
+      if (next) {
+        cwd = expandHomeDir(next);
+        index += 1;
+        continue;
+      }
+    }
+    queryTokens.push(token);
+  }
+
+  return {
+    includeAll,
+    listProjects,
+    syncTopic,
+    cwd,
+    query: queryTokens.join(" ").trim(),
+  };
+}
+
+function expandHomeDir(value: string): string {
+  if (value === "~") {
+    return os.homedir();
+  }
+  if (value.startsWith("~/")) {
+    return path.join(os.homedir(), value.slice(2));
+  }
+  return value;
+}
+
+export function selectThreadFromMatches(
+  threads: ThreadSummary[],
+  query: string,
+): ThreadSelectionResult {
+  const trimmedQuery = query.trim();
+  if (!trimmedQuery) {
+    return { kind: "none" };
+  }
+
+  if (threads.length === 0) {
+    return { kind: "none" };
+  }
+
+  const loweredQuery = trimmedQuery.toLowerCase();
+  const exactMatch =
+    threads.find((thread) => thread.threadId === trimmedQuery) ??
+    threads.find((thread) => thread.title?.trim().toLowerCase() === loweredQuery);
+
+  if (exactMatch) {
+    return { kind: "unique", thread: exactMatch };
+  }
+
+  if (threads.length === 1) {
+    return { kind: "unique", thread: threads[0] };
+  }
+
+  return { kind: "ambiguous", threads };
+}

package/src/types.ts

@@ -0,0 +1,372 @@
+import type { ConversationRef, PluginInteractiveButtons } from "openclaw/plugin-sdk";
+
+export const PLUGIN_ID = "openclaw-codex-app-server";
+export const INTERACTIVE_NAMESPACE = "codexapp";
+export const STORE_VERSION = 1;
+export const CALLBACK_TOKEN_BYTES = 9;
+export const CALLBACK_TTL_MS = 30 * 60_000;
+export const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
+export const DEFAULT_INPUT_TIMEOUT_MS = 15 * 60_000;
+
+export type CodexTransport = "stdio" | "websocket";
+
+export type PluginSettings = {
+  enabled: boolean;
+  transport: CodexTransport;
+  command: string;
+  args: string[];
+  url?: string;
+  headers?: Record<string, string>;
+  requestTimeoutMs: number;
+  inputTimeoutMs: number;
+  defaultWorkspaceDir?: string;
+  defaultModel?: string;
+  defaultServiceTier?: string;
+};
+
+export type CodexPlanStep = {
+  step: string;
+  status: "pending" | "inProgress" | "completed";
+};
+
+export type CodexPlanArtifact = {
+  explanation?: string;
+  steps: CodexPlanStep[];
+  markdown: string;
+};
+
+export type PendingApprovalDecision =
+  | "accept"
+  | "acceptForSession"
+  | "decline"
+  | "cancel";
+
+export type PendingInputAction =
+  | {
+      kind: "approval";
+      label: string;
+      decision: PendingApprovalDecision;
+      responseDecision: string;
+      proposedExecpolicyAmendment?: Record<string, unknown>;
+      sessionPrefix?: string;
+    }
+  | {
+      kind: "option";
+      label: string;
+      value: string;
+    }
+  | {
+      kind: "steer";
+      label: string;
+    };
+
+export type PendingQuestionnaireOption = {
+  key: string;
+  label: string;
+  description?: string;
+  recommended?: boolean;
+};
+
+export type PendingQuestionnaireAnswer =
+  | {
+      kind: "option";
+      optionKey: string;
+      optionLabel: string;
+    }
+  | {
+      kind: "text";
+      text: string;
+    };
+
+export type PendingQuestionnaireQuestion = {
+  index: number;
+  id: string;
+  header?: string;
+  prompt: string;
+  options: PendingQuestionnaireOption[];
+  guidance: string[];
+  allowFreeform?: boolean;
+};
+
+export type PendingQuestionnaireState = {
+  questions: PendingQuestionnaireQuestion[];
+  currentIndex: number;
+  answers: Array<PendingQuestionnaireAnswer | null>;
+  awaitingFreeform?: boolean;
+  responseMode?: "structured" | "compact";
+};
+
+export type PendingInputState = {
+  requestId: string;
+  options: string[];
+  actions?: PendingInputAction[];
+  expiresAt: number;
+  promptText?: string;
+  method?: string;
+  questionnaire?: PendingQuestionnaireState;
+};
+
+export type ThreadSummary = {
+  threadId: string;
+  title?: string;
+  summary?: string;
+  projectKey?: string;
+  createdAt?: number;
+  updatedAt?: number;
+  gitBranch?: string;
+};
+
+export type ModelSummary = {
+  id: string;
+  label?: string;
+  description?: string;
+  current?: boolean;
+};
+
+export type SkillSummary = {
+  cwd?: string;
+  name: string;
+  description?: string;
+  enabled?: boolean;
+};
+
+export type ExperimentalFeatureSummary = {
+  name: string;
+  stage?: string;
+  displayName?: string;
+  description?: string;
+  enabled?: boolean;
+  defaultEnabled?: boolean;
+};
+
+export type McpServerSummary = {
+  name: string;
+  authStatus?: string;
+  toolCount: number;
+  resourceCount: number;
+  resourceTemplateCount: number;
+};
+
+export type RateLimitSummary = {
+  name: string;
+  limitId?: string;
+  remaining?: number;
+  limit?: number;
+  used?: number;
+  usedPercent?: number;
+  resetAt?: number;
+  windowSeconds?: number;
+  windowMinutes?: number;
+};
+
+export type ThreadState = {
+  threadId: string;
+  threadName?: string;
+  model?: string;
+  modelProvider?: string;
+  serviceTier?: string;
+  cwd?: string;
+  approvalPolicy?: string;
+  sandbox?: string;
+  reasoningEffort?: string;
+};
+
+export type ThreadReplay = {
+  lastUserMessage?: string;
+  lastAssistantMessage?: string;
+};
+
+export type AccountSummary = {
+  type?: "apiKey" | "chatgpt";
+  email?: string;
+  planType?: string;
+  requiresOpenaiAuth?: boolean;
+};
+
+export type ContextUsageSnapshot = {
+  totalTokens?: number;
+  inputTokens?: number;
+  cachedInputTokens?: number;
+  outputTokens?: number;
+  reasoningOutputTokens?: number;
+  contextWindow?: number;
+  remainingTokens?: number;
+  remainingPercent?: number;
+};
+
+export type CompactProgress =
+  | {
+      phase: "started" | "completed";
+      itemId?: string;
+      usage?: ContextUsageSnapshot;
+    }
+  | {
+      phase: "usage";
+      usage: ContextUsageSnapshot;
+    };
+
+export type CompactResult = {
+  itemId?: string;
+  usage?: ContextUsageSnapshot;
+};
+
+export type ReviewTarget =
+  | { type: "uncommittedChanges" }
+  | { type: "custom"; instructions: string };
+
+export type CollaborationMode = {
+  mode: string;
+  settings?: {
+    model?: string;
+    reasoningEffort?: string;
+    developerInstructions?: string | null;
+  };
+};
+
+export type ReviewResult = {
+  reviewText: string;
+  reviewThreadId?: string;
+  turnId?: string;
+  aborted?: boolean;
+};
+
+export type TurnResult = {
+  threadId: string;
+  text?: string;
+  planArtifact?: CodexPlanArtifact;
+  aborted?: boolean;
+  usage?: ContextUsageSnapshot;
+};
+
+export type StoredBinding = {
+  conversation: ConversationRef;
+  sessionKey: string;
+  threadId: string;
+  workspaceDir: string;
+  threadTitle?: string;
+  contextUsage?: ContextUsageSnapshot;
+  updatedAt: number;
+};
+
+export type StoredPendingBind = {
+  conversation: ConversationRef;
+  threadId: string;
+  workspaceDir: string;
+  threadTitle?: string;
+  updatedAt: number;
+};
+
+export type StoredPendingRequest = {
+  requestId: string;
+  conversation: ConversationRef;
+  threadId: string;
+  workspaceDir: string;
+  state: PendingInputState;
+  updatedAt: number;
+};
+
+export type CallbackAction =
+  | {
+      token: string;
+      kind: "resume-thread";
+      conversation: ConversationRef;
+      threadId: string;
+      workspaceDir: string;
+      syncTopic?: boolean;
+      createdAt: number;
+      expiresAt: number;
+    }
+  | {
+      token: string;
+      kind: "pending-input";
+      conversation: ConversationRef;
+      requestId: string;
+      actionIndex: number;
+      createdAt: number;
+      expiresAt: number;
+    }
+  | {
+      token: string;
+      kind: "pending-questionnaire";
+      conversation: ConversationRef;
+      requestId: string;
+      questionIndex: number;
+      action: "select" | "prev" | "next" | "freeform";
+      optionIndex?: number;
+      createdAt: number;
+      expiresAt: number;
+    }
+  | {
+      token: string;
+      kind: "picker-view";
+      conversation: ConversationRef;
+      view:
+        | {
+            mode: "threads";
+            includeAll: boolean;
+            page: number;
+            syncTopic?: boolean;
+            query?: string;
+            workspaceDir?: string;
+            projectName?: string;
+          }
+        | {
+            mode: "projects";
+            includeAll: boolean;
+            page: number;
+            syncTopic?: boolean;
+            query?: string;
+            workspaceDir?: string;
+          };
+      createdAt: number;
+      expiresAt: number;
+    }
+  | {
+      token: string;
+      kind: "run-prompt";
+      conversation: ConversationRef;
+      prompt: string;
+      workspaceDir?: string;
+      collaborationMode?: CollaborationMode;
+      createdAt: number;
+      expiresAt: number;
+    }
+  | {
+      token: string;
+      kind: "set-model";
+      conversation: ConversationRef;
+      model: string;
+      createdAt: number;
+      expiresAt: number;
+    }
+  | {
+      token: string;
+      kind: "reply-text";
+      conversation: ConversationRef;
+      text: string;
+      createdAt: number;
+      expiresAt: number;
+    }
+  | {
+      token: string;
+      kind: "rename-thread";
+      conversation: ConversationRef;
+      style: "thread-project" | "thread";
+      syncTopic: boolean;
+      createdAt: number;
+      expiresAt: number;
+    };
+
+export type StoreSnapshot = {
+  version: number;
+  bindings: StoredBinding[];
+  pendingBinds: StoredPendingBind[];
+  pendingRequests: StoredPendingRequest[];
+  callbacks: CallbackAction[];
+};
+
+export type ConversationTarget = ConversationRef & {
+  threadId?: number;
+};
+
+export type CommandButtons = PluginInteractiveButtons;

package/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": [
+      "ES2023"
+    ],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": [
+      "node",
+      "vitest/globals"
+    ]
+  },
+  "include": [
+    "index.ts",
+    "src/**/*.ts",
+    "src/**/*.d.ts"
+  ]
+}