Files
archie/internal/gateway/task_tools.go
T
sam 68a17aed91 feat(taskactions): one approval path answers the review gate from every surface
Decision 1 of docs/prds/pr-review-operator-response.md: the dashboard's
POST /api/tasks/{id}/action is the authoritative surface, chat's /approve
is a shortcut that posts every offered finding, and both reach the same
Service.Apply so one operator intent cannot be recorded as two decisions.

The action body now carries instructions (required by rereview) and the
finding keys an approve posts. taskactions.Service answers an offer
through the guarded RespondReviewGate write: approve records the
selection on the offer, rereview records the instructions, increments the
round and clears the offer, and a rereview with no instructions, with no
offer, or at the cap is refused as a conflict with nothing written. Chat
reaches the same service: chatTaskControllerAdapter.ApproveChatTask
delegates to b.taskActions() instead of its own requeue, which is what
removed the handler's hardcoded implement handoff -- feasibility's deliver
stage now names implement on the task before it waits, the invariant the
handler needs.

The payload crosses every hop it must: the NATS action request, the
gateway.v1 gRPC contract (regenerated), the LocalChatAdapter, and the
webui handler, which answers 400 for a rereview without instructions and
409 for the cap. A rereview event kind names its actor the way the
approval and rejection trios do.

taskactions.Task gains review_gate and rereview_rounds, and the two
surfaces' tests assert they agree.
2026-10-02 02:27:59 +10:00

531 lines
20 KiB
Go

