From d4df04f549cf52cc497f29678e966efe82a2cb90 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Wed, 23 Sep 2026 03:26:14 +1000 Subject: [PATCH] feat(edastore): project tool_call events into the tool_calls collection The tool_calls collection existed in the event-capture schema but nothing wrote it. Give it its write path: - edastore gains InsertToolCall and the minimal TaskToolCalls read, writing only the existing collection. No new index: the collection is an append-only transcript and the SQLite predecessor had no unique index. - internal/app/archied composes toolCallProjectingTaskStore, a decorator on the task store that persists the event first, then -- only for tool_call events -- writes one row. A projection failure is counted and logged but never returned from InsertEvent: event persistence is load-bearing, tool_calls is observability. - stateStoreDeps wires the decorator around deps.Tasks when both stores are open, and passes Tasks through untouched otherwise. The event adapts to the existing schema, not the other way round: the tool name comes from data, a succeeded call's detail is the row's result, a failed call's detail its error; args and duration_ms stay reserved for a producer that reports them. --- internal/app/archied/state_store.go | 9 + internal/app/archied/state_store_toolcalls.go | 87 ++++++++ .../app/archied/state_store_toolcalls_test.go | 192 ++++++++++++++++++ .../infrastructure/edastore/tool_calls.go | 98 +++++++++ .../edastore/tool_calls_test.go | 102 ++++++++++ 5 files changed, 488 insertions(+) create mode 100644 internal/app/archied/state_store_toolcalls.go create mode 100644 internal/app/archied/state_store_toolcalls_test.go create mode 100644 internal/infrastructure/edastore/tool_calls.go create mode 100644 internal/infrastructure/edastore/tool_calls_test.go diff --git a/internal/app/archied/state_store.go b/internal/app/archied/state_store.go index 1756b2506..4918ee7b5 100644 --- a/internal/app/archied/state_store.go +++ b/internal/app/archied/state_store.go @@ -300,6 +300,15 @@ func (b *boot) stateStoreDeps(grants *staterpc.TaskGrants) staterpc.Deps { deps.BindingDispatcher = b.eda deps.PlaybookDispatcher = b.eda } + // tool_call events project into the tool_calls collection on the same + // event-capture store: this process legitimately owns both, so the + // projection rides on the task-store surface it decorates. With no + // event-capture store (or no task store) there is nothing to project + // through, and Tasks passes through unwrapped rather than decorating a + // nil operand. + if b.eda != nil && b.st != nil { + deps.Tasks = newToolCallProjectingTaskStore(b.st, b.eda, b.log) + } if btc, ok := b.st.(storecontract.BindingTaskCreator); ok { deps.BindingTaskCreator = btc } diff --git a/internal/app/archied/state_store_toolcalls.go b/internal/app/archied/state_store_toolcalls.go new file mode 100644 index 000000000..f4ba41edc --- /dev/null +++ b/internal/app/archied/state_store_toolcalls.go @@ -0,0 +1,87 @@ +package archied + +import ( + "context" + "log/slog" + "sync/atomic" + + "github.com/samcharles93/archie-core/internal/domain/storecontract" + "github.com/samcharles93/archie-core/internal/events" + "github.com/samcharles93/archie-core/internal/infrastructure/edastore" +) + +// toolCallWriter is the edastore surface the projection writes through. Kept +// narrow so a test can fail it without touching the real store. +type toolCallWriter interface { + InsertToolCall(ctx context.Context, tc edastore.ToolCall) error +} + +// toolCallProjectingTaskStore decorates the State Store's task store so every +// persisted tool_call event also lands in the tool_calls collection on the +// event-capture store, which this same process owns. The task event log stays +// the source of truth; the collection is the queryable transcript of it. +// +// A projection failure is NEVER returned: event persistence is load-bearing, +// the collection is observability, and failing a task write because its +// transcript copy failed would trade the fact for its shadow. The failure is +// instead counted and logged with the running count, so it is visible without +// ever changing InsertEvent's outcome. +type toolCallProjectingTaskStore struct { + storecontract.TaskStore + toolCalls toolCallWriter + log *slog.Logger + projectionFailures atomic.Int64 +} + +func newToolCallProjectingTaskStore(inner storecontract.TaskStore, toolCalls toolCallWriter, log *slog.Logger) *toolCallProjectingTaskStore { + if log == nil { + log = slog.Default() + } + return &toolCallProjectingTaskStore{TaskStore: inner, toolCalls: toolCalls, log: log} +} + +// toolCallProjectionFailures reports how many tool_call projections have been +// dropped since this process started. Named and exported to the test surface +// rather than buried in a log field alone: a silent swallow is the bug this +// decorator exists not to have. +func (s *toolCallProjectingTaskStore) toolCallProjectionFailures() int64 { + return s.projectionFailures.Load() +} + +func (s *toolCallProjectingTaskStore) InsertEvent(ctx context.Context, e events.Event) (int64, error) { + id, err := s.TaskStore.InsertEvent(ctx, e) + if err != nil || e.Kind != events.KindToolCall { + return id, err + } + if perr := s.toolCalls.InsertToolCall(ctx, toolCallFromEvent(e)); perr != nil { + failures := s.projectionFailures.Add(1) + s.log.Error("tool_call projection failed; the event persisted but the tool_calls row did not", + "err", perr, "task_id", e.TaskID, "attempt", e.Attempt, + "tool", e.Data["tool"], "projection_failures", failures) + } + return id, nil +} + +// toolCallFromEvent adapts a tool_call event to the existing tool_calls +// collection. The event carries the tool name and the failure flag in data and +// the one-line outcome in detail: a succeeded call's summary is its result, a +// failed call's summary is its error. The collection's args and duration_ms +// fields stay unwritten -- the event reports neither -- so they are schema +// reserved for a producer that one day reports them, not promises this +// projection makes. +func toolCallFromEvent(e events.Event) edastore.ToolCall { + tool, _ := e.Data["tool"].(string) + failed, _ := e.Data["failed"].(bool) + tc := edastore.ToolCall{ + TaskID: e.TaskID, + Attempt: e.Attempt, + Tool: tool, + CalledAt: e.At, + } + if failed { + tc.Error = e.Detail + } else { + tc.Result = e.Detail + } + return tc +} diff --git a/internal/app/archied/state_store_toolcalls_test.go b/internal/app/archied/state_store_toolcalls_test.go new file mode 100644 index 000000000..1371f7d55 --- /dev/null +++ b/internal/app/archied/state_store_toolcalls_test.go @@ -0,0 +1,192 @@ +package archied + +import ( + "bytes" + "context" + "errors" + "log/slog" + "strings" + "testing" + "time" + + "github.com/samcharles93/archie-core/internal/events" + "github.com/samcharles93/archie-core/internal/infrastructure/edastore" + "github.com/samcharles93/archie-core/internal/infrastructure/staterpc" + "github.com/samcharles93/archie-core/internal/store" +) + +func toolCallEvent(taskID int64, attempt int) events.Event { + return events.Event{ + Kind: events.KindToolCall, + TaskID: taskID, + Attempt: attempt, + Stage: "implement", + Detail: "all checks passed", + Data: map[string]any{"tool": "shell", "failed": false}, + At: time.Now().UTC(), + Workflow: "tdd", + } +} + +// TestInsertEventProjectsToolCall pins the projection (test a): one tool_call +// event through the decorated store persists the event AND exactly one +// tool_calls row, with the row's fields taken from the event -- the tool name +// from data, the output summary in result for a succeeded call. +func TestInsertEventProjectsToolCall(t *testing.T) { + st := store.OpenTest(t) + eda := edastore.OpenTest(t) + ts := newToolCallProjectingTaskStore(st, eda, slog.Default()) + + id, err := ts.InsertEvent(t.Context(), toolCallEvent(42, 2)) + if err != nil { + t.Fatalf("InsertEvent() error = %v", err) + } + if id == 0 { + t.Fatal("InsertEvent() returned id 0; the event itself must still persist") + } + + rows, err := eda.TaskToolCalls(t.Context(), 42) + if err != nil { + t.Fatalf("TaskToolCalls() error = %v", err) + } + if len(rows) != 1 { + t.Fatalf("TaskToolCalls() returned %d rows, want exactly one per tool_call event: %+v", len(rows), rows) + } + row := rows[0] + if row.TaskID != 42 || row.Attempt != 2 { + t.Errorf("row task/attempt = %d/%d, want 42/2", row.TaskID, row.Attempt) + } + if row.Tool != "shell" { + t.Errorf("row tool = %q, want \"shell\" from the event's data", row.Tool) + } + if row.Result != "all checks passed" { + t.Errorf("row result = %q, want the event detail of a succeeded call", row.Result) + } + if row.Error != "" { + t.Errorf("row error = %q, want empty for a succeeded call", row.Error) + } + if row.CalledAt.IsZero() { + t.Error("row called_at is zero; it must carry the event time") + } +} + +// TestInsertEventProjectsFailedToolCall pins the failure column: a tool_call +// event whose call failed stores its detail under error, not result, so the +// transcript can distinguish the two without re-parsing text. +func TestInsertEventProjectsFailedToolCall(t *testing.T) { + st := store.OpenTest(t) + eda := edastore.OpenTest(t) + ts := newToolCallProjectingTaskStore(st, eda, slog.Default()) + + e := toolCallEvent(42, 2) + e.Detail = "error: no such file" + e.Data = map[string]any{"tool": "read_file", "failed": true} + if _, err := ts.InsertEvent(t.Context(), e); err != nil { + t.Fatalf("InsertEvent() error = %v", err) + } + + rows, err := eda.TaskToolCalls(t.Context(), 42) + if err != nil { + t.Fatalf("TaskToolCalls() error = %v", err) + } + if len(rows) != 1 { + t.Fatalf("TaskToolCalls() returned %d rows, want 1", len(rows)) + } + if rows[0].Error != "error: no such file" { + t.Errorf("row error = %q, want the failed call's detail", rows[0].Error) + } + if rows[0].Result != "" { + t.Errorf("row result = %q, want empty for a failed call", rows[0].Result) + } +} + +// TestInsertEventLeavesOtherKindsUnprojected pins the kind gate: only +// tool_call events reach the collection; the task timeline's other kinds must +// not grow tool_calls rows. +func TestInsertEventLeavesOtherKindsUnprojected(t *testing.T) { + st := store.OpenTest(t) + eda := edastore.OpenTest(t) + ts := newToolCallProjectingTaskStore(st, eda, slog.Default()) + + if _, err := ts.InsertEvent(t.Context(), events.Event{ + Kind: events.KindStageFinish, TaskID: 42, Attempt: 2, + Data: map[string]any{"duration_ms": 12.0}, + }); err != nil { + t.Fatalf("InsertEvent() error = %v", err) + } + + rows, err := eda.TaskToolCalls(t.Context(), 42) + if err != nil { + t.Fatalf("TaskToolCalls() error = %v", err) + } + if len(rows) != 0 { + t.Fatalf("TaskToolCalls() returned %d rows for a stage_finish event, want 0", len(rows)) + } +} + +// failingToolCallWriter stands in for a broken PocketBase side, so the +// never-returned-failure contract can be tested without sabotaging the real +// store. +type failingToolCallWriter struct{ err error } + +func (f failingToolCallWriter) InsertToolCall(context.Context, edastore.ToolCall) error { + return f.err +} + +// TestInsertEventSucceedsWhenProjectionFails pins the load-bearing half of the +// contract: a tool_calls write failure is never returned from InsertEvent -- +// event persistence is the contract, the projection is observability -- and +// the failure is recorded, not swallowed silently. +func TestInsertEventSucceedsWhenProjectionFails(t *testing.T) { + st := store.OpenTest(t) + var buf bytes.Buffer + ts := newToolCallProjectingTaskStore(st, failingToolCallWriter{ + err: errors.New("disk on fire"), + }, slog.New(slog.NewTextHandler(&buf, nil))) + + id, err := ts.InsertEvent(t.Context(), toolCallEvent(42, 2)) + if err != nil { + t.Fatalf("InsertEvent() error = %v; a projection failure must never fail the event write", err) + } + if id == 0 { + t.Fatal("InsertEvent() returned id 0; the event must still persist") + } + if got := ts.toolCallProjectionFailures(); got != 1 { + t.Errorf("toolCallProjectionFailures() = %d, want 1: the failure must be counted, not swallowed", got) + } + if !strings.Contains(buf.String(), "disk on fire") { + t.Errorf("log output %q does not carry the projection failure; it was swallowed silently", buf.String()) + } + // The event row is what the whole surface exists for -- it must be there. + persisted, err := st.TaskEvents(t.Context(), 42) + if err != nil { + t.Fatalf("TaskEvents() error = %v", err) + } + if len(persisted) != 1 { + t.Fatalf("TaskEvents() returned %d events, want 1: the event persisted despite the projection failure", len(persisted)) + } +} + +// TestStateStoreDepsProjectToolCalls pins the wire-in: with both stores open, +// the composition serves Tasks as the projecting decorator; with no +// event-capture store, Tasks is passed through untouched rather than wrapped +// around a nil writer. +func TestStateStoreDepsProjectToolCalls(t *testing.T) { + st := store.OpenTest(t) + eda := edastore.OpenTest(t) + + b := newBootstrap() + b.st = st + b.eda = eda + deps := b.stateStoreDeps(&staterpc.TaskGrants{}) + if _, ok := deps.Tasks.(*toolCallProjectingTaskStore); !ok { + t.Fatalf("deps.Tasks = %T, want the tool_call projecting decorator", deps.Tasks) + } + + plain := newBootstrap() + plain.st = st + plainDeps := plain.stateStoreDeps(&staterpc.TaskGrants{}) + if _, ok := plainDeps.Tasks.(*toolCallProjectingTaskStore); ok { + t.Fatal("deps.Tasks is decorated with no event-capture store on the boot; the projection would write through a nil writer") + } +} diff --git a/internal/infrastructure/edastore/tool_calls.go b/internal/infrastructure/edastore/tool_calls.go new file mode 100644 index 000000000..7a72f1e30 --- /dev/null +++ b/internal/infrastructure/edastore/tool_calls.go @@ -0,0 +1,98 @@ +package edastore + +import ( + "context" + "encoding/json" + "fmt" + "time" + + "github.com/pocketbase/pocketbase/core" +) + +// ToolCall is one completed tool invocation during an agent stage run, as the +// tool_call event projection stores it. The projection adapts the event to the +// existing collection (schema.go): a tool's output summary goes in result, a +// failure's detail in error. The args and duration_ms fields the schema also +// carries are left unwritten -- the tool_call event reports neither -- and a +// future producer that has them can start filling them without a schema +// change. +type ToolCall struct { + ID string + TaskID int64 + Attempt int + Tool string + Result string + Error string + CalledAt time.Time +} + +// InsertToolCall appends one row to the tool_calls collection. There is no +// idempotency here, deliberately: the collection is an append-only transcript +// and the schema carries no unique index (the SQLite predecessor had none -- +// tool calls lived only in the on-disk task log), so one event is one row. +// +// The notify hook stays silent, matching the task-dispatch tables rather than +// the operator-editable ones: tool calls are high-frequency telemetry, not +// dashboard activity. +func (s *Store) InsertToolCall(_ context.Context, tc ToolCall) error { + collection, err := s.app.FindCollectionByNameOrId(CollToolCalls) + if err != nil { + return err + } + r := core.NewRecord(collection) + r.Set("task_id", tc.TaskID) + r.Set("attempt", tc.Attempt) + r.Set("tool", tc.Tool) + if tc.Result != "" { + r.Set("result", tc.Result) + } + if tc.Error != "" { + r.Set("error", tc.Error) + } + if !tc.CalledAt.IsZero() { + // called_at is an autodate field, but an explicitly set date is kept: + // the row carries the time the tool call happened, not the time it + // was projected. + r.Set("called_at", tc.CalledAt) + } + if err := s.app.Save(r); err != nil { + return fmt.Errorf("edastore: insert tool call: %w", err) + } + return nil +} + +// TaskToolCalls returns one task's tool calls in call order. +func (s *Store) TaskToolCalls(_ context.Context, taskID int64) ([]ToolCall, error) { + records, err := s.app.FindRecordsByFilter(CollToolCalls, "task_id = {:task}", "+called_at", 0, 0, + map[string]any{"task": taskID}) + if err != nil { + return nil, fmt.Errorf("edastore: list tool calls: %w", err) + } + out := make([]ToolCall, 0, len(records)) + for _, r := range records { + out = append(out, ToolCall{ + ID: r.Id, + TaskID: r.GetInt64("task_id"), + Attempt: r.GetInt("attempt"), + Tool: r.GetString("tool"), + Result: jsonTextToString(r.GetString("result")), + Error: r.GetString("error"), + CalledAt: r.GetDateTime("called_at").Time(), + }) + } + return out, nil +} + +// jsonTextToString unwraps the JSON string a JSONField stores a plain text +// summary under, and falls back to the raw text for anything that is not a +// JSON string (e.g. an object a future producer stored directly). +func jsonTextToString(raw string) string { + if raw == "" { + return "" + } + var decoded string + if err := json.Unmarshal([]byte(raw), &decoded); err != nil { + return raw + } + return decoded +} diff --git a/internal/infrastructure/edastore/tool_calls_test.go b/internal/infrastructure/edastore/tool_calls_test.go new file mode 100644 index 000000000..d845c977a --- /dev/null +++ b/internal/infrastructure/edastore/tool_calls_test.go @@ -0,0 +1,102 @@ +package edastore_test + +import ( + "testing" + "time" + + "github.com/samcharles93/archie-core/internal/infrastructure/edastore" +) + +func insertToolCall(t *testing.T, s *edastore.Store, tc edastore.ToolCall) { + t.Helper() + if err := s.InsertToolCall(t.Context(), tc); err != nil { + t.Fatalf("InsertToolCall() error = %v", err) + } +} + +// TestInsertToolCallRoundTrip pins the write/read pair on the tool_calls +// collection: a row written with the fields the tool_call projection provides +// reads back unchanged, and the read filters on task_id so one task's calls +// never surface in another's. +func TestInsertToolCallRoundTrip(t *testing.T) { + s := newStore(t) + at := time.Date(2026, 9, 23, 1, 2, 3, 0, time.UTC) + + insertToolCall(t, s, edastore.ToolCall{ + TaskID: 42, + Attempt: 2, + Tool: "shell", + Result: "all checks passed", + CalledAt: at, + }) + insertToolCall(t, s, edastore.ToolCall{ + TaskID: 42, + Attempt: 2, + Tool: "read_file", + Error: "no such file", + CalledAt: at.Add(time.Second), + }) + // A different task's call must not leak into the read below. + insertToolCall(t, s, edastore.ToolCall{ + TaskID: 7, + Attempt: 1, + Tool: "shell", + Result: "other task's call", + CalledAt: at.Add(2 * time.Second), + }) + + got, err := s.TaskToolCalls(t.Context(), 42) + if err != nil { + t.Fatalf("TaskToolCalls() error = %v", err) + } + if len(got) != 2 { + t.Fatalf("TaskToolCalls() returned %d rows for task 42, want 2: %+v", len(got), got) + } + + first, second := got[0], got[1] + // Chronological order: the earlier call first. + if first.Tool != "shell" || second.Tool != "read_file" { + t.Errorf("order = [%q, %q], want [shell, read_file] by called_at", first.Tool, second.Tool) + } + if first.TaskID != 42 || first.Attempt != 2 { + t.Errorf("first row task/attempt = %d/%d, want 42/2", first.TaskID, first.Attempt) + } + if first.Result != "all checks passed" { + t.Errorf("first row result = %q, want the stored summary without JSON quoting", first.Result) + } + if first.Error != "" { + t.Errorf("first row error = %q, want empty: a succeeded call is not an error", first.Error) + } + if second.Error != "no such file" { + t.Errorf("second row error = %q, want the stored failure detail", second.Error) + } + if second.Result != "" { + t.Errorf("second row result = %q, want empty: a failed call has no result", second.Result) + } + if first.CalledAt.IsZero() { + t.Error("first row called_at is zero; the call time must round-trip") + } +} + +// TestInsertToolCallIsAnAppendOnlyTranscript pins that the collection is one +// row per tool call, not an upsert: repeated calls with the same (task, +// attempt, tool) are distinct transcript entries. There is no unique index and +// there must not be one -- the SQLite predecessor had none (tool calls lived +// only in the on-disk task log), so the schema's non-unique (task_id, attempt) +// index stays the only one. +func TestInsertToolCallIsAnAppendOnlyTranscript(t *testing.T) { + s := newStore(t) + at := time.Date(2026, 9, 23, 1, 2, 3, 0, time.UTC) + row := edastore.ToolCall{TaskID: 42, Attempt: 3, Tool: "shell", Result: "ok", CalledAt: at} + + insertToolCall(t, s, row) + insertToolCall(t, s, row) + + got, err := s.TaskToolCalls(t.Context(), 42) + if err != nil { + t.Fatalf("TaskToolCalls() error = %v", err) + } + if len(got) != 2 { + t.Fatalf("TaskToolCalls() returned %d rows, want 2: the transcript is append-only, not a dedup ledger", len(got)) + } +}