@vitest-agent/cli 1.0.0

package/commands/record.js

@@ -0,0 +1,204 @@
+import { recordSessionEnd, recordSessionStart } from "../lib/record-session.js";
+import { recordTddArtifactEffect } from "../lib/record-tdd-artifact.js";
+import { recordTurnEffect } from "../lib/record-turn.js";
+import { recordRunWorkspaceChangesEffect } from "../lib/record-workspace-changes.js";
+import { DataReader, DataStore } from "@vitest-agent/sdk";
+import { Effect, Option } from "effect";
+import { Args, Command, Options } from "@effect/cli";
+
+//#region src/commands/record.ts
+/**
+* CLI record command -- write session/turn data to the database.
+*
+* Hook scripts in plugin/hooks/ shell out to these subcommands. The
+* record-turn and record-session libs (in ../lib) implement the actual
+* write effects; commands here are thin \@effect/cli wrappers.
+*
+* @packageDocumentation
+*/
+const chatId = Options.text("chat-id").pipe(Options.withDescription("Host chat id (`session_id` in the Claude Code hook envelope; equivalent in other clients)"));
+const occurredAt = Options.text("occurred-at").pipe(Options.withDefault((/* @__PURE__ */ new Date()).toISOString()), Options.withDescription("ISO 8601 timestamp; defaults to now"));
+const payloadArg = Args.text({ name: "payload-json" }).pipe(Args.withDescription("Stringified JSON payload (validated against TurnPayload)"));
+const project = Options.text("project");
+const cwd = Options.text("cwd");
+const projectOptional = Options.optional(Options.text("project"));
+const cwdOptional = Options.optional(Options.text("cwd"));
+const turnSubcommand = Command.make("turn", {
+	chatId,
+	occurredAt,
+	project: projectOptional,
+	cwd: cwdOptional,
+	payload: payloadArg
+}, ({ chatId, occurredAt, project, cwd, payload }) => recordTurnEffect({
+	chatId,
+	payloadJson: payload,
+	occurredAt,
+	...project._tag === "Some" && { project: project.value },
+	...cwd._tag === "Some" && { cwd: cwd.value }
+}).pipe(Effect.flatMap((result) => Effect.sync(() => process.stdout.write(`${JSON.stringify(result)}\n`))), Effect.catchAll((err) => Effect.sync(() => {
+	process.stderr.write(`record turn: ${err instanceof Error ? err.message : String(err)}\n`);
+	process.exit(1);
+})))).pipe(Command.withDescription("Validate a TurnPayload JSON and write a turn row"));
+const agentKind = Options.choice("agent-kind", ["main", "subagent"]).pipe(Options.withDefault("main"));
+const agentType = Options.optional(Options.text("agent-type"));
+const parentChatId = Options.optional(Options.text("parent-chat-id"));
+const triageWasNonEmpty = Options.boolean("triage-was-non-empty").pipe(Options.withDefault(false));
+const startedAt = Options.text("started-at").pipe(Options.withDefault((/* @__PURE__ */ new Date()).toISOString()));
+const sessionStartSubcommand = Command.make("session-start", {
+	chatId,
+	project,
+	cwd,
+	agentKind,
+	agentType,
+	parentChatId,
+	triageWasNonEmpty,
+	startedAt
+}, (opts) => recordSessionStart({
+	chatId: opts.chatId,
+	project: opts.project,
+	cwd: opts.cwd,
+	agentKind: opts.agentKind,
+	...opts.agentType._tag === "Some" && { agentType: opts.agentType.value },
+	...opts.parentChatId._tag === "Some" && { parentChatId: opts.parentChatId.value },
+	triageWasNonEmpty: opts.triageWasNonEmpty,
+	startedAt: opts.startedAt
+}).pipe(Effect.flatMap((result) => Effect.sync(() => process.stdout.write(`${JSON.stringify(result)}\n`))), Effect.catchAll((err) => Effect.sync(() => {
+	process.stderr.write(`record session-start: ${err instanceof Error ? err.message : String(err)}\n`);
+	process.exit(1);
+})))).pipe(Command.withDescription("Insert a new sessions row"));
+const endedAt = Options.text("ended-at").pipe(Options.withDefault((/* @__PURE__ */ new Date()).toISOString()));
+const endReason = Options.optional(Options.text("end-reason"));
+const sessionEndSubcommand = Command.make("session-end", {
+	chatId,
+	endedAt,
+	endReason
+}, (opts) => recordSessionEnd({
+	chatId: opts.chatId,
+	endedAt: opts.endedAt,
+	endReason: opts.endReason._tag === "Some" ? opts.endReason.value : null
+}).pipe(Effect.flatMap(() => Effect.sync(() => process.stdout.write(`{"ok":true}\n`))), Effect.catchAll((err) => Effect.sync(() => {
+	process.stderr.write(`record session-end: ${err instanceof Error ? err.message : String(err)}\n`);
+	process.exit(1);
+})))).pipe(Command.withDescription("Update sessions.ended_at + end_reason"));
+const artifactKindOpt = Options.choice("artifact-kind", [
+	"test_written",
+	"test_failed_run",
+	"code_written",
+	"test_passed_run",
+	"refactor",
+	"test_weakened"
+]);
+const filePathOpt = Options.optional(Options.text("file-path"));
+const testCaseIdOpt = Options.optional(Options.integer("test-case-id"));
+const testRunIdOpt = Options.optional(Options.integer("test-run-id"));
+const testFirstFailureRunIdOpt = Options.optional(Options.integer("test-first-failure-run-id"));
+const diffExcerptOpt = Options.optional(Options.text("diff-excerpt"));
+const recordedAtOpt = Options.text("recorded-at").pipe(Options.withDefault((/* @__PURE__ */ new Date()).toISOString()));
+const tddArtifactSubcommand = Command.make("tdd-artifact", {
+	chatId,
+	project: projectOptional,
+	cwd: cwdOptional,
+	artifactKind: artifactKindOpt,
+	filePath: filePathOpt,
+	testCaseId: testCaseIdOpt,
+	testRunId: testRunIdOpt,
+	testFirstFailureRunId: testFirstFailureRunIdOpt,
+	diffExcerpt: diffExcerptOpt,
+	recordedAt: recordedAtOpt
+}, (opts) => Effect.gen(function* () {
+	let fileId;
+	if (opts.filePath._tag === "Some") fileId = yield* (yield* DataStore).ensureFile(opts.filePath.value);
+	return yield* recordTddArtifactEffect({
+		chatId: opts.chatId,
+		...opts.project._tag === "Some" && { project: opts.project.value },
+		...opts.cwd._tag === "Some" && { cwd: opts.cwd.value },
+		artifactKind: opts.artifactKind,
+		...fileId !== void 0 && { fileId },
+		...opts.testCaseId._tag === "Some" && { testCaseId: opts.testCaseId.value },
+		...opts.testRunId._tag === "Some" && { testRunId: opts.testRunId.value },
+		...opts.testFirstFailureRunId._tag === "Some" && { testFirstFailureRunId: opts.testFirstFailureRunId.value },
+		...opts.diffExcerpt._tag === "Some" && { diffExcerpt: opts.diffExcerpt.value },
+		recordedAt: opts.recordedAt
+	});
+}).pipe(Effect.flatMap((result) => Effect.sync(() => process.stdout.write(`${JSON.stringify(result)}\n`))), Effect.catchAll((err) => Effect.sync(() => {
+	process.stderr.write(`record tdd-artifact: ${err instanceof Error ? err.message : String(err)}\n`);
+	process.exit(1);
+})))).pipe(Command.withDescription("Record a TDD artifact (D7: CLI-only)"));
+const testCaseTurnsSubcommand = Command.make("test-case-turns", { chatId }, ({ chatId }) => Effect.gen(function* () {
+	const store = yield* DataStore;
+	const reader = yield* DataReader;
+	const updated = yield* store.backfillTestCaseTurns(chatId);
+	const latestId = yield* reader.getLatestTestCaseForSession(chatId);
+	return {
+		updated,
+		latestTestCaseId: Option.getOrNull(latestId)
+	};
+}).pipe(Effect.flatMap((result) => Effect.sync(() => process.stdout.write(`${JSON.stringify(result)}\n`))), Effect.catchAll((err) => Effect.sync(() => {
+	process.stderr.write(`record test-case-turns: ${err instanceof Error ? err.message : String(err)}\n`);
+	process.exit(1);
+})))).pipe(Command.withDescription("Backfill test_cases.created_turn_id from file_edits in the current session (BUG-2 fix)"));
+const invocationMethodOpt = Options.choice("invocation-method", [
+	"bash",
+	"mcp",
+	"cli"
+]).pipe(Options.withDescription("How tests were invoked: \"bash\", \"mcp\", or \"cli\""), Options.withDefault("bash"));
+const runTriggerSubcommand = Command.make("run-trigger", {
+	chatId,
+	invocationMethod: invocationMethodOpt
+}, ({ chatId, invocationMethod }) => Effect.gen(function* () {
+	yield* (yield* DataStore).associateLatestRunWithSession({
+		chatId,
+		invocationMethod
+	});
+}).pipe(Effect.catchAll((err) => Effect.sync(() => {
+	process.stderr.write(`record run-trigger: ${err instanceof Error ? err.message : String(err)}\n`);
+	process.exit(1);
+})))).pipe(Command.withDescription("Associate the latest test run with the current Claude Code session"));
+const shaOpt = Options.text("sha");
+const parentShaOpt = Options.optional(Options.text("parent-sha"));
+const messageOpt = Options.optional(Options.text("message"));
+const authorOpt = Options.optional(Options.text("author"));
+const committedAtOpt = Options.optional(Options.text("committed-at"));
+const branchOpt = Options.optional(Options.text("branch"));
+const projectOpt = Options.optional(Options.text("project"));
+const filesArg = Args.text({ name: "files-json" }).pipe(Args.withDescription("JSON array of {\"filePath\",\"changeKind\"} objects"));
+const runWorkspaceChangesSubcommand = Command.make("run-workspace-changes", {
+	sha: shaOpt,
+	parentSha: parentShaOpt,
+	message: messageOpt,
+	author: authorOpt,
+	committedAt: committedAtOpt,
+	branch: branchOpt,
+	project: projectOpt,
+	files: filesArg
+}, (opts) => Effect.gen(function* () {
+	const parsed = yield* Effect.try({
+		try: () => JSON.parse(opts.files),
+		catch: (e) => /* @__PURE__ */ new Error(`Invalid files-json: ${e instanceof Error ? e.message : String(e)}`)
+	});
+	return yield* recordRunWorkspaceChangesEffect({
+		sha: opts.sha,
+		...opts.parentSha._tag === "Some" && { parentSha: opts.parentSha.value },
+		...opts.message._tag === "Some" && { message: opts.message.value },
+		...opts.author._tag === "Some" && { author: opts.author.value },
+		...opts.committedAt._tag === "Some" && { committedAt: opts.committedAt.value },
+		...opts.branch._tag === "Some" && { branch: opts.branch.value },
+		...opts.project._tag === "Some" && { project: opts.project.value },
+		files: parsed
+	});
+}).pipe(Effect.flatMap((result) => Effect.sync(() => process.stdout.write(`${JSON.stringify(result)}\n`))), Effect.catchAll((err) => Effect.sync(() => {
+	process.stderr.write(`record run-workspace-changes: ${err instanceof Error ? err.message : String(err)}\n`);
+	process.exit(1);
+})))).pipe(Command.withDescription("Record a commit + its changed files (driven by post-commit hook)"));
+const recordCommand = Command.make("record").pipe(Command.withSubcommands([
+	turnSubcommand,
+	sessionStartSubcommand,
+	sessionEndSubcommand,
+	tddArtifactSubcommand,
+	runWorkspaceChangesSubcommand,
+	runTriggerSubcommand,
+	testCaseTurnsSubcommand
+]), Command.withDescription("Hook write surface (Decision D3): turn, session-start, session-end, tdd-artifact, run-workspace-changes"));
+
+//#endregion
+export { recordCommand };