package gateway
import (
"context"
"fmt"
"strings"
"time"
"github.com/samcharles93/archie-core/internal/domain/taskactions"
"github.com/samcharles93/archie-core/internal/taskstate"
"github.com/samcharles93/archie-core/internal/tools"
)
const (
// defaultTaskListLimit is how many tasks a bare task_list returns.
defaultTaskListLimit = 20
// maxTaskListLimit bounds what the model can ask for. A queue of a few
// hundred tasks would otherwise land in the context window whole.
maxTaskListLimit = 100
// defaultTaskLogLimit is how many log entries a bare task_logs returns.
defaultTaskLogLimit = 200
// maxTaskLogLimit bounds what the model can ask for in one call.
maxTaskLogLimit = 2000
)
// ChatTaskSummary is the per-task view the task tools return. It is
// deliberately narrower than a store task: notes, plan and body are the bulk
// of a row and none of them help answer "what are you working on?".
type ChatTaskSummary struct {
ID int64 `json:"id"`
Repo string `json:"repo"` // "owner/name"
Title string `json:"title"`
Status string `json:"status"`
Workflow string `json:"workflow,omitempty"`
PRNumber int `json:"pr_number,omitempty"`
// Attempt is the task's current retry attempt. 0 or 1 means it has never
// been retried; the /tasks command only surfaces this once it is
// actionable information (attempt > 1).
Attempt int `json:"attempt,omitempty"`
// ParkReason explains why a parked task is parked. Empty for any other
// status.
ParkReason string `json:"park_reason,omitempty"`
// UpdatedAt is the task's last transition time, so a caller can tell a
// task that is running but stuck (old UpdatedAt) from one making
// progress (recent UpdatedAt).
UpdatedAt time.Time `json:"updated_at,omitzero"`
}
// ChatTaskLister is the read surface the task tools need. It mirrors the
// existing chatTaskWriter/chatTaskController pattern: gateway states what it
// needs and the daemon supplies an adapter over the store, so this package
// keeps its independence from the task store.
type ChatTaskLister interface {
ListChatTasks(ctx context.Context, identity string, limit int) ([]ChatTaskSummary, error)
}
// TaskListResult is what task_list returns.
type TaskListResult struct {
Tasks []ChatTaskSummary `json:"tasks"`
}
// TaskSpawnResult is what task_spawn returns.
type TaskSpawnResult struct {
ID int64 `json:"id"`
Message string `json:"message"`
}
// ChatTaskActor is the mutation surface task_action needs. It mirrors the
// ChatTaskLister pattern: gateway states what it needs and the daemon
// supplies an adapter over the store and runtime, so this package keeps its
// independence from the task store.
type ChatTaskActor interface {
// ApplyChatTaskAction executes action on taskID, scoped to identity's own
// tasks. A nil identity is an authenticated dashboard operator, who acts
// across identities -- the distinction internal/domain/taskactions draws,
// and not the same as an empty name, which is a real identity in a
// single-identity deployment. res is the review gate answer payload; this
// tool has no instruction or selection syntax, so it is the zero value.
ApplyChatTaskAction(ctx context.Context, identity *string, actor taskactions.Actor, taskID int64, action taskstate.Action, res taskactions.ReviewResponse) (TaskActionResult, error)
}
// ChatTaskLogEntry is one log line as task_logs returns it. It mirrors
// internal/logging.Entry's shape without importing that package: gateway
// keeps its independence from internal/logging the same way it already does
// from the task store, with the daemon adapting between them.
type ChatTaskLogEntry struct {
Time time.Time `json:"time"`
Level string `json:"level"`
Message string `json:"message"`
Fields map[string]any `json:"fields,omitempty"`
}
// ChatTaskLogQuery filters a task_logs read.
type ChatTaskLogQuery struct {
// Component matches the log entry's component field case-insensitively.
// Empty means any.
Component string
// Contains matches the message or any field value, case-insensitively.
Contains string
// Levels restricts results to these levels (case-insensitive). Empty
// means all levels.
Levels []string
// Since excludes entries whose timestamp is strictly before this. Zero
// time disables the bound.
Since time.Time
// Until excludes entries whose timestamp is strictly after this. Zero
// time disables the bound.
Until time.Time
// AfterID is the byte-offset cursor returned in the previous page's
// Cursor field. Zero means "start at the beginning of the scanned
// window". The model treats this as opaque and just passes it back
// unchanged; the byte offset is not intended to be human-readable.
AfterID int64
// Limit caps returned entries.
Limit int
}
// ChatTaskLogResult is what task_logs returns.
type ChatTaskLogResult struct {
Entries []ChatTaskLogEntry `json:"entries"`
// Attempt is the attempt number actually read, so the model can tell
// the caller which run it looked at when none was requested explicitly.
Attempt int `json:"attempt"`
// Truncated reports that older matching entries exist beyond what this
// page examined (the on-disk scan hit its size cap before EOF).
Truncated bool `json:"truncated"`
// Cursor is the opaque byte offset to pass back as AfterID to read the
// next page. It is the file offset just past the last line this page
// returned, so a non-zero value after a full page means "resume here";
// when MoreAvailable is false the caller is done regardless of the
// value. Zero means the log was missing or empty, not "exhausted".
Cursor int64 `json:"cursor"`
// MoreAvailable is true when the scan saw more matching entries that
// did not fit in this page. Combine with Truncated: a result can be
// MoreAvailable=false while still Truncated=true when the scan ended
// at the size cap, or MoreAvailable=true while Truncated=false when
// more matches remain within the same scan window.
MoreAvailable bool `json:"more_available"`
}
// ChatTaskLogReader is the read surface task_logs needs. It mirrors the
// ChatTaskLister pattern: gateway states what it needs and the daemon
// supplies an adapter, so this package keeps its independence from
// the task store and internal/logging.
type ChatTaskLogReader interface {
// ReadChatTaskLogs returns taskID's log entries for attempt (0 selects
// the task's current/latest attempt), scoped to identity's own tasks.
ReadChatTaskLogs(ctx context.Context, identity string, taskID int64, attempt int, q ChatTaskLogQuery) (ChatTaskLogResult, error)
}
// TaskTools builds the chat tools that let Archie see, add to, and manage its own work
// queue. Until these existed, /spawn and the task list were slash commands only
// a human could type, so "what are you working on?" had no tool path at all.
//
// All tools are bound to identity at construction. The model never supplies
// it: a model that could name an identity could read, mutate or file work
// belonging to another instance on the same host.
//
// A nil backend omits its tool rather than registering one that always fails,
// so a daemon without chat task support advertises nothing.
func TaskTools(lister ChatTaskLister, creator TaskCreator, logs ChatTaskLogReader, actor ChatTaskActor, identity string) []tools.ToolEntry {
var entries []tools.ToolEntry
if lister != nil {
entries = append(entries, taskListTool(lister, identity))
}
if creator != nil {
entries = append(entries, taskSpawnTool(creator, identity))
}
if logs != nil {
entries = append(entries, taskLogsTool(logs, identity))
}
if actor != nil {
entries = append(entries, taskActionTool(actor, identity))
}
return entries
}
func taskListTool(lister ChatTaskLister, identity string) tools.ToolEntry {
return tools.ToolEntry{
Name: "task_list",
Toolset: "tasks",
Description: "List the tasks this instance is working on, most recent first. " +
"Use it to answer questions about current, queued, parked or finished work. " +
"Optionally filter by status (queued, running, waiting_human, parked, pr_open, merged, rejected).",
Classification: tools.ClassIdempotent,
Schema: tools.JSONSchema{
"type": "object",
"properties": map[string]any{
"status": map[string]any{
"type": "string",
"description": "Only return tasks with this status. Omit for all statuses.",
},
"limit": map[string]any{
"type": "integer",
"description": fmt.Sprintf(
"Maximum tasks to return. Defaults to %d, capped at %d.",
defaultTaskListLimit, maxTaskListLimit,
),
},
},
},
Handler: func(ctx context.Context, input map[string]any) (any, error) {
limit := taskListLimit(input)
// The bound identity, never input["identity"].
all, err := lister.ListChatTasks(ctx, identity, limit)
if err != nil {
return nil, fmt.Errorf("task_list: %w", err)
}
status := strings.TrimSpace(strings.ToLower(asString(input["status"])))
// Non-nil even when empty: an empty queue is an answer, and a
// null would read to the model as a failed call worth retrying.
filtered := make([]ChatTaskSummary, 0, len(all))
for _, task := range all {
if status != "" && !strings.EqualFold(task.Status, status) {
continue
}
filtered = append(filtered, task)
}
return TaskListResult{Tasks: filtered}, nil
},
}
}
func taskSpawnTool(creator TaskCreator, identity string) tools.ToolEntry {
return tools.ToolEntry{
Name: "task_spawn",
Toolset: "tasks",
Description: "Queue a workflow task for this instance. The selected workflow determines its outcome. " +
"Use it when the user asks for work to be carried out rather than answered in chat.",
Classification: tools.ClassMutating,
Schema: tools.JSONSchema{
"type": "object",
"properties": map[string]any{
"title": map[string]any{
"type": "string",
"description": "What the task should accomplish, as a single instruction.",
},
"repo": map[string]any{
"type": "string",
"description": "Target repository as \"owner/name\". Omit to use this instance's default repository. A repository this instance is not configured for is refused.",
},
"workflow": map[string]any{
"type": "string",
"description": "Workflow to run. Omit to let the daemon route it.",
},
"inputs": map[string]any{
"type": "object",
"description": "Inputs declared by the selected workflow. The daemon validates their names, types and required values before execution.",
},
},
"required": []any{"title"},
},
Handler: func(ctx context.Context, input map[string]any) (any, error) {
title := strings.TrimSpace(asString(input["title"]))
if title == "" {
return nil, fmt.Errorf("task_spawn: title is required")
}
var inputs map[string]any
if value, supplied := input["inputs"]; supplied {
var ok bool
inputs, ok = value.(map[string]any)
if !ok {
return nil, fmt.Errorf("task_spawn: inputs must be an object")
}
}
id, err := creator.CreateTask(ctx, SpawnRequest{
Title: title,
Repo: strings.TrimSpace(asString(input["repo"])),
Workflow: strings.TrimSpace(asString(input["workflow"])),
Inputs: inputs,
// The bound identity, never input["identity"]. CreateTask
// enforces the repository allow-list for it.
Identity: identity,
})
if err != nil {
return nil, fmt.Errorf("task_spawn: %w", err)
}
return TaskSpawnResult{
ID: id,
Message: fmt.Sprintf("queued task %d: %s", id, title),
}, nil
},
}
}
func taskActionTool(actor ChatTaskActor, identity string) tools.ToolEntry {
return tools.ToolEntry{
Name: "task_action",
Toolset: "tasks",
Description: "Perform an operator action on a task (e.g. abandon, archive, retry, stop, cancel, approve, reject). " +
"Use it when the user asks to close, abandon, archive, retry, stop or approve a task.",
Classification: tools.ClassMutating | tools.RequiresApproval,
BuildApprovalDescription: func(input map[string]any) string {
action := strings.TrimSpace(asString(input["action"]))
taskID, _ := asInt64(input["task_id"])
return fmt.Sprintf("Apply action %q to task %d.", action, taskID)
},
Schema: tools.JSONSchema{
"type": "object",
"properties": map[string]any{
"task_id": map[string]any{
"type": "integer",
"description": "ID of the task to act on.",
},
"action": map[string]any{
"type": "string",
"description": "The action to perform: abandon, archive, retry, stop, cancel, approve, reject.",
},
},
"required": []any{"task_id", "action"},
},
Handler: func(ctx context.Context, input map[string]any) (any, error) {
taskID, ok := asInt64(input["task_id"])
if !ok {
return nil, fmt.Errorf("task_action: task_id is required")
}
actionStr := strings.TrimSpace(strings.ToLower(asString(input["action"])))
if actionStr == "" {
return nil, fmt.Errorf("task_action: action is required")
}
// The bound identity, never input["identity"]. Passed by
// address: chat is always scoped, never an operator. The
// actor is that same bound identity, because a bot acting on
// its own channel's task is exactly what happened -- and it is
// recorded as an agent's action, not a person's.
result, err := actor.ApplyChatTaskAction(ctx, &identity, taskactions.ActorFromScope(identity), taskID, taskstate.Action(actionStr), taskactions.ReviewResponse{})
if err != nil {
return nil, fmt.Errorf("task_action: %w", err)
}
return result, nil
},
}
}
func taskLogsTool(reader ChatTaskLogReader, identity string) tools.ToolEntry {
return tools.ToolEntry{
Name: "task_logs",
Toolset: "tasks",
Description: "Read a task's persisted log history -- gate output, agent activity, errors -- " +
"to answer questions like \"why did task N park?\" or \"what happened on task N?\" " +
"without an operator needing to open the dashboard. " +
"Defaults to the task's latest attempt when attempt is omitted. " +
fmt.Sprintf("One call returns at most %d entries. ", maxTaskLogLimit) +
"Two separate signals report incompleteness and they mean different things: " +
"more_available means this call left matching entries unread, so pass its " +
"cursor back as after_id to continue; truncated means the log is larger than " +
"the readable window, so its OLDEST entries cannot be reached by paging at all. " +
"If truncated is true, say so rather than implying you read the whole log, and " +
"use send_file when the operator wants the complete archive.",
Classification: tools.ClassIdempotent,
Schema: taskLogsSchema(),
Handler: func(ctx context.Context, input map[string]any) (any, error) {
taskID, ok := asInt64(input["task_id"])
if !ok {
return nil, fmt.Errorf("task_logs: task_id is required")
}
attempt := 0
if v, ok := asInt64(input["attempt"]); ok {
attempt = int(v)
}
limit := tools.ListLimit(input, defaultTaskLogLimit, maxTaskLogLimit)
levels := asStringSlice(input["level"])
since, err := asRFC3339(input["since"])
if err != nil {
return nil, fmt.Errorf("task_logs: since: %w", err)
}
until, err := asRFC3339(input["until"])
if err != nil {
return nil, fmt.Errorf("task_logs: until: %w", err)
}
var afterID int64
if v, ok := asInt64(input["after_id"]); ok {
afterID = v
}
// The bound identity, never input["identity"].
result, err := reader.ReadChatTaskLogs(ctx, identity, taskID, attempt, ChatTaskLogQuery{
Component: strings.TrimSpace(asString(input["component"])),
Contains: strings.TrimSpace(asString(input["q"])),
Levels: levels,
Since: since,
Until: until,
AfterID: afterID,
Limit: limit,
})
if err != nil {
return nil, fmt.Errorf("task_logs: %w", err)
}
return result, nil
},
}
}
// taskLogsSchema is the task_logs input schema. It lives apart from the
// tool entry only because the literal is long; it is pure data, and the
// handler is the sole consumer.
func taskLogsSchema() tools.JSONSchema {
return tools.JSONSchema{
"type": "object",
"properties": map[string]any{
"task_id": map[string]any{
"type": "integer",
"description": "ID of the task to read logs for.",
},
"attempt": map[string]any{
"type": "integer",
"description": "Which attempt to read. Omit for the task's current/latest attempt.",
},
"component": map[string]any{
"type": "string",
"description": "Only return entries from this component (e.g. \"gate\"). Omit for all components.",
},
"q": map[string]any{
"type": "string",
"description": "Only return entries whose message or fields contain this text (case-insensitive).",
},
"level": map[string]any{
"type": "array",
"items": map[string]any{"type": "string"},
"description": "Only return entries whose level matches one of these (case-insensitive). Omit for all levels.",
},
"since": map[string]any{
"type": "string",
"format": "date-time",
"description": "RFC3339 timestamp; exclude entries strictly before this. Omit for no lower bound.",
},
"until": map[string]any{
"type": "string",
"format": "date-time",
"description": "RFC3339 timestamp; exclude entries strictly after this. Omit for no upper bound.",
},
"after_id": map[string]any{
"type": "integer",
"description": "Opaque cursor from a previous task_logs result's \"cursor\" field. Omit for the first page.",
},
"limit": map[string]any{
"type": "integer",
"description": fmt.Sprintf(
"Maximum entries to return. Defaults to %d, capped at %d.",
defaultTaskLogLimit, maxTaskLogLimit,
),
},
},
"required": []any{"task_id"},
}
}
// asStringSlice reads a JSON array of strings, tolerating absent or
// non-array values by returning nil. A model that emits a single string
// instead of an array is normalised to a one-element slice.
func asStringSlice(v any) []string {
switch t := v.(type) {
case []string:
return t
case []any:
out := make([]string, 0, len(t))
for _, item := range t {
if s, ok := item.(string); ok && strings.TrimSpace(s) != "" {
out = append(out, strings.TrimSpace(s))
}
}
return out
case string:
if s := strings.TrimSpace(t); s != "" {
return []string{s}
}
}
return nil
}
// asRFC3339 parses an RFC3339 timestamp string, treating the zero value
// as "no bound" (returns time.Time{} without error). An obviously
// malformed value is rejected so a model that emits nonsense does not
// silently get every entry. The parser accepts RFC3339Nano (with
// fractional seconds) as well as bare RFC3339 -- the schema advertises
// "RFC3339 timestamp" and per Go's time package the two layouts both
// match when no fractional component is present, but RFC3339 alone
// rejects the fractional case. RFC3339Nano is a strict superset.
func asRFC3339(v any) (time.Time, error) {
s, ok := v.(string)
if !ok || strings.TrimSpace(s) == "" {
return time.Time{}, nil
}
t, err := time.Parse(time.RFC3339Nano, strings.TrimSpace(s))
if err != nil {
return time.Time{}, fmt.Errorf("invalid timestamp %q: %w", s, err)
}
return t, nil
}
// asInt64 reads an integer field. JSON numbers decode as float64, but a
// model that emits an integer through a different provider path can arrive
// as int or int64, so all three are accepted.
func asInt64(v any) (int64, bool) {
switch n := v.(type) {
case float64:
return int64(n), true
case int64:
return n, true
case int:
return int64(n), true
default:
return 0, false
}
}
// taskListLimit resolves the requested limit, falling back to the default for
// anything absent or non-positive and clamping the rest.
//
// JSON numbers decode as float64, but a model that emits an integer through a
// different provider path can arrive as int, so both are accepted.
func taskListLimit(input map[string]any) int {
return tools.ListLimit(input, defaultTaskListLimit, maxTaskListLimit)
}
// asString reads a string field, tolerating an absent or wrongly-typed value
// rather than failing the call over it.
func asString(v any) string {
s, _ := v.(string)
return s
}