@shivaedev/agent-codex 0.1.0 → 0.3.0

package/src/adapters/connect.ts

@@ -0,0 +1,129 @@
+import { Effect, Schema } from "effect";
+import { type BackendFailure, BackendUnavailable, ProtocolFailure, UnknownAcceptance } from "@shivaedev/agent/failures.ts";
+import type { LineProcess } from "#adapters/process.ts";
+import type { RpcNotification } from "#adapters/rpc.ts";
+import { Envelope, rejected } from "#adapters/rpcProtocol.ts";
+
+interface Pending {
+	readonly complete: (effect: Effect.Effect<unknown, BackendFailure>) => void;
+	readonly operationId: string | undefined;
+}
+export function connect(
+	child: LineProcess,
+	timeoutMs: number,
+	notified: (notification: RpcNotification) => void,
+	serverRequest: (id: number | string, method: string, params: unknown) => void,
+	exited: () => void,
+) {
+	const pending = new Map<number, Pending>();
+	let closed = false;
+	let nextId = 0;
+	function send(message: unknown) {
+		return child.write(JSON.stringify(message));
+	}
+	function unavailable() {
+		return new BackendUnavailable({ backend: "codex", message: "Codex app-server exited" });
+	}
+	function ambiguous(operationId: string, message: string) {
+		return new UnknownAcceptance({ backend: "codex", message, operationId });
+	}
+	child.onExit(() => {
+		closed = true;
+		for (const entry of pending.values()) {
+			entry.complete(
+				Effect.fail(
+					entry.operationId === undefined
+						? unavailable()
+						: ambiguous(entry.operationId, "Codex disconnected after submission; reconcile before retrying"),
+				),
+			);
+		}
+		pending.clear();
+		exited();
+	});
+	child.onLine((line) => {
+		let envelope: typeof Envelope.Type;
+		try {
+			envelope = Schema.decodeUnknownSync(Envelope)(JSON.parse(line));
+		} catch {
+			for (const entry of pending.values()) {
+				entry.complete(
+					Effect.fail(
+						entry.operationId === undefined
+							? new ProtocolFailure({ backend: "codex", message: "Invalid Codex RPC envelope" })
+							: ambiguous(entry.operationId, "Invalid response after mutation"),
+					),
+				);
+			}
+			pending.clear();
+			return;
+		}
+		dispatch(envelope);
+	});
+	function dispatch(envelope: typeof Envelope.Type) {
+		if (envelope.method !== undefined) {
+			if (envelope.id === undefined) {
+				notified({ method: envelope.method, params: envelope.params });
+			} else {
+				serverRequest(envelope.id, envelope.method, envelope.params);
+			}
+			return;
+		}
+		if (typeof envelope.id !== "number") {
+			return;
+		}
+		const entry = pending.get(envelope.id);
+		pending.delete(envelope.id);
+		if (entry === undefined) {
+			return;
+		}
+		if (envelope.error === undefined) {
+			entry.complete(Effect.succeed(envelope.result));
+			return;
+		}
+		const error = rejected(envelope.error);
+		entry.complete(
+			Effect.fail(
+				error._tag === "ProtocolFailure" && entry.operationId !== undefined
+					? ambiguous(entry.operationId, "Invalid rejection after mutation")
+					: error,
+			),
+		);
+	}
+
+	function request(method: string, params: unknown, operationId?: string) {
+		return Effect.callback<unknown, BackendFailure>((complete) => {
+			if (closed) {
+				complete(Effect.fail(unavailable()));
+				return;
+			}
+			nextId += 1;
+			const id = nextId;
+			pending.set(id, { complete, operationId });
+			try {
+				send({ id, method, params });
+			} catch {
+				pending.delete(id);
+				complete(Effect.fail(operationId === undefined ? unavailable() : ambiguous(operationId, "Codex write failed after submission")));
+			}
+			return Effect.sync(() => {
+				pending.delete(id);
+			});
+		}).pipe(
+			Effect.timeout(`${timeoutMs} millis`),
+			Effect.catchTag("TimeoutError", () =>
+				Effect.fail(
+					operationId === undefined
+						? new BackendUnavailable({ backend: "codex", message: `Codex ${method} timed out` })
+						: ambiguous(operationId, `Codex ${method} timed out; reconcile before retrying`),
+				),
+			),
+		);
+	}
+	return {
+		deny: (id: number | string) => send({ error: { code: -32_601, message: "No approval handler configured" }, id }),
+		notify: (method: string, params: unknown) => send({ method, params }),
+		request,
+		respond: (id: number | string, result: unknown) => send({ id, result }),
+	};
+}