package/commands/triage.js

@@ -0,0 +1,40 @@
+import { formatTriageEffect } from "@vitest-agent/sdk";
+import { Effect } from "effect";
+import { Command, Options } from "@effect/cli";
+
+//#region src/commands/triage.ts
+/**
+* CLI triage command -- emits the W3 orientation triage brief.
+*
+* Calls the shared formatTriageEffect generator, which the MCP
+* triage_brief tool also uses. The plugin's SessionStart hook runs
+* this and pipes the result into Claude Code's additionalContext.
+*
+* @packageDocumentation
+*/
+const formatOption = Options.withDefault(Options.choice("format", [
+	"markdown",
+	"json",
+	"silent"
+]), "markdown");
+const projectOption = Options.optional(Options.text("project"));
+const maxLinesOption = Options.optional(Options.integer("max-lines"));
+const triageCommand = Command.make("triage", {
+	format: formatOption,
+	project: projectOption,
+	maxLines: maxLinesOption
+}, (opts) => Effect.gen(function* () {
+	const md = yield* formatTriageEffect({
+		...opts.project._tag === "Some" && { project: opts.project.value },
+		...opts.maxLines._tag === "Some" && { maxLines: opts.maxLines.value }
+	});
+	if (opts.format === "silent") return;
+	if (opts.format === "json") {
+		yield* Effect.sync(() => process.stdout.write(`${JSON.stringify({ triage: md })}\n`));
+		return;
+	}
+	yield* Effect.sync(() => process.stdout.write(md.length > 0 ? `${md}\n` : ""));
+})).pipe(Command.withDescription("Emit the W3 orientation triage brief for SessionStart"));
+
+//#endregion
+export { triageCommand };

