@posthog/agent 2.0.0 → 2.0.1

package/src/execution-mode.ts

@@ -0,0 +1,43 @@
+import { IS_ROOT } from "./utils/common.js";
+
+export interface ModeInfo {
+  id: TwigExecutionMode;
+  name: string;
+  description: string;
+}
+
+const MODES: ModeInfo[] = [
+  {
+    id: "default",
+    name: "Always Ask",
+    description: "Prompts for permission on first use of each tool",
+  },
+  {
+    id: "acceptEdits",
+    name: "Accept Edits",
+    description: "Automatically accepts file edit permissions for the session",
+  },
+  {
+    id: "plan",
+    name: "Plan Mode",
+    description: "Claude can analyze but not modify files or execute commands",
+  },
+  {
+    id: "bypassPermissions",
+    name: "Bypass Permissions",
+    description: "Skips all permission prompts",
+  },
+];
+
+export const TWIG_EXECUTION_MODES = [
+  "default",
+  "acceptEdits",
+  "plan",
+  "bypassPermissions",
+] as const;
+
+export type TwigExecutionMode = (typeof TWIG_EXECUTION_MODES)[number];
+
+export function getAvailableModes(): ModeInfo[] {
+  return IS_ROOT ? MODES.filter((m) => m.id !== "bypassPermissions") : MODES;
+}

package/src/gateway-models.ts

@@ -0,0 +1,135 @@
+export interface GatewayModel {
+  id: string;
+  owned_by: string;
+  context_window: number;
+  supports_streaming: boolean;
+  supports_vision: boolean;
+}
+
+interface GatewayModelsResponse {
+  object: "list";
+  data: GatewayModel[];
+}
+
+export interface FetchGatewayModelsOptions {
+  gatewayUrl: string;
+}
+
+export const DEFAULT_GATEWAY_MODEL = "claude-opus-4-6";
+
+export const BLOCKED_MODELS = new Set(["gpt-5-mini", "openai/gpt-5-mini"]);
+
+type ArrayModelsResponse =
+  | {
+      data?: Array<{ id?: string; owned_by?: string }>;
+      models?: Array<{ id?: string; owned_by?: string }>;
+    }
+  | Array<{ id?: string; owned_by?: string }>;
+
+export async function fetchGatewayModels(
+  options?: FetchGatewayModelsOptions,
+): Promise<GatewayModel[]> {
+  const gatewayUrl = options?.gatewayUrl ?? process.env.ANTHROPIC_BASE_URL;
+  if (!gatewayUrl) {
+    return [];
+  }
+
+  const modelsUrl = `${gatewayUrl}/v1/models`;
+
+  try {
+    const response = await fetch(modelsUrl);
+
+    if (!response.ok) {
+      return [];
+    }
+
+    const data = (await response.json()) as GatewayModelsResponse;
+    const models = data.data ?? [];
+    return models.filter((m) => !BLOCKED_MODELS.has(m.id));
+  } catch {
+    return [];
+  }
+}
+
+export function isAnthropicModel(model: GatewayModel): boolean {
+  if (model.owned_by) {
+    return model.owned_by === "anthropic";
+  }
+  return model.id.startsWith("claude-") || model.id.startsWith("anthropic/");
+}
+
+export async function fetchArrayModelIds(
+  options?: FetchGatewayModelsOptions,
+): Promise<string[]> {
+  const models = await fetchArrayModels(options);
+  return models.map((model) => model.id);
+}
+
+export interface ArrayModelInfo {
+  id: string;
+  owned_by?: string;
+}
+
+export async function fetchArrayModels(
+  options?: FetchGatewayModelsOptions,
+): Promise<ArrayModelInfo[]> {
+  const gatewayUrl = options?.gatewayUrl ?? process.env.ANTHROPIC_BASE_URL;
+  if (!gatewayUrl) {
+    return [];
+  }
+
+  try {
+    const base = new URL(gatewayUrl);
+    base.pathname = "/array/v1/models";
+    base.search = "";
+    base.hash = "";
+    const response = await fetch(base.toString());
+    if (!response.ok) {
+      return [];
+    }
+    const data = (await response.json()) as ArrayModelsResponse;
+    const models = Array.isArray(data)
+      ? data
+      : (data.data ?? data.models ?? []);
+    const results: ArrayModelInfo[] = [];
+    for (const model of models) {
+      const id = model?.id ? String(model.id) : "";
+      if (!id) continue;
+      results.push({ id, owned_by: model?.owned_by });
+    }
+    return results;
+  } catch {
+    return [];
+  }
+}
+
+const PROVIDER_NAMES: Record<string, string> = {
+  anthropic: "Anthropic",
+  openai: "OpenAI",
+  "google-vertex": "Gemini",
+};
+
+export function getProviderName(ownedBy: string): string {
+  return PROVIDER_NAMES[ownedBy] ?? ownedBy;
+}
+
+const PROVIDER_PREFIXES = ["anthropic/", "openai/", "google-vertex/"];
+
+export function formatGatewayModelName(model: GatewayModel): string {
+  let cleanId = model.id;
+  for (const prefix of PROVIDER_PREFIXES) {
+    if (cleanId.startsWith(prefix)) {
+      cleanId = cleanId.slice(prefix.length);
+      break;
+    }
+  }
+
+  cleanId = cleanId.replace(/(\d)-(\d)/g, "$1.$2");
+
+  const words = cleanId.split(/[-_]/).map((word) => {
+    if (word.match(/^[0-9.]+$/)) return word;
+    return word.charAt(0).toUpperCase() + word.slice(1).toLowerCase();
+  });
+
+  return words.join(" ");
+}