package/src/adapters/delivery.ts

@@ -0,0 +1,137 @@
+import { Deferred, Effect, Schema, Semaphore } from "effect";
+import { type BackendFailure, BackendUnavailable, Rejected, UnknownAcceptance } from "@shivaedev/agent/failures.ts";
+import type { ImageInput, Input } from "@shivaedev/agent/run.ts";
+import { deliveryState } from "#adapters/deliveryState.ts";
+import { TurnNotification } from "#adapters/protocol.ts";
+import type { RpcNotification } from "#adapters/rpc.ts";
+import { AppServer } from "#adapters/server.ts";
+import { turnRequests } from "#adapters/turnRequests.ts";
+export const delivery = Effect.fn("Codex.delivery")(function* (
+	threadId: string,
+	settings: { model?: string; effort?: string },
+	remember: (operationId: string) => void,
+) {
+	const server = yield* AppServer;
+	const { state, gate, close, queue } = yield* deliveryState;
+	const requests = yield* turnRequests(threadId, settings);
+	function closedError() {
+		return new BackendUnavailable({ backend: "codex", message: "Session closed before delivery reached Codex" });
+	}
+	const start = Effect.fn("Codex.start")(function* (input: ImageInput, operationId: string) {
+		if (state.closed) {
+			return yield* closedError();
+		}
+		if (state.uncertain !== undefined) {
+			return yield* new UnknownAcceptance({
+				backend: "codex",
+				message: "Reconcile the previous submission before sending another turn",
+				operationId: state.uncertain,
+			});
+		}
+		remember(operationId);
+		state.active = yield* requests.start(input, operationId).pipe(
+			Effect.tapError((error) =>
+				Effect.sync(() => {
+					if (error._tag !== "Rejected") {
+						state.uncertain = operationId;
+					}
+				}),
+			),
+		);
+
+		if (!state.finished.has(state.active)) {
+			state.finished.set(state.active, yield* Deferred.make<void, BackendFailure>());
+		}
+		return state.active;
+	});
+	const flush = Effect.gen(function* () {
+		if (state.active !== undefined || state.uncertain !== undefined || state.closed) {
+			return;
+		}
+		const next = state.pending.shift();
+		if (next === undefined) {
+			return;
+		}
+		yield* start(next.input, next.input.id ?? crypto.randomUUID()).pipe(
+			Effect.matchEffect({
+				onFailure: (error) => Deferred.fail(next.accepted, error),
+				onSuccess: () => Deferred.succeed(next.accepted, undefined),
+			}),
+		);
+	});
+	const settle = Effect.fn("Codex.settle")(function* (turnId: string) {
+		if (state.active !== turnId) {
+			return;
+		}
+		state.active = undefined;
+		const signal = state.finished.get(turnId);
+		if (signal !== undefined) {
+			yield* Deferred.succeed(signal, undefined);
+		}
+		yield* flush;
+	});
+	const track = Effect.fn("Codex.track")(function* (notification: RpcNotification) {
+		const value = Schema.decodeUnknownOption(TurnNotification)(notification.params);
+		if (value._tag === "None" || value.value.threadId !== threadId) {
+			return;
+		}
+		const id = value.value.turn.id;
+		if (notification.method === "turn/completed") {
+			yield* settle(id);
+			return;
+		}
+		if (notification.method !== "turn/started") {
+			return;
+		}
+		state.active = id;
+		if (!state.finished.has(id)) {
+			state.finished.set(id, yield* Deferred.make<void, BackendFailure>());
+		}
+	});
+
+	yield* Effect.addFinalizer(() => close);
+	yield* Effect.forkScoped(server.exited.pipe(Effect.andThen(close)));
+
+	return {
+		interrupt: (turnId: string) =>
+			Effect.gen(function* () {
+				if (state.active !== turnId) {
+					return;
+				}
+				const outcome = yield* requests.interrupt(turnId);
+				if (outcome === "inactive") {
+					yield* Semaphore.withPermit(gate)(settle(turnId));
+				}
+				const signal = state.finished.get(turnId);
+				if (signal !== undefined) {
+					yield* Deferred.await(signal);
+				}
+			}),
+		queue: (input: Input) => queue(input, flush),
+		recovered: (turnId: string, running: boolean) =>
+			Semaphore.withPermit(gate)(
+				Effect.gen(function* () {
+					state.active = running ? turnId : undefined;
+					state.uncertain = undefined;
+					if (running && !state.finished.has(turnId)) {
+						state.finished.set(turnId, yield* Deferred.make<void, BackendFailure>());
+					}
+					yield* flush;
+				}),
+			),
+		start: (input: ImageInput, operationId: string) => Semaphore.withPermit(gate)(start(input, operationId)),
+		steer: (expected: string, input: Input) =>
+			Semaphore.withPermit(gate)(
+				Effect.gen(function* () {
+					if (state.active !== expected) {
+						return yield* new Rejected({ backend: "codex", message: "The expected turn is no longer active" });
+					}
+					const operationId = input.id ?? crypto.randomUUID();
+					remember(operationId);
+					yield* requests.steer(expected, input, operationId);
+				}),
+			),
+		track: (notification: RpcNotification) => Semaphore.withPermit(gate)(track(notification)),
+	};
+});
+export type Delivery = Effect.Success<ReturnType<typeof delivery>>;

