diff --git a/README.md b/README.md index ea91d0307..112da4cc7 100644 --- a/README.md +++ b/README.md @@ -99,6 +99,7 @@ zero doctor [--connectivity] [--json] # health checks zero config [--json] # inspect resolved configuration zero sandbox policy [--json] # inspect sandbox backend support zero serve --mcp [-C ] # expose Zero read-only tools over MCP stdio +zero specialist list|show|create|edit|delete # manage local specialist sub-agents zero update --check [--json --target windows-x64] # check for a newer release ``` @@ -124,6 +125,8 @@ runtimes (Ollama, gateways, etc.) plug in the same way. | `update_plan` | maintain a live task plan | plan | | `write_file` · `edit_file` · `apply_patch` | create & modify files | write (gated) | | `bash` | run shell commands | shell (gated) | +| `Task` · `TaskOutput` · `TaskStop` | delegate to specialist sub-agents | shell/read (gated by tool) | +| `GenerateSpecialist` | create project-local specialist manifests | write (gated) | Write/shell tools route through the permission policy before any side effect. @@ -199,6 +202,7 @@ and [`docs/UPDATE.md`](docs/UPDATE.md) for the update flow. - [Product Requirements (PRD)](docs/PRD.md) — vision, goals, full feature spec, roadmap - [Stream-JSON protocol](docs/STREAM_JSON_PROTOCOL.md) — headless I/O contract +- [Specialists](docs/SPECIALISTS.md) — sub-agent manifests, Task tools, and background task state - [Headless exec PRD](docs/M1_HEADLESS_EXEC_PRD.md) - [npm wrapper smoke checklist](docs/NPM_WRAPPER_SMOKE.md) - [Performance](docs/PERFORMANCE.md) · [Install](docs/INSTALL.md) · [Update](docs/UPDATE.md) diff --git a/docs/SPECIALISTS.md b/docs/SPECIALISTS.md new file mode 100644 index 000000000..7435a56e0 --- /dev/null +++ b/docs/SPECIALISTS.md @@ -0,0 +1,140 @@ +# Zero Specialists + +Specialists are named sub-agents that Zero can delegate focused work to through +the `Task` tool. A specialist is a markdown manifest with YAML-style +frontmatter plus a system prompt body. + +Specialists can be built in, user-scoped, or project-scoped: + +| Scope | Path | Notes | +| --- | --- | --- | +| Built-in | compiled into Zero | `worker`, `explorer`, and `code-review` ship with the binary. | +| User | `~/.config/zero/specialists/*.md` | Available across local workspaces. | +| Project | `.zero/specialists/*.md` | Shared with the current repository when committed. | + +Project specialists override user and built-in specialists with the same name. +User specialists override built-ins. + +## CLI Management + +```bash +zero specialist list +zero specialist show worker +zero specialist path + +zero specialist create api-review \ + --project \ + --description "Reviews API changes" \ + --tools read-only,plan \ + --prompt "Review API changes for compatibility and missing tests." + +zero specialist edit api-review --project +zero specialist delete api-review --project +``` + +Use `--json` with `list`, `show`, `path`, `create`, or `delete` when scripting. +`create --force` replaces an existing manifest, but refuses symlink overwrites. +`edit` also refuses symlink manifests before opening `$VISUAL` or `$EDITOR`. + +## Manifest Format + +```markdown +--- +name: api-review +description: Reviews API changes for compatibility and missing tests. +tools: + - read-only + - plan +--- + +Review API changes for behavior regressions, compatibility breaks, and missing +tests. Report concrete findings with file paths. +``` + +Supported frontmatter keys: + +| Key | Purpose | +| --- | --- | +| `name` | Lowercase specialist id. Use letters, numbers, and dashes. | +| `description` | Short summary shown in listings and task metadata. | +| `extends` | Optional base specialist to inherit prompt/model/tools from. | +| `model` | Optional model override. Empty means inherit the parent model. | +| `reasoningEffort` | Optional reasoning effort override. | +| `tools` | Array of tool categories or tool ids. | + +If the body is empty and `description` is set, Zero uses the description as the +system prompt and reports a warning in `zero specialist show`. + +## Tool Selection + +Known categories: + +| Category | Tools | +| --- | --- | +| `read-only` | `read_file`, `list_directory`, `grep`, `glob` | +| `edit` | read-only tools plus `write_file`, `edit_file`, `apply_patch` | +| `execute` | read-only tools plus `bash` | +| `plan` | `update_plan` | + +Specialist manifests cannot enable `Task`, `TaskOutput`, `TaskStop`, or +`GenerateSpecialist`, so child specialists cannot spawn more specialists or +author new ones. + +## Agent Tools + +Zero registers these tools for top-level agent runs: + +| Tool | Purpose | +| --- | --- | +| `Task` | Launch a specialist sub-agent for a focused prompt. | +| `TaskOutput` | Read or block on a background specialist task's output. | +| `TaskStop` | Stop a running background specialist task. | +| `GenerateSpecialist` | Create a project-local specialist manifest from a description. | + +`GenerateSpecialist` is project-scoped only. It writes to +`.zero/specialists`, not the user specialist directory. + +Example LLM-facing `Task` payload: + +```json +{ + "name": "explorer", + "description": "Find session storage code", + "prompt": "Find the files that create, load, and list sessions." +} +``` + +Background task payload: + +```json +{ + "name": "worker", + "description": "Audit release docs", + "prompt": "Check the release docs for stale TypeScript references.", + "run_in_background": true +} +``` + +The returned `task_id` is also the child session id. Use it with +`TaskOutput`, `TaskStop`, or `Task` resume. + +## Background State + +Background specialist output is stored under: + +```text +${XDG_DATA_HOME:-~/.local/share}/zero/background/ +``` + +Each task has: + +- `.ndjson` for the child process stream output +- `.json` for task metadata such as status, PID, parent session, and + timestamps + +Persisted metadata lets a new background manager instance read completed task +output or stop a still-running task by id. + +If Zero is restarted while a background task is still marked `running`, the new +manager marks that task `error` and clears its PID. This avoids sending +`TaskStop` to a stale PID that may now belong to an unrelated process. diff --git a/internal/background/manager.go b/internal/background/manager.go index 5bacb2c01..8b6a3c870 100644 --- a/internal/background/manager.go +++ b/internal/background/manager.go @@ -1,8 +1,10 @@ package background import ( + "encoding/json" "errors" "fmt" + "log" "os" "path/filepath" "regexp" @@ -55,6 +57,7 @@ type ManagerOptions struct { type Manager struct { mu sync.Mutex tasks map[string]Task + warnings []string rootDir string now func() time.Time killProcess func(pid int) error @@ -84,7 +87,11 @@ func NewManagerWithOptions(options ManagerOptions) (*Manager, error) { if killProcess == nil { killProcess = terminateProcess } - return &Manager{tasks: map[string]Task{}, rootDir: rootDir, now: now, killProcess: killProcess}, nil + manager := &Manager{tasks: map[string]Task{}, rootDir: rootDir, now: now, killProcess: killProcess} + if err := manager.loadTasks(); err != nil { + return nil, err + } + return manager, nil } func DefaultRoot(env map[string]string) string { @@ -108,6 +115,12 @@ func (manager *Manager) RootDir() string { return manager.rootDir } +func (manager *Manager) LoadWarnings() []string { + manager.mu.Lock() + defer manager.mu.Unlock() + return append([]string(nil), manager.warnings...) +} + func (manager *Manager) Register(input RegisterInput) (string, error) { taskID := strings.TrimSpace(input.TaskID) if !validTaskID(taskID) { @@ -144,7 +157,7 @@ func (manager *Manager) Register(input RegisterInput) (string, error) { return "", fmt.Errorf("close background task output file: %w", err) } - manager.tasks[taskID] = Task{ + task := Task{ ID: taskID, Type: taskType, SpecialistName: strings.TrimSpace(input.SpecialistName), @@ -155,6 +168,12 @@ func (manager *Manager) Register(input RegisterInput) (string, error) { OutputFile: outputFile, StartedAt: manager.now(), } + manager.tasks[taskID] = task + if err := manager.persistTaskLocked(task); err != nil { + delete(manager.tasks, taskID) + _ = os.Remove(outputFile) + return "", err + } return outputFile, nil } @@ -171,6 +190,9 @@ func (manager *Manager) SetPID(taskID string, pid int) error { return fmt.Errorf("background task not found: %s", taskID) } task.PID = pid + if err := manager.persistTaskLocked(task); err != nil { + return err + } manager.tasks[taskID] = task return nil } @@ -194,6 +216,9 @@ func (manager *Manager) UpdateStatus(taskID string, status Status, exitCode int) } else if task.CompletedAt.IsZero() { task.CompletedAt = manager.now() } + if err := manager.persistTaskLocked(task); err != nil { + return err + } manager.tasks[taskID] = task return nil } @@ -218,6 +243,9 @@ func (manager *Manager) MarkExited(taskID string, status Status, exitCode int) e if task.CompletedAt.IsZero() { task.CompletedAt = manager.now() } + if err := manager.persistTaskLocked(task); err != nil { + return err + } manager.tasks[taskID] = task return nil } @@ -299,10 +327,141 @@ func (manager *Manager) markKilledIfStillRunning(taskID string, pid int) error { if task.CompletedAt.IsZero() { task.CompletedAt = manager.now() } + if err := manager.persistTaskLocked(task); err != nil { + return err + } manager.tasks[taskID] = task return nil } +func (manager *Manager) loadTasks() error { + entries, err := os.ReadDir(manager.rootDir) + if err != nil { + return fmt.Errorf("read background task directory: %w", err) + } + for _, entry := range entries { + if entry.IsDir() || filepath.Ext(entry.Name()) != ".json" { + continue + } + if entry.Type()&os.ModeSymlink != 0 { + manager.warnf("skipped symlink background task metadata: %s", filepath.Join(manager.rootDir, entry.Name())) + continue + } + taskID := strings.TrimSuffix(entry.Name(), ".json") + if !validTaskID(taskID) { + manager.warnf("skipped invalid background task metadata file %q", entry.Name()) + continue + } + path := manager.metadataFile(taskID) + data, err := os.ReadFile(path) + if err != nil { + manager.warnf("skipped unreadable background task metadata %s: %s", path, err) + continue + } + var task Task + if err := json.Unmarshal(data, &task); err != nil { + manager.warnf("skipped invalid background task metadata %s: %s", path, err) + continue + } + task, changed, err := manager.normalizeLoadedTask(taskID, task) + if err != nil { + manager.warnf("skipped invalid background task metadata %s: %s", path, err) + continue + } + if changed { + if err := manager.persistTaskLocked(task); err != nil { + manager.warnf("failed to repair background task metadata %s: %s", path, err) + } + } + manager.tasks[task.ID] = task + } + return nil +} + +func (manager *Manager) normalizeLoadedTask(fileTaskID string, task Task) (Task, bool, error) { + changed := false + task.ID = strings.TrimSpace(task.ID) + if task.ID == "" { + task.ID = fileTaskID + changed = true + } + if task.ID != fileTaskID { + return Task{}, false, fmt.Errorf("metadata id %q does not match file id %q", task.ID, fileTaskID) + } + if !validTaskID(task.ID) { + return Task{}, false, fmt.Errorf("invalid task id %q", task.ID) + } + if trimmed := strings.TrimSpace(task.Type); trimmed != task.Type { + task.Type = trimmed + changed = true + } + if task.Type == "" { + return Task{}, false, fmt.Errorf("background task %s requires a type", task.ID) + } + if !validStatus(task.Status) { + return Task{}, false, fmt.Errorf("invalid background task status %q", task.Status) + } + if task.PID < 0 { + return Task{}, false, fmt.Errorf("invalid background task pid %d", task.PID) + } + outputFile, err := manager.outputFile(task.ID, task.OutputFile) + if err != nil { + return Task{}, false, err + } + if outputFile != task.OutputFile { + changed = true + } + task.OutputFile = outputFile + if task.Status == StatusRunning { + task.Status = StatusError + task.PID = 0 + task.ExitCode = -1 + if task.CompletedAt.IsZero() { + task.CompletedAt = manager.now() + } + changed = true + manager.warnf("marked reloaded running background task %s as error; original process ownership was lost", task.ID) + } + return task, changed, nil +} + +func (manager *Manager) persistTaskLocked(task Task) error { + data, err := json.MarshalIndent(task, "", " ") + if err != nil { + return fmt.Errorf("encode background task metadata: %w", err) + } + path := manager.metadataFile(task.ID) + file, err := os.CreateTemp(filepath.Dir(path), filepath.Base(path)+".tmp-*") + if err != nil { + return fmt.Errorf("create background task metadata temp file: %w", err) + } + tmp := file.Name() + if _, err := file.Write(append(data, '\n')); err != nil { + _ = file.Close() + _ = os.Remove(tmp) + return fmt.Errorf("write background task metadata: %w", err) + } + if err := file.Close(); err != nil { + _ = os.Remove(tmp) + return fmt.Errorf("close background task metadata: %w", err) + } + if err := os.Rename(tmp, path); err != nil { + _ = os.Remove(tmp) + return fmt.Errorf("replace background task metadata: %w", err) + } + return nil +} + +func (manager *Manager) metadataFile(taskID string) string { + return filepath.Join(manager.rootDir, taskID+".json") +} + +func (manager *Manager) warnf(format string, args ...any) { + message := fmt.Sprintf(format, args...) + manager.warnings = append(manager.warnings, message) + log.Printf("zero background: %s", message) +} + func (manager *Manager) OutputPath(taskID string) string { task, ok := manager.Get(taskID) if !ok { diff --git a/internal/background/manager_test.go b/internal/background/manager_test.go index aaf60876b..2bf5663c3 100644 --- a/internal/background/manager_test.go +++ b/internal/background/manager_test.go @@ -89,6 +89,152 @@ func TestManagerRegistersListsAndKillsTask(t *testing.T) { } } +func TestManagerPersistsAndLoadsTasks(t *testing.T) { + root := t.TempDir() + now := sequenceClock( + time.Date(2026, 6, 7, 10, 0, 0, 0, time.UTC), + time.Date(2026, 6, 7, 10, 0, 1, 0, time.UTC), + ) + manager, err := NewManagerWithOptions(ManagerOptions{RootDir: root, Now: now}) + if err != nil { + t.Fatalf("NewManagerWithOptions returned error: %v", err) + } + outputFile, err := manager.Register(RegisterInput{ + TaskID: "task_1", + Type: "specialist", + SpecialistName: "worker", + Description: "Persist metadata", + ParentID: "parent", + }) + if err != nil { + t.Fatalf("Register returned error: %v", err) + } + if err := manager.SetPID("task_1", 4321); err != nil { + t.Fatalf("SetPID returned error: %v", err) + } + if err := manager.UpdateStatus("task_1", StatusCompleted, 0); err != nil { + t.Fatalf("UpdateStatus returned error: %v", err) + } + + reloaded, err := NewManager(root) + if err != nil { + t.Fatalf("NewManager reload returned error: %v", err) + } + task, ok := reloaded.Get("task_1") + if !ok { + t.Fatal("reloaded manager did not find task") + } + if task.ID != "task_1" || + task.Type != "specialist" || + task.SpecialistName != "worker" || + task.Description != "Persist metadata" || + task.ParentID != "parent" || + task.PID != 4321 || + task.Status != StatusCompleted || + task.ExitCode != 0 || + task.OutputFile != outputFile || + task.StartedAt.IsZero() || + task.CompletedAt.IsZero() { + t.Fatalf("reloaded task = %#v", task) + } + parentTasks := reloaded.ListByParent("parent") + if len(parentTasks) != 1 || parentTasks[0].ID != "task_1" { + t.Fatalf("reloaded parent tasks = %#v", parentTasks) + } +} + +func TestManagerPersistsKilledStatus(t *testing.T) { + root := t.TempDir() + manager, err := NewManagerWithOptions(ManagerOptions{ + RootDir: root, + KillProcess: func(pid int) error { + return nil + }, + }) + if err != nil { + t.Fatalf("NewManagerWithOptions returned error: %v", err) + } + if _, err := manager.Register(RegisterInput{TaskID: "task", Type: "specialist", PID: 42}); err != nil { + t.Fatalf("Register returned error: %v", err) + } + if err := manager.Kill("task"); err != nil { + t.Fatalf("Kill returned error: %v", err) + } + + reloaded, err := NewManager(root) + if err != nil { + t.Fatalf("NewManager reload returned error: %v", err) + } + task, ok := reloaded.Get("task") + if !ok || task.Status != StatusKilled || task.ExitCode != -1 || task.CompletedAt.IsZero() { + t.Fatalf("reloaded killed task = %#v", task) + } +} + +func TestManagerSkipsInvalidPersistedMetadata(t *testing.T) { + root := t.TempDir() + if err := os.WriteFile(filepath.Join(root, "task.json"), []byte(`{"id":"other","type":"specialist","status":"running","outputFile":"task.ndjson"}`+"\n"), 0o600); err != nil { + t.Fatalf("write metadata: %v", err) + } + + manager, err := NewManager(root) + + if err != nil { + t.Fatalf("NewManager returned error for invalid metadata: %v", err) + } + if _, ok := manager.Get("task"); ok { + t.Fatal("manager loaded invalid task metadata") + } + warnings := strings.Join(manager.LoadWarnings(), "\n") + if !strings.Contains(warnings, "does not match file id") { + t.Fatalf("load warnings = %q, want id mismatch warning", warnings) + } +} + +func TestManagerMarksReloadedRunningTaskNonKillable(t *testing.T) { + root := t.TempDir() + manager, err := NewManager(root) + if err != nil { + t.Fatalf("NewManager returned error: %v", err) + } + if _, err := manager.Register(RegisterInput{TaskID: "task", Type: "specialist", PID: 42}); err != nil { + t.Fatalf("Register returned error: %v", err) + } + killed := []int{} + reloaded, err := NewManagerWithOptions(ManagerOptions{ + RootDir: root, + KillProcess: func(pid int) error { + killed = append(killed, pid) + return nil + }, + }) + if err != nil { + t.Fatalf("NewManager reload returned error: %v", err) + } + task, ok := reloaded.Get("task") + if !ok { + t.Fatal("reloaded manager did not find task") + } + if task.Status != StatusError || task.PID != 0 || task.ExitCode != -1 || task.CompletedAt.IsZero() { + t.Fatalf("reloaded running task was not orphaned: %#v", task) + } + if err := reloaded.Kill("task"); err == nil || !strings.Contains(err.Error(), "is error") { + t.Fatalf("Kill reloaded running task error = %v", err) + } + if len(killed) != 0 { + t.Fatalf("Kill signaled stale pids: %#v", killed) + } + + reloadedAgain, err := NewManager(root) + if err != nil { + t.Fatalf("second reload returned error: %v", err) + } + task, ok = reloadedAgain.Get("task") + if !ok || task.Status != StatusError || task.PID != 0 { + t.Fatalf("repaired task metadata did not persist: %#v", task) + } +} + func TestManagerRejectsUnsafeTaskIDsAndOutputPaths(t *testing.T) { manager, err := NewManager(t.TempDir()) if err != nil { diff --git a/internal/specialist/output_tool_test.go b/internal/specialist/output_tool_test.go index 086833641..e1a4f57ae 100644 --- a/internal/specialist/output_tool_test.go +++ b/internal/specialist/output_tool_test.go @@ -54,6 +54,39 @@ func TestOutputToolReadsCompletedTaskSummary(t *testing.T) { } } +func TestOutputToolReadsTaskAfterManagerReload(t *testing.T) { + root := t.TempDir() + manager, err := background.NewManager(root) + if err != nil { + t.Fatalf("NewManager returned error: %v", err) + } + outputFile, err := manager.Register(background.RegisterInput{ + TaskID: "child_task", + Type: "specialist", + SpecialistName: "worker", + Description: "Reloaded output", + }) + if err != nil { + t.Fatalf("Register returned error: %v", err) + } + if err := os.WriteFile(outputFile, []byte(`{"schemaVersion":1,"type":"final","runId":"run_1","text":"persisted output"}`+"\n"), 0o600); err != nil { + t.Fatalf("WriteFile returned error: %v", err) + } + if err := manager.UpdateStatus("child_task", background.StatusCompleted, 0); err != nil { + t.Fatalf("UpdateStatus returned error: %v", err) + } + reloaded, err := background.NewManager(root) + if err != nil { + t.Fatalf("NewManager reload returned error: %v", err) + } + + result := NewOutputTool(reloaded).Run(context.Background(), map[string]any{"task_id": "child_task"}) + + if result.Status != tools.StatusOK || !strings.Contains(result.Output, "output:\npersisted output") || result.Meta["status"] != string(background.StatusCompleted) { + t.Fatalf("TaskOutput reloaded result = %#v", result) + } +} + func TestOutputToolFallsBackToRawLines(t *testing.T) { manager, err := background.NewManager(t.TempDir()) if err != nil {