@posthog/agent 1.30.0 → 2.0.1

package/src/adapters/claude/questions/utils.ts

@@ -0,0 +1,92 @@
+import type { ToolCallContent, ToolKind } from "@agentclientprotocol/sdk";
+import { z } from "zod";
+import type { PermissionOption } from "../permissions/permission-options.js";
+
+export const OPTION_PREFIX = "option_";
+
+export const QuestionOptionSchema = z.object({
+  label: z.string(),
+  description: z.string().optional(),
+});
+
+export const QuestionItemSchema = z.object({
+  question: z.string(),
+  header: z.string().optional(),
+  options: z.array(QuestionOptionSchema),
+  multiSelect: z.boolean().optional(),
+  completed: z.boolean().optional(),
+});
+
+export const QuestionMetaSchema = z.object({
+  questions: z.array(QuestionItemSchema),
+});
+
+export type QuestionOption = z.infer<typeof QuestionOptionSchema>;
+export type QuestionItem = z.infer<typeof QuestionItemSchema>;
+export type QuestionMeta = z.infer<typeof QuestionMetaSchema>;
+
+export interface AskUserQuestionInput {
+  questions?: QuestionItem[];
+  question?: string;
+  header?: string;
+  options?: QuestionOption[];
+  multiSelect?: boolean;
+}
+
+export function normalizeAskUserQuestionInput(
+  input: AskUserQuestionInput,
+): QuestionItem[] | null {
+  if (input.questions && input.questions.length > 0) {
+    return input.questions;
+  }
+
+  if (input.question) {
+    return [
+      {
+        question: input.question,
+        header: input.header,
+        options: input.options || [],
+        multiSelect: input.multiSelect,
+      },
+    ];
+  }
+
+  return null;
+}
+
+interface QuestionToolCallData {
+  toolCallId: string;
+  title: string;
+  kind: ToolKind;
+  content: ToolCallContent[];
+  _meta: {
+    twigToolKind: "question";
+    questions: QuestionItem[];
+  };
+}
+
+export function buildQuestionToolCallData(
+  questions: QuestionItem[],
+): QuestionToolCallData {
+  return {
+    toolCallId: `question-${Date.now()}`,
+    title: questions[0]?.question ?? "Question",
+    kind: "other",
+    content: [],
+    _meta: {
+      twigToolKind: "question",
+      questions,
+    },
+  };
+}
+
+export function buildQuestionOptions(
+  question: QuestionItem,
+): PermissionOption[] {
+  return question.options.map((opt, idx) => ({
+    kind: "allow_once" as const,
+    name: opt.label,
+    optionId: `${OPTION_PREFIX}${idx}`,
+    _meta: opt.description ? { description: opt.description } : undefined,
+  }));
+}

package/src/adapters/claude/session/commands.ts

@@ -0,0 +1,38 @@
+import type { AvailableCommand } from "@agentclientprotocol/sdk";
+import type { Query } from "@anthropic-ai/claude-agent-sdk";
+
+const UNSUPPORTED_COMMANDS = [
+  "context",
+  "cost",
+  "login",
+  "logout",
+  "output-style:new",
+  "release-notes",
+  "todos",
+];
+
+export async function getAvailableSlashCommands(
+  q: Query,
+): Promise<AvailableCommand[]> {
+  const commands = await q.supportedCommands();
+
+  return commands
+    .map((command) => {
+      const input = command.argumentHint
+        ? { hint: command.argumentHint }
+        : null;
+      let name = command.name;
+      if (command.name.endsWith(" (MCP)")) {
+        name = `mcp:${name.replace(" (MCP)", "")}`;
+      }
+      return {
+        name,
+        description: command.description || "",
+        input,
+      };
+    })
+    .filter(
+      (command: AvailableCommand) =>
+        !UNSUPPORTED_COMMANDS.includes(command.name),
+    );
+}

package/src/adapters/claude/session/mcp-config.ts

