Files
archie/internal/tools/builtin/read_tracker.go
T
sam e03cef17c9 feat(tools): lift tau's file and shell tools into the tool registry
The chat agent had two tools -- memory_edit and skill_activate -- so it
could not read a file, search a tree or run a command. ai-sdk's runtime
already drives a tool loop for it (MaxSteps 8, toolExecute wired as the
executor), so the loop was never the missing piece: the registry was empty
of anything useful.

Lifted from tau internal/agent/tools at commit f5289ea, per the recorded
copy-and-mutate strategy: every file carries a provenance header naming its
tau source path, the commit, and the mutations made, so refreshing from
upstream is a diff rather than archaeology.

  internal/tools/builtin/          the lifted tools, ~3.1k lines
  internal/tools/provider/builtin/ the adapter to tools.ToolEntry

Six tools: read, write, edit, shell, grep, find. Tau's own tests came with
them and pass unmodified, which is the evidence that the lift is faithful.

Deliberately not lifted:
  - agent.go (1214 lines): subagent spawning, and the only real coupling in
    the package -- 10 tau packages including chat, sessions, store and
    registry. Nothing the chat agent needs to do work.
  - skill.go: depends on tau's skills package; archie has internal/skill and
    already exposes skill_activate.
  - docs.go: serves tau's own embedded documentation via tau/docs.

Not lifting the coordinator either. It is tau's agent loop (6.4k lines over
ten packages) and archie already has one in the ai-sdk runtime; porting it
would leave two loops competing. Its cancellation and tool events are worth
having, but they are a few hundred lines built against the existing path
rather than six thousand lifted onto a second one.

The adapter bridges two shape differences: archie hands handlers decoded
arguments where tau's executor takes raw JSON, and tau reports tool-level
failure in Result.IsError rather than as an error -- surfaced as a real
error so the runtime and the guardrail engine both see it. Tools are
classified idempotent or mutating for guardrails and budgets; that is
categorisation, not a jail.

chat.workspace roots the tools and defaults to empty, which registers none
of them. They read, write and execute, so the directory has to be a
deliberate choice rather than whatever the daemon started in -- in the
container that is /.

Verified: go build, go vet, gofmt clean; full suite passes.
2026-07-29 15:46:21 +10:00

168 lines
5.0 KiB
Go

// Lifted from tau internal/agent/tools/read_tracker.go
// tau commit f5289ea3782c099339c2d26fe3af8ebcf42ba52d (2026-07-27).
//
// Mutations from upstream:
// - package renamed tools -> builtin (archie-core already has an
// internal/tools package holding the registry these are registered into).
//
// Refresh by diffing against that path at a newer tau commit. Do not
// edit without recording the change above.
package builtin
import (
"fmt"
"os"
"path/filepath"
"slices"
"sync"
)
// lineRange is an inclusive 1-based line interval.
type lineRange struct{ start, end int }
// fileReads is what a session has already been shown of one file. identity is
// a cheap stat fingerprint; when it changes, served is discarded because the
// previously shown lines no longer describe the file.
type fileReads struct {
identity string
served []lineRange // sorted, non-overlapping, non-adjacent
}
// ReadTracker records which files the model has read so that mutation
// tools (write, edit) can enforce a read-before-write safety check, and which
// line ranges of each file it has already been shown so read can avoid
// re-sending content the model already has.
type ReadTracker struct {
mu sync.Mutex
reads map[string]bool // absolute paths that have been read
seen map[string]*fileReads // absolute path -> already-served ranges
}
// NewReadTracker creates a new ReadTracker.
func NewReadTracker() *ReadTracker {
return &ReadTracker{
reads: make(map[string]bool),
seen: make(map[string]*fileReads),
}
}
// FileIdentity is a cheap fingerprint of a file's current state. Size plus
// modification time is enough here: a rewrite that preserves both is
// indistinguishable from no change, and the cost of being wrong is a stale
// suppression notice the model can override with full:true. Hashing every
// re-read would be strictly more accurate and materially more expensive.
func FileIdentity(info os.FileInfo) string {
return fmt.Sprintf("%d:%d", info.Size(), info.ModTime().UnixNano())
}
// Novel reports which part of [start,end] the model has not already been shown
// for this file, and records the whole request as served.
//
// It returns ok=false when the request is entirely covered, meaning read should
// suppress the body. When only part is new AND that part is contiguous, the
// narrowed range is returned. A request whose novel portion is fragmented is
// served whole, because stitching disjoint fragments into one response is more
// confusing to the model than simply repeating some lines.
func (rt *ReadTracker) Novel(cwd, path, identity string, start, end int) (ns, ne int, ok bool) {
abs := resolvePath(cwd, path)
rt.mu.Lock()
defer rt.mu.Unlock()
st := rt.seen[abs]
if st == nil || st.identity != identity {
st = &fileReads{identity: identity}
rt.seen[abs] = st
}
gaps := subtract(lineRange{start, end}, st.served)
st.served = merge(append(st.served, lineRange{start, end}))
switch len(gaps) {
case 0:
return 0, 0, false
case 1:
return gaps[0].start, gaps[0].end, true
default:
return start, end, true
}
}
// subtract returns the parts of want not covered by served (sorted, disjoint).
func subtract(want lineRange, served []lineRange) []lineRange {
var gaps []lineRange
cursor := want.start
for _, s := range served {
if s.end < cursor {
continue
}
if s.start > want.end {
break
}
if s.start > cursor {
gaps = append(gaps, lineRange{cursor, min(s.start-1, want.end)})
}
cursor = max(cursor, s.end+1)
if cursor > want.end {
return gaps
}
}
if cursor <= want.end {
gaps = append(gaps, lineRange{cursor, want.end})
}
return gaps
}
// merge normalises ranges into a sorted, non-overlapping, non-adjacent set.
// Adjacent ranges are coalesced so that [1,100] and [101,200] become [1,200],
// keeping the served set compact across many small reads.
func merge(ranges []lineRange) []lineRange {
if len(ranges) < 2 {
return ranges
}
slices.SortFunc(ranges, func(a, b lineRange) int { return a.start - b.start })
out := ranges[:1]
for _, r := range ranges[1:] {
last := &out[len(out)-1]
if r.start <= last.end+1 {
last.end = max(last.end, r.end)
continue
}
out = append(out, r)
}
return out
}
// MarkRead records that a file at the given path has been read by the
// model. The path is normalised to absolute form before recording.
func (rt *ReadTracker) MarkRead(cwd, path string) {
abs := resolvePath(cwd, path)
rt.mu.Lock()
rt.reads[abs] = true
rt.mu.Unlock()
}
// CheckRead returns an error if the file at the given path has not been
// read by the model in this session. The path is normalised to absolute
// form. A file must be read (via the read tool) before it can be written,
// edited.
func (rt *ReadTracker) CheckRead(cwd, path string) error {
abs := resolvePath(cwd, path)
rt.mu.Lock()
read := rt.reads[abs]
rt.mu.Unlock()
if !read {
rel, _ := filepath.Rel(cwd, abs)
if rel == "" {
rel = abs
}
return fmt.Errorf(
"file %q has not been read in this session - use the read tool first to read the file before writing or editing it",
rel,
)
}
return nil
}