package/src/adapters/deliveryState.ts

@@ -0,0 +1,43 @@
+import { Deferred, Effect, Semaphore } from "effect";
+import { type BackendFailure, BackendUnavailable } from "@shivaedev/agent/failures.ts";
+import type { Input } from "@shivaedev/agent/run.ts";
+
+interface Pending {
+	readonly accepted: Deferred.Deferred<void, BackendFailure>;
+	readonly input: Input;
+}
+interface State {
+	active: string | undefined;
+	closed: boolean;
+	finished: Map<string, Deferred.Deferred<void, BackendFailure>>;
+	pending: Pending[];
+	uncertain: string | undefined;
+}
+export const deliveryState = Effect.gen(function* () {
+	const gate = yield* Semaphore.make(1);
+	const state: State = { active: undefined, closed: false, finished: new Map(), pending: [], uncertain: undefined };
+	const close = Effect.gen(function* () {
+		state.closed = true;
+		const error = new BackendUnavailable({ backend: "codex", message: "Session closed before delivery reached Codex" });
+		for (const next of state.pending.splice(0)) {
+			yield* Deferred.fail(next.accepted, error);
+		}
+		for (const signal of state.finished.values()) {
+			yield* Deferred.fail(signal, error);
+		}
+	});
+	const queue = Effect.fn("Codex.queue")(function* (input: Input, flush: Effect.Effect<void>) {
+		const accepted = yield* Deferred.make<void, BackendFailure>();
+		yield* Semaphore.withPermit(gate)(
+			Effect.gen(function* () {
+				if (state.closed) {
+					return yield* new BackendUnavailable({ backend: "codex", message: "Session closed before delivery reached Codex" });
+				}
+				state.pending.push({ accepted, input });
+				yield* flush;
+			}),
+		);
+		yield* Deferred.await(accepted);
+	});
+	return { close, gate, queue, state };
+});

package/src/adapters/engine.ts

@@ -0,0 +1,11 @@
+import { Effect } from "effect";
+import { backend } from "#adapters/backend.ts";
+import { census } from "#adapters/census.ts";
+import { initializeEngine } from "#adapters/initializeEngine.ts";
+import type { LineProcess } from "#adapters/process.ts";
+import type { CodexConfiguration } from "#config.ts";
+
+export const engine = Effect.fn("Codex.engine")(function* (config: CodexConfiguration, spawn?: () => LineProcess) {
+	const state = yield* initializeEngine(config, spawn);
+	return { backend: backend(state), census: census(state) };
+});

package/src/adapters/features.ts