package/commands/wrapup.js

@@ -0,0 +1,48 @@
+import { formatWrapupEffect } from "@vitest-agent/sdk";
+import { Effect } from "effect";
+import { Command, Options } from "@effect/cli";
+
+//#region src/commands/wrapup.ts
+/**
+* CLI wrapup command -- emits the W5 wrap-up prompt for a session.
+*
+* Drives the four interpretive hooks (Stop / SessionEnd / PreCompact /
+* UserPromptSubmit). Hooks invoke the bin with --kind set; humans on
+* the terminal can also run it on demand with --chat-id (host chat UUID)
+* or --row-id (internal integer FK, mostly for debugging).
+*
+* @packageDocumentation
+*/
+const rowIdOption = Options.optional(Options.integer("row-id"));
+const chatIdOption = Options.optional(Options.text("chat-id"));
+const kindOption = Options.withDefault(Options.choice("kind", [
+	"stop",
+	"session_end",
+	"pre_compact",
+	"tdd_handoff",
+	"user_prompt_nudge"
+]), "session_end");
+const userPromptHintOption = Options.optional(Options.text("user-prompt-hint"));
+const formatOption = Options.withDefault(Options.choice("format", ["markdown", "json"]), "markdown");
+const wrapupCommand = Command.make("wrapup", {
+	rowId: rowIdOption,
+	chatId: chatIdOption,
+	kind: kindOption,
+	userPromptHint: userPromptHintOption,
+	format: formatOption
+}, (opts) => Effect.gen(function* () {
+	const md = yield* formatWrapupEffect({
+		...opts.rowId._tag === "Some" && { sessionId: opts.rowId.value },
+		...opts.chatId._tag === "Some" && { chatId: opts.chatId.value },
+		kind: opts.kind,
+		...opts.userPromptHint._tag === "Some" && { userPromptHint: opts.userPromptHint.value }
+	});
+	if (opts.format === "json") {
+		yield* Effect.sync(() => process.stdout.write(`${JSON.stringify({ wrapup: md })}\n`));
+		return;
+	}
+	yield* Effect.sync(() => process.stdout.write(md.length > 0 ? `${md}\n` : ""));
+})).pipe(Command.withDescription("Emit the W5 wrap-up prompt for a session"));
+
+//#endregion
+export { wrapupCommand };