package/src/index.ts

@@ -0,0 +1,79 @@
+export type {
+  BranchCreatedPayload,
+  CompactBoundaryPayload,
+  ConsoleNotificationPayload,
+  ErrorNotificationPayload,
+  ModeChangePayload,
+  PostHogNotificationPayload,
+  PostHogNotificationType,
+  RunStartedPayload,
+  SdkSessionPayload,
+  SessionResumePayload,
+  StatusPayload,
+  TaskCompletePayload,
+  TaskNotificationPayload,
+  TreeSnapshotPayload,
+  UserMessagePayload,
+} from "./acp-extensions.js";
+export { POSTHOG_NOTIFICATIONS } from "./acp-extensions.js";
+export type {
+  AcpConnection,
+  AcpConnectionConfig,
+  AgentAdapter,
+  InProcessAcpConnection,
+} from "./adapters/acp-connection.js";
+export { createAcpConnection } from "./adapters/acp-connection.js";
+export {
+  fetchMcpToolMetadata,
+  isMcpToolReadOnly,
+} from "./adapters/claude/mcp/tool-metadata.js";
+export type { CodexProcessOptions } from "./adapters/codex/spawn.js";
+export { Agent } from "./agent.js";
+export {
+  type ArrayModelInfo,
+  BLOCKED_MODELS,
+  DEFAULT_GATEWAY_MODEL,
+  type FetchGatewayModelsOptions,
+  fetchArrayModels,
+  fetchGatewayModels,
+  formatGatewayModelName,
+  type GatewayModel,
+  getProviderName,
+  isAnthropicModel,
+} from "./gateway-models.js";
+export type { OtelLogConfig, SessionContext } from "./otel-log-writer.js";
+export { OtelLogWriter } from "./otel-log-writer.js";
+export { PostHogAPIClient } from "./posthog-api.js";
+export type {
+  ConversationTurn,
+  ResumeConfig,
+  ResumeState,
+  ToolCallInfo,
+} from "./resume.js";
+export { conversationToPromptHistory, resumeFromLog } from "./resume.js";
+export type { SessionLogWriterOptions } from "./session-log-writer.js";
+export { SessionLogWriter } from "./session-log-writer.js";
+export type { TreeSnapshot, TreeTrackerConfig } from "./tree-tracker.js";
+export {
+  isCommitOnRemote,
+  TreeTracker,
+  validateForCloudHandoff,
+} from "./tree-tracker.js";
+export type {
+  AgentConfig,
+  AgentMode,
+  DeviceInfo,
+  FileChange,
+  FileStatus,
+  LogLevel,
+  OnLogCallback,
+  OtelTransportConfig,
+  StoredEntry,
+  StoredNotification,
+  Task,
+  TaskRun,
+  TreeSnapshotEvent,
+} from "./types.js";
+export { getLlmGatewayUrl } from "./utils/gateway.js";
+export type { LoggerConfig } from "./utils/logger.js";
+export { Logger } from "./utils/logger.js";

