Skip to content

Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.

25.4 KB
Raw Blame
import * as Match from "effect/Match";
import { readSdkRecord } from "../ProtocolJson.ts";
import * as Predicate from "effect/Predicate";
/**
 * ClaudeAdapterLive - Scoped live implementation for the Claude Agent provider adapter.
 *
 * Wraps `@anthropic-ai/claude-agent-sdk` query sessions behind the generic
 * provider adapter contract and emits canonical runtime events.
 *
 * @module ClaudeAdapterLive
 */
import { type SDKMessage } from "@anthropic-ai/claude-agent-sdk";

import { EventId, type ProviderRuntimeEvent, RuntimeTaskId } from "@akeru/contracts";

import * as DateTime from "effect/DateTime";

import * as Effect from "effect/Effect";

import { ProviderAdapterRequestError } from "../../Errors.ts";

import { PROVIDER, type ClaudeSessionContext } from "./ClaudeAdapterState.ts";
import {
  asCanonicalTurnId,
  nativeProviderRefs,
  sdkNativeMethod,
  describeUnknownSdkMessage,
} from "./ClaudeProtocolValues.ts";
import {
  trimmedString,
  normalizeTaskUsage,
  CLAUDE_TASK_PATCH_STATUS,
  taskLinkageFor,
  parseWorkflowProgress,
  workflowAgentStatus,
} from "./ClaudeTasks.ts";
import {
  describeClaudeUsageLimit,
  compactBoundaryTokenUsageSnapshot,
  normalizeClaudeTaskProgressTokenUsage,
} from "./ClaudeUsage.ts";