@@ -0,0 +1,62 @@
+import type { Scope } from "effect";
+import { Effect } from "effect";
+import type { ConfiguredFeatures, FeatureImplementations } from "@shivaedev/agent/backend.ts";
+import type { BackendFailure } from "@shivaedev/agent/failures.ts";
+import { Rejected } from "@shivaedev/agent/failures.ts";
+import type { ImageInput, Receipt, StartRequest } from "@shivaedev/agent/run.ts";
+import { ModelListResponse } from "#adapters/protocol.ts";
+import { decode, readRequest, transcript } from "#adapters/reads.ts";
+import { AppServer } from "#adapters/server.ts";
+import type { Session } from "#adapters/session.ts";
+export const features = Effect.fn("Codex.features")(function* (
+	sessions: Map<string, Session>,
+	start: (
+		request: Omit<StartRequest, "input"> & { readonly input: ImageInput },
+		session?: { value: string; version: number },
+	) => Effect.Effect<Receipt, BackendFailure, Scope.Scope>,
+) {
+	const server = yield* AppServer;
+	function driverFor(receipt: Receipt) {
+		return Effect.suspend(() => {
+			const session = sessions.get(receipt.session?.value ?? "");
+			return session === undefined
+				? Effect.fail(new Rejected({ backend: "codex", message: "No live session for this receipt" }))
+				: Effect.succeed(session.driver);
+		});
+	}
+	const models: FeatureImplementations["models"] = {
+		list: readRequest("model/list", {}).pipe(
+			Effect.flatMap((value) => decode(ModelListResponse, value)),
+			Effect.map(({ data }) =>
+				data.map((model) => ({
+					defaultEffort: model.defaultReasoningEffort,
+					efforts: model.supportedReasoningEfforts.map((effort) => effort.reasoningEffort),
+					id: model.model,
+					isDefault: model.isDefault,
+					name: model.displayName,
+				})),
+			),
+			Effect.provideService(AppServer, server),
+		),
+	};
+	return {
+		imageInput: { implementation: { start }, support: "supported" },
+		interruption: {
+			implementation: { interrupt: (receipt) => driverFor(receipt).pipe(Effect.flatMap((driver) => driver.interrupt(receipt.reference.value))) },
+			support: "supported",
+		},
+		models: { implementation: models, support: "supported" },
+		queuedInput: {
+			implementation: { queue: (receipt, input) => driverFor(receipt).pipe(Effect.flatMap((driver) => driver.queue(input))) },
+			support: "supported",
+		},
+		sessions: { implementation: { resume: (session, request) => start(request, session) }, support: "supported" },
+		steering: {
+			implementation: {
+				steer: (receipt, input) => driverFor(receipt).pipe(Effect.flatMap((driver) => driver.steer(receipt.reference.value, input))),
+			},
+			support: "supported",
+		},
+		transcript: { implementation: { read: (receipt) => transcript(receipt).pipe(Effect.provideService(AppServer, server)) }, support: "supported" },
+	} satisfies ConfiguredFeatures;
+});

package/src/adapters/handshake.ts

@@ -0,0 +1,35 @@
+import { Effect, Option, Schema } from "effect";
+import { InitializeResponse } from "#adapters/protocol.ts";
+import type { Request } from "#adapters/Request.ts";
+
+const CLIENT_INFO = { name: "platform_agent_codex", title: "Platform Codex", version: "0.0.0" };
+
+export const MUTED_NOTIFICATIONS = [
+	"item/agentMessage/delta",
+	"item/commandExecution/outputDelta",
+	"item/fileChange/outputDelta",
+	"item/fileChange/patchUpdated",
+	"item/plan/delta",
+	"item/reasoning/summaryPartAdded",
+	"item/reasoning/summaryTextDelta",
+	"item/reasoning/textDelta",
+	"turn/diff/updated",
+];
+
+const decodeInitialize = Schema.decodeUnknownOption(InitializeResponse);
+
+function versionOf(response: unknown): Option.Option<string> {
+	return Option.map(decodeInitialize(response), ({ userAgent }) => userAgent.split(" ")[0]?.split("/")[1] ?? "");
+}
+
+// Codex requires one initialize followed by initialized, with experimentalApi enabled for dynamic tools.
+export function handshake(request: Request) {
+	return request("initialize", {
+		capabilities: {
+			experimentalApi: true,
+			optOutNotificationMethods: MUTED_NOTIFICATIONS,
+			requestAttestation: false,
+		},
+		clientInfo: CLIENT_INFO,
+	}).pipe(Effect.map(versionOf));
+}

package/src/adapters/initializeCodex.ts

@@ -0,0 +1,8 @@
+import { Effect } from "effect";
+import { initializeEngine } from "#adapters/initializeEngine.ts";
+import { CodexConfig } from "#config.ts";
+
+export const initializeCodex = Effect.gen(function* () {
+	const config = yield* CodexConfig;
+	return yield* initializeEngine(config);
+});

