From eec5f1398ed9304ac6e3c9f20560224a3c7e8297 Mon Sep 17 00:00:00 2001
From: Lukas May <lukas.may@carealytix.com>
Date: Fri, 30 Jan 2026 19:59:04 +0100
Subject: [PATCH] feat(04-01): create AgentRepository port interface

- Define AgentRepository interface with CRUD operations
- Add findByName, findByTaskId, findBySessionId for lookups
- Add findByStatus for filtering by agent state
- Add updateStatus and updateSessionId for state changes
- Export AgentStatus type
- Export from repositories barrel file
---
 src/db/repositories/agent-repository.ts | 86 +++++++++++++++++++++++++
 src/db/repositories/index.ts            |  2 +
 2 files changed, 88 insertions(+)
 create mode 100644 src/db/repositories/agent-repository.ts

diff --git a/src/db/repositories/agent-repository.ts b/src/db/repositories/agent-repository.ts
new file mode 100644
index 0000000..7c1e785
--- /dev/null
+++ b/src/db/repositories/agent-repository.ts
@@ -0,0 +1,86 @@
+/**
+ * Agent Repository Port Interface
+ *
+ * Port for Agent aggregate operations.
+ * Implementations (Drizzle, etc.) are adapters.
+ */
+
+import type { Agent, NewAgent } from '../schema.js';
+
+/**
+ * Agent status values.
+ */
+export type AgentStatus = 'idle' | 'running' | 'waiting_for_input' | 'stopped' | 'crashed';
+
+/**
+ * Agent Repository Port
+ *
+ * Defines operations for the Agent aggregate.
+ * Enables agent state persistence for session resumption and listing.
+ */
+export interface AgentRepository {
+  /**
+   * Create a new agent.
+   * Generates id and sets timestamps automatically.
+   * Name must be unique.
+   */
+  create(agent: Omit<NewAgent, 'id' | 'createdAt' | 'updatedAt'>): Promise<Agent>;
+
+  /**
+   * Find an agent by its ID.
+   * Returns null if not found.
+   */
+  findById(id: string): Promise<Agent | null>;
+
+  /**
+   * Find an agent by its human-readable name.
+   * Returns null if not found.
+   */
+  findByName(name: string): Promise<Agent | null>;
+
+  /**
+   * Find an agent by its associated task.
+   * Returns null if no agent is assigned to that task.
+   */
+  findByTaskId(taskId: string): Promise<Agent | null>;
+
+  /**
+   * Find an agent by its Claude CLI session ID.
+   * Used for session resumption.
+   * Returns null if not found.
+   */
+  findBySessionId(sessionId: string): Promise<Agent | null>;
+
+  /**
+   * Find all agents.
+   * Returns empty array if none exist.
+   */
+  findAll(): Promise<Agent[]>;
+
+  /**
+   * Find agents by status.
+   * Returns empty array if no agents have that status.
+   */
+  findByStatus(status: AgentStatus): Promise<Agent[]>;
+
+  /**
+   * Update an agent's status.
+   * Throws if agent not found.
+   * Updates updatedAt timestamp automatically.
+   */
+  updateStatus(id: string, status: AgentStatus): Promise<Agent>;
+
+  /**
+   * Update an agent's session ID.
+   * Called after first CLI run completes and provides session ID.
+   * Throws if agent not found.
+   * Updates updatedAt timestamp automatically.
+   */
+  updateSessionId(id: string, sessionId: string): Promise<Agent>;
+
+  /**
+   * Delete an agent.
+   * Throws if agent not found.
+   */
+  delete(id: string): Promise<void>;
+}
diff --git a/src/db/repositories/index.ts b/src/db/repositories/index.ts
index 5c9166b..0378dce 100644
--- a/src/db/repositories/index.ts
+++ b/src/db/repositories/index.ts
@@ -29,3 +29,5 @@ export type {
   CreateTaskData,
   UpdateTaskData,
 } from './task-repository.js';
+
+export type { AgentRepository, AgentStatus } from './agent-repository.js';