@shivaedev/agent-claude-code 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shivaedev/agent-claude-code",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Claude Code integration for Effect applications",
   "homepage": "https://github.com/ShivaeDev/platform/tree/main/packages/agent-claude-code#readme",
   "bugs": {
@@ -19,7 +19,8 @@
       "@shivaedev/source": "./src/*.ts",
       "types": "./dist/*.d.ts",
       "default": "./dist/*.js"
-    }
+    },
+    "#test/*": "./src/test-support/*"
   },
   "exports": {
     "./*.ts": {
@@ -32,12 +33,38 @@
   "files": [
     "dist",
     "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.spec.ts",
+    "!src/**/test-support",
     "CHANGELOG.md",
     "README.md"
   ],
+  "dependencies": {
+    "@shivaedev/agent": "0.4.0"
+  },
   "devDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "0.3.312",
+    "@effect/vitest": "4.1.0",
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "@shivaedev/quality": "0.65.0",
+    "@shivaedev/test-story": "0.42.0",
     "@types/node": "24.19.2",
-    "typescript": "7.0.2"
+    "effect": "4.1.0",
+    "typescript": "7.0.2",
+    "vitest": "5.0.5"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "0.3.312",
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "effect": "4.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/claude-agent-sdk": {
+      "optional": true
+    },
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    }
   },
   "engines": {
     "node": ">=24"
@@ -48,7 +75,8 @@
   },
   "scripts": {
     "build": "node --eval \"import('node:fs').then(({ rmSync }) => rmSync('dist', { force: true, recursive: true }))\" && tsc --project tsconfig.build.json",
-    "ready": "pnpm typecheck && pnpm build",
+    "ready": "pnpm typecheck && pnpm test && pnpm build",
+    "test": "vitest run --configLoader native",
     "typecheck": "tsc --noEmit"
   }
 }

package/src/SessionConnection.ts

@@ -0,0 +1,10 @@
+import type { Effect, Stream } from "effect";
+import type { RunEvent } from "@shivaedev/agent/events.ts";
+import type { BackendUnavailable } from "@shivaedev/agent/failures.ts";
+import type { Input } from "@shivaedev/agent/run.ts";
+
+export interface SessionConnection {
+	readonly events: Stream.Stream<RunEvent, BackendUnavailable>;
+	readonly interrupt: Effect.Effect<void, BackendUnavailable>;
+	readonly queue: (input: Input, priority?: "now") => Effect.Effect<void, BackendUnavailable>;
+}

package/src/adapters/ClaudeProvider.ts

