@shivaedev/agent-claude-code 0.2.0 → 0.3.0

package/src/adapters/workflowIdentity.ts

@@ -0,0 +1,75 @@
+import type { SDKMessage } from "@anthropic-ai/claude-agent-sdk";
+import { isRecord } from "#adapters/blocks.ts";
+import type { ChildOutcome } from "#protocol.ts";
+
+type SystemMessage = Extract<
+	SDKMessage,
+	{
+		type: "system";
+	}
+>;
+type TaskProgress = Extract<
+	SystemMessage,
+	{
+		subtype: "task_progress";
+	}
+>;
+export interface WorkflowIdentity {
+	readonly ended: ChildOutcome | undefined;
+	readonly label: string | undefined;
+	readonly model: string | undefined;
+	readonly phase: string | undefined;
+	readonly spawnedBy: string | undefined;
+}
+function stringAt(entry: Record<string, unknown>, field: string) {
+	return typeof entry[field] === "string" ? entry[field] : undefined;
+}
+function endingOf(state: string | undefined): ChildOutcome | undefined {
+	if (state === "done") {
+		return "completed";
+	}
+	return state === "error" || state === "blocked" ? "failed" : undefined;
+}
+function labelOf(entry: Record<string, unknown>): string | undefined {
+	const label = stringAt(entry, "label");
+	const phase = stringAt(entry, "phaseTitle");
+	if (label === undefined) {
+		return phase;
+	}
+	return phase === undefined ? label : `${phase}: ${label}`;
+}
+function identityOf(entry: Record<string, unknown>, spawnedBy: string | undefined): WorkflowIdentity {
+	return {
+		ended: endingOf(stringAt(entry, "state")),
+		label: labelOf(entry),
+		model: stringAt(entry, "model"),
+		phase: stringAt(entry, "phaseTitle"),
+		spawnedBy,
+	};
+}
+function snapshot(message: TaskProgress): readonly unknown[] {
+	const carried = "workflow_progress" in message && message.workflow_progress;
+	return Array.isArray(carried) ? carried : [];
+}
+export interface WorkflowIdentities {
+	readonly observe: (message: TaskProgress) => void;
+	readonly of: (agentId: string) => WorkflowIdentity | undefined;
+}
+// `workflow_progress` is absent from the published SDK types; live progress frames carry the workflow-agent identity snapshot.
+export function openWorkflowIdentities(): WorkflowIdentities {
+	const identities = new Map<string, WorkflowIdentity>();
+	return {
+		observe: (message) => {
+			for (const entry of snapshot(message)) {
+				if (!isRecord(entry) || entry.type !== "workflow_agent") {
+					continue;
+				}
+				const agentId = stringAt(entry, "agentId");
+				if (agentId !== undefined) {
+					identities.set(agentId, identityOf(entry, message.tool_use_id));
+				}
+			}
+		},
+		of: (agentId) => identities.get(agentId),
+	};
+}

package/src/claudeCode.ts