package/index.d.ts

@@ -0,0 +1,169 @@
+import * as NodeContext from "@effect/platform-node/NodeContext";
+import * as SqliteMigrator from "@effect/sql-sqlite-node/SqliteMigrator";
+import { Effect, Layer, LogLevel } from "effect";
+import { DataReader, DataStore, PerClientSessionMapWriter, ProjectIdentityNotResolvableError } from "@vitest-agent/sdk";
+
+//#region src/layers/CliLive.d.ts
+/**
+ * Composition layer for the CLI runtime.
+ *
+ * Wires `DataReader`, `ProjectDiscovery`, `HistoryTracker`,
+ * `OutputPipeline`, `SqliteClient`, the DB migrator, `NodeContext`,
+ * `NodeFileSystem`, and `Logger` into a single layer the `vitest-agent`
+ * bin provides to `Command.run`.
+ *
+ * @param dbPath - absolute path to the per-project `data.db`
+ * @param logLevel - optional log level override; defaults to `Info`
+ * @param logFile - optional path for structured log output
+ * @public
+ */
+declare const CliLive: (dbPath: string, logLevel?: LogLevel.LogLevel, logFile?: string) => Layer.Layer<import("@vitest-agent/sdk").DataStore | import("@vitest-agent/sdk").DataReader | import("@effect/sql/SqlClient").SqlClient | import("@effect/sql-sqlite-node/SqliteClient").SqliteClient | NodeContext.NodeContext | import("@vitest-agent/sdk").ProjectDiscovery | import("@vitest-agent/sdk").HistoryTracker | import("@vitest-agent/sdk").DetailResolver | import("@vitest-agent/sdk").EnvironmentDetector | import("@vitest-agent/sdk").ExecutorResolver | import("@vitest-agent/sdk").FormatSelector | import("@vitest-agent/sdk").OutputRenderer, import("effect/ConfigError").ConfigError | import("@effect/sql/SqlError").SqlError | SqliteMigrator.MigrationError, never>;
+//#endregion
+//#region src/layers/SidecarLive.d.ts
+/**
+ * SQLite database paths consumed by {@link SidecarLive}.
+ *
+ * @public
+ */
+interface SidecarPaths {
+  /** Absolute path to the per-project `data.db`. */
+  readonly perProjectDbPath: string;
+  /** Absolute path to the per-client `sessions.db`. */
+  readonly sessionMapDbPath: string;
+  /** Absolute path to the global `registry.db`. */
+  readonly registryDbPath: string;
+}
+/**
+ * Build the sidecar Live layer for the supplied SQLite paths.
+ *
+ * Each store gets its own `SqlClient` connection (separate scopes,
+ * independent migrators) so concurrent operations on the three
+ * stores don't share lock state.
+ *
+ * @param paths - the three SQLite database paths to open
+ * @public
+ */
+declare const SidecarLive: (paths: SidecarPaths) => Layer.Layer<import("@vitest-agent/sdk").DataStore | import("@vitest-agent/sdk").DataReader | import("@vitest-agent/sdk").PerClientSessionMapWriter | import("@vitest-agent/sdk").RunContext$ | NodeContext.NodeContext | import("@vitest-agent/sdk").PerClientSessionMapReader | import("@vitest-agent/sdk").DiscoveryRegistry, import("effect/ConfigError").ConfigError | import("@effect/sql/SqlError").SqlError | SqliteMigrator.MigrationError, never>;
+//#endregion
+//#region src/lib/internal-register-agent.d.ts
+/**
+ * Input for the end-to-end agent registration effect.
+ *
+ * @public
+ */
+interface RegisterAgentInput {
+  /** The host's native session identifier (e.g. Claude's `session_id`). */
+  readonly hostSessionId: string;
+  /** Absolute path to the host's conversation transcript file. */
+  readonly transcriptPath: string;
+  /** Working directory of the agent process. */
+  readonly cwd: string;
+  /** Host kind string (e.g. `"claude-code"`). */
+  readonly hostKind: string;
+  /** Agent type label (e.g. `"main"` or `"subagent"`). */
+  readonly agentType: string;
+  /** Normalized project key derived from the workspace root `package.json#name`. */
+  readonly projectKey: string;
+  /** Agent ID of the parent when registering a subagent. */
+  readonly parentAgentId?: string;
+  /** Optional idempotency nonce; derived from `hostSessionId + agentType + parentAgentId` when omitted. */
+  readonly clientNonce?: string;
+}
+/**
+ * Output of the end-to-end agent registration effect.
+ *
+ * @public
+ */
+interface RegisterAgentOutput {
+  /** Canonical UUID assigned to this agent in the per-project store. */
+  readonly agentId: string;
+  /** UUID of the conversation this agent belongs to. */
+  readonly conversationId: string;
+  /** Idempotency key used for the `registerAgent` upsert. */
+  readonly idempotencyKey: string;
+  /** `true` when an existing agent row was recovered rather than inserted. */
+  readonly idempotencyHit: boolean;
+}
+/**
+ * End-to-end agent registration.
+ *
+ * Returns the canonical `agentId` + the conversation it belongs to +
+ * the resolved `idempotencyKey`. The `idempotencyHit` flag is `true`
+ * when the per-project store recovered an existing agent row instead
+ * of inserting a new one.
+ *
+ * @param input - registration inputs including host identifiers and agent metadata
+ * @returns an Effect resolving to `RegisterAgentOutput`
+ * @public
+ */
+declare const registerAgentEffect: (input: RegisterAgentInput) => Effect.Effect<{
+  agentId: string;
+  conversationId: string;
+  mainAgentId: string;
+  idempotencyKey: string;
+  idempotencyHit: boolean;
+}, import("@vitest-agent/sdk").DataStoreError | import("@vitest-agent/sdk").RegistrationConflictError, DataStore | DataReader | PerClientSessionMapWriter | import("@vitest-agent/sdk").RunContext$>;
+//#endregion
+//#region src/lib/sidecar-paths.d.ts
+/**
+ * Filename of the per-project test-data SQLite database.
+ *
+ * @public
+ */
+declare const DATA_DB_FILENAME = "data.db";
+/**
+ * Filename of the per-client session-map SQLite database.
+ *
+ * @public
+ */
+declare const SESSIONS_DB_FILENAME = "sessions.db";
+/**
+ * Filename of the global discovery-registry SQLite database.
+ *
+ * @public
+ */
+declare const REGISTRY_DB_FILENAME = "registry.db";
+/**
+ * Resolve (and create) the per-project data directory for the supplied
+ * normalized `projectKey`. Returns the directory; callers join
+ * {@link DATA_DB_FILENAME} onto it for the `data.db` path.
+ *
+ * @param projectKey - normalized project key (e.g. `@org__pkg`)
+ * @returns absolute path to the resolved (and created) data directory
+ * @public
+ */
+declare const resolveProjectDataDir: (projectKey: string) => string;
+/**
+ * Resolve (and create) the directory holding the global `registry.db`.
+ * Callers join {@link REGISTRY_DB_FILENAME} onto it.
+ *
+ * @returns absolute path to the resolved (and created) registry directory
+ * @public
+ */
+declare const resolveRegistryDir: () => string;
+/**
+ * Resolve the per-client `sessions.db` path.
+ *
+ * Precedence: the `CLAUDE_PLUGIN_DATA` env var, then
+ * `VITEST_AGENT_SESSION_MAP_DIR`, then `~/.vitest-agent/`. Fails
+ * with `ProjectIdentityNotResolvableError` when no home directory
+ * is resolvable.
+ *
+ * @returns an Effect resolving to the absolute `sessions.db` path
+ * @public
+ */
+declare const resolveSessionMapPath: () => Effect.Effect<string, ProjectIdentityNotResolvableError>;
+//#endregion
+//#region src/index.d.ts
+/**
+ * The version of this package, inlined at build time from
+ * `package.json#version` via rslib-builder's `__PACKAGE_VERSION__` substitution.
+ * Compared against `CURRENT_SDK_VERSION` at CLI bin init to surface
+ * partially-upgraded installs as a single stderr warning.
+ *
+ * @public
+ */
+declare const CURRENT_CLI_VERSION: string;
+//#endregion
+export { CURRENT_CLI_VERSION, CliLive, DATA_DB_FILENAME, REGISTRY_DB_FILENAME, type RegisterAgentInput, type RegisterAgentOutput, SESSIONS_DB_FILENAME, SidecarLive, type SidecarPaths, registerAgentEffect, resolveProjectDataDir, resolveRegistryDir, resolveSessionMapPath };
+//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -0,0 +1,18 @@
+import { CliLive } from "./layers/CliLive.js";
+import { SidecarLive } from "./layers/SidecarLive.js";
+import { registerAgentEffect } from "./lib/internal-register-agent.js";
+import { DATA_DB_FILENAME, REGISTRY_DB_FILENAME, SESSIONS_DB_FILENAME, resolveProjectDataDir, resolveRegistryDir, resolveSessionMapPath } from "./lib/sidecar-paths.js";
+
+//#region src/index.ts
+/**
+* The version of this package, inlined at build time from
+* `package.json#version` via rslib-builder's `__PACKAGE_VERSION__` substitution.
+* Compared against `CURRENT_SDK_VERSION` at CLI bin init to surface
+* partially-upgraded installs as a single stderr warning.
+*
+* @public
+*/
+const CURRENT_CLI_VERSION = "1.0.0";
+
+//#endregion
+export { CURRENT_CLI_VERSION, CliLive, DATA_DB_FILENAME, REGISTRY_DB_FILENAME, SESSIONS_DB_FILENAME, SidecarLive, registerAgentEffect, resolveProjectDataDir, resolveRegistryDir, resolveSessionMapPath };