@@ -0,0 +1,16 @@
+import type { getSubagentMessages, listSubagents, Options, Query, SDKMessage, SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
+import { Context, Layer } from "effect";
+import { loadClaudeSdk } from "#adapters/loadClaudeSdk.ts";
+export class ClaudeProvider extends Context.Service<
+	ClaudeProvider,
+	{
+		readonly query: (request: {
+			readonly prompt: AsyncIterable<SDKUserMessage>;
+			readonly options: Options;
+		}) => AsyncIterable<SDKMessage> & Pick<Query, "interrupt" | "close">;
+		readonly getSubagentMessages: typeof getSubagentMessages;
+		readonly listSubagents: typeof listSubagents;
+	}
+>()("@shivaedev/agent-claude-code/ClaudeProvider") {
+	static layer = Layer.effect(this, loadClaudeSdk);
+}

package/src/adapters/InputQueue.ts

@@ -0,0 +1,89 @@
+import type { SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
+import { Deferred, Effect } from "effect";
+import { BackendUnavailable } from "@shivaedev/agent/failures.ts";
+
+interface QueuedInput {
+	readonly accepted: Deferred.Deferred<void, BackendUnavailable>;
+	readonly message: SDKUserMessage;
+}
+function closedFailure() {
+	return new BackendUnavailable({
+		backend: "claude-code",
+		message: "session closed before delivery reached the provider",
+	});
+}
+// Claude accepts a user message when `query` pulls it from the prompt iterable.
+export class InputQueue {
+	readonly #buffer: QueuedInput[] = [];
+	readonly #handOff: (message: SDKUserMessage) => void;
+	#pending: ((result: IteratorResult<SDKUserMessage>) => void) | null = null;
+	#done = false;
+	constructor(handOff: (message: SDKUserMessage) => void) {
+		this.#handOff = handOff;
+	}
+	#accept(input: QueuedInput): void {
+		this.#handOff(input.message);
+		Deferred.doneUnsafe(input.accepted, Effect.void);
+	}
+	#fail(input: QueuedInput): void {
+		Deferred.doneUnsafe(input.accepted, Effect.fail(closedFailure()));
+	}
+	#offer(input: QueuedInput): void {
+		if (this.#done) {
+			this.#fail(input);
+			return;
+		}
+		const pending = this.#pending;
+		if (pending !== null) {
+			this.#pending = null;
+			pending({ done: false, value: input.message });
+			this.#accept(input);
+			return;
+		}
+		this.#buffer.push(input);
+	}
+	push(message: SDKUserMessage): Effect.Effect<void, BackendUnavailable> {
+		const queue = this;
+		return Effect.gen(function* () {
+			const accepted = yield* Deferred.make<void, BackendUnavailable>();
+			yield* Effect.sync(() => queue.#offer({ accepted, message }));
+			yield* Deferred.await(accepted);
+		});
+	}
+	close(): void {
+		this.#done = true;
+		for (const input of this.#buffer.splice(0)) {
+			this.#fail(input);
+		}
+		const pending = this.#pending;
+		if (pending !== null) {
+			this.#pending = null;
+			pending({ done: true, value: undefined });
+		}
+	}
+	stream(): AsyncIterable<SDKUserMessage> {
+		return {
+			[Symbol.asyncIterator]: () => ({
+				next: () => {
+					const buffered = this.#buffer.shift();
+					if (buffered !== undefined) {
+						this.#accept(buffered);
+						return Promise.resolve({
+							done: false,
+							value: buffered.message,
+						});
+					}
+					if (this.#done) {
+						return Promise.resolve({
+							done: true as const,
+							value: undefined,
+						});
+					}
+					return new Promise((promiseResolve) => {
+						this.#pending = promiseResolve;
+					});
+				},
+			}),
+		};
+	}
+}

package/src/adapters/blocks.ts

@@ -0,0 +1,63 @@
+import type { RunEvent } from "@shivaedev/agent/events.ts";
+import { toolIdentity } from "#adapters/toolIdentity.ts";
+import type { Origin, RawPayload } from "#protocol.ts";
+export function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+export function contentBlocks(message: object): readonly Record<string, unknown>[] {
+	if (!("message" in message && isRecord(message.message))) {
+		return [];
+	}
+	const content = message.message.content;
+	if (typeof content === "string") {
+		return [{ text: content, type: "text" }];
+	}
+	return Array.isArray(content) ? content.filter(isRecord) : [];
+}
+export function textOf(content: unknown): string {
+	if (typeof content === "string") {
+		return content;
+	}
+	if (Array.isArray(content)) {
+		return content
+			.filter(isRecord)
+			.map((block) => (typeof block.text === "string" ? block.text : ""))
+			.join("");
+	}
+	return JSON.stringify(content);
+}
+export function blockEvent(
+	raw: RawPayload,
+	role: "agent" | "user",
+	block: Record<string, unknown>,
+	origin: Origin | undefined,
+): RunEvent | undefined {
+	const from = origin === undefined ? {} : { origin };
+	if (block.type === "text" && typeof block.text === "string") {
+		return { ...from, parts: [{ text: block.text, type: "text" }], raw, role, type: "message" };
+	}
+	if (block.type === "thinking" && typeof block.thinking === "string") {
+		return { ...from, raw, text: block.thinking, type: "thinking" };
+	}
+	if (block.type === "tool_use" && typeof block.id === "string" && typeof block.name === "string") {
+		return {
+			...from,
+			input: JSON.stringify(block.input),
+			...toolIdentity(block.name),
+			raw,
+			toolId: block.id,
+			type: "tool.started",
+		};
+	}
+	if (block.type === "tool_result" && typeof block.tool_use_id === "string") {
+		return {
+			...from,
+			ok: block.is_error !== true,
+			output: textOf(block.content),
+			raw,
+			toolId: block.tool_use_id,
+			type: "tool.completed",
+		};
+	}
+	return undefined;
+}