export function createClaudeSystemMessages(deps: {
  readonly makeEventStamp: () => Effect.Effect<
    { eventId: EventId; createdAt: string },
    ProviderAdapterRequestError,
    never
  >;
  readonly offerRuntimeEvent: (event: ProviderRuntimeEvent) => Effect.Effect<void>;
  readonly emitThreadTokenUsage: (
    context: ClaudeSessionContext,
    usage:
      | {
          readonly usedTokens: number;
          readonly totalProcessedTokens?: number | undefined;
          readonly maxTokens?: number | undefined;
          readonly inputTokens?: number | undefined;
          readonly cachedInputTokens?: number | undefined;
          readonly cacheCreationTokens?: number | undefined;
          readonly outputTokens?: number | undefined;
          readonly reasoningOutputTokens?: number | undefined;
          readonly lastUsedTokens?: number | undefined;
          readonly lastInputTokens?: number | undefined;
          readonly lastCachedInputTokens?: number | undefined;
          readonly lastCacheCreationTokens?: number | undefined;
          readonly lastOutputTokens?: number | undefined;
          readonly lastReasoningOutputTokens?: number | undefined;
          readonly toolUses?: number | undefined;
          readonly durationMs?: number | undefined;
          readonly compactsAutomatically?: boolean | undefined;
          readonly autoCompactThreshold?: number | undefined;
        }
      | undefined,
    options?: { readonly rawMethod?: string; readonly rawPayload?: unknown } | undefined,
  ) => Effect.Effect<void, ProviderAdapterRequestError, never>;
  readonly emitRuntimeWarning: (
    context: ClaudeSessionContext,
    message: string,
    detail?: Extract<ProviderRuntimeEvent, { type: "runtime.warning" }>["payload"]["detail"],
    lifecycle?: { readonly key: string; readonly resolved?: boolean } | undefined,
  ) => Effect.Effect<void, ProviderAdapterRequestError, never>;
  readonly emitRuntimeError: (
    context: ClaudeSessionContext,
    message: string,
    cause?: unknown,
  ) => Effect.Effect<void, ProviderAdapterRequestError, never>;
}) {
  const emitWorkflowMemberProgress = Effect.fn("emitWorkflowMemberProgress")(function* (
    context: ClaudeSessionContext,
    base: Omit<ProviderRuntimeEvent, "type" | "payload">,
    message: Extract<SDKMessage, { type: "system"; subtype: "task_progress" }>,
  ) {
    const progress = parseWorkflowProgress(readSdkRecord(message)?.workflow_progress);

    if (!progress) {
      return;
    }

    const coordinatorId = message.task_id;

    for (const entry of progress.agents) {
      const memberTaskId = `${coordinatorId}:wf:${entry.index}`;
      const status = workflowAgentStatus(entry);

      // Material-transition filter: the wire repeats every member each tick.
      // Emit only when something the client renders actually changed, so a
      // 100-agent fleet costs ~1 event per changed member instead of 100
      // per tick (review finding: unbounded event amplification).
      const fingerprint = [
        status,
        entry.label ?? "",
        entry.model ?? "",
        entry.lastToolName ?? "",
        entry.error ?? "",
        entry.tokens ?? "",
        entry.toolCalls ?? "",
        entry.phaseIndex ?? "",
        entry.phaseTitle ?? "",
        entry.attempt ?? "",
      ].join("\u001f");

      if (context.workflowMemberFingerprints.get(memberTaskId) === fingerprint) {
        continue;
      }

      context.workflowMemberFingerprints.set(memberTaskId, fingerprint);
      const stamp = yield* deps.makeEventStamp();
      yield* deps.offerRuntimeEvent({
        ...base,
        eventId: stamp.eventId,
        createdAt: stamp.createdAt,
        type: "task.progress",
        payload: {
          taskId: RuntimeTaskId.make(memberTaskId),
          description: entry.label ?? `agent ${entry.index}`,
          status,
          ...(entry.error ? { error: entry.error } : {}),
          ...(entry.label ? { title: entry.label } : {}),
          ...(entry.model ? { model: entry.model } : {}),
          ...(entry.lastToolName ? { lastToolName: entry.lastToolName } : {}),
          ...(entry.tokens !== undefined
            ? {
                typedUsage: {
                  totalTokens: entry.tokens,
                  ...(entry.toolCalls !== undefined ? { toolUses: entry.toolCalls } : {}),
                },
              }
            : {}),
          parentAgentId: coordinatorId,
          agentIndex: entry.index,
          ...(entry.phaseIndex !== undefined ? { phaseIndex: entry.phaseIndex } : {}),
          ...(entry.phaseTitle ? { phaseTitle: entry.phaseTitle } : {}),
          ...(entry.attempt !== undefined ? { attempt: entry.attempt } : {}),
          timelineBypass: true,
        },
      });
    }
  });

  const handleSystemMessage = Effect.fn("handleSystemMessage")(function* (
    context: ClaudeSessionContext,
    message: SDKMessage,
  ) {
    if (message.type !== "system") {
      return;
    }

    const stamp = yield* deps.makeEventStamp();

    const base = {
      eventId: stamp.eventId,
      provider: PROVIDER,
      createdAt: stamp.createdAt,
      threadId: context.session.threadId,
      ...(context.turnState ? { turnId: asCanonicalTurnId(context.turnState.turnId) } : {}),
      providerRefs: nativeProviderRefs(context),
      raw: {
        source: "claude.sdk.message" as const,
        method: sdkNativeMethod(message),
        messageType: `${message.type}:${message.subtype}`,
        payload: message,
      },
    };

    // Undeclared-but-real subtypes (absent from the SDK's union, so they can't
    // be switch cases): consumed intentionally without emitting, otherwise
    // they fall through to the unknown-subtype warning and surface as spurious
    // error rows in client work logs. `background_tasks_changed` is a roster
    // snapshot ({tasks: [...]}) — the task_* lifecycle events carry the
    // authoritative per-agent data and the typed background_tasks control
    // request is the reconciliation source. `vcs_state_changed`
    // ({kind: commit|push|rebase}) and `code_change_published`
    // ({provider, url, repo}) are informational CLI notices; the work log
    // already shows the underlying git/gh tool calls.
    switch (String(message.subtype)) {
      case "background_tasks_changed":
      case "vcs_state_changed":
      case "code_change_published":
        return;
    }

    switch (message.subtype) {
      case "init":
        yield* deps.offerRuntimeEvent({
          ...base,
          type: "session.configured",
          payload: {
            config: message,
          },
        });

        return;
      case "status":
        yield* deps.offerRuntimeEvent({
          ...base,
          type: "session.state.changed",
          payload: {
            state: message.status === "compacting" ? "waiting" : "running",
            reason: `status:${message.status ?? "active"}`,
            detail: message,
          },
        });

        return;
      case "compact_boundary":
        if (context.turnState) {
          context.turnState.latestAssistantUsage = undefined;
          context.turnState.compactedSinceLatestAssistantUsage = true;
        }

        yield* deps.emitThreadTokenUsage(
          context,
          compactBoundaryTokenUsageSnapshot(
            message,
            context.lastKnownContextWindow,
            context.lastKnownTotalProcessedTokens,
          ),
          {
            rawMethod: "claude/system/compact_boundary",
            rawPayload: message,
          },
        );
        yield* deps.offerRuntimeEvent({
          ...base,
          type: "thread.state.changed",
          payload: {
            state: "compacted",
            detail: message,
          },
        });

        return;
      case "hook_started":
        yield* deps.offerRuntimeEvent({
          ...base,
          type: "hook.started",
          payload: {
            hookId: message.hook_id,
            hookName: message.hook_name,
            hookEvent: message.hook_event,
          },
        });

        return;
      case "hook_progress":
        yield* deps.offerRuntimeEvent({
          ...base,
          type: "hook.progress",
          payload: {
            hookId: message.hook_id,
            output: message.output,
            stdout: message.stdout,
            stderr: message.stderr,
          },
        });

        return;
      case "hook_response":
        yield* deps.offerRuntimeEvent({
          ...base,
          type: "hook.completed",
          payload: {
            hookId: message.hook_id,
            outcome: message.outcome,
            output: message.output,
            stdout: message.stdout,
            stderr: message.stderr,
            ...(Predicate.isNumber(message.exit_code) ? { exitCode: message.exit_code } : {}),
          },
        });

        return;
      case "task_started": {
        // A task launched by a tool that itself ran inside a subagent (the
        // in-flight tool carries agentId from parent_tool_use_id) is
        // agent-internal: a subagent's background shell, not parent work.
        const launchingTool = message.tool_use_id
          ? Array.from(context.inFlightTools.values()).find(
              (tool) => tool.itemId === message.tool_use_id,
            )
          : undefined;

        const owningAgentId = launchingTool?.agentId;
        // Model/effort: the Agent tool's input carries explicit overrides;
        // absent ones inherit the session's selection (SDK behavior).
        // Subagent assistant snapshots refine model with the authoritative API
        // id: one that already arrived is buffered and outranks the seed here,
        // later ones refine the record in place. AgentInput.effort may be a
        // named level or an integer.
        const launchInput = launchingTool?.input;
        const toolUseId = message.tool_use_id;
        const bufferedModel = toolUseId ? context.pendingTaskModels.get(toolUseId) : undefined;

        if (toolUseId) {
          context.pendingTaskModels.delete(toolUseId);
        }

        const model =
          bufferedModel ??
          trimmedString(launchInput?.model) ??
          trimmedString(context.session.model ?? undefined);

        const rawLaunchEffort = launchInput?.effort;

        const effort =
          trimmedString(rawLaunchEffort) ??
          (Predicate.isNumber(rawLaunchEffort) && Number.isFinite(rawLaunchEffort)
            ? String(rawLaunchEffort)
            : context.currentEffort);

        // Remember the agent identity so every later task.* payload for this
        // taskId is self-describing (identity must survive activity retention).
        context.taskAgents.set(message.task_id, {
          taskId: message.task_id,
          toolUseId: message.tool_use_id,
          description: message.description,
          subagentType: message.subagent_type,
          taskType: message.task_type,
          workflowName: message.workflow_name,
          skipTranscript: message.skip_transcript === true,
          runHandles: context.taskAgents.get(message.task_id)?.runHandles,
          owningAgentId,
          model,
          effort,
        });
        context.liveTaskIds.add(message.task_id);
        yield* deps.offerRuntimeEvent({
          ...base,
          type: "task.started",
          payload: {
            taskId: RuntimeTaskId.make(message.task_id),
            description: message.description,
            ...(message.task_type ? { taskType: message.task_type } : {}),
            ...(owningAgentId ? { agentId: owningAgentId } : {}),
            ...(message.description ? { title: message.description } : {}),
            ...(message.subagent_type ? { role: message.subagent_type } : {}),
            ...(model ? { model } : {}),
            ...(effort ? { effort } : {}),
            ...(message.tool_use_id ? { toolUseId: message.tool_use_id } : {}),
            ...(message.workflow_name ? { workflowName: message.workflow_name } : {}),
          },
        });

        return;
      }

      case "task_progress": {
        yield* deps.emitThreadTokenUsage(
          context,
          normalizeClaudeTaskProgressTokenUsage(message.usage, context),
          {
            rawMethod: "claude/system/task_progress",
            rawPayload: message,
          },
        );
        const linkage = taskLinkageFor(context.taskAgents, message.task_id);
        const typedUsage = normalizeTaskUsage(message.usage);

        // Phases ride on the coordinator's ONE progress row per tick. A
        // separate phases-only row shared the stable ingestion activity id
        // with this full row, and the thinner upsert overwrote usage and
        // progress text (review finding).
        const workflowPhases = parseWorkflowProgress(
          readSdkRecord(message)?.workflow_progress,
        )?.phases;

        yield* deps.offerRuntimeEvent({
          ...base,
          type: "task.progress",
          payload: {
            taskId: RuntimeTaskId.make(message.task_id),
            description: message.description,
            ...(message.summary ? { summary: message.summary } : {}),
            ...(message.usage ? { usage: message.usage } : {}),
            ...(typedUsage ? { typedUsage } : {}),
            ...(message.last_tool_name ? { lastToolName: message.last_tool_name } : {}),
            ...(workflowPhases && workflowPhases.length > 0 ? { phases: workflowPhases } : {}),
            ...linkage,
            ...(message.subagent_type ? { role: message.subagent_type } : {}),
          },
        });
        yield* emitWorkflowMemberProgress(context, base, message);

        return;
      }

      case "task_updated": {
        // Status patch (killed/paused/backgrounded/end_time/error) — main
        // previously dropped this on the floor, losing all transitions.
        const patch = message.patch;

        const status =
          patch.status !== undefined ? CLAUDE_TASK_PATCH_STATUS[patch.status] : undefined;

        if (status === "completed" || status === "failed" || status === "cancelled") {
          context.liveTaskIds.delete(message.task_id);
        }

        const endedAt =
          Predicate.isNumber(patch.end_time) && Number.isFinite(patch.end_time)
            ? DateTime.formatIso(DateTime.makeUnsafe(patch.end_time))
            : undefined;

        yield* deps.offerRuntimeEvent({
          ...base,
          type: "task.updated",
          payload: {
            taskId: RuntimeTaskId.make(message.task_id),
            ...(status ? { status } : {}),
            ...(patch.description ? { description: patch.description } : {}),
            ...(patch.error ? { error: patch.error } : {}),
            ...(endedAt ? { endedAt } : {}),
            ...(patch.is_backgrounded !== undefined
              ? { isBackgrounded: patch.is_backgrounded }
              : {}),
            ...taskLinkageFor(context.taskAgents, message.task_id),
          },
        });

        return;
      }

      case "task_notification": {
        context.liveTaskIds.delete(message.task_id);
        yield* deps.emitThreadTokenUsage(
          context,
          normalizeClaudeTaskProgressTokenUsage(message.usage, context),
          {
            rawMethod: "claude/system/task_notification",
            rawPayload: message,
          },
        );
        const typedUsage = normalizeTaskUsage(message.usage);
        yield* deps.offerRuntimeEvent({
          ...base,
          type: "task.completed",
          payload: {
            taskId: RuntimeTaskId.make(message.task_id),
            status: message.status,
            ...(message.summary ? { summary: message.summary } : {}),
            ...(message.usage ? { usage: message.usage } : {}),
            ...(typedUsage ? { typedUsage } : {}),
            ...(message.output_file ? { outputFile: message.output_file } : {}),
            ...taskLinkageFor(context.taskAgents, message.task_id),
          },
        });

        return;
      }

      case "files_persisted":
        yield* deps.offerRuntimeEvent({
          ...base,
          type: "files.persisted",
          payload: {
            files: Array.isArray(message.files)
              ? message.files.map((file: { filename: string; file_id: string }) => ({
                  filename: file.filename,
                  fileId: file.file_id,
                }))
              : [],
            ...(Array.isArray(message.failed)
              ? {
                  failed: message.failed.map((entry: { filename: string; error: string }) => ({
                    filename: entry.filename,
                    error: entry.error,
                  })),
                }
              : {}),
          },
        });

        return;
      case "thinking_tokens":
        return;
      case "api_retry":
        // Transport-level retry heartbeat. Surfacing each attempt as a
        // warning row spammed the work log (10 rows during a 502 storm);
        // the terminal result/error path reports the actual failure. Keep
        // the session visibly alive instead.
        yield* deps.offerRuntimeEvent({
          ...base,
          type: "session.state.changed",
          payload: {
            state: "running",
            reason: `api_retry:${message.attempt}/${message.max_retries}`,
          },
        });

        return;
      case "session_state_changed":
        // Authoritative turn-over signal from the CLI.
        yield* deps.offerRuntimeEvent({
          ...base,
          type: "session.state.changed",
          payload: {
            state: Match.value(message.state).pipe(
              Match.when("running", () => "running" as const),
              Match.when("requires_action", () => "waiting" as const),
              Match.orElse(() => "ready" as const),
            ),
            reason: `session_state:${message.state}`,
          },
        });

        return;
      case "notification":
        // User-facing CLI notification (e.g. context-limit warnings). Only
        // high-priority ones warrant a work-log row.
        if (message.priority === "high" || message.priority === "immediate") {
          yield* deps.emitRuntimeWarning(context, message.text, message);
        }

        return;
      // Inner protocol/UX details with no T3 surface today — consumed
      // deliberately so they don't masquerade as unknown-subtype warnings.
      case "model_refusal_fallback":
      case "local_command_output":
      case "plugin_install":
      case "commands_changed":
      case "memory_recall":
      case "elicitation_complete":
        return;
      case "permission_denied":
        yield* deps.offerRuntimeEvent({
          ...base,
          type: "tool.denied",
          payload: {
            toolName: message.tool_name,
            ...(message.tool_use_id ? { toolUseId: message.tool_use_id } : {}),
            ...(message.decision_reason ? { reason: message.decision_reason } : {}),
            ...(message.agent_id ? { agentId: message.agent_id } : {}),
          },
        });

        return;
      case "mirror_error":
        yield* deps.emitRuntimeError(
          context,
          `Claude workspace mirror error: ${message.error}`,
          message,
        );

        return;
      default: {
        // Exhaustiveness guard: every subtype in the SDK's typed union is
        // handled above, so `message` narrows to never here — a new SDK
        // release adding a subtype fails this typecheck instead of silently
        // warning at runtime. The runtime fallback still catches undeclared
        // wire-only subtypes (like background_tasks_changed used to be).
        message satisfies never;
        const unknownMessage = readSdkRecord(message);
        yield* deps.emitRuntimeWarning(
          context,
          describeUnknownSdkMessage(`Claude system message '${unknownMessage?.subtype}'`, message),
          message,
        );

        return;
      }
    }
  });

  const handleSdkTelemetryMessage = Effect.fn("handleSdkTelemetryMessage")(function* (
    context: ClaudeSessionContext,
    message: SDKMessage,
  ) {
    const stamp = yield* deps.makeEventStamp();

    const base = {
      eventId: stamp.eventId,
      provider: PROVIDER,
      createdAt: stamp.createdAt,
      threadId: context.session.threadId,
      ...(context.turnState ? { turnId: asCanonicalTurnId(context.turnState.turnId) } : {}),
      providerRefs: nativeProviderRefs(context),
      raw: {
        source: "claude.sdk.message" as const,
        method: sdkNativeMethod(message),
        messageType: message.type,
        payload: message,
      },
    };

    if (message.type === "tool_progress") {
      yield* deps.offerRuntimeEvent({
        ...base,
        type: "tool.progress",
        payload: {
          toolUseId: message.tool_use_id,
          toolName: message.tool_name,
          elapsedSeconds: message.elapsed_time_seconds,
          ...(message.task_id ? { taskId: RuntimeTaskId.make(message.task_id) } : {}),
          ...(message.parent_tool_use_id !== null
            ? { parentToolUseId: message.parent_tool_use_id }
            : {}),
        },
      });

      return;
    }

    if (message.type === "tool_use_summary") {
      yield* deps.offerRuntimeEvent({
        ...base,
        type: "tool.summary",
        payload: {
          summary: message.summary,
          ...(message.preceding_tool_use_ids.length > 0
            ? {
                precedingToolUseIds: message.preceding_tool_use_ids,
              }
            : {}),
        },
      });

      return;
    }

    if (message.type === "auth_status") {
      yield* deps.offerRuntimeEvent({
        ...base,
        type: "auth.status",
        payload: {
          isAuthenticating: message.isAuthenticating,
          output: message.output,
          ...(message.error ? { error: message.error } : {}),
        },
      });

      return;
    }

    if (message.type === "rate_limit_event") {
      yield* deps.offerRuntimeEvent({
        ...base,
        type: "account.rate-limits.updated",
        payload: {
          rateLimits: message,
        },
      });
      const rateLimitInfo = message.rate_limit_info;

      if (!rateLimitInfo) return;

      // A rejected window parks the turn inside the SDK: no further messages
      // arrive and no result lands, so without a row the thread just spins.
      // Warnings (allowed_warning) still have headroom and stay quiet, an
      // account spending provisioned overage keeps running despite the reject,
      // and between turns there is no turn to report as paused.
      const overageAllowed =
        rateLimitInfo.overageStatus === "allowed" ||
        rateLimitInfo.overageStatus === "allowed_warning" ||
        rateLimitInfo.isUsingOverage === true ||
        rateLimitInfo.overageInUse === true;

      const blocked = rateLimitInfo.status === "rejected" && !overageAllowed;
      const limitType = rateLimitInfo.rateLimitType ?? "unknown";
      const limitKey = `${limitType}:${rateLimitInfo.resetsAt ?? "unknown"}`;
      const warningKey = `claude.rate-limit:${limitType}`;

      const recovered =
        context.turnState?.rejectedRateLimitTypes.has(limitType) === true && !blocked;

      if (context.turnState) {
        // Current blocking evidence is independent of whether its warning has
        // already been shown. A recovery can omit or advance the reset time;
        // its window type remains stable without clearing another window.
        if (blocked) context.turnState.rejectedRateLimitTypes.add(limitType);
        else if (
          rateLimitInfo.status === "allowed" ||
          rateLimitInfo.status === "allowed_warning" ||
          overageAllowed
        ) {
          context.turnState.rejectedRateLimitTypes.delete(limitType);
        }
      }

      if (blocked && context.turnState !== undefined) {
        const turnId = context.turnState.turnId;

        if (context.announcedUsageLimits?.turnId !== turnId) {
          context.announcedUsageLimits = { turnId, keys: new Set() };
        }

        if (!context.announcedUsageLimits.keys.has(limitKey)) {
          context.announcedUsageLimits.keys.add(limitKey);
          const notice = describeClaudeUsageLimit(rateLimitInfo, Date.parse(stamp.createdAt));
          yield* deps.emitRuntimeWarning(context, notice, rateLimitInfo, { key: warningKey });
        }
      } else if (recovered) {
        yield* deps.emitRuntimeWarning(
          context,
          "Claude usage limit recovered. Processing resumed.",
          rateLimitInfo,
          { key: warningKey, resolved: true },
        );
      }

      return;
    }
  });

  return { emitWorkflowMemberProgress, handleSystemMessage, handleSdkTelemetryMessage };
}