@@ -0,0 +1,37 @@
+import type {
+  LoadSessionRequest,
+  NewSessionRequest,
+} from "@agentclientprotocol/sdk";
+import type { McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
+
+export function parseMcpServers(
+  params: NewSessionRequest | LoadSessionRequest,
+): Record<string, McpServerConfig> {
+  const mcpServers: Record<string, McpServerConfig> = {};
+  if (!Array.isArray(params.mcpServers)) {
+    return mcpServers;
+  }
+
+  for (const server of params.mcpServers) {
+    if ("type" in server) {
+      mcpServers[server.name] = {
+        type: server.type,
+        url: server.url,
+        headers: server.headers
+          ? Object.fromEntries(server.headers.map((e) => [e.name, e.value]))
+          : undefined,
+      };
+    } else {
+      mcpServers[server.name] = {
+        type: "stdio",
+        command: server.command,
+        args: server.args,
+        env: server.env
+          ? Object.fromEntries(server.env.map((e) => [e.name, e.value]))
+          : undefined,
+      };
+    }
+  }
+
+  return mcpServers;
+}

package/src/adapters/claude/session/models.ts

@@ -0,0 +1,12 @@
+export const DEFAULT_MODEL = "opus";
+
+const GATEWAY_TO_SDK_MODEL: Record<string, string> = {
+  "claude-opus-4-5": "opus",
+  "claude-opus-4-6": "opus",
+  "claude-sonnet-4-5": "sonnet",
+  "claude-haiku-4-5": "haiku",
+};
+
+export function toSdkModelId(modelId: string): string {
+  return GATEWAY_TO_SDK_MODEL[modelId] ?? modelId;
+}

package/src/adapters/claude/session/options.ts

@@ -0,0 +1,236 @@
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type {
+  McpServerConfig,
+  Options,
+  SpawnedProcess,
+  SpawnOptions,
+} from "@anthropic-ai/claude-agent-sdk";
+import { IS_ROOT } from "../../../utils/common.js";
+import type { Logger } from "../../../utils/logger.js";
+import { createPostToolUseHook, type OnModeChange } from "../hooks.js";
+import type { TwigExecutionMode } from "../tools.js";
+
+export interface ProcessSpawnedInfo {
+  pid: number;
+  command: string;
+  sessionId: string;
+}
+
+export interface BuildOptionsParams {
+  cwd: string;
+  mcpServers: Record<string, McpServerConfig>;
+  permissionMode: TwigExecutionMode;
+  canUseTool: Options["canUseTool"];
+  logger: Logger;
+  systemPrompt?: Options["systemPrompt"];
+  userProvidedOptions?: Options;
+  sessionId?: string;
+  additionalDirectories?: string[];
+  onModeChange?: OnModeChange;
+  onProcessSpawned?: (info: ProcessSpawnedInfo) => void;
+  onProcessExited?: (pid: number) => void;
+}
+
+const BRANCH_NAMING_INSTRUCTIONS = `
+# Branch Naming
+
+Before pushing a "workspace-*" branch to origin, rename it to something descriptive based on the work done. Do this automatically without asking the user.
+`;
+
+export function buildSystemPrompt(
+  customPrompt?: unknown,
+): Options["systemPrompt"] {
+  const defaultPrompt: Options["systemPrompt"] = {
+    type: "preset",
+    preset: "claude_code",
+    append: BRANCH_NAMING_INSTRUCTIONS,
+  };
+
+  if (!customPrompt) {
+    return defaultPrompt;
+  }
+
+  if (typeof customPrompt === "string") {
+    return customPrompt + BRANCH_NAMING_INSTRUCTIONS;
+  }
+
+  if (
+    typeof customPrompt === "object" &&
+    customPrompt !== null &&
+    "append" in customPrompt &&
+    typeof customPrompt.append === "string"
+  ) {
+    return {
+      ...defaultPrompt,
+      append: customPrompt.append + BRANCH_NAMING_INSTRUCTIONS,
+    };
+  }
+
+  return defaultPrompt;
+}
+
+function buildMcpServers(
+  userServers: Record<string, McpServerConfig> | undefined,
+  acpServers: Record<string, McpServerConfig>,
+): Record<string, McpServerConfig> {
+  return {
+    ...(userServers || {}),
+    ...acpServers,
+  };
+}
+
+function buildEnvironment(): Record<string, string> {
+  return {
+    ...process.env,
+    ELECTRON_RUN_AS_NODE: "1",
+    CLAUDE_CODE_ENABLE_ASK_USER_QUESTION_TOOL: "true",
+  };
+}
+
+function buildHooks(
+  userHooks: Options["hooks"],
+  onModeChange?: OnModeChange,
+): Options["hooks"] {
+  return {
+    ...userHooks,
+    PostToolUse: [
+      ...(userHooks?.PostToolUse || []),
+      {
+        hooks: [createPostToolUseHook({ onModeChange })],
+      },
+    ],
+  };
+}
+
+function getAbortController(
+  userProvidedController: AbortController | undefined,
+): AbortController {
+  const controller = userProvidedController ?? new AbortController();
+  if (controller.signal.aborted) {
+    throw new Error("Cancelled");
+  }
+  return controller;
+}
+
+function buildSpawnWrapper(
+  sessionId: string,
+  onProcessSpawned: (info: ProcessSpawnedInfo) => void,
+  onProcessExited?: (pid: number) => void,
+): (options: SpawnOptions) => SpawnedProcess {
+  return (spawnOpts: SpawnOptions): SpawnedProcess => {
+    const child = spawn(spawnOpts.command, spawnOpts.args, {
+      cwd: spawnOpts.cwd,
+      env: spawnOpts.env as NodeJS.ProcessEnv,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+
+    if (child.pid) {
+      onProcessSpawned({
+        pid: child.pid,
+        command: `${spawnOpts.command} ${spawnOpts.args.join(" ")}`,
+        sessionId,
+      });
+    }
+
+    if (onProcessExited) {
+      child.on("exit", () => {
+        if (child.pid) {
+          onProcessExited(child.pid);
+        }
+      });
+    }
+
+    // Listen for abort signal
+    if (spawnOpts.signal) {
+      spawnOpts.signal.addEventListener("abort", () => {
+        child.kill("SIGTERM");
+      });
+    }
+
+    return {
+      stdin: child.stdin!,
+      stdout: child.stdout!,
+      get killed() {
+        return child.killed;
+      },
+      get exitCode() {
+        return child.exitCode;
+      },
+      kill(signal: NodeJS.Signals) {
+        return child.kill(signal);
+      },
+      on(event: "exit" | "error", listener: (...args: any[]) => void) {
+        child.on(event, listener);
+      },
+      once(event: "exit" | "error", listener: (...args: any[]) => void) {
+        child.once(event, listener);
+      },
+      off(event: "exit" | "error", listener: (...args: any[]) => void) {
+        child.off(event, listener);
+      },
+    };
+  };
+}
+
+export function buildSessionOptions(params: BuildOptionsParams): Options {
+  const options: Options = {
+    ...params.userProvidedOptions,
+    systemPrompt: params.systemPrompt ?? buildSystemPrompt(),
+    settingSources: ["user", "project", "local"],
+    stderr: (err) => params.logger.error(err),
+    cwd: params.cwd,
+    includePartialMessages: true,
+    allowDangerouslySkipPermissions: !IS_ROOT,
+    permissionMode: params.permissionMode,
+    canUseTool: params.canUseTool,
+    executable: "node",
+    mcpServers: buildMcpServers(
+      params.userProvidedOptions?.mcpServers,
+      params.mcpServers,
+    ),
+    env: buildEnvironment(),
+    hooks: buildHooks(params.userProvidedOptions?.hooks, params.onModeChange),
+    abortController: getAbortController(
+      params.userProvidedOptions?.abortController,
+    ),
+    ...(params.onProcessSpawned && {
+      spawnClaudeCodeProcess: buildSpawnWrapper(
+        params.sessionId ?? "unknown",
+        params.onProcessSpawned,
+        params.onProcessExited,
+      ),
+    }),
+  };
+
+  if (process.env.CLAUDE_CODE_EXECUTABLE) {
+    options.pathToClaudeCodeExecutable = process.env.CLAUDE_CODE_EXECUTABLE;
+  }
+
+  if (params.sessionId) {
+    options.resume = params.sessionId;
+  }
+
+  if (params.additionalDirectories) {
+    options.additionalDirectories = params.additionalDirectories;
+  }
+
+  clearStatsigCache();
+  return options;
+}
+
+function clearStatsigCache(): void {
+  const statsigPath = path.join(
+    process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude"),
+    "statsig",
+  );
+  try {
+    if (fs.existsSync(statsigPath)) {
+      fs.rmSync(statsigPath, { recursive: true, force: true });
+    }
+  } catch {
+    // Ignore errors - cache clearing is best-effort
+  }
+}

package/src/adapters/claude/tool-meta.ts

@@ -0,0 +1,143 @@
+import { z } from "zod";
+
+const QuestionOptionSchema = z.object({
+  label: z.string(),
+  description: z.string().optional(),
+});
+
+const QuestionItemSchema = z.object({
+  question: z.string(),
+  header: z.string().optional(),
+  options: z.array(QuestionOptionSchema),
+  multiSelect: z.boolean().optional(),
+  completed: z.boolean().optional(),
+});
+
+export const QuestionMetaSchema = z.object({
+  questions: z.array(QuestionItemSchema),
+});
+
+export type QuestionOption = z.infer<typeof QuestionOptionSchema>;
+export type QuestionItem = z.infer<typeof QuestionItemSchema>;
+export type QuestionMeta = z.infer<typeof QuestionMetaSchema>;
+
+const toolSchemas = {
+  bash: z.object({
+    command: z.string(),
+    description: z.string().optional(),
+  }),
+  edit: z.object({
+    file_path: z.string(),
+    old_string: z.string(),
+    new_string: z.string(),
+    replace_all: z.boolean().optional(),
+  }),
+  write: z.object({
+    file_path: z.string(),
+    content: z.string(),
+  }),
+  read: z.object({
+    file_path: z.string(),
+    offset: z.number().optional(),
+    limit: z.number().optional(),
+  }),
+  switch_mode: z.object({
+    plan: z.string().optional(),
+  }),
+} as const;
+
+type ToolKind = keyof typeof toolSchemas;
+const _toolKinds = Object.keys(toolSchemas) as ToolKind[];
+
+const sdkToolNameToKind: Record<string, ToolKind> = {
+  Bash: "bash",
+  Edit: "edit",
+  Write: "write",
+  Read: "read",
+  ExitPlanMode: "switch_mode",
+};
+
+const BaseTwigToolMetaSchema = z.object({
+  claudeCode: z
+    .object({
+      toolName: z.string(),
+      toolResponse: z.unknown().optional(),
+    })
+    .optional(),
+});
+
+type BaseMeta = z.infer<typeof BaseTwigToolMetaSchema>;
+
+type ToolMeta<K extends ToolKind> = BaseMeta & {
+  twigToolKind: K;
+} & { [P in K]: z.infer<(typeof toolSchemas)[K]> };
+
+export type BashToolMeta = ToolMeta<"bash">;
+export type EditToolMeta = ToolMeta<"edit">;
+export type WriteToolMeta = ToolMeta<"write">;
+export type ReadToolMeta = ToolMeta<"read">;
+export type SwitchModeToolMeta = ToolMeta<"switch_mode">;
+export type QuestionToolMeta = BaseMeta & {
+  twigToolKind: "question";
+  questions: QuestionItem[];
+};
+export type GenericToolMeta = BaseMeta & { twigToolKind?: undefined };
+
+export type TwigToolMeta =
+  | BashToolMeta
+  | EditToolMeta
+  | WriteToolMeta
+  | ReadToolMeta
+  | SwitchModeToolMeta
+  | QuestionToolMeta
+  | GenericToolMeta;
+
+export function isBashToolMeta(meta: TwigToolMeta): meta is BashToolMeta {
+  return meta.twigToolKind === "bash";
+}
+
+export function isEditToolMeta(meta: TwigToolMeta): meta is EditToolMeta {
+  return meta.twigToolKind === "edit";
+}
+
+export function isWriteToolMeta(meta: TwigToolMeta): meta is WriteToolMeta {
+  return meta.twigToolKind === "write";
+}
+
+export function isReadToolMeta(meta: TwigToolMeta): meta is ReadToolMeta {
+  return meta.twigToolKind === "read";
+}
+
+export function isSwitchModeToolMeta(
+  meta: TwigToolMeta,
+): meta is SwitchModeToolMeta {
+  return meta.twigToolKind === "switch_mode";
+}
+
+export function isQuestionToolMeta(
+  meta: TwigToolMeta,
+): meta is QuestionToolMeta {
+  return meta.twigToolKind === "question";
+}
+
+export function buildToolMeta(
+  toolName: string,
+  input: Record<string, unknown>,
+): TwigToolMeta {
+  const kind = sdkToolNameToKind[toolName];
+  if (!kind) {
+    return { claudeCode: { toolName } };
+  }
+
+  const schema = toolSchemas[kind];
+  const result = schema.safeParse(input);
+  if (!result.success) {
+    return { claudeCode: { toolName } };
+  }
+
+  return {
+    claudeCode: { toolName },
+    twigToolKind: kind,
+    [kind]: result.data,
+  } as TwigToolMeta;
+}