package/src/adapters/consumeSession.ts

@@ -0,0 +1,35 @@
+import type { SDKMessage } from "@anthropic-ai/claude-agent-sdk";
+import { Cause, Queue } from "effect";
+import { BackendUnavailable } from "@shivaedev/agent/failures.ts";
+import type { InputQueue } from "#adapters/InputQueue.ts";
+import type { Delivery } from "#adapters/sessionLanes.ts";
+import type { Repair } from "#adapters/workflowAdoption.ts";
+
+export async function consumeSession(
+	live: AsyncIterable<SDKMessage>,
+	input: InputQueue,
+	queue: Queue.Queue<Delivery, BackendUnavailable | Cause.Done>,
+	deliver: (delivery: Delivery) => void,
+	repair: () => Promise<Repair | undefined>,
+	stopped: () => boolean,
+): Promise<void> {
+	try {
+		for await (const message of live) {
+			if (stopped()) {
+				break;
+			}
+			deliver({ kind: "frame", message });
+		}
+		const recovered = await repair();
+		if (!stopped() && recovered !== undefined) {
+			deliver({ kind: "repair", repair: recovered });
+		}
+	} catch (error) {
+		if (!stopped()) {
+			Queue.failCauseUnsafe(queue, Cause.fail(new BackendUnavailable({ backend: "claude-code", message: String(error) })));
+		}
+	} finally {
+		input.close();
+		Queue.endUnsafe(queue);
+	}
+}

package/src/adapters/loadClaudeSdk.ts

@@ -0,0 +1,6 @@
+import { Effect } from "effect";
+import { BackendUnavailable } from "@shivaedev/agent/failures.ts";
+export const loadClaudeSdk = Effect.tryPromise({
+	catch: (error) => new BackendUnavailable({ backend: "claude-code", message: String(error) }),
+	try: () => import("@anthropic-ai/claude-agent-sdk"),
+});

package/src/adapters/mirrorKeys.ts

@@ -0,0 +1,33 @@
+import type { SessionKey } from "@anthropic-ai/claude-agent-sdk";
+
+const SUBAGENTS = "subagents";
+const WORKFLOWS = "workflows";
+const AGENT = "agent-";
+// Observed transcript keys identify delegated agents by a final `agent-<id>` segment. Workflow keys start with
+// `subagents/workflows/<run-id>` and may nest through further delegates.
+export interface WorkflowAgentRef {
+	readonly agentId: string;
+	readonly runId: string;
+}
+function agentIdOf(segment = ""): string | undefined {
+	return segment.startsWith(AGENT) ? segment.slice(AGENT.length) : undefined;
+}
+export function workflowAgentRef(key: SessionKey): WorkflowAgentRef | undefined {
+	const segments = key.subpath?.split("/") ?? [];
+	const [scope, kind, runId] = segments;
+	if (scope !== SUBAGENTS || kind !== WORKFLOWS || runId === undefined) {
+		return undefined;
+	}
+	const agentId = agentIdOf(segments.at(-1));
+	return agentId === undefined || segments.length < 4 ? undefined : { agentId, runId };
+}
+export function subagentRef(key: SessionKey): string | undefined {
+	const segments = key.subpath?.split("/") ?? [];
+	return segments.length >= 2 && segments[0] === SUBAGENTS ? agentIdOf(segments.at(-1)) : undefined;
+}
+export function agentFileRef(agentId: string): string {
+	return [SUBAGENTS, `${AGENT}${agentId}`].join("/");
+}
+export function workflowRunRef(runId: string): string {
+	return [SUBAGENTS, WORKFLOWS, runId].join("/");
+}

package/src/adapters/openSession.ts

