@posthog/agent 2.1.47 → 2.1.53

package/dist/types.d.ts

@@ -103,6 +103,8 @@ interface AgentConfig {
     otelTransport?: OtelTransportConfig;
     /** Skip session log persistence (e.g. for preview sessions with no real task) */
     skipLogPersistence?: boolean;
+    /** Local cache path for instant log loading (e.g., ~/.twig) */
+    localCachePath?: string;
     debug?: boolean;
     onLog?: OnLogCallback;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posthog/agent",
-  "version": "2.1.47",
+  "version": "2.1.53",
   "repository": "https://github.com/PostHog/twig",
   "description": "TypeScript agent framework wrapping Claude Agent SDK with Git-based task execution for PostHog",
   "exports": {

package/src/adapters/acp-connection.ts

@@ -23,8 +23,6 @@ export type AcpConnectionConfig = {
   /** Deployment environment - "local" for desktop, "cloud" for cloud sandbox */
   deviceType?: "local" | "cloud";
   logger?: Logger;
-  /** Enable dev-only instrumentation (timing, verbose logging) */
-  debug?: boolean;
   processCallbacks?: ProcessSpawnedCallback;
   codexOptions?: CodexProcessOptions;
   allowedModelIds?: Set<string>;
@@ -196,10 +194,7 @@ function createClaudeConnection(config: AcpConnectionConfig): AcpConnection {
 
   let agent: ClaudeAcpAgent | null = null;
   const agentConnection = new AgentSideConnection((client) => {
-    agent = new ClaudeAcpAgent(client, logWriter, {
-      ...config.processCallbacks,
-      debug: config.debug,
-    });
+    agent = new ClaudeAcpAgent(client, logWriter, config.processCallbacks);
     logger.info(`Created ${agent.adapterName} agent`);
     return agent;
   }, agentStream);

package/src/adapters/claude/claude-agent.ts

@@ -29,7 +29,6 @@ import {
   type SDKMessage,
   type SDKUserMessage,
 } from "@anthropic-ai/claude-agent-sdk";
-import { createTimingCollector } from "@posthog/shared";
 import { v7 as uuidv7 } from "uuid";
 import packageJson from "../../../package.json" with { type: "json" };
 import type { SessionContext } from "../../otel-log-writer.js";
@@ -70,8 +69,6 @@ import type {
 export interface ClaudeAcpAgentOptions {
   onProcessSpawned?: (info: ProcessSpawnedInfo) => void;
   onProcessExited?: (pid: number) => void;
-  /** Enable dev-only instrumentation (timing, verbose logging) */
-  debug?: boolean;
 }
 
 export class ClaudeAcpAgent extends BaseAcpAgent {
@@ -83,7 +80,6 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
   private logWriter?: SessionLogWriter;
   private options?: ClaudeAcpAgentOptions;
   private lastSentConfigOptions?: SessionConfigOption[];
-  private debug: boolean;
 
   constructor(
     client: AgentSideConnection,
@@ -93,7 +89,6 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
     super(client);
     this.logWriter = logWriter;
     this.options = options;
-    this.debug = options?.debug ?? false;
     this.toolUseCache = {};
     this.logger = new Logger({ debug: true, prefix: "[ClaudeAcpAgent]" });
   }
@@ -141,10 +136,6 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
   async newSession(params: NewSessionRequest): Promise<NewSessionResponse> {
     this.checkAuthStatus();
 
-    const tc = createTimingCollector(this.debug, (msg, data) =>
-      this.logger.info(msg, data),
-    );
-
     const meta = params._meta as NewSessionMeta | undefined;
     const sessionId = uuidv7();
     const permissionMode: TwigExecutionMode =
@@ -153,29 +144,25 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
         ? (meta.permissionMode as TwigExecutionMode)
         : "default";
 
-    const mcpServers = tc.timeSync("parseMcpServers", () =>
-      parseMcpServers(params),
-    );
+    const mcpServers = parseMcpServers(params);
 
-    const options = tc.timeSync("buildSessionOptions", () =>
-      buildSessionOptions({
-        cwd: params.cwd,
-        mcpServers,
-        permissionMode,
-        canUseTool: this.createCanUseTool(sessionId),
-        logger: this.logger,
-        systemPrompt: buildSystemPrompt(meta?.systemPrompt),
-        userProvidedOptions: meta?.claudeCode?.options,
-        sessionId,
-        isResume: false,
-        onModeChange: this.createOnModeChange(sessionId),
-        onProcessSpawned: this.options?.onProcessSpawned,
-        onProcessExited: this.options?.onProcessExited,
-      }),
-    );
+    const options = buildSessionOptions({
+      cwd: params.cwd,
+      mcpServers,
+      permissionMode,
+      canUseTool: this.createCanUseTool(sessionId),
+      logger: this.logger,
+      systemPrompt: buildSystemPrompt(meta?.systemPrompt),
+      userProvidedOptions: meta?.claudeCode?.options,
+      sessionId,
+      isResume: false,
+      onModeChange: this.createOnModeChange(sessionId),
+      onProcessSpawned: this.options?.onProcessSpawned,
+      onProcessExited: this.options?.onProcessExited,
+    });
 
     const input = new Pushable<SDKUserMessage>();
-    const q = tc.timeSync("sdkQuery", () => query({ prompt: input, options }));
+    const q = query({ prompt: input, options });
 
     const session = this.createSession(
       sessionId,
@@ -189,32 +176,24 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
     this.registerPersistence(sessionId, meta as Record<string, unknown>);
 
     if (meta?.taskRunId) {
-      await tc.time("extNotification", () =>
-        this.client.extNotification("_posthog/sdk_session", {
-          taskRunId: meta.taskRunId!,
-          sessionId,
-          adapter: "claude",
-        }),
-      );
+      await this.client.extNotification("_posthog/sdk_session", {
+        taskRunId: meta.taskRunId!,
+        sessionId,
+        adapter: "claude",
+      });
     }
 
     // Only await model config — slash commands and MCP metadata are deferred
     // since they're not needed to return configOptions to the client.
-    const modelOptions = await tc.time("fetchModels", () =>
-      this.getModelConfigOptions(),
-    );
+    const modelOptions = await this.getModelConfigOptions();
 
     // Deferred: slash commands + MCP metadata (not needed to return configOptions)
-    this.deferBackgroundFetches(tc, q, sessionId, mcpServers);
+    this.deferBackgroundFetches(q, sessionId, mcpServers);
 
     session.modelId = modelOptions.currentModelId;
     await this.trySetModel(q, modelOptions.currentModelId);
 
-    const configOptions = await tc.time("buildConfigOptions", () =>
-      this.buildConfigOptions(modelOptions),
-    );
-
-    tc.summarize("newSession");
+    const configOptions = await this.buildConfigOptions(modelOptions);
 
     return {
       sessionId,
@@ -229,10 +208,6 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
   async resumeSession(
     params: LoadSessionRequest,
   ): Promise<LoadSessionResponse> {
-    const tc = createTimingCollector(this.debug, (msg, data) =>
-      this.logger.info(msg, data),
-    );
-
     const meta = params._meta as NewSessionMeta | undefined;
     const sessionId = meta?.sessionId;
     if (!sessionId) {
@@ -242,9 +217,7 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
       return {};
     }
 
-    const mcpServers = tc.timeSync("parseMcpServers", () =>
-      parseMcpServers(params),
-    );
+    const mcpServers = parseMcpServers(params);
 
     const permissionMode: TwigExecutionMode =
       meta?.permissionMode &&
@@ -252,31 +225,25 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
         ? (meta.permissionMode as TwigExecutionMode)
         : "default";
 
-    const { query: q, session } = await tc.time("initializeQuery", () =>
-      this.initializeQuery({
-        cwd: params.cwd,
-        permissionMode,
-        mcpServers,
-        systemPrompt: buildSystemPrompt(meta?.systemPrompt),
-        userProvidedOptions: meta?.claudeCode?.options,
-        sessionId,
-        isResume: true,
-        additionalDirectories: meta?.claudeCode?.options?.additionalDirectories,
-      }),
-    );
+    const { query: q, session } = await this.initializeQuery({
+      cwd: params.cwd,
+      permissionMode,
+      mcpServers,
+      systemPrompt: buildSystemPrompt(meta?.systemPrompt),
+      userProvidedOptions: meta?.claudeCode?.options,
+      sessionId,
+      isResume: true,
+      additionalDirectories: meta?.claudeCode?.options?.additionalDirectories,
+    });
 
     session.taskRunId = meta?.taskRunId;
 
     this.registerPersistence(sessionId, meta as Record<string, unknown>);
 
     // Deferred: slash commands + MCP metadata (not needed to return configOptions)
-    this.deferBackgroundFetches(tc, q, sessionId, mcpServers);
+    this.deferBackgroundFetches(q, sessionId, mcpServers);
 
-    const configOptions = await tc.time("buildConfigOptions", () =>
-      this.buildConfigOptions(),
-    );
-
-    tc.summarize("resumeSession");
+    const configOptions = await this.buildConfigOptions();
 
     return { configOptions };
   }
@@ -529,16 +496,13 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
    * Both populate caches used later — neither is needed to return configOptions.
    */
   private deferBackgroundFetches(
-    tc: ReturnType<typeof createTimingCollector>,
     q: Query,
     sessionId: string,
     mcpServers: ReturnType<typeof parseMcpServers>,
   ): void {
     Promise.all([
-      tc.time("slashCommands", () => getAvailableSlashCommands(q)),
-      tc.time("mcpMetadata", () =>
-        fetchMcpToolMetadata(mcpServers, this.logger),
-      ),
+      getAvailableSlashCommands(q),
+      fetchMcpToolMetadata(mcpServers, this.logger),
     ])
       .then(([slashCommands]) => {
         this.sendAvailableCommandsUpdate(sessionId, slashCommands);

package/src/agent.ts

@@ -36,6 +36,7 @@ export class Agent {
       this.sessionLogWriter = new SessionLogWriter({
         posthogAPI: this.posthogAPI,
         logger: this.logger.child("SessionLogWriter"),
+        localCachePath: config.localCachePath,
       });
     }
   }
@@ -111,7 +112,6 @@ export class Agent {
       taskId,
       deviceType: "local",
       logger: this.logger,
-      debug: this.debug,
       processCallbacks: options.processCallbacks,
       allowedModelIds,
       codexOptions:

package/src/session-log-writer.ts

@@ -1,3 +1,5 @@
+import fs from "node:fs";
+import path from "node:path";
 import type { SessionContext } from "./otel-log-writer.js";
 import type { PostHogAPIClient } from "./posthog-api.js";
 import type { StoredNotification } from "./types.js";
@@ -8,6 +10,8 @@ export interface SessionLogWriterOptions {
   posthogAPI?: PostHogAPIClient;
   /** Logger instance */
   logger?: Logger;
+  /** Local cache path for instant log loading (e.g., ~/.twig) */
+  localCachePath?: string;
 }
 
 interface ChunkBuffer {
@@ -34,9 +38,11 @@ export class SessionLogWriter {
   private sessions: Map<string, SessionState> = new Map();
   private messageCounts: Map<string, number> = new Map();
   private logger: Logger;
+  private localCachePath?: string;
 
   constructor(options: SessionLogWriterOptions = {}) {
     this.posthogAPI = options.posthogAPI;
+    this.localCachePath = options.localCachePath;
     this.logger =
       options.logger ??
       new Logger({ debug: false, prefix: "[SessionLogWriter]" });
@@ -71,7 +77,24 @@ export class SessionLogWriter {
       taskId: context.taskId,
     });
     this.sessions.set(sessionId, { context });
+
     this.lastFlushAttemptTime.set(sessionId, Date.now());
+
+    if (this.localCachePath) {
+      const sessionDir = path.join(
+        this.localCachePath,
+        "sessions",
+        context.runId,
+      );
+      try {
+        fs.mkdirSync(sessionDir, { recursive: true });
+      } catch (error) {
+        this.logger.warn("Failed to create local cache directory", {
+          sessionDir,
+          error,
+        });
+      }
+    }
   }
 
   isRegistered(sessionId: string): boolean {
@@ -120,6 +143,8 @@ export class SessionLogWriter {
         notification: message,
       };
 
+      this.writeToLocalCache(sessionId, entry);
+
       if (this.posthogAPI) {
         const pending = this.pendingEntries.get(sessionId) ?? [];
         pending.push(entry);
@@ -236,6 +261,8 @@ export class SessionLogWriter {
       },
     };
 
+    this.writeToLocalCache(sessionId, entry);
+
     if (this.posthogAPI) {
       const pending = this.pendingEntries.get(sessionId) ?? [];
       pending.push(entry);
@@ -269,4 +296,27 @@ export class SessionLogWriter {
     const timeout = setTimeout(() => this.flush(sessionId), delay);
     this.flushTimeouts.set(sessionId, timeout);
   }
+
+  private writeToLocalCache(
+    sessionId: string,
+    entry: StoredNotification,
+  ): void {
+    if (!this.localCachePath) return;
+
+    const session = this.sessions.get(sessionId);
+    if (!session) return;
+
+    const logPath = path.join(
+      this.localCachePath,
+      "sessions",
+      session.context.runId,
+      "logs.ndjson",
+    );
+
+    try {
+      fs.appendFileSync(logPath, `${JSON.stringify(entry)}\n`);
+    } catch (error) {
+      this.logger.warn("Failed to write to local cache", { logPath, error });
+    }
+  }
 }

package/src/types.ts

@@ -143,6 +143,8 @@ export interface AgentConfig {
   otelTransport?: OtelTransportConfig;
   /** Skip session log persistence (e.g. for preview sessions with no real task) */
   skipLogPersistence?: boolean;
+  /** Local cache path for instant log loading (e.g., ~/.twig) */
+  localCachePath?: string;
   debug?: boolean;
   onLog?: OnLogCallback;
 }