@prismatic-io/lux 0.0.1

package/src/drivers/claude-code/parse-events.ts

@@ -0,0 +1,464 @@
+import { z } from "zod";
+import {
+  type Interrupt,
+  type ParsedDriverEvent,
+  parseAgentUsage,
+  type TokenUsage,
+  TURN_GLYPHS,
+  toolResultProgress,
+} from "../../core/index.js";
+
+const ContentBlockSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("text"), text: z.string() }),
+  z.object({ type: z.literal("tool_use"), id: z.string(), name: z.string(), input: z.unknown() }),
+  z.object({ type: z.literal("thinking"), thinking: z.exactOptional(z.string()) }),
+]);
+
+// Unmodeled block/line types are skipped, not fatal.
+export const ClaudeCodeLineSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("system"),
+    subtype: z.literal("init"),
+    model: z.string().optional().catch(undefined),
+    session_id: z.string().optional().catch(undefined),
+  }),
+  z.object({
+    type: z.literal("user"),
+    message: z.object({ content: z.array(z.unknown()).catch([]) }),
+    parent_tool_use_id: z.string().optional().catch(undefined),
+  }),
+  z.object({
+    type: z.literal("assistant"),
+    message: z.object({
+      id: z.string().optional().catch(undefined),
+      content: z.array(z.unknown()).catch([]),
+      usage: z.unknown().optional(),
+    }),
+    parent_tool_use_id: z.string().optional().catch(undefined),
+  }),
+  z.object({
+    type: z.literal("result"),
+    subtype: z.string().optional().catch(undefined),
+    is_error: z.boolean().optional().catch(undefined),
+    result: z.unknown().optional(),
+    usage: z.unknown().optional(),
+    session_id: z.string().optional().catch(undefined),
+    total_cost_usd: z.unknown().optional(),
+    duration_ms: z.unknown().optional(),
+    num_turns: z.number().optional().catch(undefined),
+    stop_reason: z.string().optional().catch(undefined),
+    deferred_tool_use: z
+      .object({
+        id: z.string(),
+        name: z.string(),
+        input: z.unknown(),
+      })
+      .optional()
+      .catch(undefined),
+  }),
+]);
+
+// Loose so the option/header fields `context` forwards to the answerer survive.
+const AskToolInputSchema = z.looseObject({
+  question: z.unknown().optional(),
+  questions: z.array(z.unknown()).optional().catch(undefined),
+  message: z.unknown().optional(),
+  text: z.unknown().optional(),
+});
+
+const AskToolQuestionSchema = z.looseObject({ question: z.string() });
+
+type ClaudeCodeLine = z.infer<typeof ClaudeCodeLineSchema>;
+type SystemLine = Extract<ClaudeCodeLine, { type: "system" }>;
+type UserLine = Extract<ClaudeCodeLine, { type: "user" }>;
+type AssistantLine = Extract<ClaudeCodeLine, { type: "assistant" }>;
+type ResultLine = Extract<ClaudeCodeLine, { type: "result" }>;
+type ContentBlock = z.infer<typeof ContentBlockSchema>;
+type ParserOutput = ParsedDriverEvent | ParsedDriverEvent[] | null;
+
+type ParserConfig = {
+  askToolName: string;
+  interactionMode: "defer-resume" | "stream-json";
+};
+
+type PendingTurn = {
+  id: string;
+  usage: TokenUsage;
+  tools: string[];
+  asked: boolean;
+  thought: boolean;
+  text?: string;
+};
+
+type AssistantContent = {
+  events: ParsedDriverEvent[];
+  tools: string[];
+  asked: boolean;
+  thought: boolean;
+  firstText?: string;
+};
+
+const questionTextOf = (raw: unknown): string =>
+  AskToolQuestionSchema.safeParse(raw).data?.question ?? "";
+
+/** Build an `ask` interrupt from the configured deferred user-message tool. */
+const parseAskInterrupt = (block: { id: string; input: unknown }): Interrupt => {
+  const input = AskToolInputSchema.safeParse(block.input).data;
+  const questions = input?.questions ?? null;
+  let question: string;
+  if (questions) {
+    question = questions.map(questionTextOf).filter(Boolean).join("\n");
+  } else if (typeof input?.question === "string") {
+    question = input.question;
+  } else if (typeof input?.message === "string") {
+    question = input.message;
+  } else if (typeof input?.text === "string") {
+    question = input.text;
+  } else if (typeof block.input === "string") {
+    question = block.input;
+  } else {
+    question = JSON.stringify(block.input);
+  }
+  return {
+    kind: "ask",
+    id: block.id,
+    question,
+    context: { toolUseId: block.id, ...(questions ? { questions } : {}) },
+  };
+};
+
+// A glyph badge of every facet the call exercised, then its most telling
+// detail — the tools it ran or a snippet of its reply.
+const turnLabel = (turn: PendingTurn): string | undefined => {
+  const badge =
+    (turn.thought ? TURN_GLYPHS.thinking : "") +
+    (turn.asked ? TURN_GLYPHS.ask : "") +
+    (turn.tools.length > 0 ? TURN_GLYPHS.tool : "") +
+    (turn.text ? TURN_GLYPHS.reply : "");
+  if (!badge) return undefined;
+  const detail =
+    turn.tools.length > 0
+      ? turn.tools.join(", ")
+      : turn.text?.replace(/\s+/g, " ").trim().slice(0, 120);
+  return detail ? `${badge} ${detail}` : badge;
+};
+
+const collapseEvents = (events: ParsedDriverEvent[]): ParserOutput => {
+  if (events.length === 0) return null;
+  return events.length === 1 ? (events[0] ?? null) : events;
+};
+
+const toolResultText = (content: unknown): string => {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return JSON.stringify(content);
+  return content
+    .filter(
+      (part): part is { type: "text"; text: string } =>
+        typeof part === "object" &&
+        part !== null &&
+        (part as { type?: unknown }).type === "text" &&
+        typeof (part as { text?: unknown }).text === "string",
+    )
+    .map((part) => part.text)
+    .join("\n");
+};
+
+const toolInfrastructureFailure = (text: string): string | null =>
+  /Could not start .+E2BIG[\s\S]+sandbox profile/i.test(text)
+    ? `Claude Code could not start a sandboxed tool process: ${text}`
+    : null;
+
+class ClaudeEventParser {
+  private eventSequence = 0;
+  private pendingTurn: PendingTurn | null = null;
+  private readonly toolNames = new Map<string, string>();
+  private readonly config: ParserConfig;
+  private readonly cliVersion: string | undefined;
+
+  constructor(config: ParserConfig, cliVersion?: string) {
+    this.config = config;
+    this.cliVersion = cliVersion;
+  }
+
+  readonly parse = (line: string): ParserOutput => {
+    const event = this.parseLine(line);
+    if (!event) return null;
+
+    switch (event.type) {
+      case "system":
+        return this.readyEvent(event);
+      case "user":
+        return this.userEvents(event);
+      case "assistant":
+        return this.assistantEvents(event);
+      case "result":
+        return this.resultEvents(event);
+    }
+  };
+
+  private parseLine(line: string): ClaudeCodeLine | null {
+    try {
+      return ClaudeCodeLineSchema.safeParse(JSON.parse(line)).data ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  private readyEvent(event: SystemLine): ParsedDriverEvent {
+    return {
+      tag: "ready",
+      ready: {
+        agentId: "claude-code",
+        ...(event.model !== undefined ? { model: event.model } : {}),
+        detail: {
+          sessionId: event.session_id,
+          ...(this.cliVersion ? { cliVersion: this.cliVersion } : {}),
+        },
+      },
+    };
+  }
+
+  private userEvents(event: UserLine): ParserOutput {
+    const events: ParsedDriverEvent[] = [];
+    for (const rawBlock of event.message.content) {
+      const block = this.toolResultBlock(rawBlock, event.parent_tool_use_id);
+      if (!block) continue;
+      events.push(block);
+      if (block.tag !== "progress") continue;
+      const text = (block.progress.payload as { text?: unknown }).text;
+      const failure = typeof text === "string" ? toolInfrastructureFailure(text) : null;
+      if (failure) {
+        events.push({
+          tag: "error",
+          error: { exitReason: "error", reason: failure },
+        });
+      }
+    }
+    return collapseEvents(events);
+  }
+
+  private toolResultBlock(rawBlock: unknown, parentToolUseId?: string): ParsedDriverEvent | null {
+    if (!rawBlock || typeof rawBlock !== "object") return null;
+    const block = rawBlock as Record<string, unknown>;
+    if (block.type !== "tool_result" || typeof block.tool_use_id !== "string") return null;
+
+    const toolUseId = block.tool_use_id;
+    const content = block.content ?? [];
+    return {
+      tag: "progress",
+      progress: toolResultProgress(
+        this.eventSequence++,
+        {
+          name: this.toolNames.get(toolUseId) ?? "unknown",
+          toolUseId,
+          content,
+          isError: block.is_error === true,
+          text: toolResultText(content),
+          ...(parentToolUseId ? { parentToolUseId } : {}),
+        },
+        Date.now(),
+      ),
+    };
+  }
+
+  private assistantEvents(event: AssistantLine): ParserOutput {
+    const events: ParsedDriverEvent[] = [];
+    const id = event.message.id;
+    this.flushPreviousTurn(id, events);
+
+    const content = this.assistantContent(event);
+    events.push(...content.events);
+    this.recordTurn(id, parseAgentUsage(event.message.usage), content, events);
+    return collapseEvents(events);
+  }
+
+  private flushPreviousTurn(id: string | undefined, events: ParsedDriverEvent[]): void {
+    if (!id || !this.pendingTurn || this.pendingTurn.id === id) return;
+    const flushed = this.flushTurn();
+    if (flushed) events.push(flushed);
+  }
+
+  private assistantContent(event: AssistantLine): AssistantContent {
+    const content: AssistantContent = {
+      events: [],
+      tools: [],
+      asked: false,
+      thought: false,
+    };
+    for (const rawBlock of event.message.content) {
+      const block = ContentBlockSchema.safeParse(rawBlock).data;
+      if (block) this.recordContentBlock(block, event.parent_tool_use_id, content);
+    }
+    return content;
+  }
+
+  private recordContentBlock(
+    block: ContentBlock,
+    parentToolUseId: string | undefined,
+    content: AssistantContent,
+  ): void {
+    switch (block.type) {
+      case "thinking":
+        content.thought = true;
+        return;
+      case "text":
+        this.recordAgentMessage(block.text, parentToolUseId, content);
+        return;
+      case "tool_use":
+        this.recordToolUse(block, parentToolUseId, content);
+    }
+  }
+
+  private recordAgentMessage(
+    text: string,
+    parentToolUseId: string | undefined,
+    content: AssistantContent,
+  ): void {
+    if (!text) return;
+    content.firstText ??= text;
+    content.events.push({
+      tag: "progress",
+      progress: {
+        id: `am-${this.eventSequence++}`,
+        kind: "agent-message",
+        payload: { text, ...(parentToolUseId ? { parentToolUseId } : {}) },
+        ts: Date.now(),
+      },
+    });
+  }
+
+  private recordToolUse(
+    block: Extract<ContentBlock, { type: "tool_use" }>,
+    parentToolUseId: string | undefined,
+    content: AssistantContent,
+  ): void {
+    if (block.name === this.config.askToolName) {
+      content.asked = true;
+      if (this.config.interactionMode === "stream-json") {
+        content.events.push({ tag: "interrupt", interrupt: parseAskInterrupt(block) });
+      }
+      return;
+    }
+
+    this.toolNames.set(block.id, block.name);
+    if (!content.tools.includes(block.name)) content.tools.push(block.name);
+    content.events.push({
+      tag: "progress",
+      progress: {
+        id: `tc-${block.id}`,
+        kind: "tool-call",
+        payload: {
+          name: block.name,
+          input: block.input,
+          toolUseId: block.id,
+          ...(parentToolUseId ? { parentToolUseId } : {}),
+        },
+        ts: Date.now(),
+      },
+    });
+  }
+
+  private recordTurn(
+    id: string | undefined,
+    usage: TokenUsage | null,
+    content: AssistantContent,
+    events: ParsedDriverEvent[],
+  ): void {
+    if (!usage) return;
+    if (!id && this.pendingTurn) {
+      const flushed = this.flushTurn();
+      if (flushed) events.push(flushed);
+    }
+
+    this.pendingTurn ??= {
+      id: id ?? "",
+      usage,
+      tools: [],
+      asked: false,
+      thought: false,
+    };
+    this.pendingTurn.usage = usage;
+    this.pendingTurn.asked ||= content.asked;
+    this.pendingTurn.thought ||= content.thought;
+    for (const tool of content.tools) {
+      if (!this.pendingTurn.tools.includes(tool)) this.pendingTurn.tools.push(tool);
+    }
+    if (content.firstText && this.pendingTurn.text === undefined) {
+      this.pendingTurn.text = content.firstText;
+    }
+
+    if (!id) {
+      const flushed = this.flushTurn();
+      if (flushed) events.push(flushed);
+    }
+  }
+
+  private resultEvents(event: ResultLine): ParserOutput {
+    if (event.stop_reason === "tool_deferred" && event.deferred_tool_use) {
+      return this.withPendingUsage({
+        tag: "interrupt",
+        interrupt: this.deferredInterrupt(event.deferred_tool_use),
+      });
+    }
+    if (event.is_error === true || event.subtype?.startsWith("error")) {
+      return this.withPendingUsage({
+        tag: "error",
+        error: {
+          exitReason: "error",
+          reason: typeof event.result === "string" ? event.result : "claude reported error",
+        },
+      });
+    }
+
+    const usage = parseAgentUsage(event.usage);
+    return this.withPendingUsage({
+      tag: "done",
+      done: {
+        exitReason: "done",
+        summary: {
+          sessionId: event.session_id,
+          cost: event.total_cost_usd,
+          durationMs: event.duration_ms,
+          ...(event.num_turns !== undefined ? { numTurns: event.num_turns } : {}),
+          ...(usage ? { usage } : {}),
+        },
+      },
+    });
+  }
+
+  private deferredInterrupt(deferred: NonNullable<ResultLine["deferred_tool_use"]>): Interrupt {
+    if (deferred.name === this.config.askToolName) return parseAskInterrupt(deferred);
+    return {
+      kind: "custom",
+      id: deferred.id,
+      payload: deferred.input,
+      context: { toolUseId: deferred.id, toolName: deferred.name },
+    };
+  }
+
+  private withPendingUsage(event: ParsedDriverEvent): ParsedDriverEvent | ParsedDriverEvent[] {
+    const usage = this.flushTurn();
+    return usage ? [usage, event] : event;
+  }
+
+  private flushTurn(): ParsedDriverEvent | null {
+    if (!this.pendingTurn) return null;
+    const label = turnLabel(this.pendingTurn);
+    const event: ParsedDriverEvent = {
+      tag: "progress",
+      progress: {
+        id: `usage-${this.eventSequence++}`,
+        kind: "usage",
+        payload: { ...this.pendingTurn.usage, ...(label ? { label } : {}) },
+        ts: Date.now(),
+      },
+    };
+    this.pendingTurn = null;
+    return event;
+  }
+}
+
+export const makeParseEvent = (
+  config: ParserConfig,
+  cliVersion?: string,
+): ((line: string) => ParserOutput) => new ClaudeEventParser(config, cliVersion).parse;

package/src/drivers/codex/app-events.ts

@@ -0,0 +1,218 @@
+import {
+  type ParsedDriverEvent,
+  type TokenUsage,
+  TURN_GLYPHS,
+  toolResultProgress,
+} from "../../core/index.js";
+
+const resultText = (content: unknown): string => {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter(
+      (block): block is { type: "text"; text: string } =>
+        typeof block === "object" &&
+        block !== null &&
+        (block as { type?: unknown }).type === "text" &&
+        typeof (block as { text?: unknown }).text === "string",
+    )
+    .map((block) => block.text)
+    .join("\n");
+};
+
+export type RpcId = string | number;
+export type RpcRecord = Record<string, unknown>;
+export type AppTurnFacets = {
+  tools: string[];
+  asked: boolean;
+  thought: boolean;
+  text?: string;
+};
+
+export const asRecord = (value: unknown): RpcRecord | null =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as RpcRecord)
+    : null;
+export const messageOf = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error);
+
+export const appTurnLabel = (facets: AppTurnFacets | undefined): string | undefined => {
+  if (!facets) return undefined;
+  const badge =
+    (facets.thought ? TURN_GLYPHS.thinking : "") +
+    (facets.asked ? TURN_GLYPHS.ask : "") +
+    (facets.tools.length > 0 ? TURN_GLYPHS.tool : "") +
+    (facets.text ? TURN_GLYPHS.reply : "");
+  if (!badge) return undefined;
+  const detail =
+    facets.tools.length > 0
+      ? facets.tools.join(", ")
+      : facets.text?.replace(/\s+/g, " ").trim().slice(0, 120);
+  return detail ? `${badge} ${detail}` : badge;
+};
+
+export const appUsage = (raw: unknown): TokenUsage | null => {
+  const value = asRecord(raw);
+  if (!value) return null;
+  const input = typeof value.inputTokens === "number" ? value.inputTokens : 0;
+  const cached = typeof value.cachedInputTokens === "number" ? value.cachedInputTokens : 0;
+  const output = typeof value.outputTokens === "number" ? value.outputTokens : 0;
+  const cacheCreation =
+    typeof value.cacheWriteInputTokens === "number" ? value.cacheWriteInputTokens : 0;
+  return {
+    input: Math.max(0, input - cached),
+    output,
+    cacheRead: cached,
+    cacheCreation,
+  };
+};
+
+export const appItemToolName = (item: RpcRecord): string | null => {
+  switch (item.type) {
+    case "commandExecution":
+      return "command_execution";
+    case "fileChange":
+      return "file_change";
+    case "webSearch":
+      return "web_search";
+    case "mcpToolCall":
+    case "dynamicToolCall":
+      return String(item.tool ?? item.type);
+    case "collabAgentToolCall":
+      return String(item.tool ?? "collab_agent");
+    default:
+      return null;
+  }
+};
+
+const appItemInput = (item: RpcRecord): unknown => {
+  switch (item.type) {
+    case "commandExecution":
+      return { command: item.command, cwd: item.cwd };
+    case "fileChange":
+      return { changes: item.changes };
+    case "webSearch":
+      return { query: item.query };
+    case "collabAgentToolCall":
+      return {
+        prompt: item.prompt,
+        model: item.model,
+        reasoningEffort: item.reasoningEffort,
+        receiverThreadIds: item.receiverThreadIds,
+      };
+    default:
+      return item.arguments;
+  }
+};
+
+const appItemContent = (item: RpcRecord, result: RpcRecord | null): unknown => {
+  switch (item.type) {
+    case "commandExecution":
+      return { output: item.aggregatedOutput ?? "", exitCode: item.exitCode };
+    case "fileChange":
+      return { changes: item.changes, status: item.status };
+    case "webSearch":
+      return { query: item.query, results: item.results };
+    case "dynamicToolCall":
+      return item.contentItems;
+    case "collabAgentToolCall":
+      return { receiverThreadIds: item.receiverThreadIds, agentsStates: item.agentsStates };
+    default:
+      return result?.content ?? [];
+  }
+};
+
+const appItemResultText = (item: RpcRecord, error: RpcRecord | null, content: unknown): string => {
+  if (typeof item.aggregatedOutput === "string") return item.aggregatedOutput;
+  if (typeof error?.message === "string") return error.message;
+  return resultText(content);
+};
+
+export const appItemProgress = (
+  item: RpcRecord,
+  phase: "started" | "completed",
+  parentToolUseId?: string,
+): ParsedDriverEvent | null => {
+  const id = typeof item.id === "string" ? item.id : `${String(item.type)}-${Date.now()}`;
+  if (item.type === "agentMessage" && phase === "completed" && typeof item.text === "string") {
+    return {
+      tag: "progress",
+      progress: {
+        id: `am-${id}`,
+        kind: "agent-message",
+        payload: { text: item.text, ...(parentToolUseId ? { parentToolUseId } : {}) },
+        ts: Date.now(),
+      },
+    };
+  }
+  if (item.type === "reasoning" && phase === "completed") {
+    const summary = Array.isArray(item.summary)
+      ? item.summary.filter((part): part is string => typeof part === "string").join("\n")
+      : "";
+    const content = Array.isArray(item.content)
+      ? item.content.filter((part): part is string => typeof part === "string").join("\n")
+      : "";
+    return {
+      tag: "progress",
+      progress: {
+        id: `reasoning-${id}`,
+        kind: "reasoning",
+        payload: {
+          text: summary || content,
+          ...(parentToolUseId ? { parentToolUseId } : {}),
+        },
+        ts: Date.now(),
+      },
+    };
+  }
+
+  const tool = appItemToolName(item);
+  if (!tool) return null;
+
+  if (phase === "started") {
+    const input = appItemInput(item);
+    return {
+      tag: "progress",
+      progress: {
+        id: `tc-${id}`,
+        kind: "tool-call",
+        payload: {
+          name: tool,
+          input,
+          toolUseId: id,
+          ...(typeof item.server === "string" ? { server: item.server } : {}),
+          ...(parentToolUseId ? { parentToolUseId } : {}),
+        },
+        ts: Date.now(),
+      },
+    };
+  }
+
+  const result = asRecord(item.result);
+  const content = appItemContent(item, result);
+  const structuredContent = result?.structuredContent;
+  const error = asRecord(item.error);
+  const isError =
+    item.status === "failed" ||
+    item.success === false ||
+    (typeof item.exitCode === "number" && item.exitCode !== 0) ||
+    error !== null;
+  return {
+    tag: "progress",
+    progress: toolResultProgress(
+      0,
+      {
+        name: tool,
+        toolUseId: id,
+        content,
+        ...(asRecord(structuredContent)
+          ? { structuredContent: asRecord(structuredContent) ?? {} }
+          : {}),
+        isError,
+        text: appItemResultText(item, error, content),
+        ...(parentToolUseId ? { parentToolUseId } : {}),
+      },
+      Date.now(),
+    ),
+  };
+};