package/src/adapters/initializeEngine.ts

@@ -0,0 +1,75 @@
+import { Effect, Semaphore } from "effect";
+import { Rejected, UnknownAcceptance } from "@shivaedev/agent/failures.ts";
+import type { ImageInput, Receipt, StartRequest } from "@shivaedev/agent/run.ts";
+import { features } from "#adapters/features.ts";
+import type { LineProcess } from "#adapters/process.ts";
+import { observe, readRequest } from "#adapters/reads.ts";
+import { receiptOf, recovery } from "#adapters/recovery.ts";
+import { AppServer, openServer } from "#adapters/server.ts";
+import { openSession, type Session } from "#adapters/session.ts";
+import type { CodexConfiguration } from "#config.ts";
+export const initializeEngine = Effect.fn("Codex.initializeEngine")(function* (config: CodexConfiguration, spawn?: () => LineProcess) {
+	const server = yield* openServer(config, spawn);
+	const sessions = new Map<string, Session>();
+	const { operations, refusals, reconcile } = yield* recovery(sessions).pipe(Effect.provideService(AppServer, server));
+	const submissionGate = yield* Semaphore.make(1);
+	const submit = Effect.fn("Codex.submit")(function* (
+		request: Omit<StartRequest, "input"> & { readonly input: ImageInput },
+		reference?: { value: string; version: number },
+	) {
+		if (operations.has(request.operationId)) {
+			const result = yield* reconcile(request.operationId);
+			if (result.type === "accepted") {
+				return result.receipt;
+			}
+			if (result.type === "not-accepted") {
+				return yield* new Rejected({ backend: "codex", message: result.evidence });
+			}
+			return yield* new UnknownAcceptance({
+				backend: "codex",
+				message: result.reason,
+				operationId: request.operationId,
+			});
+		}
+		if (reference !== undefined && (reference.version !== 1 || server.claims.isNode(reference.value))) {
+			return yield* new Rejected({ backend: "codex", message: "Child threads are observed passively and cannot be resumed" });
+		}
+		operations.set(request.operationId, reference?.value);
+		const session = yield* openSession(config, request, reference?.value, (operationId, threadId) => {
+			operations.set(operationId, threadId);
+		}).pipe(Effect.provideService(AppServer, server));
+		operations.set(request.operationId, session.threadId);
+		sessions.set(session.threadId, session);
+		yield* Effect.addFinalizer(() =>
+			Effect.sync(() => {
+				if (sessions.get(session.threadId) === session) {
+					sessions.delete(session.threadId);
+				}
+			}),
+		);
+		const turnId = yield* session.driver.start(request.input, request.operationId);
+		return receiptOf(request.operationId, session.threadId, turnId);
+	});
+	function start(request: Omit<StartRequest, "input"> & { readonly input: ImageInput }, session?: { value: string; version: number }) {
+		return Semaphore.withPermit(submissionGate)(submit(request, session)).pipe(
+			Effect.tapError((error) =>
+				Effect.sync(() => {
+					if (error._tag === "Rejected") {
+						refusals.set(request.operationId, error.message);
+					}
+				}),
+			),
+		);
+	}
+	return {
+		claims: server.claims,
+		exited: server.exited,
+		features: yield* features(sessions, start).pipe(Effect.provideService(AppServer, server)),
+		inspect: (receipt: Receipt) => observe(receipt).pipe(Effect.provideService(AppServer, server)),
+		read: (method: string, params: unknown) => readRequest(method, params).pipe(Effect.provideService(AppServer, server)),
+		reconcile,
+		sessions,
+		start,
+	};
+});
+export type EngineState = Effect.Success<ReturnType<typeof initializeEngine>>;

package/src/adapters/items.ts