@@ -1 +1,117 @@
-export {};
+import { Deferred, Effect, Layer, Option, Ref, Schema, Stream } from "effect";
+import { Backend, type ConfiguredBackend } from "@shivaedev/agent/backend.ts";
+import { ProtocolFailure, Rejected, UnknownAcceptance } from "@shivaedev/agent/failures.ts";
+import type { BackendReference, Receipt, StartRequest } from "@shivaedev/agent/run.ts";
+import { ClaudeProvider } from "#adapters/ClaudeProvider.ts";
+import { openSession } from "#adapters/openSession.ts";
+import type { ClaudeOptions } from "#options.ts";
+import { makeRunState, type RunState } from "#runState.ts";
+
+const decodeEffort = Schema.decodeUnknownOption(Schema.Literals(["low", "medium", "high", "xhigh", "max"]));
+function protocol(message: string) {
+	return new ProtocolFailure({ backend: "claude-code", message });
+}
+export const makeClaudeBackend = Effect.fn("ClaudeCode.makeClaudeBackend")(function* (
+	options: ClaudeOptions = {},
+): Effect.fn.Return<ConfiguredBackend, never, ClaudeProvider> {
+	const peer = yield* ClaudeProvider;
+	const runs = new Map<string, RunState>();
+	function lookup(receipt: Receipt) {
+		return Effect.suspend(() => {
+			const run =
+				receipt.backend === "claude-code" && receipt.reference.version === 1 && receipt.reference.value === receipt.operationId
+					? runs.get(receipt.operationId)
+					: undefined;
+			return run === undefined ? Effect.fail(protocol("No run evidence for this receipt in this backend instance")) : Effect.succeed(run);
+		});
+	}
+	const start = Effect.fn("ClaudeCode.start")(function* (request: StartRequest, resume?: typeof BackendReference.Type) {
+		if (resume !== undefined && resume.version !== 1) {
+			return yield* Effect.fail(new Rejected({ backend: "claude-code", message: "Unsupported native session reference version" }));
+		}
+		const effort = request.effort === undefined ? Option.none() : decodeEffort(request.effort);
+		if (request.effort !== undefined && Option.isNone(effort)) {
+			return yield* Effect.fail(new Rejected({ backend: "claude-code", message: `Unsupported Claude effort: ${request.effort}` }));
+		}
+		const existing = runs.get(request.operationId);
+		if (existing !== undefined) {
+			return yield* Deferred.await(existing.acknowledged);
+		}
+		const session = yield* openSession(request, options, Option.getOrUndefined(effort), resume?.value).pipe(
+			Effect.provideService(ClaudeProvider, peer),
+			Effect.mapError((error) => new UnknownAcceptance({ backend: "claude-code", message: error.message, operationId: request.operationId })),
+		);
+		const run = yield* makeRunState(request.operationId, session);
+		runs.set(request.operationId, run);
+		yield* session
+			.queue(request.input)
+			.pipe(Effect.mapError((error) => new UnknownAcceptance({ backend: "claude-code", message: error.message, operationId: request.operationId })));
+		return yield* Deferred.await(run.acknowledged);
+	});
+	return {
+		backend: "claude-code",
+		events: (receipt) => Stream.unwrap(Effect.map(lookup(receipt), (run) => run.events)),
+		features: {
+			imageInput: { reason: "This adapter accepts text input only", support: "unsupported" },
+			interruption: {
+				implementation: { interrupt: (receipt) => Effect.flatMap(lookup(receipt), (run) => run.session.interrupt) },
+				support: "supported",
+			},
+			models: { reason: "Model discovery is not exposed; supply a provider model in the start request", support: "unsupported" },
+			queuedInput: {
+				implementation: { queue: (receipt, input) => Effect.flatMap(lookup(receipt), (run) => run.session.queue(input)) },
+				support: "supported",
+			},
+			sessions: { implementation: { resume: (session, request) => start(request, session) }, support: "supported" },
+			steering: {
+				implementation: { steer: (receipt, input) => Effect.flatMap(lookup(receipt), (run) => run.session.queue(input, "now")) },
+				support: "supported",
+			},
+			transcript: {
+				implementation: {
+					read: (receipt) =>
+						Effect.gen(function* () {
+							const run = yield* lookup(receipt);
+							const events = yield* Ref.get(run.history);
+							return { completeness: events.some((event) => event.type === "gap") ? "partial" : "complete", events } as const;
+						}),
+				},
+				support: "supported",
+			},
+		},
+		inspect: (receipt) =>
+			Effect.gen(function* () {
+				const found = runs.get(receipt.operationId);
+				if (found === undefined) {
+					return { reason: "This backend instance has no evidence; absence does not prove non-acceptance", type: "missing" } as const;
+				}
+				const run = yield* lookup(receipt);
+				const error = yield* Ref.get(run.failure);
+				if (error !== undefined) {
+					return yield* Effect.fail(error);
+				}
+				return { state: yield* Ref.get(run.state), type: "known" } as const;
+			}),
+		reconcile: (operationId) =>
+			Effect.gen(function* () {
+				const run = runs.get(operationId);
+				const acknowledgement = run === undefined ? Option.none() : yield* Deferred.poll(run.acknowledged);
+				if (Option.isSome(acknowledgement)) {
+					return yield* acknowledgement.value.pipe(
+						Effect.map((receipt) => ({ receipt, type: "accepted" }) as const),
+						Effect.catchTag("UnknownAcceptance", (error) => Effect.succeed({ operationId, reason: error.message, type: "uncertain" } as const)),
+					);
+				}
+				return {
+					operationId,
+					reason: "No native acknowledgement in this backend instance; no replacement work was submitted",
+					type: "uncertain",
+				} as const;
+			}),
+		start,
+	};
+});
+
+export function claudeCodeLayer(options: ClaudeOptions = {}) {
+	return Layer.effect(Backend, makeClaudeBackend(options)).pipe(Layer.provide(ClaudeProvider.layer));
+}