@@ -0,0 +1,102 @@
+import { randomUUID } from "node:crypto";
+import { resolve } from "node:path";
+import type { EffortLevel, SessionStore } from "@anthropic-ai/claude-agent-sdk";
+import { type Cause, Effect, Queue, type Scope, Stream } from "effect";
+import { BackendUnavailable } from "@shivaedev/agent/failures.ts";
+import type { Input, StartRequest } from "@shivaedev/agent/run.ts";
+import { ClaudeProvider } from "#adapters/ClaudeProvider.ts";
+import { consumeSession } from "#adapters/consumeSession.ts";
+import { InputQueue } from "#adapters/InputQueue.ts";
+import { repairSession } from "#adapters/repairSession.ts";
+import { type Delivery, openSessionLanes } from "#adapters/sessionLanes.ts";
+import { sessionOptions } from "#adapters/sessionOptions.ts";
+import { makeToolServer } from "#adapters/toolServer.ts";
+import type { ClaudeOptions } from "#options.ts";
+import type { SessionConnection } from "#SessionConnection.ts";
+
+function unavailable(error: unknown) {
+	return new BackendUnavailable({ backend: "claude-code", message: String(error) });
+}
+
+export const openSession = Effect.fn("ClaudeCode.openSession")(function* (
+	request: StartRequest,
+	config: ClaudeOptions,
+	effort: EffortLevel | undefined,
+	resume: string | undefined,
+): Effect.fn.Return<SessionConnection, BackendUnavailable, ClaudeProvider | Scope.Scope> {
+	const peer = yield* ClaudeProvider;
+	const deliveries = yield* Queue.unbounded<Delivery, BackendUnavailable | Cause.Done>();
+	const tools = config.tools ?? [];
+	const server =
+		tools.length === 0
+			? undefined
+			: yield* Effect.acquireRelease(Effect.tryPromise({ catch: unavailable, try: () => makeToolServer(tools) }), (instance) =>
+					Effect.promise(() => instance.close()),
+				);
+	return yield* Effect.acquireRelease(
+		Effect.try({
+			catch: unavailable,
+			try: () => {
+				let nativeRef = resume;
+				let stopped = false;
+				function deliver(delivery: Delivery) {
+					if (delivery.kind === "frame" && delivery.message.type === "system" && delivery.message.subtype === "init") {
+						nativeRef = delivery.message.session_id;
+					}
+					Queue.offerUnsafe(deliveries, delivery);
+				}
+				const inputIds = new Map<string, string>();
+				const input = new InputQueue((message) => {
+					const inputId = message.uuid === undefined ? undefined : inputIds.get(message.uuid);
+					deliver({ kind: "frame", message, ...(inputId === undefined ? {} : { inputId }) });
+				});
+				const store: SessionStore = {
+					append: (key, entries) => {
+						deliver({ kind: "mirror", write: { entries, key } });
+						return Promise.resolve();
+					},
+					load: () => Promise.resolve(null),
+				};
+				const live = peer.query({
+					options: sessionOptions(request, config, store, effort, resume, server),
+					prompt: input.stream(),
+				});
+				void consumeSession(
+					live,
+					input,
+					deliveries,
+					deliver,
+					() =>
+						stopped || nativeRef === undefined
+							? Promise.resolve(undefined)
+							: Effect.runPromise(repairSession(nativeRef, resolve(request.cwd)).pipe(Effect.provideService(ClaudeProvider, peer))),
+					() => stopped,
+				);
+				return {
+					close: () => {
+						stopped = true;
+						input.close();
+						live.close();
+						Queue.endUnsafe(deliveries);
+					},
+					events: Stream.fromQueue(deliveries).pipe(Stream.map(openSessionLanes().deliver), Stream.flattenIterable),
+					interrupt: Effect.tryPromise({ catch: unavailable, try: () => live.interrupt() }).pipe(Effect.asVoid),
+					queue: (value: Input, priority?: "now") => {
+						const uuid = randomUUID();
+						if (value.id !== undefined) {
+							inputIds.set(uuid, value.id);
+						}
+						return input.push({
+							message: { content: value.parts.map((part) => part.text).join("\n"), role: "user" },
+							"parent_tool_use_id": null,
+							type: "user",
+							uuid,
+							...(priority === undefined ? {} : { priority }),
+						});
+					},
+				};
+			},
+		}),
+		(session) => Effect.sync(session.close),
+	);
+});

