Agent tools: plant lookup, plant creation, journal entries (#55)

"Change the garlic garden bed to instead be cucumbers this year" was nearly
executable already — describe_garden resolves "the garlic bed" to an object id
because it reports the NAMES of what's planted, clear_object empties it, and
fill_region replants it. Step three had no way to get its plantId. The toolbox
had no plant tool at all, so the agent could see the string "Garlic" come out of
describe_garden and had no route from "cucumbers" to an id. One missing tool
blocked the whole flagship interaction.

find_plant matches the actor's visible catalog and deliberately returns SEVERAL
candidates rather than one guess. "garlic" against a catalog holding both
"Garlic" and "German Red Garlic" is genuinely ambiguous, and a caller holding
the surrounding conversation is far better placed to disambiguate than a
fuzzy-match heuristic here. Results are ranked exact, then prefix, then
substring, then category, and ordered stably — a tool whose results reshuffle
between calls is one a model can't reason about across turns.

Each result also reports how much seed is left of that plant across the actor's
lots, so the agent can say "you only have enough for half that bed" instead of
confidently planting seed that doesn't exist. Omitted rather than zeroed when
there are no lots, and dropped when lots disagree about the unit, since summing
seeds and grams would be a lie.

create_plant lets a variety be named in conversation without leaving the chat.
It's user-scoped, not garden-scoped — someone with no editable garden can still
name a plant — which the tests assert deliberately rather than assume.

add_journal_entry arrived with #52: "note that the west bed has mildew" is
squarely the kind of thing you say out loud while walking around.

Also reviewed the descriptions on the existing seven tools, since they are the
model's only documentation. fill_region's region vocabulary now says north is
the top of the garden, gives a worked example of the replant sequence, and notes
that filling twice is safe.

The demo sequence is now a test: describe_garden → find_plant("cucumber") →
clear_object → fill_region, ending with a bed of cucumbers and no active garlic.

go.mod is deliberately untouched — majordomo stays out of the module until #56
drops the build tag, so the default build is unaffected.

Closes #55

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01H3zbym8Doka2d7D48maSgZ

internal/agent/tools.go

@@ -36,11 +36,36 @@ func NewToolbox(svc *service.Service, actorID int64) *llm.Toolbox {
 			"Place one plop of a plant inside a plantable object, positioned in the object's LOCAL frame (0,0 = object center, -y = north).",
 			a.placePlanting),
 		llm.DefineTool("fill_region",
-			"Fill a named region of a plantable object with a plant, hex-packed. Region is one of nw/ne/sw/se (corners), north/south/east/west or top/bottom/left/right (halves), or all.",
+			"Fill part of a plantable object with one plant, hex-packed at the plant's spacing. "+
+				"region is a compass name, not coordinates: nw|ne|sw|se for the quarter corners, "+
+				"north|south|east|west (or top|bottom|left|right) for halves, or all for the whole thing. "+
+				"North is the top of the garden. Example: to replant a whole bed, clear_object then "+
+				"fill_region with region=all. Filling skips spots already covered by an existing plant, "+
+				"so it is safe to run twice.",
 			a.fillRegion),
 		llm.DefineTool("clear_object",
-			"Remove all plants from an object (soft-remove; history is kept).",
+			"Remove all plants from an object. They are soft-removed, so the planting history for past "+
+				"seasons is kept and the change can be undone. Use this before replanting a bed with "+
+				"something else.",
 			a.clearObject),
+		llm.DefineTool("find_plant",
+			"Look up plants in the user's catalog by name or category, to get the plantId that "+
+				"place_planting and fill_region need. Returns SEVERAL candidates when the query is "+
+				"ambiguous — \"garlic\" may match both the built-in \"Garlic\" and a custom \"German Red "+
+				"Garlic\" — so pick the one that fits what the user asked for, or ask them which. Each "+
+				"result also reports how much seed the user has left of it, when they have recorded any.",
+			a.findPlant),
+		llm.DefineTool("create_plant",
+			"Add a new plant to the user's own catalog, for when they name a variety that isn't in it "+
+				"yet. Check find_plant first — creating a duplicate of something that already exists is "+
+				"worse than reusing it. The plant belongs to the user, not to any garden.",
+			a.createPlant),
+		llm.DefineTool("add_journal_entry",
+			"Write a dated observation into the garden's grow journal — what happened, and when. "+
+				"Attach it to one bed with objectId when it is about that bed. This is for events "+
+				"(\"powdery mildew on the west bed\", \"first frost\"), not for descriptions of what a "+
+				"thing is. observedAt defaults to today; set it to backdate.",
+			a.addJournalEntry),
 	)
 }
 
@@ -108,6 +133,42 @@ func (a *adapter) fillRegion(ctx context.Context, args struct {
 	return a.svc.FillNamedRegion(ctx, a.actor, args.ObjectID, args.Region, args.PlantID, args.SpacingOverride)
 }
 
+func (a *adapter) findPlant(ctx context.Context, args struct {
+	Query string `json:"query" description:"plant name or category to search for, e.g. \"cucumber\" or \"herb\"; empty lists the catalog"`
+}) (any, error) {
+	return a.svc.FindPlants(ctx, a.actor, args.Query)
+}
+
+func (a *adapter) createPlant(ctx context.Context, args struct {
+	Name           string  `json:"name" description:"the variety's name, e.g. \"German Red Garlic\""`
+	Category       string  `json:"category" description:"vegetable | herb | flower | fruit | tree_shrub | cover"`
+	SpacingCM      float64 `json:"spacingCm" description:"mature in-row spacing in cm; this is what fill_region packs to"`
+	Color          string  `json:"color" description:"hex color for the plant on the canvas, e.g. #8a5a8a"`
+	Icon           string  `json:"icon" description:"a single emoji to draw it with, e.g. 🧄"`
+	DaysToMaturity *int    `json:"daysToMaturity" description:"optional days from planting to harvest"`
+	SourceURL      string  `json:"sourceUrl" description:"optional http(s) link to where the seed came from"`
+	Vendor         string  `json:"vendor" description:"optional vendor name, e.g. \"Johnny\u0027s Selected Seeds\""`
+}) (any, error) {
+	return a.svc.CreatePlant(ctx, a.actor, service.PlantInput{
+		Name: args.Name, Category: args.Category, SpacingCM: args.SpacingCM,
+		Color: args.Color, Icon: args.Icon, DaysToMaturity: args.DaysToMaturity,
+		SourceURL: args.SourceURL, Vendor: args.Vendor,
+	})
+}
+
+func (a *adapter) addJournalEntry(ctx context.Context, args struct {
+	GardenID   int64  `json:"gardenId" description:"garden the observation is about"`
+	ObjectID   *int64 `json:"objectId" description:"optional bed the observation is about; omit for a garden-level note"`
+	Body       string `json:"body" description:"what happened, in plain words"`
+	ObservedAt string `json:"observedAt" description:"optional date it happened, YYYY-MM-DD; defaults to today"`
+}) (any, error) {
+	in := service.JournalInput{ObjectID: args.ObjectID, Body: args.Body}
+	if args.ObservedAt != "" {
+		in.ObservedAt = &args.ObservedAt
+	}
+	return a.svc.CreateJournalEntry(ctx, a.actor, args.GardenID, in)
+}
+
 func (a *adapter) clearObject(ctx context.Context, args struct {
 	ObjectID int64 `json:"objectId" description:"object to remove all plants from"`
 }) (any, error) {