Files
archie/internal/gateway/task_tools.go
T
sam 28128eb4ed feat(identity): attribute a task action to the identity that acted
The transport could carry an actor and nothing filled it. It does now, so a
dashboard approval is recorded as the person whose credential verified, and an
agent's token is recorded as the agent's action -- for an agent, agent_approved;
for a person, human_approved; and for a caller whose identity archie could not
verify, task_approved, which claims nothing about who did it.

The actor travels the path the action takes: webui reads it from the request
context the middleware resolved, carries it in the gateway request, the daemon
passes it through the in-process adapter, and the NATS request body carries it to
the service that records it. Scope stays separate from actor at every hop, because
scope is which task a caller may touch and the actor is who touched it.

A chat channel's bound identity is an actor too: a bot acting on its own channel's
task is recorded as an agent's action rather than a person's, via ActorFromScope,
whose empty kind is what keeps it out of human_approved. The agent-facing
task_action tool passes that identity and never input["identity"].

The UI process's credential check is now filled by endpoint references rather than
by configuration: -oidc-issuer and -oidc-audience on archie-ui, two URLs the
process already understands the shape of, with the verifier built in Run because
cmd/ parses flags and nothing else. The UI package still never reads config, and a
configured provider that cannot be reached fails boot rather than falling back to
the gate that names nobody.

Evidence for this change, stated as measured: go build ./... and go vet ./... are
clean, and every package this touches passes -- webui, domain/taskactions,
infrastructure/taskactions, infrastructure/gatewayrpc, gateway, app/archieui,
app/archied, domain/messaging, channels/telegram, cmd/archie-ui. task check could
not be run to completion: it fails in cmd/archie-messaging on an untracked
internal/buildinfo package another lane has in flight, which is not this change and
was left untouched. The end-to-end flip is covered in
internal/webui/api_tasks_actor_test.go: a person's credential produces a record
naming that person with human_approved, an agent's produces agent_approved, an
unverified request produces task_approved with no actor, and a request carrying
forged actor fields cannot name one.
2026-09-22 14:52:10 +10:00

518 lines
19 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"`
Stage string `json:"stage,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 internal/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 internal/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.
ApplyChatTaskAction(ctx context.Context, identity *string, actor taskactions.Actor, taskID int64, action taskstate.Action) (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 internal/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
// internal/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 new task for this instance to work on in its own worktree, " +
"opening a pull request for review when it finishes. " +
"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 (e.g. implement, tdd, feasibility). Omit to let the daemon route it.",
},
},
"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")
}
id, err := creator.CreateTask(ctx, SpawnRequest{
Title: title,
Repo: strings.TrimSpace(asString(input["repo"])),
Workflow: strings.TrimSpace(asString(input["workflow"])),
// 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))
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
}