package/src/adapters/openSessionMapping.ts

@@ -0,0 +1,84 @@
+import type { SDKMessage } from "@anthropic-ai/claude-agent-sdk";
+import type { RunEvent } from "@shivaedev/agent/events.ts";
+import { blockEvent, contentBlocks } from "#adapters/blocks.ts";
+import { openSubsessions } from "#adapters/openSubsessions.ts";
+import { openTurnUsage } from "#adapters/openTurnUsage.ts";
+import { rateLimitEvent } from "#adapters/rateLimitEvent.ts";
+import { rawOf } from "#adapters/rawPayload.ts";
+import { spilledPreview } from "#adapters/spilledPreview.ts";
+import { systemEvents } from "#adapters/systemEvents.ts";
+import type { Origin, RawPayload } from "#protocol.ts";
+
+type ResultMessage = Extract<
+	SDKMessage,
+	{
+		type: "result";
+	}
+>;
+function turnStatus(message: ResultMessage) {
+	if (message.terminal_reason === "aborted_streaming") {
+		return "interrupted";
+	}
+	return message.is_error ? "failed" : "completed";
+}
+function originOf(message: SDKMessage): Origin | undefined {
+	const spawnedBy = "parent_tool_use_id" in message && typeof message.parent_tool_use_id === "string" ? message.parent_tool_use_id : undefined;
+	if (spawnedBy === undefined) {
+		return undefined;
+	}
+	return "parent_agent_id" in message && typeof message.parent_agent_id === "string"
+		? { parentNode: message.parent_agent_id, spawnedBy }
+		: { spawnedBy };
+}
+type ContentMessage = Extract<
+	SDKMessage,
+	{
+		type: "assistant" | "user";
+	}
+>;
+function contentEvents(raw: RawPayload, message: ContentMessage, lifecycle: readonly RunEvent[]): readonly RunEvent[] {
+	const role = message.type === "assistant" ? "agent" : "user";
+	const origin = originOf(message);
+	const events = [
+		...contentBlocks(message)
+			.map((block) => blockEvent(raw, role, block, origin))
+			.filter((event): event is RunEvent => event !== undefined),
+		...spilledPreview(raw, message, origin),
+		...lifecycle,
+	];
+	return events.length === 0 ? [{ raw, type: "raw" }] : events;
+}
+interface SessionMapping {
+	readonly frame: (message: SDKMessage) => readonly RunEvent[];
+	readonly spawnerOf: (childRef: string) => string | undefined;
+}
+export function openSessionMapping(): SessionMapping {
+	const subsessions = openSubsessions();
+	const turns = openTurnUsage();
+	function frame(message: SDKMessage): readonly RunEvent[] {
+		const raw = rawOf(message);
+		const system = message.type === "system" ? systemEvents(raw, message) : undefined;
+		if (system !== undefined) {
+			return system;
+		}
+		if (message.type === "rate_limit_event") {
+			return [rateLimitEvent(raw, message)];
+		}
+		if (message.type === "result") {
+			return [
+				...turns.usage(raw, message),
+				{
+					raw,
+					state: turnStatus(message),
+					type: "execution",
+				},
+			];
+		}
+		const lifecycle = subsessions.events(raw, message);
+		if (message.type === "assistant" || message.type === "user") {
+			return contentEvents(raw, message, lifecycle);
+		}
+		return lifecycle.length === 0 ? [{ raw, type: "raw" }] : lifecycle;
+	}
+	return { frame, spawnerOf: subsessions.spawnerOf };
+}

package/src/adapters/openSubsessions.ts