package/layers/CliLive.js

@@ -0,0 +1,30 @@
+import { NodeFileSystem } from "@effect/platform-node";
+import * as NodeContext$1 from "@effect/platform-node/NodeContext";
+import { layer } from "@effect/sql-sqlite-node/SqliteClient";
+import * as SqliteMigrator from "@effect/sql-sqlite-node/SqliteMigrator";
+import { DataReaderLive, DataStoreLive, HistoryTrackerLive, LoggerLive, OutputPipelineLive, ProjectDiscoveryLive, migration0001 } from "@vitest-agent/sdk";
+import { Layer } from "effect";
+
+//#region src/layers/CliLive.ts
+/**
+* Composition layer for the CLI runtime.
+*
+* Wires `DataReader`, `ProjectDiscovery`, `HistoryTracker`,
+* `OutputPipeline`, `SqliteClient`, the DB migrator, `NodeContext`,
+* `NodeFileSystem`, and `Logger` into a single layer the `vitest-agent`
+* bin provides to `Command.run`.
+*
+* @param dbPath - absolute path to the per-project `data.db`
+* @param logLevel - optional log level override; defaults to `Info`
+* @param logFile - optional path for structured log output
+* @public
+*/
+const CliLive = (dbPath, logLevel, logFile) => {
+	const SqliteLayer = layer({ filename: dbPath });
+	const PlatformLayer = NodeContext$1.layer;
+	const MigratorLayer = SqliteMigrator.layer({ loader: SqliteMigrator.fromRecord({ "0001_initial": migration0001 }) }).pipe(Layer.provide(Layer.merge(SqliteLayer, PlatformLayer)));
+	return Layer.mergeAll(ProjectDiscoveryLive, HistoryTrackerLive, OutputPipelineLive).pipe(Layer.provideMerge(DataReaderLive), Layer.provideMerge(DataStoreLive), Layer.provideMerge(MigratorLayer), Layer.provideMerge(SqliteLayer), Layer.provideMerge(PlatformLayer), Layer.provideMerge(NodeFileSystem.layer), Layer.provideMerge(LoggerLive(logLevel, logFile)));
+};
+
+//#endregion
+export { CliLive };