@@ -0,0 +1,133 @@
+import type { Raw as RawSchema } from "@shivaedev/agent/eventData.ts";
+import type { RunEvent as AgentEvent } from "@shivaedev/agent/events.ts";
+
+type RawPayload = typeof RawSchema.Type;
+
+import { Option, Schema } from "effect";
+import { KnownItem } from "#adapters/protocolItems.ts";
+import { userMessageEvent } from "#adapters/userMessageEvent.ts";
+
+type Item<T extends KnownItem["type"]> = Extract<KnownItem, { type: T }>;
+
+const decodeItem = Schema.decodeUnknownOption(KnownItem);
+
+type Started = Extract<AgentEvent, { type: "tool.started" }>;
+
+function toolIdentity(item: KnownItem): Pick<Started, "name" | "providerName"> {
+	if (item.type === "mcpToolCall") {
+		return { name: `${item.server}: ${item.tool}`, providerName: `${item.server}/${item.tool}` };
+	}
+	return item.type === "dynamicToolCall" ? { name: item.tool } : { name: item.type };
+}
+
+function toolInput(item: KnownItem): string {
+	switch (item.type) {
+		case "commandExecution":
+			return item.command;
+		case "dynamicToolCall":
+			return JSON.stringify(item.arguments);
+		case "fileChange":
+			return item.changes.map((change) => change.path).join("\n");
+		case "mcpToolCall":
+			return JSON.stringify(item.arguments);
+		case "webSearch":
+			return item.query;
+		default:
+			return "";
+	}
+}
+
+function isTool(
+	item: KnownItem,
+): item is Item<"commandExecution"> | Item<"dynamicToolCall"> | Item<"fileChange"> | Item<"mcpToolCall"> | Item<"webSearch"> {
+	return (
+		item.type === "commandExecution"
+		|| item.type === "dynamicToolCall"
+		|| item.type === "fileChange"
+		|| item.type === "mcpToolCall"
+		|| item.type === "webSearch"
+	);
+}
+
+function commandOk(item: Item<"commandExecution">): boolean {
+	return item.status === "completed" && (item.exitCode ?? 0) === 0;
+}
+
+function dynamicOutcome(item: Item<"dynamicToolCall">) {
+	return {
+		ok: item.success ?? item.status === "completed",
+		output: (item.contentItems ?? []).map((part) => part.text ?? "").join("\n"),
+	};
+}
+
+function toolOutcome(item: Item<"commandExecution" | "dynamicToolCall" | "fileChange" | "mcpToolCall" | "webSearch">): {
+	ok: boolean;
+	output: string;
+} {
+	switch (item.type) {
+		case "commandExecution":
+			return { ok: commandOk(item), output: item.aggregatedOutput ?? "" };
+		case "dynamicToolCall":
+			return dynamicOutcome(item);
+		case "fileChange":
+			return {
+				ok: item.status === "completed",
+				output: item.changes.map((change) => change.diff).join("\n"),
+			};
+		case "mcpToolCall":
+			return {
+				ok: item.status === "completed",
+				output: JSON.stringify(item.error ?? item.result ?? null),
+			};
+		case "webSearch":
+			return { ok: true, output: "" };
+	}
+}
+
+function reasoningText(item: Item<"reasoning">): string {
+	return [...(item.summary ?? []), ...(item.content ?? [])].join("\n");
+}
+
+function knownStarted(raw: RawPayload, item: KnownItem): AgentEvent[] {
+	if (isTool(item)) {
+		return [
+			{
+				input: toolInput(item),
+				...toolIdentity(item),
+				raw,
+				toolId: item.id,
+				type: "tool.started",
+			},
+		];
+	}
+	return item.type === "agentMessage" || item.type === "reasoning" || item.type === "userMessage" ? [] : [{ raw, type: "raw" }];
+}
+
+function knownCompleted(raw: RawPayload, item: KnownItem): AgentEvent[] {
+	if (isTool(item)) {
+		return [{ ...toolOutcome(item), raw, toolId: item.id, type: "tool.completed" }];
+	}
+	switch (item.type) {
+		case "agentMessage":
+			return [{ parts: [{ text: item.text, type: "text" }], raw, role: "agent", type: "message" }];
+		case "userMessage":
+			return [userMessageEvent(item, raw)];
+		case "reasoning": {
+			const text = reasoningText(item);
+			return text.length === 0 ? [] : [{ raw, text, type: "thinking" }];
+		}
+		default:
+			return [{ raw, type: "raw" }];
+	}
+}
+
+function projectItem(project: (raw: RawPayload, item: KnownItem) => AgentEvent[]) {
+	return (raw: RawPayload, item: unknown): AgentEvent[] =>
+		Option.match(decodeItem(item), {
+			onNone: () => [{ raw, type: "raw" }],
+			onSome: (known) => project(raw, known),
+		});
+}
+
+export const itemStarted = projectItem(knownStarted);
+export const itemCompleted = projectItem(knownCompleted);