Merge branch 'main' into feat/desktop-control-plane-port

Author: AbirAbbas

CHANGELOG.md

@@ -6,6 +6,122 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
 <!-- changelog:entries -->
 
+## [0.1.114-rc.2] - 2026-07-22
+
+
+### Added
+
+- Feat(cli): surface the harness golden path (af wait, catalog, golden_path help, JSON envelopes) (#816)
+
+* feat(cli): emit a JSON envelope for af call --async under -o json
+
+`af call --async` printed a bare run-id string on stdout for every output
+format, so a harness parsing `-o json` got a non-JSON token. Under an
+explicitly requested machine format (-o json/-o yaml) it now emits
+{"run_id": "...", "status": "accepted"} so parsers get valid JSON/YAML.
+
+The default and pretty paths keep the bare run-id line that shell scripts
+capture via RUN_ID=$(af call node.reasoner --async), so that contract does
+not regress.
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
+
+* feat(cli): surface the golden path in af agent help
+
+The machine-friendly `af agent help` payload taught discovery and
+introspection but never execution: quick_start omitted `af call` and
+`af tail` entirely, so a harness could find agents but was never shown how
+to run one.
+
+Add a `golden_path` field — an ordered array of {step, command, purpose}
+covering the full driving loop (doctor → catalog → install → secrets →
+run → ls/discover → call --schema → call --async → wait/tail) — and add
+`af call` and `af tail` entries to quick_start.
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
+
+* feat(cli): install both AgentField skills when no skill name is given
+
+`af skill install` with no argument resolved to Catalog[0] and installed
+only the `agentfield` build skill, never `agentfield-use` — the drive
+skill that documents the discover → call → wait loop. A first-time user
+therefore never got the golden-loop docs.
+
+Add skillkit.InstallAll, which installs every catalog skill into the
+resolved targets, and call it from `af skill install` when no skill name
+is passed. Explicit `af skill install <name>` is unchanged. The
+interactive picker copy now names both skills (build + drive).
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
+
+* feat(cli): add a shared control-plane-unreachable hint
+
+`af call`/`af ls`/`af tail` emitted a raw Go dial error when the control
+plane was down, with no guidance — while `af agent` commands already
+appended a reachability hint. Every CLI command that talks to the control
+plane routes through makeRequest, so wrap a transport-level failure there
+with a shared, actionable hint:
+
+  Control plane not reachable at <url>. Start it with `af server` or
+  launch the AgentField desktop app.
+
+A cancelled context (Ctrl-C / caller-handled timeout) is passed through
+unwrapped so only genuine connectivity failures get the hint.
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
+
+* feat(cli): add af wait to block on an async run
+
+`af call --async` returns a run_id, but there was no first-class way to
+block until that run finished — a harness had to poll or tail. Add
+`af wait <run_id> [--timeout <sec, default 600>]`: it polls the run
+overview (the same /api/v1/agentic/run/:run_id API `af agent run --id`
+uses) until every execution is terminal, prints the final status and
+result as JSON, and maps outcomes to exit codes — 0 on succeeded, 1 on
+failed/cancelled, 2 on timeout.
+
+A 404 (records not yet written after an async accept) is treated as
+"not ready" so a freshly-accepted run keeps polling. The command also
+exercises the shared control-plane-unreachable hint, covered here by a
+cross-command test over call/ls/tail/wait.
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
+
+* feat(cli): add af catalog to browse installable agent nodes
+
+There was no CLI way to discover installable nodes — the only curated
+catalog lived in the desktop app (desktop/src/shared/catalog.ts). Add
+`af catalog`, backed by an in-binary catalog seeded from that same
+curated list (name, description, install source, docs URL), so a harness
+can browse nodes before `af install` and works offline.
+
+Supports `-o json`/`-o yaml`; the human table ends with the hint
+`af install <source>`.
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
+
+* test(cli): cover af wait/catalog command paths for the patch gate
+
+Add behavior tests for the previously-untested command wiring and
+error paths surfaced by the coverage patch gate:
+
+- af wait: pretty output, invalid-format/empty-id (exit 2), a control
+  plane 5xx (exit 3), the nil-opts default path, end-to-end command
+  execution, and rootExecutionResult (explicit root, last-execution
+  fallback, non-JSON, empty).
+- af catalog: end-to-end command execution under -o json.
+- af skill install <name>: the explicit-name path stays single-skill.
+- makeRequest: a cancelled context is passed through unwrapped, not
+  relabeled as an unreachable-control-plane error.
+
+Raises control-plane patch coverage back over the 80% floor.
+
+Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
+
+---------
+
+Co-authored-by: Claude Fable 5 <noreply@anthropic.com> (d6197f0)
+
 ## [0.1.114-rc.1] - 2026-07-22
 
 

VERSION

@@ -1 +1 @@
-0.1.114-rc.1
+0.1.114-rc.2

control-plane/internal/cli/agent_commands.go

@@ -907,10 +907,29 @@ func agentHelpData() map[string]interface{} {
 			"af agent discover -q run",
 			"af agent search \"review pull request\"",
 			"af agent query -r runs --limit 10",
+			"af call <node>.<reasoner> --schema",
+			"af call <node>.<reasoner> --async -o json",
+			"af wait <run_id> -o json",
+			"af tail <run_id>",
 			"af agent run --id <run_id>",
 			"af agent kb topics",
 			"af agent kb guide --goal 'build swe agent'",
 		},
+		// golden_path is the end-to-end loop a harness follows to go from a cold
+		// start to a result: discover → install → run → schema → call → wait.
+		// Each step is ordered and self-contained so an agent can execute them in
+		// sequence without prior context.
+		"golden_path": []map[string]interface{}{
+			{"step": 1, "command": "af doctor", "purpose": "Confirm the CLI can reach a running control plane and inspect the environment"},
+			{"step": 2, "command": "af catalog -o json", "purpose": "Browse installable agent nodes (name, description, install source)"},
+			{"step": 3, "command": "af install <source>", "purpose": "Install a node from the catalog, a git URL, or a local path"},
+			{"step": 4, "command": "af secrets set <KEY> <value>", "purpose": "Provide the API keys the node needs (e.g. model-provider keys)"},
+			{"step": 5, "command": "af run <node>", "purpose": "Start the node so its reasoners register with the control plane"},
+			{"step": 6, "command": "af ls   # or: af agent discover -q <term>", "purpose": "List the reasoners now available to call"},
+			{"step": 7, "command": "af call <node>.<reasoner> --schema", "purpose": "Fetch a reasoner's input schema before calling it"},
+			{"step": 8, "command": "af call <node>.<reasoner> --async -o json", "purpose": "Trigger the reasoner; get {\"run_id\":...,\"status\":\"accepted\"} back as JSON"},
+			{"step": 9, "command": "af wait <run_id> -o json   # or: af tail <run_id>", "purpose": "Block for the final status+result as JSON, or stream progress live"},
+		},
 		"auth": map[string]interface{}{
 			"method":           "Set X-API-Key header via --api-key or AGENTFIELD_API_KEY",
 			"public_endpoints": []string{"GET /api/v1/agentic/kb/topics", "GET /api/v1/agentic/kb/articles", "GET /api/v1/agentic/kb/articles/:article_id", "GET /api/v1/agentic/kb/guide"},

control-plane/internal/cli/agent_helpers_test.go

@@ -7,6 +7,7 @@ import (
 	"net/http"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 	"time"
 
@@ -174,6 +175,30 @@ func TestAgentHelpDataShape(t *testing.T) {
 	require.NoError(t, err)
 	require.Contains(t, string(raw), `"quick_start"`)
 	require.Contains(t, string(raw), `"response_schemas"`)
+
+	// Contract: quick_start teaches execution, not just introspection — it must
+	// surface `af call` and `af tail` (the audit found these were omitted).
+	quickStart, ok := data["quick_start"].([]string)
+	require.True(t, ok)
+	joined := strings.Join(quickStart, "\n")
+	require.Contains(t, joined, "af call")
+	require.Contains(t, joined, "af tail")
+
+	// Contract: golden_path is the ordered driving loop a harness follows.
+	golden, ok := data["golden_path"].([]map[string]interface{})
+	require.True(t, ok)
+	require.GreaterOrEqual(t, len(golden), 8)
+	var commands []string
+	for i, step := range golden {
+		require.Equal(t, i+1, step["step"], "steps must be ordered starting at 1")
+		require.NotEmpty(t, step["command"])
+		require.NotEmpty(t, step["purpose"])
+		commands = append(commands, step["command"].(string))
+	}
+	loop := strings.Join(commands, "\n")
+	for _, want := range []string{"af doctor", "af catalog", "af install", "af secrets set", "af run", "af call", "--schema", "--async", "af wait", "af tail"} {
+		require.Contains(t, loop, want, "golden_path must cover %q", want)
+	}
 }
 
 func TestListCommandAndLogViewer(t *testing.T) {

control-plane/internal/cli/call.go

@@ -128,6 +128,13 @@ func runCall(ctx context.Context, target string, opts *callOptions) error {
 		if runID == "" {
 			return cliExitError{Code: 3, Err: fmt.Errorf("server accepted async execution without run_id")}
 		}
+		// When a machine format is explicitly requested (-o json/-o yaml), emit a
+		// structured envelope so a harness parsing stdout gets valid JSON instead
+		// of a bare token. The default/pretty path keeps the bare run-id line that
+		// shell scripts capture via `RUN_ID=$(af call node.reasoner --async)`.
+		if requested := strings.ToLower(strings.TrimSpace(opts.outputFormat)); requested == "json" || requested == "yaml" {
+			return writeValue(opts.stdout, map[string]interface{}{"run_id": runID, "status": "accepted"}, requested)
+		}
 		_, _ = fmt.Fprintln(opts.stdout, runID)
 		return nil
 	}

control-plane/internal/cli/catalog.go

@@ -0,0 +1,117 @@
+package cli
+
+import (
+	"fmt"
+	"io"
+	"os"
+
+	"github.com/Agent-Field/agentfield/control-plane/internal/ui"
+	"github.com/spf13/cobra"
+)
+
+// nodeCatalogEntry describes one installable AgentField agent node.
+//
+// This is deliberately a hand-vetted, in-binary list so `af catalog` works
+// offline and gives a harness a curated set of nodes to install before any
+// registry search lands. It is seeded from the desktop app's curated list
+// (desktop/src/shared/catalog.ts) — keep the two in sync when adding nodes.
+// `name` MUST equal the node's agentfield-package.yaml `name:` (the registry
+// key after install), which is often not the repo name (SWE-AF → swe-planner).
+type nodeCatalogEntry struct {
+	Name        string `json:"name"`
+	Description string `json:"description"`
+	Source      string `json:"source"` // pass to `af install <source>`
+	Docs        string `json:"docs"`   // public repo/docs URL
+	Language    string `json:"language"`
+}
+
+// nodeCatalog is the curated set of installable nodes. Mirrors
+// desktop/src/shared/catalog.ts. Docs point at the public GitHub repo (the
+// `//<subdir>` source selector stripped, since the docs live at the repo root).
+var nodeCatalog = []nodeCatalogEntry{
+	{
+		Name:        "swe-planner",
+		Description: "Autonomous software-engineering fleet: plan, code, test, and ship production-grade PRs",
+		Source:      "https://github.com/Agent-Field/SWE-AF",
+		Docs:        "https://github.com/Agent-Field/SWE-AF",
+		Language:    "python",
+	},
+	{
+		Name:        "swe-planner-go",
+		Description: "Go port of the SWE fleet: same planning/execution reasoners, one static binary",
+		Source:      "https://github.com/Agent-Field/SWE-AF//go",
+		Docs:        "https://github.com/Agent-Field/SWE-AF",
+		Language:    "go",
+	},
+	{
+		Name:        "pr-af",
+		Description: "Turns a plain task description into a draft pull request on GitHub",
+		Source:      "https://github.com/Agent-Field/pr-af",
+		Docs:        "https://github.com/Agent-Field/pr-af",
+		Language:    "python",
+	},
+	{
+		Name:        "pr-af-go",
+		Description: "Go port of the PR review agent: same reasoners, one static binary",
+		Source:      "https://github.com/Agent-Field/pr-af//go",
+		Docs:        "https://github.com/Agent-Field/pr-af",
+		Language:    "go",
+	},
+	{
+		Name:        "sec-af",
+		Description: "Code security auditor: scans repositories and proves exploitability with verdicts and traces",
+		Source:      "https://github.com/Agent-Field/sec-af",
+		Docs:        "https://github.com/Agent-Field/sec-af",
+		Language:    "python",
+	},
+	{
+		Name:        "cloudsecurity-af",
+		Description: "Cloud security posture: read-only attack-path scans across AWS, GCP, and Azure",
+		Source:      "https://github.com/Agent-Field/cloudsecurity-af",
+		Docs:        "https://github.com/Agent-Field/cloudsecurity-af",
+		Language:    "python",
+	},
+}
+
+// NewCatalogCommand builds `af catalog` — the browse step of the golden path,
+// letting a harness discover installable nodes before `af install`.
+func NewCatalogCommand() *cobra.Command {
+	var outputFormat string
+	cmd := &cobra.Command{
+		Use:   "catalog",
+		Short: "Browse installable AgentField agent nodes",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return runCatalog(os.Stdout, autoOutputFormat(outputFormat, isOutputTerminal()))
+		},
+		SilenceUsage: true,
+	}
+	cmd.Flags().StringVarP(&outputFormat, "output", "o", "", "Output format: pretty, json, yaml")
+	return cmd
+}
+
+func runCatalog(stdout io.Writer, format string) error {
+	switch format {
+	case "json", "yaml":
+		return writeValue(stdout, nodeCatalog, format)
+	case "pretty":
+		renderNodeCatalog(stdout)
+		return nil
+	default:
+		return cliExitError{Code: 2, Err: fmt.Errorf("output format must be pretty, json, or yaml")}
+	}
+}
+
+func renderNodeCatalog(stdout io.Writer) {
+	rows := make([][]string, 0, len(nodeCatalog))
+	for _, n := range nodeCatalog {
+		rows = append(rows, []string{n.Name, n.Language, n.Description, n.Source})
+	}
+	_, _ = fmt.Fprintln(stdout, ui.Table(
+		fmt.Sprintf("Installable agent nodes (%d)", len(rows)),
+		[]string{"NODE", "LANG", "DESCRIPTION", "SOURCE"},
+		rows,
+	))
+	_, _ = fmt.Fprintln(stdout)
+	_, _ = fmt.Fprintln(stdout, ui.Muted("Install one with:  af install <source>"))
+}

control-plane/internal/cli/catalog_test.go

@@ -0,0 +1,49 @@
+package cli
+
+import (
+	"bytes"
+	"encoding/json"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestRunCatalogJSON(t *testing.T) {
+	var stdout bytes.Buffer
+	require.NoError(t, runCatalog(&stdout, "json"))
+
+	var entries []map[string]interface{}
+	require.NoError(t, json.Unmarshal(stdout.Bytes(), &entries))
+	require.GreaterOrEqual(t, len(entries), 5, "catalog must list at least five installable nodes")
+
+	for _, e := range entries {
+		require.NotEmpty(t, e["name"], "entry missing name: %v", e)
+		require.NotEmpty(t, e["description"], "entry %v missing description", e["name"])
+		require.NotEmpty(t, e["source"], "entry %v missing source", e["name"])
+	}
+}
+
+func TestRunCatalogPrettyEndsWithInstallHint(t *testing.T) {
+	var stdout bytes.Buffer
+	require.NoError(t, runCatalog(&stdout, "pretty"))
+	out := stdout.String()
+	require.Contains(t, out, "af install <source>")
+	require.Contains(t, out, "swe-planner")
+}
+
+func TestRunCatalogRejectsUnknownFormat(t *testing.T) {
+	var stdout bytes.Buffer
+	err := runCatalog(&stdout, "csv")
+	require.Equal(t, 2, ExitCode(err))
+}
+
+func TestNewCatalogCommandExecute(t *testing.T) {
+	cmd := NewCatalogCommand()
+	cmd.SetArgs([]string{"-o", "json"})
+	out := captureOutput(t, func() {
+		require.NoError(t, cmd.Execute())
+	})
+	var entries []map[string]interface{}
+	require.NoError(t, json.Unmarshal([]byte(out), &entries))
+	require.GreaterOrEqual(t, len(entries), 5)
+}