package/layers/SidecarLive.js

@@ -0,0 +1,34 @@
+import { NodeFileSystem } from "@effect/platform-node";
+import * as NodeContext$1 from "@effect/platform-node/NodeContext";
+import { layer } from "@effect/sql-sqlite-node/SqliteClient";
+import * as SqliteMigrator from "@effect/sql-sqlite-node/SqliteMigrator";
+import { DataReaderLive, DataStoreLive, DiscoveryRegistryLive, LoggerLive, PerClientSessionMapWriterLive, RunContextLive, migration0001, registryMigration0001, sessionMapMigration0001 } from "@vitest-agent/sdk";
+import { Layer } from "effect";
+
+//#region src/layers/SidecarLive.ts
+/**
+* Build the sidecar Live layer for the supplied SQLite paths.
+*
+* Each store gets its own `SqlClient` connection (separate scopes,
+* independent migrators) so concurrent operations on the three
+* stores don't share lock state.
+*
+* @param paths - the three SQLite database paths to open
+* @public
+*/
+const SidecarLive = (paths) => {
+	const PlatformLayer = NodeContext$1.layer;
+	const ProjectSqliteLayer = layer({ filename: paths.perProjectDbPath });
+	const ProjectMigratorLayer = SqliteMigrator.layer({ loader: SqliteMigrator.fromRecord({ "0001_initial": migration0001 }) }).pipe(Layer.provide(Layer.merge(ProjectSqliteLayer, PlatformLayer)));
+	const ProjectStoreLayer = Layer.mergeAll(DataStoreLive.pipe(Layer.provide(ProjectSqliteLayer)), DataReaderLive.pipe(Layer.provide(ProjectSqliteLayer)), ProjectMigratorLayer);
+	const SessionMapSqliteLayer = layer({ filename: paths.sessionMapDbPath });
+	const SessionMapMigratorLayer = SqliteMigrator.layer({ loader: SqliteMigrator.fromRecord({ "0001_initial": sessionMapMigration0001 }) }).pipe(Layer.provide(Layer.merge(SessionMapSqliteLayer, PlatformLayer)));
+	const SessionMapLayer = Layer.mergeAll(PerClientSessionMapWriterLive.pipe(Layer.provide(SessionMapSqliteLayer)), SessionMapMigratorLayer);
+	const RegistrySqliteLayer = layer({ filename: paths.registryDbPath });
+	const RegistryMigratorLayer = SqliteMigrator.layer({ loader: SqliteMigrator.fromRecord({ "0001_initial": registryMigration0001 }) }).pipe(Layer.provide(Layer.merge(RegistrySqliteLayer, PlatformLayer)));
+	const RegistryLayer = Layer.mergeAll(DiscoveryRegistryLive.pipe(Layer.provide(RegistrySqliteLayer)), RegistryMigratorLayer);
+	return Layer.mergeAll(ProjectStoreLayer, SessionMapLayer, RegistryLayer, RunContextLive).pipe(Layer.provideMerge(PlatformLayer), Layer.provideMerge(NodeFileSystem.layer), Layer.provideMerge(LoggerLive()));
+};
+
+//#endregion
+export { SidecarLive };