package/src/options.ts

@@ -0,0 +1,19 @@
+import type { Effect } from "effect";
+export interface ClaudeTool {
+	readonly call: (
+		args: unknown,
+		callId: string,
+	) => Effect.Effect<{
+		readonly text: string;
+		readonly ok: boolean;
+	}>;
+	readonly description: string;
+	readonly inputSchema: Readonly<Record<string, unknown>>;
+	readonly name: string;
+}
+export interface ClaudeOptions {
+	readonly executable?: string;
+	readonly skills?: string;
+	readonly systemPrompt?: string;
+	readonly tools?: readonly ClaudeTool[];
+}

package/src/protocol.ts

@@ -0,0 +1,9 @@
+import type { RunEvent } from "@shivaedev/agent/events.ts";
+export type Origin = NonNullable<RunEvent["origin"]>;
+export type RawPayload = NonNullable<RunEvent["raw"]>;
+export type ChildOutcome = Extract<
+	RunEvent,
+	{
+		type: "child.ended";
+	}
+>["outcome"];

package/src/runState.ts

@@ -0,0 +1,70 @@
+import { Deferred, Effect, Exit, PubSub, Ref, Stream, type Take } from "effect";
+import type { RunEvent } from "@shivaedev/agent/events.ts";
+import { type ReadFailure, UnknownAcceptance } from "@shivaedev/agent/failures.ts";
+import type { ExecutionState, Receipt } from "@shivaedev/agent/run.ts";
+import type { SessionConnection } from "#SessionConnection.ts";
+export const makeRunState = Effect.fn("ClaudeCode.makeRunState")(function* (operationId: string, session: SessionConnection) {
+	const acknowledged = yield* Deferred.make<Receipt, UnknownAcceptance>();
+	const history = yield* Ref.make<readonly RunEvent[]>([]);
+	const state = yield* Ref.make<typeof ExecutionState.Type>("accepted");
+	const terminalSeen = yield* Ref.make(false);
+	const failure = yield* Ref.make<ReadFailure | undefined>(undefined);
+	const hub = yield* PubSub.unbounded<Take.Take<RunEvent, ReadFailure>>({ replay: Number.POSITIVE_INFINITY });
+	function publish(event: RunEvent) {
+		return Ref.update(history, (events) => [...events, event]).pipe(Effect.andThen(PubSub.publish(hub, [event])));
+	}
+	function observe(event: RunEvent) {
+		return Effect.gen(function* () {
+			if (event.type === "session.opened") {
+				const receipt: Receipt = {
+					backend: "claude-code",
+					operationId,
+					reference: { value: operationId, version: 1 },
+					session: { value: event.reference, version: 1 },
+				};
+				if (yield* Deferred.succeed(acknowledged, receipt)) {
+					yield* publish({ receipt, type: "acknowledged" });
+				}
+			}
+			if (event.type === "execution") {
+				yield* Ref.set(state, event.state);
+				if (event.state !== "awaiting-input") {
+					yield* Ref.set(terminalSeen, event.state === "completed" || event.state === "failed" || event.state === "interrupted");
+				}
+			}
+			yield* publish(event);
+		});
+	}
+	const consume = session.events.pipe(
+		Stream.runForEach(observe),
+		Effect.matchEffect({
+			onFailure: (error) =>
+				Ref.set(failure, error).pipe(
+					Effect.andThen(publish({ detail: error.message, kind: "provider-unavailable", type: "gap" })),
+					Effect.andThen(PubSub.end(hub, Exit.fail(error))),
+				),
+			onSuccess: () =>
+				Effect.gen(function* () {
+					const terminal = yield* Ref.get(terminalSeen);
+					if (!terminal) {
+						yield* publish({ detail: "The provider stream ended without a terminal turn result", kind: "missing-output", type: "gap" });
+					}
+					yield* PubSub.end(hub, Exit.void);
+				}),
+		}),
+		Effect.ensuring(
+			Deferred.fail(
+				acknowledged,
+				new UnknownAcceptance({
+					backend: "claude-code",
+					message: "The provider ended before acknowledging its native session identity",
+					operationId,
+				}),
+			),
+		),
+		Effect.onInterrupt(() => PubSub.end(hub, Exit.void)),
+	);
+	yield* Effect.forkScoped(consume);
+	return { acknowledged, events: Stream.fromPubSubTake(hub), failure, history, session, state };
+});
+export type RunState = Effect.Success<ReturnType<typeof makeRunState>>;