@@ -0,0 +1,70 @@
+import type { SDKMessage } from "@anthropic-ai/claude-agent-sdk";
+import type { RunEvent } from "@shivaedev/agent/events.ts";
+import { type Ending, endedEvent, notifiedEnding, reportedEnding, updatedEnding } from "#adapters/subsessionEndings.ts";
+import type { RawPayload } from "#protocol.ts";
+
+const LOCAL_AGENT = "local_agent";
+type SystemMessage = Extract<
+	SDKMessage,
+	{
+		type: "system";
+	}
+>;
+type TaskStarted = Extract<
+	SystemMessage,
+	{
+		subtype: "task_started";
+	}
+>;
+type Opened = Extract<
+	RunEvent,
+	{
+		type: "child.opened";
+	}
+>;
+function openedEvent(raw: RawPayload, message: TaskStarted): Opened | undefined {
+	if (message.task_type !== LOCAL_AGENT || message.tool_use_id === undefined) {
+		return undefined;
+	}
+	return {
+		...(message.prompt === undefined ? {} : { charter: message.prompt }),
+		...(message.description === "" ? {} : { label: message.description }),
+		childRef: message.task_id,
+		raw,
+		spawnedBy: message.tool_use_id,
+		type: "child.opened",
+	};
+}
+interface Subsessions {
+	readonly events: (raw: RawPayload, message: SDKMessage) => readonly RunEvent[];
+	readonly spawnerOf: (childRef: string) => string | undefined;
+}
+// Task updates and notifications omit `task_type`, so only ids observed opening as `local_agent` can close a subsession.
+export function openSubsessions(): Subsessions {
+	const open = new Set<string>();
+	const spawners = new Map<string, string>();
+	function close(raw: RawPayload, ending: Ending | undefined): readonly RunEvent[] {
+		return ending === undefined || !open.delete(ending.childRef) ? [] : [endedEvent(raw, ending)];
+	}
+	return {
+		events: (raw, message) => {
+			if (message.type !== "system") {
+				return close(raw, reportedEnding(message));
+			}
+			if (message.subtype === "task_started") {
+				const opened = openedEvent(raw, message);
+				if (opened === undefined) {
+					return [];
+				}
+				open.add(message.task_id);
+				spawners.set(message.task_id, opened.spawnedBy);
+				return [opened];
+			}
+			if (message.subtype === "task_updated") {
+				return close(raw, updatedEnding(message));
+			}
+			return message.subtype === "task_notification" ? close(raw, notifiedEnding(message)) : [];
+		},
+		spawnerOf: (childRef) => spawners.get(childRef),
+	};
+}

package/src/adapters/openTurnUsage.ts

@@ -0,0 +1,52 @@
+import type { ModelUsage, SDKMessage } from "@anthropic-ai/claude-agent-sdk";
+import type { RunEvent } from "@shivaedev/agent/events.ts";
+import type { RawPayload } from "#protocol.ts";
+
+function step(now: number, before: number) {
+	return now < before ? now : now - before;
+}
+export function openTurnUsage() {
+	const previous = new Map<string, ModelUsage>();
+	return {
+		usage: (
+			raw: RawPayload,
+			message: Extract<
+				SDKMessage,
+				{
+					type: "result";
+				}
+			>,
+		): readonly RunEvent[] =>
+			Object.entries(message.modelUsage).flatMap(([key, now]): RunEvent[] => {
+				if (now.inputTokens + now.outputTokens + now.cacheReadInputTokens + now.cacheCreationInputTokens + now.costUSD === 0) {
+					return [];
+				}
+				const before = previous.get(key);
+				previous.set(key, now);
+				const model = now.canonicalModel ?? key;
+				return [
+					{
+						cacheReadTokens: step(now.cacheReadInputTokens, before?.cacheReadInputTokens ?? 0),
+						cacheWriteTokens: step(now.cacheCreationInputTokens, before?.cacheCreationInputTokens ?? 0),
+						inputTokens: step(now.inputTokens, before?.inputTokens ?? 0),
+						model,
+						outputTokens: step(now.outputTokens, before?.outputTokens ?? 0),
+						raw,
+						scope: "delta",
+						type: "usage",
+						unit: "turn",
+					},
+					{
+						amount: step(now.costUSD, before?.costUSD ?? 0),
+						currency: "USD",
+						model,
+						raw,
+						scope: "delta",
+						source: "provider",
+						type: "cost",
+						unit: "turn",
+					},
+				];
+			}),
+	};
+}