package/lib/format-db-query.js

@@ -0,0 +1,26 @@
+//#region src/lib/format-db-query.ts
+const renderCell = (value) => {
+	if (value === null || value === void 0) return "NULL";
+	if (typeof value === "object") return JSON.stringify(value);
+	return String(value);
+};
+/**
+* Render query rows as whitespace-padded tabular text or a JSON array.
+*
+* Table format: column headers in the first line, one row per line,
+* each cell padded to its column's widest value. An empty result set
+* renders as `(0 rows)`. JSON format emits a single array of row
+* objects keyed by column name; an empty result set is `[]`.
+*/
+const formatDbQuery = (rows, format) => {
+	if (format === "json") return JSON.stringify(rows);
+	if (rows.length === 0) return "(0 rows)";
+	const columns = Object.keys(rows[0]);
+	const cells = rows.map((row) => columns.map((col) => renderCell(row[col])));
+	const widths = columns.map((col, i) => Math.max(col.length, ...cells.map((row) => row[i].length)));
+	const renderLine = (values) => values.map((value, i) => value.padEnd(widths[i])).join("  ").trimEnd();
+	return [renderLine(columns), ...cells.map(renderLine)].join("\n");
+};
+
+//#endregion
+export { formatDbQuery };

package/lib/format-doctor.js

