Refactor db pkg

internal/db/schema/1.init.sql

@@ -99,31 +99,56 @@ BEGIN
     WHERE id = OLD.conversation_id;
 END;
 
--- Approvals track tool calls that require user permission before
--- execution. When the LLM requests a tool call that needs approval, a row
--- is inserted with status "pending" and the agent loop pauses. The UI
--- queries pending approvals to present an inbox to the user. When the
--- user decides, the status transitions to "approved" (proceed) or
--- "denied" (refuse), and the agent loop resumes.
+-- Executions track the state of tool calls. Each row references a
+-- specific tool call within an assistant message via message_id and
+-- tool_call_id. The tool call's name and arguments are stored in the
+-- message's content JSON; they are not duplicated here. The tool's
+-- execution result (stdout, stderr, exit code) is stored as a
+-- separate tool-role message in the messages table, not in this row.
 --
--- Each approval references a specific tool call within an assistant
--- message via message_id and tool_call_id. The tool call's name and
--- arguments are stored in the message's content JSON; they are not
--- duplicated here. The tool's execution result (stdout, stderr, exit
--- code) is stored as a separate tool-role message in the messages
--- table, not in the approval.
-CREATE TABLE IF NOT EXISTS approvals (
+-- Lifecycle, by tool kind:
+--
+-- A. Approval not required:
+--
+-- ┌────────────┐    ┌────────────┐
+-- │  running   ├┄┄┄▶│ completed  │
+-- └────────────┘    └────────────┘
+--
+-- B. Approval required:
+--
+-- ┌────────────┐    ┌────────────┐    ┌────────────┐    ┌────────────┐
+-- │  pending   ├───▶│  approved  ├───▶│  running   ├┄┄┄▶│ completed  │
+-- └────────────┘    └────────────┘    └────────────┘    └────────────┘
+--       │
+--       ▼
+-- ┌────────────┐
+-- │   denied   │
+-- └────────────┘
+--
+-- The dashed arrow from running to completed indicates the possibility that a
+-- tool call may not complete. if a tool call is interrupted, the row ends at
+-- running.
+--
+-- approved:  tool call approved by user. The call has not launched yet.
+-- completed: the tool call returned output or an error. Terminal.
+-- denied:    user refused the tool call. Terminal.
+-- pending:   the call awaits a user decision.
+-- running:   the tool call either:
+--            A. is about to be started,
+--            B. was started and is still executing,
+--            C. was interrupted before it started or finished (terminal).
+CREATE TABLE IF NOT EXISTS executions (
     created_at   TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
     id           TEXT PRIMARY KEY,
     message_id   TEXT NOT NULL REFERENCES messages(id) ON DELETE CASCADE,
-    status       TEXT NOT NULL DEFAULT 'pending',
+    status       TEXT NOT NULL DEFAULT 'running',
     tool_call_id TEXT NOT NULL,
     updated_at   TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
-    CHECK (status IN ('pending', 'approved', 'denied'))
+    CHECK (status IN ('approved', 'completed', 'denied', 'pending', 'running'))
 ) STRICT;
 
-CREATE INDEX IF NOT EXISTS idx_approvals_message ON approvals(message_id);
-CREATE INDEX IF NOT EXISTS idx_approvals_pending ON approvals(status) WHERE status = 'pending';
+CREATE INDEX IF NOT EXISTS idx_executions_message ON executions(message_id);
+CREATE INDEX IF NOT EXISTS idx_executions_pending ON executions(status) WHERE status = 'pending';
 
 -- Default user. Temporary workaround until authentication is built.
 INSERT INTO users (id, name, password, role)