@blogic-cz/agent-tools 0.4.1 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # @blogic-cz/agent-tools
 
-Safe CLI wrappers for AI coding agents. 6 tools for GitHub, databases, Kubernetes, Azure DevOps, logs, and OpenCode sessions — with JSON5 config and a credential guard that blocks agents from touching secrets.
+Safe CLI wrappers for AI coding agents. 7 tools for GitHub, databases, Kubernetes, Azure DevOps, logs, OpenCode sessions, and audit history — with JSON5 config and a credential guard that blocks agents from touching secrets.
 
 ## Why
 
@@ -47,7 +47,7 @@ Follow these steps to set up agent-tools in the consumer project.
 
 **Step 2 — Configure**
 
-Ask the user which tools they need (gh, db, k8s, az, logs, session). Create `agent-tools.json5` in the project root with **only the selected tools configured**. See [`examples/agent-tools.json5`](./examples/agent-tools.json5) for the full config reference with all options documented.
+Ask the user which tools they need (gh, db, k8s, az, logs, session, audit). Create `agent-tools.json5` in the project root with **only the selected tools configured**. See [`examples/agent-tools.json5`](./examples/agent-tools.json5) for the full config reference with all options documented.
 
 Minimal starting config:
 
@@ -124,6 +124,10 @@ bun run agent-tools/example-tool/index.ts ping
 {
   $schema: "https://raw.githubusercontent.com/blogic-cz/agent-tools/main/schemas/agent-tools.schema.json",
   defaultEnvironment: "test", // optional: any string (e.g. "local", "test", "prod")
+  audit: {
+    retentionDays: 90,
+    dbPath: "~/.agent-tools/audit.sqlite",
+  },
   kubernetes: {
     default: {
       clusterId: "your-cluster-id",
@@ -145,6 +149,7 @@ bun run agent-tools/example-tool/index.ts ping
 bunx agent-tools-gh pr status
 bunx agent-tools-k8s kubectl --env test --cmd "get pods"
 bunx agent-tools-logs list --env local
+bunx agent-tools-audit list --limit 20
 ```
 
 ```bash
@@ -158,6 +163,7 @@ Optionally, add script aliases to your `package.json` for shorter invocation:
 {
   "scripts": {
     "gh-tool": "agent-tools-gh",
+    "audit-tool": "agent-tools-audit",
     "k8s-tool": "agent-tools-k8s",
     "db-tool": "agent-tools-db",
     "logs-tool": "agent-tools-logs",
@@ -181,6 +187,7 @@ export default { handleToolExecuteBefore };
 | Binary                | Description                                                                                                      |
 | --------------------- | ---------------------------------------------------------------------------------------------------------------- |
 | `agent-tools-gh`      | GitHub CLI wrapper — PR management, issues, workflows, composite commands (`review-triage`, `reply-and-resolve`) |
+| `agent-tools-audit`   | Audit trail browser — inspect recent tool invocations and purge old entries                                      |
 | `agent-tools-db`      | Database query tool — SQL execution, schema introspection                                                        |
 | `agent-tools-k8s`     | Kubernetes tool — kubectl wrapper + structured commands (`pods`, `logs`, `describe`, `exec`, `top`)              |
 | `agent-tools-az`      | Azure DevOps tool — pipelines, builds, repos                                                                     |
@@ -189,6 +196,65 @@ export default { handleToolExecuteBefore };
 
 All tools support `--help` for full usage documentation.
 
+`agent-tools-audit` reads the same SQLite file the wrappers write to. By default that file lives at `~/.agent-tools/audit.sqlite`, and you can override both path and retention per repo with the global `audit` config section.
+
+## Audit Logging
+
+Every tool invocation is automatically recorded to a local SQLite database — zero configuration required. The audit trail captures which tool ran, what arguments it received, how long it took, whether it succeeded, and which project directory it was called from.
+
+### How it works
+
+Each CLI wrapper (`gh`, `k8s`, `db`, `az`, `logs`, `session`, `audit`) writes a row to `~/.agent-tools/audit.sqlite` on every execution. Logging is fire-and-forget — if the database is unavailable or write fails, the tool continues normally. Audit never blocks or slows down your workflow.
+
+Entries older than `retentionDays` (default: 90) are automatically purged on each write.
+
+### Browsing the audit trail
+
+```bash
+# Recent 20 entries (default)
+bunx agent-tools-audit list
+
+# Last 50 entries, JSON format
+bunx agent-tools-audit list --limit 50 --format json
+
+# Filter by tool
+bunx agent-tools-audit list --tool gh
+
+# Filter by project directory
+bunx agent-tools-audit list --project /Users/me/my-repo
+
+# Purge entries older than 30 days
+bunx agent-tools-audit purge --days 30
+```
+
+### Audit Configuration
+
+Both the database path and retention period are configurable in `agent-tools.json5`:
+
+```json5
+{
+  audit: {
+    retentionDays: 90, // days before auto-purge (default: 90)
+    dbPath: "~/.agent-tools/audit.sqlite", // database file location
+  },
+}
+```
+
+All settings are optional — audit works out of the box with sensible defaults.
+
+### What gets recorded
+
+| Column      | Description                                            |
+| ----------- | ------------------------------------------------------ |
+| `ts`        | ISO 8601 timestamp                                     |
+| `tool`      | Tool name (`gh`, `k8s`, `db`, `az`, `logs`, `session`) |
+| `project`   | Working directory (`process.cwd()`)                    |
+| `args`      | Command-line arguments (JSON array)                    |
+| `duration`  | Execution time in milliseconds                         |
+| `success`   | `1` (success) or `0` (failure)                         |
+| `error`     | Error message if failed, `null` otherwise              |
+| `exit_code` | Process exit code                                      |
+
 ## Configuration
 
 Config is loaded from `agent-tools.json5` (or `agent-tools.json`) by walking up from the current working directory. Missing config = zero-config mode (works for `gh-tool`; others require config).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@blogic-cz/agent-tools",
-  "version": "0.4.1",
-  "description": "CLI tools for AI coding agent workflows — GitHub, database, Kubernetes, Azure DevOps, logs, and sessions",
+  "version": "0.5.0",
+  "description": "CLI tools for AI coding agent workflows — GitHub, database, Kubernetes, Azure DevOps, logs, sessions, and audit",
   "keywords": [
     "agent",
     "ai",
@@ -19,6 +19,7 @@
     "url": "https://github.com/blogic-cz/agent-tools.git"
   },
   "bin": {
+    "agent-tools-audit": "./src/audit-tool/index.ts",
     "agent-tools-az": "./src/az-tool/index.ts",
     "agent-tools-db": "./src/db-tool/index.ts",
     "agent-tools-gh": "./src/gh-tool/index.ts",

package/schemas/agent-tools.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://raw.githubusercontent.com/blogic-cz/agent-tools/main/schemas/agent-tools.schema.json",
   "title": "Agent Tools Configuration",
-  "description": "Root configuration for the agent-tools package. Tool-specific sections (azure, kubernetes, database, logs) are maps of named profiles keyed by profile name. Tools choose a profile via --profile <name> (default key is 'default', single-entry maps can be auto-selected). session and credentialGuard are global sections.",
+  "description": "Root configuration for the agent-tools package. Tool-specific sections (azure, kubernetes, database, logs) are maps of named profiles keyed by profile name. Tools choose a profile via --profile <name> (default key is 'default', single-entry maps can be auto-selected). session, audit, and credentialGuard are global sections.",
   "type": "object",
   "additionalProperties": false,
   "properties": {
@@ -46,6 +46,10 @@
       "description": "Global session configuration shared across profiles.",
       "$ref": "#/definitions/SessionConfig"
     },
+    "audit": {
+      "description": "Global audit logging configuration shared across profiles.",
+      "$ref": "#/definitions/AuditConfig"
+    },
     "credentialGuard": {
       "description": "Global credential guard configuration merged with built-in defaults.",
       "$ref": "#/definitions/CredentialGuardConfig"
@@ -199,6 +203,21 @@
       },
       "required": ["storagePath"]
     },
+    "AuditConfig": {
+      "description": "Global audit configuration.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "retentionDays": {
+          "description": "How many days of audit history to keep before purge on open.",
+          "type": "number"
+        },
+        "dbPath": {
+          "description": "Filesystem path for the audit SQLite database.",
+          "type": "string"
+        }
+      }
+    },
     "CliToolOverride": {
       "description": "CLI override entry that blocks a tool and recommends a safer wrapper.",
       "type": "object",
@@ -311,6 +330,10 @@
       "session": {
         "storagePath": "~/.local/share/opencode/storage"
       },
+      "audit": {
+        "retentionDays": 90,
+        "dbPath": "~/.agent-tools/audit.sqlite"
+      },
       "credentialGuard": {
         "additionalBlockedPaths": ["private/"],
         "additionalAllowedPaths": ["apps/web-app/.env.test"],

package/src/audit-tool/index.ts

@@ -0,0 +1,102 @@
+#!/usr/bin/env bun
+import { Command, Flag } from "effect/unstable/cli";
+import { BunRuntime, BunServices } from "@effect/platform-bun";
+import { Console, Effect, Layer, Option } from "effect";
+
+import { formatOption, formatOutput, renderCauseToStderr, VERSION } from "#shared";
+import { AuditService, AuditServiceLayer, withAudit } from "#shared/audit";
+
+type AuditToolResult<T> = {
+  success: boolean;
+  executionTimeMs: number;
+  data?: T;
+  error?: string;
+};
+
+const commonFlags = {
+  format: formatOption,
+};
+
+const listCommand = Command.make(
+  "list",
+  {
+    ...commonFlags,
+    limit: Flag.integer("limit").pipe(
+      Flag.withDescription("Maximum number of recent audit entries to return"),
+      Flag.withDefault(20),
+    ),
+    project: Flag.optional(Flag.string("project")).pipe(
+      Flag.withDescription("Filter entries by exact working directory path"),
+    ),
+    tool: Flag.optional(Flag.string("tool")).pipe(
+      Flag.withDescription("Filter entries by tool name (gh, k8s, db, az, logs, session, audit)"),
+    ),
+  },
+  ({ format, limit, project, tool }) =>
+    Effect.gen(function* () {
+      const startTime = Date.now();
+      const audit = yield* AuditService;
+      const entries = yield* audit.listRecent(limit);
+      const toolFilteredEntries = Option.match(tool, {
+        onNone: () => entries,
+        onSome: (value) => entries.filter((entry) => entry.tool === value),
+      });
+      const filteredEntries = Option.match(project, {
+        onNone: () => toolFilteredEntries,
+        onSome: (value) => toolFilteredEntries.filter((entry) => entry.project === value),
+      });
+
+      const result: AuditToolResult<typeof filteredEntries> = {
+        success: true,
+        executionTimeMs: Date.now() - startTime,
+        data: filteredEntries,
+      };
+
+      yield* Console.log(formatOutput(result, format));
+    }),
+).pipe(Command.withDescription("List recent audit log entries"));
+
+const purgeCommand = Command.make(
+  "purge",
+  {
+    ...commonFlags,
+    days: Flag.integer("days").pipe(
+      Flag.withDescription("Delete audit entries older than this many days"),
+      Flag.withDefault(90),
+    ),
+  },
+  ({ days, format }) =>
+    Effect.gen(function* () {
+      const startTime = Date.now();
+      const audit = yield* AuditService;
+      const deleted = yield* audit.purgeOlderThanDays(days);
+
+      const result: AuditToolResult<{ deleted: number; days: number }> = {
+        success: true,
+        executionTimeMs: Date.now() - startTime,
+        data: { deleted, days },
+      };
+
+      yield* Console.log(formatOutput(result, format));
+    }),
+).pipe(Command.withDescription("Delete old audit log entries"));
+
+const mainCommand = Command.make("audit-tool", {}).pipe(
+  Command.withDescription("Audit log inspection and maintenance for agent-tools"),
+  Command.withSubcommands([listCommand, purgeCommand]),
+);
+
+const cli = Command.run(mainCommand, {
+  version: VERSION,
+});
+
+const MainLayer = AuditServiceLayer.pipe(Layer.provideMerge(BunServices.layer));
+
+const program = withAudit("audit", cli).pipe(
+  Effect.provide(MainLayer),
+  Effect.tapCause(renderCauseToStderr),
+);
+
+BunRuntime.runMain(program, {
+  disableErrorReporting: true,
+});

package/src/az-tool/index.ts

@@ -4,6 +4,7 @@ import { BunRuntime, BunServices } from "@effect/platform-bun";
 import { Console, Effect, Layer, Option } from "effect";
 
 import { formatAny, formatOption, formatOutput, renderCauseToStderr, VERSION } from "#shared";
+import { AuditServiceLayer, withAudit } from "#shared/audit";
 import {
   findFailedJobs,
   getBuildJobSummary,
@@ -196,9 +197,13 @@ const cli = Command.run(mainCommand, {
 const MainLayer = AzServiceLayer.pipe(
   Layer.provideMerge(ConfigServiceLayer),
   Layer.provideMerge(BunServices.layer),
+  Layer.provideMerge(AuditServiceLayer),
 );
 
-const program = cli.pipe(Effect.provide(MainLayer), Effect.tapCause(renderCauseToStderr));
+const program = withAudit("az", cli).pipe(
+  Effect.provide(MainLayer),
+  Effect.tapCause(renderCauseToStderr),
+);
 
 BunRuntime.runMain(program, {
   disableErrorReporting: true,

package/src/config/index.ts

@@ -5,6 +5,7 @@ export type {
   DbEnvConfig,
   DatabaseConfig,
   LogsConfig,
+  AuditConfig,
   CliToolOverride,
   CredentialGuardConfig,
 } from "./types.ts";

package/src/config/loader.ts

@@ -54,6 +54,11 @@ const LogsConfigSchema = Schema.Struct({
   remotePath: Schema.String,
 });
 
+const AuditConfigSchema = Schema.Struct({
+  retentionDays: Schema.optionalKey(Schema.Number),
+  dbPath: Schema.optionalKey(Schema.String),
+});
+
 const AgentToolsConfigSchema = Schema.Struct({
   $schema: Schema.optionalKey(Schema.String),
   azure: Schema.optionalKey(Schema.Record(Schema.String, AzureConfigSchema)),
@@ -65,6 +70,7 @@ const AgentToolsConfigSchema = Schema.Struct({
       storagePath: Schema.String,
     }),
   ),
+  audit: Schema.optionalKey(AuditConfigSchema),
   credentialGuard: Schema.optionalKey(CredentialGuardConfigSchema),
   defaultEnvironment: Schema.optionalKey(Schema.String),
 });

package/src/config/types.ts

@@ -56,6 +56,11 @@ export type CredentialGuardConfig = {
   additionalDangerousBashPatterns?: string[];
 };
 
+export type AuditConfig = {
+  retentionDays?: number;
+  dbPath?: string;
+};
+
 /**
  * Root agent-tools configuration.
  *
@@ -63,7 +68,7 @@ export type CredentialGuardConfig = {
  * of named profiles. Tools select a profile via the --profile <name> flag (default = "default" key).
  * If only one profile exists, it is used automatically.
  *
- * session and credentialGuard are global - not per-profile.
+ * session, credentialGuard, and audit are global - not per-profile.
  */
 export type AgentToolsConfig = {
   $schema?: string;
@@ -79,6 +84,7 @@ export type AgentToolsConfig = {
   session?: {
     storagePath: string;
   };
+  audit?: AuditConfig;
   /** Global credential guard config (merged with built-in defaults, not per-profile) */
   credentialGuard?: CredentialGuardConfig;
   /** Optional default environment name (local|test|prod) used by tools when no --env flag is provided */

package/src/db-tool/index.ts

@@ -6,6 +6,7 @@ import { Console, Effect, Layer, Option } from "effect";
 import type { SchemaMode } from "./types";
 
 import { formatOption, formatOutput, renderCauseToStderr, VERSION } from "#shared";
+import { AuditServiceLayer, withAudit } from "#shared/audit";
 import { ConfigService, ConfigServiceLayer, getDefaultEnvironment } from "#config";
 import { makeDbConfigLayer } from "./config-service";
 import { DbConnectionError } from "./errors";
@@ -121,9 +122,13 @@ const MainLayer = DbService.layer.pipe(
   Layer.provide(dbConfigLayer),
   Layer.provideMerge(ConfigServiceLayer),
   Layer.provideMerge(BunServices.layer),
+  Layer.provideMerge(AuditServiceLayer),
 );
 
-const program = cli.pipe(Effect.provide(MainLayer), Effect.tapCause(renderCauseToStderr));
+const program = withAudit("db", cli).pipe(
+  Effect.provide(MainLayer),
+  Effect.tapCause(renderCauseToStderr),
+);
 
 BunRuntime.runMain(program, {
   disableErrorReporting: true,

package/src/db-tool/service.ts

@@ -17,6 +17,21 @@ import { detectSchemaError, isValidTableName, isMutationQuery } from "./security
 
 const LOCALHOST_HOSTS = new Set(["localhost", "127.0.0.1"]);
 
+export function resolveDbAccessMode(
+  env: string,
+  host: string,
+  hasKubectlConfig: boolean,
+): Pick<DbConfig, "allowMutations" | "host" | "needsTunnel"> {
+  const isLocalHost = LOCALHOST_HOSTS.has(host);
+  const isLocalEnvironment = env === "local";
+
+  return {
+    host,
+    needsTunnel: hasKubectlConfig && !isLocalEnvironment && isLocalHost,
+    allowMutations: isLocalEnvironment,
+  };
+}
+
 export class DbService extends ServiceMap.Service<
   DbService,
   {
@@ -506,19 +521,21 @@ export class DbService extends ServiceMap.Service<
             throw new Error(`Unknown environment "${env}". Available: ${available}`);
           }
 
-          const isLocal = LOCALHOST_HOSTS.has(envConfig.host);
-          const isLocalEnvironment = env === "local";
-          const needsTunnel = dbConfig.kubectl !== undefined && !isLocalEnvironment && isLocal;
+          const accessMode = resolveDbAccessMode(
+            env,
+            envConfig.host,
+            dbConfig.kubectl !== undefined,
+          );
 
           return {
-            host: envConfig.host,
+            host: accessMode.host,
             user: envConfig.user,
             database: envConfig.database,
             password: envConfig.password,
             passwordEnvVar: envConfig.passwordEnvVar,
             port: envConfig.port,
-            needsTunnel,
-            allowMutations: isLocalEnvironment,
+            needsTunnel: accessMode.needsTunnel,
+            allowMutations: accessMode.allowMutations,
           };
         };
 

package/src/gh-tool/index.ts

@@ -4,6 +4,7 @@ import { BunRuntime, BunServices } from "@effect/platform-bun";
 import { Effect, Layer } from "effect";
 
 import { renderCauseToStderr, VERSION } from "#shared";
+import { AuditServiceLayer, withAudit } from "#shared/audit";
 import {
   issueCloseCommand,
   issueCommentCommand,
@@ -162,9 +163,15 @@ const cli = Command.run(mainCommand, {
   version: VERSION,
 });
 
-const MainLayer = GitHubService.layer.pipe(Layer.provideMerge(BunServices.layer));
+const MainLayer = GitHubService.layer.pipe(
+  Layer.provideMerge(BunServices.layer),
+  Layer.provideMerge(AuditServiceLayer),
+);
 
-const program = cli.pipe(Effect.provide(MainLayer), Effect.tapCause(renderCauseToStderr));
+const program = withAudit("gh", cli).pipe(
+  Effect.provide(MainLayer),
+  Effect.tapCause(renderCauseToStderr),
+);
 
 BunRuntime.runMain(program, {
   disableErrorReporting: true,

package/src/k8s-tool/index.ts

@@ -6,6 +6,7 @@ import { Console, Effect, Layer, Option } from "effect";
 import type { CommandResult } from "./types";
 
 import { formatOption, formatOutput, renderCauseToStderr, VERSION } from "#shared";
+import { AuditServiceLayer, withAudit } from "#shared/audit";
 import { K8sService, K8sServiceLayer } from "./service";
 import { ConfigService, ConfigServiceLayer, getDefaultEnvironment, getToolConfig } from "#config";
 import type { K8sConfig } from "#config";
@@ -401,9 +402,13 @@ const cli = Command.run(mainCommand, {
 const MainLayer = K8sServiceLayer.pipe(
   Layer.provideMerge(ConfigServiceLayer),
   Layer.provideMerge(BunServices.layer),
+  Layer.provideMerge(AuditServiceLayer),
 );
 
-const program = cli.pipe(Effect.provide(MainLayer), Effect.tapCause(renderCauseToStderr));
+const program = withAudit("k8s", cli).pipe(
+  Effect.provide(MainLayer),
+  Effect.tapCause(renderCauseToStderr),
+);
 
 BunRuntime.runMain(program, {
   disableErrorReporting: true,

package/src/logs-tool/index.ts

@@ -21,6 +21,7 @@ import { Console, Effect, Layer, Option, Result } from "effect";
 import type { Environment, LogResult, ReadOptions } from "./types";
 
 import { formatOption, formatOutput, renderCauseToStderr, VERSION } from "#shared";
+import { AuditServiceLayer, withAudit } from "#shared/audit";
 import { ConfigService, ConfigServiceLayer, getDefaultEnvironment } from "#config";
 import { LogsConfigError, LogsNotFoundError, LogsReadError, LogsTimeoutError } from "./errors";
 import { LogsService, LogsServiceLayer } from "./service";
@@ -229,9 +230,13 @@ export const run = Command.runWith(mainCommand, {
 const MainLayer = LogsServiceLayer.pipe(
   Layer.provideMerge(ConfigServiceLayer),
   Layer.provideMerge(BunServices.layer),
+  Layer.provideMerge(AuditServiceLayer),
 );
 
-const program = cli.pipe(Effect.provide(MainLayer), Effect.tapCause(renderCauseToStderr));
+const program = withAudit("logs", cli).pipe(
+  Effect.provide(MainLayer),
+  Effect.tapCause(renderCauseToStderr),
+);
 
 BunRuntime.runMain(program, {
   disableErrorReporting: true,

package/src/session-tool/index.ts

@@ -14,6 +14,7 @@ import { Console, Effect, Layer, Result } from "effect";
 import type { MessageSummary, SessionResult } from "./types";
 
 import { formatOption, formatOutput, VERSION } from "#shared";
+import { AuditServiceLayer, withAudit } from "#shared/audit";
 import { ResolvedPaths, ResolvedPathsLayer } from "./config";
 import { SessionStorageNotFoundError } from "./errors";
 import { formatDate, SessionService, SessionServiceLayer, truncate } from "./service";
@@ -261,9 +262,12 @@ export const run = Command.runWith(mainCommand, {
   version: VERSION,
 });
 
-const MainLayer = AppLayer.pipe(Layer.provideMerge(BunServices.layer));
+const MainLayer = AppLayer.pipe(
+  Layer.provideMerge(BunServices.layer),
+  Layer.provideMerge(AuditServiceLayer),
+);
 
-const program = cli.pipe(Effect.provide(MainLayer));
+const program = withAudit("session", cli).pipe(Effect.provide(MainLayer));
 
 BunRuntime.runMain(program, {
   disableErrorReporting: true,

package/src/shared/audit.ts

@@ -0,0 +1,324 @@
+import { Database, constants } from "bun:sqlite";
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+
+import { Cause, Effect, Layer, ServiceMap } from "effect";
+
+import { loadConfig } from "#config";
+
+const DEFAULT_AUDIT_RETENTION_DAYS = 90;
+const IN_MEMORY_DB_PATH = ":memory:";
+
+export type AuditLogEntry = {
+  id: number;
+  ts: string;
+  tool: string;
+  project: string;
+  args: string;
+  duration: number;
+  success: boolean;
+  error: string | null;
+  exitCode: number | null;
+};
+
+export type AuditRecord = {
+  tool: string;
+  project: string;
+  args: string;
+  duration: number;
+  success: boolean;
+  error?: string;
+  exitCode?: number | null;
+};
+
+type AuditServiceShape = {
+  readonly dbPath: string;
+  readonly record: (entry: AuditRecord) => Effect.Effect<void, never, never>;
+  readonly listRecent: (limit?: number) => Effect.Effect<readonly AuditLogEntry[], never, never>;
+  readonly purgeOlderThanDays: (days: number) => Effect.Effect<number, never, never>;
+};
+
+type AuditServiceOptions = {
+  readonly dbPath?: string;
+  readonly retentionDays?: number;
+};
+
+type ResolvedAuditOptions = {
+  dbPath: string;
+  retentionDays: number;
+};
+
+type AuditRow = {
+  id: number;
+  ts: string;
+  tool: string;
+  project: string;
+  args: string;
+  duration: number;
+  success: number;
+  error: string | null;
+  exit_code: number | null;
+};
+
+type TableInfoRow = {
+  name: string;
+};
+
+export class AuditService extends ServiceMap.Service<AuditService, AuditServiceShape>()(
+  "@agent-tools/AuditService",
+) {}
+
+export const resolveAuditDbPath = (): string => join(homedir(), ".agent-tools", "audit.sqlite");
+
+const expandHomePath = (path: string): string =>
+  path === "~" || path.startsWith("~/") ? join(homedir(), path.slice(2)) : path;
+
+const isInMemoryDatabase = (dbPath: string): boolean =>
+  dbPath === "" || dbPath === IN_MEMORY_DB_PATH;
+
+const toAuditEntry = (row: AuditRow): AuditLogEntry => ({
+  id: row.id,
+  ts: row.ts,
+  tool: row.tool,
+  project: row.project,
+  args: row.args,
+  duration: row.duration,
+  success: row.success === 1,
+  error: row.error,
+  exitCode: row.exit_code,
+});
+
+const safeToolName = (tool: string): string => tool.trim() || "unknown";
+
+const deriveToolNameFromArgv = (): string => {
+  const executablePath = process.argv[1];
+  if (!executablePath) {
+    return "unknown";
+  }
+
+  const fileName = basename(executablePath, ".ts");
+  return fileName.replace(/^agent-tools-/, "").replace(/-tool$/, "");
+};
+
+const formatUnknownError = (error: unknown): string => {
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  if (typeof error === "object" && error !== null) {
+    const message = Reflect.get(error, "message");
+    if (typeof message === "string") {
+      return message;
+    }
+  }
+
+  return String(error);
+};
+
+const formatCause = (cause: Cause.Cause<unknown>): string => {
+  const firstFailure = cause.reasons.find(Cause.isFailReason);
+  if (firstFailure !== undefined) {
+    return formatUnknownError(firstFailure.error);
+  }
+
+  const firstDefect = cause.reasons.find(Cause.isDieReason);
+  if (firstDefect !== undefined) {
+    return formatUnknownError(firstDefect.defect);
+  }
+
+  if (Cause.hasInterruptsOnly(cause)) {
+    return "Interrupted";
+  }
+
+  return "Unknown error";
+};
+
+const extractExitCode = (cause: Cause.Cause<unknown>): number | null => {
+  const firstFailure = cause.reasons.find(Cause.isFailReason);
+  if (
+    firstFailure === undefined ||
+    typeof firstFailure.error !== "object" ||
+    firstFailure.error === null
+  ) {
+    return null;
+  }
+
+  const exitCode = Reflect.get(firstFailure.error, "exitCode");
+  return typeof exitCode === "number" ? exitCode : null;
+};
+
+const createTableSql = `
+  CREATE TABLE IF NOT EXISTS audit_log (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    ts TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+    tool TEXT NOT NULL,
+    project TEXT NOT NULL,
+    args TEXT NOT NULL,
+    duration INTEGER NOT NULL,
+    success INTEGER NOT NULL,
+    error TEXT,
+    exit_code INTEGER
+  ) STRICT
+`;
+
+const initializeDatabase = (db: Database, retentionDays: number): void => {
+  db.run("PRAGMA journal_mode=WAL");
+  db.run("PRAGMA synchronous=NORMAL");
+  db.run("PRAGMA busy_timeout=5000");
+  db.run(createTableSql);
+  const columns = db.query<TableInfoRow, []>("PRAGMA table_info(audit_log)").all();
+  if (!columns.some((column) => column.name === "project")) {
+    db.run("ALTER TABLE audit_log ADD COLUMN project TEXT");
+  }
+  db.run("UPDATE audit_log SET project = '' WHERE project IS NULL");
+  db.run("CREATE INDEX IF NOT EXISTS idx_audit_log_ts ON audit_log(ts DESC)");
+  db.run("CREATE INDEX IF NOT EXISTS idx_audit_log_tool_ts ON audit_log(tool, ts DESC)");
+  db.run("CREATE INDEX IF NOT EXISTS idx_audit_log_project_ts ON audit_log(project, ts DESC)");
+  db.run("DELETE FROM audit_log WHERE ts < strftime('%Y-%m-%dT%H:%M:%fZ', 'now', ?)", [
+    `-${retentionDays} days`,
+  ]);
+};
+
+const openDatabase = (dbPath: string, retentionDays: number): Database => {
+  if (!isInMemoryDatabase(dbPath)) {
+    mkdirSync(dirname(dbPath), { recursive: true });
+  }
+
+  const db = new Database(dbPath, { create: true, strict: true });
+  initializeDatabase(db, retentionDays);
+
+  if (!isInMemoryDatabase(dbPath)) {
+    try {
+      db.fileControl(constants.SQLITE_FCNTL_PERSIST_WAL, 0);
+    } catch {
+      return db;
+    }
+  }
+
+  return db;
+};
+
+const resolveAuditOptions = (options: AuditServiceOptions): Effect.Effect<ResolvedAuditOptions> =>
+  Effect.tryPromise({
+    try: () => loadConfig(),
+    catch: () => undefined,
+  }).pipe(
+    Effect.orElseSucceed(() => undefined),
+    Effect.map((config) => ({
+      dbPath: expandHomePath(options.dbPath ?? config?.audit?.dbPath ?? resolveAuditDbPath()),
+      retentionDays:
+        options.retentionDays ?? config?.audit?.retentionDays ?? DEFAULT_AUDIT_RETENTION_DAYS,
+    })),
+  );
+
+const createAuditService = (dbPath: string, db: Database | null): AuditServiceShape => ({
+  dbPath,
+  record: (entry) =>
+    db === null
+      ? Effect.void
+      : Effect.sync(() => {
+          db.run(
+            "INSERT INTO audit_log (tool, project, args, duration, success, error, exit_code) VALUES (?, ?, ?, ?, ?, ?, ?)",
+            [
+              safeToolName(entry.tool),
+              entry.project,
+              entry.args,
+              entry.duration,
+              entry.success ? 1 : 0,
+              entry.error ?? null,
+              entry.exitCode ?? null,
+            ],
+          );
+        }),
+  listRecent: (limit = 20) =>
+    db === null
+      ? Effect.succeed([])
+      : Effect.sync(() => {
+          const rows = db
+            .query<AuditRow, [number]>(
+              "SELECT id, ts, tool, project, args, duration, success, error, exit_code FROM audit_log ORDER BY id DESC LIMIT ?",
+            )
+            .all(limit);
+          return rows.map(toAuditEntry);
+        }),
+  purgeOlderThanDays: (days) =>
+    db === null
+      ? Effect.succeed(0)
+      : Effect.sync(() => {
+          const result = db.run(
+            "DELETE FROM audit_log WHERE ts < strftime('%Y-%m-%dT%H:%M:%fZ', 'now', ?)",
+            [`-${days} days`],
+          );
+          return result.changes;
+        }),
+});
+
+export const makeAuditServiceLayer = (options: AuditServiceOptions = {}) => {
+  return Layer.effect(
+    AuditService,
+    Effect.flatMap(resolveAuditOptions(options), ({ dbPath, retentionDays }) =>
+      Effect.acquireRelease(
+        Effect.sync(() => {
+          try {
+            return openDatabase(dbPath, retentionDays);
+          } catch {
+            return null;
+          }
+        }),
+        (db) =>
+          db === null
+            ? Effect.void
+            : Effect.sync(() => {
+                db.close(false);
+              }).pipe(Effect.ignore),
+      ).pipe(Effect.map((db) => createAuditService(dbPath, db))),
+    ),
+  );
+};
+
+export const AuditServiceLayer = makeAuditServiceLayer();
+
+const safelyRecord = (entry: AuditRecord) =>
+  Effect.gen(function* () {
+    const audit = yield* AuditService;
+    yield* audit.record(entry);
+  }).pipe(Effect.ignore);
+
+export const withAudit = <A, E, R>(
+  toolName: string,
+  program: Effect.Effect<A, E, R>,
+): Effect.Effect<A, E, R | AuditService> =>
+  Effect.suspend(() => {
+    const startedAt = Date.now();
+    const project = process.cwd();
+    const args = process.argv.slice(2).join(" ");
+    const tool = safeToolName(toolName || deriveToolNameFromArgv());
+
+    return Effect.matchCauseEffect(program, {
+      onFailure: (cause) =>
+        Effect.flatMap(
+          safelyRecord({
+            tool,
+            project,
+            args,
+            duration: Date.now() - startedAt,
+            success: false,
+            error: formatCause(cause),
+            exitCode: extractExitCode(cause),
+          }),
+          () => Effect.failCause(cause),
+        ),
+      onSuccess: (value) =>
+        Effect.flatMap(
+          safelyRecord({
+            tool,
+            project,
+            args,
+            duration: Date.now() - startedAt,
+            success: true,
+          }),
+          () => Effect.succeed(value),
+        ),
+    });
+  });