@@ -0,0 +1,14 @@
+//#region src/lib/format-doctor.ts
+function formatDoctor(results) {
+	const lines = [];
+	lines.push("## Doctor\n");
+	for (const result of results) {
+		const icon = result.passed ? "[x]" : "[ ]";
+		lines.push(`- ${icon} ${result.name}: ${result.detail}`);
+	}
+	if (results.some((r) => !r.passed)) lines.push("\nSuggestion: Run `vitest-agent db reset` then re-run tests.");
+	return lines.join("\n");
+}
+
+//#endregion
+export { formatDoctor };

package/lib/internal-end-agent.js

@@ -0,0 +1,27 @@
+import { DataStore, PerClientSessionMapWriter } from "@vitest-agent/sdk";
+import { Effect } from "effect";
+
+//#region src/lib/internal-end-agent.ts
+/**
+* Sidecar `_internal end-agent` implementation.
+*
+* Sets `agents.ended_at` on the per-project store. For main-agent
+* stops (SessionEnd), the caller also passes `--host-session-id` so
+* the per-client session map's `ended_at` is updated and
+* `lookupByProjectDir` no longer returns the row as the active
+* session. For subagent stops (SubagentStop), the host session stays
+* open — only the subagent's `agents` row is closed.
+*
+* @packageDocumentation
+*/
+/**
+* End an agent. Closes the `agents` row, optionally also closes the
+* `session_map` row.
+*/
+const endAgentEffect = (input) => Effect.gen(function* () {
+	yield* (yield* DataStore).endAgent(input.agentId, input.endedAt);
+	if (input.hostSessionId !== void 0) yield* (yield* PerClientSessionMapWriter).endSession(input.hostSessionId, input.endedAt);
+});
+
+//#endregion
+export { endAgentEffect };