package/src/otel-log-writer.test.ts

@@ -0,0 +1,105 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { OtelLogWriter } from "./otel-log-writer.js";
+import type { StoredNotification } from "./types.js";
+
+// Mock the OTEL exporter
+const mockExport = vi.fn((_logs, callback) => {
+  callback({ code: 0 }); // Success
+});
+
+vi.mock("@opentelemetry/exporter-logs-otlp-http", () => ({
+  OTLPLogExporter: vi.fn().mockImplementation(() => ({
+    export: mockExport,
+    shutdown: vi.fn().mockResolvedValue(undefined),
+  })),
+}));
+
+describe("OtelLogWriter", () => {
+  let writer: OtelLogWriter;
+
+  beforeEach(() => {
+    mockExport.mockClear();
+    // Session context (taskId, runId) is now passed in constructor as resource attributes
+    writer = new OtelLogWriter(
+      {
+        posthogHost: "https://us.i.posthog.com",
+        apiKey: "phc_test_key",
+        flushIntervalMs: 100,
+      },
+      {
+        taskId: "task-123",
+        runId: "run-456",
+      },
+    );
+  });
+
+  afterEach(async () => {
+    await writer.shutdown();
+  });
+
+  it("should emit a log entry with event_type as regular attribute", async () => {
+    const notification: StoredNotification = {
+      type: "notification",
+      timestamp: new Date().toISOString(),
+      notification: {
+        jsonrpc: "2.0",
+        method: "_posthog/test_event",
+        params: { foo: "bar" },
+      },
+    };
+
+    // taskId and runId are now resource attributes set in constructor,
+    // only notification is passed per-emit
+    writer.emit({ notification });
+
+    // Force flush to trigger export
+    await writer.flush();
+
+    // Verify export was called
+    expect(mockExport).toHaveBeenCalled();
+
+    // Get the logs that were exported
+    const exportedLogs = mockExport.mock.calls[0][0];
+    expect(exportedLogs.length).toBe(1);
+
+    const log = exportedLogs[0];
+    // task_id and run_id are now resource attributes, not regular attributes
+    expect(log.attributes.task_id).toBeUndefined();
+    expect(log.attributes.run_id).toBeUndefined();
+    // event_type is still a regular attribute (varies per log entry)
+    expect(log.attributes.event_type).toBe("_posthog/test_event");
+    expect(log.body).toBe(JSON.stringify(notification));
+
+    // Verify resource attributes contain task_id and run_id
+    expect(log.resource.attributes.task_id).toBe("task-123");
+    expect(log.resource.attributes.run_id).toBe("run-456");
+    expect(log.resource.attributes["service.name"]).toBe("twig-agent");
+  });
+
+  it("should batch multiple log entries", async () => {
+    const makeNotification = (method: string): StoredNotification => ({
+      type: "notification",
+      timestamp: new Date().toISOString(),
+      notification: {
+        jsonrpc: "2.0",
+        method,
+      },
+    });
+
+    writer.emit({ notification: makeNotification("event_1") });
+    writer.emit({ notification: makeNotification("event_2") });
+    writer.emit({ notification: makeNotification("event_3") });
+
+    await writer.flush();
+
+    expect(mockExport).toHaveBeenCalled();
+    const exportedLogs = mockExport.mock.calls[0][0];
+    expect(exportedLogs.length).toBe(3);
+
+    // All logs should share the same resource attributes
+    for (const log of exportedLogs) {
+      expect(log.resource.attributes.task_id).toBe("task-123");
+      expect(log.resource.attributes.run_id).toBe("run-456");
+    }
+  });
+});

