merge(run/pb-toolcalls): project tool_call events into the tool_calls collection

Lane D. The collection existed in the event-capture schema with nothing
writing it; tool calls reached only the on-disk task log, readable as text
and never queryable.

The projection is a decorator on the State Store's task store, wired in
stateStoreDeps. InsertEvent persists the event first and only then, for a
tool_call event, writes one row. A projection failure is counted and logged
but never returned: event persistence is load-bearing, the transcript is
observability, and failing a task write because its shadow failed trades
the fact for the record of it. With no event-capture store the task store
passes through unwrapped.

The event adapts to the existing collection rather than the collection to
the event; args and duration_ms stay reserved. InsertToolCall stays silent
on the notify hook, matching the dispatch tables rather than the
operator-editable ones -- tool calls are high-frequency telemetry, not
dashboard activity.
This commit is contained in:
sam committed 2026-09-23 03:28:39 +10:00
commit b995eac1e1
5 files changed
+488

No files matched your search

+9
View File
@@ -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
}
@@ -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
}
@@ -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")
}
}
@@ -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
}
@@ -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))
}
}