package/src/otel-log-writer.ts

@@ -0,0 +1,94 @@
+import { SeverityNumber } from "@opentelemetry/api-logs";
+import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import {
+  BatchLogRecordProcessor,
+  LoggerProvider,
+} from "@opentelemetry/sdk-logs";
+import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
+import type { StoredNotification } from "./types.js";
+import type { Logger } from "./utils/logger.js";
+
+export interface OtelLogConfig {
+  /** PostHog ingest host, e.g., "https://us.i.posthog.com" */
+  posthogHost: string;
+  /** Project API key, e.g., "phc_xxx" */
+  apiKey: string;
+  /** Batch flush interval in ms (default: 500) */
+  flushIntervalMs?: number;
+  /** Override the logs endpoint path (default: /i/v1/agent-logs) */
+  logsPath?: string;
+}
+
+/**
+ * Session context for resource attributes.
+ * These are set once per OTEL logger instance and indexed via resource_fingerprint
+ */
+export interface SessionContext {
+  /** Parent task grouping - all runs for a task share this */
+  taskId: string;
+  /** Primary conversation identifier - all events in a run share this */
+  runId: string;
+  /** Deployment environment - "local" for desktop, "cloud" for cloud sandbox */
+  deviceType?: "local" | "cloud";
+}
+
+export class OtelLogWriter {
+  private loggerProvider: LoggerProvider;
+  private logger: ReturnType<LoggerProvider["getLogger"]>;
+
+  constructor(
+    config: OtelLogConfig,
+    sessionContext: SessionContext,
+    _debugLogger?: Logger,
+  ) {
+    const logsPath = config.logsPath ?? "/i/v1/agent-logs";
+    const exporter = new OTLPLogExporter({
+      url: `${config.posthogHost}${logsPath}`,
+      headers: { Authorization: `Bearer ${config.apiKey}` },
+    });
+
+    const processor = new BatchLogRecordProcessor(exporter, {
+      scheduledDelayMillis: config.flushIntervalMs ?? 500,
+    });
+
+    // Resource attributes are set ONCE per session and indexed via resource_fingerprint
+    // So we have fast queries by run_id/task_id in PostHog Logs UI
+    this.loggerProvider = new LoggerProvider({
+      resource: resourceFromAttributes({
+        [ATTR_SERVICE_NAME]: "twig-agent",
+        run_id: sessionContext.runId,
+        task_id: sessionContext.taskId,
+        device_type: sessionContext.deviceType ?? "local",
+      }),
+      processors: [processor],
+    });
+
+    this.logger = this.loggerProvider.getLogger("agent-session");
+  }
+
+  /**
+   * Emit an agent event to PostHog Logs via OTEL.
+   */
+  emit(entry: { notification: StoredNotification }): void {
+    const { notification } = entry;
+    const eventType = notification.notification.method;
+
+    this.logger.emit({
+      severityNumber: SeverityNumber.INFO,
+      severityText: "INFO",
+      body: JSON.stringify(notification),
+      attributes: {
+        event_type: eventType,
+      },
+    });
+  }
+
+  async flush(): Promise<void> {
+    await this.loggerProvider.forceFlush();
+  }
+
+  async shutdown(): Promise<void> {
+    await this.loggerProvider.shutdown();
+  }
+}