From bc067249e815ed86b34829300d9e9ca3fabd8689 Mon Sep 17 00:00:00 2001 From: "Asim A." Date: Fri, 13 Nov 2026 09:35:54 +0000 Subject: [PATCH 1/2] Remove standalone flow and unused Kubernetes deploy packages --- CHANGELOG.md | 6 +- CLAUDE.md | 1 - CODEX.md | 3 +- Makefile | 23 +- agent/agent_test.go | 9 +- agent/approval_test.go | 11 +- agent/checkpoint_test.go | 55 +- agent/otel_test.go | 3 +- agent/resilience_test.go | 5 +- agent/run/run_test.go | 4 +- agent/run_errors_test.go | 9 +- agent/stream_test.go | 3 +- agent/transient_resume_test.go | 3 +- cmd/micro/README.md | 14 - cmd/micro/cli/agent/agent_test.go | 6 +- cmd/micro/cli/cli.go | 14 +- cmd/micro/examples_wayfinding_test.go | 2 +- cmd/micro/flow/flow.go | 350 -------- cmd/micro/flow/flow_test.go | 156 ---- cmd/micro/inspect/inspect.go | 163 +--- cmd/micro/inspect/inspect_test.go | 72 +- cmd/micro/main.go | 1 - cmd/micro/zero_to_hero_cli_test.go | 12 +- deploy/kubernetes/README.md | 68 -- deploy/kubernetes/config/crd/agent.yaml | 53 -- deploy/kubernetes/config/crd/flow.yaml | 53 -- deploy/kubernetes/config/crd/service.yaml | 53 -- deploy/kubernetes/controller.go | 135 --- deploy/kubernetes/controller_test.go | 151 ---- deploy/kubernetes/doc.go | 8 - deploy/kubernetes/kubernetes_test.go | 87 -- deploy/kubernetes/manifests.go | 32 - deploy/kubernetes/reconcile.go | 110 --- deploy/kubernetes/reconcile_test.go | 88 -- deploy/kubernetes/types.go | 154 ---- examples/INDEX.md | 7 +- examples/README.md | 26 +- examples/agent-durable/README.md | 35 +- examples/flow-durable/README.md | 73 -- examples/flow-durable/main.go | 114 --- examples/flow-loop/main.go | 71 -- examples/support/README.md | 31 +- examples/support/main.go | 53 +- examples/support/main_test.go | 11 +- flow/analyze.go | 212 ----- flow/analyze_test.go | 89 -- flow/dispatch_test.go | 176 ---- flow/environment_test.go | 43 - flow/example_verify_test.go | 45 - flow/flow.go | 360 -------- flow/flow_test.go | 131 --- flow/loop.go | 151 ---- flow/loop_test.go | 91 -- flow/options.go | 156 ---- flow/otel.go | 117 --- flow/otel_test.go | 102 --- flow/record.go | 29 - flow/record_test.go | 53 -- flow/registry_test.go | 65 -- flow/schedule.go | 60 -- flow/steps.go | 658 -------------- flow/steps_test.go | 674 --------------- flow/verification_test.go | 100 --- flow/verify.go | 191 ---- flow/verify_test.go | 96 -- internal/docs/AGENT_CONFORMANCE.md | 2 +- internal/docs/AGENT_DESIGN.md | 10 +- internal/docs/DURABLE_EXECUTION_DESIGN.md | 320 ------- internal/docs/THESIS.md | 137 +-- internal/harness/agent-flow/main.go | 330 ------- internal/harness/agent-flow/main_test.go | 211 ----- internal/harness/composition/README.md | 24 - internal/harness/composition/main.go | 245 ------ internal/harness/install-smoke/run.sh | 1 - internal/harness/plan-delegate/main.go | 776 ----------------- internal/harness/plan-delegate/main_test.go | 818 ------------------ .../harness/provider-conformance/README.md | 10 +- internal/harness/provider-conformance/main.go | 5 +- .../harness/provider-conformance/main_test.go | 12 +- internal/harness/recovery/main.go | 245 ------ internal/harness/universe/main.go | 601 ------------- internal/harness/universe/main_test.go | 300 ------- internal/harness/zero-to-hero-ci/docs_test.go | 26 +- internal/harness/zero-to-hero-ci/run.sh | 2 - internal/test/developer_journey_test.go | 46 - internal/website/_data/navigation.yml | 4 - .../blog/news/agents-across-frameworks-a2a.md | 3 + .../index.md | 3 + .../news/building-a-support-agent-in-go.md | 3 + .../content/en/blog/news/durable-workflows.md | 5 +- .../index.md | 3 + ...ing-a-framework-for-agentic-development.md | 3 + ...ro-joins-openai-s-codex-for-open-source.md | 4 +- .../blog/news/introducing-micro-newagent.md | 3 + .../micro-chat-talk-to-your-services/index.md | 3 + .../news/not-everything-should-be-an-agent.md | 5 +- ...es-why-go-micro-was-always-ready-for-ai.md | 3 + .../blog/news/when-the-event-is-the-prompt.md | 5 +- internal/website/content/en/docs/agents.md | 1 - .../content/en/docs/ai-integration/index.md | 28 +- .../content/en/docs/architecture/index.md | 35 +- .../content/en/docs/examples/_index.md | 11 +- .../content/en/docs/getting-started/index.md | 3 +- .../content/en/docs/guides/a2a-protocol.md | 27 +- .../en/docs/guides/agent-guardrails.md | 1 - .../content/en/docs/guides/agent-harness.md | 25 +- .../content/en/docs/guides/agent-loops.md | 116 --- .../en/docs/guides/agent-run-records.md | 18 +- .../en/docs/guides/agents-and-workflows.md | 199 ----- .../content/en/docs/guides/comparison.md | 18 +- .../en/docs/guides/debugging-agents.md | 32 +- .../content/en/docs/guides/durability.md | 131 +-- .../en/docs/guides/flow-run-records.md | 61 -- .../en/docs/guides/install-troubleshooting.md | 2 +- .../content/en/docs/guides/micro-loop.md | 2 +- .../en/docs/guides/migration/v5-to-v6.md | 20 +- .../en/docs/guides/no-secret-first-agent.md | 9 +- .../content/en/docs/guides/plan-delegate.md | 2 +- .../en/docs/guides/provider-conformance.md | 7 +- .../content/en/docs/guides/x402-payments.md | 1 - .../en/docs/guides/your-first-agent.md | 27 +- .../content/en/docs/guides/zero-to-hero.md | 38 +- .../content/en/docs/interactive-agent.md | 5 +- .../en/docs/project/execution-contract.md | 94 -- .../website/content/en/docs/quickstart.md | 1 - internal/website/content/en/docs/reference.md | 1 - internal/website/content/en/docs/roadmap.md | 21 +- internal/website/content/en/docs/v7.md | 160 +--- internal/website/content/en/docs/workflows.md | 70 -- internal/website/data/docs.yaml | 2 - internal/website/data/vanity.yaml | 15 - micro.go | 115 +-- 132 files changed, 267 insertions(+), 11136 deletions(-) delete mode 100644 cmd/micro/flow/flow.go delete mode 100644 cmd/micro/flow/flow_test.go delete mode 100644 deploy/kubernetes/README.md delete mode 100644 deploy/kubernetes/config/crd/agent.yaml delete mode 100644 deploy/kubernetes/config/crd/flow.yaml delete mode 100644 deploy/kubernetes/config/crd/service.yaml delete mode 100644 deploy/kubernetes/controller.go delete mode 100644 deploy/kubernetes/controller_test.go delete mode 100644 deploy/kubernetes/doc.go delete mode 100644 deploy/kubernetes/kubernetes_test.go delete mode 100644 deploy/kubernetes/manifests.go delete mode 100644 deploy/kubernetes/reconcile.go delete mode 100644 deploy/kubernetes/reconcile_test.go delete mode 100644 deploy/kubernetes/types.go delete mode 100644 examples/flow-durable/README.md delete mode 100644 examples/flow-durable/main.go delete mode 100644 examples/flow-loop/main.go delete mode 100644 flow/analyze.go delete mode 100644 flow/analyze_test.go delete mode 100644 flow/dispatch_test.go delete mode 100644 flow/environment_test.go delete mode 100644 flow/example_verify_test.go delete mode 100644 flow/flow.go delete mode 100644 flow/flow_test.go delete mode 100644 flow/loop.go delete mode 100644 flow/loop_test.go delete mode 100644 flow/options.go delete mode 100644 flow/otel.go delete mode 100644 flow/otel_test.go delete mode 100644 flow/record.go delete mode 100644 flow/record_test.go delete mode 100644 flow/registry_test.go delete mode 100644 flow/schedule.go delete mode 100644 flow/steps.go delete mode 100644 flow/steps_test.go delete mode 100644 flow/verification_test.go delete mode 100644 flow/verify.go delete mode 100644 flow/verify_test.go delete mode 100644 internal/docs/DURABLE_EXECUTION_DESIGN.md delete mode 100644 internal/harness/agent-flow/main.go delete mode 100644 internal/harness/agent-flow/main_test.go delete mode 100644 internal/harness/composition/README.md delete mode 100644 internal/harness/composition/main.go delete mode 100644 internal/harness/plan-delegate/main.go delete mode 100644 internal/harness/plan-delegate/main_test.go delete mode 100644 internal/harness/recovery/main.go delete mode 100644 internal/harness/universe/main.go delete mode 100644 internal/harness/universe/main_test.go delete mode 100644 internal/website/content/en/docs/guides/agent-loops.md delete mode 100644 internal/website/content/en/docs/guides/agents-and-workflows.md delete mode 100644 internal/website/content/en/docs/guides/flow-run-records.md delete mode 100644 internal/website/content/en/docs/project/execution-contract.md delete mode 100644 internal/website/content/en/docs/workflows.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 3ede960549..ac5e969a73 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,10 @@ # Changelog +## Unreleased: services and agents cleanup + +- Removed the `flow` package, `micro.NewFlow` / `Flow*` helpers, flow CLI commands, and unused top-level Kubernetes deployment prototype. +- Agent checkpoints and recovery remain supported through `agent` and `agent/run`. + All notable changes to Go Micro are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/) and versions @@ -80,7 +85,6 @@ below is kept current between tags and rolled into the next version when it ship ### Added - **A2A inbound AP2 mandate verification (opt-in)** — set `Options.AP2PublicKey` (or `a2a.WithAP2PublicKey` for embedded handlers) and the gateway verifies AP2 payment/checkout mandates carried on incoming messages — signature and task/context binding — recording the outcome in each task's `ap2Verifications`, with the x402 settlement rail carried through for the paid path. Off by default. (`gateway/a2a/`) - **Flow human-in-the-loop pause/resume** — a flow step can suspend a run for external input with `flow.Await(key, prompt)`: the run checkpoints with status `waiting`, `Flow.Waiting` lists suspended runs, and `Flow.ResumeWith(ctx, runID, input)` injects the input and continues. Recovery skips waiting runs since they need input, not a restart. (`flow/`) -- **Kubernetes reconcile core (alpha)** — `kubernetes.Reconcile(desired, observed)` decides the action needed to converge an `Agent`/`Service`/`Flow` resource toward its Deployment and returns `Ready`/`Error` conditions; dependency-free and unit-testable, on top of the embedded CRD foundation. (`deploy/kubernetes/`) - **In-process "local network" fast-path (opt-in)** — `client.Local()` lets a unary `Call` to a co-located service skip the network transport and dispatch straight to the server's handlers (raw `codec/bytes.Frame` bodies — the shape agent/MCP/flow tool calls use). Benchmark: ~545µs → ~28µs (≈20×) with ~3.6× fewer allocations. `micro.Local()` turns it on service-wide. Off by default. (`client/`, `server/`, `service/`, `internal/network/`) - **gRPC-reflection MCP** — the MCP gateway can expose reflected gRPC services as agent tools. (`gateway/mcp/`) - **x402 buyer example and agent spend observability** — a runnable buyer-agent example, with x402 spend surfaced in run observability. (`examples/`, `agent/`, `wrapper/x402/`) diff --git a/CLAUDE.md b/CLAUDE.md index ea837052ff..e0d85b14fe 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -45,7 +45,6 @@ go-micro/ ├── config/ # Dynamic config (env, file, etcd, NATS) ├── errors/ # Error handling ├── events/ # Event system (NATS JetStream) -├── flow/ # Event-driven LLM orchestration ├── gateway/ │ ├── api/ # REST API gateway │ └── mcp/ # MCP gateway (core AI integration) diff --git a/CODEX.md b/CODEX.md index 3ec4f88dde..0ca44c8d5f 100644 --- a/CODEX.md +++ b/CODEX.md @@ -58,7 +58,7 @@ Go Micro is maintained by two AI tools — **Codex** (you) and **Claude Code** ( - Keep the 0→1 path current: scaffold, run, call, chat, inspect. - Keep the 0→hero example current: a realistic multi-agent system that exercises - agents, services, flows, MCP, A2A, and observability. + agents, services, MCP, A2A, and observability. - Add runnable examples for new primitives before adding broad prose. ### 5. Hardening backlog @@ -122,7 +122,6 @@ make test make harness make lint go run ./examples/hello-world -go run ./internal/harness/universe ``` ### Week 2: choose one roadmap slice diff --git a/Makefile b/Makefile index 743021a24f..b53e476866 100644 --- a/Makefile +++ b/Makefile @@ -6,7 +6,7 @@ LDFLAGS = -X $(GIT_IMPORT).version=$(GIT_TAG) # GORELEASER_DOCKER_IMAGE = ghcr.io/goreleaser/goreleaser-cross:v1.25.7 GORELEASER_DOCKER_IMAGE = ghcr.io/goreleaser/goreleaser:latest -.PHONY: service-smoke chat-smoke test test-race test-coverage harness composition-gate recovery-gate zero-to-hero-transcript inner-loop cli-wayfinding docs-wayfinding install-smoke provider-conformance-mock provider-conformance lint fmt install-tools proto clean help gorelease-dry-run gorelease-dry-run-docker +.PHONY: service-smoke chat-smoke test test-race test-coverage harness zero-to-hero-transcript inner-loop cli-wayfinding docs-wayfinding install-smoke provider-conformance-mock provider-conformance lint fmt install-tools proto clean help gorelease-dry-run gorelease-dry-run-docker # Default target help: @@ -17,8 +17,6 @@ help: @echo " make test-coverage - Run tests with coverage" @echo " make lint - Run linter" @echo " make harness - Run deterministic getting-started and end-to-end harnesses" - @echo " make composition-gate - Run restartable service-agent-flow acceptance fixture" - @echo " make recovery-gate - Run restart and failure-injection acceptance fixture" @echo " make chat-smoke - Exercise chat setup, tools, approvals, and recovery in a terminal" @echo " make zero-to-hero-transcript - Verify the ordered 0→hero lifecycle transcript" @echo " make inner-loop - Verify scaffold → run/chat/inspect → deploy dry-run contract" @@ -50,32 +48,17 @@ test-coverage: @echo "Coverage report: coverage.html" # Run the documented getting-started contracts plus the deterministic -# services → agents → workflows harnesses (mock LLM — no API key). +# services → agents harnesses (mock LLM — no API key). # This mirrors the default CI path so local dogfooding catches scaffold, # run/chat/inspect, and 0→hero regressions before a PR is opened. harness: $(MAKE) cli-wayfinding $(MAKE) inner-loop $(MAKE) zero-to-hero-transcript - go run ./internal/harness/agent-flow - $(MAKE) composition-gate - $(MAKE) recovery-gate $(MAKE) provider-conformance-mock -# Provider-free complete-composition contract: real RPC, bounded agent tool -# work, durable approval, replacement flow hosts, and an idempotent final effect. -composition-gate: - go run -race ./internal/harness/composition - -# Provider-free v7 recovery contract: replace a flow host while retaining its -# checkpoint, preserve waiting work and lineage, inject an ambiguous effect and -# concurrent duplicate resumes, enforce idempotent effects, and record exhausted -# retry budgets as failures. -recovery-gate: - go run ./internal/harness/recovery - # Verify the maintained 0→hero transcript in the same order documented for new -# developers: scaffold → run/chat/inspect → support-agent chat → flow history → +# developers: scaffold → run/chat/inspect → support-agent chat → # deploy dry-run. This is the focused CI contract for the full lifecycle path. zero-to-hero-transcript: ./internal/harness/zero-to-hero-ci/run.sh diff --git a/agent/agent_test.go b/agent/agent_test.go index 5e85549579..e7acc3ad21 100644 --- a/agent/agent_test.go +++ b/agent/agent_test.go @@ -5,7 +5,6 @@ import ( "testing" pb "go-micro.dev/v6/agent/proto" - "go-micro.dev/v6/flow" "go-micro.dev/v6/metadata" "go-micro.dev/v6/model" "go-micro.dev/v6/store" @@ -155,12 +154,12 @@ func TestChatPreservesTransportedFlowLineageThroughToolExecution(t *testing.T) { } func TestResumeRestoresPersistedFlowLineage(t *testing.T) { - cp := flow.StoreCheckpoint(store.NewMemoryStore(), "ops-agent") - run := flow.Run{ + cp := StoreCheckpoint(store.NewMemoryStore(), "ops-agent") + run := Run{ ID: "agent-run-resume", ParentID: "flow-run-resume", Flow: "ops-agent", OriginFlow: "daily-ops", OriginStep: "summarize", Dispatch: "schedule", Trigger: "daily-review", - State: flow.State{Stage: "ask", Data: []byte("resume review")}, - Steps: []flow.StepRecord{{Name: "ask", Status: "failed"}}, Status: "failed", + State: State{Stage: "ask", Data: []byte("resume review")}, + Steps: []StepRecord{{Name: "ask", Status: "failed"}}, Status: "failed", } if err := cp.Save(context.Background(), run); err != nil { t.Fatal(err) diff --git a/agent/approval_test.go b/agent/approval_test.go index c218e9a4bf..7e80b64182 100644 --- a/agent/approval_test.go +++ b/agent/approval_test.go @@ -6,7 +6,6 @@ import ( "strings" "testing" - "go-micro.dev/v6/flow" "go-micro.dev/v6/model" "go-micro.dev/v6/store" ) @@ -21,7 +20,7 @@ func TestDurableApprovalExecutesSavedCallAfterRestart(t *testing.T) { } t.Run(name, func(t *testing.T) { st := store.NewMemoryStore() - cp := flow.StoreCheckpoint(st, "approval") + cp := StoreCheckpoint(st, "approval") toolCalls, modelCalls, approvalCalls := 0, 0, 0 ctx := context.WithValue(context.Background(), approvalIdentityKey{}, "reviewer") makeAgent := func() *agentImpl { @@ -122,11 +121,11 @@ func TestDurableApprovalExecutesSavedCallAfterRestart(t *testing.T) { } type failingApprovalCheckpoint struct { - flow.Checkpoint + Checkpoint saves int } -func (cp *failingApprovalCheckpoint) Save(ctx context.Context, run flow.Run) error { +func (cp *failingApprovalCheckpoint) Save(ctx context.Context, run Run) error { cp.saves++ if cp.saves == 2 { return errors.New("approval storage unavailable") @@ -134,7 +133,7 @@ func (cp *failingApprovalCheckpoint) Save(ctx context.Context, run flow.Run) err return cp.Checkpoint.Save(ctx, run) } func TestDurableApprovalFailsClosedOnSaveError(t *testing.T) { - cp := &failingApprovalCheckpoint{Checkpoint: flow.StoreCheckpoint(store.NewMemoryStore(), "failed-approval")} + cp := &failingApprovalCheckpoint{Checkpoint: StoreCheckpoint(store.NewMemoryStore(), "failed-approval")} executed := 0 a := newTestAgent(Name("save-failure"), WithCheckpoint(cp), WithApproval(func(context.Context, model.ToolCall) (ApprovalDecision, error) { return ApprovalDecision{Status: ApprovalPending, ID: "review"}, nil @@ -154,7 +153,7 @@ func TestDurableApprovalFailsClosedOnSaveError(t *testing.T) { } func TestDurableApprovalReturnsPauseAfterProviderCancellation(t *testing.T) { - cp := flow.StoreCheckpoint(store.NewMemoryStore(), "canceled-approval") + cp := StoreCheckpoint(store.NewMemoryStore(), "canceled-approval") ctx, cancel := context.WithCancel(context.Background()) defer cancel() a := newTestAgent(Name("cancel-after-save"), WithCheckpoint(cp), WithApproval(func(context.Context, model.ToolCall) (ApprovalDecision, error) { diff --git a/agent/checkpoint_test.go b/agent/checkpoint_test.go index d432ae8f3e..6b62018b7b 100644 --- a/agent/checkpoint_test.go +++ b/agent/checkpoint_test.go @@ -9,7 +9,6 @@ import ( "go-micro.dev/v6/client" codecBytes "go-micro.dev/v6/codec/bytes" - "go-micro.dev/v6/flow" "go-micro.dev/v6/model" "go-micro.dev/v6/registry" "go-micro.dev/v6/store" @@ -17,7 +16,7 @@ import ( func TestResumeCompletedCheckpointDoesNotReplayModel(t *testing.T) { ctx := context.Background() - cp := flow.StoreCheckpoint(store.NewMemoryStore(), "durable-agent") + cp := StoreCheckpoint(store.NewMemoryStore(), "durable-agent") calls := 0 fakeGen = func(ctx context.Context, opts model.Options, req *model.Request) (*model.Response, error) { calls++ @@ -59,7 +58,7 @@ func TestResumeCompletedCheckpointDoesNotReplayModel(t *testing.T) { func TestResumeFailedCheckpointDoesNotReplayCompletedTool(t *testing.T) { ctx := context.Background() - cp := flow.StoreCheckpoint(store.NewMemoryStore(), "tool-resume-agent") + cp := StoreCheckpoint(store.NewMemoryStore(), "tool-resume-agent") toolRuns := 0 first := true fakeGen = func(ctx context.Context, opts model.Options, req *model.Request) (*model.Response, error) { @@ -117,7 +116,7 @@ func TestResumeFailedCheckpointDoesNotReplayCompletedTool(t *testing.T) { func TestCheckpointSkipsDuplicateToolWithinAsk(t *testing.T) { ctx := context.Background() - cp := flow.StoreCheckpoint(store.NewMemoryStore(), "tool-dedupe-agent") + cp := StoreCheckpoint(store.NewMemoryStore(), "tool-dedupe-agent") toolRuns := 0 fakeGen = func(ctx context.Context, opts model.Options, req *model.Request) (*model.Response, error) { if opts.ToolHandler == nil { @@ -156,12 +155,12 @@ func TestCheckpointSkipsDuplicateToolWithinAsk(t *testing.T) { func TestCheckpointToolWrapSurvivesClearedCurrentRun(t *testing.T) { ctx := context.Background() - cp := flow.StoreCheckpoint(store.NewMemoryStore(), "tool-cleared-run-agent") - run := flow.Run{ + cp := StoreCheckpoint(store.NewMemoryStore(), "tool-cleared-run-agent") + run := Run{ ID: "run-1", Flow: "tool-cleared-run-agent", Status: "running", - Steps: []flow.StepRecord{{Name: agentAskStep, Status: "in_progress"}}, + Steps: []StepRecord{{Name: agentAskStep, Status: "in_progress"}}, } a := &agentImpl{ opts: newOptions(Name("tool-cleared-run-agent"), WithCheckpoint(cp)), @@ -195,7 +194,7 @@ func TestCheckpointToolWrapSurvivesClearedCurrentRun(t *testing.T) { func TestCheckpointContinuesRunWithUnfinishedPlanStep(t *testing.T) { ctx := context.Background() - cp := flow.StoreCheckpoint(store.NewMemoryStore(), "unfinished-plan-agent") + cp := StoreCheckpoint(store.NewMemoryStore(), "unfinished-plan-agent") reg := registry.NewMemoryRegistry() if err := reg.Register(®istry.Service{ @@ -270,7 +269,7 @@ func TestCheckpointContinuesRunWithUnfinishedPlanStep(t *testing.T) { func TestCheckpointContinuesRunThroughSeveralSingleStepTurns(t *testing.T) { ctx := context.Background() - cp := flow.StoreCheckpoint(store.NewMemoryStore(), "single-step-plan-agent") + cp := StoreCheckpoint(store.NewMemoryStore(), "single-step-plan-agent") completed := []string{} modelCalls := 0 @@ -337,7 +336,7 @@ func TestCheckpointContinuesRunThroughSeveralSingleStepTurns(t *testing.T) { func TestResumeFailedCheckpointAfterFreshAgentRestart(t *testing.T) { ctx := context.Background() st := store.NewMemoryStore() - cp := flow.StoreCheckpoint(st, "restart-resume-agent") + cp := StoreCheckpoint(st, "restart-resume-agent") toolRuns := 0 modelCalls := 0 failFirst := true @@ -448,7 +447,7 @@ func TestResumeFailedCheckpointAfterFreshAgentRestart(t *testing.T) { func TestResumePendingAfterFreshAgentRestartDoesNotReplayCompletedTool(t *testing.T) { ctx := context.Background() st := store.NewMemoryStore() - cp := flow.StoreCheckpoint(st, "startup-resume-agent") + cp := StoreCheckpoint(st, "startup-resume-agent") toolRuns := 0 failFirst := true fakeGen = func(ctx context.Context, opts model.Options, req *model.Request) (*model.Response, error) { @@ -513,7 +512,7 @@ func TestResumePendingAfterFreshAgentRestartDoesNotReplayCompletedTool(t *testin func TestResumeFailedCheckpointDoesNotDuplicateCompactedMemory(t *testing.T) { ctx := context.Background() st := store.NewMemoryStore() - cp := flow.StoreCheckpoint(st, "memory-resume-agent") + cp := StoreCheckpoint(st, "memory-resume-agent") failRetry := true var sawRecall bool fakeGen = func(ctx context.Context, opts model.Options, req *model.Request) (*model.Response, error) { @@ -578,12 +577,12 @@ func countMemoryContent(messages []model.Message, needle string) int { func TestResumePendingResumesOldestAgentRunsUntilFailure(t *testing.T) { ctx := context.Background() - cp := flow.StoreCheckpoint(store.NewMemoryStore(), "resume-pending-agent") + cp := StoreCheckpoint(store.NewMemoryStore(), "resume-pending-agent") base := time.Date(2026, 7, 7, 12, 0, 0, 0, time.UTC) - for _, run := range []flow.Run{ - {ID: "run-ok", Flow: "resume-pending-agent", Status: "failed", State: flow.State{Stage: agentAskStep, Data: []byte("ok")}, Started: base}, - {ID: "run-blocked", Flow: "resume-pending-agent", Status: "failed", State: flow.State{Stage: agentAskStep, Data: []byte("block")}, Started: base.Add(time.Minute)}, - {ID: "run-later", Flow: "resume-pending-agent", Status: "failed", State: flow.State{Stage: agentAskStep, Data: []byte("later")}, Started: base.Add(2 * time.Minute)}, + for _, run := range []Run{ + {ID: "run-ok", Flow: "resume-pending-agent", Status: "failed", State: State{Stage: agentAskStep, Data: []byte("ok")}, Started: base}, + {ID: "run-blocked", Flow: "resume-pending-agent", Status: "failed", State: State{Stage: agentAskStep, Data: []byte("block")}, Started: base.Add(time.Minute)}, + {ID: "run-later", Flow: "resume-pending-agent", Status: "failed", State: State{Stage: agentAskStep, Data: []byte("later")}, Started: base.Add(2 * time.Minute)}, } { if err := cp.Save(ctx, run); err != nil { t.Fatalf("Save(%s): %v", run.ID, err) @@ -623,8 +622,8 @@ func TestResumePendingResumesOldestAgentRunsUntilFailure(t *testing.T) { func TestPendingReturnsUnfinishedAgentRuns(t *testing.T) { ctx := context.Background() - cp := flow.StoreCheckpoint(store.NewMemoryStore(), "pending-agent") - run := flow.Run{ID: "run-1", Flow: "pending-agent", Status: "failed", State: flow.State{Stage: agentAskStep, Data: []byte("retry me")}} + cp := StoreCheckpoint(store.NewMemoryStore(), "pending-agent") + run := Run{ID: "run-1", Flow: "pending-agent", Status: "failed", State: State{Stage: agentAskStep, Data: []byte("retry me")}} if err := cp.Save(ctx, run); err != nil { t.Fatalf("Save: %v", err) } @@ -640,12 +639,12 @@ func TestPendingReturnsUnfinishedAgentRuns(t *testing.T) { func TestPendingSkipsTerminalCanceledAndExpiredAgentRuns(t *testing.T) { ctx := context.Background() - cp := flow.StoreCheckpoint(store.NewMemoryStore(), "terminal-agent") - for _, run := range []flow.Run{ - {ID: "active", Flow: "terminal-agent", Status: "failed", State: flow.State{Stage: agentAskStep, Data: []byte("retry me")}}, - {ID: "done", Flow: "terminal-agent", Status: "done", State: flow.State{Stage: agentAskStep, Data: []byte("done")}}, - {ID: "canceled", Flow: "terminal-agent", Status: "canceled", State: flow.State{Stage: agentAskStep, Data: []byte("canceled")}}, - {ID: "expired", Flow: "terminal-agent", Status: "expired", State: flow.State{Stage: agentAskStep, Data: []byte("expired")}}, + cp := StoreCheckpoint(store.NewMemoryStore(), "terminal-agent") + for _, run := range []Run{ + {ID: "active", Flow: "terminal-agent", Status: "failed", State: State{Stage: agentAskStep, Data: []byte("retry me")}}, + {ID: "done", Flow: "terminal-agent", Status: "done", State: State{Stage: agentAskStep, Data: []byte("done")}}, + {ID: "canceled", Flow: "terminal-agent", Status: "canceled", State: State{Stage: agentAskStep, Data: []byte("canceled")}}, + {ID: "expired", Flow: "terminal-agent", Status: "expired", State: State{Stage: agentAskStep, Data: []byte("expired")}}, } { if err := cp.Save(ctx, run); err != nil { t.Fatalf("Save(%s): %v", run.ID, err) @@ -669,7 +668,7 @@ func TestPendingSkipsTerminalCanceledAndExpiredAgentRuns(t *testing.T) { func TestHumanInputPauseResumesSameRunWithInput(t *testing.T) { ctx := context.Background() - cp := flow.StoreCheckpoint(store.NewMemoryStore(), "input-agent") + cp := StoreCheckpoint(store.NewMemoryStore(), "input-agent") calls := 0 fakeGen = func(ctx context.Context, opts model.Options, req *model.Request) (*model.Response, error) { calls++ @@ -727,7 +726,7 @@ func TestHumanInputPauseResumesSameRunWithInput(t *testing.T) { func TestHumanInputResumeHonorsCanceledContextAndLeavesRunPending(t *testing.T) { ctx := context.Background() - cp := flow.StoreCheckpoint(store.NewMemoryStore(), "input-cancel-agent") + cp := StoreCheckpoint(store.NewMemoryStore(), "input-cancel-agent") fakeGen = func(ctx context.Context, opts model.Options, req *model.Request) (*model.Response, error) { if opts.ToolHandler != nil { opts.ToolHandler(ctx, model.ToolCall{ID: "input-1", Name: toolHumanInput, Input: map[string]any{"prompt": "Approve deploy?"}}) @@ -772,7 +771,7 @@ func TestHumanInputResumeHonorsCanceledContextAndLeavesRunPending(t *testing.T) func TestApprovalDenialPausesCheckpointedRunAndResumeContinues(t *testing.T) { ctx := context.Background() - cp := flow.StoreCheckpoint(store.NewMemoryStore(), "approval-agent") + cp := StoreCheckpoint(store.NewMemoryStore(), "approval-agent") calls := 0 fakeGen = func(ctx context.Context, opts model.Options, req *model.Request) (*model.Response, error) { calls++ diff --git a/agent/otel_test.go b/agent/otel_test.go index 378cd9986d..f2e4eaf5ec 100644 --- a/agent/otel_test.go +++ b/agent/otel_test.go @@ -10,7 +10,6 @@ import ( "testing" "time" - "go-micro.dev/v6/flow" "go-micro.dev/v6/model" "go-micro.dev/v6/store" "go.opentelemetry.io/otel/attribute" @@ -648,7 +647,7 @@ func TestAgentCheckpointAndResumeTimelineEvents(t *testing.T) { exp := tracetest.NewInMemoryExporter() tp := trace.NewTracerProvider(trace.WithSyncer(exp)) st := store.NewMemoryStore() - cp := flow.StoreCheckpoint(st, "resume-otel-agent") + cp := StoreCheckpoint(st, "resume-otel-agent") first := true fakeGen = func(ctx context.Context, opts model.Options, req *model.Request) (*model.Response, error) { if first { diff --git a/agent/resilience_test.go b/agent/resilience_test.go index ec3f5ec3f8..c5bcf41f5a 100644 --- a/agent/resilience_test.go +++ b/agent/resilience_test.go @@ -7,7 +7,6 @@ import ( "testing" "time" - "go-micro.dev/v6/flow" "go-micro.dev/v6/model" "go-micro.dev/v6/store" ) @@ -85,7 +84,7 @@ func TestAskRetriesTransientErrorsThenSurfacesStructuredError(t *testing.T) { func TestModelRetryDoesNotDuplicateCheckpointedToolSideEffects(t *testing.T) { ctx := context.Background() - cp := flow.StoreCheckpoint(store.NewMemoryStore(), "retry-tool-dedupe-agent") + cp := StoreCheckpoint(store.NewMemoryStore(), "retry-tool-dedupe-agent") attempts := 0 toolRuns := 0 fakeGen = func(ctx context.Context, opts model.Options, req *model.Request) (*model.Response, error) { @@ -302,7 +301,7 @@ func TestAskCheckpointRecordsOperationalFailureStatus(t *testing.T) { for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { - cp := flow.StoreCheckpoint(store.NewMemoryStore(), "terminal-"+strings.ReplaceAll(tt.name, " ", "-")) + cp := StoreCheckpoint(store.NewMemoryStore(), "terminal-"+strings.ReplaceAll(tt.name, " ", "-")) fakeGen = func(ctx context.Context, opts model.Options, req *model.Request) (*model.Response, error) { return nil, tt.err } diff --git a/agent/run/run_test.go b/agent/run/run_test.go index 6cf398fff4..21ed5fc605 100644 --- a/agent/run/run_test.go +++ b/agent/run/run_test.go @@ -5,7 +5,7 @@ import ( "testing" "go-micro.dev/v6/agent" - "go-micro.dev/v6/flow" + "go-micro.dev/v6/agent/run" "go-micro.dev/v6/store" ) @@ -24,7 +24,7 @@ func TestExistingCheckpointRemainsReadable(t *testing.T) { if err := cp.Save(context.Background(), record); err != nil { t.Fatal(err) } - restored, found, err := flow.StoreCheckpoint(st, "assistant").Load(context.Background(), "saved") + restored, found, err := run.StoreCheckpoint(st, "assistant").Load(context.Background(), "saved") if err != nil || !found || restored.Status != "waiting" { t.Fatalf("run=%+v found=%v err=%v", restored, found, err) } diff --git a/agent/run_errors_test.go b/agent/run_errors_test.go index 68dc8c49e2..f83062d062 100644 --- a/agent/run_errors_test.go +++ b/agent/run_errors_test.go @@ -6,17 +6,16 @@ import ( "fmt" "testing" - "go-micro.dev/v6/flow" "go-micro.dev/v6/model" "go-micro.dev/v6/store" ) func TestTypedRunErrors(t *testing.T) { ctx := context.Background() - cp := flow.StoreCheckpoint(store.NewMemoryStore(), "typed-errors") + cp := StoreCheckpoint(store.NewMemoryStore(), "typed-errors") a := newTestAgent(Name("typed-errors"), WithCheckpoint(cp)) for _, status := range []string{"canceled", "expired"} { - if err := cp.Save(ctx, flow.Run{ID: status, Status: status}); err != nil { + if err := cp.Save(ctx, Run{ID: status, Status: status}); err != nil { t.Fatal(err) } _, err := Resume(ctx, a, status) @@ -25,7 +24,7 @@ func TestTypedRunErrors(t *testing.T) { t.Fatalf("unexpected terminal error: %v", err) } } - if err := cp.Save(ctx, flow.Run{ID: "input", Status: "paused", State: flow.State{Stage: agentInputStep}}); err != nil { + if err := cp.Save(ctx, Run{ID: "input", Status: "paused", State: State{Stage: agentInputStep}}); err != nil { t.Fatal(err) } _, err := Resume(ctx, a, "input") @@ -37,7 +36,7 @@ func TestTypedRunErrors(t *testing.T) { func TestTypedMultilinePause(t *testing.T) { ctx := context.Background() - cp := flow.StoreCheckpoint(store.NewMemoryStore(), "typed-pause") + cp := StoreCheckpoint(store.NewMemoryStore(), "typed-pause") reason := "First question?\nSecond question?" fakeGen = func(ctx context.Context, opts model.Options, req *model.Request) (*model.Response, error) { opts.ToolHandler(ctx, model.ToolCall{ID: "ask-human", Name: toolHumanInput, Input: map[string]any{"prompt": reason}}) diff --git a/agent/stream_test.go b/agent/stream_test.go index 8980854370..dd0c0c482d 100644 --- a/agent/stream_test.go +++ b/agent/stream_test.go @@ -7,7 +7,6 @@ import ( "testing" "time" - "go-micro.dev/v6/flow" "go-micro.dev/v6/model" "go-micro.dev/v6/store" ) @@ -198,7 +197,7 @@ func TestAgentStreamCanceledContextSkipsProviderCallAndMemory(t *testing.T) { func TestResumeStreamAskDoesNotReplayCompletedTool(t *testing.T) { ctx := context.Background() - cp := flow.StoreCheckpoint(store.NewStore(), "stream-resume-agent") + cp := StoreCheckpoint(store.NewStore(), "stream-resume-agent") toolRuns := 0 first := true fakeGen = func(ctx context.Context, opts model.Options, req *model.Request) (*model.Response, error) { diff --git a/agent/transient_resume_test.go b/agent/transient_resume_test.go index e38d0b7f4b..fb639b0684 100644 --- a/agent/transient_resume_test.go +++ b/agent/transient_resume_test.go @@ -6,7 +6,6 @@ import ( "io" "testing" - "go-micro.dev/v6/flow" "go-micro.dev/v6/model" "go-micro.dev/v6/store" ) @@ -22,7 +21,7 @@ func TestResumeTransientFailureAfterRestart(t *testing.T) { t.Run(failure.name+"/"+mode, func(t *testing.T) { ctx := context.Background() st := store.NewMemoryStore() - cp := flow.StoreCheckpoint(st, "recovery") + cp := StoreCheckpoint(st, "recovery") modelCalls, toolCalls := 0, 0 fakeGen = func(ctx context.Context, opts model.Options, req *model.Request) (*model.Response, error) { modelCalls++ diff --git a/cmd/micro/README.md b/cmd/micro/README.md index 2e561aaa49..ab557f83a6 100644 --- a/cmd/micro/README.md +++ b/cmd/micro/README.md @@ -535,20 +535,6 @@ Supports: `--provider` (anthropic, openai, gemini, atlascloud, groq, mistral, op Environment variables: `MICRO_AI_PROVIDER`, `MICRO_AI_API_KEY`, or provider-specific keys like `ANTHROPIC_API_KEY`. -### micro flow - -Event-driven LLM orchestration: - -```bash -# Subscribe to events and react -micro flow run --trigger events.user.created \ - --prompt "New user: {{.Data}}. Send welcome email." \ - --provider anthropic - -# One-shot execution -micro flow exec --prompt "List all users" --provider anthropic -``` - ### micro mcp Expose services as MCP tools for AI agents: diff --git a/cmd/micro/cli/agent/agent_test.go b/cmd/micro/cli/agent/agent_test.go index 60ae1f1572..01273167fa 100644 --- a/cmd/micro/cli/agent/agent_test.go +++ b/cmd/micro/cli/agent/agent_test.go @@ -9,7 +9,7 @@ import ( "time" goagent "go-micro.dev/v6/agent" - aiflow "go-micro.dev/v6/flow" + agentrun "go-micro.dev/v6/agent/run" "go-micro.dev/v6/model" "go-micro.dev/v6/store" ) @@ -147,8 +147,8 @@ func TestResumeInputRunCompletesCheckpointAndInspectSummary(t *testing.T) { t.Cleanup(func() { store.DefaultStore = oldStore }) ctx := context.Background() - cp := aiflow.StoreCheckpoint(store.DefaultStore, "runner") - run := aiflow.Run{ID: "run-input", Flow: "runner", Status: "paused", State: aiflow.State{Stage: "input-required"}, Steps: []aiflow.StepRecord{{Name: "ask", Status: "paused", Error: "Which region?"}}} + cp := agentrun.StoreCheckpoint(store.DefaultStore, "runner") + run := agentrun.Run{ID: "run-input", Flow: "runner", Status: "paused", State: agentrun.State{Stage: "input-required"}, Steps: []agentrun.StepRecord{{Name: "ask", Status: "paused", Error: "Which region?"}}} if err := run.State.Set(cliInputPause{OriginalMessage: "deploy", Prompt: "Which region?"}); err != nil { t.Fatalf("set pause: %v", err) } diff --git a/cmd/micro/cli/cli.go b/cmd/micro/cli/cli.go index af30d5a8c8..242716ec7b 100644 --- a/cmd/micro/cli/cli.go +++ b/cmd/micro/cli/cli.go @@ -27,14 +27,14 @@ import ( const zeroToHeroHelp = `0→hero no-secret lifecycle demo Run this from a go-micro repository checkout when you want one command that -proves the maintained services → agents → workflows path without provider keys: +proves the maintained services → agents path without provider keys: ./internal/harness/zero-to-hero-ci/run.sh That script runs the same deterministic path CI uses: - - CLI discovery for scaffold, run, chat, inspect, flow runs, and deploy dry-run + - CLI discovery for scaffold, run, chat, inspect and deploy dry-run - the smallest first-agent example - - the support-desk reference app with services, an agent, a flow, and an approval gate + - the support-desk reference app with services, an agent and an approval gate - plan/delegate and universe harnesses with only the model mocked If you only want the runnable examples first: @@ -59,9 +59,9 @@ examples map, open examples/INDEX.md: go test ./internal/harness/zero-to-hero-ci -run TestNoSecretFirstAgentTranscript -count=1 Exercises service tools, mock-model chat, and inspectable run history. - 3. Full services → agents → workflows reference app + 3. Full services → agents reference app go run ./examples/support - Shows the support desk service, agent, workflow, and approval gate together. + Shows the support desk service, agent and approval gate together. Then continue the same path with the installed CLI: micro agent demo @@ -191,7 +191,7 @@ func init() { Name: "examples", Usage: "Show provider-free first-agent example paths", Description: `Print the maintained no-secret examples for the services → agents → -workflows on-ramp: first-agent, transcript, support app, and matching guides.`, +agents on-ramp: first-agent, transcript, support app, and matching guides.`, Action: func(ctx *cli.Context) error { fmt.Fprintln(ctx.App.Writer, examplesWayfinding) return nil @@ -200,7 +200,7 @@ workflows on-ramp: first-agent, transcript, support app, and matching guides.`, { Name: "zero-to-hero", Usage: "Show the no-secret 0→hero lifecycle demo command", - Description: `Print the maintained provider-free services → agents → workflows + Description: `Print the maintained provider-free services → agents lifecycle command and the smaller runnable examples it covers.`, Aliases: []string{"hero"}, Action: func(ctx *cli.Context) error { diff --git a/cmd/micro/examples_wayfinding_test.go b/cmd/micro/examples_wayfinding_test.go index f131b69f6d..3c4f3ae5bb 100644 --- a/cmd/micro/examples_wayfinding_test.go +++ b/cmd/micro/examples_wayfinding_test.go @@ -40,7 +40,7 @@ func TestExamplesWayfindingIndexStaysLinked(t *testing.T) { }, { file: "examples/INDEX.md", - want: []string{"go run ./examples/first-agent", "go run ./examples/support", "mcp/hello", "mcp/workflow", "flow-durable", "micro examples"}, + want: []string{"go run ./examples/first-agent", "go run ./examples/support", "mcp/hello", "mcp/workflow", "micro examples"}, }, } { for _, want := range check.want { diff --git a/cmd/micro/flow/flow.go b/cmd/micro/flow/flow.go deleted file mode 100644 index a6fd26ed85..0000000000 --- a/cmd/micro/flow/flow.go +++ /dev/null @@ -1,350 +0,0 @@ -// Package flow implements the 'micro flow' command for event-driven -// LLM orchestration of microservices. -package flow - -import ( - "context" - "encoding/json" - "fmt" - "io" - "os" - "os/signal" - "sort" - "syscall" - - "github.com/urfave/cli/v2" - "go-micro.dev/v6/broker" - "go-micro.dev/v6/client" - "go-micro.dev/v6/cmd" - aiflow "go-micro.dev/v6/flow" - "go-micro.dev/v6/registry" -) - -func init() { - cmd.Register(&cli.Command{ - Name: "flow", - Usage: "Event-driven LLM orchestration", - Description: `Run flows that subscribe to broker events and use an LLM to -orchestrate service calls in response. - -This command runs a single-step flow from flags. For ordered, durable -multi-step workflows (checkpointed steps that resume after a crash), -define the flow in code with micro.FlowSteps and a Checkpoint — see -examples/flow-durable. - -Examples: - # Run a flow that reacts to user creation events - micro flow run --trigger events.user.created \ - --prompt "New user: {{.Data}}. Send welcome email." \ - --provider anthropic - - # Run a one-shot flow with inline data - micro flow exec --prompt "List all users and count them" \ - --provider anthropic - - # Run a flow with a specific model - micro flow exec --prompt "Create a test user" \ - --provider atlascloud --model deepseek-ai/DeepSeek-V3-0324`, - Subcommands: []*cli.Command{ - { - Name: "run", - Usage: "Start a flow that listens to broker events", - Flags: flowFlags(), - Action: func(c *cli.Context) error { - return runFlow(c, false) - }, - }, - { - Name: "exec", - Usage: "Execute a flow once with inline data", - Flags: append(flowFlags(), &cli.StringFlag{ - Name: "data", - Usage: "Input data for the flow (default: reads from --prompt only)", - }), - Action: func(c *cli.Context) error { - return runFlow(c, true) - }, - }, - { - Name: "list", - Usage: "List running flows (from the registry, type=flow)", - Action: listFlows, - }, - { - Name: "runs", - Usage: "Show durable run history for a flow", - ArgsUsage: "[name]", - Flags: []cli.Flag{ - &cli.BoolFlag{Name: "json", Usage: "Print durable run history as JSON for automation"}, - &cli.BoolFlag{Name: "pending", Usage: "Only show runs that have not completed"}, - &cli.StringFlag{Name: "status", Usage: "Only show runs with this status (running, done, failed)"}, - &cli.IntFlag{Name: "limit", Usage: "Show the most recently updated N runs"}, - &cli.StringFlag{Name: "stage", Usage: "Only show runs currently checkpointed at this stage"}, - }, - Action: flowRuns, - }, - }, - }) -} - -// listFlows shows flows currently registered in the registry — the live -// view, mirroring `micro agent list`. -func listFlows(c *cli.Context) error { - svcs, err := registry.ListServices() - if err != nil { - return err - } - found := false - for _, svc := range svcs { - records, err := registry.GetService(svc.Name) - if err != nil || len(records) == 0 { - continue - } - meta := records[0].Metadata - isFlow := meta != nil && meta["type"] == "flow" - if !isFlow && len(records[0].Nodes) > 0 { - nm := records[0].Nodes[0].Metadata - isFlow = nm != nil && nm["type"] == "flow" - } - if !isFlow { - continue - } - found = true - trigger := "" - if meta != nil { - trigger = meta["trigger"] - } - fmt.Printf(" \033[36m⚡\033[0m %-20s trigger: %s\n", svc.Name, trigger) - } - if !found { - fmt.Println(" No running flows.") - fmt.Println(" Run one with: micro flow run --trigger --prompt <...>") - } - return nil -} - -// flowRuns shows a flow's durable run history from the store — the -// historic view, available whether or not the flow is currently running. -func flowRuns(c *cli.Context) error { - name := c.Args().First() - if name == "" { - return fmt.Errorf("flow name required: micro flow runs ") - } - runs, err := aiflow.StoreCheckpoint(nil, name).List(context.Background()) - if err != nil { - return err - } - opts, err := validateFlowRunOptions(flowRunOptions{Pending: c.Bool("pending"), Status: c.String("status"), Stage: c.String("stage"), Limit: c.Int("limit")}) - if err != nil { - return err - } - runs = filterFlowRuns(runs, opts) - if len(runs) == 0 { - if c.Bool("pending") { - fmt.Printf(" No pending runs recorded for flow %q.\n", name) - return nil - } - fmt.Printf(" No runs recorded for flow %q.\n", name) - return nil - } - return writeFlowRuns(os.Stdout, runs, c.Bool("json")) -} - -type flowRunOptions struct { - Pending bool - Status string - Stage string - Limit int -} - -func validateFlowRunOptions(opts flowRunOptions) (flowRunOptions, error) { - switch opts.Status { - case "", "running", "done", "failed": - default: - return opts, fmt.Errorf("invalid run status %q: expected running, done, or failed", opts.Status) - } - if opts.Limit < 0 { - return opts, fmt.Errorf("invalid limit %d: expected a non-negative value", opts.Limit) - } - return opts, nil -} - -func filterFlowRuns(runs []aiflow.Run, opts flowRunOptions) []aiflow.Run { - if len(runs) == 0 { - return nil - } - filtered := make([]aiflow.Run, 0, len(runs)) - for _, run := range runs { - if opts.Pending && run.Status == "done" { - continue - } - if opts.Status != "" && run.Status != opts.Status { - continue - } - if opts.Stage != "" && run.State.Stage != opts.Stage { - continue - } - filtered = append(filtered, run) - } - if opts.Limit > 0 && len(filtered) > opts.Limit { - sort.SliceStable(filtered, func(i, j int) bool { - if filtered[i].Updated.Equal(filtered[j].Updated) { - return filtered[i].Started.Before(filtered[j].Started) - } - return filtered[i].Updated.Before(filtered[j].Updated) - }) - start := len(filtered) - opts.Limit - limited := append([]aiflow.Run(nil), filtered[start:]...) - return limited - } - return filtered -} - -func pendingFlowRuns(runs []aiflow.Run) []aiflow.Run { - return filterFlowRuns(runs, flowRunOptions{Pending: true}) -} - -func writeFlowRuns(w io.Writer, runs []aiflow.Run, asJSON bool) error { - if asJSON { - enc := json.NewEncoder(w) - enc.SetIndent("", " ") - return enc.Encode(runs) - } - fmt.Fprintf(w, " %d run%s\n", len(runs), plural(len(runs))) - for _, r := range runs { - id := r.ID - if len(id) > 8 { - id = id[:8] - } - stage := r.State.Stage - if stage == "" { - stage = "-" - } - fmt.Fprintf(w, " %s %-8s stage=%-12s updated=%s (%d steps)\n", - id, r.Status, stage, r.Updated.Format("2006-01-02T15:04:05Z07:00"), len(r.Steps)) - for _, step := range r.Steps { - fmt.Fprintf(w, " - %-12s %-11s attempts=%d", step.Name, step.Status, step.Attempts) - if step.Error != "" { - fmt.Fprintf(w, " error=%q", step.Error) - } - fmt.Fprintln(w) - } - } - return nil -} - -func plural(n int) string { - if n == 1 { - return "" - } - return "s" -} - -func flowFlags() []cli.Flag { - return []cli.Flag{ - &cli.StringFlag{Name: "trigger", Usage: "Broker topic to subscribe to", EnvVars: []string{"MICRO_FLOW_TRIGGER"}}, - &cli.StringFlag{Name: "prompt", Usage: "Prompt template (use {{.Data}} for event data)", EnvVars: []string{"MICRO_FLOW_PROMPT"}}, - &cli.StringFlag{Name: "provider", Usage: "AI provider", Value: "openai", EnvVars: []string{"MICRO_AI_PROVIDER"}}, - &cli.StringFlag{Name: "api_key", Usage: "API key", EnvVars: []string{"MICRO_AI_API_KEY"}}, - &cli.StringFlag{Name: "model", Usage: "Model name", EnvVars: []string{"MICRO_AI_MODEL"}}, - &cli.StringFlag{Name: "base_url", Usage: "Provider base URL", EnvVars: []string{"MICRO_AI_BASE_URL"}}, - &cli.StringFlag{Name: "name", Usage: "Flow name", Value: "default"}, - } -} - -func runFlow(c *cli.Context, oneShot bool) error { - prompt := c.String("prompt") - if prompt == "" { - return fmt.Errorf("--prompt is required") - } - - provider := c.String("provider") - apiKey := c.String("api_key") - if apiKey == "" { - apiKey = fallbackKey(provider) - } - if apiKey == "" { - return fmt.Errorf("no API key; set --api_key or the provider's env var") - } - - opts := []aiflow.Option{ - aiflow.Prompt(prompt), - aiflow.Provider(provider), - aiflow.APIKey(apiKey), - } - if v := c.String("trigger"); v != "" { - opts = append(opts, aiflow.Trigger(v)) - } - if v := c.String("model"); v != "" { - opts = append(opts, aiflow.Model(v)) - } - if v := c.String("base_url"); v != "" { - opts = append(opts, aiflow.BaseURL(v)) - } - - opts = append(opts, aiflow.OnResult(func(r aiflow.Result) { - out, _ := json.MarshalIndent(r, "", " ") - fmt.Println(string(out)) - })) - - f := aiflow.New(c.String("name"), opts...) - - reg := registry.DefaultRegistry - br := broker.DefaultBroker - cl := client.DefaultClient - - if err := br.Connect(); err != nil { - return fmt.Errorf("broker connect: %w", err) - } - - if err := f.Register(reg, br, cl); err != nil { - return err - } - - if oneShot { - data := c.String("data") - if data == "" { - data = prompt - } - return f.Execute(context.Background(), data) - } - - if c.String("trigger") == "" { - return fmt.Errorf("--trigger is required for 'flow run' (use 'flow exec' for one-shot)") - } - - fmt.Println() - fmt.Println(" \033[1mmicro flow\033[0m") - fmt.Println() - fmt.Printf(" Flow \033[36m%s\033[0m\n", f.Name()) - fmt.Printf(" Topic \033[36m%s\033[0m\n", c.String("trigger")) - fmt.Printf(" Provider \033[36m%s\033[0m\n", provider) - fmt.Println() - fmt.Println(" \033[2mListening for events. Ctrl-C to stop.\033[0m") - fmt.Println() - - sig := make(chan os.Signal, 1) - signal.Notify(sig, syscall.SIGINT, syscall.SIGTERM) - <-sig - - fmt.Printf("\nStopped. %d executions recorded.\n", len(f.Results())) - return nil -} - -func fallbackKey(provider string) string { - envMap := map[string]string{ - "anthropic": "ANTHROPIC_API_KEY", - "openai": "OPENAI_API_KEY", - "gemini": "GEMINI_API_KEY", - "groq": "GROQ_API_KEY", - "mistral": "MISTRAL_API_KEY", - "openrouter": "OPENROUTER_API_KEY", - "together": "TOGETHER_API_KEY", - "atlascloud": "ATLASCLOUD_API_KEY", - "litellm": "LITELLM_API_KEY", - } - if env, ok := envMap[provider]; ok { - return os.Getenv(env) - } - return "" -} diff --git a/cmd/micro/flow/flow_test.go b/cmd/micro/flow/flow_test.go deleted file mode 100644 index a84c120cc3..0000000000 --- a/cmd/micro/flow/flow_test.go +++ /dev/null @@ -1,156 +0,0 @@ -package flow - -import ( - "bytes" - "encoding/json" - "strings" - "testing" - "time" - - aiflow "go-micro.dev/v6/flow" -) - -func TestWriteFlowRunsIncludesStepDetails(t *testing.T) { - updated := time.Date(2026, 6, 24, 12, 30, 0, 0, time.UTC) - runs := []aiflow.Run{{ - ID: "1234567890abcdef", - Status: "failed", - Updated: updated, - State: aiflow.State{Stage: "charge"}, - Steps: []aiflow.StepRecord{ - {Name: "reserve", Status: "done", Attempts: 1}, - {Name: "charge", Status: "failed", Attempts: 3, Error: "card declined"}, - }, - }} - - var out bytes.Buffer - if err := writeFlowRuns(&out, runs, false); err != nil { - t.Fatalf("writeFlowRuns: %v", err) - } - got := out.String() - for _, want := range []string{ - "1 run", - "12345678 failed stage=charge", - "updated=2026-06-24T12:30:00Z", - "- reserve done attempts=1", - `- charge failed attempts=3 error="card declined"`, - } { - if !strings.Contains(got, want) { - t.Fatalf("output missing %q:\n%s", want, got) - } - } -} - -func TestValidateFlowRunOptionsRejectsInvalidStatus(t *testing.T) { - _, err := validateFlowRunOptions(flowRunOptions{Status: "stuck"}) - if err == nil || !strings.Contains(err.Error(), "invalid run status") { - t.Fatalf("expected invalid status error, got %v", err) - } -} - -func TestValidateFlowRunOptionsRejectsNegativeLimit(t *testing.T) { - _, err := validateFlowRunOptions(flowRunOptions{Limit: -1}) - if err == nil || !strings.Contains(err.Error(), "invalid limit") { - t.Fatalf("expected invalid limit error, got %v", err) - } -} - -func TestWriteFlowRunsJSON(t *testing.T) { - runs := []aiflow.Run{{ID: "run-1", Flow: "checkout", Status: "done"}} - - var out bytes.Buffer - if err := writeFlowRuns(&out, runs, true); err != nil { - t.Fatalf("writeFlowRuns: %v", err) - } - var got []aiflow.Run - if err := json.Unmarshal(out.Bytes(), &got); err != nil { - t.Fatalf("invalid JSON: %v\n%s", err, out.String()) - } - if len(got) != 1 || got[0].ID != "run-1" || got[0].Flow != "checkout" || got[0].Status != "done" { - t.Fatalf("decoded runs = %+v", got) - } -} - -func TestPendingFlowRunsFiltersCompletedRuns(t *testing.T) { - runs := []aiflow.Run{ - {ID: "run-1", Status: "done"}, - {ID: "run-2", Status: "failed"}, - {ID: "run-3", Status: "running"}, - } - - got := pendingFlowRuns(runs) - if len(got) != 2 { - t.Fatalf("pendingFlowRuns returned %d runs, want 2: %+v", len(got), got) - } - if got[0].ID != "run-2" || got[1].ID != "run-3" { - t.Fatalf("pending runs = %+v", got) - } -} - -func TestFilterFlowRunsStatus(t *testing.T) { - runs := []aiflow.Run{ - {ID: "run-1", Status: "done"}, - {ID: "run-2", Status: "failed"}, - {ID: "run-3", Status: "running"}, - {ID: "run-4", Status: "failed"}, - } - - got := filterFlowRuns(runs, flowRunOptions{Status: "failed"}) - if len(got) != 2 { - t.Fatalf("filterFlowRuns returned %d runs, want 2: %+v", len(got), got) - } - if got[0].ID != "run-2" || got[1].ID != "run-4" { - t.Fatalf("failed runs = %+v", got) - } -} - -func TestFilterFlowRunsStage(t *testing.T) { - runs := []aiflow.Run{ - {ID: "run-1", Status: "failed", State: aiflow.State{Stage: "reserve"}}, - {ID: "run-2", Status: "failed", State: aiflow.State{Stage: "charge"}}, - {ID: "run-3", Status: "running", State: aiflow.State{Stage: "charge"}}, - {ID: "run-4", Status: "done", State: aiflow.State{}}, - } - - got := filterFlowRuns(runs, flowRunOptions{Stage: "charge"}) - if len(got) != 2 { - t.Fatalf("filterFlowRuns returned %d runs, want 2: %+v", len(got), got) - } - if got[0].ID != "run-2" || got[1].ID != "run-3" { - t.Fatalf("charge-stage runs = %+v", got) - } -} - -func TestFilterFlowRunsLimitKeepsNewestRuns(t *testing.T) { - runs := []aiflow.Run{ - {ID: "run-1", Status: "done"}, - {ID: "run-2", Status: "failed"}, - {ID: "run-3", Status: "running"}, - } - - got := filterFlowRuns(runs, flowRunOptions{Limit: 2}) - if len(got) != 2 { - t.Fatalf("filterFlowRuns returned %d runs, want 2: %+v", len(got), got) - } - if got[0].ID != "run-2" || got[1].ID != "run-3" { - t.Fatalf("limited runs = %+v", got) - } -} - -func TestFilterFlowRunsCombinesPendingStatusAndLimit(t *testing.T) { - runs := []aiflow.Run{ - {ID: "run-1", Status: "failed"}, - {ID: "run-2", Status: "done"}, - {ID: "run-3", Status: "failed"}, - {ID: "run-4", Status: "running"}, - {ID: "run-5", Status: "failed"}, - } - - got := filterFlowRuns(runs, flowRunOptions{Pending: true, Status: "failed", Limit: 2}) - if len(got) != 2 { - t.Fatalf("filterFlowRuns returned %d runs, want 2: %+v", len(got), got) - } - if got[0].ID != "run-3" || got[1].ID != "run-5" { - t.Fatalf("filtered runs = %+v", got) - } -} diff --git a/cmd/micro/inspect/inspect.go b/cmd/micro/inspect/inspect.go index 2ea8c127af..5c62fb9e57 100644 --- a/cmd/micro/inspect/inspect.go +++ b/cmd/micro/inspect/inspect.go @@ -2,7 +2,6 @@ package inspect import ( - "context" "encoding/json" "fmt" "io" @@ -12,16 +11,15 @@ import ( "github.com/urfave/cli/v2" goagent "go-micro.dev/v6/agent" "go-micro.dev/v6/cmd" - aiflow "go-micro.dev/v6/flow" "go-micro.dev/v6/store" ) func init() { cmd.Register(&cli.Command{ Name: "inspect", - Usage: "Inspect recent agent and workflow activity", + Usage: "Inspect recent agent activity", Description: `Inspect is the CLI checkpoint in the local scaffold → run → chat → inspect loop. -It reads durable local run history, so it works after the agent or flow has stopped.`, +It reads durable local run history, so it works after the agent has stopped.`, Subcommands: []*cli.Command{ { Name: "agent", @@ -30,13 +28,6 @@ It reads durable local run history, so it works after the agent or flow has stop Flags: inspectAgentFlags(), Action: inspectAgent, }, - { - Name: "flow", - Usage: "Show durable run history for a flow", - ArgsUsage: "[flow]", - Flags: inspectFlowFlags(), - Action: inspectFlow, - }, }, }) } @@ -52,17 +43,6 @@ func inspectAgentFlags() []cli.Flag { } } -func inspectFlowFlags() []cli.Flag { - return []cli.Flag{ - &cli.BoolFlag{Name: "json", Usage: "Print durable run history as JSON for automation"}, - &cli.StringFlag{Name: "run", Usage: "Show the complete versioned record for this run id"}, - &cli.BoolFlag{Name: "pending", Usage: "Only show runs that have not completed"}, - &cli.StringFlag{Name: "status", Usage: "Only show runs with this status (running, done, failed)"}, - &cli.IntFlag{Name: "limit", Usage: "Show the most recently updated N runs"}, - &cli.StringFlag{Name: "stage", Usage: "Only show runs currently checkpointed at this stage"}, - } -} - func inspectAgent(c *cli.Context) error { name := c.Args().First() if name == "" { @@ -134,9 +114,6 @@ func writeAgentRunRecord(w io.Writer, record goagent.RunRecord, asJSON bool) err fmt.Fprintf(w, " trigger=%q", summary.Trigger) } fmt.Fprintln(w) - if summary.ParentID != "" { - fmt.Fprintf(w, " parent: micro inspect flow %s --run %s\n", summary.Flow, summary.ParentID) - } } fmt.Fprintln(w, " Timeline") for _, event := range record.Events { @@ -220,9 +197,6 @@ func writeAgentInspection(w io.Writer, name string, runs []goagent.RunSummary, a fmt.Fprintf(w, " step=%s", run.Step) } fmt.Fprintln(w) - if run.Flow != "" && run.ParentID != "" { - fmt.Fprintf(w, " parent: micro inspect flow %s --run %s\n", run.Flow, run.ParentID) - } writeAgentRunBreadcrumbs(w, name, run) } return nil @@ -251,139 +225,6 @@ func isResumableAgentRun(run goagent.RunSummary) bool { } } -func inspectFlow(c *cli.Context) error { - name := c.Args().First() - if name == "" { - return fmt.Errorf("flow name required: micro inspect flow ") - } - checkpoint := aiflow.StoreCheckpoint(nil, name) - if runID := c.String("run"); runID != "" { - record, err := aiflow.LoadRunRecord(context.Background(), checkpoint, name, runID) - if err != nil { - return err - } - return writeFlowRunRecord(os.Stdout, record, c.Bool("json")) - } - runs, err := checkpoint.List(context.Background()) - if err != nil { - return err - } - runs = filterFlowInspection(runs, c.Bool("pending"), c.String("status"), c.String("stage"), c.Int("limit")) - return writeFlowInspection(os.Stdout, name, runs, c.Bool("json"), c.Bool("pending")) -} - -func writeFlowRunRecord(w io.Writer, record aiflow.RunRecord, asJSON bool) error { - if asJSON { - enc := json.NewEncoder(w) - enc.SetIndent("", " ") - return enc.Encode(record) - } - run := record.Run - if run.Status == "" { - fmt.Fprintf(w, " No recorded flow %q run %q.\n", run.Flow, run.ID) - return nil - } - fmt.Fprintf(w, " Flow %q run %q schema=%d\n", run.Flow, run.ID, record.SchemaVersion) - fmt.Fprintf(w, " status=%s started=%s updated=%s", run.Status, run.Started.Format(time.RFC3339Nano), run.Updated.Format(time.RFC3339Nano)) - if run.ParentID != "" { - fmt.Fprintf(w, " parent=%s", run.ParentID) - } - if run.Dispatch != "" { - fmt.Fprintf(w, " dispatch=%s", run.Dispatch) - } - if run.Trigger != "" { - fmt.Fprintf(w, " trigger=%q", run.Trigger) - } - if run.State.Stage != "" { - fmt.Fprintf(w, " stage=%s", run.State.Stage) - } - fmt.Fprintln(w) - fmt.Fprintln(w, " Steps") - for _, step := range run.Steps { - fmt.Fprintf(w, " %s status=%s attempts=%d", step.Name, step.Status, step.Attempts) - if step.Service != "" { - fmt.Fprintf(w, " service=%s endpoint=%s", step.Service, step.Endpoint) - } - if step.Agent != "" { - fmt.Fprintf(w, " agent=%s", step.Agent) - } - if step.ChildRunID != "" { - fmt.Fprintf(w, " child_run=%s", step.ChildRunID) - } - if step.VerificationStatus != "" { - fmt.Fprintf(w, " verification=%s", step.VerificationStatus) - } - if step.ErrorKind != "" { - fmt.Fprintf(w, " error_kind=%s", step.ErrorKind) - } - if step.Error != "" { - fmt.Fprintf(w, " error=%q", step.Error) - } - fmt.Fprintln(w) - if step.Agent != "" && step.ChildRunID != "" { - fmt.Fprintf(w, " inspect: micro inspect agent %s --run %s\n", step.Agent, step.ChildRunID) - } - } - return nil -} - -func filterFlowInspection(runs []aiflow.Run, pending bool, status, stage string, limit int) []aiflow.Run { - filtered := make([]aiflow.Run, 0, len(runs)) - for _, run := range runs { - if pending && run.Status == "done" { - continue - } - if status != "" && run.Status != status { - continue - } - if stage != "" && run.State.Stage != stage { - continue - } - filtered = append(filtered, run) - } - if limit > 0 && len(filtered) > limit { - return filtered[len(filtered)-limit:] - } - return filtered -} - -func writeFlowInspection(w io.Writer, name string, runs []aiflow.Run, asJSON, pending bool) error { - if asJSON { - enc := json.NewEncoder(w) - enc.SetIndent("", " ") - return enc.Encode(runs) - } - if len(runs) == 0 { - if pending { - fmt.Fprintf(w, " No pending flow runs recorded for %q.\n", name) - return nil - } - fmt.Fprintf(w, " No flow runs recorded for %q. After executing a durable flow, try: micro inspect flow %s\n", name, name) - return nil - } - fmt.Fprintf(w, " Flow %q runs\n", name) - for _, run := range runs { - stage := run.State.Stage - if stage == "" { - stage = "-" - } - fmt.Fprintf(w, " %s status=%s stage=%s steps=%d", shortID(run.ID), run.Status, stage, len(run.Steps)) - for _, step := range run.Steps { - if step.Error != "" { - fmt.Fprintf(w, " error=%q", step.Error) - break - } - } - fmt.Fprintln(w) - for _, step := range run.Steps { - if step.Agent != "" && step.ChildRunID != "" { - fmt.Fprintf(w, " child: micro inspect agent %s --run %s\n", step.Agent, step.ChildRunID) - } - } - } - return nil -} - func shortID(id string) string { if len(id) <= 12 { return id diff --git a/cmd/micro/inspect/inspect_test.go b/cmd/micro/inspect/inspect_test.go index d461b5614a..fe329926cd 100644 --- a/cmd/micro/inspect/inspect_test.go +++ b/cmd/micro/inspect/inspect_test.go @@ -8,7 +8,6 @@ import ( "time" goagent "go-micro.dev/v6/agent" - aiflow "go-micro.dev/v6/flow" ) func TestWriteAgentInspectionIncludesActionableBreadcrumbs(t *testing.T) { @@ -72,7 +71,7 @@ func TestWriteAgentRunRecordIncludesSummaryAndTimeline(t *testing.T) { t.Fatal(err) } got := out.String() - for _, want := range []string{`Agent "support" run "run-1"`, "schema=1", "status=timeout", "events=2", "duration_ms=2000", "trace=trace-1", "Origin", "flow=daily-ops", "step=summarize", "dispatch=schedule", `trigger="daily-review"`, "micro inspect flow daily-ops --run flow-run-1", "Timeline", "kind=run", "input_chars=18", "kind=error", "error_kind=timeout", `error="deadline exceeded"`} { + for _, want := range []string{`Agent "support" run "run-1"`, "schema=1", "status=timeout", "events=2", "duration_ms=2000", "trace=trace-1", "Origin", "flow=daily-ops", "step=summarize", "dispatch=schedule", `trigger="daily-review"`, "Timeline", "kind=run", "input_chars=18", "kind=error", "error_kind=timeout", `error="deadline exceeded"`} { if !strings.Contains(got, want) { t.Fatalf("output missing %q:\n%s", want, got) } @@ -97,72 +96,3 @@ func TestWriteAgentRunRecordJSONPreservesSchema(t *testing.T) { t.Fatalf("decoded record = %#v", got) } } - -func TestWriteFlowInspectionIncludesFailedStepBreadcrumb(t *testing.T) { - runs := []aiflow.Run{{ID: "1234567890abcdef", Status: "failed", State: aiflow.State{Stage: "charge"}, Steps: []aiflow.StepRecord{{Name: "charge", Status: "failed", Error: "card declined"}}}} - var out bytes.Buffer - if err := writeFlowInspection(&out, "checkout", runs, false, false); err != nil { - t.Fatal(err) - } - got := out.String() - for _, want := range []string{"Flow \"checkout\" runs", "1234567890ab", "status=failed", "stage=charge", "steps=1", `error="card declined"`} { - if !strings.Contains(got, want) { - t.Fatalf("output missing %q:\n%s", want, got) - } - } -} - -func TestWriteFlowInspectionJSON(t *testing.T) { - runs := []aiflow.Run{{ID: "run-1", Flow: "checkout", Status: "done"}} - var out bytes.Buffer - if err := writeFlowInspection(&out, "checkout", runs, true, false); err != nil { - t.Fatal(err) - } - var got []aiflow.Run - if err := json.Unmarshal(out.Bytes(), &got); err != nil { - t.Fatalf("invalid JSON: %v\n%s", err, out.String()) - } - if len(got) != 1 || got[0].ID != "run-1" || got[0].Status != "done" { - t.Fatalf("decoded runs = %+v", got) - } -} - -func TestWriteFlowRunRecordIncludesTargetsAndChildBreadcrumb(t *testing.T) { - start := time.Date(2026, time.September, 6, 12, 0, 0, 0, time.UTC) - record := aiflow.RunRecord{ - SchemaVersion: aiflow.RunRecordSchemaVersion, - Run: aiflow.Run{ - ID: "flow-run-1", Flow: "checkout", Status: "done", Dispatch: "schedule", Trigger: "nightly", - Started: start, Updated: start.Add(time.Second), - Steps: []aiflow.StepRecord{ - {Name: "charge", Status: "done", Attempts: 1, Service: "payments", Endpoint: "Payments.Charge"}, - {Name: "notify", Status: "done", Attempts: 1, Agent: "comms", ChildRunID: "agent-run-1"}, - }, - }, - } - var out bytes.Buffer - if err := writeFlowRunRecord(&out, record, false); err != nil { - t.Fatal(err) - } - got := out.String() - for _, want := range []string{`Flow "checkout" run "flow-run-1"`, "schema=1", "status=done", "dispatch=schedule", `trigger="nightly"`, "Steps", "service=payments", "endpoint=Payments.Charge", "agent=comms", "child_run=agent-run-1", "micro inspect agent comms --run agent-run-1"} { - if !strings.Contains(got, want) { - t.Fatalf("output missing %q:\n%s", want, got) - } - } -} - -func TestWriteFlowRunRecordJSONPreservesSchema(t *testing.T) { - record := aiflow.RunRecord{SchemaVersion: aiflow.RunRecordSchemaVersion, Run: aiflow.Run{ID: "flow-run-1", Flow: "checkout"}} - var out bytes.Buffer - if err := writeFlowRunRecord(&out, record, true); err != nil { - t.Fatal(err) - } - var got aiflow.RunRecord - if err := json.Unmarshal(out.Bytes(), &got); err != nil { - t.Fatalf("invalid JSON: %v\n%s", err, out.String()) - } - if got.SchemaVersion != aiflow.RunRecordSchemaVersion || got.Run.ID != "flow-run-1" { - t.Fatalf("decoded record = %#v", got) - } -} diff --git a/cmd/micro/main.go b/cmd/micro/main.go index 5a21880334..ec5115a246 100644 --- a/cmd/micro/main.go +++ b/cmd/micro/main.go @@ -21,7 +21,6 @@ import ( _ "go-micro.dev/v6/cmd/micro/cli" _ "go-micro.dev/v6/cmd/micro/cli/build" _ "go-micro.dev/v6/cmd/micro/cli/deploy" - _ "go-micro.dev/v6/cmd/micro/flow" "go-micro.dev/v6/cmd/micro/gateway" _ "go-micro.dev/v6/cmd/micro/inspect" _ "go-micro.dev/v6/cmd/micro/loop" diff --git a/cmd/micro/zero_to_hero_cli_test.go b/cmd/micro/zero_to_hero_cli_test.go index 123a8bf75c..1041ecc75d 100644 --- a/cmd/micro/zero_to_hero_cli_test.go +++ b/cmd/micro/zero_to_hero_cli_test.go @@ -21,16 +21,16 @@ func TestZeroToHeroCLIBoundaries(t *testing.T) { } } - for _, want := range []string{"run", "chat", "flow", "inspect", "deploy", "zero-to-hero"} { + for _, want := range []string{"run", "chat", "inspect", "deploy", "zero-to-hero"} { if !commands[want] { t.Fatalf("missing %q command", want) } } - if !subcommands["flow"]["runs"] { - t.Fatal("missing inspect boundary: flow runs") + if commands["flow"] || subcommands["inspect"]["flow"] { + t.Fatal("removed flow command is registered") } - if !subcommands["inspect"]["agent"] || !subcommands["inspect"]["flow"] { - t.Fatal("missing inspect boundary: inspect agent/flow") + if !subcommands["inspect"]["agent"] { + t.Fatal("missing inspect boundary: inspect agent") } var hasDeployDryRun bool @@ -69,7 +69,7 @@ func TestZeroToHeroCommandPrintsMaintainedNoSecretPath(t *testing.T) { "go run ./examples/first-agent", "go run ./examples/support", "make harness", - "services → agents → workflows", + "services → agents", } { if !strings.Contains(got, want) { t.Fatalf("micro zero-to-hero output missing %q:\n%s", want, got) diff --git a/deploy/kubernetes/README.md b/deploy/kubernetes/README.md deleted file mode 100644 index 05c6f52dcf..0000000000 --- a/deploy/kubernetes/README.md +++ /dev/null @@ -1,68 +0,0 @@ -# Kubernetes deployment foundation (alpha) - -This package is the first opt-in Kubernetes foundation for the Go Micro lifecycle: -`Service`, `Agent`, and `Flow` resources. It is intentionally experimental and -additive. Nothing in the Go Micro runtime installs these resources or changes -production defaults. - -## What is included - -- Alpha CRD manifests in `config/crd/` for `agents.micro.dev`, - `services.micro.dev`, and `flows.micro.dev`. -- A small dependency-free mapper that turns a desired Go Micro resource into the - Kubernetes `Deployment` and ClusterIP `Service` shapes a reconciliation loop owns. -- A dependency-free `Reconcile(desired, observed)` core that decides the one - action needed to converge (create / update / noop) and the `Ready`/`Error` - status conditions — no controller-runtime, no client-go, fully unit-testable. - `ReconcileWorkloads` renders both Kubernetes API objects. -- An opt-in `Controller` that observes workloads, applies changes and writes CR - status through a `WorkloadClient` adapter. CRDs enable the status subresource. - A host supplies its Kubernetes client, watches and requeue policy. -- Unit tests that validate the structural CRD fragments, the Agent-to-Deployment - mapping, controller create/update/noop behavior, and error status propagation. - -## Local validation - -```sh -go test ./deploy/kubernetes -``` - -If you have a Kubernetes cluster and `kubectl` available, you can also perform a -server-side dry run of the CRDs: - -```sh -kubectl apply --dry-run=server -f deploy/kubernetes/config/crd/ -``` - -The manifests are `v1alpha1`; expect the API shape to evolve before this becomes -a production operator. - -## Controller integration - -```go -controller := kubernetes.Controller{Client: adapter} -conditions, err := controller.Reconcile(ctx, kubernetes.Resource{ - Kind: kubernetes.KindService, - Name: "hello", - Namespace: "default", - UID: objectUID, - Spec: kubernetes.WorkloadSpec{Image: "example/hello:v1", Port: 8080}, -}) -``` - -`adapter` implements `WorkloadClient`: observe the managed Deployment/Service -fields, apply the supplied API objects with a stable server-side-apply field -manager, and replace `status.conditions` on the source custom resource. Exclude -server-assigned Service addresses and unmanaged fields from observations. The -source UID adds owner references so Kubernetes can garbage-collect workloads. - -The default RPC port is 8080. The mapper supplies `MICRO_SERVER_ADDRESS` unless -explicitly set; an override must listen on `spec.port`. Names must be unique -across Agent, Service and Flow resources within a namespace because they share -the Deployment and Service namespace. Ready remains false while either object -changes or the desired replica count is unavailable. Adapters must observe the -current Deployment generation before reporting ready replicas. - -This is a controller skeleton, not an installed operator: there is no bundled -cluster client, watch loop, RBAC installer or production rollout policy. A host -must arrange reconciliation on resource/workload updates and retry errors. diff --git a/deploy/kubernetes/config/crd/agent.yaml b/deploy/kubernetes/config/crd/agent.yaml deleted file mode 100644 index 4aed99e675..0000000000 --- a/deploy/kubernetes/config/crd/agent.yaml +++ /dev/null @@ -1,53 +0,0 @@ -apiVersion: apiextensions.k8s.io/v1 -kind: CustomResourceDefinition -metadata: - name: agents.micro.dev -spec: - group: micro.dev - scope: Namespaced - names: - plural: agents - singular: agent - kind: Agent - shortNames: [magent] - versions: - - name: v1alpha1 - served: true - storage: true - subresources: - status: {} - schema: - openAPIV3Schema: - type: object - required: [spec] - properties: - status: - type: object - properties: - conditions: - type: array - items: - type: object - required: [type, status, reason] - properties: - type: {type: string} - status: {type: string} - reason: {type: string} - message: {type: string} - spec: - type: object - required: [image] - properties: - port: {type: integer, minimum: 1, maximum: 65535, default: 8080} - image: {type: string, minLength: 1} - command: - type: array - items: {type: string} - args: - type: array - items: {type: string} - replicas: {type: integer, minimum: 0} - registry: {type: string} - env: - type: object - additionalProperties: {type: string} diff --git a/deploy/kubernetes/config/crd/flow.yaml b/deploy/kubernetes/config/crd/flow.yaml deleted file mode 100644 index b5f3798ec3..0000000000 --- a/deploy/kubernetes/config/crd/flow.yaml +++ /dev/null @@ -1,53 +0,0 @@ -apiVersion: apiextensions.k8s.io/v1 -kind: CustomResourceDefinition -metadata: - name: flows.micro.dev -spec: - group: micro.dev - scope: Namespaced - names: - plural: flows - singular: flow - kind: Flow - shortNames: [mflow] - versions: - - name: v1alpha1 - served: true - storage: true - subresources: - status: {} - schema: - openAPIV3Schema: - type: object - required: [spec] - properties: - status: - type: object - properties: - conditions: - type: array - items: - type: object - required: [type, status, reason] - properties: - type: {type: string} - status: {type: string} - reason: {type: string} - message: {type: string} - spec: - type: object - required: [image] - properties: - port: {type: integer, minimum: 1, maximum: 65535, default: 8080} - image: {type: string, minLength: 1} - command: - type: array - items: {type: string} - args: - type: array - items: {type: string} - replicas: {type: integer, minimum: 0} - registry: {type: string} - env: - type: object - additionalProperties: {type: string} diff --git a/deploy/kubernetes/config/crd/service.yaml b/deploy/kubernetes/config/crd/service.yaml deleted file mode 100644 index bc9ac72586..0000000000 --- a/deploy/kubernetes/config/crd/service.yaml +++ /dev/null @@ -1,53 +0,0 @@ -apiVersion: apiextensions.k8s.io/v1 -kind: CustomResourceDefinition -metadata: - name: services.micro.dev -spec: - group: micro.dev - scope: Namespaced - names: - plural: services - singular: service - kind: Service - shortNames: [mservice] - versions: - - name: v1alpha1 - served: true - storage: true - subresources: - status: {} - schema: - openAPIV3Schema: - type: object - required: [spec] - properties: - status: - type: object - properties: - conditions: - type: array - items: - type: object - required: [type, status, reason] - properties: - type: {type: string} - status: {type: string} - reason: {type: string} - message: {type: string} - spec: - type: object - required: [image] - properties: - port: {type: integer, minimum: 1, maximum: 65535, default: 8080} - image: {type: string, minLength: 1} - command: - type: array - items: {type: string} - args: - type: array - items: {type: string} - replicas: {type: integer, minimum: 0} - registry: {type: string} - env: - type: object - additionalProperties: {type: string} diff --git a/deploy/kubernetes/controller.go b/deploy/kubernetes/controller.go deleted file mode 100644 index 874888ac7d..0000000000 --- a/deploy/kubernetes/controller.go +++ /dev/null @@ -1,135 +0,0 @@ -package kubernetes - -import ( - "context" - "errors" - "fmt" - "reflect" -) - -// NetworkService is the ClusterIP Service shape owned by the alpha controller. -// Cluster-assigned addresses are deliberately excluded from reconciliation. -type NetworkService struct { - Type string - PortName string - Protocol string - TargetPort string - Name string - Namespace string - Labels map[string]string - Selector map[string]string - Port int32 -} - -func workloadPort(resource Resource) int32 { - if resource.Spec.Port == 0 { - return 8080 - } - return resource.Spec.Port -} - -// MapService maps a lifecycle resource to a stable RPC service endpoint. -func MapService(resource Resource) (NetworkService, error) { - deployment, err := MapDeployment(resource) - if err != nil { - return NetworkService{}, err - } - return NetworkService{Type: "ClusterIP", PortName: "rpc", Protocol: "TCP", TargetPort: "rpc", Name: deployment.Name, Namespace: deployment.Namespace, Labels: copyMap(deployment.Labels), Selector: copyMap(deployment.Pod.Labels), Port: workloadPort(resource)}, nil -} - -// WorkloadAction contains a Kubernetes API object ready for an adapter to apply. -type WorkloadAction struct { - Type ActionType - Object map[string]interface{} -} - -func objectMetadata(resource Resource, name, namespace string, labels map[string]string) map[string]interface{} { - metadata := map[string]interface{}{"name": name, "namespace": namespace, "labels": labels} - if resource.UID != "" { - metadata["ownerReferences"] = []map[string]interface{}{{"apiVersion": Group + "/" + Version, "kind": string(resource.Kind), "name": resource.Name, "uid": resource.UID, "controller": true, "blockOwnerDeletion": true}} - } - return metadata -} - -// ReconcileWorkloads plans Deployment and Service create/update/noop actions. -// It preserves the original dependency-light Reconcile API for existing callers. -func ReconcileWorkloads(resource Resource, observed Observed) ([]WorkloadAction, []Condition, error) { - action, conditions, err := Reconcile(resource, observed) - if err != nil { - return nil, conditions, err - } - deployment := action.Deployment - service, err := MapService(resource) - if err != nil { - return nil, conditions, err - } - env := make([]map[string]string, 0, len(deployment.Pod.Container.Environment)) - for _, key := range deployment.Pod.Container.EnvironmentKeys() { - env = append(env, map[string]string{"name": key, "value": deployment.Pod.Container.Environment[key]}) - } - container := map[string]interface{}{"name": deployment.Pod.Container.Name, "image": deployment.Pod.Container.Image, "env": env, "ports": []map[string]interface{}{{"name": deployment.Pod.Container.PortName, "containerPort": deployment.Pod.Container.Port, "protocol": deployment.Pod.Container.Protocol}}} - if len(deployment.Pod.Container.Command) > 0 { - container["command"] = deployment.Pod.Container.Command - } - if len(deployment.Pod.Container.Args) > 0 { - container["args"] = deployment.Pod.Container.Args - } - depObject := map[string]interface{}{"apiVersion": "apps/v1", "kind": "Deployment", "metadata": objectMetadata(resource, deployment.Name, deployment.Namespace, deployment.Labels), "spec": map[string]interface{}{"replicas": deployment.Replicas, "selector": map[string]interface{}{"matchLabels": deployment.Pod.Labels}, "template": map[string]interface{}{"metadata": map[string]interface{}{"labels": deployment.Pod.Labels}, "spec": map[string]interface{}{"containers": []map[string]interface{}{container}}}}} - serviceObject := map[string]interface{}{"apiVersion": "v1", "kind": "Service", "metadata": objectMetadata(resource, service.Name, service.Namespace, service.Labels), "spec": map[string]interface{}{"type": service.Type, "selector": service.Selector, "ports": []map[string]interface{}{{"name": service.PortName, "port": service.Port, "targetPort": service.TargetPort, "protocol": service.Protocol}}}} - serviceAction := ActionNoop - if observed.Service == nil { - serviceAction = ActionCreate - } else if !reflect.DeepEqual(*observed.Service, service) { - serviceAction = ActionUpdate - } - if serviceAction != ActionNoop { - conditions = []Condition{{Type: "Ready", Status: "False", Reason: "Reconciling", Message: "service endpoint is being reconciled"}} - } - return []WorkloadAction{{Type: action.Type, Object: depObject}, {Type: serviceAction, Object: serviceObject}}, conditions, nil -} - -// WorkloadClient is the cluster adapter for the opt-in controller skeleton. -// Apply should use server-side apply with a stable field manager and preserve -// fields owned by Kubernetes. Observe must return only the fields represented -// by Observed; UpdateStatus writes the CR's status subresource. -type WorkloadClient interface { - Observe(context.Context, Resource) (Observed, error) - Apply(context.Context, map[string]interface{}) error - UpdateStatus(context.Context, Resource, []Condition) error -} - -// Controller reconciles one supplied Agent, Service or Flow resource. The host -// supplies watches/requeues and a Kubernetes adapter, keeping client-go out of -// the core framework. No cluster connection or controller starts implicitly. -type Controller struct{ Client WorkloadClient } - -func (c Controller) Reconcile(ctx context.Context, resource Resource) ([]Condition, error) { - if c.Client == nil { - return nil, errors.New("kubernetes: workload client is required") - } - if err := ctx.Err(); err != nil { - return nil, err - } - observed, err := c.Client.Observe(ctx, resource) - var actions []WorkloadAction - var conditions []Condition - if err == nil { - actions, conditions, err = ReconcileWorkloads(resource, observed) - } - if err == nil { - for _, action := range actions { - if action.Type != ActionNoop { - if err = c.Client.Apply(ctx, action.Object); err != nil { - break - } - } - } - } - if err != nil { - conditions = []Condition{{Type: "Error", Status: "True", Reason: "ReconcileFailed", Message: err.Error()}, {Type: "Ready", Status: "False", Reason: "ReconcileFailed", Message: "workloads have not converged"}} - } - if statusErr := c.Client.UpdateStatus(ctx, resource, conditions); statusErr != nil { - err = errors.Join(err, fmt.Errorf("update status: %w", statusErr)) - } - return conditions, err -} diff --git a/deploy/kubernetes/controller_test.go b/deploy/kubernetes/controller_test.go deleted file mode 100644 index 72df697447..0000000000 --- a/deploy/kubernetes/controller_test.go +++ /dev/null @@ -1,151 +0,0 @@ -package kubernetes - -import ( - "context" - "errors" - "reflect" - "testing" -) - -type fakeWorkloadClient struct { - observed Observed - objects []map[string]interface{} - status []Condition - observeErr, applyErr, statusErr error -} - -func (f *fakeWorkloadClient) Observe(context.Context, Resource) (Observed, error) { - return f.observed, f.observeErr -} -func (f *fakeWorkloadClient) Apply(_ context.Context, object map[string]interface{}) error { - f.objects = append(f.objects, object) - return f.applyErr -} -func (f *fakeWorkloadClient) UpdateStatus(_ context.Context, _ Resource, conditions []Condition) error { - f.status = conditions - return f.statusErr -} - -func TestControllerLifecycle(t *testing.T) { - for _, kind := range []Kind{KindAgent, KindService, KindFlow} { - t.Run(string(kind), func(t *testing.T) { - resource := agentResource() - resource.Kind, resource.UID, resource.Spec.Port = kind, "resource-uid", 9090 - client := &fakeWorkloadClient{} - controller := Controller{Client: client} - conditions, err := controller.Reconcile(context.Background(), resource) - if err != nil || len(client.objects) != 2 { - t.Fatalf("create: objects=%v err=%v", client.objects, err) - } - if findCondition(conditions, "Ready").Status != "False" { - t.Fatal("new workloads reported ready") - } - deployment, service := client.objects[0], client.objects[1] - if deployment["apiVersion"] != "apps/v1" || deployment["kind"] != "Deployment" || service["kind"] != "Service" { - t.Fatal("invalid workload objects") - } - metadata := deployment["metadata"].(map[string]interface{}) - owner := metadata["ownerReferences"].([]map[string]interface{})[0] - if owner["uid"] != resource.UID || owner["kind"] != string(kind) { - t.Fatalf("owner=%v", owner) - } - spec := deployment["spec"].(map[string]interface{}) - template := spec["template"].(map[string]interface{}) - container := template["spec"].(map[string]interface{})["containers"].([]map[string]interface{})[0] - if container["ports"].([]map[string]interface{})[0]["containerPort"] != int32(9090) { - t.Fatal("wrong container port") - } - serviceSpec := service["spec"].(map[string]interface{}) - if !reflect.DeepEqual(serviceSpec["selector"], template["metadata"].(map[string]interface{})["labels"]) { - t.Fatal("service does not select workload") - } - port := serviceSpec["ports"].([]map[string]interface{})[0] - if port["port"] != int32(9090) || port["targetPort"] != "rpc" { - t.Fatalf("service port=%v", port) - } - dep, _ := MapDeployment(resource) - svc, _ := MapService(resource) - client.observed = Observed{Deployment: &dep, Service: &svc, ReadyReplicas: 2} - client.objects = nil - conditions, err = controller.Reconcile(context.Background(), resource) - if err != nil || len(client.objects) != 0 || findCondition(conditions, "Ready").Status != "True" { - t.Fatalf("converged: %v %v", conditions, err) - } - resource.Spec.Image = "example/support:v2" - conditions, err = controller.Reconcile(context.Background(), resource) - if err != nil || len(client.objects) != 1 || findCondition(conditions, "Ready").Status != "False" { - t.Fatalf("update: %v %v", conditions, err) - } - }) - } -} - -func TestControllerFailures(t *testing.T) { - sentinel := errors.New("cluster unavailable") - for _, stage := range []string{"observe", "apply", "status", "invalid"} { - t.Run(stage, func(t *testing.T) { - client := &fakeWorkloadClient{} - resource := agentResource() - switch stage { - case "observe": - client.observeErr = sentinel - case "apply": - client.applyErr = sentinel - case "status": - client.statusErr = sentinel - case "invalid": - resource.Spec.Port = -1 - } - _, err := (Controller{Client: client}).Reconcile(context.Background(), resource) - if err == nil { - t.Fatal("expected failure") - } - if stage != "invalid" && !errors.Is(err, sentinel) { - t.Fatalf("lost cause: %v", err) - } - if stage != "status" && findCondition(client.status, "Error").Status != "True" { - t.Fatalf("missing error status: %v", client.status) - } - if (stage == "observe" || stage == "invalid") && len(client.objects) > 0 { - t.Fatal("applied after failure") - } - }) - } - ctx, cancel := context.WithCancel(context.Background()) - cancel() - client := &fakeWorkloadClient{} - if _, err := (Controller{Client: client}).Reconcile(ctx, agentResource()); !errors.Is(err, context.Canceled) || len(client.objects) > 0 { - t.Fatalf("canceled: %v", err) - } -} - -func TestControllerRepairsPortDrift(t *testing.T) { - for _, field := range []string{"service-type", "service-name", "service-protocol", "service-target", "container-port", "container-name", "container-protocol"} { - t.Run(field, func(t *testing.T) { - resource := agentResource() - dep, _ := MapDeployment(resource) - svc, _ := MapService(resource) - switch field { - case "service-type": - svc.Type = "NodePort" - case "service-name": - svc.PortName = "wrong" - case "service-protocol": - svc.Protocol = "UDP" - case "service-target": - svc.TargetPort = "9000" - case "container-port": - dep.Pod.Container.Port = 9000 - case "container-name": - dep.Pod.Container.PortName = "wrong" - case "container-protocol": - dep.Pod.Container.Protocol = "UDP" - } - client := &fakeWorkloadClient{observed: Observed{Deployment: &dep, Service: &svc, ReadyReplicas: 2}} - conditions, err := (Controller{Client: client}).Reconcile(context.Background(), resource) - if err != nil || len(client.objects) != 1 || findCondition(conditions, "Ready").Status != "False" { - t.Fatalf("drift ignored: actions=%v conditions=%v err=%v", client.objects, conditions, err) - } - }) - } -} diff --git a/deploy/kubernetes/doc.go b/deploy/kubernetes/doc.go deleted file mode 100644 index fe6df5e623..0000000000 --- a/deploy/kubernetes/doc.go +++ /dev/null @@ -1,8 +0,0 @@ -// Package kubernetes contains the experimental Kubernetes deployment foundation -// for Go Micro services, agents, and flows. -// -// The package is intentionally small and additive: it exposes alpha custom -// resource manifests and a dry-run mapper that turns a resource spec into the -// Deployment shape an operator would reconcile. It does not install an operator -// or change any runtime defaults. -package kubernetes diff --git a/deploy/kubernetes/kubernetes_test.go b/deploy/kubernetes/kubernetes_test.go deleted file mode 100644 index bbb26144ed..0000000000 --- a/deploy/kubernetes/kubernetes_test.go +++ /dev/null @@ -1,87 +0,0 @@ -package kubernetes - -import ( - "strings" - "testing" -) - -func TestCRDManifestsAreStructural(t *testing.T) { - for _, kind := range []Kind{KindAgent, KindService, KindFlow} { - manifest := CRDManifests[kind] - if manifest == "" { - t.Fatalf("missing manifest for %s", kind) - } - checks := []string{ - "apiVersion: apiextensions.k8s.io/v1", - "kind: CustomResourceDefinition", - "group: micro.dev", - "kind: " + string(kind), - "name: v1alpha1", - "served: true", - "storage: true", - "openAPIV3Schema:", - "type: object", - "required: [image]", - } - for _, check := range checks { - if !strings.Contains(manifest, check) { - t.Fatalf("%s manifest missing %q:\n%s", kind, check, manifest) - } - } - } -} - -func TestMapDeploymentForAgent(t *testing.T) { - deployment, err := MapDeployment(Resource{ - Kind: KindAgent, - Name: "support-agent", - Namespace: "agents", - Spec: WorkloadSpec{ - Image: "ghcr.io/acme/support-agent:v1", - Replicas: 2, - Registry: "kubernetes", - Environment: map[string]string{ - "MODEL": "gpt-5.5", - }, - }, - }) - if err != nil { - t.Fatalf("MapDeployment returned error: %v", err) - } - if deployment.Name != "support-agent" || deployment.Namespace != "agents" { - t.Fatalf("unexpected identity: %+v", deployment) - } - if deployment.Replicas != 2 { - t.Fatalf("replicas = %d, want 2", deployment.Replicas) - } - if got := deployment.Labels["micro.dev/kind"]; got != "agent" { - t.Fatalf("micro.dev/kind label = %q, want agent", got) - } - container := deployment.Pod.Container - if container.Image != "ghcr.io/acme/support-agent:v1" { - t.Fatalf("image = %q", container.Image) - } - if got := container.Environment["MICRO_REGISTRY"]; got != "kubernetes" { - t.Fatalf("MICRO_REGISTRY = %q, want kubernetes", got) - } - if got := container.Environment["MODEL"]; got != "gpt-5.5" { - t.Fatalf("MODEL = %q, want gpt-5.5", got) - } -} - -func TestMapDeploymentDefaultsAndValidation(t *testing.T) { - deployment, err := MapDeployment(Resource{Kind: KindService, Name: "api", Spec: WorkloadSpec{Image: "api:latest"}}) - if err != nil { - t.Fatalf("MapDeployment returned error: %v", err) - } - if deployment.Namespace != "default" || deployment.Replicas != 1 { - t.Fatalf("defaults = namespace %q replicas %d", deployment.Namespace, deployment.Replicas) - } - - if _, err := MapDeployment(Resource{Kind: KindFlow, Name: "ingest"}); err == nil { - t.Fatal("MapDeployment without image succeeded") - } - if _, err := MapDeployment(Resource{Kind: "Job", Name: "job", Spec: WorkloadSpec{Image: "job:latest"}}); err == nil { - t.Fatal("MapDeployment with unsupported kind succeeded") - } -} diff --git a/deploy/kubernetes/manifests.go b/deploy/kubernetes/manifests.go deleted file mode 100644 index 4a66649fbc..0000000000 --- a/deploy/kubernetes/manifests.go +++ /dev/null @@ -1,32 +0,0 @@ -package kubernetes - -import ( - "embed" - "fmt" -) - -// crdFS holds the canonical CRD manifests. They live as real YAML under -// config/crd/ so they can be applied directly (`kubectl apply -f -// deploy/kubernetes/config/crd/`) and are embedded here so the Go API serves -// the exact same bytes — one source of truth, no drift. -// -//go:embed config/crd/agent.yaml config/crd/service.yaml config/crd/flow.yaml -var crdFS embed.FS - -// CRDManifests contains the alpha CRDs for Go Micro lifecycle resources, loaded -// from the embedded config/crd/ YAML. -var CRDManifests = map[Kind]string{ - KindAgent: mustCRD("agent"), - KindService: mustCRD("service"), - KindFlow: mustCRD("flow"), -} - -// mustCRD reads an embedded CRD manifest. The files are embedded at compile -// time, so a read error means a build/packaging bug, not a runtime condition. -func mustCRD(name string) string { - b, err := crdFS.ReadFile("config/crd/" + name + ".yaml") - if err != nil { - panic(fmt.Sprintf("kubernetes: embedded CRD %q missing: %v", name, err)) - } - return string(b) -} diff --git a/deploy/kubernetes/reconcile.go b/deploy/kubernetes/reconcile.go deleted file mode 100644 index 734db04054..0000000000 --- a/deploy/kubernetes/reconcile.go +++ /dev/null @@ -1,110 +0,0 @@ -package kubernetes - -import ( - "fmt" - "reflect" -) - -// Reconcile is the pure decision core an operator's reconcile loop runs: given -// a desired resource and the currently observed cluster state, it computes the -// one action needed to converge (create / update / nothing) plus the status -// conditions to publish. It does not talk to a cluster — no controller-runtime, -// no client-go — so the whole convergence decision is unit-testable. An adapter -// binary supplies Observed from the live cluster and applies the returned -// Action; that adapter is the only piece that needs the Kubernetes client. - -// ActionType is the change a reconcile wants applied. -type ActionType string - -const ( - // ActionCreate means the workload does not exist yet and should be created. - ActionCreate ActionType = "create" - // ActionUpdate means the workload exists but drifts from desired. - ActionUpdate ActionType = "update" - // ActionNoop means the workload already matches desired. - ActionNoop ActionType = "noop" -) - -// Action is the change Reconcile decided on, carrying the desired Deployment. -type Action struct { - Type ActionType - Deployment Deployment -} - -// Observed is the current cluster state Reconcile compares against. The adapter -// fills it from the live cluster; a nil Deployment means "not created yet". -type Observed struct { - // Service is the currently observed ClusterIP service, or nil if absent. - Service *NetworkService - // Deployment is the workload as it currently exists, or nil if absent. - Deployment *Deployment - // ReadyReplicas is how many pods are ready, from the live Deployment status. - ReadyReplicas int32 -} - -// Condition is a status condition to publish on the resource — the ready/error -// signal for the inner-loop and deploy story. It mirrors the Kubernetes -// condition shape without importing the API types. -type Condition struct { - Type string `json:"type"` // "Ready" | "Error" - Status string `json:"status"` // "True" | "False" | "Unknown" - Reason string `json:"reason"` - Message string `json:"message,omitempty"` -} - -// Reconcile computes the action to bring observed toward desired, plus the -// status conditions. A spec that fails to map returns an Error condition and -// the error (no action). -func Reconcile(desired Resource, observed Observed) (Action, []Condition, error) { - want, err := MapDeployment(desired) - if err != nil { - return Action{}, []Condition{{ - Type: "Error", Status: "True", Reason: "InvalidSpec", Message: err.Error(), - }}, err - } - - var action Action - switch { - case observed.Deployment == nil: - action = Action{Type: ActionCreate, Deployment: want} - case deploymentDiffers(*observed.Deployment, want): - action = Action{Type: ActionUpdate, Deployment: want} - default: - action = Action{Type: ActionNoop, Deployment: want} - } - - return action, conditions(want, observed), nil -} - -// conditions derives the Ready condition from observed state against desired. -func conditions(want Deployment, observed Observed) []Condition { - switch { - case observed.Deployment == nil: - return []Condition{{ - Type: "Ready", Status: "False", Reason: "Creating", - Message: "workload not yet created", - }} - case deploymentDiffers(*observed.Deployment, want): - return []Condition{{Type: "Ready", Status: "False", Reason: "Updating", Message: "workload spec is changing"}} - case observed.ReadyReplicas < want.Replicas: - return []Condition{{ - Type: "Ready", Status: "False", Reason: "Progressing", - Message: fmt.Sprintf("%d/%d replicas ready", observed.ReadyReplicas, want.Replicas), - }} - default: - return []Condition{{ - Type: "Ready", Status: "True", Reason: "Available", - Message: fmt.Sprintf("%d/%d replicas ready", observed.ReadyReplicas, want.Replicas), - }} - } -} - -// deploymentDiffers reports whether the observed deployment drifts from desired -// on the fields this operator manages (replicas, container, labels). Fields the -// cluster owns (status, cluster-assigned metadata) are intentionally ignored. -func deploymentDiffers(current, want Deployment) bool { - return current.Replicas != want.Replicas || - !reflect.DeepEqual(current.Pod.Container, want.Pod.Container) || - !reflect.DeepEqual(current.Labels, want.Labels) || - !reflect.DeepEqual(current.Pod.Labels, want.Pod.Labels) -} diff --git a/deploy/kubernetes/reconcile_test.go b/deploy/kubernetes/reconcile_test.go deleted file mode 100644 index c96750fb0c..0000000000 --- a/deploy/kubernetes/reconcile_test.go +++ /dev/null @@ -1,88 +0,0 @@ -package kubernetes - -import "testing" - -func agentResource() Resource { - return Resource{ - Kind: KindAgent, - Name: "support", - Namespace: "agents", - Spec: WorkloadSpec{Image: "example/support:v1", Replicas: 2, Registry: "kubernetes"}, - } -} - -func TestReconcileCreatesWhenAbsent(t *testing.T) { - action, conds, err := Reconcile(agentResource(), Observed{Deployment: nil}) - if err != nil { - t.Fatalf("Reconcile: %v", err) - } - if action.Type != ActionCreate { - t.Fatalf("action = %q, want create", action.Type) - } - if action.Deployment.Name != "support" || action.Deployment.Replicas != 2 { - t.Fatalf("desired deployment = %+v", action.Deployment) - } - if ready := findCondition(conds, "Ready"); ready == nil || ready.Status != "False" || ready.Reason != "Creating" { - t.Fatalf("ready condition = %+v, want False/Creating", ready) - } -} - -func TestReconcileNoopWhenMatchedAndReady(t *testing.T) { - want, _ := MapDeployment(agentResource()) - action, conds, err := Reconcile(agentResource(), Observed{Deployment: &want, ReadyReplicas: 2}) - if err != nil { - t.Fatalf("Reconcile: %v", err) - } - if action.Type != ActionNoop { - t.Fatalf("action = %q, want noop", action.Type) - } - if ready := findCondition(conds, "Ready"); ready == nil || ready.Status != "True" || ready.Reason != "Available" { - t.Fatalf("ready condition = %+v, want True/Available", ready) - } -} - -func TestReconcileUpdatesOnDrift(t *testing.T) { - current, _ := MapDeployment(agentResource()) - current.Pod.Container.Image = "example/support:v0" // stale image → drift - action, _, err := Reconcile(agentResource(), Observed{Deployment: ¤t, ReadyReplicas: 2}) - if err != nil { - t.Fatalf("Reconcile: %v", err) - } - if action.Type != ActionUpdate { - t.Fatalf("action = %q, want update", action.Type) - } - if action.Deployment.Pod.Container.Image != "example/support:v1" { - t.Fatalf("update should carry the desired image, got %q", action.Deployment.Pod.Container.Image) - } -} - -func TestReconcileProgressingWhenUnderReplicated(t *testing.T) { - want, _ := MapDeployment(agentResource()) - _, conds, err := Reconcile(agentResource(), Observed{Deployment: &want, ReadyReplicas: 1}) - if err != nil { - t.Fatalf("Reconcile: %v", err) - } - if ready := findCondition(conds, "Ready"); ready == nil || ready.Status != "False" || ready.Reason != "Progressing" { - t.Fatalf("ready condition = %+v, want False/Progressing", ready) - } -} - -func TestReconcileErrorOnInvalidSpec(t *testing.T) { - // Missing image → MapDeployment fails → Error condition, no action. - _, conds, err := Reconcile(Resource{Kind: KindService, Name: "api"}, Observed{}) - if err == nil { - t.Fatal("Reconcile should error on an invalid spec") - } - if e := findCondition(conds, "Error"); e == nil || e.Status != "True" || e.Reason != "InvalidSpec" { - t.Fatalf("error condition = %+v, want True/InvalidSpec", e) - } -} - -func findCondition(conds []Condition, typ string) *Condition { - for i := range conds { - if conds[i].Type == typ { - return &conds[i] - } - } - return nil -} diff --git a/deploy/kubernetes/types.go b/deploy/kubernetes/types.go deleted file mode 100644 index 356e7254c3..0000000000 --- a/deploy/kubernetes/types.go +++ /dev/null @@ -1,154 +0,0 @@ -package kubernetes - -import ( - "fmt" - "sort" - "strings" -) - -const ( - // Group is the API group for the alpha Go Micro Kubernetes resources. - Group = "micro.dev" - // Version is the current alpha API version for the CRDs in this package. - Version = "v1alpha1" -) - -// Kind identifies a Go Micro lifecycle resource that can be reconciled toward a -// Kubernetes Deployment. -type Kind string - -const ( - KindAgent Kind = "Agent" - KindService Kind = "Service" - KindFlow Kind = "Flow" -) - -// WorkloadSpec is the common alpha spec shared by Agent, Service, and Flow CRDs. -type WorkloadSpec struct { - // Port is the workload RPC port (default 8080). - Port int32 `json:"port,omitempty"` - Image string `json:"image"` - Command []string `json:"command,omitempty"` - Args []string `json:"args,omitempty"` - Replicas int32 `json:"replicas,omitempty"` - Registry string `json:"registry,omitempty"` - Environment map[string]string `json:"env,omitempty"` -} - -// Resource is the minimal desired state for a Go Micro lifecycle resource. -type Resource struct { - // UID enables Kubernetes garbage-collection ownership on rendered workloads. - UID string - Kind Kind - Name string - Namespace string - Spec WorkloadSpec -} - -// Deployment is a small, dependency-free representation of the Kubernetes -// Deployment fields the alpha reconciler skeleton owns. -type Deployment struct { - Name string - Namespace string - Labels map[string]string - Replicas int32 - Pod PodTemplate -} - -// PodTemplate describes the pod fields emitted by MapDeployment. -type PodTemplate struct { - Labels map[string]string - Container Container -} - -// Container describes the single Go Micro workload container. -type Container struct { - Port int32 - PortName string - Protocol string - Name string - Image string - Command []string - Args []string - Environment map[string]string -} - -// MapDeployment maps a Go Micro alpha resource to the Deployment shape an -// operator reconciliation loop would apply. -func MapDeployment(resource Resource) (Deployment, error) { - if resource.Kind != KindAgent && resource.Kind != KindService && resource.Kind != KindFlow { - return Deployment{}, fmt.Errorf("unsupported kind %q", resource.Kind) - } - name := strings.TrimSpace(resource.Name) - if name == "" { - return Deployment{}, fmt.Errorf("name is required") - } - if resource.Spec.Port < 0 || resource.Spec.Port > 65535 { - return Deployment{}, fmt.Errorf("spec.port must be between 1 and 65535") - } - image := strings.TrimSpace(resource.Spec.Image) - if image == "" { - return Deployment{}, fmt.Errorf("spec.image is required") - } - - namespace := strings.TrimSpace(resource.Namespace) - if namespace == "" { - namespace = "default" - } - replicas := resource.Spec.Replicas - if replicas == 0 { - replicas = 1 - } - - labels := map[string]string{ - "app.kubernetes.io/name": name, - "app.kubernetes.io/managed-by": "go-micro", - "micro.dev/kind": strings.ToLower(string(resource.Kind)), - } - env := copyMap(resource.Spec.Environment) - if _, configured := env["MICRO_SERVER_ADDRESS"]; !configured { - env["MICRO_SERVER_ADDRESS"] = fmt.Sprintf(":%d", workloadPort(resource)) - } - if resource.Spec.Registry != "" { - env["MICRO_REGISTRY"] = resource.Spec.Registry - } - - return Deployment{ - Name: name, - Namespace: namespace, - Labels: copyMap(labels), - Replicas: replicas, - Pod: PodTemplate{ - Labels: copyMap(labels), - Container: Container{ - Name: name, - Port: workloadPort(resource), - PortName: "rpc", - Protocol: "TCP", - Image: image, - Command: append([]string(nil), resource.Spec.Command...), - Args: append([]string(nil), resource.Spec.Args...), - Environment: env, - }, - }, - }, nil -} - -// EnvironmentKeys returns stable environment variable keys from a mapped -// container. It is useful for deterministic validation and rendering. -func (c Container) EnvironmentKeys() []string { - keys := make([]string, 0, len(c.Environment)) - for key := range c.Environment { - keys = append(keys, key) - } - sort.Strings(keys) - return keys -} - -func copyMap(in map[string]string) map[string]string { - out := make(map[string]string, len(in)) - for k, v := range in { - out[k] = v - } - return out -} diff --git a/examples/INDEX.md b/examples/INDEX.md index 97ec4ca734..902a7ef8b7 100644 --- a/examples/INDEX.md +++ b/examples/INDEX.md @@ -1,7 +1,7 @@ # Examples wayfinding Use this index when you want the shortest path from a first runnable agent to the -next services, agents, workflows, and interop examples. Every command below is +next services, agents, and interop examples. Every command below is provider-free unless the example README says otherwise. ## Pick by goal @@ -15,7 +15,6 @@ provider-free unless the example README says otherwise. | Try a paid tool with x402 | [`agent-x402-buyer`](./agent-x402-buyer/) | `go run ./examples/agent-x402-buyer` | [`Payments (x402)` guide](../internal/website/docs/guides/x402-payments.md) | | Try A2A or gRPC interop next | [`agent-demo`](./agent-demo/) plus gateway docs | run the example, then use the gateway docs | [`grpc`](./grpc/) and [`grpc-interop`](./grpc-interop/) | | Call a service with grpcurl | [`grpc`](./grpc/) | `grpcurl -plaintext localhost:8080 list` then `grpcurl -plaintext -d '{"name":"World"}' localhost:8080 helloworld.Say.Hello` | [`grpc-interop`](./grpc-interop/) | -| Add workflow durability | [`flow-durable`](./flow-durable/) | `go run ./examples/flow-durable` | [`flow-loop`](./flow-loop/) | ## Recommended adoption path @@ -26,14 +25,12 @@ provider-free unless the example README says otherwise. no provider key. 3. **0→hero reference:** run [`support`](./support/) with `go run ./examples/support`; it keeps typed services, an agent chat loop, an - event-driven flow, and an approval gate in one maintained example. + approval gate in one maintained example. 4. **Interop next:** use [`mcp/hello`](./mcp/hello/), [`mcp/crud`](./mcp/crud/), and [`mcp/workflow`](./mcp/workflow/) when you are ready to expose tools to external AI clients. 5. **Paid tools:** run [`agent-x402-buyer`](./agent-x402-buyer/) to see an agent pay a local x402-protected tool with a mock facilitator and budget. -6. **Workflow depth:** use [`flow-durable`](./flow-durable/) once the agent path - needs checkpointed, resumable deterministic work. ## CLI wayfinding diff --git a/examples/README.md b/examples/README.md index 5ff346dfd5..b7f91b6988 100644 --- a/examples/README.md +++ b/examples/README.md @@ -2,7 +2,7 @@ This directory contains runnable examples that take you through the Go Micro lifecycle: start with a service, expose it as agent-usable capability, then -coordinate work with workflows. +call services from agents. ## Quick Start @@ -13,13 +13,14 @@ or follow the first-agent path below instead of reading the directories alphabet ## Recommended first-agent path -This path is the canonical services → agents → workflows route through the examples map. Debugging and observability wayfinding stays nearby once the first run works. +This path is the canonical services → agents route through the examples map. Debugging and observability wayfinding stays nearby once the first run works. | Step | Start here | What you learn | Next step | |------|------------|----------------|-----------| | 1. First service | [`hello-world`](./hello-world/) | Build the 0→1 service path: create and register a basic RPC service, add a handler, call it with a client, and expose health checks. | Move to [`agent-demo`](./agent-demo/) to see services used by an agent. | | 2. First agent | [`first-agent`](./first-agent/) | Run the smallest service-backed agent with a deterministic mock model and no provider key. | Compare with [`agent-demo`](./agent-demo/) or the maintained 0-to-hero path in [`support`](./support/). | -| 3. First workflow | [`support`](./support/) | Follow typed services into an agent chat loop, an event-driven `intake` flow, and an approval gate in one runnable reference. | Deepen the workflow model with [`flow-durable`](./flow-durable/). | + +| 3. Support agent | [`support`](./support/) | Call typed services through an agent with an approval gate. | Inspect the result and adapt the tools. | For the shortest AI-tooling bridge, the MCP path is [`mcp/hello`](./mcp/hello/) → [`mcp/crud`](./mcp/crud/) → @@ -107,24 +108,7 @@ before the run can continue. Local-model agent wiring for developers experimenting with Ollama-backed model calls. -### 3. Workflows — coordinate longer-running work - -#### [support](./support/) -A maintained 0-to-hero reference path in one runnable file: -- **scaffold** typed `customers`, `tickets`, and `notify` services -- **run/chat** with a support agent that uses those services as tools -- **inspect** the event-driven `intake` flow and approval gate -- **CI** keeps the deterministic mock-model journey runnable with `go test ./examples/support` - -#### [flow-durable](./flow-durable/) -A workflow as ordered, checkpointed steps that survives a crash and resumes where it stopped: -- **steps** — a flow is a task with stages (`reserve → charge → confirm`), not just one LLM turn -- **Checkpoint** — each step is persisted; on `Resume`, completed steps are not re-run (no duplicate side effects) - -#### [flow-loop](./flow-loop/) -A looping flow example for repeated workflow steps. - -### 4. MCP and agent integration examples +### 3. MCP and agent integration examples See the [mcp/](./mcp/) directory for AI agent integration examples: - **[hello](./mcp/hello/)** - Minimal MCP service (start here) diff --git a/examples/agent-durable/README.md b/examples/agent-durable/README.md index f498b3cb7a..c9b9610d87 100644 --- a/examples/agent-durable/README.md +++ b/examples/agent-durable/README.md @@ -1,10 +1,7 @@ # Durable agent run resume -This example shows the agent-side counterpart to `examples/flow-durable`: an -agent run is checkpointed with the same `Checkpoint` interface used by flows, -then resumed after an interruption without repeating a completed side effect. -The sample uses an in-memory store to keep repeated local runs deterministic; -use your service store for process-restart recovery. +This example shows an agent run checkpointed through `agent.Checkpoint`, +so interrupted work can resume without repeating recorded tool results. Run it with: @@ -17,31 +14,3 @@ after the tool call was checkpointed. `micro.AgentPending` finds the unfinished run and `micro.AgentResume` continues it from the saved checkpoint. The final `tool executions: 1` line is the important bit: the reservation tool was not called a second time during resume. - -## When to use this instead of a durable flow - -Use a durable flow when the path is known ahead of time: ordered service calls, -retries, timers, compensation, and a precise resume stage such as `reserve` or -`charge`. Use a checkpointed agent run when the path is open-ended and the model -may choose tools dynamically, and reuse tool results whose completion has already been saved. A side effect -that succeeds before its checkpoint is saved can still repeat. See the -[durability contract](../../internal/website/content/en/docs/guides/durability.md) -for tool identity, storage failure, and recovery limitations. - -They compose: keep deterministic business process in `flow-durable`, then hand -off the judgment-heavy step to a checkpointed agent when the workflow needs -model-directed tool use. Both use the same `Checkpoint` backend, so inspection -and recovery can share one run-history store. - -In a service, use the same pattern at startup: - -```go -pending, _ := micro.AgentPending(ctx, agent) -for _, run := range pending { - _, _ = micro.AgentResume(ctx, agent, run.ID) -} -``` - -`context.Context` cancellation and deadlines are still honored by checkpoint -loads/saves, model calls, and tool calls. Runs with terminal statuses such as -`done`, `canceled`, and `expired` are not returned by `AgentPending`. diff --git a/examples/flow-durable/README.md b/examples/flow-durable/README.md deleted file mode 100644 index d32e5a24ef..0000000000 --- a/examples/flow-durable/README.md +++ /dev/null @@ -1,73 +0,0 @@ -# Durable Flow - -A workflow that survives a crash and resumes where it stopped. - -A `flow` can be an ordered list of **steps** — a task with stages — -instead of a single LLM turn. Each step is checkpointed before and after -through a pluggable `Checkpoint` (store-backed by default), so if the -process dies mid-run, the run resumes at the step it stopped on, without -re-running steps whose completion was successfully checkpointed. A step -interrupted before that save can repeat its side effects; see the -[durability contract](../../internal/website/content/en/docs/guides/durability.md). - -## What this shows - -A three-step checkout (`reserve → charge → confirm`) whose `charge` step -fails the first time, simulating a transient outage / crash: - -``` -first run: - reserve → inventory reserved - charge → payment dependency unavailable (crash) - run failed: payment gateway timeout - -checkpoint: run 70643f61 is at step "charge" (status failed) - -resume: - charge → payment captured - confirm → order confirmed - -reserve ran 1 time(s) total — completed steps are not repeated on resume -no pending runs — the workflow completed durably -``` - -The key line is the last pair: on `Resume`, `reserve` does **not** run -again — its result was checkpointed — and the run finishes. - -## The pieces - -```go -f := micro.NewFlow("checkout", - micro.FlowSteps( - micro.FlowStep{Name: "reserve", Run: reserve}, - micro.FlowStep{Name: "charge", Run: charge}, - micro.FlowStep{Name: "confirm", Run: confirm}, - ), - micro.FlowWithCheckpoint(micro.StoreCheckpoint(nil, "checkout")), // nil store = default; "checkout" = key scope -) - -f.Execute(ctx, `{}`) // runs; crashes at charge -pending, _ := f.Pending(ctx) // the run, checkpointed at "charge" -f.Resume(ctx, pending[0].ID) // continues from charge to the end -``` - -- **`State`** carries a typed payload (`Set`/`Scan`) plus a `Stage` - marker — the resume point. -- **`Checkpoint`** persists each `Run`. The built-in is store-backed and - keeps each flow's runs in their own store table (database `flow`, table - `checkout`) via `store.Scope`, so one flow's runs don't share a table - with another's — or with agent or service state. The default file store survives a process restart when its files are - retained. Other stores can be selected explicitly; `Checkpoint` alone does - not supply an external-engine adapter or exactly-once execution. -- A real step would be `flow.Call(service, endpoint)` (an RPC), - `flow.Dispatch(agent)` (hand off to an agent), or `flow.LLM(prompt)` - (one model turn). Here they're plain funcs so durability is the only - thing on display. - -## Run - -```bash -go run main.go -``` - -No LLM key required. diff --git a/examples/flow-durable/main.go b/examples/flow-durable/main.go deleted file mode 100644 index 1c6cfd712b..0000000000 --- a/examples/flow-durable/main.go +++ /dev/null @@ -1,114 +0,0 @@ -// Durable Flow — a workflow that survives a crash and resumes -// -// A flow can be an ordered list of steps (a task with stages) rather than -// a single LLM turn. Each step is checkpointed before and after through a -// pluggable Checkpoint (store-backed by default), so if the process dies -// mid-run, the run resumes at the step it stopped on — without re-running -// the steps that already completed (and already had their side effects). -// -// This example needs no LLM key. It runs a three-step checkout flow whose -// "charge" step fails the first time (a transient outage). The run is -// checkpointed as failed at that step; we then "recover" the dependency -// and Resume — and the already-completed "reserve" step does not run -// again. A real step would call a service (flow.Call), an agent -// (flow.Dispatch), or the model (flow.LLM); here they're plain funcs so -// the durability is the only thing on display. -package main - -import ( - "context" - "errors" - "fmt" - - "go-micro.dev/v6" -) - -// Order is the payload carried across steps via State.Set / State.Scan. -type Order struct { - ID string `json:"id"` - Reserved bool `json:"reserved"` - Charged bool `json:"charged"` - Confirmed bool `json:"confirmed"` -} - -// charged toggles the transient failure: 0 = the payment dependency is -// down (first run), 1 = recovered (on resume). -var charged int - -// reserveCalls proves the completed step is not re-run on resume. -var reserveCalls int - -func reserve(_ context.Context, in micro.FlowState) (micro.FlowState, error) { - reserveCalls++ - var o Order - in.Scan(&o) - o.ID = "order-1" - o.Reserved = true - fmt.Println(" reserve → inventory reserved") - return in, in.Set(o) -} - -func charge(_ context.Context, in micro.FlowState) (micro.FlowState, error) { - var o Order - in.Scan(&o) - if charged == 0 { - fmt.Println(" charge → payment dependency unavailable (crash)") - return in, errors.New("payment gateway timeout") - } - o.Charged = true - fmt.Println(" charge → payment captured") - return in, in.Set(o) -} - -func confirm(_ context.Context, in micro.FlowState) (micro.FlowState, error) { - var o Order - in.Scan(&o) - o.Confirmed = true - fmt.Println(" confirm → order confirmed") - return in, in.Set(o) -} - -func main() { - f := micro.NewFlow("checkout", - micro.FlowSteps( - micro.FlowStep{Name: "reserve", Run: reserve}, - micro.FlowStep{Name: "charge", Run: charge}, - micro.FlowStep{Name: "confirm", Run: confirm}, - ), - // Durable by default; shown explicitly. Runs are namespaced under - // the flow name ("flow/checkout/runs/..."), so this flow's state - // doesn't share a keyspace with other flows. Point the default - // store at Postgres or NATS KV to survive a real process restart. - micro.FlowWithCheckpoint(micro.StoreCheckpoint(nil, "checkout")), - ) - - ctx := context.Background() - - fmt.Println("first run:") - if err := f.Execute(ctx, `{}`); err != nil { - fmt.Printf(" run failed: %v\n", err) - } - - pending, _ := f.Pending(ctx) - if len(pending) == 0 { - fmt.Println("nothing pending — unexpected") - return - } - run := pending[0] - fmt.Printf("\ncheckpoint: run %s is at step %q (status %s)\n", - run.ID[:8], run.State.Stage, run.Status) - - // The dependency recovers (or a new process picks the run up). - charged = 1 - - fmt.Println("\nresume:") - if err := f.Resume(ctx, run.ID); err != nil { - fmt.Printf(" resume failed: %v\n", err) - return - } - - fmt.Printf("\nreserve ran %d time(s) total — completed steps are not repeated on resume\n", reserveCalls) - if pend, _ := f.Pending(ctx); len(pend) == 0 { - fmt.Println("no pending runs — the workflow completed durably") - } -} diff --git a/examples/flow-loop/main.go b/examples/flow-loop/main.go deleted file mode 100644 index 486086d7ba..0000000000 --- a/examples/flow-loop/main.go +++ /dev/null @@ -1,71 +0,0 @@ -// Agentic Loop — keep working until the goal is met, with a guaranteed ceiling -// -// The "loop" pattern from agentic AI: instead of one shot, run a step over -// and over until the goal is reached, letting it decide when to stop — but -// always bounded by a hard iteration cap (the guardrail) so it can never run -// away, or run up an unbounded bill. -// -// flow.Loop is just a flow step, so it composes with the normal checkpointed -// step engine. This example needs no LLM key: the body is a plain func that -// "improves a draft" each pass, and a code-defined Until stops it once the -// draft is good enough — capped by FlowLoopMax. In a real flow the body would -// be micro.FlowDispatch("coder") (an agent) or micro.FlowLLM(...), and the -// stop check micro.FlowUntilLLM("Is the work complete?") — the supervised -// "Ralph" loop, where the model decides it's done but the cap still bounds it. -package main - -import ( - "context" - "fmt" - - "go-micro.dev/v6" -) - -// Draft is the payload carried across iterations via State.Set / State.Scan. -type Draft struct { - Text string `json:"text"` - Quality int `json:"quality"` // 0..100, improved each pass -} - -// improve is one loop pass: it refines the draft a bit. In a real flow this -// would be an agent or an LLM turn; here it's deterministic so the example -// runs offline. -func improve(_ context.Context, in micro.FlowState) (micro.FlowState, error) { - var d Draft - _ = in.Scan(&d) - d.Quality += 30 - d.Text = fmt.Sprintf("draft refined (quality %d)", d.Quality) - return in, in.Set(d) -} - -func main() { - const goodEnough = 90 - - f := micro.NewFlow("refine", - micro.FlowSteps( - micro.FlowStep{Name: "improve", Run: micro.FlowLoop( - improve, - // Stop early once the draft is good enough... - micro.FlowUntil(func(_ context.Context, s micro.FlowState, iter int) (bool, error) { - var d Draft - _ = s.Scan(&d) - fmt.Printf(" pass %d → quality %d\n", iter, d.Quality) - return d.Quality >= goodEnough, nil - }), - // ...but never run the body more than 10 times (the ceiling). - micro.FlowLoopMax(10), - )}, - ), - micro.FlowDeleteOnSuccess(), - ) - - fmt.Println("refining until quality >=", goodEnough) - if err := f.Execute(context.Background(), `{"text":"initial draft","quality":0}`); err != nil { - fmt.Println("flow error:", err) - return - } - - for _, r := range f.Results() { - fmt.Printf("\ndone: %s\n", r.Answer) - } -} diff --git a/examples/support/README.md b/examples/support/README.md index f4f68e4290..1a925e63ac 100644 --- a/examples/support/README.md +++ b/examples/support/README.md @@ -2,7 +2,7 @@ A maintained 0-to-hero reference for the Go Micro lifecycle: scaffold a few typed services, run them in one process, let an agent chat with those services -as tools, then inspect the durable flow that triggered the work. It is one +as tools, then inspect the agent result. It is one runnable file and one CI smoke test, so the reference path stays honest as the framework evolves. @@ -12,19 +12,17 @@ framework evolves. typed Go Micro services. Their request/response structs and method comments become the tool contract the agent sees. 2. **Run the harness** — the example starts an in-memory registry, broker, - client, store, services, agent, and flow in one process; no external + client, store, services and agent in one process; no external dependencies or API key are required for the default run. -3. **Chat through an agent** — the `support` agent receives the ticket event as +3. **Chat through an agent** — the `support` agent receives the ticket as a prompt and calls service tools to look up the customer, triage the ticket, and draft a reply. -4. **Inspect the workflow** — the `intake` flow records the event-driven run and - prints the agent result, showing the service → agent → workflow lifecycle as - one runtime. +4. **Inspect the agent** — the example prints tool calls, the approval decision + and the agent response. ## The scenario -A customer files a ticket. A `ticket.created` event triggers the support -agent, which: +A customer files a ticket. A request asks the support agent, which: 1. looks the customer up (`customers` service), 2. sets the ticket's priority (`tickets` service), @@ -32,14 +30,14 @@ agent, which: the approval gate.** ``` -> event: events.ticket.created {"id":"ticket-1","customer":"alice@acme.com",...} +> ticket: {"id":"ticket-1","customer":"alice@acme.com",...} [customers] looked up Alice (pro plan) [tickets] ticket-1 → priority=high status=in_progress ▣ approval gate notify_NotifyService_Send(alice@acme.com) — approved [notify] 📨 to=alice@acme.com: "Hi Alice — thanks for reaching out..." -✓ ticket triaged and the customer was replied to — triggered by an event +✓ ticket triaged and the customer was replied to — handled by the agent ``` ## The pieces @@ -48,8 +46,6 @@ agent, which: agent discovers their endpoints as tools automatically. - **Agent** (`support`) — `micro.NewAgent` with those three services. It reasons over the ticket and calls the tools. -- **Flow** (`intake`) — triggers on `events.ticket.created` and hands the event to - the agent: *the event is the prompt*. No human types anything. - **Guardrail** (`ApproveTool`) — the agent can read and triage freely, but emailing a customer (`notify.Send`) passes through the gate first. Return `false` to hold it for a person or a policy; the example approves and logs. @@ -57,12 +53,12 @@ agent, which: ## Expected inspect transcript The provider-free run prints the same visible checkpoints a new developer should -compare against after chat and flow execution. The transcript includes service +compare against after agent execution. The transcript includes service tool calls, the approval gate, and the inspect/run-history commands that prove -the workflow run was recorded. +the agent handled the request. ```text -> event: events.ticket.created {"customer":"alice@acme.com","id":"ticket-1","subject":"Can't log in"} +> ticket: {"customer":"alice@acme.com","id":"ticket-1","subject":"Can't log in"} [customers] looked up Alice (pro plan) [tickets] ticket-1 → priority=high status=in_progress @@ -72,12 +68,9 @@ the workflow run was recorded. support agent: Triaged ticket-1 for Alice and sent a reply. inspect transcript: - micro inspect flow intake - flow: intake runs=1 latest.reply="Triaged ticket-1 for Alice and sent a reply." micro agent history support - agent: support runs=1 latest.status=completed -✓ ticket triaged and the customer was replied to — triggered by an event +✓ ticket triaged and the customer was replied to — handled by the agent ``` ## Run diff --git a/examples/support/main.go b/examples/support/main.go index e74fdc2252..76940af595 100644 --- a/examples/support/main.go +++ b/examples/support/main.go @@ -1,10 +1,9 @@ -// Support desk — a real-world agent built from services, a flow, and a +// Support desk — a real-world agent built from services and a // guardrail. It's the "zero to hero" shape: a few services, an agent that -// manages them, an event that triggers the agent, and a human-in-the-loop +// manages them, a request to the agent, and a human-in-the-loop // gate on the one action that touches a customer. // -// The scenario: a customer files a ticket. A ticket.created event triggers -// the support agent, which looks the customer up, sets the ticket's +// The scenario: a customer files a ticket. The support agent looks the customer up, sets the ticket's // priority, and drafts a reply — but it can't actually email the customer // without passing the approval gate. // @@ -31,7 +30,6 @@ import ( "go-micro.dev/v6/agent" "go-micro.dev/v6/broker" "go-micro.dev/v6/client" - "go-micro.dev/v6/flow" "go-micro.dev/v6/model" "go-micro.dev/v6/registry" "go-micro.dev/v6/selector" @@ -270,48 +268,21 @@ func runSupport(provider string) error { waitFor(reg, "customers", "tickets", "notify", "support") - // A new ticket arrives, and a flow turns the event into work for the - // agent: the event is the prompt. - intake := flow.New("intake", - flow.Trigger("events.ticket.created"), - flow.Agent("support"), - flow.Prompt("A new support ticket arrived: {{.Data}}. Handle it."), - ) - if err := intake.Register(reg, br, cl); err != nil { - return fmt.Errorf("flow register: %w", err) - } - defer intake.Stop() - - // The customer files a ticket (it exists before the event fires). + // Create the ticket before asking the agent to handle it. tickets.seed(&Ticket{ID: "ticket-1", Customer: "alice@acme.com", Subject: "Can't log in", Body: "I'm locked out.", Status: "open"}) body, _ := json.Marshal(map[string]string{"id": "ticket-1", "customer": "alice@acme.com", "subject": "Can't log in"}) - fmt.Println("\033[1m> event:\033[0m events.ticket.created", string(body)) + fmt.Println("\033[1m> ticket:\033[0m", string(body)) fmt.Println() - if err := br.Publish("events.ticket.created", &broker.Message{Body: body}); err != nil { - return fmt.Errorf("publish: %w", err) - } - - // Wait for the agent to act. - deadline := time.Now().Add(20 * time.Second) - for time.Now().Before(deadline) { - if notify.sent >= 1 { - break - } - time.Sleep(50 * time.Millisecond) - } - - if rs := intake.Results(); len(rs) > 0 { - latest := rs[len(rs)-1] - fmt.Printf("\n\033[1msupport agent:\033[0m %s\n", latest.Reply) - fmt.Println("\n\033[1minspect transcript:\033[0m") - fmt.Println(" micro inspect flow intake") - fmt.Printf(" flow: intake runs=%d latest.reply=%q\n", len(rs), latest.Reply) - fmt.Println(" micro agent history support") - fmt.Printf(" agent: support runs=%d latest.status=completed\n", len(rs)) + reply, err := support.Ask(context.Background(), "Handle this support ticket: "+string(body)) + if err != nil { + return err } + fmt.Printf("\nsupport agent: %s\n", reply.Reply) + fmt.Println("\ninspect transcript:") + fmt.Println(" micro agent history support") if notify.sent >= 1 { - fmt.Println("\n\033[32m✓ ticket triaged and the customer was replied to — triggered by an event\033[0m") + fmt.Println("\n\033[32m✓ ticket triaged and the customer was replied to — handled by the agent\033[0m") return nil } fmt.Println("\n\033[31m✗ the agent did not complete the triage\033[0m") diff --git a/examples/support/main_test.go b/examples/support/main_test.go index 280e05cbc6..5301f4aca2 100644 --- a/examples/support/main_test.go +++ b/examples/support/main_test.go @@ -25,7 +25,7 @@ func TestZeroToHeroReadmeDocumentsLifecycle(t *testing.T) { "Scaffold services", "Run the harness", "Chat through an agent", - "Inspect the workflow", + "Inspect the agent", "go test ./examples/support", } { if !strings.Contains(doc, want) { @@ -43,18 +43,15 @@ func TestZeroToHeroInspectTranscript(t *testing.T) { got := stripANSI(out) for _, want := range []string{ - `> event: events.ticket.created {"customer":"alice@acme.com","id":"ticket-1","subject":"Can't log in"}`, + `> ticket: {"customer":"alice@acme.com","id":"ticket-1","subject":"Can't log in"}`, `[customers] looked up Alice (pro plan)`, `[tickets] ticket-1 → priority=high status=in_progress`, `approval gate notify_NotifyService_Send(alice@acme.com) — approved`, `[notify] 📨 to=alice@acme.com: "Hi Alice — thanks for reaching out. We've bumped this to high priority and are on it."`, `support agent: Triaged ticket-1 for Alice and sent a reply.`, `inspect transcript:`, - `micro inspect flow intake`, - `flow: intake runs=1 latest.reply="Triaged ticket-1 for Alice and sent a reply."`, `micro agent history support`, - `agent: support runs=1 latest.status=completed`, - `✓ ticket triaged and the customer was replied to — triggered by an event`, + `✓ ticket triaged and the customer was replied to — handled by the agent`, } { if !strings.Contains(got, want) { t.Fatalf("support transcript missing %q\n--- got ---\n%s", want, got) @@ -67,9 +64,7 @@ func TestZeroToHeroInspectTranscript(t *testing.T) { } for _, want := range []string{ "Expected inspect transcript", - "micro inspect flow intake", "micro agent history support", - "agent: support runs=1 latest.status=completed", } { if !strings.Contains(string(readme), want) { t.Fatalf("README.md missing transcript contract %q", want) diff --git a/flow/analyze.go b/flow/analyze.go deleted file mode 100644 index c35270db7e..0000000000 --- a/flow/analyze.go +++ /dev/null @@ -1,212 +0,0 @@ -package flow - -import ( - "context" - "encoding/json" - "fmt" - "sort" - "strings" - "time" - - "go-micro.dev/v6/model" -) - -// AnalyzeOptions configures Analyze. -type AnalyzeOptions struct { - // MaxFeedbackSamples bounds the number of representative grader feedback - // strings retained per candidate. Values <= 0 use a small default. - MaxFeedbackSamples int -} - -// AnalyzeOption configures Analyze. -type AnalyzeOption func(*AnalyzeOptions) - -// AnalyzeMaxFeedbackSamples sets how many grader feedback examples are kept for -// each candidate in the report. -func AnalyzeMaxFeedbackSamples(n int) AnalyzeOption { - return func(o *AnalyzeOptions) { o.MaxFeedbackSamples = n } -} - -// Report is the machine-readable output of Analyze. Candidates are ordered from -// worst to best so an agent, CLI, or human can pick the first improvement to try. -type Report struct { - Candidates []Candidate `json:"candidates"` -} - -// Candidate identifies one underperforming flow step and the trace evidence that -// made it worth improving. -type Candidate struct { - Step string `json:"step"` - Metric string `json:"metric"` - Score float64 `json:"score"` - Runs int `json:"runs"` - Failures int `json:"failures"` - PassRate float64 `json:"pass_rate"` - ErrorRate float64 `json:"error_rate"` - AverageRetries float64 `json:"average_retries"` - P50Latency time.Duration `json:"p50_latency"` - P95Latency time.Duration `json:"p95_latency"` - SampleFeedback []string `json:"sample_feedback,omitempty"` - RunIDs []string `json:"run_ids,omitempty"` -} - -// Analyze aggregates a bounded window of persisted flow runs and returns ranked -// hill-climbing candidates. It uses the same Run records read by Checkpoint.List: -// failed verification fields in step results drive pass-rate and feedback, step -// status drives error rate, and retry attempts contribute retry pressure. An -// empty window returns an empty report. -func Analyze(runs []Run, opts ...AnalyzeOption) Report { - o := AnalyzeOptions{MaxFeedbackSamples: 3} - for _, opt := range opts { - opt(&o) - } - if o.MaxFeedbackSamples <= 0 { - o.MaxFeedbackSamples = 3 - } - - stats := map[string]*stepStats{} - for _, run := range runs { - for _, step := range run.Steps { - if step.Name == "" { - continue - } - s := stats[step.Name] - if s == nil { - s = &stepStats{} - stats[step.Name] = s - } - s.runs++ - s.runIDs = appendUnique(s.runIDs, run.ID) - if step.Attempts > 1 { - s.retries += step.Attempts - 1 - } - if step.Status == "failed" || step.Error != "" { - s.errors++ - } - if len(run.Steps) > 0 && !run.Started.IsZero() && !run.Updated.IsZero() { - s.latencies = append(s.latencies, run.Updated.Sub(run.Started)/time.Duration(len(run.Steps))) - } - passed, feedback, ok := verificationFields(step.Result) - if ok { - s.graded++ - if !passed { - s.gradeFailures++ - if feedback != "" && len(s.feedback) < o.MaxFeedbackSamples { - s.feedback = append(s.feedback, feedback) - } - } - } - } - } - - report := Report{} - for step, s := range stats { - if s.runs == 0 { - continue - } - failures := s.errors + s.gradeFailures - passRate := 1.0 - if s.graded > 0 { - passRate = float64(s.graded-s.gradeFailures) / float64(s.graded) - } else if s.errors > 0 { - passRate = float64(s.runs-s.errors) / float64(s.runs) - } - errorRate := float64(s.errors) / float64(s.runs) - avgRetries := float64(s.retries) / float64(s.runs) - score := float64(s.gradeFailures)*3 + float64(s.errors)*2 + avgRetries - metric := "pass_rate" - if s.gradeFailures == 0 && s.errors > 0 { - metric = "error_rate" - } else if s.gradeFailures == 0 && s.errors == 0 && s.retries > 0 { - metric = "retry_count" - } - report.Candidates = append(report.Candidates, Candidate{ - Step: step, Metric: metric, Score: score, Runs: s.runs, Failures: failures, - PassRate: passRate, ErrorRate: errorRate, AverageRetries: avgRetries, - P50Latency: percentile(s.latencies, 0.50), P95Latency: percentile(s.latencies, 0.95), - SampleFeedback: append([]string(nil), s.feedback...), RunIDs: append([]string(nil), s.runIDs...), - }) - } - sort.SliceStable(report.Candidates, func(i, j int) bool { - a, b := report.Candidates[i], report.Candidates[j] - if a.Score == b.Score { - return a.Step < b.Step - } - return a.Score > b.Score - }) - return report -} - -type stepStats struct { - runs, graded, gradeFailures, errors, retries int - feedback, runIDs []string - latencies []time.Duration -} - -// PromptOptimizer proposes prompt improvements for a candidate without mutating -// the source flow. Applying the returned prompt stays explicitly gated by the caller. -type PromptOptimizer struct{ model model.Model } - -// LLMOptimizer returns an optimizer that asks model to revise prompts for -// Analyze candidates. The model is injected so tests and callers can use mocks. -func LLMOptimizer(model model.Model) *PromptOptimizer { return &PromptOptimizer{model: model} } - -// OptimizePrompt asks the model for a revised prompt for candidate using the -// current prompt and trace feedback. It returns only the proposal; it never -// modifies a Flow, Step, or Checkpoint. -func (o *PromptOptimizer) OptimizePrompt(ctx context.Context, candidate Candidate, currentPrompt string) (string, error) { - if o == nil || o.model == nil { - return "", fmt.Errorf("flow: LLMOptimizer requires a model") - } - prompt := fmt.Sprintf("Revise this workflow step prompt to improve the failing step.\nStep: %s\nMetric: %s\nScore: %.2f\nFeedback:\n- %s\n\nCurrent prompt:\n%s\n\nReturn only the revised prompt.", candidate.Step, candidate.Metric, candidate.Score, strings.Join(candidate.SampleFeedback, "\n- "), currentPrompt) - resp, err := o.model.Generate(ctx, &model.Request{Prompt: prompt}) - if err != nil { - return "", err - } - proposal := strings.TrimSpace(resp.Answer) - if proposal == "" { - proposal = strings.TrimSpace(resp.Reply) - } - if proposal == "" { - return "", fmt.Errorf("flow: LLMOptimizer returned an empty prompt") - } - return proposal, nil -} - -func verificationFields(result string) (bool, string, bool) { - if result == "" { - return false, "", false - } - var obj map[string]any - if err := json.Unmarshal([]byte(result), &obj); err != nil { - return false, "", false - } - v, ok := obj["verification_passed"].(bool) - if !ok { - return false, "", false - } - fb, _ := obj["verification_feedback"].(string) - return v, fb, true -} - -func appendUnique(values []string, value string) []string { - if value == "" { - return values - } - for _, v := range values { - if v == value { - return values - } - } - return append(values, value) -} - -func percentile(values []time.Duration, p float64) time.Duration { - if len(values) == 0 { - return 0 - } - sorted := append([]time.Duration(nil), values...) - sort.Slice(sorted, func(i, j int) bool { return sorted[i] < sorted[j] }) - idx := int(float64(len(sorted)-1) * p) - return sorted[idx] -} diff --git a/flow/analyze_test.go b/flow/analyze_test.go deleted file mode 100644 index 2046cda68f..0000000000 --- a/flow/analyze_test.go +++ /dev/null @@ -1,89 +0,0 @@ -package flow - -import ( - "context" - "strings" - "testing" - "time" - - "go-micro.dev/v6/model" -) - -func TestAnalyzeRanksFailedGraderStepAbovePassingStep(t *testing.T) { - now := time.Now() - runs := []Run{ - {ID: "run-1", Started: now, Updated: now.Add(time.Second), Steps: []StepRecord{ - {Name: "draft", Status: "done", Attempts: 2, Result: `{"verification_passed":false,"verification_feedback":"cite sources"}`}, - {Name: "publish", Status: "done", Attempts: 1, Result: `{"verification_passed":true,"verification_feedback":"ok"}`}, - }}, - {ID: "run-2", Started: now, Updated: now.Add(2 * time.Second), Steps: []StepRecord{ - {Name: "draft", Status: "done", Attempts: 1, Result: `{"verification_passed":false,"verification_feedback":"too vague"}`}, - {Name: "publish", Status: "done", Attempts: 1, Result: `{"verification_passed":true,"verification_feedback":"ok"}`}, - }}, - } - - report := Analyze(runs) - if len(report.Candidates) != 2 { - t.Fatalf("Analyze returned %d candidates, want 2", len(report.Candidates)) - } - if got := report.Candidates[0].Step; got != "draft" { - t.Fatalf("top candidate = %q, want draft", got) - } - if report.Candidates[0].PassRate != 0 { - t.Fatalf("draft pass rate = %v, want 0", report.Candidates[0].PassRate) - } -} - -func TestAnalyzeCarriesFeedbackSamplesAndRunIDs(t *testing.T) { - report := Analyze([]Run{{ID: "run-9", Steps: []StepRecord{{ - Name: "grade", Status: "done", Attempts: 3, - Result: `{"verification_passed":false,"verification_feedback":"include totals"}`, - }}}}) - if len(report.Candidates) != 1 { - t.Fatalf("candidates = %d, want 1", len(report.Candidates)) - } - c := report.Candidates[0] - if len(c.SampleFeedback) != 1 || c.SampleFeedback[0] != "include totals" { - t.Fatalf("feedback = %#v, want include totals", c.SampleFeedback) - } - if len(c.RunIDs) != 1 || c.RunIDs[0] != "run-9" { - t.Fatalf("run ids = %#v, want run-9", c.RunIDs) - } - if c.AverageRetries != 2 { - t.Fatalf("average retries = %v, want 2", c.AverageRetries) - } -} - -func TestAnalyzeEmptyWindowReturnsEmptyReport(t *testing.T) { - if got := Analyze(nil); len(got.Candidates) != 0 { - t.Fatalf("empty Analyze candidates = %d, want 0", len(got.Candidates)) - } -} - -func TestLLMOptimizerReturnsProposalWithoutMutatingFlow(t *testing.T) { - f := New("optimize", Prompt("original prompt")) - before := f.opts.Prompt - optimizer := LLMOptimizer(&optimizerModel{reply: "revised prompt"}) - proposal, err := optimizer.OptimizePrompt(context.Background(), Candidate{Step: "draft", Metric: "pass_rate", SampleFeedback: []string{"cite sources"}}, before) - if err != nil { - t.Fatalf("OptimizePrompt returned error: %v", err) - } - if !strings.Contains(proposal, "revised") { - t.Fatalf("proposal = %q, want revised prompt", proposal) - } - if f.opts.Prompt != before { - t.Fatalf("flow prompt mutated to %q, want %q", f.opts.Prompt, before) - } -} - -type optimizerModel struct{ reply string } - -func (m *optimizerModel) Init(...model.Option) error { return nil } -func (m *optimizerModel) Options() model.Options { return model.Options{} } -func (m *optimizerModel) Generate(context.Context, *model.Request, ...model.GenerateOption) (*model.Response, error) { - return &model.Response{Reply: m.reply}, nil -} -func (m *optimizerModel) Stream(context.Context, *model.Request, ...model.GenerateOption) (model.Stream, error) { - return nil, model.ErrStreamingUnsupported -} -func (m *optimizerModel) String() string { return "optimizer" } diff --git a/flow/dispatch_test.go b/flow/dispatch_test.go deleted file mode 100644 index 201445ff36..0000000000 --- a/flow/dispatch_test.go +++ /dev/null @@ -1,176 +0,0 @@ -package flow - -import ( - "context" - "encoding/json" - "testing" - - "go-micro.dev/v6/client" - codecbytes "go-micro.dev/v6/codec/bytes" - "go-micro.dev/v6/model" - "go-micro.dev/v6/store" -) - -// fakeClient embeds the default client (so NewRequest works) and -// overrides Call with a test-supplied function. -type fakeClient struct { - client.Client - callFn func(ctx context.Context, req client.Request, rsp interface{}) error -} - -func (c *fakeClient) Call(ctx context.Context, req client.Request, rsp interface{}, opts ...client.CallOption) error { - return c.callFn(ctx, req, rsp) -} - -// A flow with Agent set hands the rendered prompt to that agent's -// Agent.Chat endpoint over RPC and records its reply — it does not run -// its own model. -func TestExecuteDispatchesToAgent(t *testing.T) { - f := New("welcome", Agent("comms"), Prompt("welcome {{.Data}}")) - - var svc, ep, parentID string - f.client = &fakeClient{ - Client: client.DefaultClient, - callFn: func(_ context.Context, req client.Request, rsp interface{}) error { - svc, ep = req.Service(), req.Endpoint() - reqFrame := req.Body().(*codecbytes.Frame) - var body map[string]string - if err := json.Unmarshal(reqFrame.Data, &body); err != nil { - t.Fatalf("request body: %v", err) - } - parentID = body["parent_id"] - frame := rsp.(*codecbytes.Frame) - frame.Data = []byte(`{"reply":"welcomed bob","agent":"comms"}`) - return nil - }, - } - - if err := f.Execute(context.Background(), "bob"); err != nil { - t.Fatalf("Execute: %v", err) - } - - if svc != "comms" || ep != "Agent.Chat" { - t.Errorf("dispatched to %s.%s, want comms.Agent.Chat", svc, ep) - } - if parentID == "" { - t.Fatal("dispatch request parent_id is empty") - } - - results := f.Results() - if len(results) != 1 { - t.Fatalf("got %d results, want 1", len(results)) - } - if results[0].Reply != "welcomed bob" { - t.Errorf("result reply = %q, want %q", results[0].Reply, "welcomed bob") - } - if results[0].Prompt != "welcome bob" { - t.Errorf("rendered prompt = %q, want %q", results[0].Prompt, "welcome bob") - } -} - -// A caller-owned schedule can trigger an agent workflow without a human chat -// prompt and still leave the normal flow run metadata behind for inspection. -func TestScheduledAgentRunHarnessContract(t *testing.T) { - ctx := context.Background() - cp := StoreCheckpoint(store.NewMemoryStore(), "scheduled-contract") - f := New("scheduled-contract", - Trigger("schedule.daily"), - WithCheckpoint(cp), - Steps(Step{Name: "summarize", Run: Dispatch("ops-agent")}), - ) - - var parentID string - var dispatched model.RunInfo - f.client = &fakeClient{ - Client: client.DefaultClient, - callFn: func(ctx context.Context, req client.Request, rsp interface{}) error { - dispatched, _ = model.RunInfoFrom(ctx) - if req.Service() != "ops-agent" || req.Endpoint() != "Agent.Chat" { - t.Fatalf("dispatched to %s.%s, want ops-agent.Agent.Chat", req.Service(), req.Endpoint()) - } - reqFrame := req.Body().(*codecbytes.Frame) - var body map[string]string - if err := json.Unmarshal(reqFrame.Data, &body); err != nil { - t.Fatalf("request body: %v", err) - } - parentID = body["parent_id"] - if body["message"] != "run unattended daily ops review" { - t.Fatalf("message = %q, want scheduled payload", body["message"]) - } - frame := rsp.(*codecbytes.Frame) - frame.Data = []byte(`{"reply":"review queued","agent":"ops-agent","run_id":"agent-run-456","parent_id":"` + parentID + `"}`) - return nil - }, - } - - if err := Scheduled(f, "run unattended daily ops review").Tick(ctx); err != nil { - t.Fatalf("scheduled tick: %v", err) - } - if parentID == "" { - t.Fatal("dispatch did not receive the scheduled flow run id as parent_id") - } - - runs, err := cp.List(ctx) - if err != nil { - t.Fatalf("list scheduled runs: %v", err) - } - if len(runs) != 1 { - t.Fatalf("got %d runs, want 1", len(runs)) - } - run := runs[0] - if run.ID != parentID { - t.Fatalf("run ID = %q, parent_id = %q", run.ID, parentID) - } - if run.Flow != "scheduled-contract" || run.Status != "done" { - t.Fatalf("run = %+v, want scheduled-contract done", run) - } - if run.Dispatch != "schedule" || run.Trigger != "schedule.daily" { - t.Fatalf("run origin = dispatch %q trigger %q, want scheduled schedule.daily", run.Dispatch, run.Trigger) - } - if dispatched.RunID != run.ID || dispatched.Flow != run.Flow || dispatched.Step != "summarize" || - dispatched.Dispatch != run.Dispatch || dispatched.Trigger != run.Trigger { - t.Fatalf("dispatch RunInfo = %#v, want flow run lineage", dispatched) - } - if got := run.State.String(); got != "review queued" { - t.Fatalf("run result = %q, want agent reply", got) - } - if len(run.Steps) != 1 || run.Steps[0].Name != "summarize" || run.Steps[0].Status != "done" { - t.Fatalf("steps = %+v, want summarize done", run.Steps) - } - if run.Steps[0].Agent != "ops-agent" || run.Steps[0].ChildRunID != "agent-run-456" { - t.Fatalf("dispatch lineage = %+v, want ops-agent child run", run.Steps[0]) - } -} - -func TestCallRecordsServiceTargetAndPropagatesLineage(t *testing.T) { - ctx := context.Background() - cp := StoreCheckpoint(store.NewMemoryStore(), "service-call") - f := New("service-call", WithCheckpoint(cp), Steps(Step{Name: "charge", Run: Call("payments", "Payments.Charge")})) - - var called model.RunInfo - f.client = &fakeClient{ - Client: client.DefaultClient, - callFn: func(callCtx context.Context, req client.Request, rsp interface{}) error { - called, _ = model.RunInfoFrom(callCtx) - if req.Service() != "payments" || req.Endpoint() != "Payments.Charge" { - t.Fatalf("called %s.%s, want payments.Payments.Charge", req.Service(), req.Endpoint()) - } - rsp.(*codecbytes.Frame).Data = []byte(`{"status":"paid"}`) - return nil - }, - } - if err := f.Execute(ctx, `{"order":"123"}`); err != nil { - t.Fatalf("Execute: %v", err) - } - runs, err := cp.List(ctx) - if err != nil || len(runs) != 1 { - t.Fatalf("runs = %+v, err = %v", runs, err) - } - run := runs[0] - if called.RunID != run.ID || called.Flow != "service-call" || called.Step != "charge" || called.Dispatch != "direct" { - t.Fatalf("service RunInfo = %#v, want direct flow step lineage", called) - } - if len(run.Steps) != 1 || run.Steps[0].Service != "payments" || run.Steps[0].Endpoint != "Payments.Charge" { - t.Fatalf("persisted service target = %+v", run.Steps) - } -} diff --git a/flow/environment_test.go b/flow/environment_test.go deleted file mode 100644 index da64a2de72..0000000000 --- a/flow/environment_test.go +++ /dev/null @@ -1,43 +0,0 @@ -package flow - -import ( - "go-micro.dev/v6/broker" - "go-micro.dev/v6/client" - "go-micro.dev/v6/registry" - "testing" -) - -func TestProviderEnvironment(t *testing.T) { - t.Setenv("MICRO_AI_PROVIDER", "mistral") - t.Setenv("MICRO_AI_MODEL", "configured-model") - t.Setenv("MICRO_AI_BASE_URL", "http://localhost:9999") - t.Setenv("MICRO_AI_API_KEY", "") - t.Setenv("MISTRAL_API_KEY", "mistral-test-key") - t.Setenv("OPENAI_API_KEY", "openai-test-key") - o := New("test").opts - if o.Provider != "mistral" || o.Model != "configured-model" || o.APIKey != "mistral-test-key" || o.BaseURL != "http://localhost:9999" { - t.Fatal("flow did not use configured environment") - } - if New("test", APIKey("")).opts.APIKey != "" { - t.Fatal("explicit empty key must disable environment authentication") - } - o = New("test", Provider("openai"), Model("explicit"), BaseURL(""), APIKey("explicit-key")).opts - if o.Provider != "openai" || o.Model != "explicit" || o.APIKey != "explicit-key" || o.BaseURL != "" { - t.Fatal("explicit flow options did not override environment") - } -} - -func TestEnvironmentProvidersRegistered(t *testing.T) { - for _, provider := range []string{"ollama", "minimax"} { - t.Run(provider, func(t *testing.T) { - t.Setenv("MICRO_AI_PROVIDER", provider) - f := New("test") - if err := f.Register(registry.NewMemoryRegistry(), broker.NewMemoryBroker(), client.NewClient()); err != nil { - t.Fatal(err) - } - if f.model.String() != provider { - t.Fatalf("registered %q instead of %q", f.model.String(), provider) - } - }) - } -} diff --git a/flow/example_verify_test.go b/flow/example_verify_test.go deleted file mode 100644 index c03b0c1e98..0000000000 --- a/flow/example_verify_test.go +++ /dev/null @@ -1,45 +0,0 @@ -package flow_test - -import ( - "context" - "fmt" - "strings" - - "go-micro.dev/v6/flow" -) - -func ExampleVerify() { - generate := func(_ context.Context, in flow.State) (flow.State, error) { - if strings.Contains(in.String(), "feedback") { - in.Data = []byte(`{"answer":"include a source"}`) - return in, nil - } - in.Data = []byte(`{"answer":"draft"}`) - return in, nil - } - grader := func(_ context.Context, out flow.State) (bool, string, error) { - return strings.Contains(out.String(), "source"), "add a source", nil - } - - out, _ := flow.Verify(generate, grader, flow.VerifyMaxAttempts(2))(context.Background(), flow.State{}) - fmt.Println(strings.Contains(out.String(), `"verification_passed":true`)) - // Output: true -} - -func ExampleAnalyze() { - runs := []flow.Run{{ - ID: "run-1", - Steps: []flow.StepRecord{{ - Name: "draft", - Status: "done", - Result: `{"verification_passed":false,"verification_feedback":"add a source"}`, - }}, - }} - - report := flow.Analyze(runs) - fmt.Println(report.Candidates[0].Step) - fmt.Println(report.Candidates[0].SampleFeedback[0]) - // Output: - // draft - // add a source -} diff --git a/flow/flow.go b/flow/flow.go deleted file mode 100644 index 061e05affc..0000000000 --- a/flow/flow.go +++ /dev/null @@ -1,360 +0,0 @@ -// Package flow provides event-driven workflows for go-micro services. -// -// A Flow coordinates predefined steps, including service calls, model calls, -// and agent dispatch. It can subscribe to a broker topic or execute directly. -// Prompt-driven flows let a model choose tools for an event; ordered flows -// checkpoint between steps. Use an Agent when the work needs to direct itself -// dynamically. Recovery requires persistent checkpoint storage, and interrupted -// steps may execute again. -// -// Usage: -// -// f := flow.New("onboard-user", -// flow.Trigger("events.user.created"), -// flow.Prompt("New user created: {{.Data}}. Send welcome email and create workspace."), -// flow.Provider("anthropic"), -// flow.APIKey(key), -// ) -// f.Register(service.Options().Registry, service.Options().Broker, service.Client()) -// service.Run() -package flow - -import ( - "bytes" - "context" - "encoding/json" - "fmt" - "os" - "strconv" - "sync" - "text/template" - "time" - - "github.com/google/uuid" - "go-micro.dev/v6/broker" - "go-micro.dev/v6/client" - codecbytes "go-micro.dev/v6/codec/bytes" - "go-micro.dev/v6/logger" - "go-micro.dev/v6/model" - "go-micro.dev/v6/registry" - - // Register default providers. - _ "go-micro.dev/v6/model/anthropic" - _ "go-micro.dev/v6/model/atlascloud" - _ "go-micro.dev/v6/model/gemini" - _ "go-micro.dev/v6/model/groq" - _ "go-micro.dev/v6/model/litellm" - _ "go-micro.dev/v6/model/minimax" - _ "go-micro.dev/v6/model/mistral" - _ "go-micro.dev/v6/model/ollama" - _ "go-micro.dev/v6/model/openai" - _ "go-micro.dev/v6/model/openrouter" - _ "go-micro.dev/v6/model/together" -) - -// Flow coordinates prompt-driven or ordered work, including service calls and -// agent dispatch. Broker events can trigger execution. -type Flow struct { - name string - opts Options - model model.Model - toolSet *model.Tools - client client.Client - tmpl *template.Template - log logger.Logger - checkpoint Checkpoint - reg registry.Registry - sub broker.Subscriber - registration *registry.Service - mu sync.Mutex - results []Result -} - -// Result records one flow execution. -type Result struct { - FlowName string `json:"flow"` - Trigger string `json:"trigger"` - Prompt string `json:"prompt"` - Reply string `json:"reply,omitempty"` - Answer string `json:"answer,omitempty"` - ToolCalls []string `json:"tool_calls,omitempty"` - Error string `json:"error,omitempty"` - ErrorKind string `json:"error_kind,omitempty"` - Timestamp time.Time `json:"timestamp"` - Duration float64 `json:"duration_seconds"` -} - -// New creates a Flow with the given name and options. -func New(name string, opts ...Option) *Flow { - o := Options{ - Provider: os.Getenv("MICRO_AI_PROVIDER"), - Model: os.Getenv("MICRO_AI_MODEL"), - BaseURL: os.Getenv("MICRO_AI_BASE_URL"), - SystemPrompt: "You are a service orchestrator. Use the available tools to fulfill the request. Explain what you do.", - HistoryLimit: 20, - } - for _, opt := range opts { - opt(&o) - } - - if o.Provider == "" { - o.Provider = model.AutoDetectProvider(o.BaseURL) - } - if !o.apiKeySet && o.APIKey == "" { - o.APIKey = os.Getenv("MICRO_AI_API_KEY") - if o.APIKey == "" { - o.APIKey = os.Getenv(model.APIKeyEnv(o.Provider)) - } - } - - var tmpl *template.Template - if o.Prompt != "" { - var err error - tmpl, err = template.New(name).Parse(o.Prompt) - if err != nil { - tmpl = template.Must(template.New(name).Parse("{{.Data}}")) - } - } - - return &Flow{ - name: name, - opts: o, - tmpl: tmpl, - log: logger.DefaultLogger, - checkpoint: defaultCheckpoint(name, o), - } -} - -// Register wires the flow into a running service. It sets up the -// model, discovers tools from the registry, and subscribes to the -// trigger topic on the broker. Call this before service.Run(). -func (f *Flow) Register(reg registry.Registry, br broker.Broker, cl client.Client) error { - f.client = cl - f.reg = reg - f.toolSet = model.NewTools(reg, model.ToolClient(cl)) - - // A flow that dispatches to an agent doesn't run its own model — the - // agent is the engine. Otherwise, set up the augmented LLM. - if f.opts.Agent == "" { - var modelOpts []model.Option - if f.opts.APIKey != "" { - modelOpts = append(modelOpts, model.WithAPIKey(f.opts.APIKey)) - } - if f.opts.Model != "" { - modelOpts = append(modelOpts, model.WithModel(f.opts.Model)) - } - if f.opts.BaseURL != "" { - modelOpts = append(modelOpts, model.WithBaseURL(f.opts.BaseURL)) - } - modelOpts = append(modelOpts, model.WithTools(f.toolSet)) - - f.model = model.New(f.opts.Provider, modelOpts...) - if f.model == nil { - return fmt.Errorf("unknown provider: %s", f.opts.Provider) - } - } - - if f.opts.TriggerTopic != "" { - sub, err := br.Subscribe(f.opts.TriggerTopic, func(p broker.Event) error { - data := string(p.Message().Body) - ctx := model.WithRunInfo(context.Background(), model.RunInfo{Dispatch: "broker", Trigger: f.opts.TriggerTopic}) - if err := f.Execute(ctx, data); err != nil { - f.log.Logf(logger.ErrorLevel, "Flow %s failed: %v", f.name, err) - } - return nil - }) - if err != nil { - return fmt.Errorf("subscribe to %s: %w", f.opts.TriggerTopic, err) - } - f.sub = sub - f.log.Logf(logger.InfoLevel, "Flow %s subscribed to %s", f.name, f.opts.TriggerTopic) - - // Announce the flow in the registry so it's discoverable like a - // service or agent (e.g. `micro flow list`). This is liveness only: - // Stop deregisters it. Durable run history lives in the store. - f.registration = ®istry.Service{ - Name: f.name, - Version: "latest", - Metadata: map[string]string{ - "type": "flow", - "trigger": f.opts.TriggerTopic, - "steps": strconv.Itoa(len(f.opts.Steps)), - }, - Nodes: []*registry.Node{{ - Id: f.name + "-" + uuid.New().String()[:8], - Address: "flow://" + f.name, - Metadata: map[string]string{"type": "flow"}, - }}, - } - if err := reg.Register(f.registration); err != nil { - f.log.Logf(logger.ErrorLevel, "Flow %s registry register: %v", f.name, err) - f.registration = nil - } - } - - return nil -} - -// Stop unsubscribes the flow from its trigger and deregisters it from the -// registry. In-flight and past runs remain in the store; Stop only ends -// the flow's liveness, mirroring how a service leaves the registry when -// it shuts down. -func (f *Flow) withTimeout(ctx context.Context) (context.Context, context.CancelFunc) { - if ctx == nil { - ctx = context.Background() - } - if f.opts.Timeout <= 0 { - return ctx, func() {} - } - if _, ok := ctx.Deadline(); ok { - return ctx, func() {} - } - return context.WithTimeout(ctx, f.opts.Timeout) -} - -func (f *Flow) Stop() error { - if f.sub != nil { - _ = f.sub.Unsubscribe() - f.sub = nil - } - if f.registration != nil && f.reg != nil { - err := f.reg.Deregister(f.registration) - f.registration = nil - return err - } - return nil -} - -// Execute runs the flow once with the given input data. This is -// called automatically on each broker event, but can also be -// invoked directly for testing or one-shot use. -func (f *Flow) Execute(ctx context.Context, data string) error { - ctx, cancel := f.withTimeout(ctx) - defer cancel() - - // Stepped flows run the ordered, checkpointed step loop. - if len(f.opts.Steps) > 0 { - _, err := f.startRun(ctx, data) - return err - } - - runID := uuid.New().String() - info, _ := model.RunInfoFrom(ctx) - info.RunID = runID - info.Flow = f.name - ctx = model.WithRunInfo(ctx, info) - - start := time.Now() - - prompt := data - if f.tmpl != nil { - var buf bytes.Buffer - _ = f.tmpl.Execute(&buf, map[string]string{"Data": data}) - prompt = buf.String() - } - - result := Result{ - FlowName: f.name, - Trigger: f.opts.TriggerTopic, - Prompt: prompt, - Timestamp: start, - } - - // Flow triggers, Agent reasons: hand the event to the named agent. - if f.opts.Agent != "" { - reply, err := f.callAgent(ctx, f.opts.Agent, prompt) - result.Duration = time.Since(start).Seconds() - if err != nil { - result.Error = err.Error() - result.ErrorKind = string(model.ClassifyError(err)) - f.record(result) - return err - } - result.Reply = reply - f.record(result) - f.log.Logf(logger.InfoLevel, "Flow %s dispatched to agent %s in %.1fs", - f.name, f.opts.Agent, result.Duration) - return nil - } - - // Otherwise run a single augmented-LLM step with the services as tools. - discovered, err := f.toolSet.Discover() - if err != nil { - result.Duration = time.Since(start).Seconds() - result.Error = err.Error() - result.ErrorKind = string(model.ClassifyError(err)) - f.record(result) - return fmt.Errorf("discover tools: %w", err) - } - - resp, err := f.model.Generate(ctx, &model.Request{ - Prompt: prompt, - SystemPrompt: f.opts.SystemPrompt, - Tools: discovered, - }) - result.Duration = time.Since(start).Seconds() - - if err != nil { - result.Error = err.Error() - result.ErrorKind = string(model.ClassifyError(err)) - f.record(result) - return err - } - - result.Reply = resp.Reply - result.Answer = resp.Answer - for _, tc := range resp.ToolCalls { - args, _ := json.Marshal(tc.Input) - result.ToolCalls = append(result.ToolCalls, fmt.Sprintf("%s(%s)", tc.Name, args)) - } - - f.record(result) - - f.log.Logf(logger.InfoLevel, "Flow %s completed in %.1fs: %d tool calls", - f.name, result.Duration, len(result.ToolCalls)) - - return nil -} - -// callAgent hands the rendered prompt to a registered agent's Agent.Chat -// endpoint over RPC and returns its reply. -func (f *Flow) callAgent(ctx context.Context, name, message string) (string, error) { - info, _ := model.RunInfoFrom(ctx) - body, _ := json.Marshal(map[string]string{"message": message, "parent_id": info.RunID}) - req := f.client.NewRequest(name, "Agent.Chat", &codecbytes.Frame{Data: body}) - var rsp codecbytes.Frame - if err := f.client.Call(ctx, req, &rsp); err != nil { - return "", err - } - var out struct { - Reply string `json:"reply"` - } - if err := json.Unmarshal(rsp.Data, &out); err != nil { - return "", err - } - return out.Reply, nil -} - -// Results returns a copy of all recorded execution results. -func (f *Flow) Results() []Result { - f.mu.Lock() - defer f.mu.Unlock() - out := make([]Result, len(f.results)) - copy(out, f.results) - return out -} - -// Name returns the flow name. -func (f *Flow) Name() string { - return f.name -} - -func (f *Flow) record(r Result) { - f.mu.Lock() - f.results = append(f.results, r) - f.mu.Unlock() - - if f.opts.OnResult != nil { - f.opts.OnResult(r) - } -} diff --git a/flow/flow_test.go b/flow/flow_test.go deleted file mode 100644 index 7c092e5396..0000000000 --- a/flow/flow_test.go +++ /dev/null @@ -1,131 +0,0 @@ -package flow - -import ( - "context" - "testing" - - "go-micro.dev/v6/model" - "go-micro.dev/v6/registry" -) - -func TestNew(t *testing.T) { - f := New("test-flow", - Trigger("events.test"), - Prompt("Handle this: {{.Data}}"), - Provider("anthropic"), - APIKey("test-key"), - HistoryLimit(10), - ) - - if f.Name() != "test-flow" { - t.Errorf("name = %q, want test-flow", f.Name()) - } - if f.opts.TriggerTopic != "events.test" { - t.Errorf("trigger = %q", f.opts.TriggerTopic) - } - if f.opts.Provider != "anthropic" { - t.Errorf("provider = %q", f.opts.Provider) - } - if f.opts.HistoryLimit != 10 { - t.Errorf("history limit = %d", f.opts.HistoryLimit) - } - if f.tmpl == nil { - t.Fatal("template not parsed") - } -} - -func TestPromptTemplate(t *testing.T) { - f := New("tmpl-test", - Prompt("User created: {{.Data}}. Send welcome email."), - ) - - // Test that the template renders - if f.tmpl == nil { - t.Fatal("template not parsed") - } -} - -func TestResultsEmpty(t *testing.T) { - f := New("empty") - results := f.Results() - if len(results) != 0 { - t.Errorf("expected 0 results, got %d", len(results)) - } -} - -func TestOnResultCallback(t *testing.T) { - var called bool - f := New("callback", - OnResult(func(r Result) { - called = true - if r.FlowName != "callback" { - t.Errorf("flow name = %q", r.FlowName) - } - }), - ) - - f.record(Result{FlowName: "callback"}) - - if !called { - t.Error("OnResult not called") - } - if len(f.Results()) != 1 { - t.Errorf("results = %d, want 1", len(f.Results())) - } -} - -func TestDefaultOptions(t *testing.T) { - f := New("defaults") - - if f.opts.Provider != "openai" { - t.Errorf("default provider = %q, want openai", f.opts.Provider) - } - if f.opts.HistoryLimit != 20 { - t.Errorf("default history limit = %d, want 20", f.opts.HistoryLimit) - } - if f.opts.SystemPrompt == "" { - t.Error("default system prompt is empty") - } -} - -func TestSingleStepFlowRunInfoIdentifiesFlow(t *testing.T) { - llm := &runInfoModel{} - f := New("single-observed") - f.model = llm - f.toolSet = model.NewTools(registry.NewMemoryRegistry()) - - if err := f.Execute(context.Background(), "observe me"); err != nil { - t.Fatalf("Execute: %v", err) - } - if llm.got.RunID == "" { - t.Fatal("RunInfo.RunID is empty") - } - if llm.got.Flow != "single-observed" { - t.Fatalf("RunInfo.Flow = %q, want single-observed", llm.got.Flow) - } - if llm.got.Agent != "" { - t.Fatalf("RunInfo.Agent = %q, want empty for flow-owned LLM run", llm.got.Agent) - } - if llm.got.Step != "" { - t.Fatalf("RunInfo.Step = %q, want empty for single-step flow", llm.got.Step) - } -} - -type runInfoModel struct { - got model.RunInfo -} - -func (m *runInfoModel) Init(...model.Option) error { return nil } - -func (m *runInfoModel) Options() model.Options { return model.Options{} } - -func (m *runInfoModel) Generate(ctx context.Context, _ *model.Request, _ ...model.GenerateOption) (*model.Response, error) { - m.got, _ = model.RunInfoFrom(ctx) - return &model.Response{Reply: "ok"}, nil -} - -func (m *runInfoModel) Stream(context.Context, *model.Request, ...model.GenerateOption) (model.Stream, error) { - return nil, model.ErrStreamingUnsupported -} - -func (m *runInfoModel) String() string { return "run-info-model" } diff --git a/flow/loop.go b/flow/loop.go deleted file mode 100644 index 7a8b5575de..0000000000 --- a/flow/loop.go +++ /dev/null @@ -1,151 +0,0 @@ -package flow - -import ( - "context" - "fmt" - "strings" - - "go-micro.dev/v6/model" -) - -// LoopCondition decides whether a Loop should stop, given the latest state -// and the iteration just completed (1-based). Returning true ends the loop. -type LoopCondition func(ctx context.Context, state State, iter int) (bool, error) - -// LoopOptions configure a Loop. Max is the hard iteration cap — the ceiling -// that guarantees the loop always terminates, however the stop is decided. -// Until and UntilLLM are the optional early-stop checks. -type LoopOptions struct { - Max int - Until LoopCondition - UntilLLM string - OnIter func(iter int, state State) -} - -// LoopOption configures a Loop. -type LoopOption func(*LoopOptions) - -// LoopMax sets the hard iteration cap — the budget guardrail. The loop never -// runs the body more than n times, so it always terminates even when the -// stop condition never fires. Default 10. -func LoopMax(n int) LoopOption { return func(o *LoopOptions) { o.Max = n } } - -// Until stops the loop when cond returns true after an iteration — a -// deterministic, code-defined exit condition. -func Until(cond LoopCondition) LoopOption { return func(o *LoopOptions) { o.Until = cond } } - -// UntilLLM stops the loop when the flow's model judges the goal met. After -// each iteration it asks the model the question with the latest state and -// stops on an affirmative answer — the agent decides when it's done (the -// supervised "Ralph" loop), while LoopMax guarantees termination. Requires a -// flow model (set Provider/APIKey). -func UntilLLM(question string) LoopOption { return func(o *LoopOptions) { o.UntilLLM = question } } - -// OnIteration runs fn after each iteration — useful for logging progress or -// persisting intermediate state. -func OnIteration(fn func(iter int, state State)) LoopOption { - return func(o *LoopOptions) { o.OnIter = fn } -} - -// Loop returns a StepFunc that runs body repeatedly until a stop condition is -// met or the iteration cap is reached, whichever comes first — the agentic -// "loop": keep working until the goal is done, with a guaranteed ceiling so -// it can never run away. -// -// Compose it as a flow step. The carried State flows from one pass to the -// next, so each iteration sees the previous result: -// -// flow.New("refactor", -// flow.Provider("anthropic"), -// flow.Steps( -// flow.Step{Name: "improve", Run: flow.Loop( -// flow.Dispatch("coder"), -// flow.UntilLLM("Is the refactor complete with no duplicated abstractions left?"), -// flow.LoopMax(5), -// )}, -// ), -// ) -// -// The loop runs as a single flow step: the flow checkpoints the loop's -// outcome, and a resume re-enters the step, so loop bodies should be safe to -// repeat. Use OnIteration to record per-pass progress. If the cap is hit -// before the stop condition fires, the loop returns the latest state rather -// than erroring — the guardrail did its job. -func Loop(body StepFunc, opts ...LoopOption) StepFunc { - o := LoopOptions{Max: 10} - for _, op := range opts { - op(&o) - } - if o.Max <= 0 { - o.Max = 10 - } - return func(ctx context.Context, in State) (State, error) { - if body == nil { - return in, fmt.Errorf("flow: Loop requires a body step") - } - cur := in - for iter := 1; iter <= o.Max; iter++ { - out, err := body(ctx, cur) - if err != nil { - return cur, fmt.Errorf("loop iteration %d: %w", iter, err) - } - cur = out - if o.OnIter != nil { - o.OnIter(iter, cur) - } - done, err := loopDone(ctx, o, cur, iter) - if err != nil { - return cur, err - } - if done { - return cur, nil - } - } - return cur, nil - } -} - -// loopDone evaluates the stop conditions: a code-defined Until predicate -// and/or an LLM judgement. Either firing stops the loop. -func loopDone(ctx context.Context, o LoopOptions, state State, iter int) (bool, error) { - if o.Until != nil { - done, err := o.Until(ctx, state, iter) - if err != nil || done { - return done, err - } - } - if o.UntilLLM != "" { - return askDone(ctx, o.UntilLLM, state) - } - return false, nil -} - -// askDone asks the flow model whether the goal is met given the current -// state, and returns true on an affirmative reply — the supervised stop check. -func askDone(ctx context.Context, question string, state State) (bool, error) { - d := depsFrom(ctx) - if d == nil || d.model == nil { - return false, fmt.Errorf("flow: UntilLLM requires a flow model (set Provider/APIKey)") - } - prompt := fmt.Sprintf("%s\n\nLatest result:\n%s\n\nAnswer with only \"yes\" or \"no\".", question, state.String()) - resp, err := d.model.Generate(ctx, &model.Request{Prompt: prompt}) - if err != nil { - return false, err - } - reply := resp.Answer - if reply == "" { - reply = resp.Reply - } - return isAffirmative(reply), nil -} - -// isAffirmative reports whether a model reply reads as "yes/done". -func isAffirmative(s string) bool { - s = strings.ToLower(strings.TrimSpace(s)) - for _, p := range []string{"yes", "done", "true", "complete", "finished"} { - if strings.HasPrefix(s, p) { - return true - } - } - return false -} diff --git a/flow/loop_test.go b/flow/loop_test.go deleted file mode 100644 index 0baf3e8858..0000000000 --- a/flow/loop_test.go +++ /dev/null @@ -1,91 +0,0 @@ -package flow - -import ( - "context" - "strconv" - "testing" -) - -// counter body: increments an integer carried in State.Data. -func counter() StepFunc { - return func(ctx context.Context, in State) (State, error) { - n, _ := strconv.Atoi(in.String()) - in.Data = []byte(strconv.Itoa(n + 1)) - return in, nil - } -} - -func TestLoopUntil(t *testing.T) { - step := Loop(counter(), - Until(func(ctx context.Context, s State, iter int) (bool, error) { - n, _ := strconv.Atoi(s.String()) - return n >= 3, nil - }), - LoopMax(100), - ) - out, err := step(context.Background(), State{Data: []byte("0")}) - if err != nil { - t.Fatal(err) - } - if out.String() != "3" { - t.Fatalf("expected 3, got %q", out.String()) - } -} - -func TestLoopMaxCapStops(t *testing.T) { - runs := 0 - body := func(ctx context.Context, in State) (State, error) { runs++; return in, nil } - // condition never fires; the cap must stop it - step := Loop(body, - Until(func(ctx context.Context, s State, iter int) (bool, error) { return false, nil }), - LoopMax(5), - ) - if _, err := step(context.Background(), State{}); err != nil { - t.Fatal(err) - } - if runs != 5 { - t.Fatalf("expected 5 iterations (cap), got %d", runs) - } -} - -func TestLoopOnIteration(t *testing.T) { - var seen []int - body := func(ctx context.Context, in State) (State, error) { return in, nil } - step := Loop(body, LoopMax(3), OnIteration(func(iter int, s State) { seen = append(seen, iter) })) - if _, err := step(context.Background(), State{}); err != nil { - t.Fatal(err) - } - if len(seen) != 3 || seen[0] != 1 || seen[2] != 3 { - t.Fatalf("expected iterations [1 2 3], got %v", seen) - } -} - -func TestLoopBodyError(t *testing.T) { - body := func(ctx context.Context, in State) (State, error) { - return in, context.Canceled - } - step := Loop(body, LoopMax(3)) - if _, err := step(context.Background(), State{}); err == nil { - t.Fatal("expected error from body to propagate") - } -} - -func TestIsAffirmative(t *testing.T) { - cases := []struct { - in string - want bool - }{ - {"yes", true}, - {"Yes, the goal is met.", true}, - {"DONE", true}, - {"complete", true}, - {"no", false}, - {"not yet", false}, - {"", false}, - } - for _, c := range cases { - if got := isAffirmative(c.in); got != c.want { - t.Errorf("isAffirmative(%q) = %v, want %v", c.in, got, c.want) - } - } -} diff --git a/flow/options.go b/flow/options.go deleted file mode 100644 index 54fbe727fd..0000000000 --- a/flow/options.go +++ /dev/null @@ -1,156 +0,0 @@ -package flow - -import ( - "time" - - "go.opentelemetry.io/otel/trace" -) - -// Options configures a Flow. -type Options struct { - // TriggerTopic is the broker topic that triggers this flow. - TriggerTopic string - // Prompt is a Go template string. {{.Data}} is the event payload. - Prompt string - // SystemPrompt is the system instruction for the LLM. - SystemPrompt string - // Provider is the AI provider name (e.g. "anthropic", "openai"). - Provider string - // APIKey for the AI provider. - APIKey string - apiKeySet bool - // Model overrides the provider's default model. - Model string - // BaseURL overrides the provider's default base URL. - BaseURL string - // HistoryLimit is the max messages per flow execution. - HistoryLimit int - // Timeout bounds one flow execution when the caller did not already - // provide a context deadline. Zero means no flow-level timeout. - Timeout time.Duration - // OnResult is called after each execution with the result. - OnResult func(Result) - // Agent, if set, names a registered agent the flow hands each event - // to (over RPC). The flow triggers; the agent reasons. When empty, - // the flow runs a single augmented-LLM step itself. - Agent string - - // Steps, if set, makes the flow run an ordered list of steps per - // event instead of a single LLM step — the deterministic-workflow - // path. Checkpointed between steps when a Checkpoint is set. - Steps []Step - // Retry is the flow-level retry count applied to each step (0 = no - // retry). A Step's own Retry field overrides this. - Retry int - // RetryBackoff is the delay between failed step attempts. Zero means - // retry immediately; cancellation/deadline stops the wait early. - RetryBackoff time.Duration - // Checkpoint is the durability backend for stepped runs. Nil with - // steps present means a store-backed default; set it to swap backends. - Checkpoint Checkpoint - // TraceProvider emits OpenTelemetry spans for stepped flow runs. - TraceProvider trace.TracerProvider - // DeleteOnSuccess removes a run's checkpoint when it completes - // successfully. Failed runs are always retained. Default: retain all. - DeleteOnSuccess bool -} - -// Option applies a configuration to Options. -type Option func(*Options) - -// Trigger sets the broker topic that triggers this flow. -func Trigger(topic string) Option { - return func(o *Options) { o.TriggerTopic = topic } -} - -// Prompt sets the prompt template. Use {{.Data}} for the event payload. -func Prompt(p string) Option { - return func(o *Options) { o.Prompt = p } -} - -// SystemPrompt sets the system instruction for the LLM. -func SystemPrompt(p string) Option { - return func(o *Options) { o.SystemPrompt = p } -} - -// Provider sets the AI provider name. -func Provider(name string) Option { - return func(o *Options) { o.Provider = name } -} - -// APIKey sets the API key for the AI provider. -func APIKey(key string) Option { - return func(o *Options) { o.APIKey = key; o.apiKeySet = true } -} - -// Model sets the model name. -func Model(name string) Option { - return func(o *Options) { o.Model = name } -} - -// BaseURL sets the provider base URL. -func BaseURL(url string) Option { - return func(o *Options) { o.BaseURL = url } -} - -// HistoryLimit sets the max messages per execution. -func HistoryLimit(n int) Option { - return func(o *Options) { o.HistoryLimit = n } -} - -// Timeout bounds one flow execution when the caller did not already -// provide a context deadline. It applies to broker-triggered runs, -// Execute calls, resumed stepped runs, and retry backoff waits. -func Timeout(d time.Duration) Option { - return func(o *Options) { o.Timeout = d } -} - -// OnResult sets a callback for each execution result. -func OnResult(fn func(Result)) Option { - return func(o *Options) { o.OnResult = fn } -} - -// Agent makes the flow hand each event to a named registered agent over -// RPC instead of running its own LLM step. The flow triggers; the agent -// reasons (with its plan, delegate, memory, and guardrails). -func Agent(name string) Option { - return func(o *Options) { o.Agent = name } -} - -// Steps sets the ordered steps of the flow. A flow with steps runs them -// in order per event, checkpointing between each, instead of the -// single-step prompt/agent behavior. Step names must be unique. -func Steps(steps ...Step) Option { - return func(o *Options) { o.Steps = steps } -} - -// Retry sets the flow-level retry count applied to each step (0 = no -// retry). A Step's own Retry field overrides this. -func Retry(n int) Option { - return func(o *Options) { o.Retry = n } -} - -// RetryBackoff sets the delay between failed step attempts. A zero -// duration preserves immediate retries. If the run context is canceled -// while waiting, the context error is returned instead of retrying. -func RetryBackoff(d time.Duration) Option { - return func(o *Options) { o.RetryBackoff = d } -} - -// WithCheckpoint sets the durability backend. With a checkpoint, a run is -// persisted before and after each step and can be resumed after a crash. -// Stepped flows default to a store-backed checkpoint; use this to swap it. -func WithCheckpoint(c Checkpoint) Option { - return func(o *Options) { o.Checkpoint = c } -} - -// DeleteOnSuccess removes a run's checkpoint when it completes -// successfully. Failed runs are always retained. Default: retain all. -func DeleteOnSuccess() Option { - return func(o *Options) { o.DeleteOnSuccess = true } -} - -// TraceProvider enables OpenTelemetry spans for stepped flow runs and steps. -func TraceProvider(tp trace.TracerProvider) Option { - return func(o *Options) { o.TraceProvider = tp } -} diff --git a/flow/otel.go b/flow/otel.go deleted file mode 100644 index be2131d583..0000000000 --- a/flow/otel.go +++ /dev/null @@ -1,117 +0,0 @@ -package flow - -import ( - "context" - "time" - - "go-micro.dev/v6/model" - "go.opentelemetry.io/otel/attribute" - "go.opentelemetry.io/otel/codes" - "go.opentelemetry.io/otel/trace" -) - -const flowInstrumentationName = "go-micro.dev/v6/flow" - -const ( - spanNameFlowRun = "flow.run" - spanNameFlowStep = "flow.step" - - AttrFlowRunID = "flow.run.id" - AttrFlowParentID = "flow.run.parent_id" - AttrFlowName = "flow.name" - AttrFlowStepName = "flow.step.name" - AttrFlowStatus = "flow.status" - AttrFlowAttempts = "flow.step.attempts" - AttrFlowLatencyMS = "flow.latency_ms" - AttrFlowErrorKind = "flow.error.kind" - AttrFlowVerificationStatus = "flow.verification.status" - AttrFlowVerificationNote = "flow.verification.note" - AttrFlowDispatch = "flow.dispatch" - AttrFlowTrigger = "flow.trigger" -) - -func (f *Flow) tracer() trace.Tracer { - return f.opts.TraceProvider.Tracer(flowInstrumentationName) -} - -func (f *Flow) startRunSpan(ctx context.Context, run Run) (context.Context, func(Run, error)) { - if f.opts.TraceProvider == nil { - return ctx, func(Run, error) {} - } - info, _ := model.RunInfoFrom(ctx) - attrs := []attribute.KeyValue{ - attribute.String(AttrFlowRunID, run.ID), - attribute.String(AttrFlowParentID, run.ParentID), - attribute.String(AttrFlowName, f.name), - attribute.String(AttrFlowStatus, run.Status), - } - attrs = appendRunInfoDispatch(attrs, info) - ctx, span := f.tracer().Start(ctx, spanNameFlowRun, trace.WithSpanKind(trace.SpanKindInternal), trace.WithAttributes(attrs...)) - start := time.Now() - return ctx, func(done Run, err error) { - span.SetAttributes( - attribute.String(AttrFlowStatus, done.Status), - attribute.Int64(AttrFlowLatencyMS, time.Since(start).Milliseconds()), - ) - if err != nil { - span.RecordError(err) - span.SetAttributes(attribute.String(AttrFlowErrorKind, string(model.ClassifyError(err)))) - span.SetStatus(codes.Error, err.Error()) - } else { - span.SetStatus(codes.Ok, "") - } - span.End() - } -} - -func (f *Flow) runStepSpan(ctx context.Context, step Step, in State) (State, int, Verification, error) { - if f.opts.TraceProvider == nil { - return f.runStep(ctx, step, in) - } - info, _ := model.RunInfoFrom(ctx) - attrs := []attribute.KeyValue{ - attribute.String(AttrFlowRunID, info.RunID), - attribute.String(AttrFlowParentID, info.ParentID), - attribute.String(AttrFlowName, f.name), - attribute.String(AttrFlowStepName, step.Name), - } - attrs = appendRunInfoDispatch(attrs, info) - ctx, span := f.tracer().Start(ctx, spanNameFlowStep, trace.WithAttributes(attrs...)) - start := time.Now() - out, attempts, verification, err := f.runStep(ctx, step, in) - span.SetAttributes( - attribute.Int(AttrFlowAttempts, attempts), - attribute.Int64(AttrFlowLatencyMS, time.Since(start).Milliseconds()), - ) - if verification.Passed { - span.SetAttributes(attribute.String(AttrFlowVerificationStatus, "passed")) - } - if verification.Feedback != "" { - span.SetAttributes(attribute.String(AttrFlowVerificationNote, verification.Feedback)) - if !verification.Passed { - span.SetAttributes(attribute.String(AttrFlowVerificationStatus, "failed")) - } - } - if a, ok := isAwaitInput(err); ok { - // A suspend is normal control flow, not a step error. - span.SetStatus(codes.Ok, "waiting: "+a.Key) - } else if err != nil { - span.RecordError(err) - span.SetAttributes(attribute.String(AttrFlowErrorKind, string(model.ClassifyError(err)))) - span.SetStatus(codes.Error, err.Error()) - } else { - span.SetStatus(codes.Ok, "") - } - span.End() - return out, attempts, verification, err -} - -func appendRunInfoDispatch(attrs []attribute.KeyValue, info model.RunInfo) []attribute.KeyValue { - if info.Dispatch != "" { - attrs = append(attrs, attribute.String(AttrFlowDispatch, info.Dispatch)) - } - if info.Trigger != "" { - attrs = append(attrs, attribute.String(AttrFlowTrigger, info.Trigger)) - } - return attrs -} diff --git a/flow/otel_test.go b/flow/otel_test.go deleted file mode 100644 index 9f348f78e5..0000000000 --- a/flow/otel_test.go +++ /dev/null @@ -1,102 +0,0 @@ -package flow - -import ( - "context" - "testing" - - "go-micro.dev/v6/model" - "go-micro.dev/v6/store" - "go.opentelemetry.io/otel/attribute" - "go.opentelemetry.io/otel/sdk/trace" - "go.opentelemetry.io/otel/sdk/trace/tracetest" -) - -func TestFlowOpenTelemetrySpans(t *testing.T) { - exp := tracetest.NewInMemoryExporter() - tp := trace.NewTracerProvider(trace.WithSyncer(exp)) - - step := Step{Name: "inspect", Run: func(ctx context.Context, in State) (State, error) { - in.Data = []byte("done") - return in, nil - }} - f := New("observed", WithCheckpoint(StoreCheckpoint(store.NewMemoryStore(), "observed")), TraceProvider(tp), Steps(step)) - ctx := withTestRunInfo(context.Background(), "agent-run-otel") - if err := f.Execute(ctx, "start"); err != nil { - t.Fatal(err) - } - - spans := exp.GetSpans().Snapshots() - seen := map[string]bool{spanNameFlowRun: false, spanNameFlowStep: false} - var runID string - for _, span := range spans { - attrs := flowSpanAttributes(span.Attributes()) - switch span.Name() { - case spanNameFlowRun: - seen[spanNameFlowRun] = true - runID = attrs[AttrFlowRunID] - if attrs[AttrFlowName] != "observed" || attrs[AttrFlowStatus] != "done" || attrs[AttrFlowParentID] != "agent-run-otel" { - t.Fatalf("run span attributes = %#v", attrs) - } - case spanNameFlowStep: - seen[spanNameFlowStep] = true - if attrs[AttrFlowName] != "observed" || attrs[AttrFlowStepName] != "inspect" || attrs[AttrFlowParentID] != "agent-run-otel" { - t.Fatalf("step span attributes = %#v", attrs) - } - } - } - for name, ok := range seen { - if !ok { - t.Fatalf("span %s not emitted; got %d spans", name, len(spans)) - } - } - if runID == "" { - t.Fatal("run span missing run id") - } - for _, span := range spans { - if span.Name() != spanNameFlowStep { - continue - } - attrs := flowSpanAttributes(span.Attributes()) - if attrs[AttrFlowRunID] != runID { - t.Fatalf("step span run id = %q, want %q", attrs[AttrFlowRunID], runID) - } - } -} - -func flowSpanAttributes(attrs []attribute.KeyValue) map[string]string { - out := make(map[string]string, len(attrs)) - for _, attr := range attrs { - out[string(attr.Key)] = attr.Value.AsString() - } - return out -} - -func withTestRunInfo(ctx context.Context, runID string) context.Context { - return model.WithRunInfo(ctx, model.RunInfo{RunID: runID, Agent: "planner"}) -} - -func TestScheduledFlowOpenTelemetryDispatchAttributes(t *testing.T) { - exp := tracetest.NewInMemoryExporter() - tp := trace.NewTracerProvider(trace.WithSyncer(exp)) - - step := Step{Name: "summarize", Run: func(ctx context.Context, in State) (State, error) { - in.Data = []byte("queued") - return in, nil - }} - f := New("scheduled-observed", Trigger("schedule.daily"), WithCheckpoint(StoreCheckpoint(store.NewMemoryStore(), "scheduled-observed")), TraceProvider(tp), Steps(step)) - if err := Scheduled(f, "daily ops review").Tick(context.Background()); err != nil { - t.Fatal(err) - } - - for _, span := range exp.GetSpans().Snapshots() { - if span.Name() != spanNameFlowRun { - continue - } - attrs := flowSpanAttributes(span.Attributes()) - if attrs[AttrFlowDispatch] != "schedule" || attrs[AttrFlowTrigger] != "schedule.daily" { - t.Fatalf("scheduled run span dispatch attributes = %#v", attrs) - } - return - } - t.Fatal("flow run span not emitted") -} diff --git a/flow/record.go b/flow/record.go deleted file mode 100644 index b134aa1ff2..0000000000 --- a/flow/record.go +++ /dev/null @@ -1,29 +0,0 @@ -package flow - -import "context" - -// RunRecordSchemaVersion is the current JSON schema version for RunRecord. -const RunRecordSchemaVersion = 1 - -// RunRecord is the versioned, durable representation of one flow execution. -// Consumers should use SchemaVersion when decoding records across releases. -type RunRecord struct { - SchemaVersion int `json:"schema_version"` - Run Run `json:"run"` -} - -// LoadRunRecord loads one versioned flow run from checkpoint storage. A -// missing run returns an empty record carrying the requested flow and run id. -func LoadRunRecord(ctx context.Context, checkpoint Checkpoint, flowName, runID string) (RunRecord, error) { - if checkpoint == nil { - checkpoint = StoreCheckpoint(nil, flowName) - } - run, ok, err := checkpoint.Load(ctx, runID) - if err != nil { - return RunRecord{}, err - } - if !ok { - run = Run{ID: runID, Flow: flowName} - } - return RunRecord{SchemaVersion: RunRecordSchemaVersion, Run: run}, nil -} diff --git a/flow/record_test.go b/flow/record_test.go deleted file mode 100644 index 83e90ec3c1..0000000000 --- a/flow/record_test.go +++ /dev/null @@ -1,53 +0,0 @@ -package flow - -import ( - "context" - "encoding/json" - "testing" - "time" - - "go-micro.dev/v6/store" -) - -func TestLoadRunRecordReturnsVersionedFlowExecution(t *testing.T) { - ctx := context.Background() - cp := StoreCheckpoint(store.NewMemoryStore(), "checkout") - want := Run{ - ID: "flow-run-1", Flow: "checkout", Dispatch: "schedule", Trigger: "nightly", Status: "done", - Started: time.Unix(100, 0).UTC(), - Steps: []StepRecord{{Name: "charge", Status: "done", Attempts: 1, Service: "payments", Endpoint: "Payments.Charge"}, - {Name: "notify", Status: "done", Attempts: 1, Agent: "comms", ChildRunID: "agent-run-1"}}, - } - if err := cp.Save(ctx, want); err != nil { - t.Fatal(err) - } - record, err := LoadRunRecord(ctx, cp, "checkout", want.ID) - if err != nil { - t.Fatal(err) - } - if record.SchemaVersion != RunRecordSchemaVersion || record.Run.ID != want.ID || - record.Run.Steps[1].ChildRunID != "agent-run-1" { - t.Fatalf("record = %#v", record) - } - data, err := json.Marshal(record) - if err != nil { - t.Fatal(err) - } - var decoded RunRecord - if err := json.Unmarshal(data, &decoded); err != nil { - t.Fatal(err) - } - if decoded.SchemaVersion != RunRecordSchemaVersion || decoded.Run.Steps[0].Service != "payments" { - t.Fatalf("decoded record = %#v", decoded) - } -} - -func TestLoadRunRecordMissingCarriesRequestedIdentity(t *testing.T) { - record, err := LoadRunRecord(context.Background(), StoreCheckpoint(store.NewMemoryStore(), "checkout"), "checkout", "missing") - if err != nil { - t.Fatal(err) - } - if record.SchemaVersion != RunRecordSchemaVersion || record.Run.Flow != "checkout" || record.Run.ID != "missing" || record.Run.Status != "" { - t.Fatalf("missing record = %#v", record) - } -} diff --git a/flow/registry_test.go b/flow/registry_test.go deleted file mode 100644 index ba03b09602..0000000000 --- a/flow/registry_test.go +++ /dev/null @@ -1,65 +0,0 @@ -package flow - -import ( - "context" - "testing" - - "go-micro.dev/v6/broker" - "go-micro.dev/v6/client" - "go-micro.dev/v6/registry" -) - -// A trigger-bound flow announces itself in the registry as type=flow -// while running, and deregisters on Stop — liveness, like a service. -func TestFlowRegistersAndDeregisters(t *testing.T) { - reg := registry.NewMemoryRegistry() - br := broker.NewMemoryBroker() - if err := br.Connect(); err != nil { - t.Fatalf("broker connect: %v", err) - } - - f := New("onboard", - Trigger("events.user.created"), - Steps(appendStep("a")), - ) - if err := f.Register(reg, br, client.DefaultClient); err != nil { - t.Fatalf("Register: %v", err) - } - - svcs, err := reg.GetService("onboard") - if err != nil || len(svcs) == 0 { - t.Fatalf("flow not registered: %v", err) - } - if svcs[0].Metadata["type"] != "flow" { - t.Errorf("registry metadata type = %q, want flow", svcs[0].Metadata["type"]) - } - if svcs[0].Metadata["trigger"] != "events.user.created" { - t.Errorf("registry metadata trigger = %q", svcs[0].Metadata["trigger"]) - } - - if err := f.Stop(); err != nil { - t.Fatalf("Stop: %v", err) - } - if svcs, _ := reg.GetService("onboard"); len(svcs) != 0 { - t.Errorf("flow should be deregistered after Stop, got %d services", len(svcs)) - } -} - -// A flow without a trigger is not a running listener and isn't registered. -func TestFlowWithoutTriggerNotRegistered(t *testing.T) { - reg := registry.NewMemoryRegistry() - br := broker.NewMemoryBroker() - _ = br.Connect() - - f := New("oneshot", Steps(appendStep("a"))) - if err := f.Register(reg, br, client.DefaultClient); err != nil { - t.Fatalf("Register: %v", err) - } - if svcs, _ := reg.GetService("oneshot"); len(svcs) != 0 { - t.Errorf("triggerless flow should not register, got %d", len(svcs)) - } - // It still runs on demand. - if err := f.Execute(context.Background(), ""); err != nil { - t.Fatalf("Execute: %v", err) - } -} diff --git a/flow/schedule.go b/flow/schedule.go deleted file mode 100644 index a669ae3308..0000000000 --- a/flow/schedule.go +++ /dev/null @@ -1,60 +0,0 @@ -package flow - -import ( - "context" - "time" - - "go-micro.dev/v6/model" -) - -// Schedule binds a flow to a recurring work item without introducing a -// scheduler service. It is a small harness contract: callers own the clock, -// Go Micro owns turning each tick into the same inspectable flow run used for -// broker events and direct Execute calls. -type Schedule struct { - flow *Flow - data string -} - -// Scheduled returns a deterministic scheduled-run harness for this flow. -// Tests and event loops can call Tick directly; production processes can wire -// the same contract to time.Ticker through RunEvery. Each tick calls Execute, so -// checkpointed run history, parent/run metadata, cancellation, and inspection -// stay on the normal flow surfaces. -func Scheduled(f *Flow, data string) Schedule { - return Schedule{flow: f, data: data} -} - -// Tick starts one scheduled run immediately and returns when that run finishes. -func (s Schedule) Tick(ctx context.Context) error { - if ctx == nil { - ctx = context.Background() - } - info, _ := model.RunInfoFrom(ctx) - info.Dispatch = "schedule" - if info.Trigger == "" { - info.Trigger = s.flow.opts.TriggerTopic - } - if info.Trigger == "" { - info.Trigger = "schedule" - } - return s.flow.Execute(model.WithRunInfo(ctx, info), s.data) -} - -// RunEvery drives scheduled runs from a ticker until ctx is canceled. It does -// not persist schedule definitions or host a scheduler; it only adapts a caller -// owned cadence to Tick. -func (s Schedule) RunEvery(ctx context.Context, interval time.Duration) error { - ticker := time.NewTicker(interval) - defer ticker.Stop() - for { - select { - case <-ctx.Done(): - return ctx.Err() - case <-ticker.C: - if err := s.Tick(ctx); err != nil { - return err - } - } - } -} diff --git a/flow/steps.go b/flow/steps.go deleted file mode 100644 index 39459a70fc..0000000000 --- a/flow/steps.go +++ /dev/null @@ -1,658 +0,0 @@ -package flow - -import ( - "bytes" - "context" - "encoding/json" - "errors" - "fmt" - "text/template" - "time" - - "github.com/google/uuid" - "go-micro.dev/v6/agent/run" - "go-micro.dev/v6/client" - codecbytes "go-micro.dev/v6/codec/bytes" - "go-micro.dev/v6/gateway/a2a" - "go-micro.dev/v6/logger" - "go-micro.dev/v6/model" - "go-micro.dev/v6/store" -) - -// State carries data across the steps of a run. -type State = run.State - -// StepFunc performs one step's work: it receives the carried state and -// returns the next state. -type StepFunc func(ctx context.Context, in State) (State, error) - -// Verifier grades a step output before the flow advances. Returning -// Passed=false converts the grade into a retryable VerificationError, so -// the existing step retry/supervision path can feed Feedback into the next -// attempt through model.RunInfo.VerificationFeedback. -type Verifier func(ctx context.Context, out State) (Verification, error) - -// Verification is the verifier's deterministic grade for one step attempt. -type Verification struct { - Passed bool - Feedback string -} - -// VerificationError reports a failed grade. It is returned from runStep so -// existing retry, checkpoint, and trace paths handle verifier failures the -// same way they handle step execution failures. -type VerificationError struct { - Step string - Feedback string -} - -func (e *VerificationError) Error() string { - if e.Feedback == "" { - return fmt.Sprintf("flow: verification failed for step %q", e.Step) - } - return fmt.Sprintf("flow: verification failed for step %q: %s", e.Step, e.Feedback) -} - -// Step is one unit of a flow — a named action with optional retry and -// verification hooks. There is one Step kind; the action is the Run func, -// and the Call/LLM/Agent helpers produce the common ones. -type Step struct { - Name string - Run StepFunc - Retry int // per-step override of the flow's retry (0 = use the flow default) - Verify Verifier // optional grade; failed grades retry the step with feedback in RunInfo -} - -// StepRecord is the recorded outcome of one step. -type StepRecord = run.StepRecord - -// Run is the persisted execution record, shared with agents. -type Run = run.Run - -// Checkpoint persists and restores runs. -type Checkpoint = run.Checkpoint - -// StoreCheckpoint returns checkpoint storage compatible with existing v6 runs. -func StoreCheckpoint(s store.Store, scope string) Checkpoint { - return run.StoreCheckpoint(s, scope) -} - -// defaultCheckpoint returns the configured checkpoint, or a store-backed -// default scoped to the flow name when the flow has steps (durable by -// default). Scoping by name keeps each flow's runs in their own keyspace -// rather than a global one. -func defaultCheckpoint(name string, o Options) Checkpoint { - if o.Checkpoint != nil { - return o.Checkpoint - } - if len(o.Steps) > 0 { - return StoreCheckpoint(store.DefaultStore, name) - } - return nil -} - -// runDeps are the flow resources the Call/LLM/Agent step helpers need. -// They are injected into the context for the duration of a run so a -// StepFunc keeps the clean (ctx, State) signature. -type runDeps struct { - client client.Client - model model.Model - tools *model.Tools - step *StepRecord -} - -type runCtxKey struct{} - -func withDeps(ctx context.Context, d *runDeps) context.Context { - return context.WithValue(ctx, runCtxKey{}, d) -} - -func depsFrom(ctx context.Context) *runDeps { - d, _ := ctx.Value(runCtxKey{}).(*runDeps) - return d -} - -// Call returns a StepFunc that invokes an RPC endpoint, sending the -// current state Data as the request body and storing the response as the -// new Data. -func Call(service, endpoint string) StepFunc { - return func(ctx context.Context, in State) (State, error) { - cl := client.DefaultClient - if d := depsFrom(ctx); d != nil { - if d.client != nil { - cl = d.client - } - if d.step != nil { - d.step.Service = service - d.step.Endpoint = endpoint - } - } - body := in.Data - if len(body) == 0 { - body = []byte("{}") - } - req := cl.NewRequest(service, endpoint, &codecbytes.Frame{Data: body}) - var rsp codecbytes.Frame - if err := cl.Call(ctx, req, &rsp); err != nil { - return in, err - } - in.Data = rsp.Data - return in, nil - } -} - -// Dispatch returns a StepFunc that hands the current state Data (as the -// message) to a registered agent's Agent.Chat endpoint and stores the -// reply as the new Data. -func Dispatch(name string) StepFunc { - return func(ctx context.Context, in State) (State, error) { - cl := client.DefaultClient - d := depsFrom(ctx) - if d != nil { - if d.client != nil { - cl = d.client - } - if d.step != nil { - d.step.Agent = name - } - } - info, _ := model.RunInfoFrom(ctx) - body, _ := json.Marshal(map[string]string{"message": in.String(), "parent_id": info.RunID}) - req := cl.NewRequest(name, "Agent.Chat", &codecbytes.Frame{Data: body}) - var rsp codecbytes.Frame - if err := cl.Call(ctx, req, &rsp); err != nil { - return in, err - } - var out struct { - Reply string `json:"reply"` - RunID string `json:"run_id"` - } - _ = json.Unmarshal(rsp.Data, &out) - if d != nil && d.step != nil { - d.step.ChildRunID = out.RunID - } - in.Data = []byte(out.Reply) - return in, nil - } -} - -// A2A returns a StepFunc that calls a remote agent over the A2A protocol -// by URL — the cross-framework counterpart to Dispatch. It sends the -// current state Data as the message and stores the reply as the new Data. -func A2A(url string) StepFunc { - return func(ctx context.Context, in State) (State, error) { - reply, err := a2a.NewClient(url).Send(ctx, in.String()) - if err != nil { - return in, err - } - in.Data = []byte(reply) - return in, nil - } -} - -// LLM returns a StepFunc that runs one augmented-LLM turn: it renders the -// prompt template against the current state (.Data, .Stage), lets the -// model call the flow's services as tools, and stores the reply as the -// new Data. -func LLM(prompt string) StepFunc { - return func(ctx context.Context, in State) (State, error) { - d := depsFrom(ctx) - if d == nil || d.model == nil { - return in, fmt.Errorf("LLM step requires a flow model (set Provider/APIKey)") - } - text := prompt - if tmpl, err := template.New("step").Parse(prompt); err == nil { - var buf bytes.Buffer - if tmpl.Execute(&buf, map[string]string{"Data": in.String(), "Stage": in.Stage}) == nil { - text = buf.String() - } - } - var tools []model.Tool - if d.tools != nil { - tools, _ = d.tools.Discover() - } - resp, err := d.model.Generate(ctx, &model.Request{Prompt: text, Tools: tools}) - if err != nil { - return in, err - } - reply := resp.Answer - if reply == "" { - reply = resp.Reply - } - in.Data = []byte(reply) - return in, nil - } -} - -// AwaitInput is the control signal a step returns (via Await) to suspend a run -// pending external input. runFrom recognizes it, checkpoints the run as -// "waiting", and returns cleanly — a suspend is not a failure. ResumeWith -// injects the input and continues. -type AwaitInput struct { - Key string // labels what is awaited (e.g. "approval") - Prompt string // human-facing description of the input needed -} - -func (e *AwaitInput) Error() string { - if e.Prompt != "" { - return fmt.Sprintf("flow: awaiting input %q: %s", e.Key, e.Prompt) - } - return fmt.Sprintf("flow: awaiting input %q", e.Key) -} - -// AwaitState records what a suspended run is waiting for. -type AwaitState = run.AwaitState - -func isAwaitInput(err error) (*AwaitInput, bool) { - var a *AwaitInput - if errors.As(err, &a) { - return a, true - } - return nil, false -} - -// Await is a StepFunc that suspends the run pending external input. The run is -// checkpointed with status "waiting" and returned cleanly; a later call to -// Flow.ResumeWith(ctx, runID, input) completes this step with the injected -// input and continues to the next step. key labels what is awaited (surfaced on -// the run and via Flow.Waiting); prompt describes the input needed. -func Await(key, prompt string) StepFunc { - return func(_ context.Context, in State) (State, error) { - return in, &AwaitInput{Key: key, Prompt: prompt} - } -} - -// AwaitStep is a convenience for a named await step: -// Step{Name: name, Run: Await(key, prompt)}. -func AwaitStep(name, key, prompt string) Step { - return Step{Name: name, Run: Await(key, prompt)} -} - -// startRun begins a fresh run of the flow's steps with the given input. -func (f *Flow) startRun(ctx context.Context, data string) (Run, error) { - if err := validateSteps(f.opts.Steps); err != nil { - return Run{}, err - } - info, _ := model.RunInfoFrom(ctx) - dispatch := info.Dispatch - if dispatch == "" { - dispatch = "direct" - } - run := Run{ - ID: uuid.New().String(), - ParentID: info.RunID, - Flow: f.name, - Dispatch: dispatch, - Trigger: info.Trigger, - State: State{Stage: f.opts.Steps[0].Name, Data: []byte(data)}, - Status: "running", - Started: time.Now(), - } - for _, s := range f.opts.Steps { - run.Steps = append(run.Steps, StepRecord{Name: s.Name, Status: "pending"}) - } - return f.runFrom(ctx, run) -} - -// Resume continues a persisted run by id, picking up at the step it -// stopped on. Completed runs are a no-op. -func (f *Flow) Resume(ctx context.Context, runID string) error { - ctx, cancel := f.withTimeout(ctx) - defer cancel() - - if err := validateSteps(f.opts.Steps); err != nil { - return err - } - if f.checkpoint == nil { - return fmt.Errorf("flow %s has no checkpoint configured", f.name) - } - run, ok, err := f.checkpoint.Load(ctx, runID) - if err != nil { - return err - } - if !ok { - return fmt.Errorf("run %s not found", runID) - } - if run.Status == "done" { - return nil - } - _, err = f.runFrom(ctx, run) - return err -} - -// ResumePending resumes every checkpointed run for this flow that has not -// completed yet, in the same oldest-first order returned by Pending. -// -// It is a convenience for service startup and recovery loops: after a process -// restart, call ResumePending to drain the durable backlog without having to -// list and resume each run manually. If any run fails again, ResumePending -// stops and returns that run id with the error so callers can log, alert, or -// retry later without hiding the failing run. -func (f *Flow) ResumePending(ctx context.Context) (string, error) { - ctx, cancel := f.withTimeout(ctx) - defer cancel() - - runs, err := f.Pending(ctx) - if err != nil { - return "", err - } - for _, run := range runs { - if err := f.Resume(ctx, run.ID); err != nil { - return run.ID, err - } - } - return "", nil -} - -// Pending returns this flow's runs that have not completed — the ones a -// process restart should resume. -func (f *Flow) Pending(ctx context.Context) ([]Run, error) { - if f.checkpoint == nil { - return nil, nil - } - all, err := f.checkpoint.List(ctx) - if err != nil { - return nil, err - } - var out []Run - for _, r := range all { - // Waiting runs need injected input (ResumeWith), not a restart, so a - // recovery loop (ResumePending) should not pick them up. - if r.Flow == f.name && r.Status != "done" && r.Status != "waiting" { - out = append(out, r) - } - } - return out, nil -} - -// Waiting returns this flow's runs suspended awaiting external input, each with -// its Await metadata, so a caller can prompt for and inject the needed input -// with ResumeWith. -func (f *Flow) Waiting(ctx context.Context) ([]Run, error) { - if f.checkpoint == nil { - return nil, nil - } - all, err := f.checkpoint.List(ctx) - if err != nil { - return nil, err - } - var out []Run - for _, r := range all { - if r.Flow == f.name && r.Status == "waiting" { - out = append(out, r) - } - } - return out, nil -} - -// ResumeWith completes a suspended (waiting) run: it injects input for the -// awaited step — the input becomes that step's output state — and continues -// from the next step. It errors if the run is not waiting for input. -func (f *Flow) ResumeWith(ctx context.Context, runID, input string) error { - ctx, cancel := f.withTimeout(ctx) - defer cancel() - - if err := validateSteps(f.opts.Steps); err != nil { - return err - } - if f.checkpoint == nil { - return fmt.Errorf("flow %s has no checkpoint configured", f.name) - } - run, ok, err := f.checkpoint.Load(ctx, runID) - if err != nil { - return err - } - if !ok { - return fmt.Errorf("run %s not found", runID) - } - if run.Status != "waiting" { - return fmt.Errorf("run %s is not waiting for input (status %q)", runID, run.Status) - } - steps := f.opts.Steps - i := stepIndex(steps, run.State.Stage) - if i < 0 { - return fmt.Errorf("run %s is waiting at unknown step %q", runID, run.State.Stage) - } - // The awaited step is satisfied by the injected input; record it done and - // advance so runFrom re-enters at the next step. - run.Steps[i].Status = "done" - run.Steps[i].Result = truncate(input, 200) - run.State.Data = []byte(input) - if i+1 < len(steps) { - run.State.Stage = steps[i+1].Name - } else { - run.State.Stage = "" - } - run.Await = nil - run.Status = "running" - _, err = f.runFrom(ctx, run) - return err -} - -// runFrom executes steps from the run's current Stage to the end, -// checkpointing before and after each step. -func (f *Flow) runFrom(ctx context.Context, run Run) (Run, error) { - steps := f.opts.Steps - deps := &runDeps{client: f.client, model: f.model, tools: f.toolSet} - ctx = withDeps(ctx, deps) - info, _ := model.RunInfoFrom(ctx) - info.RunID = run.ID - info.ParentID = run.ParentID - info.Agent = f.name - info.Flow = f.name - info.Dispatch = run.Dispatch - info.Trigger = run.Trigger - ctx = model.WithRunInfo(ctx, info) - ctx, finishSpan := f.startRunSpan(ctx, run) - var spanErr error - defer func() { finishSpan(run, spanErr) }() - - start := stepIndex(steps, run.State.Stage) - if start < 0 { - if run.State.Stage == "" { - start = len(steps) // already finished - } else { - start = 0 - } - } - - for i := start; i < len(steps); i++ { - step := steps[i] - deps.step = &run.Steps[i] - run.State.Stage = step.Name - run.Steps[i].Status = "in_progress" - if err := f.save(ctx, run); err != nil { - spanErr = err - return run, err - } - - out, attempts, verification, err := f.runStepSpan(ctx, step, run.State) - run.Steps[i].Attempts = attempts - applyVerificationRecord(&run.Steps[i], verification) - if await, ok := isAwaitInput(err); ok { - // Suspend the run pending external input — checkpoint and return - // cleanly (not a failure). ResumeWith injects the input later. - run.Steps[i].Status = "waiting" - run.Status = "waiting" - run.Await = &AwaitState{Step: step.Name, Key: await.Key, Prompt: await.Prompt} - if saveErr := f.save(ctx, run); saveErr != nil { - spanErr = saveErr - return run, saveErr - } - f.log.Logf(logger.InfoLevel, "Flow %s run %s waiting for input %q at step %q", f.name, run.ID, await.Key, step.Name) - return run, nil - } - if err != nil { - spanErr = err - run.Steps[i].Status = "failed" - run.Steps[i].Error = err.Error() - run.Steps[i].ErrorKind = string(model.ClassifyError(err)) - run.Status = "failed" - if saveErr := f.save(ctx, run); saveErr != nil { - spanErr = saveErr - return run, fmt.Errorf("%w; additionally failed to checkpoint failed run: %v", err, saveErr) - } - f.record(resultFromRun(f.opts.TriggerTopic, run)) - f.log.Logf(logger.ErrorLevel, "Flow %s run %s failed at step %q: %v", f.name, run.ID, step.Name, err) - return run, err - } - - run.State = out - run.Steps[i].Status = "done" - run.Steps[i].Result = truncate(out.String(), 200) - if i+1 < len(steps) { - run.State.Stage = steps[i+1].Name - } else { - run.State.Stage = "" - } - if err := f.save(ctx, run); err != nil { - spanErr = err - return run, err - } - } - - run.Status = "done" - if err := f.save(ctx, run); err != nil { - spanErr = err - return run, err - } - if f.opts.DeleteOnSuccess && f.checkpoint != nil { - if err := f.checkpoint.Delete(ctx, run.ID); err != nil { - spanErr = err - return run, err - } - } - f.record(resultFromRun(f.opts.TriggerTopic, run)) - f.log.Logf(logger.InfoLevel, "Flow %s run %s completed (%d steps)", f.name, run.ID, len(steps)) - return run, nil -} - -// runStep runs one step, retrying on error up to the resolved retry count. -// A step with no Run function is a configuration error, and a canceled run -// stops retrying immediately rather than burning the rest of its budget. -func (f *Flow) runStep(ctx context.Context, step Step, in State) (State, int, Verification, error) { - if step.Run == nil { - return in, 0, Verification{}, fmt.Errorf("flow: step %q has no Run function", step.Name) - } - retries := f.opts.Retry - if step.Retry > 0 { - retries = step.Retry - } - var lastErr error - var lastVerification Verification - var feedback string - for attempt := 1; attempt <= retries+1; attempt++ { - // Stop the moment the run's context is canceled or its deadline - // passes — a canceled run shouldn't keep retrying, and the context - // error is surfaced so callers can detect cancellation upstream. - if err := ctx.Err(); err != nil { - return in, attempt - 1, lastVerification, err - } - attemptCtx := ctx - if info, ok := model.RunInfoFrom(ctx); ok { - info.Step = step.Name - info.VerificationFeedback = feedback - attemptCtx = model.WithRunInfo(ctx, info) - } - out, err := step.Run(attemptCtx, in) - // An await signal is control flow, not a failure: suspend immediately - // without retrying or grading. - if _, ok := isAwaitInput(err); ok { - return in, attempt, lastVerification, err - } - if err == nil && step.Verify != nil { - lastVerification, err = step.Verify(attemptCtx, out) - if err == nil && !lastVerification.Passed { - err = &VerificationError{Step: step.Name, Feedback: lastVerification.Feedback} - } - } - if err == nil { - return out, attempt, lastVerification, nil - } - lastErr = err - if verr, ok := err.(*VerificationError); ok { - feedback = verr.Feedback - } - if attempt <= retries && f.opts.RetryBackoff > 0 { - select { - case <-time.After(f.opts.RetryBackoff): - case <-ctx.Done(): - return in, attempt, lastVerification, ctx.Err() - } - } - } - return in, retries + 1, lastVerification, lastErr -} - -func applyVerificationRecord(record *StepRecord, verification Verification) { - if verification.Passed { - record.VerificationStatus = "passed" - } - if verification.Feedback != "" { - record.VerificationNote = truncate(verification.Feedback, 200) - if !verification.Passed { - record.VerificationStatus = "failed" - } - } -} - -func (f *Flow) save(ctx context.Context, run Run) error { - if f.checkpoint == nil { - return nil - } - if err := f.checkpoint.Save(ctx, run); err != nil { - f.log.Logf(logger.ErrorLevel, "Flow %s checkpoint save: %v", f.name, err) - return fmt.Errorf("flow %s checkpoint save: %w", f.name, err) - } - return nil -} - -func validateSteps(steps []Step) error { - seen := make(map[string]struct{}, len(steps)) - for i, step := range steps { - if step.Name == "" { - return fmt.Errorf("flow: step %d has an empty name", i) - } - if _, ok := seen[step.Name]; ok { - return fmt.Errorf("flow: duplicate step name %q", step.Name) - } - seen[step.Name] = struct{}{} - } - return nil -} - -func stepIndex(steps []Step, name string) int { - for i, s := range steps { - if s.Name == name { - return i - } - } - return -1 -} - -func resultFromRun(trigger string, run Run) Result { - r := Result{ - FlowName: run.Flow, - Trigger: trigger, - Timestamp: run.Started, - Duration: run.Updated.Sub(run.Started).Seconds(), - } - for _, s := range run.Steps { - r.ToolCalls = append(r.ToolCalls, s.Name+":"+s.Status) - if s.Error != "" { - r.Error = s.Error - r.ErrorKind = s.ErrorKind - } - } - if run.Status == "done" { - r.Answer = run.State.String() - } - return r -} - -func truncate(s string, n int) string { - if len(s) <= n { - return s - } - return s[:n] + "…" -} diff --git a/flow/steps_test.go b/flow/steps_test.go deleted file mode 100644 index 1ba90c05a2..0000000000 --- a/flow/steps_test.go +++ /dev/null @@ -1,674 +0,0 @@ -package flow - -import ( - "context" - "errors" - "testing" - "time" - - "go-micro.dev/v6/model" - "go-micro.dev/v6/store" -) - -// appendStep returns a step that appends its name to the carried data, -// so a run's path is visible in the final State. -func appendStep(name string) Step { - return Step{Name: name, Run: func(_ context.Context, in State) (State, error) { - s := in.String() - if s != "" { - s += "," - } - in.Data = []byte(s + name) - return in, nil - }} -} - -func TestFlowStepsRunInOrder(t *testing.T) { - f := New("seq", - WithCheckpoint(StoreCheckpoint(store.NewMemoryStore(), "seq")), - Steps(appendStep("a"), appendStep("b"), appendStep("c")), - ) - if err := f.Execute(context.Background(), ""); err != nil { - t.Fatalf("Execute: %v", err) - } - res := f.Results() - if len(res) != 1 || res[0].Answer != "a,b,c" { - t.Fatalf("steps ran out of order: %+v", res) - } -} - -// A run that fails mid-way is persisted at the failing step and resumes -// there — without re-running the completed steps. -func TestFlowCheckpointResume(t *testing.T) { - mem := store.NewMemoryStore() - var firstCalls, fixed int - - steps := []Step{ - {Name: "first", Run: func(_ context.Context, in State) (State, error) { - firstCalls++ - in.Data = []byte("first-done") - return in, nil - }}, - {Name: "flaky", Run: func(_ context.Context, in State) (State, error) { - if fixed == 0 { - return in, errors.New("dependency unavailable") - } - in.Data = []byte("flaky-done") - return in, nil - }}, - } - - f := New("resumable", WithCheckpoint(StoreCheckpoint(mem, "resumable")), Steps(steps...)) - - // First run fails at "flaky". - if err := f.Execute(context.Background(), "start"); err == nil { - t.Fatal("expected the run to fail at the flaky step") - } - - pend, _ := f.Pending(context.Background()) - if len(pend) != 1 { - t.Fatalf("expected 1 pending run, got %d", len(pend)) - } - if pend[0].State.Stage != "flaky" { - t.Fatalf("run should be checkpointed at the flaky step, got stage %q", pend[0].State.Stage) - } - runID := pend[0].ID - - // The dependency recovers; resume continues from where it stopped. - fixed = 1 - if err := f.Resume(context.Background(), runID); err != nil { - t.Fatalf("Resume: %v", err) - } - if firstCalls != 1 { - t.Errorf("completed step should not re-run on resume; first called %d times", firstCalls) - } - if pend, _ := f.Pending(context.Background()); len(pend) != 0 { - t.Errorf("expected no pending runs after a successful resume, got %d", len(pend)) - } -} - -func TestFlowAwaitAndResumeWith(t *testing.T) { - mem := store.NewMemoryStore() - var firstCalls int - var secondInput string - - steps := []Step{ - {Name: "first", Run: func(_ context.Context, in State) (State, error) { - firstCalls++ - in.Data = []byte("first-done") - return in, nil - }}, - AwaitStep("approval", "approve", "Approve to continue?"), - {Name: "second", Run: func(_ context.Context, in State) (State, error) { - secondInput = in.String() - in.Data = []byte("second-done") - return in, nil - }}, - } - - f := New("hitl", WithCheckpoint(StoreCheckpoint(mem, "hitl")), Steps(steps...)) - - // Execute suspends at the await step — a clean return, not an error. - if err := f.Execute(context.Background(), "start"); err != nil { - t.Fatalf("Execute should suspend cleanly, got %v", err) - } - if firstCalls != 1 { - t.Fatalf("first step calls = %d, want 1", firstCalls) - } - - // A waiting run is not pending (restart), it needs input. - if pend, _ := f.Pending(context.Background()); len(pend) != 0 { - t.Errorf("a waiting run must not be pending, got %d", len(pend)) - } - waiting, err := f.Waiting(context.Background()) - if err != nil { - t.Fatal(err) - } - if len(waiting) != 1 { - t.Fatalf("waiting runs = %d, want 1", len(waiting)) - } - w := waiting[0] - if w.Status != "waiting" || w.Await == nil || w.Await.Key != "approve" || - w.Await.Prompt != "Approve to continue?" || w.Await.Step != "approval" { - t.Fatalf("await metadata = %+v (status %q)", w.Await, w.Status) - } - if w.State.Stage != "approval" { - t.Fatalf("waiting stage = %q, want approval", w.State.Stage) - } - - // Injecting input completes the awaited step and runs the rest. - if err := f.ResumeWith(context.Background(), w.ID, "approved"); err != nil { - t.Fatalf("ResumeWith: %v", err) - } - if firstCalls != 1 { - t.Errorf("completed step re-ran on resume; first calls = %d", firstCalls) - } - if secondInput != "approved" { - t.Errorf("second step input = %q, want the injected 'approved'", secondInput) - } - if wr, _ := f.Waiting(context.Background()); len(wr) != 0 { - t.Errorf("no waiting runs after resume, got %d", len(wr)) - } - runs, _ := StoreCheckpoint(mem, "hitl").List(context.Background()) - if len(runs) != 1 || runs[0].Status != "done" { - t.Fatalf("run should be done after resume, got %+v", runs) - } - if runs[0].Await != nil { - t.Errorf("await metadata should be cleared after resume, got %+v", runs[0].Await) - } -} - -func TestFlowResumeWithRejectsNonWaiting(t *testing.T) { - mem := store.NewMemoryStore() - f := New("hitl2", WithCheckpoint(StoreCheckpoint(mem, "hitl2")), - Steps(Step{Name: "only", Run: func(_ context.Context, in State) (State, error) { return in, nil }})) - if err := f.Execute(context.Background(), "x"); err != nil { - t.Fatalf("Execute: %v", err) - } - runs, _ := StoreCheckpoint(mem, "hitl2").List(context.Background()) - if len(runs) != 1 { - t.Fatalf("runs = %d", len(runs)) - } - if err := f.ResumeWith(context.Background(), runs[0].ID, "input"); err == nil { - t.Error("ResumeWith on a completed (non-waiting) run should error") - } -} - -func TestFlowStepContextIncludesRunInfo(t *testing.T) { - var got model.RunInfo - step := Step{Name: "inspect", Run: func(ctx context.Context, in State) (State, error) { - var ok bool - got, ok = model.RunInfoFrom(ctx) - if !ok { - t.Fatal("RunInfo missing from step context") - } - in.Data = []byte("ok") - return in, nil - }} - - mem := store.NewMemoryStore() - f := New("correlated", - WithCheckpoint(StoreCheckpoint(mem, "correlated")), - Steps(step), - ) - ctx := model.WithRunInfo(context.Background(), model.RunInfo{RunID: "agent-run-1", Agent: "planner"}) - if err := f.Execute(ctx, "start"); err != nil { - t.Fatalf("Execute: %v", err) - } - if got.Agent != "correlated" { - t.Fatalf("RunInfo.Agent = %q, want correlated", got.Agent) - } - if got.RunID == "" { - t.Fatal("RunInfo.RunID is empty") - } - if got.Flow != "correlated" { - t.Fatalf("RunInfo.Flow = %q, want correlated", got.Flow) - } - if got.ParentID != "agent-run-1" { - t.Fatalf("RunInfo.ParentID = %q, want agent-run-1", got.ParentID) - } - if got.Step != "inspect" { - t.Fatalf("RunInfo.Step = %q, want inspect", got.Step) - } - if got.Dispatch != "direct" { - t.Fatalf("RunInfo.Dispatch = %q, want direct", got.Dispatch) - } - runs, err := StoreCheckpoint(mem, "correlated").List(context.Background()) - if err != nil { - t.Fatalf("List: %v", err) - } - if len(runs) != 1 || runs[0].ParentID != "agent-run-1" || runs[0].Dispatch != "direct" { - t.Fatalf("persisted parent id = %+v, want agent-run-1", runs) - } -} - -func TestFlowResumePendingResumesOldestRunsUntilFailure(t *testing.T) { - mem := store.NewMemoryStore() - ctx := context.Background() - var calls int - step := Step{Name: "work", Run: func(_ context.Context, in State) (State, error) { - calls++ - if in.String() == "block" { - return in, errors.New("still blocked") - } - in.Data = []byte(in.String() + "-done") - return in, nil - }} - f := New("resume-pending", WithCheckpoint(StoreCheckpoint(mem, "resume-pending")), Steps(step)) - - base := time.Date(2026, 6, 24, 12, 0, 0, 0, time.UTC) - runs := []Run{ - { - ID: "run-ok", - Flow: "resume-pending", - State: State{Stage: "work", Data: []byte("ok")}, - Steps: []StepRecord{{Name: "work", Status: "failed", Error: "temporary"}}, - Status: "failed", - Started: base, - }, - { - ID: "run-blocked", - Flow: "resume-pending", - State: State{Stage: "work", Data: []byte("block")}, - Steps: []StepRecord{{Name: "work", Status: "failed", Error: "temporary"}}, - Status: "failed", - Started: base.Add(time.Minute), - }, - { - ID: "run-later", - Flow: "resume-pending", - State: State{Stage: "work", Data: []byte("later")}, - Steps: []StepRecord{{Name: "work", Status: "failed", Error: "temporary"}}, - Status: "failed", - Started: base.Add(2 * time.Minute), - }, - } - for _, run := range runs { - if err := f.checkpoint.Save(ctx, run); err != nil { - t.Fatalf("Save(%s): %v", run.ID, err) - } - } - - failedRun, err := f.ResumePending(ctx) - if err == nil { - t.Fatal("expected ResumePending to stop at the blocked run") - } - if failedRun != "run-blocked" { - t.Fatalf("failed run = %q, want run-blocked", failedRun) - } - if calls != 2 { - t.Fatalf("ResumePending should stop before later runs; got %d calls", calls) - } - - run, ok, err := f.checkpoint.Load(ctx, "run-ok") - if err != nil || !ok { - t.Fatalf("Load(run-ok) ok=%v err=%v", ok, err) - } - if run.Status != "done" || run.State.String() != "ok-done" { - t.Fatalf("run-ok not resumed successfully: %+v", run) - } - run, ok, err = f.checkpoint.Load(ctx, "run-later") - if err != nil || !ok { - t.Fatalf("Load(run-later) ok=%v err=%v", ok, err) - } - if run.Status != "failed" { - t.Fatalf("run-later should not be resumed after a failure, got %+v", run) - } -} - -// A flow-level Retry re-runs a failing step until it succeeds. -func TestFlowStepRetry(t *testing.T) { - var attempts int - step := Step{Name: "transient", Run: func(_ context.Context, in State) (State, error) { - attempts++ - if attempts < 3 { - return in, errors.New("transient") - } - in.Data = []byte("ok") - return in, nil - }} - - f := New("retrying", - WithCheckpoint(StoreCheckpoint(store.NewMemoryStore(), "retrying")), - Retry(2), // up to 3 tries - Steps(step), - ) - if err := f.Execute(context.Background(), ""); err != nil { - t.Fatalf("Execute: %v", err) - } - if attempts != 3 { - t.Errorf("want 3 attempts with Retry(2), got %d", attempts) - } -} - -// A per-step Retry overrides the flow default. -func TestFlowStepRetryOverride(t *testing.T) { - var attempts int - step := Step{Name: "capped", Retry: 1, Run: func(_ context.Context, in State) (State, error) { - attempts++ - return in, errors.New("always fails") - }} - - f := New("override", - WithCheckpoint(StoreCheckpoint(store.NewMemoryStore(), "override")), - Retry(5), // would be 6 tries; the step's Retry:1 caps it at 2 - Steps(step), - ) - _ = f.Execute(context.Background(), "") - if attempts != 2 { - t.Errorf("per-step Retry(1) should cap tries at 2, got %d", attempts) - } -} - -func TestFlowStepRetryBackoffWaitsBetweenAttempts(t *testing.T) { - var attempts int - step := Step{Name: "transient", Run: func(_ context.Context, in State) (State, error) { - attempts++ - if attempts == 1 { - return in, errors.New("transient") - } - in.Data = []byte("ok") - return in, nil - }} - - f := New("retry-backoff", - WithCheckpoint(StoreCheckpoint(store.NewMemoryStore(), "retry-backoff")), - Retry(1), - RetryBackoff(10*time.Millisecond), - Steps(step), - ) - start := time.Now() - if err := f.Execute(context.Background(), ""); err != nil { - t.Fatalf("Execute: %v", err) - } - if attempts != 2 { - t.Fatalf("want 2 attempts, got %d", attempts) - } - if elapsed := time.Since(start); elapsed < 10*time.Millisecond { - t.Fatalf("retry backoff was not observed; elapsed %s", elapsed) - } -} - -func TestFlowTimeoutStopsRetryBackoff(t *testing.T) { - var attempts int - step := Step{Name: "slow", Run: func(_ context.Context, in State) (State, error) { - attempts++ - return in, errors.New("transient") - }} - - f := New("timeout-backoff", - WithCheckpoint(StoreCheckpoint(store.NewMemoryStore(), "timeout-backoff")), - Timeout(20*time.Millisecond), - Retry(1), - RetryBackoff(time.Hour), - Steps(step), - ) - err := f.Execute(context.Background(), "") - if err == nil { - t.Fatal("expected the timed-out run to fail") - } - if !errors.Is(err, context.DeadlineExceeded) { - t.Errorf("want a context deadline error, got %v", err) - } - if attempts != 1 { - t.Errorf("timeout should stop during backoff before retrying, got %d attempts", attempts) - } -} - -func TestFlowTimeoutRespectsExistingDeadline(t *testing.T) { - ctx, cancel := context.WithTimeout(context.Background(), time.Hour) - defer cancel() - - f := New("existing-deadline", Timeout(time.Millisecond)) - got, stop := f.withTimeout(ctx) - defer stop() - - wantDeadline, _ := ctx.Deadline() - gotDeadline, ok := got.Deadline() - if !ok { - t.Fatal("expected the existing deadline to remain set") - } - if !gotDeadline.Equal(wantDeadline) { - t.Fatalf("deadline = %v, want existing deadline %v", gotDeadline, wantDeadline) - } -} - -func TestFlowStepRetryBackoffStopsOnCancel(t *testing.T) { - ctx, cancel := context.WithCancel(context.Background()) - var attempts int - step := Step{Name: "cancelbackoff", Run: func(_ context.Context, in State) (State, error) { - attempts++ - cancel() - return in, errors.New("transient") - }} - - f := New("cancel-backoff", - WithCheckpoint(StoreCheckpoint(store.NewMemoryStore(), "cancel-backoff")), - Retry(1), - RetryBackoff(time.Hour), - Steps(step), - ) - err := f.Execute(ctx, "") - if err == nil { - t.Fatal("expected the canceled run to fail") - } - if !errors.Is(err, context.Canceled) { - t.Errorf("want a context.Canceled error, got %v", err) - } - if attempts != 1 { - t.Errorf("cancellation should stop during backoff before retrying, got %d attempts", attempts) - } -} - -// A canceled run stops retrying immediately instead of burning the whole -// retry budget, and surfaces the context error. -func TestFlowStepRetryStopsOnCancel(t *testing.T) { - ctx, cancel := context.WithCancel(context.Background()) - - var attempts int - step := Step{Name: "cancelaware", Run: func(_ context.Context, in State) (State, error) { - attempts++ - cancel() // the run is canceled while this step is in flight - return in, errors.New("transient") - }} - - f := New("cancelretry", - WithCheckpoint(StoreCheckpoint(store.NewMemoryStore(), "cancelretry")), - Retry(5), // would be 6 tries without the cancellation check - Steps(step), - ) - - err := f.Execute(ctx, "") - if err == nil { - t.Fatal("expected the canceled run to fail") - } - if !errors.Is(err, context.Canceled) { - t.Errorf("want a context.Canceled error, got %v", err) - } - if attempts != 1 { - t.Errorf("cancellation should stop retries after the first attempt, got %d", attempts) - } -} - -func TestFlowStepNamesMustBeUnique(t *testing.T) { - step := Step{Name: "work", Run: func(_ context.Context, in State) (State, error) { - return in, nil - }} - f := New("duplicate-steps", - WithCheckpoint(StoreCheckpoint(store.NewMemoryStore(), "duplicate-steps")), - Steps(step, step), - ) - - err := f.Execute(context.Background(), "") - if err == nil { - t.Fatal("expected duplicate step names to fail validation") - } - if got, want := err.Error(), `flow: duplicate step name "work"`; got != want { - t.Fatalf("error = %q, want %q", got, want) - } -} - -func TestFlowStepNamesMustBeNonEmpty(t *testing.T) { - f := New("empty-step-name", - WithCheckpoint(StoreCheckpoint(store.NewMemoryStore(), "empty-step-name")), - Steps(Step{Name: "", Run: func(_ context.Context, in State) (State, error) { - return in, nil - }}), - ) - - err := f.Execute(context.Background(), "") - if err == nil { - t.Fatal("expected an empty step name to fail validation") - } - if got, want := err.Error(), "flow: step 0 has an empty name"; got != want { - t.Fatalf("error = %q, want %q", got, want) - } -} - -// A step with no Run function is reported as a configuration error rather -// than panicking the run. -func TestFlowStepNilRun(t *testing.T) { - f := New("nilstep", - WithCheckpoint(StoreCheckpoint(store.NewMemoryStore(), "nilstep")), - Steps(Step{Name: "missing"}), - ) - err := f.Execute(context.Background(), "") - if err == nil { - t.Fatal("expected an error for a step with no Run function") - } -} - -func TestStoreCheckpointListReturnsRunsInStartedOrder(t *testing.T) { - cp := StoreCheckpoint(store.NewMemoryStore(), "ordered") - ctx := context.Background() - base := time.Date(2026, 6, 24, 12, 0, 0, 0, time.UTC) - runs := []Run{ - {ID: "run-c", Flow: "ordered", Status: "failed", Started: base.Add(2 * time.Minute)}, - {ID: "run-a", Flow: "ordered", Status: "failed", Started: base}, - {ID: "run-b", Flow: "ordered", Status: "failed", Started: base.Add(time.Minute)}, - } - for _, run := range runs { - if err := cp.Save(ctx, run); err != nil { - t.Fatalf("Save(%s): %v", run.ID, err) - } - } - - got, err := cp.List(ctx) - if err != nil { - t.Fatalf("List: %v", err) - } - if len(got) != 3 { - t.Fatalf("List returned %d runs, want 3", len(got)) - } - want := []string{"run-a", "run-b", "run-c"} - for i, id := range want { - if got[i].ID != id { - t.Fatalf("run %d = %q, want %q (all runs: %+v)", i, got[i].ID, id, got) - } - } -} - -func TestStoreCheckpointHonorsCanceledContext(t *testing.T) { - cp := StoreCheckpoint(store.NewMemoryStore(), "canceled") - ctx, cancel := context.WithCancel(context.Background()) - cancel() - - run := Run{ID: "canceled", Started: time.Now()} - - if err := cp.Save(ctx, run); !errors.Is(err, context.Canceled) { - t.Fatalf("Save error = %v, want context.Canceled", err) - } - if _, ok, err := cp.Load(ctx, run.ID); !errors.Is(err, context.Canceled) || ok { - t.Fatalf("Load ok, error = %v, %v; want false, context.Canceled", ok, err) - } - if err := cp.Delete(ctx, run.ID); !errors.Is(err, context.Canceled) { - t.Fatalf("Delete error = %v, want context.Canceled", err) - } - if _, err := cp.List(ctx); !errors.Is(err, context.Canceled) { - t.Fatalf("List error = %v, want context.Canceled", err) - } -} - -type failingCheckpoint struct { - err error -} - -func (c failingCheckpoint) Save(context.Context, Run) error { return c.err } -func (c failingCheckpoint) Load(context.Context, string) (Run, bool, error) { - return Run{}, false, c.err -} -func (c failingCheckpoint) Delete(context.Context, string) error { return c.err } -func (c failingCheckpoint) List(context.Context) ([]Run, error) { return nil, c.err } - -func TestFlowCheckpointSaveFailureStopsRun(t *testing.T) { - checkpointErr := errors.New("checkpoint unavailable") - var ran bool - f := New("checkpoint-fails", - WithCheckpoint(failingCheckpoint{err: checkpointErr}), - Steps(Step{Name: "work", Run: func(_ context.Context, in State) (State, error) { - ran = true - return in, nil - }}), - ) - - err := f.Execute(context.Background(), "start") - if !errors.Is(err, checkpointErr) { - t.Fatalf("Execute error = %v, want checkpoint error", err) - } - if ran { - t.Fatal("step ran even though the in-progress checkpoint failed") - } -} - -func TestFlowDeleteOnSuccessFailureIsReturned(t *testing.T) { - checkpointErr := errors.New("delete unavailable") - cp := &deleteFailCheckpoint{Checkpoint: StoreCheckpoint(store.NewMemoryStore(), "delete-fails"), err: checkpointErr} - f := New("delete-fails", - WithCheckpoint(cp), - DeleteOnSuccess(), - Steps(appendStep("work")), - ) - - err := f.Execute(context.Background(), "") - if !errors.Is(err, checkpointErr) { - t.Fatalf("Execute error = %v, want delete error", err) - } -} - -type deleteFailCheckpoint struct { - Checkpoint - err error -} - -func (c *deleteFailCheckpoint) Delete(context.Context, string) error { return c.err } - -func TestStateSetScan(t *testing.T) { - var s State - type payload struct { - Email string `json:"email"` - } - if err := s.Set(payload{Email: "a@b.com"}); err != nil { - t.Fatalf("Set: %v", err) - } - var got payload - if err := s.Scan(&got); err != nil { - t.Fatalf("Scan: %v", err) - } - if got.Email != "a@b.com" { - t.Errorf("round-trip failed: %+v", got) - } -} - -func TestFlowFailureRecordsErrorKind(t *testing.T) { - cp := StoreCheckpoint(store.NewMemoryStore(), "failure-kind") - f := New("failure-kind", - WithCheckpoint(cp), - Steps(Step{Name: "limited", Run: func(_ context.Context, in State) (State, error) { - return in, errors.New("rate limit exceeded") - }}), - ) - - err := f.Execute(context.Background(), "payload") - if err == nil { - t.Fatal("Execute error = nil, want failure") - } - - runs, listErr := cp.List(context.Background()) - if listErr != nil { - t.Fatalf("List: %v", listErr) - } - if len(runs) != 1 { - t.Fatalf("runs = %d, want 1", len(runs)) - } - if got := runs[0].Steps[0].ErrorKind; got != string(model.ErrorKindRateLimited) { - t.Fatalf("step error kind = %q, want %q", got, model.ErrorKindRateLimited) - } - - results := f.Results() - if len(results) != 1 { - t.Fatalf("results = %d, want 1", len(results)) - } - if got := results[0].ErrorKind; got != string(model.ErrorKindRateLimited) { - t.Fatalf("result error kind = %q, want %q", got, model.ErrorKindRateLimited) - } -} diff --git a/flow/verification_test.go b/flow/verification_test.go deleted file mode 100644 index fb3c0f9808..0000000000 --- a/flow/verification_test.go +++ /dev/null @@ -1,100 +0,0 @@ -package flow - -import ( - "context" - "errors" - "testing" - - "go-micro.dev/v6/model" - "go-micro.dev/v6/store" -) - -func TestFlowStepVerificationRetriesWithFeedback(t *testing.T) { - var attempts int - var feedback []string - step := Step{ - Name: "draft", - Retry: 1, - Run: func(ctx context.Context, in State) (State, error) { - attempts++ - info, ok := model.RunInfoFrom(ctx) - if !ok { - t.Fatal("RunInfo missing from verified step") - } - feedback = append(feedback, info.VerificationFeedback) - if info.VerificationFeedback == "add evidence" { - in.Data = []byte("answer with evidence") - } else { - in.Data = []byte("answer") - } - return in, nil - }, - Verify: func(ctx context.Context, out State) (Verification, error) { - if out.String() == "answer with evidence" { - return Verification{Passed: true, Feedback: "meets rubric"}, nil - } - return Verification{Feedback: "add evidence"}, nil - }, - } - - cp := StoreCheckpoint(store.NewMemoryStore(), "verified") - f := New("verified", WithCheckpoint(cp), Steps(step)) - if err := f.Execute(context.Background(), "question"); err != nil { - t.Fatal(err) - } - if attempts != 2 { - t.Fatalf("attempts = %d, want 2", attempts) - } - if len(feedback) != 2 || feedback[0] != "" || feedback[1] != "add evidence" { - t.Fatalf("feedback = %#v, want empty then verifier feedback", feedback) - } - runs, err := cp.List(context.Background()) - if err != nil { - t.Fatal(err) - } - if len(runs) != 1 { - t.Fatalf("runs = %d, want 1", len(runs)) - } - stepRecord := runs[0].Steps[0] - if stepRecord.Status != "done" || stepRecord.Attempts != 2 || stepRecord.VerificationStatus != "passed" || stepRecord.VerificationNote != "meets rubric" { - t.Fatalf("step record = %#v", stepRecord) - } -} - -func TestFlowStepVerificationFailureIsCheckpointed(t *testing.T) { - step := Step{ - Name: "grade", - Run: func(ctx context.Context, in State) (State, error) { - in.Data = []byte("bad") - return in, nil - }, - Verify: func(ctx context.Context, out State) (Verification, error) { - return Verification{Feedback: "missing citation"}, nil - }, - } - - cp := StoreCheckpoint(store.NewMemoryStore(), "verified-fail") - f := New("verified-fail", WithCheckpoint(cp), Steps(step)) - err := f.Execute(context.Background(), "question") - if err == nil { - t.Fatal("Execute succeeded, want verification failure") - } - var verr *VerificationError - if !errors.As(err, &verr) { - t.Fatalf("error = %T %v, want VerificationError", err, err) - } - if verr.Feedback != "missing citation" { - t.Fatalf("feedback = %q, want missing citation", verr.Feedback) - } - runs, listErr := cp.List(context.Background()) - if listErr != nil { - t.Fatal(listErr) - } - if len(runs) != 1 { - t.Fatalf("runs = %d, want 1", len(runs)) - } - stepRecord := runs[0].Steps[0] - if runs[0].Status != "failed" || stepRecord.VerificationStatus != "failed" || stepRecord.VerificationNote != "missing citation" { - t.Fatalf("run = %#v step = %#v", runs[0], stepRecord) - } -} diff --git a/flow/verify.go b/flow/verify.go deleted file mode 100644 index cecda39229..0000000000 --- a/flow/verify.go +++ /dev/null @@ -1,191 +0,0 @@ -package flow - -import ( - "context" - "encoding/json" - "fmt" - "strings" - "time" - - "go-micro.dev/v6/model" -) - -// Grader checks a step output against a rubric. It returns pass=true when the -// output is acceptable; otherwise feedback should explain what the next attempt -// should fix. -type Grader func(ctx context.Context, out State) (pass bool, feedback string, err error) - -// VerifyOptions configure Verify. -type VerifyOptions struct { - // MaxAttempts bounds how many times the body can run. Default 2. - MaxAttempts int - // Backoff waits between failed grades. Zero means retry immediately. - Backoff time.Duration - // FeedbackField is the JSON field used to thread grader feedback into the - // next attempt's input. Default "feedback". - FeedbackField string -} - -// VerifyOption configures Verify. -type VerifyOption func(*VerifyOptions) - -// VerifyMaxAttempts sets the total attempt budget for Verify. Values <= 0 use -// the default of 2. -func VerifyMaxAttempts(n int) VerifyOption { return func(o *VerifyOptions) { o.MaxAttempts = n } } - -// VerifyBackoff sets the delay between failed verification attempts. -func VerifyBackoff(d time.Duration) VerifyOption { return func(o *VerifyOptions) { o.Backoff = d } } - -// VerifyFeedbackField sets the JSON field used to pass grader feedback to the -// next body attempt. Empty values use "feedback". -func VerifyFeedbackField(field string) VerifyOption { - return func(o *VerifyOptions) { o.FeedbackField = field } -} - -// Verify runs body, grades its output, and retries with grader feedback threaded -// into the next input until the grader passes or MaxAttempts is exhausted. It is -// a StepFunc, so it composes directly as Step.Run with Loop, LLM, Call, Agent, or -// any code-defined step. -// -// On a failed grade, Verify adds the feedback to the next attempt's input as a -// JSON field named "feedback" (or VerifyFeedbackField). When all attempts fail, -// it returns the last output without error, annotated with verification fields so -// the run can keep the bounded failure outcome in its state: -// "verification_passed": false, "verification_feedback", and -// "verification_attempts". -func Verify(body StepFunc, grader Grader, opts ...VerifyOption) StepFunc { - o := VerifyOptions{MaxAttempts: 2, FeedbackField: "feedback"} - for _, op := range opts { - op(&o) - } - if o.MaxAttempts <= 0 { - o.MaxAttempts = 2 - } - if o.FeedbackField == "" { - o.FeedbackField = "feedback" - } - return func(ctx context.Context, in State) (State, error) { - if body == nil { - return in, fmt.Errorf("flow: Verify requires a body step") - } - if grader == nil { - return in, fmt.Errorf("flow: Verify requires a grader") - } - cur := in - last := in - feedback := "" - for attempt := 1; attempt <= o.MaxAttempts; attempt++ { - if err := ctx.Err(); err != nil { - return last, err - } - if feedback != "" { - var err error - cur, err = stateWithField(cur, o.FeedbackField, feedback) - if err != nil { - return last, err - } - } - out, err := body(ctx, cur) - if err != nil { - return last, fmt.Errorf("verify attempt %d: %w", attempt, err) - } - last = out - pass, fb, err := grader(ctx, out) - if err != nil { - return last, fmt.Errorf("verify grade attempt %d: %w", attempt, err) - } - if pass { - return stateWithVerification(out, true, fb, attempt) - } - feedback = fb - cur = in - if attempt < o.MaxAttempts && o.Backoff > 0 { - select { - case <-time.After(o.Backoff): - case <-ctx.Done(): - return last, ctx.Err() - } - } - } - return stateWithVerification(last, false, feedback, o.MaxAttempts) - } -} - -// LLMGrader returns a grader that asks the flow model to judge the latest output -// against rubric. The model should answer with pass/fail plus short feedback. -// It reuses the flow's configured model, so it must run inside a flow. -func LLMGrader(rubric string) Grader { - return func(ctx context.Context, out State) (bool, string, error) { - d := depsFrom(ctx) - if d == nil || d.model == nil { - return false, "", fmt.Errorf("flow: LLMGrader requires a flow model (set Provider/APIKey)") - } - prompt := fmt.Sprintf("Grade the latest result against this rubric:\n%s\n\nLatest result:\n%s\n\nAnswer with PASS or FAIL on the first line, followed by one short feedback sentence.", rubric, out.String()) - resp, err := d.model.Generate(ctx, &model.Request{Prompt: prompt}) - if err != nil { - return false, "", err - } - reply := resp.Answer - if reply == "" { - reply = resp.Reply - } - return parseGrade(reply) - } -} - -func parseGrade(reply string) (bool, string, error) { - text := strings.TrimSpace(reply) - if text == "" { - return false, "", fmt.Errorf("flow: LLMGrader returned an empty grade") - } - lines := strings.SplitN(text, "\n", 2) - first := strings.ToLower(strings.TrimSpace(lines[0])) - feedback := "" - if len(lines) > 1 { - feedback = strings.TrimSpace(lines[1]) - } - pass := strings.HasPrefix(first, "pass") || isAffirmative(first) - if !pass && feedback == "" { - feedback = text - } - return pass, feedback, nil -} - -func stateWithField(s State, field, value string) (State, error) { - var obj map[string]any - if len(s.Data) > 0 && json.Unmarshal(s.Data, &obj) == nil && obj != nil { - obj[field] = value - return stateWithObject(s, obj) - } - obj = map[string]any{field: value} - if len(s.Data) > 0 { - obj["data"] = s.String() - } - return stateWithObject(s, obj) -} - -func stateWithVerification(s State, passed bool, feedback string, attempts int) (State, error) { - var obj map[string]any - if len(s.Data) > 0 && json.Unmarshal(s.Data, &obj) == nil && obj != nil { - obj["verification_passed"] = passed - obj["verification_feedback"] = feedback - obj["verification_attempts"] = attempts - return stateWithObject(s, obj) - } - obj = map[string]any{ - "data": s.String(), - "verification_passed": passed, - "verification_feedback": feedback, - "verification_attempts": attempts, - } - return stateWithObject(s, obj) -} - -func stateWithObject(s State, obj map[string]any) (State, error) { - b, err := json.Marshal(obj) - if err != nil { - return s, err - } - s.Data = b - return s, nil -} diff --git a/flow/verify_test.go b/flow/verify_test.go deleted file mode 100644 index 891f5ae8ef..0000000000 --- a/flow/verify_test.go +++ /dev/null @@ -1,96 +0,0 @@ -package flow - -import ( - "context" - "strings" - "testing" -) - -func TestVerifyPassesFirstTry(t *testing.T) { - attempts := 0 - step := Verify(func(_ context.Context, in State) (State, error) { - attempts++ - in.Data = []byte(`{"answer":"ok"}`) - return in, nil - }, func(context.Context, State) (bool, string, error) { - return true, "looks good", nil - }, VerifyMaxAttempts(3)) - - out, err := step(context.Background(), State{}) - if err != nil { - t.Fatalf("Verify returned error: %v", err) - } - if attempts != 1 { - t.Fatalf("body attempts = %d, want 1", attempts) - } - var got map[string]any - if err := out.Scan(&got); err != nil { - t.Fatalf("scan output: %v", err) - } - if got["verification_passed"] != true { - t.Fatalf("verification_passed = %v, want true", got["verification_passed"]) - } -} - -func TestVerifyRetriesWithFeedback(t *testing.T) { - attempts := 0 - var secondInput map[string]string - step := Verify(func(_ context.Context, in State) (State, error) { - attempts++ - if attempts == 2 { - if err := in.Scan(&secondInput); err != nil { - t.Fatalf("scan second input: %v", err) - } - } - in.Data = []byte(`{"answer":"draft"}`) - return in, nil - }, func(_ context.Context, _ State) (bool, string, error) { - return attempts >= 2, "include citations", nil - }, VerifyMaxAttempts(3)) - - out, err := step(context.Background(), State{Data: []byte(`{"topic":"agents"}`)}) - if err != nil { - t.Fatalf("Verify returned error: %v", err) - } - if attempts != 2 { - t.Fatalf("body attempts = %d, want 2", attempts) - } - if secondInput["feedback"] != "include citations" { - t.Fatalf("feedback = %q, want include citations", secondInput["feedback"]) - } - if !strings.Contains(out.String(), `"verification_passed":true`) { - t.Fatalf("output missing successful verification annotation: %s", out.String()) - } -} - -func TestVerifyExhaustsAttemptsReturnsLastOutput(t *testing.T) { - attempts := 0 - step := Verify(func(_ context.Context, in State) (State, error) { - attempts++ - in.Data = []byte(`{"answer":"still wrong"}`) - return in, nil - }, func(context.Context, State) (bool, string, error) { - return false, "try again", nil - }, VerifyMaxAttempts(2)) - - out, err := step(context.Background(), State{}) - if err != nil { - t.Fatalf("Verify returned error: %v", err) - } - if attempts != 2 { - t.Fatalf("body attempts = %d, want 2", attempts) - } - var got map[string]any - if err := out.Scan(&got); err != nil { - t.Fatalf("scan output: %v", err) - } - if got["verification_passed"] != false { - t.Fatalf("verification_passed = %v, want false", got["verification_passed"]) - } - if got["verification_feedback"] != "try again" { - t.Fatalf("verification_feedback = %v, want try again", got["verification_feedback"]) - } - if got["verification_attempts"] != float64(2) { - t.Fatalf("verification_attempts = %v, want 2", got["verification_attempts"]) - } -} diff --git a/internal/docs/AGENT_CONFORMANCE.md b/internal/docs/AGENT_CONFORMANCE.md index 31bbf2809e..02c669c0fd 100644 --- a/internal/docs/AGENT_CONFORMANCE.md +++ b/internal/docs/AGENT_CONFORMANCE.md @@ -48,7 +48,7 @@ contract. For the exact scheduled command, run: ```sh go run ./internal/harness/provider-conformance \ -providers anthropic,openai,gemini,groq,minimax,mistral,together,atlascloud \ - -harnesses agent,universe,agent-flow,plan-delegate,a2a-stream-fallback \ + -harnesses agent,a2a-stream-fallback \ -summary-json provider-conformance-summary.json \ -summary-markdown provider-conformance-summary.md \ -capabilities-markdown provider-capabilities.md diff --git a/internal/docs/AGENT_DESIGN.md b/internal/docs/AGENT_DESIGN.md index 74269a208e..3ba9f5715f 100644 --- a/internal/docs/AGENT_DESIGN.md +++ b/internal/docs/AGENT_DESIGN.md @@ -115,7 +115,7 @@ An agent only sees the endpoints of its assigned services (plus excludes its own Agents persist conversation history in the store. Memory survives restarts. Each agent's state is confined to its own store table (database `agent`, table `{name}`) via `store.Scope`, so agents don't share a global table -with each other, with services, or with flows. +with each other or with services. ``` database "agent", table "{name}": @@ -124,7 +124,7 @@ database "agent", table "{name}": ## Durable Ask / StreamAsk runs -Agents can opt into the same checkpoint backend used by flows with +Agents can opt into the agent checkpoint backend with `micro.AgentWithCheckpoint(...)`. When enabled, each `Ask` or `StreamAsk` run is persisted with its input, terminal status, response, and tool-call records. If the process or transport drops after a tool has completed but before the model @@ -262,15 +262,11 @@ micro chat # routes to agents automatically micro call task-mgr Agent.Chat '{"message": "..."}' # direct RPC ``` -The split is consistent across services, agents, and flows: **`list`** +The split is consistent across services and agents: **`list`** shows what's *running* (from the registry, filtered by type), while **`history`/`runs`** show *durable* state from the scoped store — available whether or not the component is currently running. -```bash -micro flow list # list running flows (registry, type=flow) -micro flow runs checkout # durable run history for a flow (scoped store) -``` ## Generation diff --git a/internal/docs/DURABLE_EXECUTION_DESIGN.md b/internal/docs/DURABLE_EXECUTION_DESIGN.md deleted file mode 100644 index ae76228b8c..0000000000 --- a/internal/docs/DURABLE_EXECUTION_DESIGN.md +++ /dev/null @@ -1,320 +0,0 @@ -# Durable Execution: Flow Steps & Checkpoint - -**Status:** Historical design proposal, partly implemented. The shipped contract is -[Durability and Recovery](../website/content/en/docs/guides/durability.md). - -Ordered flow steps, store-backed checkpoints, flow waiting/resume-with-input, -opt-in agent checkpoints, and run tracing now exist. The proposal below is kept -for design history: its pseudocode, API sketches, rollout sequence, and suggested -idempotency behavior are not a description of current guarantees. In particular, -`Step.Retry == 0` inherits the flow default; checkpoints do not provide -exactly-once side effects or multi-replica leases. Consult the current guide and -linked implementation before using a proposed API or planning follow-up work. - -This note sketches two related changes: - -1. Give **flow** a real step model — a flow is a *task* made of *ordered - steps* — so it becomes the deterministic-workflow engine it has always - claimed to be (today it runs a single LLM step per event). -2. Introduce **`Checkpoint`**, a pluggable durability primitive that - persists run progress and resumes after a crash. Store-backed by - default; both flow and agent use it. - -The two are designed together because a step boundary is the natural -place to checkpoint. - ---- - -## Motivation - -A flow or agent run is long, expensive, and has side effects partway -through (it sent an email at step 2, charged via x402 at step 4). Today -all in-flight state lives in process memory: a crash loses the run, and -re-running from the top repeats the side effects. - -Durable execution means the run survives a crash and **continues from -where it stopped**, without re-doing completed steps. - -This is squarely a distributed-systems concern — checkpoint state, replay -on restart, pluggable backend — i.e. go-micro's kind of problem, built on -primitives it already has (`store`, `WrapTool`, `call.ID`). - ---- - -## What flow is today (for contrast) - -`flow` is a concrete `*Flow` struct. Per broker event, `Execute` runs -**one** augmented-LLM turn (a single `Generate` with services as tools) -or dispatches the event to an agent, records one `Result`, and returns. -There is no notion of a task with ordered steps, no carried state, no -checkpoint. The step model below generalizes today's behavior: a flow -with one step == current flow. - ---- - -## Core concepts - -### State - -What carries across steps. **A struct, not a map** — a typed `Data` -plus a `Stage` marker so you can always tell where a run is. - -```go -type State struct { - Stage string // name of the step the run is at — where it is - Data []byte // carried data, serialized; use Set / Scan -} - -// Set replaces the data with the JSON encoding of v. -func (s *State) Set(v any) error -// Scan decodes the data into v (a pointer to the caller's struct). -func (s State) Scan(v any) error -``` - -The developer defines their own data struct and threads it through -with `Set`/`Scan` — type-safe at the edges, serializable in the middle -(which is what makes checkpointing possible). `Stage` is the readable -"where am I"; the engine also uses it as the resume point. - -The trigger event seeds the first `State`. - -### Step - -The unit of a flow. **One kind** — a struct with a name, the action to -run, and an optional retry override. No per-kind constructors. - -```go -type StepFunc func(ctx context.Context, in State) (State, error) - -type Step struct { - Name string - Run StepFunc - Retry int // optional per-step override of the flow's retry (0 = use flow default) -} -``` - -Common actions are **helpers that return a `StepFunc`**, dropped into -`Step.Run` — so there is still one `Step` type, and the actions compose: - -```go -flow.Call(service, endpoint) StepFunc // one RPC to a service -flow.LLM(opts...) StepFunc // one augmented-LLM turn -flow.Agent(name) StepFunc // dispatch to a registered agent -// …or write your own StepFunc. -``` - -Steps are **authored by the developer** and run in order. That ordering -is the defining difference from an agent, where the *model* chooses the -steps. - -### Run - -The persisted record of one execution — what `Checkpoint` saves and -loads. Retained for success and failure (see retention below). - -```go -type Run struct { - ID string // durable run id (idempotency root) - Flow string // flow name - State State // carried data + Stage (where it is) - Steps []StepRecord // per-step status + outcome (history/audit) - Status string // running | done | failed - Started time.Time - Updated time.Time -} - -type StepRecord struct { - Name string - Status string // pending | in_progress | done | failed - Attempts int // how many tries this step took - Result string // short serialized outcome / summary - Error string -} -``` - -The resume point is `State.Stage` — there is no separate numeric cursor, -so there is one source of truth for "where it is." - -### Checkpoint - -The pluggable durability primitive. Persists and restores a `Run`. - -```go -type Checkpoint interface { - Save(ctx context.Context, run Run) error - Load(ctx context.Context, runID string) (Run, bool, error) - Delete(ctx context.Context, runID string) error -} -``` - -The built-in implementation is **store-backed** and on by default, keyed -in the store: - -``` -database "flow", table "{name}", key {runID} → JSON(Run) -``` - -Runs are confined to their own **store table** — database `flow`, one -table per flow name — via `store.Scope`, not a single shared table keyed -by prefix. `StoreCheckpoint(s, scope)` takes that scope; the flow passes -its name by default. `store.Scope` injects the database/table per -operation, so it doesn't mutate or race on the shared store (the way -`Init(Table(...))` would). Because it rides on `store.Store`, the storage -is also pluggable (Postgres, NATS KV, file) with no extra interface. - -**Retention:** completed runs (success *and* failure) are **kept** by -default, so you have a durable history of what ran. `Delete` is only -called when the flow opts in with `flow.DeleteOnSuccess()` (failures are -always kept). - ---- - -## The run loop - -``` -run := load(runID) or new Run{State: {Stage: steps[0].Name, ...}} - -start := index of step named run.State.Stage -for i := start; i < len(steps); i++ { - step := steps[i] - run.Steps[i].Status = "in_progress"; checkpoint.Save(run) - - out, err := runWithRetry(ctx, step, run.State, retriesFor(step)) - run.Steps[i].Attempts = attemptsTaken - if err != nil { - run.Steps[i].Status = "failed"; run.Steps[i].Error = err - run.Status = "failed"; checkpoint.Save(run) // kept for audit - return err // resumable: retry resumes here - } - - run.State = out - run.Steps[i].Status = "done" - if i+1 < len(steps) { - run.State.Stage = steps[i+1].Name // <-- checkpoint boundary - } else { - run.State.Stage = "" // finished - } - checkpoint.Save(run) -} - -run.Status = "done"; checkpoint.Save(run) -// Delete only if flow.DeleteOnSuccess() was set. -``` - -On restart, `Load` returns the `Run`; the loop resumes at the step named -`run.State.Stage`, so completed steps are skipped — their effects already -happened and their output is already in `run.State.Data`. - -### Retry - -Flow-level by default, per-step override when needed (e.g. a tool that -times out): - -```go -flow.Retry(2) // flow-level default for every step -flow.Step{Name: "charge", Run: …, Retry: 0} // override: never retry this one -``` - -`retriesFor(step)` uses `step.Retry` if set, else the flow default. - -### Idempotency (the honest part) - -True exactly-once is impossible if a crash lands *inside* a step. What we -provide is at-least-once + a stable **idempotency key** per step: -`runID + stepName`. That key is passed to the tool as `call.ID`, so a -replayed call is recognized downstream and de-duplicated. Side-effecting -steps must cooperate (honor the key). The framework makes this -consistent; it cannot make it free. - -Retry uses the same key, so a retried step is de-duplicated the same way. -This is where the existing `WrapTool` seam pays off: a durable wrapper -checks the checkpoint — if this `call.ID` already has a recorded result, -return it without re-calling. - ---- - -## Agent reuse - -The agent loop is the **self-directed** analogue and uses the same -`Checkpoint`. The difference is who authors the steps: - -| | Steps authored by | Steps known | Durability | -|---|---|---|---| -| **flow** | developer | up front (ordered list) | checkpoint between steps | -| **agent** | the model | discovered at runtime | checkpoint each LLM turn + its tool calls | - -For the agent, `Run.Steps` grows as the model acts, instead of being -predefined. One requirement: the agent must own its loop (today the -provider drives it), so it can `Save` between turns. That is the one -structural change on the agent side. - ---- - -## Pluggability — two levels - -1. **Storage (free today).** Built-in `Checkpoint` over `store.Store`; - swap the store backend. Covers "checkpoint to my DB instead." -2. **Engine (future).** Because steps are now explicit and named, a flow - can be mapped onto an external durable-execution engine — each `Step` - becomes a Temporal activity / Restate handler — by providing an - alternative runner. Most users only need level 1; level 2 exists so - teams already running Temporal aren't forced off it. - -The explicit step model is what makes level 2 possible later; we don't -build it now. - ---- - -## Proposed API - -```go -type Onboarding struct { - Email string `json:"email"` - WorkspaceID string `json:"workspace_id"` -} - -f := flow.New("onboard-user", - flow.Trigger("events.user.created"), - flow.Retry(2), // flow-level retry default - flow.Steps( - flow.Step{Name: "plan", Run: flow.LLM(flow.Prompt("Plan onboarding for {{.Email}}"))}, - flow.Step{Name: "workspace", Run: flow.Call("workspace", "Workspace.Create")}, - flow.Step{Name: "welcome", Run: flow.Agent("comms")}, - ), - // Durable by default (store-backed); runs are retained for audit. - flow.WithCheckpoint(flow.StoreCheckpoint(service.Options().Store, "onboard-user")), -) -f.Register(reg, broker, client) -``` - -A single-step flow keeps today's behavior, so this is additive. - ---- - -## Decisions (resolved) - -- **State is a struct, not a map** — typed `Data` + `Stage`. The - developer defines the data struct; `Stage` doubles as the resume - point, so there is one source of truth for position. -- **One `Step` kind** — a struct with `Name`, `Run`, and an optional - `Retry`. Common actions are `StepFunc` helpers (`Call`, `LLM`, - `Agent`), not separate step constructors. -- **Runs are retained** for success and failure by default; - `flow.DeleteOnSuccess()` opts into cleanup (failures always kept). -- **Retry is a flow-level option** (`flow.Retry(n)`), with a per-step - `Retry` field as a fine-grained override. - ---- - -## Scope & phasing - -1. **Step model in flow** (no durability yet): `State`, `Step`, ordered - `Steps`, the run loop, retry. Single-step flows unchanged. -2. **`Checkpoint` + store-backed default**: persist/resume flow runs, - retention. -3. **Agent durability**: move the agent loop in-package, reuse - `Checkpoint`. Opt-in (`AgentDurable()`), default off — overkill for - short interactive chats, essential for long unattended runs. -4. **Engine-level pluggability** (Temporal/Restate): only if demand. - -Each phase is independently useful and shippable. diff --git a/internal/docs/THESIS.md b/internal/docs/THESIS.md index c34eb17357..fe04029a76 100644 --- a/internal/docs/THESIS.md +++ b/internal/docs/THESIS.md @@ -1,130 +1,13 @@ -# Go Micro — Thesis & North Star +# Go Micro direction -This is the North Star for the project and for the autonomous improvement loop -(see `CONTINUOUS_IMPROVEMENT.md`). Every change should move toward it; work that -doesn't isn't an improvement, however clean. +Go Micro is a framework for services and agents. Services expose typed operations +through RPC and discovery. Agents use these operations as tools and can delegate +to other agents. The CLI and gateways provide access to the same components. -## Mission — the problem we solve +Keep the framework useful independently of any product. Studio provides a +developer workspace; Mu provides an application runtime. Neither should impose +product-specific behaviour on the framework. -Go Micro started in 2015 because building distributed systems in Go was too hard: -too much boilerplate, too many decisions before a single endpoint runs. The -mission was to **make building distributed systems simple** — sane defaults, -pluggable, out of the developer's way. - -Agents are distributed systems too. The moment an agent discovers services, calls -them, holds state, and recovers from failure, it *is* a distributed system — the -exact problem Go Micro already solved for services. So the mission hasn't -changed, only extended: - -> **Make building agentic, distributed software in Go simple — make building an -> agent as easy as building a service, on one runtime, because an agent is a -> distributed system.** - -That is the problem we solve, and it is the question every priority is judged -against: *does this make the services → agents → workflows lifecycle simpler, more -cohesive, and more operable — or is it scope that doesn't serve that?* It is -evolution, not a pivot: the decade of services work is the foundation, and the -agent layer is that foundation leveraged for the AI era. - -## The canon - -The vision isn't only in this file. The years of focus and context live in the -**corpus** — the [blog](../website/blog/) (the actual thinking, e.g. `/blog/14` -"Going All In on AI" and `/blog/27` "Back from the Dead"), the -[`README`](../../README.md), and the [website](../website/). Those are the canon; -this North Star is their **distillation** and must stay faithful to them. When the -two diverge, that's a signal — either the work has drifted from the mission, or the -North Star has drifted from the lived story and needs re-grounding in the corpus. -The architect re-derives alignment from the canon, not from this file alone. - -## Thesis - -Go Micro is an **agent harness and service framework** — one runtime that, holistically, -encapsulates the **lifecycle of services, agents, and workflows**. Not three -products stitched together: one set of primitives, because an agent is a -distributed system and building one is building a service. - -## The progression: services → agents → workflows - -Value is unlocked in order, and each layer needs the one beneath it: - -1. **Services** — typed, discoverable, callable capabilities. The substrate; every - endpoint is automatically an AI-callable tool. -2. **Agents** — a model with memory and tools that *uses* those services, plans, - delegates, and is bounded by guardrails. Intelligence on top of capability. -3. **Workflows** — the part that **pieces it all together**: composing agents and - services over time, deterministically where the path is known and dynamically - where it isn't, on schedules and in loops. The workloads come *after* the - agents, because the value is in stitching it into systems that do real work. - -A harness that stops at "a model in a loop" is incomplete. The point is the whole -lifecycle — capability, intelligence, and orchestration as one runtime. - -## Where we fit — complementary, not competing - -"Agent = Model + Harness" ([LangChain](https://www.langchain.com/blog/the-anatomy-of-an-agent-harness)) -is the right frame, but *harness* has two layers, and we own the second: - -- **The intra-agent harness** — the runtime around a *single model*: system prompt, - tools, context compaction, sandbox, self-verification, and the continuation - ("Ralph") loop. LangChain / LangGraph, deepagents, and Claude Code do this well. - **We do not compete here.** -- **The operational harness** — the distributed substrate agents *operate inside*: - services as typed tools, discovery and RPC, durable and resumable runs, - observability, scheduling, and the protocols agents use to reach each other. The - place a single agent becomes part of a system, and many agents, services, and - workflows compose. **This is Go Micro's focus.** - -They stack. An intra-agent harness produces an agent; Go Micro is where that agent -runs as a first-class service and gets composed into workflows with other services -and agents. They plug together through open protocols — a LangGraph or deepagents -agent is reachable over A2A and consumes Go Micro tools over MCP, and the reverse. -We make those agents better neighbours, not obsolete. - -So the focus is deliberately narrow: **the operational harness for Go, and the -services → agents → workflows lifecycle** — not a model-orchestration framework, not -a graph DSL, not a prompt layer. Lead with interop and the distributed substrate; -treat LangChain-class tools as complements to build alongside, never as targets to -replace. - -## Why now - -The frontier is moving from chat to **scheduled, looping, work-performing agents**: -Anthropic itself is building toward agents that do work on a cadence (Claude for -Work, schedulers), and running coding agents *continuously in loops* is becoming -standard practice among the people who build them. That shift is exactly the -"workflows after agents" layer — and the harness is what makes it safe, durable, -observable, and composable instead of a fragile script. - -The bet: whoever gives Go a holistic harness for the **whole lifecycle** — not just -an agent SDK, not just a service framework — owns where agentic software gets built. - -## What every improvement should serve - -Judge each loop increment against the North Star: - -1. **Make the harness real** — operate the loop in production: durability, - observability, resilience, streaming, human-in-the-loop. -2. **Tighten the lifecycle** — services ↔ agents ↔ workflows as one runtime, not - three silos. -3. **Advance orchestration** — durable, resumable, scheduled, looping workflows - that compose agents and services over time. -4. **Sharpen DX** — the 0→1 and 0→hero paths stay effortless. -5. **Strengthen interop** — MCP (tools), A2A (agents), x402 (paid tools). -6. **Harden trust** — cross-provider conformance, failure semantics, tests. - -Prefer changes that advance these; avoid scope that doesn't. Brand/positioning -copy and breaking public-API changes stay with the human. - -## The loop is the proof - -Go Micro is built by an autonomous agentic loop — Claude Code and Codex -continuously improving the repo against this North Star. That isn't a gimmick; it's -the thesis applied to itself: an agent harness, built by agents running in a loop. -If the harness is good enough to build itself, it's good enough to build your -agentic software. - -## What this is not - -The framework is the product — no hosted platform, no enterprise tier, no VC, no -graph DSL. Sustained by sponsorship from those who run it. See `ROADMAP.md`. +The standalone flow abstraction has been removed. Focus on simple service and +agent APIs, dependable tool execution, cancellation, checkpointing and inspection. +Prove changes with real service-to-agent journeys rather than adding abstractions. diff --git a/internal/harness/agent-flow/main.go b/internal/harness/agent-flow/main.go deleted file mode 100644 index c945e142bb..0000000000 --- a/internal/harness/agent-flow/main.go +++ /dev/null @@ -1,330 +0,0 @@ -// Agent Flow harness — "the event is the prompt". -// -// No human types anything. A user.created event lands on the broker, a -// Flow renders it into a prompt and hands it to a registered agent, and -// the agent reasons and acts through its services — creating a workspace -// and sending a welcome. The whole stack is real (services, registry, -// RPC, broker, the agent loop, store); only the LLM is mocked, so it -// runs without an API key. Swap -provider to run it against a live model. -// -// Run: -// -// go run ./internal/harness/agent-flow -package main - -import ( - "context" - "encoding/json" - "flag" - "fmt" - "os" - "strings" - "sync" - "time" - - "go-micro.dev/v6/agent" - "go-micro.dev/v6/broker" - "go-micro.dev/v6/flow" - "go-micro.dev/v6/internal/harness/harnessutil" - "go-micro.dev/v6/model" - "go-micro.dev/v6/registry" - "go-micro.dev/v6/service" - "go-micro.dev/v6/store" -) - -// --------------------------------------------------------------------------- -// real services -// --------------------------------------------------------------------------- - -type Workspace struct { - ID string `json:"id"` - Owner string `json:"owner"` -} - -type CreateRequest struct { - Owner string `json:"owner" description:"Owner email of the workspace (required)"` -} -type CreateResponse struct { - Workspace *Workspace `json:"workspace"` -} - -type WorkspaceService struct { - mu sync.Mutex - n int - byOwner map[string]*Workspace -} - -// Create provisions a workspace for a new user. -// @example {"owner": "alice@acme.com"} -func (s *WorkspaceService) Create(ctx context.Context, req *CreateRequest, rsp *CreateResponse) error { - s.mu.Lock() - if s.byOwner == nil { - s.byOwner = make(map[string]*Workspace) - } - if ws, ok := s.byOwner[req.Owner]; ok { - s.mu.Unlock() - fmt.Printf(" \033[32m[workspace]\033[0m duplicate suppressed %s for %s\n", ws.ID, req.Owner) - rsp.Workspace = ws - return nil - } - s.n++ - id := fmt.Sprintf("ws-%d", s.n) - ws := &Workspace{ID: id, Owner: req.Owner} - s.byOwner[req.Owner] = ws - s.mu.Unlock() - fmt.Printf(" \033[32m[workspace]\033[0m created %s for %s\n", id, req.Owner) - rsp.Workspace = ws - return nil -} - -func (s *WorkspaceService) count() int { - s.mu.Lock() - defer s.mu.Unlock() - return s.n -} - -type SendRequest struct { - To string `json:"to" description:"Recipient address (required)"` - Message string `json:"message" description:"Message body (required)"` -} -type SendResponse struct { - Sent bool `json:"sent"` -} -type NotifyService struct { - mu sync.Mutex - n int - sent map[string]bool -} - -// Send delivers a notification message to a recipient. -// @example {"to": "alice@acme.com", "message": "Welcome"} -func (s *NotifyService) Send(ctx context.Context, req *SendRequest, rsp *SendResponse) error { - key := strings.ToLower(strings.TrimSpace(req.To)) - s.mu.Lock() - if s.sent == nil { - s.sent = make(map[string]bool) - } - if s.sent[key] { - s.mu.Unlock() - fmt.Printf(" \033[35m[notify]\033[0m duplicate suppressed to=%s message=%q\n", req.To, req.Message) - rsp.Sent = true - return nil - } - s.sent[key] = true - s.n++ - s.mu.Unlock() - fmt.Printf(" \033[35m[notify]\033[0m 📨 to=%s message=%q\n", req.To, req.Message) - rsp.Sent = true - return nil -} - -func (s *NotifyService) count() int { - s.mu.Lock() - defer s.mu.Unlock() - return s.n -} - -// --------------------------------------------------------------------------- -// mock LLM — the only fake. It reasons by the tools it's offered. -// --------------------------------------------------------------------------- - -type mockModel struct{ opts model.Options } - -func newMock(opts ...model.Option) model.Model { - m := &mockModel{} - _ = m.Init(opts...) - return m -} - -func (m *mockModel) Init(opts ...model.Option) error { - for _, o := range opts { - o(&m.opts) - } - return nil -} -func (m *mockModel) Options() model.Options { return m.opts } -func (m *mockModel) String() string { return "mock" } -func (m *mockModel) Stream(ctx context.Context, req *model.Request, _ ...model.GenerateOption) (model.Stream, error) { - return nil, fmt.Errorf("stream not supported by mock") -} - -func findTool(tools []model.Tool, sub string) string { - for _, t := range tools { - if strings.Contains(t.Name, sub) { - return t.Name - } - } - return "" -} - -func (m *mockModel) call(name string, input map[string]any) { - args, _ := json.Marshal(input) - fmt.Printf(" \033[33m[onboarder]\033[0m → %s(%s)\n", name, args) - if m.opts.ToolHandler != nil { - m.opts.ToolHandler(context.Background(), model.ToolCall{Name: name, Input: input}) - } -} - -func (m *mockModel) Generate(ctx context.Context, req *model.Request, _ ...model.GenerateOption) (*model.Response, error) { - owner := "alice@acme.com" - if create := findTool(req.Tools, "Create"); create != "" { - m.call(create, map[string]any{"owner": owner}) - } - if send := findTool(req.Tools, "Send"); send != "" { - m.call(send, map[string]any{"to": owner, "message": "Welcome — your workspace is ready."}) - } - return &model.Response{Answer: "Onboarded " + owner + "."}, nil -} - -// --------------------------------------------------------------------------- -// wiring -// --------------------------------------------------------------------------- - -func providerKey(provider string) string { - if v := os.Getenv("MICRO_AI_API_KEY"); v != "" { - return v - } - env := map[string]string{ - "anthropic": "ANTHROPIC_API_KEY", "openai": "OPENAI_API_KEY", - "gemini": "GEMINI_API_KEY", "groq": "GROQ_API_KEY", "mistral": "MISTRAL_API_KEY", - "together": "TOGETHER_API_KEY", "atlascloud": "ATLASCLOUD_API_KEY", - }[provider] - return os.Getenv(env) -} - -func waitFor(reg registry.Registry, name string) { - deadline := time.Now().Add(5 * time.Second) - for time.Now().Before(deadline) { - if svcs, err := reg.GetService(name); err == nil && len(svcs) > 0 && len(svcs[0].Nodes) > 0 { - return - } - time.Sleep(20 * time.Millisecond) - } -} - -func waitForOnboardingSideEffects(ctx context.Context, wsSvc *WorkspaceService, ntSvc *NotifyService, recoverMissingNotify func(context.Context) error) error { - ticker := time.NewTicker(50 * time.Millisecond) - defer ticker.Stop() - - recovered := false - for { - workspaces, notifications := wsSvc.count(), ntSvc.count() - if workspaces >= 1 && notifications >= 1 { - return nil - } - if workspaces >= 1 && notifications == 0 && !recovered && recoverMissingNotify != nil { - recovered = true - if err := recoverMissingNotify(ctx); err != nil { - return fmt.Errorf("agent-flow created workspace but failed to recover missing onboarding notification: workspaces=%d/1 notifications=%d/1: %w", workspaces, notifications, err) - } - } - - select { - case <-ctx.Done(): - return fmt.Errorf("agent-flow missing required onboarding side effects before timeout: workspaces=%d/1 notifications=%d/1", workspaces, notifications) - case <-ticker.C: - } - } -} - -func main() { - provider := flag.String("provider", "mock", "LLM provider: mock (default), anthropic, openai, ...") - flag.Parse() - - apiKey := "" - if *provider == "mock" { - model.Register("mock", newMock) - } else { - apiKey = providerKey(*provider) - if apiKey == "" { - fmt.Printf("no API key for provider %q — set MICRO_AI_API_KEY or the provider's key env\n", *provider) - return - } - } - - fmt.Printf("\n\033[1mAgent Flow — the event is the prompt (provider: %s)\033[0m\n", *provider) - fmt.Print("No human prompt: a user.created event triggers an agent that onboards the user.\n\n") - - reg := registry.NewMemoryRegistry() - br := broker.NewMemoryBroker() - if err := br.Connect(); err != nil { - fmt.Println("broker connect:", err) - os.Exit(1) - } - cl := harnessutil.Client(*provider, reg) - mem := store.NewMemoryStore() - liveAgentOpts := harnessutil.AgentOptions(*provider) - - wsSvc := new(WorkspaceService) - ws := service.New(service.Name("workspace"), service.Address("127.0.0.1:0"), service.Registry(reg), service.Client(cl)) - ws.Handle(wsSvc) - go ws.Run() - - ntSvc := new(NotifyService) - nt := service.New(service.Name("notify"), service.Address("127.0.0.1:0"), service.Registry(reg), service.Client(cl)) - nt.Handle(ntSvc) - go nt.Run() - - // The onboarder agent, registered so the flow can reach it over RPC. - onboarderOpts := []agent.Option{ - agent.Name("onboarder"), - agent.Address("127.0.0.1:0"), - agent.Services("workspace", "notify"), - agent.Prompt("You onboard new users. Create their workspace and send a welcome message."), - agent.Provider(*provider), - agent.APIKey(apiKey), - agent.WithRegistry(reg), agent.WithClient(cl), agent.WithStore(mem), - } - onboarderOpts = append(onboarderOpts, liveAgentOpts...) - onboarder := agent.New(onboarderOpts...) - go onboarder.Run() - defer onboarder.Stop() - - waitFor(reg, "workspace") - waitFor(reg, "notify") - waitFor(reg, "onboarder") - - // A workflow that turns the event into a prompt for the agent. - f := flow.New("onboard", - flow.Trigger("events.user.created"), - flow.Agent("onboarder"), - flow.Prompt("A new user signed up: {{.Data}}. Get them set up."), - flow.Timeout(harnessutil.LiveTimeout(*provider)), - ) - if err := f.Register(reg, br, cl); err != nil { - fmt.Println("flow register:", err) - os.Exit(1) - } - - fmt.Print("\033[1m> event:\033[0m publishing events.user.created {\"email\":\"alice@acme.com\"}\n\n") - - // The event — no human in the loop. - if err := br.Publish("events.user.created", &broker.Message{ - Body: []byte(`{"email":"alice@acme.com"}`), - }); err != nil { - fmt.Println("publish:", err) - os.Exit(1) - } - - // Wait for the agent to finish acting, and fail the harness if the - // provider returns a successful reply without the required service side - // effects. The 0→hero/provider conformance path must not print success - // unless the services → agent → workflow contract actually happened. - ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second) - err := waitForOnboardingSideEffects(ctx, wsSvc, ntSvc, func(ctx context.Context) error { - fmt.Print("\n\033[33mwarning:\033[0m workspace exists before notify; retrying the welcome notification once before the flow can complete.\n") - _, err := onboarder.Ask(ctx, "The workspace for alice@acme.com already exists. Send exactly one welcome notification to alice@acme.com now. Use the notify service. Do not create another workspace and do not answer until the notification tool call has succeeded.") - return err - }) - cancel() - - fmt.Printf("\n\033[1mresult:\033[0m workspaces created=%d, notifications sent=%d\n", wsSvc.count(), ntSvc.count()) - if rs := f.Results(); len(rs) > 0 { - fmt.Printf("flow reply: %s\n", rs[len(rs)-1].Reply) - } - if err != nil { - fmt.Printf("\n\033[31m✗ %v\033[0m\n", err) - os.Exit(1) - } - fmt.Println("\n\033[32m✓ the agent onboarded the user — triggered by an event, not a prompt\033[0m") -} diff --git a/internal/harness/agent-flow/main_test.go b/internal/harness/agent-flow/main_test.go deleted file mode 100644 index fc3103b02a..0000000000 --- a/internal/harness/agent-flow/main_test.go +++ /dev/null @@ -1,211 +0,0 @@ -package main - -import ( - "context" - "strings" - "testing" - "time" - - "go-micro.dev/v6/agent" - "go-micro.dev/v6/broker" - "go-micro.dev/v6/client" - "go-micro.dev/v6/flow" - "go-micro.dev/v6/model" - "go-micro.dev/v6/registry" - "go-micro.dev/v6/selector" - "go-micro.dev/v6/service" - "go-micro.dev/v6/store" -) - -// TestEventTriggersAgentNoPrompt proves "the event is the prompt": a -// broker event drives a Flow that hands off to a registered agent, which -// reasons and acts through its services — workspace created, welcome -// sent — with no human prompt anywhere. Real services, registry, RPC, -// broker, agent loop, store; only the LLM is mocked. No mDNS, no sleeps -// beyond polling for the asynchronous side effect. -func TestEventTriggersAgentNoPrompt(t *testing.T) { - model.Register("mock", newMock) - - reg := registry.NewMemoryRegistry() - br := broker.NewMemoryBroker() - if err := br.Connect(); err != nil { - t.Fatalf("broker connect: %v", err) - } - cl := client.NewClient( - client.Registry(reg), - client.Selector(selector.NewSelector(selector.Registry(reg))), - ) - mem := store.NewMemoryStore() - - wsSvc := new(WorkspaceService) - ws := service.New(service.Name("workspace"), service.Address("127.0.0.1:0"), service.Registry(reg), service.Client(cl)) - if err := ws.Handle(wsSvc); err != nil { - t.Fatalf("handle workspace: %v", err) - } - go ws.Run() - - ntSvc := new(NotifyService) - nt := service.New(service.Name("notify"), service.Address("127.0.0.1:0"), service.Registry(reg), service.Client(cl)) - if err := nt.Handle(ntSvc); err != nil { - t.Fatalf("handle notify: %v", err) - } - go nt.Run() - - onboarder := agent.New( - agent.Name("onboarder"), - agent.Address("127.0.0.1:0"), - agent.Services("workspace", "notify"), - agent.Prompt("You onboard new users. Create their workspace and send a welcome message."), - agent.Provider("mock"), - agent.WithRegistry(reg), agent.WithClient(cl), agent.WithStore(mem), - ) - go onboarder.Run() - defer onboarder.Stop() - - waitFor(reg, "workspace") - waitFor(reg, "notify") - waitFor(reg, "onboarder") - - f := flow.New("onboard", - flow.Trigger("events.user.created"), - flow.Agent("onboarder"), - flow.Prompt("A new user signed up: {{.Data}}. Get them set up."), - ) - if err := f.Register(reg, br, cl); err != nil { - t.Fatalf("flow register: %v", err) - } - - // The event — nobody typed a prompt. - if err := br.Publish("events.user.created", &broker.Message{ - Body: []byte(`{"email":"alice@acme.com"}`), - }); err != nil { - t.Fatalf("publish: %v", err) - } - - // Wait for the agent to act (delivery is asynchronous). - deadline := time.Now().Add(10 * time.Second) - for time.Now().Before(deadline) { - if wsSvc.count() >= 1 && ntSvc.count() >= 1 { - break - } - time.Sleep(20 * time.Millisecond) - } - - if got := wsSvc.count(); got != 1 { - t.Errorf("workspace created %d times, want 1", got) - } - if got := ntSvc.count(); got != 1 { - t.Errorf("notify sent %d times, want 1 (event->flow->agent chain broken)", got) - } - if rs := f.Results(); len(rs) == 0 || rs[len(rs)-1].Reply == "" { - t.Errorf("flow recorded no result for the event") - } -} - -func TestWaitForOnboardingSideEffectsFailsWhenMissing(t *testing.T) { - wsSvc := new(WorkspaceService) - ntSvc := new(NotifyService) - - ctx, cancel := context.WithTimeout(context.Background(), time.Millisecond) - defer cancel() - - err := waitForOnboardingSideEffects(ctx, wsSvc, ntSvc, nil) - if err == nil { - t.Fatal("waitForOnboardingSideEffects returned nil, want missing side effects error") - } - if got := err.Error(); !strings.Contains(got, "workspaces=0/1") || !strings.Contains(got, "notifications=0/1") { - t.Fatalf("waitForOnboardingSideEffects error %q does not report missing side effects", got) - } -} - -func TestWaitForOnboardingSideEffectsPassesWhenComplete(t *testing.T) { - wsSvc := new(WorkspaceService) - ntSvc := new(NotifyService) - - if err := wsSvc.Create(context.Background(), &CreateRequest{Owner: "alice@acme.com"}, &CreateResponse{}); err != nil { - t.Fatalf("create workspace: %v", err) - } - if err := ntSvc.Send(context.Background(), &SendRequest{To: "alice@acme.com", Message: "Welcome"}, &SendResponse{}); err != nil { - t.Fatalf("send notification: %v", err) - } - - ctx, cancel := context.WithTimeout(context.Background(), time.Second) - defer cancel() - if err := waitForOnboardingSideEffects(ctx, wsSvc, ntSvc, nil); err != nil { - t.Fatalf("waitForOnboardingSideEffects returned %v, want nil", err) - } -} - -func TestWaitForOnboardingSideEffectsRecoversMissingNotification(t *testing.T) { - wsSvc := new(WorkspaceService) - ntSvc := new(NotifyService) - - if err := wsSvc.Create(context.Background(), &CreateRequest{Owner: "alice@acme.com"}, &CreateResponse{}); err != nil { - t.Fatalf("create workspace: %v", err) - } - - recovered := false - ctx, cancel := context.WithTimeout(context.Background(), time.Second) - defer cancel() - err := waitForOnboardingSideEffects(ctx, wsSvc, ntSvc, func(ctx context.Context) error { - recovered = true - return ntSvc.Send(ctx, &SendRequest{To: "alice@acme.com", Message: "Welcome — your workspace is ready."}, &SendResponse{}) - }) - if err != nil { - t.Fatalf("waitForOnboardingSideEffects returned %v, want recovered notification", err) - } - if !recovered { - t.Fatal("missing notification recovery did not run") - } - if got := ntSvc.count(); got != 1 { - t.Fatalf("notifications sent = %d, want 1 after recovery", got) - } -} - -func TestWorkspaceCreateSuppressesDuplicateOwner(t *testing.T) { - wsSvc := new(WorkspaceService) - first := new(CreateResponse) - if err := wsSvc.Create(context.Background(), &CreateRequest{Owner: "alice@acme.com"}, first); err != nil { - t.Fatalf("create first workspace: %v", err) - } - second := new(CreateResponse) - if err := wsSvc.Create(context.Background(), &CreateRequest{Owner: "alice@acme.com"}, second); err != nil { - t.Fatalf("create duplicate workspace: %v", err) - } - - if got := wsSvc.count(); got != 1 { - t.Fatalf("workspace creations = %d, want 1 after duplicate owner replay", got) - } - if first.Workspace == nil || second.Workspace == nil || second.Workspace.ID != first.Workspace.ID { - t.Fatalf("duplicate create returned workspace %#v, want original %#v", second.Workspace, first.Workspace) - } -} - -func TestNotifySendSuppressesDuplicateMessage(t *testing.T) { - ntSvc := new(NotifyService) - req := &SendRequest{To: "alice@acme.com", Message: "Welcome — your workspace is ready."} - if err := ntSvc.Send(context.Background(), req, &SendResponse{}); err != nil { - t.Fatalf("send first notification: %v", err) - } - if err := ntSvc.Send(context.Background(), req, &SendResponse{}); err != nil { - t.Fatalf("send duplicate notification: %v", err) - } - - if got := ntSvc.count(); got != 1 { - t.Fatalf("notifications sent = %d, want 1 after duplicate message replay", got) - } -} - -func TestNotifySendSuppressesDuplicateRecipient(t *testing.T) { - ntSvc := new(NotifyService) - if err := ntSvc.Send(context.Background(), &SendRequest{To: "Alice@Acme.com", Message: "Welcome — your workspace is ready."}, &SendResponse{}); err != nil { - t.Fatalf("send first notification: %v", err) - } - if err := ntSvc.Send(context.Background(), &SendRequest{To: " alice@acme.com ", Message: "Your workspace is ready."}, &SendResponse{}); err != nil { - t.Fatalf("send duplicate recipient notification: %v", err) - } - - if got := ntSvc.count(); got != 1 { - t.Fatalf("notifications sent = %d, want 1 after duplicate recipient replay", got) - } -} diff --git a/internal/harness/composition/README.md b/internal/harness/composition/README.md deleted file mode 100644 index a4c5f1f71e..0000000000 --- a/internal/harness/composition/README.md +++ /dev/null @@ -1,24 +0,0 @@ -# Restartable composition gate - -This provider-free fixture is the executable v6 Stage 4 contract. It starts a -real RPC capability service and agent, runs bounded mock-model tool work inside -a checkpointed flow, durably waits for approval, and invokes an idempotent final -service operation. The flow host is replaced after every boundary while its -file-backed checkpoint is retained. - -Run the release gate with: - -```sh -make composition-gate -``` - -The mock path is the only CI requirement and never needs credentials. For an -optional live-provider composition check, run the existing agent-flow harness: - -```sh -MICRO_AI_API_KEY=... go run ./internal/harness/agent-flow -provider openai -``` - -That live check is intentionally separate: provider availability and billing -must not determine whether restart, approval, lineage, or idempotency contracts -pass. diff --git a/internal/harness/composition/main.go b/internal/harness/composition/main.go deleted file mode 100644 index aa9c062d3c..0000000000 --- a/internal/harness/composition/main.go +++ /dev/null @@ -1,245 +0,0 @@ -// Command composition proves the restartable service-agent-flow contract with -// real in-process RPC, a mock model, and a persistent local checkpoint. -package main - -import ( - "context" - "errors" - "fmt" - "os" - "path/filepath" - "strings" - "sync" - "time" - - "go-micro.dev/v6/agent" - "go-micro.dev/v6/broker" - "go-micro.dev/v6/client" - "go-micro.dev/v6/flow" - "go-micro.dev/v6/model" - "go-micro.dev/v6/registry" - "go-micro.dev/v6/selector" - "go-micro.dev/v6/service" - "go-micro.dev/v6/store" -) - -type Request struct { - Key string `json:"key"` -} -type Response struct { - Key string `json:"key"` - Done bool `json:"done"` -} - -type Capability struct { - mu sync.Mutex - prepared, worked, finalized map[string]int -} - -func newCapability() *Capability { - return &Capability{prepared: map[string]int{}, worked: map[string]int{}, finalized: map[string]int{}} -} -func (s *Capability) Prepare(_ context.Context, req *Request, rsp *Response) error { - s.mu.Lock() - defer s.mu.Unlock() - s.prepared[req.Key]++ - rsp.Key = req.Key - return nil -} -func (s *Capability) Work(_ context.Context, req *Request, rsp *Response) error { - s.mu.Lock() - defer s.mu.Unlock() - s.worked[req.Key]++ - rsp.Key, rsp.Done = req.Key, true - return nil -} -func (s *Capability) Finalize(_ context.Context, req *Request, rsp *Response) error { - s.mu.Lock() - defer s.mu.Unlock() - if s.finalized[req.Key] == 0 { - s.finalized[req.Key] = 1 - } - rsp.Key, rsp.Done = req.Key, true - return nil -} -func (s *Capability) counts(key string) (int, int, int) { - s.mu.Lock() - defer s.mu.Unlock() - return s.prepared[key], s.worked[key], s.finalized[key] -} - -type mock struct{ opts model.Options } - -func (m *mock) Init(opts ...model.Option) error { - for _, opt := range opts { - opt(&m.opts) - } - return nil -} -func (m *mock) Options() model.Options { return m.opts } -func (m *mock) String() string { return "composition-mock" } -func (m *mock) Stream(context.Context, *model.Request, ...model.GenerateOption) (model.Stream, error) { - return nil, errors.New("stream unsupported") -} -func (m *mock) Generate(ctx context.Context, req *model.Request, _ ...model.GenerateOption) (*model.Response, error) { - name := "" - for _, tool := range req.Tools { - if strings.Contains(tool.Name, "Work") { - name = tool.Name - break - } - } - if name == "" || m.opts.ToolHandler == nil { - return nil, errors.New("work service tool not discovered") - } - key := "composition-42" - result := m.opts.ToolHandler(ctx, model.ToolCall{Name: name, Input: map[string]any{"key": key}}) - if result.Refused != "" { - return nil, fmt.Errorf("work tool refused: %s", result.Refused) - } - return &model.Response{Answer: `{"key":"composition-42","done":true}`}, nil -} - -func main() { - if err := run(context.Background()); err != nil { - panic(err) - } - fmt.Println("composition fixture: PASS") -} - -func run(ctx context.Context) error { - dir, err := os.MkdirTemp("", "go-micro-composition-") - if err != nil { - return err - } - defer os.RemoveAll(dir) - st := store.NewStore(store.DirOption(filepath.Join(dir, "state"))) - cp := flow.StoreCheckpoint(st, "composition") - agentCP := flow.StoreCheckpoint(st, "composition-agent") - - model.Register("composition-mock", func(opts ...model.Option) model.Model { m := new(mock); _ = m.Init(opts...); return m }) - reg := registry.NewMemoryRegistry() - cl := client.NewClient(client.Registry(reg), client.Selector(selector.NewSelector(selector.Registry(reg)))) - capability := newCapability() - svc := service.New(service.Name("composition-capability"), service.Address("127.0.0.1:0"), service.Registry(reg), service.Client(cl)) - if err := svc.Handle(capability); err != nil { - return err - } - go svc.Run() - defer svc.Stop() - - ag := agent.New(agent.Name("composition-agent"), agent.Address("127.0.0.1:0"), agent.Provider("composition-mock"), agent.Services("composition-capability"), agent.MaxSteps(1), agent.WithRegistry(reg), agent.WithClient(cl), agent.WithStore(st), agent.WithCheckpoint(agentCP)) - go ag.Run() - defer ag.Stop() - if err := waitFor(ctx, reg, "composition-capability", "composition-agent"); err != nil { - return err - } - - crash := map[string]bool{"before-agent": true, "before-approval": true, "finalize": true} - before := func(name string, fn flow.StepFunc) flow.StepFunc { - return func(ctx context.Context, in flow.State) (flow.State, error) { - if crash[name] { - crash[name] = false - return in, fmt.Errorf("injected host stop at %s", name) - } - return fn(ctx, in) - } - } - after := func(name string, fn flow.StepFunc) flow.StepFunc { - return func(ctx context.Context, in flow.State) (flow.State, error) { - out, err := fn(ctx, in) - if err == nil && crash[name] { - crash[name] = false - return out, fmt.Errorf("injected host stop after %s", name) - } - return out, err - } - } - steps := []flow.Step{ - {Name: "prepare", Run: flow.Call("composition-capability", "Capability.Prepare")}, - {Name: "agent", Run: before("before-agent", flow.Dispatch("composition-agent"))}, - {Name: "approval", Run: before("before-approval", flow.Await("approval", "approve final operation"))}, - {Name: "finalize", Run: after("finalize", flow.Call("composition-capability", "Capability.Finalize"))}, - } - newHost := func() *flow.Flow { - f := flow.New("composition", flow.Agent("composition-agent"), flow.Steps(steps...), flow.WithCheckpoint(cp)) - _ = f.Register(reg, broker.NewMemoryBroker(), cl) - return f - } - root := model.WithRunInfo(ctx, model.RunInfo{RunID: "request-composition", Dispatch: "direct"}) - if err := newHost().Execute(root, `{"key":"composition-42"}`); err == nil { - return errors.New("prepare boundary did not stop") - } - runs, _ := cp.List(ctx) - if len(runs) != 1 { - return fmt.Errorf("runs=%d, want 1", len(runs)) - } - id := runs[0].ID - if err := newHost().Resume(ctx, id); err == nil { - return errors.New("agent boundary did not stop") - } - if err := newHost().Resume(ctx, id); err != nil { - return fmt.Errorf("resume to approval: %w", err) - } - waiting, _ := newHost().Waiting(ctx) - if len(waiting) != 1 || waiting[0].Await == nil || waiting[0].Await.Prompt == "" { - return errors.New("approval was not durably inspectable") - } - if err := newHost().ResumeWith(ctx, id, `{"key":"composition-42"}`); err == nil { - return errors.New("final boundary did not stop") - } - if err := newHost().Resume(ctx, id); err != nil { - return fmt.Errorf("final restart: %w", err) - } - done, ok, _ := cp.Load(ctx, id) - if !ok || done.Status != "done" || done.ParentID != "request-composition" { - return fmt.Errorf("lost status or lineage: %+v", done) - } - agentRuns, _ := agentCP.List(ctx) - if len(agentRuns) == 0 || agentRuns[len(agentRuns)-1].ParentID != id { - return fmt.Errorf("agent child lineage was not inspectable: %+v", agentRuns) - } - prepared, worked, finalized := capability.counts("composition-42") - if prepared != 1 || worked != 1 || finalized != 1 { - return fmt.Errorf("unexpected effects prepare=%d work=%d finalize=%d", prepared, worked, finalized) - } - - failing := flow.New("composition-failed", flow.Steps(flow.Step{Name: "failed-tool", Run: func(_ context.Context, in flow.State) (flow.State, error) { return in, errors.New("tool failed") }}), flow.WithCheckpoint(flow.StoreCheckpoint(st, "failed"))) - if err := failing.Execute(ctx, "x"); err == nil { - return errors.New("failed tool reported success") - } - cancelCP := flow.StoreCheckpoint(st, "canceled") - canceled := flow.New("composition-canceled", flow.Steps(flow.Step{Name: "canceled", Run: func(_ context.Context, in flow.State) (flow.State, error) { return in, context.Canceled }}), flow.WithCheckpoint(cancelCP)) - if err := canceled.Execute(ctx, "x"); !errors.Is(err, context.Canceled) { - return fmt.Errorf("cancel outcome=%v", err) - } - cancelledRuns, _ := cancelCP.List(ctx) - if len(cancelledRuns) != 1 || cancelledRuns[0].Status != "failed" || cancelledRuns[0].Steps[0].ErrorKind != string(model.ErrorKindCanceled) { - return fmt.Errorf("canceled run was not a terminal non-success: %+v", cancelledRuns) - } - return nil -} - -func waitFor(ctx context.Context, reg registry.Registry, names ...string) error { - deadline := time.NewTimer(5 * time.Second) - defer deadline.Stop() - for { - all := true - for _, name := range names { - svcs, err := reg.GetService(name) - if err != nil || len(svcs) == 0 || len(svcs[0].Nodes) == 0 { - all = false - } - } - if all { - return nil - } - select { - case <-ctx.Done(): - return ctx.Err() - case <-deadline.C: - return errors.New("services did not register") - case <-time.After(10 * time.Millisecond): - } - } -} diff --git a/internal/harness/install-smoke/run.sh b/internal/harness/install-smoke/run.sh index ce391d5261..1b756f3244 100755 --- a/internal/harness/install-smoke/run.sh +++ b/internal/harness/install-smoke/run.sh @@ -86,7 +86,6 @@ require_output "first-agent preflight" "preflight" agent preflight --help require_output "local runtime" "micro run" run --help require_output "agent chat" "micro chat" chat --help require_output "agent inspection" "micro inspect agent" inspect agent --help -require_output "flow inspection" "micro inspect flow" inspect flow --help require_ordered_output "installed first-agent docs wayfinding" \ "micro agent demo" \ diff --git a/internal/harness/plan-delegate/main.go b/internal/harness/plan-delegate/main.go deleted file mode 100644 index 7c80991784..0000000000 --- a/internal/harness/plan-delegate/main.go +++ /dev/null @@ -1,776 +0,0 @@ -// Plan & Delegate integration harness. -// -// This runs the REAL go-micro stack end to end — real services, real -// registry, real RPC, the real agent loop, real store, real delegate -// routing — and mocks ONLY the LLM with a deterministic provider. It -// proves the plumbing works without an API key, and it's reproducible. -// -// Swap MICRO_AI_PROVIDER/MICRO_AI_API_KEY (and remove --mock) to run the -// exact same flow against a live model. -// -// Run: -// -// go run ./internal/harness/plan-delegate -package main - -import ( - "context" - "encoding/json" - "flag" - "fmt" - "os" - "strings" - "sync" - "time" - - "go-micro.dev/v6/agent" - "go-micro.dev/v6/broker" - "go-micro.dev/v6/flow" - "go-micro.dev/v6/internal/harness/harnessutil" - "go-micro.dev/v6/model" - "go-micro.dev/v6/registry" - "go-micro.dev/v6/service" - "go-micro.dev/v6/store" -) - -// --------------------------------------------------------------------------- -// real services -// --------------------------------------------------------------------------- - -type Task struct { - ID string `json:"id"` - Title string `json:"title"` -} - -type AddRequest struct { - Title string `json:"title" description:"Title of the task to add"` -} -type AddResponse struct { - Task *Task `json:"task"` -} -type ListRequest struct{} -type ListResponse struct { - Tasks []*Task `json:"tasks"` -} - -type TaskService struct { - mu sync.Mutex - tasks []*Task - byTitle map[string]*Task - nextID int -} - -// Add creates a new task with the given title. Replayed live-model tool calls -// are idempotent by launch task title so the conformance harness proves exactly -// one durable side effect per intended task even if a provider resends a call. -// @example {"title": "Design"} -func (s *TaskService) Add(ctx context.Context, req *AddRequest, rsp *AddResponse) error { - s.mu.Lock() - defer s.mu.Unlock() - if s.byTitle == nil { - s.byTitle = map[string]*Task{} - } - key := launchTaskKey(req.Title) - if t := s.byTitle[key]; t != nil { - rsp.Task = t - fmt.Printf(" \033[32m[task]\033[0m reused %s %q\n", t.ID, t.Title) - return nil - } - s.nextID++ - t := &Task{ID: fmt.Sprintf("task-%d", s.nextID), Title: canonicalLaunchTitle(req.Title)} - s.tasks = append(s.tasks, t) - s.byTitle[key] = t - rsp.Task = t - fmt.Printf(" \033[32m[task]\033[0m created %s %q\n", t.ID, t.Title) - return nil -} - -func launchTaskKey(title string) string { - s := strings.ToLower(strings.TrimSpace(title)) - switch { - case strings.Contains(s, "design"): - return "design" - case strings.Contains(s, "build"): - return "build" - case strings.Contains(s, "ship"): - return "ship" - default: - return s - } -} - -func canonicalLaunchTitle(title string) string { - switch launchTaskKey(title) { - case "design": - return "Design" - case "build": - return "Build" - case "ship": - return "Ship" - default: - return strings.TrimSpace(title) - } -} - -// List returns all tasks. -// @example {} -func (s *TaskService) List(ctx context.Context, req *ListRequest, rsp *ListResponse) error { - s.mu.Lock() - defer s.mu.Unlock() - rsp.Tasks = append(rsp.Tasks, s.tasks...) - return nil -} - -func (s *TaskService) count() int { - s.mu.Lock() - defer s.mu.Unlock() - return len(s.tasks) -} - -const delegatedNotifyTask = "Use the notify Send tool exactly once to tell owner@acme.com: The launch plan is ready. Do not answer until the notify tool call has succeeded." - -const commsPrompt = "You handle outbound notifications. When asked to notify someone, you must call the notify Send tool exactly once before replying. Never claim a notification was sent unless the notify tool returned success." - -const delegatedNotifySettleTimeout = 10 * time.Second - -type SendRequest struct { - To string `json:"to" description:"Recipient address"` - Message string `json:"message" description:"Message body"` -} -type SendResponse struct { - Sent bool `json:"sent"` -} -type NotifyService struct { - mu sync.Mutex - sent int - attempts int - duplicates int - bySend map[string]bool -} - -// Send delivers a notification message to a recipient. Duplicate delivery -// attempts for the same recipient/message are treated as successful replays -// without producing another side effect. -// @example {"to": "owner@acme.com", "message": "ready"} -func (s *NotifyService) Send(ctx context.Context, req *SendRequest, rsp *SendResponse) error { - s.mu.Lock() - if s.bySend == nil { - s.bySend = map[string]bool{} - } - key := notifyDedupKey(req.To, req.Message) - s.attempts++ - if !s.bySend[key] { - s.bySend[key] = true - s.sent++ - fmt.Printf(" \033[35m[notify]\033[0m 📨 to=%s message=%q\n", req.To, req.Message) - } else { - s.duplicates++ - fmt.Printf(" \033[35m[notify]\033[0m reused to=%s message=%q\n", req.To, req.Message) - } - s.mu.Unlock() - rsp.Sent = true - return nil -} - -func (s *NotifyService) count() int { - s.mu.Lock() - defer s.mu.Unlock() - return s.sent -} - -func (s *NotifyService) duplicateAttempts() int { - s.mu.Lock() - defer s.mu.Unlock() - return s.duplicates -} - -func notifyDedupKey(to, message string) string { - recipient := canonicalLaunchNotifyRecipient(normalizeNotifyText(to)) - body := normalizeNotifyText(message) - if recipient == "owner@acme.com" && isLaunchReadinessNotify(body) { - body = "launch-readiness" - } - return recipient + "\x00" + body -} - -func canonicalLaunchNotifyRecipient(recipient string) string { - recipient = canonicalSpokenEmailRecipient(recipient) - switch recipient { - case "owner", "launch owner", "plan owner", "owner acme com", "owner@acme com", "owner @ acme com": - return "owner@acme.com" - default: - if strings.Contains(recipient, "owner") && strings.Contains(recipient, "acme") { - return "owner@acme.com" - } - return recipient - } -} - -func canonicalSpokenEmailRecipient(recipient string) string { - fields := strings.Fields(recipient) - if len(fields) == 5 && fields[1] == "at" && fields[3] == "dot" { - return fields[0] + "@" + fields[2] + "." + fields[4] - } - return recipient -} - -func normalizeNotifyText(message string) string { - message = strings.ToLower(strings.TrimSpace(message)) - message = strings.Map(func(r rune) rune { - switch { - case r >= 'a' && r <= 'z', r >= '0' && r <= '9': - return r - case r == '@': - return r - default: - return ' ' - } - }, message) - return strings.Join(strings.Fields(message), " ") -} - -func isLaunchReadinessNotify(message string) bool { - hasLaunch := strings.Contains(message, "launch") - hasPlanOrReadiness := strings.Contains(message, "plan") || - strings.Contains(message, "readiness") || - strings.Contains(message, "ready") - hasCompletion := strings.Contains(message, "ready") || - strings.Contains(message, "readiness") || - strings.Contains(message, "prepared") || - strings.Contains(message, "complete") || - strings.Contains(message, "finished") || - strings.Contains(message, "done") || - strings.Contains(message, "sent") - return hasLaunch && hasPlanOrReadiness && hasCompletion -} - -// --------------------------------------------------------------------------- -// mock LLM provider — the ONLY fake. It "reasons" by simple heuristics -// over the tools it's offered and the system prompt it's given, calling -// the real tool handler exactly the way a real provider would. -// --------------------------------------------------------------------------- - -type mockModel struct { - opts model.Options - - // unknownDelegateOnce makes the mock emit one provider-style, unavailable - // delegate tool name before using the registered delegate tool. This mirrors - // live providers that occasionally hallucinate a provider-specific tool while - // still keeping the regression deterministic and keyless. - unknownDelegateOnce bool - emittedUnknownDelegate bool - - // duplicateNotify makes the comms mock replay the same notification call. - // The notify service should collapse that replay to one durable side effect. - duplicateNotify bool - - // duplicateDelegate makes the conductor mock replay the same delegate call. - // The delegate idempotency path should collapse that replay before it can - // ask the delegated comms agent to notify twice. - duplicateDelegate bool - - // interruptAfterTasks makes the conductor mock stop after persisted plan and - // task side effects, before delegation. The harness should recover the - // missing notification without replaying completed tasks. - interruptAfterTasks bool - - // nestedDelegateMarkup makes the conductor mock attempt to smuggle text - // tool-call markup inside the delegate arguments. The agent guardrail must - // refuse it before any delegated side effect can run. - nestedDelegateMarkup bool -} - -func newMock(opts ...model.Option) model.Model { - m := &mockModel{} - _ = m.Init(opts...) - return m -} - -func newMockUnknownDelegate(opts ...model.Option) model.Model { - m := &mockModel{unknownDelegateOnce: true} - _ = m.Init(opts...) - return m -} - -func newMockDuplicateNotify(opts ...model.Option) model.Model { - m := &mockModel{duplicateNotify: true} - _ = m.Init(opts...) - return m -} - -func newMockDuplicateDelegate(opts ...model.Option) model.Model { - m := &mockModel{duplicateDelegate: true} - _ = m.Init(opts...) - return m -} - -func newMockInterruptAfterTasks(opts ...model.Option) model.Model { - m := &mockModel{interruptAfterTasks: true} - _ = m.Init(opts...) - return m -} - -func newMockNestedDelegateMarkup(opts ...model.Option) model.Model { - m := &mockModel{nestedDelegateMarkup: true} - _ = m.Init(opts...) - return m -} - -func (m *mockModel) Init(opts ...model.Option) error { - for _, o := range opts { - o(&m.opts) - } - return nil -} -func (m *mockModel) Options() model.Options { return m.opts } -func (m *mockModel) String() string { return "mock" } -func (m *mockModel) Stream(ctx context.Context, req *model.Request, _ ...model.GenerateOption) (model.Stream, error) { - return nil, fmt.Errorf("stream not supported by mock") -} - -// findTool returns the safe name of the first offered tool whose name -// contains sub, or "" if none. -func findTool(tools []model.Tool, sub string) string { - for _, t := range tools { - if strings.Contains(t.Name, sub) { - return t.Name - } - } - return "" -} - -func (m *mockModel) call(who, name string, input map[string]any) model.ToolResult { - args, _ := json.Marshal(input) - fmt.Printf(" \033[33m[%s]\033[0m → %s(%s)\n", who, name, args) - if m.opts.ToolHandler != nil { - return m.opts.ToolHandler(context.Background(), model.ToolCall{Name: name, Input: input}) - } - return model.ToolResult{} -} - -func (m *mockModel) Generate(ctx context.Context, req *model.Request, _ ...model.GenerateOption) (*model.Response, error) { - // Classify by the tools actually offered, not by prompt text: - // the conductor has the task "Add" tool, comms has "Send". - hasAdd := findTool(req.Tools, "Add") != "" - hasSend := findTool(req.Tools, "Send") != "" - - switch { - // comms agent: owns notify, has Send but not Add. - case hasSend && !hasAdd: - send := findTool(req.Tools, "Send") - input := map[string]any{ - "to": "owner@acme.com", - "message": "The launch plan is ready", - } - m.call("comms", send, input) - if m.duplicateNotify { - m.call("comms", send, input) - } - return &model.Response{Answer: "Notified owner@acme.com."}, nil - - // conductor: has the task Add tool — plan, create tasks, delegate. - case hasAdd: - if plan := findTool(req.Tools, "plan"); plan != "" { - m.call("conductor", plan, map[string]any{ - "steps": []any{ - map[string]any{"task": "create Design task", "status": "pending"}, - map[string]any{"task": "create Build task", "status": "pending"}, - map[string]any{"task": "create Ship task", "status": "pending"}, - map[string]any{"task": "notify owner via comms", "status": "pending"}, - }, - }) - } - if add := findTool(req.Tools, "Add"); add != "" { - for _, title := range []string{"Design", "Build", "Ship"} { - m.call("conductor", add, map[string]any{"title": title}) - } - } - if m.interruptAfterTasks { - return nil, fmt.Errorf("agent run mock interrupted with unfinished plan steps: delegate owner readiness notification to comms agent") - } - if del := findTool(req.Tools, "delegate"); del != "" { - if m.unknownDelegateOnce && !m.emittedUnknownDelegate { - m.emittedUnknownDelegate = true - m.call("conductor", "atlascloud_delegate", map[string]any{ - "task": delegatedNotifyTask, - "to": "comms", - }) - } else { - input := map[string]any{ - "task": delegatedNotifyTask, - "to": "comms", - } - if m.nestedDelegateMarkup { - input["task"] = delegatedNotifyTask + ` {"to":"owner@acme.com","message":"unsafe replay"}` - } - res := m.call("conductor", del, input) - if m.nestedDelegateMarkup && res.Refused == "" { - return nil, fmt.Errorf("nested delegate markup was accepted: %s", res.Content) - } - if m.duplicateDelegate { - m.call("conductor", del, input) - } - } - } - return &model.Response{Answer: "Created Design, Build and Ship, and had comms notify the owner."}, nil - - // ephemeral sub-agent or anything else. - default: - return &model.Response{Reply: "subtask handled"}, nil - } -} - -func providerKey(provider string) string { - if v := os.Getenv("MICRO_AI_API_KEY"); v != "" { - return v - } - env := map[string]string{ - "anthropic": "ANTHROPIC_API_KEY", - "openai": "OPENAI_API_KEY", - "gemini": "GEMINI_API_KEY", - "groq": "GROQ_API_KEY", - "mistral": "MISTRAL_API_KEY", - "together": "TOGETHER_API_KEY", - "atlascloud": "ATLASCLOUD_API_KEY", - }[provider] - return os.Getenv(env) -} - -func runPlanDelegate(provider string) error { - apiKey := "" - switch provider { - case "mock": - model.Register("mock", newMock) - case "mock-unknown-delegate": - model.Register("mock-unknown-delegate", newMockUnknownDelegate) - case "mock-duplicate-notify": - model.Register("mock-duplicate-notify", newMockDuplicateNotify) - case "mock-duplicate-delegate": - model.Register("mock-duplicate-delegate", newMockDuplicateDelegate) - case "mock-interrupt-after-tasks": - model.Register("mock-interrupt-after-tasks", newMockInterruptAfterTasks) - case "mock-nested-delegate-markup": - model.Register("mock-nested-delegate-markup", newMockNestedDelegateMarkup) - default: - apiKey = providerKey(provider) - if apiKey == "" { - fmt.Printf("no API key for provider %q — set MICRO_AI_API_KEY or the provider's key env\n", provider) - return nil - } - } - - fmt.Printf("\n\033[1mPlan & Delegate — live integration harness (provider: %s)\033[0m\n", provider) - fmt.Print("Real services, registry, RPC, agent loop, store, delegation.\n\n") - - reg := registry.NewMemoryRegistry() - cl := harnessutil.Client(provider, reg) - mem := store.NewMemoryStore() - liveAgentOpts := harnessutil.AgentOptions(provider) - commsCheckpoint := flow.StoreCheckpoint(mem, "agent-comms") - conductorCheckpoint := flow.StoreCheckpoint(mem, "agent-conductor") - - // Real services. - taskSvc := new(TaskService) - task := service.New(service.Name("task"), service.Address("127.0.0.1:0"), service.Registry(reg), service.Client(cl)) - if err := task.Handle(taskSvc); err != nil { - return fmt.Errorf("task handle: %w", err) - } - if err := task.Start(); err != nil { - return fmt.Errorf("task start: %w", err) - } - defer task.Stop() - - notifySvc := new(NotifyService) - notify := service.New(service.Name("notify"), service.Address("127.0.0.1:0"), service.Registry(reg), service.Client(cl)) - if err := notify.Handle(notifySvc); err != nil { - return fmt.Errorf("notify handle: %w", err) - } - if err := notify.Start(); err != nil { - return fmt.Errorf("notify start: %w", err) - } - defer notify.Stop() - - // Real comms agent (owns notify), registered so delegate reaches it over RPC. - commsOpts := []agent.Option{ - agent.Name("comms"), - agent.Address("127.0.0.1:0"), - agent.Services("notify"), - agent.Prompt(commsPrompt), - agent.Provider(provider), agent.APIKey(apiKey), - agent.WithRegistry(reg), agent.WithClient(cl), agent.WithStore(mem), - agent.WithCheckpoint(commsCheckpoint), - } - commsOpts = append(commsOpts, liveAgentOpts...) - comms := agent.New(commsOpts...) - go comms.Run() - defer comms.Stop() - - // Real conductor agent (owns task), registered so the flow can reach it over RPC. - conductorOpts := []agent.Option{ - agent.Name("conductor"), - agent.Address("127.0.0.1:0"), - agent.Services("task"), - agent.Prompt("You coordinate launch work. Before any task or delegate tool call, you must persist the launch-readiness plan with the built-in plan tool. Then create exactly one Design task, one Build task, and one Ship task, then delegate exactly one readiness notification to the \"comms\" agent. Do not create duplicate tasks and do not send notifications yourself."), - agent.Provider(provider), agent.APIKey(apiKey), - agent.WithRegistry(reg), agent.WithClient(cl), agent.WithStore(mem), - agent.WithCheckpoint(conductorCheckpoint), - agent.WrapTool(requirePersistedPlanBeforeConductorActions(mem)), - } - conductorOpts = append(conductorOpts, liveAgentOpts...) - conductor := agent.New(conductorOpts...) - go conductor.Run() - defer conductor.Stop() - - fmt.Println("waiting for services + agents to register...") - waitForService := func(name string) error { - deadline := time.Now().Add(5 * time.Second) - for time.Now().Before(deadline) { - if svcs, err := reg.GetService(name); err == nil && len(svcs) > 0 && len(svcs[0].Nodes) > 0 { - return nil - } - time.Sleep(20 * time.Millisecond) - } - return fmt.Errorf("service %q never registered", name) - } - for _, name := range []string{"task", "notify", "comms", "conductor"} { - if err := waitForService(name); err != nil { - return err - } - } - - f := flow.New("zero-to-hero", - flow.Steps( - flow.Step{Name: "conductor", Run: planDelegateConductorStep(conductor, taskSvc, notifySvc)}, - flow.Step{Name: "require-notify", Run: requireDelegatedNotifyStep(taskSvc, notifySvc, func(ctx context.Context) error { - _, err := comms.Ask(ctx, "Send exactly one owner readiness notification now with this exact task: "+delegatedNotifyTask+" Use the notify service and do not answer until the notification has been sent.") - return err - })}, - ), - flow.WithCheckpoint(flow.StoreCheckpoint(mem, "flow-zero-to-hero")), - flow.Timeout(harnessutil.LiveTimeout(provider)), - ) - if err := f.Register(reg, broker.DefaultBroker, cl); err != nil { - return fmt.Errorf("flow register: %w", err) - } - - fmt.Print("\n\033[1m> flow:\033[0m services + agents + workflow + plan/delegate, no API key.\n\n") - ctx, cancel := context.WithCancel(context.Background()) - defer cancel() - executeDone := make(chan error, 1) - go func() { - executeDone <- f.Execute(ctx, "launch readiness") - }() - - if err := waitForPlanDelegateExecution(executeDone, taskSvc, notifySvc, func(ctx context.Context) error { - _, err := comms.Ask(ctx, "Recover the missing owner readiness notification now for the launch work already created. Send exactly one notification with this exact task: "+delegatedNotifyTask+" Use the notify service and do not create or modify tasks.") - return err - }); err != nil { - return err - } - - if err := requireConductorPlan(context.Background(), mem, conductor); err != nil { - return err - } - if taskSvc.count() == 0 || notifySvc.count() != 1 { - return fmt.Errorf("unexpected side effects: tasks=%d notify=%d", taskSvc.count(), notifySvc.count()) - } - - fmt.Println("\n\033[32m✓ 0→hero flow complete (services → agents → workflow)\033[0m") - return nil -} - -func requirePersistedPlanBeforeConductorActions(mem store.Store) model.ToolWrapper { - return func(next model.ToolHandler) model.ToolHandler { - return func(ctx context.Context, call model.ToolCall) model.ToolResult { - if call.Name == "plan" { - return next(ctx, call) - } - if recs, err := store.Scope(mem, "agent", "conductor").Read("plan"); err == nil && len(recs) > 0 { - return next(ctx, call) - } - msg := "persist the launch-readiness plan first by calling the built-in plan tool before task or delegate side effects" - return model.ToolResult{ - ID: call.ID, - Value: map[string]string{"error": msg}, - Content: `{"error":"` + msg + `"}`, - Refused: model.RefusedApproval, - } - } - } -} - -func requireConductorPlan(ctx context.Context, mem store.Store, conductor agent.Agent) error { - recs, _ := store.Scope(mem, "agent", "conductor").Read("plan") - if len(recs) == 0 && conductor != nil { - fmt.Print("\n\033[33mwarning:\033[0m conductor completed side effects without a persisted plan; retrying plan persistence once before final assertions.\n") - _, err := conductor.Ask(ctx, "Persist the launch-readiness plan now using the built-in plan tool before answering. Record exactly these completed steps: Design launch task, Build launch task, Ship launch task, and delegate owner readiness notification to comms. Do not call task or notify tools.") - if err != nil { - return fmt.Errorf("plan was not persisted at agent/conductor/plan and recovery prompt failed after completed side effects: %w", err) - } - recs, _ = store.Scope(mem, "agent", "conductor").Read("plan") - } - if len(recs) == 0 { - return fmt.Errorf("plan was not persisted at agent/conductor/plan; conductor completed task/notify side effects without calling the built-in plan tool") - } - if len(recs) != 1 { - return fmt.Errorf("unexpected persisted conductor plans at agent/conductor/plan: got %d records, want 1", len(recs)) - } - fmt.Printf("\n\033[1mstored plan (agent/conductor/plan):\033[0m %s\n", string(recs[0].Value)) - return nil -} - -func planDelegateConductorStep(conductor agent.Agent, taskSvc *TaskService, notifySvc *NotifyService) flow.StepFunc { - return func(ctx context.Context, in flow.State) (flow.State, error) { - prompt := "Create three launch tasks (Design, Build, Ship), then make sure owner@acme.com is notified: " + in.String() - rsp, err := conductor.Ask(ctx, prompt) - if err != nil { - if isUnfinishedPlanError(err) && taskSvc != nil && notifySvc != nil && taskSvc.count() > 0 && notifySvc.count() == 0 { - fmt.Printf("\n\033[33mwarning:\033[0m conductor stopped with unfinished delegation after creating tasks; continuing to require-notify recovery: %v\n", err) - return in, nil - } - return in, err - } - if rsp != nil && rsp.Reply != "" { - fmt.Println("\n\033[1m< conductor reply:\033[0m", rsp.Reply) - } - if taskSvc != nil && notifySvc != nil && taskSvc.count() == 0 && notifySvc.count() == 0 { - fmt.Print("\n\033[33mwarning:\033[0m conductor persisted/planned without service side effects; retrying task execution before notify gate.\n") - rsp, err = conductor.Ask(ctx, "Continue the launch-readiness run now. Execute the persisted plan by calling the task Add tool exactly once for Design, Build, and Ship, then delegate the owner readiness notification to comms. Do not answer until at least one required tool call succeeds.") - if err != nil { - if isUnfinishedPlanError(err) && taskSvc.count() > 0 && notifySvc.count() == 0 { - fmt.Printf("\n\033[33mwarning:\033[0m conductor recovered tasks but stopped before notification; continuing to require-notify recovery: %v\n", err) - return in, nil - } - return in, err - } - if rsp != nil && rsp.Reply != "" { - fmt.Println("\n\033[1m< conductor reply:\033[0m", rsp.Reply) - } - } - if taskSvc != nil && notifySvc != nil && taskSvc.count() == 0 { - return in, fmt.Errorf("plan-delegate reached notify gate before task side effects completed (tasks=0/3 notify=%d/1); model produced a plan but did not call task Add for Design, Build, and Ship", notifySvc.count()) - } - return in, nil - } -} - -func isUnfinishedPlanError(err error) bool { - if err == nil { - return false - } - return strings.Contains(strings.ToLower(err.Error()), "unfinished plan steps") -} - -func requireDelegatedNotifyStep(taskSvc *TaskService, notifySvc *NotifyService, recoverMissingNotify func(context.Context) error) flow.StepFunc { - return func(ctx context.Context, in flow.State) (flow.State, error) { - tasks := taskSvc.count() - notify := notifySvc.count() - if notify == 1 { - return in, nil - } - if recoverMissingNotify == nil || tasks == 0 || notify != 0 { - return in, fmt.Errorf("delegation completed without required notify side effect: notify=%d, want 1", notify) - } - settled, err := waitForNotifySideEffect(notifySvc, delegatedNotifySettleTimeout) - if err != nil { - return in, err - } - if !settled { - fmt.Print("\n\033[33mwarning:\033[0m conductor step completed before delegated notify; retrying the missing comms handoff once before the flow can complete.\n") - if err := recoverMissingNotify(ctx); err != nil { - return in, fmt.Errorf("delegation completed without required notify side effect and recovery failed: notify=%d, want 1: %w", notify, err) - } - settled, err = waitForNotifySideEffect(notifySvc, delegatedNotifySettleTimeout) - if err != nil { - return in, err - } - if !settled { - return in, fmt.Errorf("delegation recovery completed without required notify side effect: notify=%d, want 1", notifySvc.count()) - } - } - if notify = notifySvc.count(); notify != 1 { - return in, fmt.Errorf("delegation recovery completed without required notify side effect: notify=%d, want 1", notify) - } - return in, nil - } -} - -func waitForPlanDelegateExecution(done <-chan error, taskSvc *TaskService, notifySvc *NotifyService, recoverMissingNotify func(context.Context) error) error { - ticker := time.NewTicker(50 * time.Millisecond) - defer ticker.Stop() - for { - select { - case err := <-done: - tasks := taskSvc.count() - notify := notifySvc.count() - if err != nil { - if hasCompletedPlanDelegateSideEffects(tasks, notify) { - fmt.Printf("\n\033[33mwarning:\033[0m flow execute returned after completed side effects: %v\n", err) - return nil - } - if isClientTimeout(err) { - return classifiedPlanDelegateTimeout(tasks, notify, err) - } - if isUnfinishedPlanError(err) && tasks > 0 && notify == 0 && recoverMissingNotify != nil { - fmt.Printf("\n\033[33mwarning:\033[0m flow stopped after partial plan side effects; recovering missing delegated notify: %v\n", err) - if recoverErr := recoverMissingNotify(context.Background()); recoverErr != nil { - return fmt.Errorf("flow execute after side effects tasks=%d notify=%d and recovery failed: %w", tasks, notify, recoverErr) - } - settled, waitErr := waitForNotifySideEffect(notifySvc, delegatedNotifySettleTimeout) - if waitErr != nil { - return waitErr - } - if settled { - return nil - } - return fmt.Errorf("flow execute after side effects tasks=%d notify=%d: delegation recovery completed without required notify side effect: notify=%d, want 1", tasks, notify, notifySvc.count()) - } - return fmt.Errorf("flow execute after side effects tasks=%d notify=%d: %w", tasks, notify, err) - } - if notify != 1 { - return fmt.Errorf("delegation completed without required notify side effect: notify=%d, want 1", notify) - } - return nil - case <-ticker.C: - if notifySvc.count() == 1 { - continue - } - } - } -} - -func waitForNotifySideEffect(notifySvc *NotifyService, timeout time.Duration) (bool, error) { - deadline := time.Now().Add(timeout) - for { - if notifySvc.count() == 1 { - return true, nil - } - if !time.Now().Before(deadline) { - return false, nil - } - time.Sleep(50 * time.Millisecond) - } -} - -func hasCompletedPlanDelegateSideEffects(tasks, notify int) bool { - return tasks == 3 && notify == 1 -} - -func classifiedPlanDelegateTimeout(tasks, notify int, err error) error { - return fmt.Errorf("provider latency/outage during plan-delegate before required side effects completed (tasks=%d/3 notify=%d/1); retry live provider or inspect provider logs if this recurs: %w", tasks, notify, err) -} - -func isClientTimeout(err error) bool { - msg := strings.ToLower(err.Error()) - return strings.Contains(msg, "request timeout") || strings.Contains(msg, "code=408") || strings.Contains(msg, "code\":408") -} - -func main() { - provider := flag.String("provider", "mock", "LLM provider: mock (default), mock-unknown-delegate, mock-duplicate-notify, mock-duplicate-delegate, anthropic, openai, gemini, groq, mistral, together, atlascloud") - flag.Parse() - - if err := runPlanDelegate(*provider); err != nil { - fmt.Println("\033[31merror:\033[0m", err) - os.Exit(1) - } -} diff --git a/internal/harness/plan-delegate/main_test.go b/internal/harness/plan-delegate/main_test.go deleted file mode 100644 index f380b378bc..0000000000 --- a/internal/harness/plan-delegate/main_test.go +++ /dev/null @@ -1,818 +0,0 @@ -package main - -import ( - "context" - "errors" - "reflect" - "strings" - "testing" - "time" - - "go-micro.dev/v6/agent" - "go-micro.dev/v6/broker" - "go-micro.dev/v6/client" - "go-micro.dev/v6/flow" - "go-micro.dev/v6/model" - "go-micro.dev/v6/registry" - "go-micro.dev/v6/selector" - "go-micro.dev/v6/service" - "go-micro.dev/v6/store" -) - -// waitForService polls the registry until name is registered, instead of -// sleeping. Keeps the test deterministic. -func waitForService(t *testing.T, reg registry.Registry, name string) { - t.Helper() - deadline := time.Now().Add(5 * time.Second) - for time.Now().Before(deadline) { - if svcs, err := reg.GetService(name); err == nil && len(svcs) > 0 && len(svcs[0].Nodes) > 0 { - return - } - time.Sleep(20 * time.Millisecond) - } - t.Fatalf("service %q never registered", name) -} - -// TestPlanDelegateEndToEnd runs the whole feature against the real stack -// — real services, a shared in-memory registry, real RPC, the real agent -// loop, real store — with only the LLM mocked. No mDNS, no sleeps. -func TestPlanDelegateEndToEnd(t *testing.T) { - model.Register("mock", newMock) - - // Shared infrastructure: one in-memory registry, a client bound to - // it, and an in-memory store. Everything resolves through these. - reg := registry.NewMemoryRegistry() - cl := client.NewClient( - client.Registry(reg), - client.Selector(selector.NewSelector(selector.Registry(reg))), - ) - mem := store.NewMemoryStore() - - // Real services on the shared registry/client. - taskSvc := new(TaskService) - task := service.New(service.Name("task"), service.Address("127.0.0.1:0"), service.Registry(reg), service.Client(cl)) - if err := task.Handle(taskSvc); err != nil { - t.Fatalf("handle task: %v", err) - } - if err := task.Start(); err != nil { - t.Fatalf("start task: %v", err) - } - defer task.Stop() - - notifySvc := new(NotifyService) - notify := service.New(service.Name("notify"), service.Address("127.0.0.1:0"), service.Registry(reg), service.Client(cl)) - if err := notify.Handle(notifySvc); err != nil { - t.Fatalf("handle notify: %v", err) - } - if err := notify.Start(); err != nil { - t.Fatalf("start notify: %v", err) - } - defer notify.Stop() - - // Real comms agent (owns notify), registered so delegate reaches it over RPC. - comms := agent.New( - agent.Name("comms"), - agent.Address("127.0.0.1:0"), - agent.Services("notify"), - agent.Prompt(commsPrompt), - agent.Provider("mock"), - agent.WithRegistry(reg), - agent.WithClient(cl), - agent.WithStore(mem), - ) - go comms.Run() - defer comms.Stop() - - waitForService(t, reg, "task") - waitForService(t, reg, "notify") - waitForService(t, reg, "comms") - - // Real conductor agent (owns task), driven programmatically. - conductor := agent.New( - agent.Name("conductor"), - agent.Address("127.0.0.1:0"), - agent.Services("task"), - agent.Prompt("Plan first, create tasks, delegate notifications to the comms agent."), - agent.Provider("mock"), - agent.WithRegistry(reg), - agent.WithClient(cl), - agent.WithStore(mem), - ) - - resp, err := conductor.Ask(context.Background(), - "Create three launch tasks: Design, Build, and Ship. Then notify owner@acme.com that the plan is ready.") - if err != nil { - t.Fatalf("Ask: %v", err) - } - if resp.Reply == "" { - t.Error("conductor returned an empty reply") - } - - // Tasks were created via real RPC into the task service. - if n := taskSvc.count(); n != 3 { - t.Errorf("task service has %d tasks, want 3", n) - } - - // The plan was persisted to the real store, in the agent's scoped table. - if recs, err := store.Scope(mem, "agent", "conductor").Read("plan"); err != nil || len(recs) == 0 { - t.Errorf("plan not persisted to store: err=%v recs=%d", err, len(recs)) - } - - // Delegation reached the comms agent over RPC, which called notify. - if n := notifySvc.count(); n != 1 { - t.Errorf("notify service called %d times, want 1 (delegation did not reach comms)", n) - } -} - -// TestFlowDispatchesToAgentEndToEnd proves "Flow triggers, Agent reasons": -// a workflow event hands off to the registered conductor agent, which then -// plans, creates tasks, and delegates to comms — all over real RPC. Only -// the LLM is mocked. -func TestFlowDispatchesToAgentEndToEnd(t *testing.T) { - model.Register("mock", newMock) - - reg := registry.NewMemoryRegistry() - cl := client.NewClient( - client.Registry(reg), - client.Selector(selector.NewSelector(selector.Registry(reg))), - ) - mem := store.NewMemoryStore() - - taskSvc := new(TaskService) - task := service.New(service.Name("task"), service.Address("127.0.0.1:0"), service.Registry(reg), service.Client(cl)) - if err := task.Handle(taskSvc); err != nil { - t.Fatalf("handle task: %v", err) - } - if err := task.Start(); err != nil { - t.Fatalf("start task: %v", err) - } - defer task.Stop() - - notifySvc := new(NotifyService) - notify := service.New(service.Name("notify"), service.Address("127.0.0.1:0"), service.Registry(reg), service.Client(cl)) - if err := notify.Handle(notifySvc); err != nil { - t.Fatalf("handle notify: %v", err) - } - if err := notify.Start(); err != nil { - t.Fatalf("start notify: %v", err) - } - defer notify.Stop() - - comms := agent.New( - agent.Name("comms"), - agent.Address("127.0.0.1:0"), - agent.Services("notify"), - agent.Prompt(commsPrompt), - agent.Provider("mock"), - agent.WithRegistry(reg), - agent.WithClient(cl), - agent.WithStore(mem), - ) - go comms.Run() - defer comms.Stop() - - // Unlike the previous test, the conductor must be registered (running) - // so the flow can reach it over RPC. - conductor := agent.New( - agent.Name("conductor"), - agent.Address("127.0.0.1:0"), - agent.Services("task"), - agent.Prompt("Plan first, create tasks, delegate notifications to the comms agent."), - agent.Provider("mock"), - agent.WithRegistry(reg), - agent.WithClient(cl), - agent.WithStore(mem), - ) - go conductor.Run() - defer conductor.Stop() - - waitForService(t, reg, "task") - waitForService(t, reg, "notify") - waitForService(t, reg, "comms") - waitForService(t, reg, "conductor") - - // A workflow that hands each event to the conductor agent. - f := flow.New("onboard", - flow.Agent("conductor"), - flow.Prompt("Get the launch ready: {{.Data}}"), - ) - if err := f.Register(reg, broker.DefaultBroker, cl); err != nil { - t.Fatalf("flow register: %v", err) - } - - // Fire the workflow (as a broker event would). - if err := f.Execute(context.Background(), "three tasks then notify owner@acme.com"); err != nil { - t.Fatalf("flow execute: %v", err) - } - - // The flow recorded the agent's reply. - if rs := f.Results(); len(rs) != 1 || rs[0].Reply == "" { - t.Errorf("flow result = %+v, want one result with a reply", rs) - } - - // The agent ran end to end: tasks created, plan stored, comms notified. - if n := taskSvc.count(); n != 3 { - t.Errorf("task service has %d tasks, want 3", n) - } - if recs, err := store.Scope(mem, "agent", "conductor").Read("plan"); err != nil || len(recs) == 0 { - t.Errorf("plan not persisted: err=%v recs=%d", err, len(recs)) - } - if n := notifySvc.count(); n != 1 { - t.Errorf("notify called %d times, want 1 (flow->agent->delegate->comms chain broken)", n) - } -} - -// TestZeroToHeroContract locks the roadmap's second golden path into the -// ordinary Go test contract. It runs the same executable harness used by -// `make harness`: services + agents + flow + plan/delegate, with only the -// LLM replaced by the deterministic mock provider. -func TestZeroToHeroContract(t *testing.T) { - if testing.Short() { - t.Skip("0→hero harness boots an end-to-end system; skipped with -short") - } - if err := runPlanDelegate("mock"); err != nil { - t.Fatalf("0→hero harness: %v", err) - } -} - -func TestPlanDelegateRetriesAfterUnknownDelegateTool(t *testing.T) { - if testing.Short() { - t.Skip("0→hero harness boots an end-to-end system; skipped with -short") - } - if err := runPlanDelegate("mock-unknown-delegate"); err != nil { - t.Fatalf("0→hero harness with unknown delegate retry: %v", err) - } -} - -func TestPlanDelegateIdempotentDuplicateNotifyReplay(t *testing.T) { - if testing.Short() { - t.Skip("0→hero harness boots an end-to-end system; skipped with -short") - } - if err := runPlanDelegate("mock-duplicate-notify"); err != nil { - t.Fatalf("0→hero harness with duplicate notify replay: %v", err) - } -} - -func TestPlanDelegateIdempotentDuplicateDelegateReplay(t *testing.T) { - if testing.Short() { - t.Skip("0→hero harness boots an end-to-end system; skipped with -short") - } - if err := runPlanDelegate("mock-duplicate-delegate"); err != nil { - t.Fatalf("0→hero harness with duplicate delegate replay: %v", err) - } -} - -func TestPlanDelegateRecoversInterruptedMockRunWithoutReplayingTasks(t *testing.T) { - if testing.Short() { - t.Skip("0→hero harness boots an end-to-end system; skipped with -short") - } - if err := runPlanDelegate("mock-interrupt-after-tasks"); err != nil { - t.Fatalf("0→hero harness with interrupted task-complete run: %v", err) - } -} - -func TestPlanDelegateRejectsNestedDelegateToolCallMarkup(t *testing.T) { - if testing.Short() { - t.Skip("0→hero harness boots an end-to-end system; skipped with -short") - } - if err := runPlanDelegate("mock-nested-delegate-markup"); err != nil { - t.Fatalf("0→hero harness with nested delegate markup refusal: %v", err) - } -} - -func TestNotifyServiceDeduplicatesAtlasCloudLaunchReadinessParaphrases(t *testing.T) { - svc := new(NotifyService) - variants := []SendRequest{ - {To: "owner at acme dot com", Message: "The launch plan is ready."}, - {To: "launch owner", Message: "Launch readiness is complete."}, - {To: "Owner ", Message: "The launch plan is finished and the readiness notification was sent."}, - } - for _, req := range variants { - var rsp SendResponse - if err := svc.Send(context.Background(), &req, &rsp); err != nil { - t.Fatalf("Send(%+v): %v", req, err) - } - if !rsp.Sent { - t.Fatalf("Send(%+v) returned sent=false", req) - } - } - if got := svc.count(); got != 1 { - t.Fatalf("notify side effects = %d, want 1 for launch-readiness paraphrase replays", got) - } - if got := svc.duplicateAttempts(); got != len(variants)-1 { - t.Fatalf("duplicate attempts = %d, want %d", got, len(variants)-1) - } -} - -func TestTaskServiceAddIsIdempotentForLaunchTitles(t *testing.T) { - svc := new(TaskService) - for _, title := range []string{"Design", "design task", "Build", "Build launch task", "Ship", "ship readiness"} { - var rsp AddResponse - if err := svc.Add(context.Background(), &AddRequest{Title: title}, &rsp); err != nil { - t.Fatalf("Add(%q): %v", title, err) - } - if rsp.Task == nil { - t.Fatalf("Add(%q) returned nil task", title) - } - } - if got := svc.count(); got != 3 { - t.Fatalf("task count = %d, want 3 after duplicate launch-title replays", got) - } -} - -func TestPlanDelegateExecutionAcceptsDuplicateNotifyReplay(t *testing.T) { - notifySvc := new(NotifyService) - for i := 0; i < 2; i++ { - var rsp SendResponse - if err := notifySvc.Send(context.Background(), &SendRequest{To: "owner@acme.com", Message: "The launch plan is ready"}, &rsp); err != nil { - t.Fatalf("Send attempt %d: %v", i+1, err) - } - } - - done := make(chan error, 1) - done <- nil - if err := waitForPlanDelegateExecution(done, new(TaskService), notifySvc, nil); err != nil { - t.Fatalf("waitForPlanDelegateExecution returned %v, want duplicate replay accepted", err) - } - if got := notifySvc.count(); got != 1 { - t.Fatalf("notify count = %d, want 1 after duplicate replay", got) - } - if got := notifySvc.duplicateAttempts(); got != 1 { - t.Fatalf("duplicate attempts = %d, want 1 recorded replay", got) - } -} - -func TestPlanDelegateExecutionRecoversUnfinishedPlanAfterPartialTaskSideEffect(t *testing.T) { - taskSvc := new(TaskService) - var addRsp AddResponse - if err := taskSvc.Add(context.Background(), &AddRequest{Title: "Design"}, &addRsp); err != nil { - t.Fatalf("Add: %v", err) - } - notifySvc := new(NotifyService) - done := make(chan error, 1) - done <- errors.New("agent run abc has unfinished plan steps: Delegate readiness notification to comms agent") - - recovered := false - err := waitForPlanDelegateExecution(done, taskSvc, notifySvc, func(ctx context.Context) error { - recovered = true - var sendRsp SendResponse - return notifySvc.Send(ctx, &SendRequest{To: "owner@acme.com", Message: "The launch plan is ready"}, &sendRsp) - }) - if err != nil { - t.Fatalf("waitForPlanDelegateExecution returned %v, want partial notify recovery", err) - } - if !recovered { - t.Fatal("missing notify recovery did not run") - } - if got := taskSvc.count(); got != 1 { - t.Fatalf("task count = %d, want completed partial task to stay singular", got) - } - if got := notifySvc.count(); got != 1 { - t.Fatalf("notify count = %d, want recovered notify side effect", got) - } -} - -func TestPlanDelegateExecutionRejectsClaimedCompletionWithoutNotify(t *testing.T) { - notifySvc := new(NotifyService) - done := make(chan error, 1) - done <- nil - - err := waitForPlanDelegateExecution(done, new(TaskService), notifySvc, nil) - if err == nil { - t.Fatal("waitForPlanDelegateExecution returned nil, want missing notify side-effect error") - } - if got := err.Error(); !strings.Contains(got, "without required notify side effect") { - t.Fatalf("error = %q, want missing notify side-effect error", got) - } -} - -type scriptedAgent struct { - replies []func(context.Context, string) (*agent.Response, error) - calls int -} - -func (a *scriptedAgent) Name() string { return "scripted" } -func (a *scriptedAgent) Init(...agent.Option) {} -func (a *scriptedAgent) Options() agent.Options { return agent.Options{} } -func (a *scriptedAgent) Stream(context.Context, string) (model.Stream, error) { return nil, nil } -func (a *scriptedAgent) Run() error { return nil } -func (a *scriptedAgent) Stop() error { return nil } -func (a *scriptedAgent) String() string { return "scripted" } -func (a *scriptedAgent) Ask(ctx context.Context, prompt string) (*agent.Response, error) { - if a.calls >= len(a.replies) { - return &agent.Response{Reply: "done"}, nil - } - reply := a.replies[a.calls] - a.calls++ - return reply(ctx, prompt) -} - -type failingAgent struct { - err error -} - -func (a failingAgent) Name() string { return "failing" } -func (a failingAgent) Init(...agent.Option) {} -func (a failingAgent) Options() agent.Options { return agent.Options{} } -func (a failingAgent) Ask(context.Context, string) (*agent.Response, error) { return nil, a.err } -func (a failingAgent) Stream(context.Context, string) (model.Stream, error) { return nil, a.err } -func (a failingAgent) Run() error { return nil } -func (a failingAgent) Stop() error { return nil } -func (a failingAgent) String() string { return "failing" } - -func TestRequireConductorPlanRecoversAfterCompletedSideEffects(t *testing.T) { - mem := store.NewMemoryStore() - ag := &scriptedAgent{replies: []func(context.Context, string) (*agent.Response, error){ - func(ctx context.Context, prompt string) (*agent.Response, error) { - if !strings.Contains(prompt, "built-in plan tool") || !strings.Contains(prompt, "Do not call task or notify tools") { - return nil, errors.New("missing scoped plan recovery prompt") - } - if err := store.Scope(mem, "agent", "conductor").Write(&store.Record{Key: "plan", Value: []byte(`{"steps":[{"task":"Design launch task","status":"done"}]}`)}); err != nil { - return nil, err - } - return &agent.Response{Reply: "Plan persisted."}, nil - }, - }} - - if err := requireConductorPlan(context.Background(), mem, ag); err != nil { - t.Fatalf("requireConductorPlan returned %v, want recovered plan", err) - } - if ag.calls != 1 { - t.Fatalf("conductor calls = %d, want one plan recovery prompt", ag.calls) - } -} - -func TestRequireConductorPlanFailureNamesScopedRecord(t *testing.T) { - err := requireConductorPlan(context.Background(), store.NewMemoryStore(), &scriptedAgent{replies: []func(context.Context, string) (*agent.Response, error){ - func(context.Context, string) (*agent.Response, error) { - return &agent.Response{Reply: "Done without plan."}, nil - }, - }}) - if err == nil { - t.Fatal("requireConductorPlan returned nil, want missing plan diagnostic") - } - for _, want := range []string{"agent/conductor/plan", "without calling the built-in plan tool"} { - if got := err.Error(); !strings.Contains(got, want) { - t.Fatalf("error = %q, want %q", got, want) - } - } -} - -func TestRequirePersistedPlanBeforeConductorActionsBlocksSideEffects(t *testing.T) { - mem := store.NewMemoryStore() - called := false - wrapped := requirePersistedPlanBeforeConductorActions(mem)(func(context.Context, model.ToolCall) model.ToolResult { - called = true - return model.ToolResult{ID: "call-1", Content: `{"ok":true}`} - }) - - res := wrapped(context.Background(), model.ToolCall{ID: "call-1", Name: "task.Add"}) - if called { - t.Fatal("side-effecting tool ran before persisted plan") - } - if res.Refused != model.RefusedApproval { - t.Fatalf("Refused = %q, want %q", res.Refused, model.RefusedApproval) - } - if !strings.Contains(res.Content, "built-in plan tool") { - t.Fatalf("Content = %q, want plan-first steering message", res.Content) - } -} - -func TestRequirePersistedPlanBeforeConductorActionsAllowsPlanAndPlannedActions(t *testing.T) { - mem := store.NewMemoryStore() - var calls []string - wrapped := requirePersistedPlanBeforeConductorActions(mem)(func(ctx context.Context, call model.ToolCall) model.ToolResult { - calls = append(calls, call.Name) - if call.Name == "plan" { - if err := store.Scope(mem, "agent", "conductor").Write(&store.Record{Key: "plan", Value: []byte(`{"steps":[{"task":"Design","status":"pending"}]}`)}); err != nil { - t.Fatalf("write plan: %v", err) - } - } - return model.ToolResult{ID: call.ID, Content: `{"ok":true}`} - }) - - if res := wrapped(context.Background(), model.ToolCall{ID: "call-1", Name: "plan"}); res.Refused != "" { - t.Fatalf("plan Refused = %q, want allowed", res.Refused) - } - if res := wrapped(context.Background(), model.ToolCall{ID: "call-2", Name: "task.Add"}); res.Refused != "" { - t.Fatalf("planned action Refused = %q, want allowed", res.Refused) - } - if want := []string{"plan", "task.Add"}; !reflect.DeepEqual(calls, want) { - t.Fatalf("calls = %v, want %v", calls, want) - } -} - -func TestPlanDelegateConductorRetriesAfterPlanOnlySuccess(t *testing.T) { - taskSvc := new(TaskService) - notifySvc := new(NotifyService) - ag := &scriptedAgent{replies: []func(context.Context, string) (*agent.Response, error){ - func(context.Context, string) (*agent.Response, error) { - return &agent.Response{Reply: "Plan saved."}, nil - }, - func(ctx context.Context, prompt string) (*agent.Response, error) { - if !strings.Contains(prompt, "Execute the persisted plan") { - return nil, errors.New("missing explicit side-effect recovery prompt") - } - for _, title := range []string{"Design", "Build", "Ship"} { - var rsp AddResponse - if err := taskSvc.Add(ctx, &AddRequest{Title: title}, &rsp); err != nil { - return nil, err - } - } - return &agent.Response{Reply: "Tasks created."}, nil - }, - }} - - step := planDelegateConductorStep(ag, taskSvc, notifySvc) - if _, err := step(context.Background(), flow.State{}); err != nil { - t.Fatalf("planDelegateConductorStep returned %v, want plan-only retry success", err) - } - if ag.calls != 2 { - t.Fatalf("conductor calls = %d, want initial plan-only call plus one side-effect retry", ag.calls) - } - if got := taskSvc.count(); got != 3 { - t.Fatalf("task count = %d, want recovered Design/Build/Ship side effects", got) - } -} - -func TestPlanDelegateConductorFailsBeforeNotifyGateAfterPlanOnlyRetryMiss(t *testing.T) { - step := planDelegateConductorStep(&scriptedAgent{replies: []func(context.Context, string) (*agent.Response, error){ - func(context.Context, string) (*agent.Response, error) { - return &agent.Response{Reply: "Plan saved."}, nil - }, - func(context.Context, string) (*agent.Response, error) { - return &agent.Response{Reply: "Still planning."}, nil - }, - }}, new(TaskService), new(NotifyService)) - - _, err := step(context.Background(), flow.State{}) - if err == nil { - t.Fatal("planDelegateConductorStep returned nil, want pre-notify-gate task side-effect error") - } - for _, want := range []string{"before task side effects completed", "tasks=0/3", "task Add for Design, Build, and Ship"} { - if got := err.Error(); !strings.Contains(got, want) { - t.Fatalf("error = %q, want %q", got, want) - } - } -} - -func TestPlanDelegateConductorAllowsNotifyRecoveryAfterUnfinishedDelegation(t *testing.T) { - taskSvc := new(TaskService) - for _, title := range []string{"Design", "Build", "Ship"} { - var rsp AddResponse - if err := taskSvc.Add(context.Background(), &AddRequest{Title: title}, &rsp); err != nil { - t.Fatalf("Add(%q): %v", title, err) - } - } - notifySvc := new(NotifyService) - step := planDelegateConductorStep(failingAgent{err: errors.New("agent run abc has unfinished plan steps: Delegate readiness notification to comms agent")}, taskSvc, notifySvc) - if _, err := step(context.Background(), flow.State{}); err != nil { - t.Fatalf("planDelegateConductorStep returned %v, want require-notify recovery to run", err) - } -} - -func TestPlanDelegateConductorKeepsUnfinishedTaskFailureActionable(t *testing.T) { - step := planDelegateConductorStep(failingAgent{err: errors.New("agent run abc has unfinished plan steps: Create Build task")}, new(TaskService), new(NotifyService)) - err := func() error { _, err := step(context.Background(), flow.State{}); return err }() - if err == nil { - t.Fatal("planDelegateConductorStep returned nil, want unfinished task error") - } - if got := err.Error(); !strings.Contains(got, "Create Build task") { - t.Fatalf("error = %q, want original unfinished task detail", got) - } -} - -func TestPlanDelegateExecutionRecoversMissingNotifyOnce(t *testing.T) { - taskSvc := new(TaskService) - for _, title := range []string{"Design", "Build", "Ship"} { - var rsp AddResponse - if err := taskSvc.Add(context.Background(), &AddRequest{Title: title}, &rsp); err != nil { - t.Fatalf("Add(%q): %v", title, err) - } - } - notifySvc := new(NotifyService) - - recovered := false - _, err := requireDelegatedNotifyStep(taskSvc, notifySvc, func(ctx context.Context) error { - recovered = true - var rsp SendResponse - return notifySvc.Send(ctx, &SendRequest{To: "owner@acme.com", Message: "The launch plan is ready"}, &rsp) - })(context.Background(), flow.State{}) - if err != nil { - t.Fatalf("waitForPlanDelegateExecution returned %v, want recovery success", err) - } - if !recovered { - t.Fatal("missing notify recovery was not invoked") - } - if got := notifySvc.count(); got != 1 { - t.Fatalf("notify count = %d, want 1 after recovery", got) - } -} - -func TestPlanDelegateExecutionWaitsForInFlightNotifyAfterFlowCompletion(t *testing.T) { - taskSvc := new(TaskService) - for _, title := range []string{"Design", "Build", "Ship"} { - var rsp AddResponse - if err := taskSvc.Add(context.Background(), &AddRequest{Title: title}, &rsp); err != nil { - t.Fatalf("Add(%q): %v", title, err) - } - } - notifySvc := new(NotifyService) - - go func() { - time.Sleep(100 * time.Millisecond) - var rsp SendResponse - _ = notifySvc.Send(context.Background(), &SendRequest{To: "owner@acme.com", Message: "The launch plan is ready"}, &rsp) - }() - - recovered := false - _, err := requireDelegatedNotifyStep(taskSvc, notifySvc, func(ctx context.Context) error { - recovered = true - var rsp SendResponse - return notifySvc.Send(ctx, &SendRequest{To: "owner@acme.com", Message: "The launch plan is ready"}, &rsp) - })(context.Background(), flow.State{}) - if err != nil { - t.Fatalf("waitForPlanDelegateExecution returned %v, want in-flight notify success", err) - } - if recovered { - t.Fatal("missing notify recovery ran while delegated notify was still in flight") - } - if got := taskSvc.count(); got != 3 { - t.Fatalf("task count = %d, want 3 after in-flight notify settles", got) - } - if got := notifySvc.count(); got != 1 { - t.Fatalf("notify count = %d, want 1 after in-flight notify settles", got) - } - if got := notifySvc.duplicateAttempts(); got != 0 { - t.Fatalf("duplicate notify attempts = %d, want 0", got) - } -} - -func TestPlanDelegateRecoveryWaitsForRecoveredNotifySideEffect(t *testing.T) { - taskSvc := new(TaskService) - for _, title := range []string{"Design", "Build", "Ship"} { - var rsp AddResponse - if err := taskSvc.Add(context.Background(), &AddRequest{Title: title}, &rsp); err != nil { - t.Fatalf("Add(%q): %v", title, err) - } - } - notifySvc := new(NotifyService) - - recovered := false - _, err := requireDelegatedNotifyStep(taskSvc, notifySvc, func(ctx context.Context) error { - recovered = true - go func() { - time.Sleep(100 * time.Millisecond) - var rsp SendResponse - _ = notifySvc.Send(ctx, &SendRequest{To: "owner@acme.com", Message: "The launch plan is ready"}, &rsp) - }() - return nil - })(context.Background(), flow.State{}) - if err != nil { - t.Fatalf("requireDelegatedNotifyStep returned %v, want delayed recovery success", err) - } - if !recovered { - t.Fatal("missing notify recovery did not run") - } - if got := notifySvc.count(); got != 1 { - t.Fatalf("notify count = %d, want recovered notify side effect", got) - } -} - -func TestPlanDelegateExecutionAcceptsClientTimeoutAfterSideEffects(t *testing.T) { - taskSvc := new(TaskService) - for _, title := range []string{"Design", "Build", "Ship"} { - var rsp AddResponse - if err := taskSvc.Add(context.Background(), &AddRequest{Title: title}, &rsp); err != nil { - t.Fatalf("Add(%q): %v", title, err) - } - } - notifySvc := new(NotifyService) - var rsp SendResponse - if err := notifySvc.Send(context.Background(), &SendRequest{To: "owner@acme.com", Message: "The launch plan is ready"}, &rsp); err != nil { - t.Fatalf("Send: %v", err) - } - - done := make(chan error, 1) - done <- errors.New(`{"id":"go.micro.client","code":408,"detail":"","status":"Request Timeout"}`) - - if err := waitForPlanDelegateExecution(done, taskSvc, notifySvc, nil); err != nil { - t.Fatalf("waitForPlanDelegateExecution returned %v, want completed side effects to satisfy client timeout", err) - } -} - -func TestPlanDelegateExecutionAcceptsApprovalPauseAfterSideEffects(t *testing.T) { - taskSvc := new(TaskService) - for _, title := range []string{"Design", "Build", "Ship"} { - var rsp AddResponse - if err := taskSvc.Add(context.Background(), &AddRequest{Title: title}, &rsp); err != nil { - t.Fatalf("Add(%q): %v", title, err) - } - } - notifySvc := new(NotifyService) - var rsp SendResponse - if err := notifySvc.Send(context.Background(), &SendRequest{To: "owner@acme.com", Message: "The launch plan is ready"}, &rsp); err != nil { - t.Fatalf("Send: %v", err) - } - - done := make(chan error, 1) - done <- errors.New("agent run abc paused for approval: The comms agent is repeatedly timing out (408 errors) while retrying the launch-readiness notification") - - if err := waitForPlanDelegateExecution(done, taskSvc, notifySvc, nil); err != nil { - t.Fatalf("waitForPlanDelegateExecution returned %v, want completed side effects to satisfy approval pause", err) - } -} - -func TestPlanDelegateExecutionClassifiesClientTimeoutBeforeSideEffects(t *testing.T) { - done := make(chan error, 1) - done <- errors.New(`{"id":"go.micro.client","code":408,"detail":"","status":"Request Timeout"}`) - - err := waitForPlanDelegateExecution(done, new(TaskService), new(NotifyService), nil) - if err == nil { - t.Fatal("waitForPlanDelegateExecution returned nil, want timeout before side effects to fail") - } - for _, want := range []string{ - "provider latency/outage during plan-delegate", - "tasks=0/3 notify=0/1", - "retry live provider or inspect provider logs", - "Request Timeout", - } { - if got := err.Error(); !strings.Contains(got, want) { - t.Fatalf("error = %q, want %q", got, want) - } - } -} - -func TestPlanDelegateExecutionClassifiesPartialClientTimeout(t *testing.T) { - taskSvc := new(TaskService) - for _, title := range []string{"Design", "Build", "Ship"} { - var rsp AddResponse - if err := taskSvc.Add(context.Background(), &AddRequest{Title: title}, &rsp); err != nil { - t.Fatalf("Add(%q): %v", title, err) - } - } - done := make(chan error, 1) - done <- errors.New(`{"id":"go.micro.client","code":408,"detail":"","status":"Request Timeout"}`) - - err := waitForPlanDelegateExecution(done, taskSvc, new(NotifyService), nil) - if err == nil { - t.Fatal("waitForPlanDelegateExecution returned nil, want timeout before notify to fail") - } - if got := err.Error(); !strings.Contains(got, "tasks=3/3 notify=0/1") { - t.Fatalf("error = %q, want partial side-effect counts", got) - } -} - -func TestNotifyServiceSendIsIdempotentForDuplicateDelivery(t *testing.T) { - svc := new(NotifyService) - messages := []string{ - "The launch plan is ready", - "The launch plan is ready.", - "Launch readiness: the plan is ready!", - } - for i, message := range messages { - var rsp SendResponse - to := "owner@acme.com" - if i == len(messages)-1 { - to = "owner" - } - if err := svc.Send(context.Background(), &SendRequest{To: to, Message: message}, &rsp); err != nil { - t.Fatalf("Send attempt %d: %v", i+1, err) - } - if !rsp.Sent { - t.Fatalf("Send attempt %d reported Sent=false", i+1) - } - } - if got := svc.count(); got != 1 { - t.Fatalf("notify count = %d, want 1 after duplicate delivery replays", got) - } - if got := svc.duplicateAttempts(); got != len(messages)-1 { - t.Fatalf("duplicate notify attempts = %d, want %d", got, len(messages)-1) - } -} - -func TestNotifyServiceCollapsesProviderReadinessParaphrases(t *testing.T) { - svc := new(NotifyService) - requests := []SendRequest{ - {To: "owner@acme.com", Message: "The launch plan is ready"}, - {To: "owner @ acme.com", Message: "Launch plan ready."}, - {To: "owner at acme dot com", Message: "The launch plan is ready."}, - {To: "launch owner", Message: "The launch readiness plan is prepared."}, - {To: "plan owner", Message: "Launch plan is complete!"}, - } - for i, req := range requests { - var rsp SendResponse - if err := svc.Send(context.Background(), &req, &rsp); err != nil { - t.Fatalf("Send attempt %d: %v", i+1, err) - } - if !rsp.Sent { - t.Fatalf("Send attempt %d reported Sent=false", i+1) - } - } - if got := svc.count(); got != 1 { - t.Fatalf("notify count = %d, want 1 after provider paraphrase replays", got) - } - if got := svc.duplicateAttempts(); got != len(requests)-1 { - t.Fatalf("duplicate notify attempts = %d, want %d", got, len(requests)-1) - } -} diff --git a/internal/harness/provider-conformance/README.md b/internal/harness/provider-conformance/README.md index 659aa93397..bbabc8cd67 100644 --- a/internal/harness/provider-conformance/README.md +++ b/internal/harness/provider-conformance/README.md @@ -1,6 +1,6 @@ # Provider conformance -This harness keeps the services → agents → workflows lifecycle honest across the +This harness keeps the services → agents lifecycle honest across the supported AI providers. It runs the same end-to-end scenarios against each configured provider and treats missing provider keys as an explicit skip, so the suite is safe for local development, forks, and scheduled CI. @@ -11,10 +11,6 @@ suite is safe for local development, forks, and scheduled CI. agent test and the harnesses in `internal/harness`: - `agent` — provider tool-call conformance through `agent.Ask`, including run metadata propagation. -- `universe` — service discovery plus agent tool calls over the real runtime. -- `agent-flow` — a workflow event that drives an agent to call services. -- `plan-delegate` — plan persistence plus agent-to-agent delegation and service - calls. - `a2a-stream-fallback` — A2A `message/stream` through the gateway, including fallback from unsupported provider streaming to the tool-calling `Ask` path while preserving run metadata. @@ -22,7 +18,7 @@ agent test and the harnesses in `internal/harness`: The command also emits the registered provider capability matrix so the run shows which providers advertise model, image, video, and streaming support. Console output and summary artifacts label each harness with the phase it is proving (for example, -model call + tool call, workflow event + tool call, or streaming fallback + tool +model call + tool call, streaming fallback + tool call), so provider failures identify the failed lifecycle phase instead of only the provider name. @@ -76,7 +72,7 @@ manual dispatch can narrow `providers` or `harnesses`, and can set missing; scheduled runs keep the safe default and report missing keys as skips. That job: -1. runs the same `agent`, `universe`, `agent-flow`, `plan-delegate`, and `a2a-stream-fallback` harness list, +1. runs the same `agent`, `a2a-streaming`, and `a2a-stream-fallback` harness list, 2. reads the provider keys from repository secrets, 3. skips providers whose secrets are absent, 4. fails when any configured provider fails a harness, and diff --git a/internal/harness/provider-conformance/main.go b/internal/harness/provider-conformance/main.go index 6661717cbd..eddb9116fc 100644 --- a/internal/harness/provider-conformance/main.go +++ b/internal/harness/provider-conformance/main.go @@ -36,13 +36,10 @@ import ( _ "go-micro.dev/v6/model/together" ) -const defaultHarnesses = "agent,universe,agent-flow,plan-delegate,a2a-streaming,a2a-stream-fallback" +const defaultHarnesses = "agent,a2a-streaming,a2a-stream-fallback" var harnessPhases = map[string]string{ "agent": "model call + tool call", - "universe": "service discovery + tool call", - "agent-flow": "workflow event + tool call", - "plan-delegate": "plan persistence + delegation + tool call", "a2a-streaming": "A2A streaming + tool call", "a2a-stream-fallback": "streaming fallback + tool call", } diff --git a/internal/harness/provider-conformance/main_test.go b/internal/harness/provider-conformance/main_test.go index 1c3a23f9ea..0ebda8681e 100644 --- a/internal/harness/provider-conformance/main_test.go +++ b/internal/harness/provider-conformance/main_test.go @@ -27,11 +27,11 @@ func TestValidateSelectionRejectsUnknownProvider(t *testing.T) { } func TestValidateSelectionRejectsUnsafeHarnessName(t *testing.T) { - err := validateSelection([]string{"mock"}, []string{"../agent-flow"}) + err := validateSelection([]string{"mock"}, []string{"../a2a-stream-fallback"}) if err == nil { t.Fatal("validateSelection returned nil for unsafe harness name") } - if !strings.Contains(err.Error(), `invalid harness name "../agent-flow"`) { + if !strings.Contains(err.Error(), `invalid harness name "../a2a-stream-fallback"`) { t.Fatalf("validateSelection error = %q, want invalid harness message", err) } } @@ -78,14 +78,14 @@ func TestCapabilityMatrixHasRegisteredProviders(t *testing.T) { } func TestMissingKeyResultsReportsEachHarness(t *testing.T) { - results := missingKeyResults("openai", []string{"agent", "plan-delegate"}, statusSkipped, "set OPENAI_API_KEY") + results := missingKeyResults("openai", []string{"agent", "a2a-streaming"}, statusSkipped, "set OPENAI_API_KEY") if len(results) != 2 { t.Fatalf("missingKeyResults returned %d results, want 2", len(results)) } wants := []conformanceResult{ {Provider: "openai", Harness: "agent", Phase: harnessPhase("agent"), Status: statusSkipped, Error: "set OPENAI_API_KEY"}, - {Provider: "openai", Harness: "plan-delegate", Phase: harnessPhase("plan-delegate"), Status: statusSkipped, Error: "set OPENAI_API_KEY"}, + {Provider: "openai", Harness: "a2a-streaming", Phase: harnessPhase("a2a-streaming"), Status: statusSkipped, Error: "set OPENAI_API_KEY"}, } for i, want := range wants { if results[i] != want { @@ -125,7 +125,7 @@ func TestWriteSummaryMarkdown(t *testing.T) { summary := conformanceSummary{ Capabilities: []model.CapabilityRow{{Provider: "mock", Capabilities: model.Capabilities{Model: true}}}, Results: []conformanceResult{ - {Provider: "mock", Harness: "agent-flow", Phase: harnessPhase("agent-flow"), Status: statusPassed}, + {Provider: "mock", Harness: "a2a-stream-fallback", Phase: harnessPhase("a2a-stream-fallback"), Status: statusPassed}, {Provider: "live", Status: statusSkipped, Error: "missing | key"}, }, Passed: 1, @@ -146,7 +146,7 @@ func TestWriteSummaryMarkdown(t *testing.T) { "Providers: —.", "Harnesses: —.", "| mock | ✅ | — | — | — |", - "| mock | agent-flow | workflow event + tool call | passed | — |", + "| mock | a2a-stream-fallback | streaming fallback + tool call | passed | — |", "| live | — | — | skipped | missing \\| key |", } { if !strings.Contains(got, want) { diff --git a/internal/harness/recovery/main.go b/internal/harness/recovery/main.go deleted file mode 100644 index 6bede2b03f..0000000000 --- a/internal/harness/recovery/main.go +++ /dev/null @@ -1,245 +0,0 @@ -// Command recovery is the provider-free restart and failure-injection release -// gate for durable flows. It deliberately replaces the Flow value between -// attempts while retaining the checkpoint, which models a host restart. -package main - -import ( - "context" - "errors" - "fmt" - "sort" - "sync" - - "go-micro.dev/v6/flow" - "go-micro.dev/v6/model" -) - -func main() { - if err := run(context.Background()); err != nil { - panic(err) - } - fmt.Println("recovery fixture: PASS") -} - -func run(ctx context.Context) error { - cp := newCheckpoint() - effects := newEffects() - var reserveCalls, chargeCalls, finalCalls int - var callsMu sync.Mutex - crashAfterCharge := true - - steps := func(concurrentFinal bool) []flow.Step { - return []flow.Step{ - {Name: "reserve", Run: func(_ context.Context, in flow.State) (flow.State, error) { - callsMu.Lock() - reserveCalls++ - callsMu.Unlock() - effects.apply("reserve:order-42") - return in, nil - }}, - {Name: "charge", Run: func(_ context.Context, in flow.State) (flow.State, error) { - callsMu.Lock() - chargeCalls++ - callsMu.Unlock() - effects.apply("charge:order-42") - if crashAfterCharge { - crashAfterCharge = false - return in, errors.New("injected crash after external charge, before checkpoint") - } - return in, nil - }}, - {Name: "approval", Run: flow.Await("ship", "approve shipment")}, - {Name: "finalize", Run: func(_ context.Context, in flow.State) (flow.State, error) { - callsMu.Lock() - finalCalls++ - calls := finalCalls - callsMu.Unlock() - effects.apply("finalize:order-42") - if concurrentFinal { - finalBarrier.arrive(calls) - } - return in, nil - }}, - } - } - - root := model.WithRunInfo(ctx, model.RunInfo{RunID: "request-7", Dispatch: "direct"}) - host1 := flow.New("recovery-gate", flow.Steps(steps(false)...), flow.WithCheckpoint(cp)) - if err := host1.Execute(root, `{"order":"42"}`); err == nil { - return errors.New("injected ambiguous charge did not fail") - } - runs, _ := cp.List(ctx) - if len(runs) != 1 || runs[0].State.Stage != "charge" || runs[0].ParentID != "request-7" { - return fmt.Errorf("failed checkpoint or lineage was not preserved: %+v", runs) - } - runID := runs[0].ID - - // A new Flow value represents a replacement host using the durable backend. - // The charge is reconciled by its idempotency key when the ambiguous step is - // retried; the completed reserve step must not run again. - host2 := flow.New("recovery-gate", flow.Steps(steps(false)...), flow.WithCheckpoint(cp)) - if err := host2.Resume(ctx, runID); err != nil { - return fmt.Errorf("restart resume: %w", err) - } - waiting, _ := host2.Waiting(ctx) - pending, _ := host2.Pending(ctx) - if len(waiting) != 1 || len(pending) != 0 || waiting[0].ParentID != "request-7" { - return fmt.Errorf("waiting run was not kept paused with its lineage") - } - if reserveCalls != 1 || chargeCalls != 2 || effects.count("charge:order-42") != 1 { - return fmt.Errorf("restart replay contract failed: reserve=%d charge calls=%d effects=%d", reserveCalls, chargeCalls, effects.count("charge:order-42")) - } - - // Two deliveries race to approve the same saved run. The checkpoint API does - // not promise a cross-host lease in v6, so both may reach the operation. The - // stable business idempotency key is the required safety boundary. - finalBarrier = newBarrier(2) - cp.synchronizeLoads(runID, 2) - host3 := flow.New("recovery-gate", flow.Steps(steps(true)...), flow.WithCheckpoint(cp)) - errCh := make(chan error, 2) - for range 2 { - go func() { errCh <- host3.ResumeWith(ctx, runID, "approved") }() - } - for range 2 { - if err := <-errCh; err != nil { - return fmt.Errorf("concurrent duplicate resume: %w", err) - } - } - completed, ok, _ := cp.Load(ctx, runID) - if !ok || completed.Status != "done" || completed.ParentID != "request-7" { - return fmt.Errorf("completed run lost status or lineage: %+v", completed) - } - if finalCalls != 2 || effects.count("finalize:order-42") != 1 { - return fmt.Errorf("idempotent final operation duplicated: calls=%d effects=%d", finalCalls, effects.count("finalize:order-42")) - } - - // Exhaustion is a failed outcome, never a successful completion. - exhaustCP := newCheckpoint() - attempts := 0 - exhaust := flow.New("exhaustion-gate", - flow.Steps(flow.Step{Name: "bounded", Run: func(_ context.Context, in flow.State) (flow.State, error) { - attempts++ - return in, errors.New("dependency unavailable") - }}), - flow.Retry(1), flow.WithCheckpoint(exhaustCP), - ) - if err := exhaust.Execute(ctx, "work"); err == nil { - return errors.New("exhausted retry budget was reported as success") - } - exhausted, _ := exhaustCP.List(ctx) - if attempts != 2 || len(exhausted) != 1 || exhausted[0].Status != "failed" || exhausted[0].Steps[0].Attempts != 2 { - return fmt.Errorf("retry exhaustion was not recorded: attempts=%d runs=%+v", attempts, exhausted) - } - return nil -} - -type memoryCheckpoint struct { - mu sync.Mutex - runs map[string]flow.Run - loadRunID string - loadBarrier *barrier -} - -func newCheckpoint() *memoryCheckpoint { return &memoryCheckpoint{runs: make(map[string]flow.Run)} } - -func (c *memoryCheckpoint) Save(_ context.Context, run flow.Run) error { - c.mu.Lock() - defer c.mu.Unlock() - c.runs[run.ID] = cloneRun(run) - return nil -} - -func (c *memoryCheckpoint) Load(_ context.Context, id string) (flow.Run, bool, error) { - c.mu.Lock() - run, ok := c.runs[id] - b := c.loadBarrier - if id != c.loadRunID { - b = nil - } - c.mu.Unlock() - if b != nil { - b.arrive(0) - } - return cloneRun(run), ok, nil -} - -// synchronizeLoads makes the duplicate-delivery scenario deterministic: both -// simulated hosts observe the same waiting record before either advances it. -// This is fixture coordination, not a lease supplied by Checkpoint. -func (c *memoryCheckpoint) synchronizeLoads(id string, n int) { - c.mu.Lock() - defer c.mu.Unlock() - c.loadRunID = id - c.loadBarrier = newBarrier(n) -} - -func (c *memoryCheckpoint) Delete(_ context.Context, id string) error { - c.mu.Lock() - defer c.mu.Unlock() - delete(c.runs, id) - return nil -} - -func (c *memoryCheckpoint) List(_ context.Context) ([]flow.Run, error) { - c.mu.Lock() - defer c.mu.Unlock() - runs := make([]flow.Run, 0, len(c.runs)) - for _, run := range c.runs { - runs = append(runs, cloneRun(run)) - } - sort.Slice(runs, func(i, j int) bool { return runs[i].ID < runs[j].ID }) - return runs, nil -} - -func cloneRun(run flow.Run) flow.Run { - run.State.Data = append([]byte(nil), run.State.Data...) - run.Steps = append([]flow.StepRecord(nil), run.Steps...) - if run.Await != nil { - await := *run.Await - run.Await = &await - } - return run -} - -type effectLedger struct { - mu sync.Mutex - counts map[string]int -} - -func newEffects() *effectLedger { return &effectLedger{counts: make(map[string]int)} } - -func (l *effectLedger) apply(key string) { - l.mu.Lock() - defer l.mu.Unlock() - if l.counts[key] == 0 { - l.counts[key] = 1 - } -} - -func (l *effectLedger) count(key string) int { - l.mu.Lock() - defer l.mu.Unlock() - return l.counts[key] -} - -type barrier struct { - mu sync.Mutex - want int - arrived int - release chan struct{} -} - -var finalBarrier = newBarrier(1) - -func newBarrier(want int) *barrier { return &barrier{want: want, release: make(chan struct{})} } - -func (b *barrier) arrive(_ int) { - b.mu.Lock() - b.arrived++ - if b.arrived == b.want { - close(b.release) - } - release := b.release - b.mu.Unlock() - <-release -} diff --git a/internal/harness/universe/main.go b/internal/harness/universe/main.go deleted file mode 100644 index 435edeb40c..0000000000 --- a/internal/harness/universe/main.go +++ /dev/null @@ -1,601 +0,0 @@ -// Universe harness — a mini end-to-end world, spun up and shut down. -// -// It boots a small but real go-micro system in one process and drives a -// realistic scenario across all the moving parts: -// -// - four real services (inventory, payment, orders, notify) over RPC; -// - a DURABLE FLOW "checkout" with ordered, checkpointed steps that -// reserves, charges, confirms, then hands off to an agent; -// - a CRASH + RESUME: the payment dependency fails on first contact, the -// run is checkpointed at that step, and on resume it continues without -// re-running the steps that already completed; -// - an AGENT "concierge" with guardrails and a tool-execution wrapper, -// reached by the flow over RPC, that sends the welcome notification; -// - SCOPED STATE: the flow's runs and the agent's history land in their -// own store tables. -// -// Everything is real — registry, RPC, broker, store, the flow engine, the -// agent loop. Only the LLM is mocked, so it runs free and deterministically -// in CI. Pass -provider anthropic (with a key) to run it against a live -// model. It exits non-zero if any assertion fails, so it doubles as an -// end-to-end test. -// -// Run: -// -// go run ./internal/harness/universe -package main - -import ( - "context" - "encoding/json" - "flag" - "fmt" - "net/http/httptest" - "os" - "strings" - "sync" - "sync/atomic" - "time" - - "go-micro.dev/v6/agent" - "go-micro.dev/v6/broker" - "go-micro.dev/v6/client" - codecbytes "go-micro.dev/v6/codec/bytes" - "go-micro.dev/v6/flow" - "go-micro.dev/v6/gateway/a2a" - "go-micro.dev/v6/internal/harness/harnessutil" - "go-micro.dev/v6/model" - "go-micro.dev/v6/registry" - "go-micro.dev/v6/service" - "go-micro.dev/v6/store" -) - -// --------------------------------------------------------------------------- -// services -// --------------------------------------------------------------------------- - -type Order struct { - Order string `json:"order" description:"Order id (required)"` - Reserved bool `json:"reserved,omitempty"` - Charged bool `json:"charged,omitempty"` - Confirmed bool `json:"confirmed,omitempty"` -} - -type Inventory struct{ reserves int64 } - -// Reserve holds stock for an order. -// @example {"order": "order-1"} -func (s *Inventory) Reserve(_ context.Context, req *Order, rsp *Order) error { - atomic.AddInt64(&s.reserves, 1) - fmt.Printf(" \033[32m[inventory]\033[0m reserved %s\n", req.Order) - *rsp = *req - rsp.Reserved = true - return nil -} - -type Payment struct{ attempts int64 } - -// Charge captures payment for an order. It fails the first time it is -// called (a transient outage) and succeeds afterwards — so the checkout -// flow crashes mid-run the first time and recovers on resume. -// @example {"order": "order-1"} -func (s *Payment) Charge(_ context.Context, req *Order, rsp *Order) error { - n := atomic.AddInt64(&s.attempts, 1) - if n == 1 { - fmt.Printf(" \033[31m[payment]\033[0m gateway timeout (attempt %d)\n", n) - return fmt.Errorf("payment gateway timeout") - } - fmt.Printf(" \033[32m[payment]\033[0m charged %s (attempt %d)\n", req.Order, n) - *rsp = *req - rsp.Charged = true - return nil -} - -type Orders struct{ confirms int64 } - -// Confirm finalizes an order. -// @example {"order": "order-1"} -func (s *Orders) Confirm(_ context.Context, req *Order, rsp *Order) error { - atomic.AddInt64(&s.confirms, 1) - fmt.Printf(" \033[32m[orders]\033[0m confirmed %s\n", req.Order) - *rsp = *req - rsp.Confirmed = true - return nil -} - -type SendRequest struct { - To string `json:"to" description:"Recipient (required)"` - Message string `json:"message" description:"Message body (required)"` -} -type SendResponse struct { - Sent bool `json:"sent"` -} - -type Notify struct { - mu sync.Mutex - sent int64 - seen map[string]struct{} - lastRejected *SendRequest -} - -// Send delivers a notification. -// @example {"to": "buyer@acme.com", "message": "Your order is confirmed"} -func (s *Notify) Send(_ context.Context, req *SendRequest, rsp *SendResponse) error { - if !isBuyerNotification(req) { - to, message := "", "" - if req != nil { - to, message = req.To, req.Message - } - s.recordRejected(to, message) - fmt.Printf(" \033[35m[notify]\033[0m 📨 ignored non-buyer notification to=%s %q\n", to, message) - rsp.Sent = false - return nil - } - - s.recordRejected("", "") - - keys := notificationDedupeKeys(req) - s.mu.Lock() - if s.seen == nil { - s.seen = make(map[string]struct{}) - } - for _, key := range keys { - if _, ok := s.seen[key]; ok { - s.mu.Unlock() - fmt.Printf(" \033[35m[notify]\033[0m 📨 duplicate suppressed to=%s %q\n", req.To, req.Message) - rsp.Sent = true - return nil - } - } - for _, key := range keys { - s.seen[key] = struct{}{} - } - s.mu.Unlock() - - atomic.AddInt64(&s.sent, 1) - fmt.Printf(" \033[35m[notify]\033[0m 📨 to=%s %q\n", req.To, req.Message) - rsp.Sent = true - return nil -} - -func isBuyerNotification(req *SendRequest) bool { - if req == nil { - return false - } - return canonicalBuyerRecipient(req.To) != "" -} - -func (s *Notify) recordRejected(to, message string) { - s.mu.Lock() - defer s.mu.Unlock() - if strings.TrimSpace(to) == "" && strings.TrimSpace(message) == "" { - s.lastRejected = nil - return - } - s.lastRejected = &SendRequest{To: to, Message: message} -} - -func (s *Notify) rejectedSummary() string { - s.mu.Lock() - defer s.mu.Unlock() - if s.lastRejected == nil { - return "no rejected notify call observed" - } - return fmt.Sprintf("last notify args to=%q message=%q", s.lastRejected.To, s.lastRejected.Message) -} - -func canonicalBuyerRecipient(to string) string { - recipient := strings.ToLower(strings.TrimSpace(to)) - switch recipient { - case "buyer", "buyer@acme.com": - return "buyer@acme.com" - } - if strings.HasPrefix(recipient, "buyer-of-order-") && len(recipient) > len("buyer-of-order-") { - return "buyer@acme.com" - } - for _, field := range strings.FieldsFunc(recipient, func(r rune) bool { - switch r { - case ' ', '\t', '\n', '\r', ',', ';', ':', '/', '\\', '(', ')', '[', ']', '{', '}': - return true - default: - return false - } - }) { - switch field { - case "buyer", "buyer@acme.com": - return "buyer@acme.com" - } - } - return "" -} - -func notificationDedupeKeys(req *SendRequest) []string { - recipient := canonicalBuyerRecipient(req.To) - if recipient == "" { - recipient = strings.TrimSpace(req.To) - } - keys := []string{recipient + "\x00" + req.Message} - message := strings.ToLower(req.Message) - if strings.Contains(message, "confirm") { - // Live models occasionally emit equivalent confirmation copy more than - // once while a resumed checkout is completing (for example, a concise - // "order-1 confirmed" followed by a fuller buyer-facing sentence). The - // harness has one checkout order, so treat confirmation messages to the - // same buyer as the same side effect while preserving exact-message - // idempotency for all other notifications. - keys = append(keys, recipient+"\x00confirmation") - } - return keys -} - -func dispatchNotifyStep(agentName string, cl client.Client, ntf *Notify) flow.StepFunc { - return func(ctx context.Context, in flow.State) (flow.State, error) { - before := atomic.LoadInt64(&ntf.sent) - out, err := dispatchBuyerNotification(ctx, agentName, cl, in) - if err != nil { - out = in - } - return completeNotifyOnObservedSideEffect(ctx, out, ntf, before, 2*time.Second, err) - } -} - -func dispatchBuyerNotification(ctx context.Context, agentName string, cl client.Client, in flow.State) (flow.State, error) { - if cl == nil { - cl = client.DefaultClient - } - info, _ := model.RunInfoFrom(ctx) - message := fmt.Sprintf( - "Checkout flow confirmed this order: %s. Use notify.Send exactly once to notify buyer@acme.com that the order is confirmed. Do not reply until the notify tool call has completed.", - strings.TrimSpace(in.String()), - ) - body, _ := json.Marshal(map[string]string{"message": message, "parent_id": info.RunID}) - req := cl.NewRequest(agentName, "Agent.Chat", &codecbytes.Frame{Data: body}) - var rsp codecbytes.Frame - if err := cl.Call(ctx, req, &rsp); err != nil { - return in, err - } - var out struct { - Reply string `json:"reply"` - } - _ = json.Unmarshal(rsp.Data, &out) - in.Data = []byte(out.Reply) - return in, nil -} - -func completeNotifyOnObservedSideEffect(ctx context.Context, in flow.State, ntf *Notify, before int64, wait time.Duration, dispatchErr error) (flow.State, error) { - deadline := time.Now().Add(wait) - for time.Now().Before(deadline) { - if atomic.LoadInt64(&ntf.sent) > before { - in.Data = []byte("Buyer notified.") - return in, nil - } - wait := time.NewTimer(25 * time.Millisecond) - select { - case <-ctx.Done(): - if !wait.Stop() { - <-wait.C - } - if dispatchErr == nil { - return in, ctx.Err() - } - // A timed-out Agent.Chat call can report the caller context as done - // while the remote agent is still finishing its notify tool call. - // Keep watching for the idempotent side effect until the local settle - // window expires so a post-side-effect timeout does not strand the - // durable checkout run as pending. - case <-wait.C: - } - } - if dispatchErr != nil { - return in, dispatchErr - } - return in, fmt.Errorf("concierge completed without notifying buyer: notify count stayed at %d; expected recipient buyer@acme.com, buyer, or buyer-of-order-; %s", before, ntf.rejectedSummary()) -} - -// --------------------------------------------------------------------------- -// mock LLM — the only fake. The concierge agent uses it to decide to notify. -// --------------------------------------------------------------------------- - -type mockModel struct{ opts model.Options } - -func newMock(opts ...model.Option) model.Model { - m := &mockModel{} - _ = m.Init(opts...) - return m -} - -func (m *mockModel) Init(opts ...model.Option) error { - for _, o := range opts { - o(&m.opts) - } - return nil -} -func (m *mockModel) Options() model.Options { return m.opts } -func (m *mockModel) String() string { return "mock" } -func (m *mockModel) Stream(context.Context, *model.Request, ...model.GenerateOption) (model.Stream, error) { - return nil, fmt.Errorf("stream not supported by mock") -} - -func (m *mockModel) Generate(ctx context.Context, req *model.Request, _ ...model.GenerateOption) (*model.Response, error) { - if strings.Contains(strings.ToLower(req.Prompt), "a2a reachability probe") { - return &model.Response{Answer: "concierge reachable"}, nil - } - - // The concierge is asked to notify the buyer. Find the notify tool and call it. - for _, t := range req.Tools { - if strings.Contains(t.Name, "Send") && m.opts.ToolHandler != nil { - m.opts.ToolHandler(ctx, model.ToolCall{ - ID: "call-1", - Name: t.Name, - Input: map[string]any{"to": "buyer@acme.com", "message": "Your order is confirmed."}, - }) - break - } - } - return &model.Response{Answer: "Buyer notified."}, nil -} - -// --------------------------------------------------------------------------- -// assertions -// --------------------------------------------------------------------------- - -var failures int - -func check(cond bool, format string, args ...any) { - if cond { - fmt.Printf(" \033[32m✓\033[0m %s\n", fmt.Sprintf(format, args...)) - return - } - fmt.Printf(" \033[31m✗ %s\033[0m\n", fmt.Sprintf(format, args...)) - failures++ -} - -// a2aReachable calls the named agent through the gateway using the A2A -// client — exercising both directions of the protocol — and reports -// whether the agent replied. The probe is intentionally side-effect-free: -// the checkout flow already proved notify tool execution, and reachability -// should not depend on a live model deciding to send another notification. -func a2aReachable(ctx context.Context, base, agent string) error { - probe := "A2A reachability probe only. Reply with the words concierge reachable. Do not call tools or send notifications." - deadline, ok := ctx.Deadline() - if !ok { - deadline = time.Now().Add(10 * time.Second) - } - - var lastErr error - for attempt := 1; ; attempt++ { - if err := ctx.Err(); err != nil { - if lastErr != nil { - return fmt.Errorf("A2A reachability probe failed after %d attempt(s): %w", attempt-1, lastErr) - } - return err - } - - remaining := time.Until(deadline) - if remaining <= 0 { - if lastErr != nil { - return fmt.Errorf("A2A reachability probe failed after %d attempt(s): %w", attempt-1, lastErr) - } - return context.DeadlineExceeded - } - - attemptTimeout := 4 * time.Second - if remaining < attemptTimeout { - attemptTimeout = remaining - } - attemptCtx, cancel := context.WithTimeout(ctx, attemptTimeout) - reply, err := a2a.NewClient(base+"/agents/"+agent).Send(attemptCtx, probe) - cancel() - if err == nil && strings.TrimSpace(reply) != "" { - return nil - } - if err == nil { - err = fmt.Errorf("empty A2A reply") - } - lastErr = err - - if time.Until(deadline) <= 0 { - return fmt.Errorf("A2A reachability probe failed after %d attempt(s): %w", attempt, lastErr) - } - time.Sleep(minDuration(200*time.Millisecond*time.Duration(attempt), time.Until(deadline))) - } -} - -func minDuration(a, b time.Duration) time.Duration { - if a < b { - return a - } - return b -} - -func providerKey(provider string) string { - if v := os.Getenv("MICRO_AI_API_KEY"); v != "" { - return v - } - return os.Getenv(map[string]string{ - "anthropic": "ANTHROPIC_API_KEY", "openai": "OPENAI_API_KEY", - "gemini": "GEMINI_API_KEY", "groq": "GROQ_API_KEY", "mistral": "MISTRAL_API_KEY", - "together": "TOGETHER_API_KEY", "atlascloud": "ATLASCLOUD_API_KEY", - }[provider]) -} - -func waitFor(reg registry.Registry, names ...string) { - deadline := time.Now().Add(5 * time.Second) - for _, name := range names { - for time.Now().Before(deadline) { - if svcs, err := reg.GetService(name); err == nil && len(svcs) > 0 && len(svcs[0].Nodes) > 0 { - break - } - time.Sleep(20 * time.Millisecond) - } - } -} - -func main() { - provider := flag.String("provider", "mock", "LLM provider: mock (default), anthropic, openai, ...") - flag.Parse() - os.Exit(runUniverse(*provider)) -} - -func runUniverse(provider string) int { - failures = 0 - apiKey := "" - if provider == "mock" { - model.Register("mock", newMock) - } else if apiKey = providerKey(provider); apiKey == "" { - fmt.Printf("no API key for provider %q — set MICRO_AI_API_KEY or the provider's key env\n", provider) - return 2 - } - - fmt.Printf("\n\033[1mUNIVERSE — booting a mini go-micro world (provider: %s)\033[0m\n\n", provider) - - // Infrastructure — all in-memory, all real. - reg := registry.NewMemoryRegistry() - br := broker.NewMemoryBroker() - if err := br.Connect(); err != nil { - fmt.Println("broker connect:", err) - return 2 - } - cl := harnessutil.Client(provider, reg) - st := store.NewMemoryStore() - liveAgentOpts := harnessutil.AgentOptions(provider) - - // Services. - inv, pay, ord, ntf := new(Inventory), new(Payment), new(Orders), new(Notify) - for name, h := range map[string]any{"inventory": inv, "payment": pay, "orders": ord, "notify": ntf} { - svc := service.New(service.Name(name), service.Address("127.0.0.1:0"), service.Registry(reg), service.Broker(br), service.Client(cl)) - svc.Handle(h) - go svc.Run() - } - - // The concierge agent: guardrails on, plus a tool-execution wrapper - // that counts calls — to prove the wrapper seam runs end-to-end. - var wrapped int64 - conciergeOpts := []agent.Option{ - agent.Name("concierge"), - agent.Services("notify"), - agent.Prompt("You notify buyers when their order is confirmed."), - agent.Address("127.0.0.1:0"), - agent.Provider(provider), agent.APIKey(apiKey), - agent.MaxSteps(5), - agent.WithBroker(br), - agent.WrapTool(func(next model.ToolHandler) model.ToolHandler { - return func(ctx context.Context, call model.ToolCall) model.ToolResult { - atomic.AddInt64(&wrapped, 1) - return next(ctx, call) - } - }), - agent.WithRegistry(reg), agent.WithClient(cl), agent.WithStore(st), - } - conciergeOpts = append(conciergeOpts, liveAgentOpts...) - concierge := agent.New(conciergeOpts...) - go concierge.Run() - defer concierge.Stop() - - waitFor(reg, "inventory", "payment", "orders", "notify", "concierge") - - // The durable checkout flow: ordered, checkpointed steps. The last step - // hands off to the concierge agent. - checkout := flow.New("checkout", - flow.Trigger("events.order.placed"), - flow.WithCheckpoint(flow.StoreCheckpoint(st, "checkout")), - flow.Timeout(harnessutil.LiveTimeout(provider)), - flow.Steps( - flow.Step{Name: "reserve", Run: flow.Call("inventory", "Inventory.Reserve")}, - flow.Step{Name: "charge", Run: flow.Call("payment", "Payment.Charge")}, - flow.Step{Name: "confirm", Run: flow.Call("orders", "Orders.Confirm")}, - flow.Step{Name: "notify", Run: dispatchNotifyStep("concierge", cl, ntf)}, - ), - ) - if err := checkout.Register(reg, br, cl); err != nil { - fmt.Println("flow register:", err) - return 2 - } - defer checkout.Stop() - - ctx := context.Background() - - // 1) An order event triggers the flow — which crashes at "charge". - fmt.Println("\033[1m> event:\033[0m events.order.placed {\"order\":\"order-1\"}") - if err := br.Publish("events.order.placed", &broker.Message{Body: []byte(`{"order":"order-1"}`)}); err != nil { - fmt.Println("publish:", err) - return 2 - } - - // Wait for the run to be checkpointed as failed at "charge". - var runID string - deadline := time.Now().Add(10 * time.Second) - for time.Now().Before(deadline) { - if pend, _ := checkout.Pending(ctx); len(pend) == 1 && pend[0].State.Stage == "charge" { - runID = pend[0].ID - break - } - time.Sleep(50 * time.Millisecond) - } - - fmt.Println("\n\033[1mafter crash:\033[0m") - check(runID != "", "flow checkpointed a pending run at the failing step") - check(atomic.LoadInt64(&inv.reserves) == 1, "inventory reserved once before the crash") - check(atomic.LoadInt64(&ord.confirms) == 0, "order not confirmed yet (run stopped at charge)") - - // 2) Resume — the dependency has recovered; continue from "charge". - fmt.Println("\n\033[1m> resume:\033[0m", runID) - if runID != "" { - if err := checkout.Resume(ctx, runID); err != nil { - fmt.Println("resume:", err) - } - } - - // Wait for the agent (last step) to have notified. - deadline = time.Now().Add(10 * time.Second) - for time.Now().Before(deadline) { - if atomic.LoadInt64(&ntf.sent) >= 1 { - break - } - time.Sleep(50 * time.Millisecond) - } - - // 3) Assert the end state of the universe. - fmt.Println("\n\033[1mafter resume:\033[0m") - check(atomic.LoadInt64(&inv.reserves) == 1, "inventory still reserved exactly once (completed step not replayed)") - check(atomic.LoadInt64(&pay.attempts) == 2, "payment attempted twice (failed once, then charged)") - check(atomic.LoadInt64(&ord.confirms) == 1, "order confirmed after resume") - check(atomic.LoadInt64(&ntf.sent) == 1, "buyer notified exactly once by the concierge agent") - check(atomic.LoadInt64(&wrapped) >= 1, "agent tool-execution wrapper observed the call") - - if pend, _ := checkout.Pending(ctx); true { - check(len(pend) == 0, "no pending runs — the workflow completed durably") - } - - // Scoped state landed in its own tables. - runs, _ := flow.StoreCheckpoint(st, "checkout").List(ctx) - check(len(runs) == 1 && runs[0].Status == "done", "flow run persisted in flow/checkout and marked done") - hist := agent.NewMemory(store.Scope(st, "agent", "concierge"), "history", 100).Messages() - check(len(hist) > 0, "agent history persisted in agent/concierge") - - // Flows are discoverable while live. - flows, _ := reg.GetService("checkout") - check(len(flows) == 1 && flows[0].Metadata["type"] == "flow", "flow registered in the registry as type=flow") - - // 4) The concierge agent is also reachable from outside, over the A2A - // protocol — its card is generated from the registry, and a task is - // translated to its Agent.Chat RPC. - gw := httptest.NewServer(a2a.New(a2a.Options{Registry: reg, Client: cl, BaseURL: "http://gw"}).Handler()) - defer gw.Close() - beforeA2A := atomic.LoadInt64(&ntf.sent) - reachCtx, cancelReach := context.WithTimeout(ctx, 10*time.Second) - reachErr := a2aReachable(reachCtx, gw.URL, "concierge") - cancelReach() - check(reachErr == nil, "concierge agent reachable over the A2A gateway: %v", reachErr) - check(atomic.LoadInt64(&ntf.sent) == beforeA2A, "A2A reachability probe did not send extra buyer notifications") - - fmt.Println("\n\033[1m> shutting down the universe\033[0m") - // defers stop the agent and flow (deregistering them). - - if failures > 0 { - fmt.Printf("\n\033[31m✗ universe failed: %d assertion(s)\033[0m\n", failures) - return 1 - } - fmt.Println("\n\033[32m✓ universe: booted, survived a crash, resumed, and shut down cleanly\033[0m") - return 0 -} diff --git a/internal/harness/universe/main_test.go b/internal/harness/universe/main_test.go deleted file mode 100644 index bd384cddf9..0000000000 --- a/internal/harness/universe/main_test.go +++ /dev/null @@ -1,300 +0,0 @@ -package main - -import ( - "context" - "errors" - "fmt" - "net/http" - "net/http/httptest" - "sync/atomic" - "testing" - "time" - - "go-micro.dev/v6/flow" -) - -// TestUniverseHarnessContract makes the 0→hero harness part of the ordinary -// Go test contract. The harness boots real services, a durable workflow, an -// agent, scoped state, and the A2A gateway with only the LLM mocked; running it -// here prevents the full services → agents → workflows lifecycle from silently -// drifting while developers rely on `go test ./...`. -func TestUniverseHarnessContract(t *testing.T) { - if testing.Short() { - t.Skip("universe harness boots an end-to-end system; skipped with -short") - } - - if code := runUniverse("mock"); code != 0 { - t.Fatalf("universe harness exited with code %d", code) - } -} - -func TestA2AReachableRetriesTransientTimeout(t *testing.T) { - var calls int64 - srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { - if got, want := r.URL.Path, "/agents/concierge"; got != want { - t.Fatalf("path = %q, want %q", got, want) - } - if atomic.AddInt64(&calls, 1) == 1 { - time.Sleep(5 * time.Second) - return - } - w.Header().Set("Content-Type", "application/json") - fmt.Fprint(w, `{"jsonrpc":"2.0","id":1,"result":{"kind":"task","id":"task-1","contextId":"ctx-1","status":{"state":"completed"},"artifacts":[{"artifactId":"artifact-1","parts":[{"kind":"text","text":"concierge reachable"}]}]}}`) - })) - defer srv.Close() - - ctx, cancel := context.WithTimeout(context.Background(), 6*time.Second) - defer cancel() - if err := a2aReachable(ctx, srv.URL, "concierge"); err != nil { - t.Fatalf("a2aReachable returned error: %v", err) - } - if got := atomic.LoadInt64(&calls); got < 2 { - t.Fatalf("A2A calls = %d, want retry after transient timeout", got) - } -} - -func TestNotifyStepCompletesAfterObservedSideEffectTimeout(t *testing.T) { - ntf := new(Notify) - before := atomic.LoadInt64(&ntf.sent) - go func() { - time.Sleep(30 * time.Millisecond) - var rsp SendResponse - if err := ntf.Send(context.Background(), &SendRequest{ - To: "buyer@acme.com", - Message: "Your order is confirmed.", - }, &rsp); err != nil { - t.Errorf("send notification: %v", err) - } - }() - - out, err := completeNotifyOnObservedSideEffect( - context.Background(), - flow.State{Data: []byte(`{"order":"order-1"}`)}, - ntf, - before, - time.Second, - errors.New("client observed timeout"), - ) - if err != nil { - t.Fatalf("notify completion returned error: %v", err) - } - if got := out.String(); got != "Buyer notified." { - t.Fatalf("result = %q, want Buyer notified.", got) - } - if got := atomic.LoadInt64(&ntf.sent); got != 1 { - t.Fatalf("notifications sent = %d, want 1", got) - } - - var rsp SendResponse - if err := ntf.Send(context.Background(), &SendRequest{ - To: "buyer@acme.com", - Message: "Your order is confirmed.", - }, &rsp); err != nil { - t.Fatalf("duplicate send: %v", err) - } - if got := atomic.LoadInt64(&ntf.sent); got != 1 { - t.Fatalf("notifications sent after duplicate = %d, want 1", got) - } -} - -func TestNotifyStepWaitsForObservedSideEffectAfterCanceledDispatchContext(t *testing.T) { - ntf := new(Notify) - before := atomic.LoadInt64(&ntf.sent) - ctx, cancel := context.WithCancel(context.Background()) - cancel() - - go func() { - time.Sleep(30 * time.Millisecond) - var rsp SendResponse - if err := ntf.Send(context.Background(), &SendRequest{ - To: "buyer@acme.com", - Message: "Your order is confirmed.", - }, &rsp); err != nil { - t.Errorf("send notification: %v", err) - } - }() - - out, err := completeNotifyOnObservedSideEffect( - ctx, - flow.State{Data: []byte(`{"order":"order-1"}`)}, - ntf, - before, - time.Second, - errors.New("client observed timeout"), - ) - if err != nil { - t.Fatalf("notify completion returned error: %v", err) - } - if got := out.String(); got != "Buyer notified." { - t.Fatalf("result = %q, want Buyer notified.", got) - } - if got := atomic.LoadInt64(&ntf.sent); got != 1 { - t.Fatalf("notifications sent = %d, want 1", got) - } -} - -func TestNotifyStepRejectsClaimedCompletionWithoutSideEffect(t *testing.T) { - ntf := new(Notify) - before := atomic.LoadInt64(&ntf.sent) - - _, err := completeNotifyOnObservedSideEffect( - context.Background(), - flow.State{Data: []byte(`claimed success`)}, - ntf, - before, - 25*time.Millisecond, - nil, - ) - if err == nil { - t.Fatal("notify completion returned nil, want missing buyer notification error") - } - want := `concierge completed without notifying buyer: notify count stayed at 0; expected recipient buyer@acme.com, buyer, or buyer-of-order-; no rejected notify call observed` - if got := err.Error(); got != want { - t.Fatalf("error = %q, want %q", got, want) - } -} - -func TestNotifySuppressesEquivalentConfirmationMessages(t *testing.T) { - ntf := new(Notify) - ctx := context.Background() - - for _, req := range []*SendRequest{ - {To: "buyer@acme.com", Message: "Your order order-1 has been confirmed."}, - {To: "buyer@acme.com", Message: "order-1 confirmed"}, - } { - var rsp SendResponse - if err := ntf.Send(ctx, req, &rsp); err != nil { - t.Fatalf("send notification %q: %v", req.Message, err) - } - if !rsp.Sent { - t.Fatalf("send notification %q did not report sent", req.Message) - } - } - - if got := atomic.LoadInt64(&ntf.sent); got != 1 { - t.Fatalf("equivalent confirmation notifications sent = %d, want 1", got) - } -} - -func TestNotifyAcceptsBuyerAlias(t *testing.T) { - ntf := new(Notify) - ctx := context.Background() - - var rsp SendResponse - if err := ntf.Send(ctx, &SendRequest{ - To: "buyer", - Message: "Your order order-1 has been confirmed.", - }, &rsp); err != nil { - t.Fatalf("send buyer alias notification: %v", err) - } - if !rsp.Sent { - t.Fatal("buyer alias notification did not report sent") - } - if got := atomic.LoadInt64(&ntf.sent); got != 1 { - t.Fatalf("buyer alias notifications sent = %d, want 1", got) - } - - if err := ntf.Send(ctx, &SendRequest{ - To: "buyer@acme.com", - Message: "order-1 confirmed", - }, &rsp); err != nil { - t.Fatalf("send canonical buyer notification: %v", err) - } - if !rsp.Sent { - t.Fatal("canonical buyer notification did not report sent") - } - if got := atomic.LoadInt64(&ntf.sent); got != 1 { - t.Fatalf("alias/canonical confirmation notifications sent = %d, want 1", got) - } -} - -func TestNotifyIgnoresNonBuyerRecipients(t *testing.T) { - ntf := new(Notify) - ctx := context.Background() - - var rsp SendResponse - if err := ntf.Send(ctx, &SendRequest{ - To: "order-1", - Message: "order-1 confirmed", - }, &rsp); err != nil { - t.Fatalf("send non-buyer notification: %v", err) - } - if rsp.Sent { - t.Fatal("non-buyer notification reported sent") - } - if got := atomic.LoadInt64(&ntf.sent); got != 0 { - t.Fatalf("non-buyer notifications sent = %d, want 0", got) - } - - if err := ntf.Send(ctx, &SendRequest{ - To: "buyer@acme.com", - Message: "Your order order-1 has been confirmed.", - }, &rsp); err != nil { - t.Fatalf("send buyer notification: %v", err) - } - if !rsp.Sent { - t.Fatal("buyer notification did not report sent") - } - if got := atomic.LoadInt64(&ntf.sent); got != 1 { - t.Fatalf("buyer notifications sent = %d, want 1", got) - } -} - -func TestNotifyAcceptsOrderScopedBuyerRecipient(t *testing.T) { - ntf := new(Notify) - ctx := context.Background() - - var rsp SendResponse - if err := ntf.Send(ctx, &SendRequest{ - To: "buyer-of-order-1", - Message: "order-1 confirmed", - }, &rsp); err != nil { - t.Fatalf("send order-scoped buyer notification: %v", err) - } - if !rsp.Sent { - t.Fatal("order-scoped buyer notification did not report sent") - } - if got := atomic.LoadInt64(&ntf.sent); got != 1 { - t.Fatalf("order-scoped buyer notifications sent = %d, want 1", got) - } - - if err := ntf.Send(ctx, &SendRequest{ - To: "non-buyer", - Message: "order-1 confirmed", - }, &rsp); err != nil { - t.Fatalf("send hyphenated non-buyer notification: %v", err) - } - if rsp.Sent { - t.Fatal("hyphenated non-buyer notification reported sent") - } - if got := atomic.LoadInt64(&ntf.sent); got != 1 { - t.Fatalf("notifications sent after hyphenated non-buyer = %d, want 1", got) - } -} - -func TestNotifyStepReportsRejectedRecipientDiagnostics(t *testing.T) { - ntf := new(Notify) - var rsp SendResponse - if err := ntf.Send(context.Background(), &SendRequest{ - To: "order-1", - Message: "order-1 confirmed", - }, &rsp); err != nil { - t.Fatalf("send rejected notification: %v", err) - } - - _, err := completeNotifyOnObservedSideEffect( - context.Background(), - flow.State{Data: []byte(`claimed success`)}, - ntf, - 0, - 25*time.Millisecond, - nil, - ) - if err == nil { - t.Fatal("notify completion returned nil, want diagnostics") - } - want := `concierge completed without notifying buyer: notify count stayed at 0; expected recipient buyer@acme.com, buyer, or buyer-of-order-; last notify args to="order-1" message="order-1 confirmed"` - if got := err.Error(); got != want { - t.Fatalf("error = %q, want %q", got, want) - } -} diff --git a/internal/harness/zero-to-hero-ci/docs_test.go b/internal/harness/zero-to-hero-ci/docs_test.go index b8804817c6..0445c637ff 100644 --- a/internal/harness/zero-to-hero-ci/docs_test.go +++ b/internal/harness/zero-to-hero-ci/docs_test.go @@ -31,10 +31,7 @@ func TestZeroToHeroReferenceDocs(t *testing.T) { "go test ./examples/support -run 'TestRunSupportMockSmoke|TestZeroToHeroReadmeDocumentsLifecycle|TestZeroToHeroInspectTranscript' -count=1", "./internal/harness/zero-to-hero-ci/run.sh", "micro zero-to-hero", - "go run ./internal/harness/agent-flow", "make provider-conformance-mock", - "internal/harness/plan-delegate", - "internal/harness/universe", } { if !strings.Contains(guide, want) { t.Fatalf("0→hero guide missing %q", want) @@ -60,7 +57,6 @@ func TestZeroToHeroReferenceDocs(t *testing.T) { "chat/inspect:", "first-agent app:", "0→hero app:", - "flow history:", } { if !strings.Contains(runScript, want) { t.Fatalf("0→hero CI run script missing debuggable boundary label %q", want) @@ -96,7 +92,6 @@ func TestZeroToHeroTranscriptTargetStaysOrdered(t *testing.T) { `run_step "chat/inspect: no-secret first-agent transcript and docs"`, `run_step "first-agent app: runnable provider-free example"`, `run_step "0→hero app: support lifecycle smoke"`, - `run_step "flow history: deterministic services → agents → workflows harnesses"`, `run_step "deploy dry-run: configured target plan"`, }) @@ -165,9 +160,9 @@ deploy prod func TestDocsNavigation(t *testing.T) { root := filepath.Clean(filepath.Join("..", "..", "..")) nav := readFile(t, filepath.Join(root, "internal", "website", "data", "docs.yaml")) - pages := []string{"quickstart", "services", "agents", "workflows", "reference"} + pages := []string{"quickstart", "services", "agents", "reference"} if strings.Count(nav, "- title:") != len(pages) { - t.Fatal("docs navigation should contain five entries") + t.Fatal("docs navigation should contain four entries") } last := -1 for _, page := range pages { @@ -190,7 +185,7 @@ func TestCurrentDocsExamplesBuild(t *testing.T) { } workspace := t.TempDir() writeFile(t, filepath.Join(workspace, "go.mod"), "module example.com/my-app\n\ngo 1.26\n\nrequire go-micro.dev/v6 v6.0.0\n\nreplace go-micro.dev/v6 => "+root+"\n") - for _, page := range []string{"quickstart", "services", "agents", "standalone-agent", "workflows"} { + for _, page := range []string{"quickstart", "services", "agents", "standalone-agent"} { docPage := page if page == "standalone-agent" { docPage = "agents" @@ -311,16 +306,14 @@ func TestArchitectureDocsAlignWithAgentHarnessLifecycle(t *testing.T) { doc := readFile(t, filepath.Join(root, "internal", "website", "content", "en", "docs", "architecture", "index.md")) for _, want := range []string{ - "services → agents → workflows lifecycle", + "services → agents lifecycle", "## Service substrate", "## Agent harness", - "## Workflows", "## Interop gateways", "`model` / `model.Model`", "`store` / memory", "`model.Tools`", "`agent`", - "`flow`", "`micro mcp`", "`micro a2a`", "[AI Integration](../ai-integration/index.md)", @@ -335,7 +328,6 @@ func TestArchitectureDocsAlignWithAgentHarnessLifecycle(t *testing.T) { assertOrderedMarkers(t, "architecture lifecycle", doc, []string{ "## Service substrate", "## Agent harness", - "## Workflows", "## Interop gateways", "## Developer path", }) @@ -348,8 +340,8 @@ func TestFirstAgentWayfindingDocs(t *testing.T) { links []string }{ {"README.md", []string{"https://go-micro.dev/docs/quickstart.html"}}, - {"internal/website/content/en/docs/quickstart.md", []string{"services.md", "agents.md", "workflows.md"}}, - {"internal/website/content/en/docs/getting-started/index.md", []string{"../quickstart.md", "../guides/your-first-agent.md", "../guides/agents-and-workflows.md"}}, + {"internal/website/content/en/docs/quickstart.md", []string{"services.md", "agents.md"}}, + {"internal/website/content/en/docs/getting-started/index.md", []string{"../quickstart.md", "../guides/your-first-agent.md"}}, {"internal/website/content/en/docs/_index.md", []string{"quickstart.md", "services.md", "agents.md", "reference.md"}}, } for _, check := range checks { @@ -394,7 +386,7 @@ func TestFirstAgentWayfindingCanonicalTrailStaysInSync(t *testing.T) { name: "website quickstart next steps", file: filepath.Join(root, "internal", "website", "content", "en", "docs", "quickstart.md"), heading: "", - markers: []string{"Go 1.26", "go mod init", "services.md", "agents.md", "workflows.md"}, + markers: []string{"Go 1.26", "go mod init", "services.md", "agents.md"}, }, { name: "examples map recommended adoption path", @@ -674,10 +666,9 @@ func TestExamplesIndexesPreserveLifecycleMap(t *testing.T) { "support", "services", "agents", - "workflows", "Debugging and observability", }, - ordered: []string{"1. First service", "2. First agent", "3. First workflow"}, + ordered: []string{"1. First service", "2. First agent"}, }, { name: "website examples lifecycle map", @@ -690,7 +681,6 @@ func TestExamplesIndexesPreserveLifecycleMap(t *testing.T) { "examples/support", "services", "agents", - "workflows", "debugging-agents.md", }, ordered: []string{"0→1 service", "Provider-free first agent", "0→hero lifecycle"}, diff --git a/internal/harness/zero-to-hero-ci/run.sh b/internal/harness/zero-to-hero-ci/run.sh index 3481799f62..b4db7fc4fc 100755 --- a/internal/harness/zero-to-hero-ci/run.sh +++ b/internal/harness/zero-to-hero-ci/run.sh @@ -33,7 +33,5 @@ run_step "first-agent app: runnable provider-free example" \ go test ./examples/first-agent -run TestRunFirstAgent -count=1 run_step "0→hero app: support lifecycle smoke" \ go test ./examples/support -run 'TestRunSupportMockSmoke|TestZeroToHeroReadmeDocumentsLifecycle|TestZeroToHeroInspectTranscript' -count=1 -run_step "flow history: deterministic services → agents → workflows harnesses" \ - go test ./internal/harness/universe ./internal/harness/plan-delegate -run 'Test.*Harness|TestPlanDelegateEndToEnd|TestPlanDelegateFlowHandoff' -count=1 run_step "deploy dry-run: configured target plan" \ go test ./cmd/micro/cli/deploy -run TestDeployDryRun -count=1 diff --git a/internal/test/developer_journey_test.go b/internal/test/developer_journey_test.go index f2a0cba8e0..62b301fa10 100644 --- a/internal/test/developer_journey_test.go +++ b/internal/test/developer_journey_test.go @@ -3,7 +3,6 @@ package test_test import ( "context" "encoding/json" - "errors" "net/http" "net/http/httptest" "strings" @@ -13,7 +12,6 @@ import ( micro "go-micro.dev/v6" "go-micro.dev/v6/agent" "go-micro.dev/v6/broker" - "go-micro.dev/v6/flow" "go-micro.dev/v6/registry" "go-micro.dev/v6/store" ) @@ -106,48 +104,4 @@ func TestDeveloperJourney(t *testing.T) { }) } - dir := t.TempDir() - newStore := func() store.Store { return store.NewFileStore(store.DirOption(dir)) } - st := newStore() - fail := true - makeFlow := func(st store.Store) *flow.Flow { - f := flow.New("read-notes", flow.WithCheckpoint(flow.StoreCheckpoint(st, "read-notes")), flow.Steps( - flow.Step{Name: "list", Run: flow.Call("notes", "JourneyNotes.List")}, - flow.Step{Name: "save", Run: func(_ context.Context, in flow.State) (flow.State, error) { - if fail { - return in, errors.New("destination unavailable") - } - if !strings.Contains(in.String(), "Review the release") { - t.Error("lost service response") - } - return in, nil - }}, - )) - if err := f.Register(reg, br, svc.Client()); err != nil { - t.Fatal(err) - } - return f - } - f := makeFlow(st) - if err := f.Execute(ctx, "{}"); err == nil { - t.Fatal("expected interrupted workflow") - } - before := notes.calls.Load() - if err := st.Close(); err != nil { - t.Fatal(err) - } - st = newStore() - defer st.Close() - fail = false - f = makeFlow(st) - if _, err := f.ResumePending(ctx); err != nil { - t.Fatal(err) - } - if notes.calls.Load() != before { - t.Fatal("resume repeated completed service call") - } - pending, err := f.Pending(ctx) - if err != nil || len(pending) != 0 { - t.Fatalf("unfinished workflow: %v %v", pending, err) - } } diff --git a/internal/website/_data/navigation.yml b/internal/website/_data/navigation.yml index eb1027d047..5338998249 100644 --- a/internal/website/_data/navigation.yml +++ b/internal/website/_data/navigation.yml @@ -48,14 +48,10 @@ guides: url: /docs/guides/plan-delegate.html - title: Agent Guardrails url: /docs/guides/agent-guardrails.html - - title: Agents and Workflows - url: /docs/guides/agents-and-workflows.html - title: Agent Integration Patterns url: /docs/guides/agent-patterns.html - title: The Agent Harness url: /docs/guides/agent-harness.html - - title: Agent Loops - url: /docs/guides/agent-loops.html - title: Agent2Agent (A2A) url: /docs/guides/a2a-protocol.html - title: AI Provider Guide diff --git a/internal/website/content/en/blog/news/agents-across-frameworks-a2a.md b/internal/website/content/en/blog/news/agents-across-frameworks-a2a.md index c5ab8731b1..fe84c16679 100644 --- a/internal/website/content/en/blog/news/agents-across-frameworks-a2a.md +++ b/internal/website/content/en/blog/news/agents-across-frameworks-a2a.md @@ -12,6 +12,9 @@ tags: aliases: - /blog/26 --- + +> Historical article: the standalone flow package and flow CLI commands have since been removed. Use services and agents for current development. + Inside a Go Micro system, agents already talk to each other. An agent is a service with an `Agent.Chat` endpoint, so `delegate` just calls another agent over RPC. That works as long as everyone is on Go Micro. The moment an agent is built on a different framework, the conversation stops: it can't call yours, and yours can't call it. [A2A](https://a2a-protocol.org) — the open Agent2Agent protocol — is the standard that closes that gap, and Go Micro now speaks it. diff --git a/internal/website/content/en/blog/news/build-your-own-ai-agent-cli-in-150-lines/index.md b/internal/website/content/en/blog/news/build-your-own-ai-agent-cli-in-150-lines/index.md index b3aa13de1a..99a4f72990 100644 --- a/internal/website/content/en/blog/news/build-your-own-ai-agent-cli-in-150-lines/index.md +++ b/internal/website/content/en/blog/news/build-your-own-ai-agent-cli-in-150-lines/index.md @@ -12,6 +12,9 @@ tags: aliases: - /blog/11 --- + +> Historical article: the standalone flow package and flow CLI commands have since been removed. Use services and agents for current development. + ![](developer-experience.jpg) We [introduced `micro chat`](/blog/2026/05/29/micro-chat-talk-to-your-services.html) — a CLI that lets you talk to your microservices through an LLM. People asked how it works under the hood. The honest answer: it's about 150 lines, and there's no magic. This post walks through every piece so you can build your own — for go-micro, for your own framework, or for whatever services you have. diff --git a/internal/website/content/en/blog/news/building-a-support-agent-in-go.md b/internal/website/content/en/blog/news/building-a-support-agent-in-go.md index 0349e74f90..d0ccc7fce2 100644 --- a/internal/website/content/en/blog/news/building-a-support-agent-in-go.md +++ b/internal/website/content/en/blog/news/building-a-support-agent-in-go.md @@ -12,6 +12,9 @@ tags: aliases: - /blog/28 --- + +> Historical article: the standalone flow package and flow CLI commands have since been removed. Use services and agents for current development. + Most agent demos are a chat box wired to one tool. Real systems aren't that — they're a handful of services, an agent that operates them, something that triggers the agent without a human typing, and a gate on the actions you don't want it taking on its own. Here's that, built end to end. The full code is in [`examples/support`](https://github.com/micro/go-micro/tree/master/examples/support); it runs with no API key. The scenario: a customer files a ticket. That should trigger an agent to look the customer up, set a priority, and reply — but it must not email anyone without passing an approval gate. diff --git a/internal/website/content/en/blog/news/durable-workflows.md b/internal/website/content/en/blog/news/durable-workflows.md index c644956a43..1848537a17 100644 --- a/internal/website/content/en/blog/news/durable-workflows.md +++ b/internal/website/content/en/blog/news/durable-workflows.md @@ -12,6 +12,9 @@ tags: aliases: - /blog/24 --- + +> Historical article: the standalone flow package and flow CLI commands have since been removed. Use services and agents for current development. + A workflow that calls real services is rarely instant and rarely side-effect-free. It reserves inventory at step one, charges a card at step two, sends a confirmation at step three. Each of those changes the world. So when the process dies between step two and step three — a deploy, an OOM, a node going away — you can't just run it again from the top: that reserves twice and charges twice. And if the workflow was triggered by an event with no human watching, nobody noticed it died at all. This is the oldest problem in distributed systems, and it has an established answer: **durable execution** — checkpoint progress as you go, and on restart resume from where you stopped instead of from the beginning. Go Micro flows now do this. @@ -90,4 +93,4 @@ type Checkpoint interface { That's the through-line. Durable execution isn't a workflow engine you adopt alongside your services; it's a store and an interface, and the workflow is still just an ordered list of steps you can read. Same as everything else in Go Micro — the abstraction is the service, and this is one more thing the substrate underneath it now handles. -See the [Agents and Workflows guide](/docs/guides/agents-and-workflows.html) for the full reference. +See the [Agents and Workflows guide](https://github.com/micro/go-micro/blob/8b4578aa45cefe3336d211cfd93537d62d9f29d2/internal/website/content/en/docs/guides/agents-and-workflows.md) for the full reference. diff --git a/internal/website/content/en/blog/news/from-chat-to-flows-what-if-your-services-could-orchestrate-themselves/index.md b/internal/website/content/en/blog/news/from-chat-to-flows-what-if-your-services-could-orchestrate-themselves/index.md index d610eff88c..0c18394f3c 100644 --- a/internal/website/content/en/blog/news/from-chat-to-flows-what-if-your-services-could-orchestrate-themselves/index.md +++ b/internal/website/content/en/blog/news/from-chat-to-flows-what-if-your-services-could-orchestrate-themselves/index.md @@ -12,6 +12,9 @@ tags: aliases: - /blog/9 --- + +> Historical article: the standalone flow package and flow CLI commands have since been removed. Use services and agents for current development. + ![](blog-agents-demo.jpg) We shipped `micro chat` recently — an interactive terminal where you talk to your services through an LLM. You say "list all users over 30 and send each a welcome email," and the model figures out which services to call, in what order, with what arguments. diff --git a/internal/website/content/en/blog/news/go-micro-is-becoming-a-framework-for-agentic-development.md b/internal/website/content/en/blog/news/go-micro-is-becoming-a-framework-for-agentic-development.md index bde697c5b3..1d833a9f53 100644 --- a/internal/website/content/en/blog/news/go-micro-is-becoming-a-framework-for-agentic-development.md +++ b/internal/website/content/en/blog/news/go-micro-is-becoming-a-framework-for-agentic-development.md @@ -12,6 +12,9 @@ tags: aliases: - /blog/25 --- + +> Historical article: the standalone flow package and flow CLI commands have since been removed. Use services and agents for current development. + When Anthropic began sponsoring Go Micro, we committed to building in the open and reporting progress as it happened. It has been three months. Each post so far covered one change; this one is about what they add up to. **Go Micro is becoming a framework for agentic development, the same way it has been a framework for services for the last decade.** It's an extension of the existing framework, not a rewrite, because an agent is a distributed system and Go Micro is how you build one. ## The idea diff --git a/internal/website/content/en/blog/news/go-micro-joins-openai-s-codex-for-open-source.md b/internal/website/content/en/blog/news/go-micro-joins-openai-s-codex-for-open-source.md index 39f0e39d9b..3b619c7512 100644 --- a/internal/website/content/en/blog/news/go-micro-joins-openai-s-codex-for-open-source.md +++ b/internal/website/content/en/blog/news/go-micro-joins-openai-s-codex-for-open-source.md @@ -20,13 +20,13 @@ Codex for Open Source backs maintainers directly: the constant, unglamorous work ## Why it fits Go Micro -There's a neat symmetry here. Go Micro is a framework for **agentic development** — agents that use tools, services that are automatically AI-callable, workflows that [loop until the job is done](/docs/guides/agent-loops.html). Building and maintaining it with an agentic coding tool is that same idea pointed back at itself: tools calling tools. +There's a neat symmetry here. Go Micro is a framework for **agentic development** — agents that use tools, services that are automatically AI-callable, workflows that [loop until the job is done](https://github.com/micro/go-micro/blob/8b4578aa45cefe3336d211cfd93537d62d9f29d2/internal/website/content/en/docs/guides/agent-loops.md). Building and maintaining it with an agentic coding tool is that same idea pointed back at itself: tools calling tools. It also lines up with what's already in the box. `openai` has been a first-class model provider in Go Micro since the AI-native rewrite — one of [several](/docs/guides/ai-provider-guide.html) behind the same `model.Model` interface. So you can build *on* OpenAI models with Go Micro, and now we build Go Micro itself with OpenAI's tooling. ## What we'll use it for -Honestly: throughput. More reviewed PRs, faster releases, quicker issue triage, more examples and docs. The recent run of work — [agent loops](/docs/guides/agent-loops.html), [A2A](/blog/2026/06/18/agents-across-frameworks-a2a.html), durable flows, a blocking lint gate in CI — is the pace we want to keep, and maintainer tooling is what sustains it. +Honestly: throughput. More reviewed PRs, faster releases, quicker issue triage, more examples and docs. The recent run of work — [agent loops](https://github.com/micro/go-micro/blob/8b4578aa45cefe3336d211cfd93537d62d9f29d2/internal/website/content/en/docs/guides/agent-loops.md), [A2A](/blog/2026/06/18/agents-across-frameworks-a2a.html), durable flows, a blocking lint gate in CI — is the pace we want to keep, and maintainer tooling is what sustains it. ## Thanks diff --git a/internal/website/content/en/blog/news/introducing-micro-newagent.md b/internal/website/content/en/blog/news/introducing-micro-newagent.md index 7e51566930..3e9d8cb3e0 100644 --- a/internal/website/content/en/blog/news/introducing-micro-newagent.md +++ b/internal/website/content/en/blog/news/introducing-micro-newagent.md @@ -11,6 +11,9 @@ tags: aliases: - /blog/16 --- + +> Historical article: the standalone flow package and flow CLI commands have since been removed. Use services and agents for current development. + Go Micro now has three core abstractions: ```go diff --git a/internal/website/content/en/blog/news/micro-chat-talk-to-your-services/index.md b/internal/website/content/en/blog/news/micro-chat-talk-to-your-services/index.md index fbaac04899..91a906b9ce 100644 --- a/internal/website/content/en/blog/news/micro-chat-talk-to-your-services/index.md +++ b/internal/website/content/en/blog/news/micro-chat-talk-to-your-services/index.md @@ -12,6 +12,9 @@ tags: aliases: - /blog/10 --- + +> Historical article: the standalone flow package and flow CLI commands have since been removed. Use services and agents for current development. + ![](developer-experience.jpg) We built `micro chat` — a CLI that lets you talk to your microservices through an LLM. It discovers every service in the registry, exposes each endpoint as a tool, and lets a model decide which RPCs to call based on what you ask. diff --git a/internal/website/content/en/blog/news/not-everything-should-be-an-agent.md b/internal/website/content/en/blog/news/not-everything-should-be-an-agent.md index 13b58c3a9c..5c07b170a8 100644 --- a/internal/website/content/en/blog/news/not-everything-should-be-an-agent.md +++ b/internal/website/content/en/blog/news/not-everything-should-be-an-agent.md @@ -12,6 +12,9 @@ tags: aliases: - /blog/18 --- + +> Historical article: the standalone flow package and flow CLI commands have since been removed. Use services and agents for current development. + The last two posts were about agents — [the abstraction](/blog/2026/06/05/introducing-micro-newagent.html), and then [agents that plan and delegate](/blog/2026/06/07/agents-that-plan-and-delegate.html), directing their own work over many turns. That's the exciting part. It's also, honestly, the part you should reach for *least often*. An agent decides its own path at runtime. That's powerful when the task genuinely needs it, and a liability when it doesn't — you trade predictability, latency, and cost for flexibility you may not want. Most real work has a known shape: *when this event happens, do these things.* For that, you don't want a model improvising. You want a **workflow**. @@ -85,7 +88,7 @@ The mistake is starting at 3. Agents are the most capable tool and the easiest t We didn't build a workflow engine and an agent framework. We built services that are tools, and then pointed an LLM at them two ways — a predefined path, or a dynamic one. `Flow` and `Agent` are modes, not frameworks, and they compose because they share everything underneath. That's the same principle we've held since [going all in on AI](/blog/2026/06/04/going-all-in-on-model.html): services are the only abstraction, the LLM calls them as tools, and everything else is how you arrange them. -Read the [Agents and Workflows guide](/docs/guides/agents-and-workflows.html) for the full mapping, or [Plan & Delegate](/docs/guides/plan-delegate.html) for the agent side. +Read the [Agents and Workflows guide](https://github.com/micro/go-micro/blob/8b4578aa45cefe3336d211cfd93537d62d9f29d2/internal/website/content/en/docs/guides/agents-and-workflows.md) for the full mapping, or [Plan & Delegate](/docs/guides/plan-delegate.html) for the agent side. ```bash curl -fsSL https://go-micro.dev/install.sh | sh diff --git a/internal/website/content/en/blog/news/tools-as-services-why-go-micro-was-always-ready-for-ai.md b/internal/website/content/en/blog/news/tools-as-services-why-go-micro-was-always-ready-for-ai.md index ca4b96001e..68df9eb35a 100644 --- a/internal/website/content/en/blog/news/tools-as-services-why-go-micro-was-always-ready-for-ai.md +++ b/internal/website/content/en/blog/news/tools-as-services-why-go-micro-was-always-ready-for-ai.md @@ -12,6 +12,9 @@ tags: aliases: - /blog/12 --- + +> Historical article: the standalone flow package and flow CLI commands have since been removed. Use services and agents for current development. + When people see `micro chat` or the MCP gateway, they assume we built something new. We didn't. We exposed something that was already there. Go Micro has always treated services as self-describing, addressable units. Every service registers its name, endpoints, and request types with the registry. Every endpoint is callable through a standardised path. The only thing that changed is *who's calling*. diff --git a/internal/website/content/en/blog/news/when-the-event-is-the-prompt.md b/internal/website/content/en/blog/news/when-the-event-is-the-prompt.md index da62ced0ff..719dcc74cc 100644 --- a/internal/website/content/en/blog/news/when-the-event-is-the-prompt.md +++ b/internal/website/content/en/blog/news/when-the-event-is-the-prompt.md @@ -12,6 +12,9 @@ tags: aliases: - /blog/21 --- + +> Historical article: the standalone flow package and flow CLI commands have since been removed. Use services and agents for current development. + Almost every agent demo starts the same way: a human types a prompt, the agent responds. That framing is a habit from chat, and it hides the more useful case. The agents worth running don't wait for you to ask. They run because something happened — a user signed up, a payment failed, a deployment finished, a metric crossed a line. In those systems there is no prompt, because there is no human in the loop. The event is the prompt. Go Micro has had the pieces for this since we added [workflows](/blog/2026/06/08/not-everything-should-be-an-agent.html): a `Flow` subscribes to a broker topic, and an `Agent` reasons and acts. Putting them together is the point of this post. @@ -39,7 +42,7 @@ f := micro.NewFlow("onboard", When a `user.created` event lands on the broker, the flow renders it into a prompt and hands it to the onboarder over RPC. The agent looks at its tools, creates the workspace, sends the welcome, and stops. No one typed anything. -There's a runnable version of exactly this in [`internal/harness/agent-flow`](https://github.com/micro/go-micro/tree/master/internal/harness/agent-flow) — real services, registry, RPC, broker, and the agent loop, with only the model mocked so it runs without a key: +There's a runnable version of exactly this in [`internal/harness/agent-flow`](https://github.com/micro/go-micro/tree/8b4578aa45cefe3336d211cfd93537d62d9f29d2/internal/harness/agent-flow) — real services, registry, RPC, broker, and the agent loop, with only the model mocked so it runs without a key: ``` > event: publishing events.user.created {"email":"alice@acme.com"} diff --git a/internal/website/content/en/docs/agents.md b/internal/website/content/en/docs/agents.md index 7645a9f8a7..841976dd4d 100644 --- a/internal/website/content/en/docs/agents.md +++ b/internal/website/content/en/docs/agents.md @@ -166,7 +166,6 @@ where `st` is your persistent store. `agent.Pending` lists unfinished runs and a crash may already have performed its action. These are agent capabilities; no workflow definition is required. -[Workflows](workflows.md) remain available for applications that need a predefined sequence of operations. ## Call an agent from Go diff --git a/internal/website/content/en/docs/ai-integration/index.md b/internal/website/content/en/docs/ai-integration/index.md index 0d2603f313..4418c3b6d7 100644 --- a/internal/website/content/en/docs/ai-integration/index.md +++ b/internal/website/content/en/docs/ai-integration/index.md @@ -17,7 +17,7 @@ model.Tools → discovers services + executes RPCs programmatica ↓ model.Model → calls LLMs (Anthropic, OpenAI, Gemini, Atlas Cloud, ...) ↓ -agent / flow / micro chat → agent-managed, event-driven, or interactive orchestration +agent / micro chat → agent-managed or interactive orchestration ``` Every layer is optional. You can use go-micro without AI. You can use the `model` package without MCP. But when you stack them, you get services that AI agents can discover and orchestrate automatically. @@ -126,32 +126,6 @@ ANTHROPIC_API_KEY=sk-ant-... micro chat --provider anthropic Conversations persist through the agent memory store. Use `/new` to start a separate conversation, `/sessions` to list them, and `/resume ID` to continue one. -### 7. micro flow (event-driven orchestration) - -Subscribe to broker events and let an LLM orchestrate the response: - -```go -import "go-micro.dev/v6/flow" - -f := flow.New("onboard", - flow.Trigger("events.user.created"), - flow.Prompt("New user: {{.Data}}. Send welcome email and create workspace."), - flow.Provider("anthropic"), - flow.APIKey(key), -) -f.Register(service.Options().Registry, service.Options().Broker, service.Client()) -``` - -Or from the CLI: - -```bash -micro flow run --trigger events.user.created \ - --prompt "New user: {{.Data}}. Send welcome email." \ - --provider anthropic - -micro flow exec --prompt "List all users" --provider anthropic -``` - ### 8. micro api (HTTP gateway) A standalone HTTP-to-RPC gateway for exposing services over HTTP without the full dashboard: diff --git a/internal/website/content/en/docs/architecture/index.md b/internal/website/content/en/docs/architecture/index.md index ee7bf96c31..bc0e317f03 100644 --- a/internal/website/content/en/docs/architecture/index.md +++ b/internal/website/content/en/docs/architecture/index.md @@ -1,6 +1,6 @@ --- title: "Architecture" -description: "How services, models, agents, and workflows fit together." +description: "How services, models and agents fit together." --- Go Micro began as a framework for service communication. RPC clients and servers, @@ -9,7 +9,7 @@ without tying their business logic to one infrastructure provider. Storage, configuration, and authentication support that same application boundary. Agents extend this foundation: a service endpoint can also be a tool. The -services → agents → workflows lifecycle describes how these components compose; +services → agents lifecycle describes how these components compose; it is not a requirement to adopt all of them or a replacement for RPC. | Component | Responsibility | Public entry point | @@ -17,7 +17,6 @@ it is not a requirement to adopt all of them or a replacement for RPC. | Service | Implement capabilities and own application data | `micro.NewService` | | Model | Adapt model requests, responses, and tool calls to a provider | `model.Model` | | Agent | Interpret a request and use tools, memory, and execution controls | `micro.NewAgent` | -| Workflow | Coordinate predefined steps, with agent decisions where needed | `micro.NewFlow` | | Application | Combine these components with users, interfaces, and usable outputs | Your program or a runtime such as Mu | ## Service substrate @@ -70,20 +69,6 @@ See [AI Integration](../ai-integration/index.md), [guardrails](../guides/agent-guardrails.md), and [durability and recovery](../guides/durability.md). -## Workflows - -Use `flow` when the sequence is defined: call a service, validate a result, -dispatch to an agent, and save the outcome. Flows can react to broker events or -run through their execution APIs. A prompt-driven flow can also let a model -choose tools; a workflow does not require every step to use a model. - -Flows save checkpoints between steps. Recovery needs persistent storage, and an -interrupted step may execute again. An agent's plan is its working plan; -a workflow is the sequence defined by application code. Neither is automatically -a user-facing task queue or a guarantee that an external action succeeded. - -See [Agents and Workflows](../guides/agents-and-workflows.md). - ## Interop gateways - **`micro api`** exposes service RPC over HTTP. @@ -93,22 +78,6 @@ See [Agents and Workflows](../guides/agents-and-workflows.md). Gateways derive their service and agent descriptions from registry metadata. An application can expose the same capabilities to Go clients, agents, and a UI. -## Services, agents, and flows - -Services expose capabilities and own their data. Agents choose capabilities in -response to a goal. Flows coordinate explicit steps, calling services and agents -where needed. The same service remains usable directly, without a model. - -The next development priority is consistent execution across these boundaries: -run identity, completion, cancellation, retry budgets, approval, and recovery. -Existing checkpoints are useful, but interrupted operations can execute again; -external effects require service-level idempotency. See the [v7 plan](../v7.md) -for the implementation sequence and acceptance criteria. - -Applications can provide interfaces and store outputs using these components. -App generation, rendering, publishing, and product accounts belong to applications -and hosts such as Mu. Go Micro does not define a separate app package. - ## Developer path 1. [Quick Start](../quickstart.md): develop services through conversation. diff --git a/internal/website/content/en/docs/examples/_index.md b/internal/website/content/en/docs/examples/_index.md index c75c402c3f..4952480d5d 100644 --- a/internal/website/content/en/docs/examples/_index.md +++ b/internal/website/content/en/docs/examples/_index.md @@ -7,7 +7,7 @@ weight: 3 Runnable examples are the fastest way to move from reading the guides to changing one thing. Start with the path that matches where you are in the services → -agents → workflows lifecycle. +agents lifecycle. ## Start here @@ -18,10 +18,9 @@ For the provider-free first-agent route, run [`examples/first-agent`](https://gi | 0→1 service | [`examples/hello-world`](https://github.com/micro/go-micro/tree/master/examples/hello-world) | Smallest RPC service with a client call and health checks. | | Provider-free first agent | [`examples/first-agent`](https://github.com/micro/go-micro/tree/master/examples/first-agent) | Smallest service-backed agent with a deterministic mock model; no provider key required. | | First service-backed agent | [`examples/agent-demo`](https://github.com/micro/go-micro/tree/master/examples/agent-demo) | Multi-service project/task/team app with agent playground integration. | -| 0→hero lifecycle | [`examples/support`](https://github.com/micro/go-micro/tree/master/examples/support) | No-secret support-desk story: typed services, an agent, an event-driven flow, and a guardrail. | +| 0→hero lifecycle | [`examples/support`](https://github.com/micro/go-micro/tree/master/examples/support) | No-secret support-desk story: typed services, an agent and a guardrail. | | Planning and delegation | [`examples/agent-plan-delegate`](https://github.com/micro/go-micro/tree/master/examples/agent-plan-delegate) | Two agents collaborate through `plan` and `delegate` over normal Go Micro RPC. | | Durable agent runs | [`examples/agent-durable`](https://github.com/micro/go-micro/tree/master/examples/agent-durable) | Checkpoint and resume a model-directed run without replaying completed tool side effects. | -| Durable workflows | [`examples/flow-durable`](https://github.com/micro/go-micro/tree/master/examples/flow-durable) | Ordered, checkpointed flow steps resume without duplicating completed side effects. | | AI-callable services | [`examples/mcp`](https://github.com/micro/go-micro/tree/master/examples/mcp) | MCP examples that expose service endpoints as model tools. | ## Guide-to-example map @@ -44,19 +43,17 @@ For the provider-free first-agent route, run [`examples/first-agent`](https://gi for the human-readable scenario, then `make harness` for the full CI contract. - [Plan & Delegate](../guides/plan-delegate.md) → run [`examples/agent-plan-delegate`](https://github.com/micro/go-micro/tree/master/examples/agent-plan-delegate). -- [Agents and Workflows](../guides/agents-and-workflows.md) → run - [`examples/flow-durable`](https://github.com/micro/go-micro/tree/master/examples/flow-durable) for deterministic checkpointed steps, [`examples/agent-durable`](https://github.com/micro/go-micro/tree/master/examples/agent-durable) for model-directed checkpointed runs, and [`examples/support`](https://github.com/micro/go-micro/tree/master/examples/support) - for the full services → agents → workflows lifecycle. + for the full services → agents lifecycle. ## Repository examples See the repository [examples index](https://github.com/micro/go-micro/tree/master/examples) for the complete runnable list, including deployment, auth, gRPC interop, MCP, -agent, and flow examples. +and agent examples. ## More diff --git a/internal/website/content/en/docs/getting-started/index.md b/internal/website/content/en/docs/getting-started/index.md index 4b177aa1b0..66764b024a 100644 --- a/internal/website/content/en/docs/getting-started/index.md +++ b/internal/website/content/en/docs/getting-started/index.md @@ -4,7 +4,7 @@ description: "Build a service, use it through an agent, and extend your applicat --- Go Micro connects services through discovery, RPC, and publish/subscribe. Agents -use service endpoints as tools. Workflows coordinate defined sequences of work. +use service endpoints as tools. You can use these parts independently and extend them through Go interfaces. ## Build your first project @@ -37,7 +37,6 @@ loop are also available to your own Go programs. - [Build a service](../client-server.md): implement typed handlers and call them over RPC. - [Build an agent](../guides/your-first-agent.md): give it instructions and services to use as tools. -- [Compose a workflow](../guides/agents-and-workflows.md): combine service calls and agent decisions into defined steps. - [Choose infrastructure](../architecture/index.md): understand the registry, transport, broker, store, and other replaceable components. - [Deploy](../deployment.md): run your application beyond local development. diff --git a/internal/website/content/en/docs/guides/a2a-protocol.md b/internal/website/content/en/docs/guides/a2a-protocol.md index 87133b7c24..011560a227 100644 --- a/internal/website/content/en/docs/guides/a2a-protocol.md +++ b/internal/website/content/en/docs/guides/a2a-protocol.md @@ -4,7 +4,7 @@ title: "Agent2Agent (A2A)" Go Micro speaks the [Agent2Agent (A2A) protocol](https://a2a-protocol.org) — the open standard for agents on different frameworks to discover and call each other over HTTP. The A2A gateway is the agent-side analogue of the [MCP gateway](../mcp.md): MCP exposes your services as tools, A2A exposes your agents as agents. -There is nothing to add to an agent. An agent already registers in the registry with `type=agent` metadata; the gateway discovers it, generates an **Agent Card** from that metadata, and translates incoming A2A tasks to the agent's existing `Agent.Chat` RPC — the same call `delegate` and flows use. +There is nothing to add to an agent. An agent already registers in the registry with `type=agent` metadata; the gateway discovers it, generates an **Agent Card** from that metadata, and translates incoming A2A tasks to the agent's existing `Agent.Chat` RPC — the same call `delegate` uses. ## Run it @@ -143,31 +143,15 @@ outage. If a token is configured, it is sent as `Authorization: Bearer `. ## Calling out to other agents -The gateway makes your agents reachable *from* the A2A ecosystem. The -client (`a2a.Client`) is the other direction: it lets a Go Micro agent or -flow call an agent on any framework, by URL. +Use `a2a.Client` to call an agent on another framework: ```go reply, err := a2a.NewClient("https://other.example.com/agents/research"). Send(ctx, "Summarize the latest on X") ``` -It's wired into the two places that hand off work: - -- **A flow step** — `flow.A2A(url)` is the cross-framework counterpart to - `flow.Dispatch(name)` (which dispatches to a local agent): - - ```go - flow.Step{Name: "research", Run: flow.A2A("https://other.example.com/agents/research")} - ``` - -- **Agent delegate** — when an agent's `delegate` target is an `http(s)` - URL, the subtask is sent to that external agent over A2A instead of to a - locally registered one. Nothing else changes; the model just delegates - to a URL. - -`Send` handles the task lifecycle: if the remote returns a task that isn't -yet terminal, it polls `tasks/get` until it completes. +An agent's `delegate` tool also accepts an HTTP(S) URL as its target. `Send` +polls `tasks/get` until the remote task completes when it is not yet terminal. ## Scope @@ -182,7 +166,7 @@ This is the JSON-RPC binding for task execution: - **`input-required`** task state carries human-input handoffs (for example checkpointed approval pauses) in task status, artifacts, and history; continue the task by sending a follow-up message with the same `taskId` and `contextId`. - **Agent Card** discovery, generated from the registry. -Both directions work: the gateway exposes your agents, and `a2a.Client` (via `flow.A2A` or `delegate` to a URL) calls external ones. The task binding is what makes a Go Micro agent both reachable from, and able to reach, the A2A ecosystem today. +Both directions work: the gateway exposes your agents, and `a2a.Client` (via `delegate` to a URL) calls external ones. The task binding is what makes a Go Micro agent both reachable from, and able to reach, the A2A ecosystem today. ## AP2 mandate layer (opt-in) @@ -210,5 +194,4 @@ ledger. The x402 payment path still performs its own verification and settlement ## See also - [MCP & AI Agents](../mcp.md) — exposing services as tools -- [Agents and Workflows](agents-and-workflows.md) — the agent model - [A2A protocol specification](https://a2a-protocol.org) diff --git a/internal/website/content/en/docs/guides/agent-guardrails.md b/internal/website/content/en/docs/guides/agent-guardrails.md index b469ee2451..34d9c8854f 100644 --- a/internal/website/content/en/docs/guides/agent-guardrails.md +++ b/internal/website/content/en/docs/guides/agent-guardrails.md @@ -117,7 +117,6 @@ These are most important when no human is in the loop. An agent [triggered by an ## See also - [Plan & Delegate](plan-delegate.md) — the agent's built-in tools -- [Agents and Workflows](agents-and-workflows.md) — where agents fit ## Durable human approval diff --git a/internal/website/content/en/docs/guides/agent-harness.md b/internal/website/content/en/docs/guides/agent-harness.md index 649697559f..fd2fbd9639 100644 --- a/internal/website/content/en/docs/guides/agent-harness.md +++ b/internal/website/content/en/docs/guides/agent-harness.md @@ -7,7 +7,7 @@ and tool guardrails. `micro chat` uses this package for its development agent an for routing requests between registered agents. A single registered agent is called directly and owns its model and credentials. -The framework also supplies discovery, RPC, storage, and flows. Those support +The framework also supplies discovery, RPC and storage. Those support agents, but are not substitutes for managing the model's conversation and tools. ## Current limits @@ -30,12 +30,11 @@ agents, but are not substitutes for managing the model's conversation and tools. | Tools | Every service endpoint is an MCP-callable tool from registry metadata — no extra code | Shipped | | Memory | Store-backed agent memory (`AgentMemory`), durable across restarts | Shipped | | Guardrails | `MaxSteps`, `LoopLimit`, `ApproveTool`, tool wrappers — enforced at the call site | Shipped | -| Workflows | Durable flows; `micro.FlowLoop` for run-until-done | Shipped | | Planning / delegation | Built-in `plan` and `delegate` tools on every agent | Shipped | | Discovery & RPC | Registry + client; agents and services find and call each other | Shipped | | Interop | MCP (tools), A2A (agents), x402 (paid tools) | Shipped | | Resilience | Per-call timeout with context propagation; opt-in retry/backoff (`ModelRetry`) across the loop | Shipped | -| Durable runs | Checkpoint and resume an agent run with the same checkpoint backend flows use | Shipped | +| Durable runs | Checkpoint and resume an agent run with agent checkpoint storage | Shipped | | Observability | `RunInfo` → OpenTelemetry spans for runs, model calls, tools, delegation, and failures; persisted run history | Shipped | | Streaming | `model.Stream` through chat, agent, and A2A | In progress | @@ -44,8 +43,7 @@ and the work is happening in the open. ## Durable agent runs -Agents can persist their execution history to the same `Checkpoint` backend as -flows. A checkpointed `Ask` records the run id, original prompt, model result, +Agents can persist their execution history to the `agent.Checkpoint` backend. A checkpointed `Ask` records the run id, original prompt, model result, and completed tool calls. If the process restarts after a tool result has been saved but before the model finishes, `AgentResume` continues the same run and returns the recorded tool result instead of re-running the side effect. If a run already @@ -68,19 +66,8 @@ if err != nil { _ = resp ``` -Choose the boundary deliberately: use a durable flow when the steps are known -(`reserve`, `charge`, `confirm`) and each step has deterministic retry/resume -semantics. Use a checkpointed agent run when the model is deciding which tools to -call or how many turns it needs, while reusing recorded tool results. Flows and agents share the same -`Checkpoint` interface. Recovery still depends on the service handling repeated -actions safely. - -For human-in-the-loop runs that pause through the built-in `request_input` tool, -resume with the operator's response: - -```go -_, err := micro.AgentResumeInput(ctx, agent, runID, "Deploy to us-east-1") -``` +Use an agent when the model needs to choose tools and adapt its next action. +Keep deterministic business logic in services. ## Observing agent runs @@ -124,8 +111,6 @@ layer, not in spite of it: executes the call. - **Agents are services** — they register, load-balance, expose `Agent.Chat`, and are reachable by other agents. -- **Workflows are code paths** — use a flow when the path is known; hand off to an - agent when it isn't. - **Safety lives at execution** — guardrails run on the one path every tool call takes. diff --git a/internal/website/content/en/docs/guides/agent-loops.md b/internal/website/content/en/docs/guides/agent-loops.md deleted file mode 100644 index af9c180aab..0000000000 --- a/internal/website/content/en/docs/guides/agent-loops.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -title: "Agent Loops" ---- - -Most agent work is one-shot: a prompt goes in, an answer comes out. The next -step in agentic systems is the **loop** — run a step over and over, letting the -agent keep working until the goal is met instead of stopping after one pass. One -agent improves an architecture while another removes duplicated abstractions, -both opening pull requests continuously; a draft is refined until it's good -enough; a build is fixed and re-run until it's green. - -The catch is cost and runaway risk: a loop "burns through tokens a lot faster -than a simple Q&A chatbot," and a non-deterministic stop ("keep going until -you're done") has no natural ceiling. So a usable loop needs two things: - -1. a **stop condition** — how it decides it's done, and -2. a **hard cap** — a guardrail that guarantees it always terminates. - -Go Micro gives you both as a flow step: `micro.FlowLoop`. - -## The shape - -`micro.FlowLoop` is a `StepFunc`, so it drops into a flow's ordered, checkpointed -step list like any other step. It runs a **body** step repeatedly, carrying the -flow `State` from one pass to the next, until a stop condition fires or the -iteration cap is hit — whichever comes first. - -```go -f := micro.NewFlow("refactor", - micro.FlowProvider("anthropic"), - micro.FlowSteps( - micro.FlowStep{Name: "improve", Run: micro.FlowLoop( - micro.FlowDispatch("coder"), // the body: an agent does one pass - micro.FlowUntilLLM("Is the refactor complete with no duplicated abstractions left?"), - micro.FlowLoopMax(5), // the ceiling: never more than 5 passes - )}, - ), -) -``` - -## Stop conditions - -**Code-defined** — `FlowUntil` stops when your predicate returns true. Use it -when "done" is something you can measure (tests pass, a score clears a -threshold, a queue is empty): - -```go -micro.FlowUntil(func(_ context.Context, s micro.FlowState, iter int) (bool, error) { - var d Draft - _ = s.Scan(&d) - return d.Quality >= 90, nil -}) -``` - -**Model-judged** — `FlowUntilLLM` asks the flow's model, after each pass, -whether the goal is met, and stops on an affirmative answer. This is the -supervised ("Ralph") loop: the agent decides when it's done, while the cap -still guarantees it stops. It requires a flow model (`FlowProvider`/`FlowAPIKey`). - -```go -micro.FlowUntilLLM("Have all the failing tests been fixed?") -``` - -You can combine both — either firing stops the loop. - -## The guardrail - -`FlowLoopMax(n)` is the ceiling. The body never runs more than `n` times, so the -loop always terminates even if the stop condition never fires. When the cap is -hit, the loop returns the latest state rather than erroring — the guardrail did -its job. **Always set it.** For tighter budgets, keep the cap low and pair the -loop with [agent guardrails](agent-guardrails.md) (e.g. token/spend limits) -and [paid tools](x402-payments.md) (per-call metering) so a background loop -can't run up an unbounded bill. - -## Watching progress - -`FlowOnIteration` runs after each pass — log it, or persist a summary so you can -see how a long-running loop is doing: - -```go -micro.FlowOnIteration(func(iter int, s micro.FlowState) { - log.Printf("pass %d: %s", iter, s.String()) -}) -``` - -## Durability - -A loop runs as a **single flow step**. The flow checkpoints the loop's outcome -(before and after the step) through its [Checkpoint](durability.md), and a -resume re-enters the step — so keep loop bodies safe to repeat. For long loops, -use `FlowOnIteration` for application-owned progress recording; the callback does -not change the engine's resume boundary or automatically skip completed iterations. - -## Run it - -A complete, offline example (no API key — the body and stop condition are plain -Go) is in [`examples/flow-loop`](https://github.com/micro/go-micro/tree/master/examples/flow-loop): - -```bash -go run ./examples/flow-loop/ -# refining until quality >= 90 -# pass 1 → quality 30 -# pass 2 → quality 60 -# pass 3 → quality 90 -# done: {"text":"draft refined (quality 90)","quality":90} -``` - -Swap the body for `micro.FlowDispatch("agent")` or `micro.FlowLLM(...)` and the -stop check for `micro.FlowUntilLLM(...)` to turn it into a real agent loop. - -## See also - -- [Agents and Workflows](agents-and-workflows.md) — flows vs. agents -- [Agent Guardrails](agent-guardrails.md) — bounding what a loop can do -- [Plan & Delegate](plan-delegate.md) — splitting work across agents diff --git a/internal/website/content/en/docs/guides/agent-run-records.md b/internal/website/content/en/docs/guides/agent-run-records.md index f80e0d187d..505dcc8e0c 100644 --- a/internal/website/content/en/docs/guides/agent-run-records.md +++ b/internal/website/content/en/docs/guides/agent-run-records.md @@ -25,9 +25,7 @@ The JSON view emits the public `agent.RunRecord` contract: "summary": { "run_id": "01J...", "agent": "support", - "parent_id": "flow-01J...", - "flow": "daily-ops", - "step": "summarize", + "parent_id": "agent-01J...", "dispatch": "schedule", "trigger": "daily-review", "status": "done", @@ -62,15 +60,9 @@ process uses the same agent name and state store. ## Fields -The summary contains run and parent ids, agent identity, originating flow and -step, dispatch and trigger, trace/span correlation, start and update times, -duration, event count, derived status, latest checkpoint and stage, latest event -and error, and cumulative spend. When a flow dispatched the agent, the human -view prints the exact parent command: - -```sh -micro inspect flow --run -``` +The summary contains run and parent ids, agent identity, dispatch and trigger, +trace/span correlation, start and update times, duration, event count, status, +latest checkpoint and stage, latest event and error, and cumulative spend. Each event contains its timestamp, run lineage, trace/span correlation, agent, kind, and the metadata relevant to that kind. Model events can include provider, @@ -84,8 +76,6 @@ Go callers can load the same contract directly: record, err := agent.LoadRunRecord(stateStore, "support", runID) ``` -See [Flow run records](flow-run-records.md) for the parent side of the same -execution graph, including service targets and child agent run ids. ## Privacy and redaction diff --git a/internal/website/content/en/docs/guides/agents-and-workflows.md b/internal/website/content/en/docs/guides/agents-and-workflows.md deleted file mode 100644 index c8321ab0dc..0000000000 --- a/internal/website/content/en/docs/guides/agents-and-workflows.md +++ /dev/null @@ -1,199 +0,0 @@ ---- -title: "Agents and Workflows" ---- - -Go Micro's AI primitives map directly onto the taxonomy in Anthropic's [Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents). That post draws one distinction that matters: - -- **Workflows** — "LLMs and tools orchestrated through **predefined code paths**." Deterministic. -- **Agents** — "LLMs **dynamically direct their own processes** and tool usage." Model-driven. - -Go Micro has both, plus the harness they run inside — and expresses them as plain services and tools, with no graph DSL. That's deliberate: the same post advises finding "the simplest solution possible" and being "cautious with frameworks… they obscure the underlying mechanics." - -## The building block: the augmented LLM - -Anthropic's foundational unit is the *augmented LLM* — a model with tools, retrieval, and memory. In Go Micro: - -| Augmented LLM | Go Micro | -|---|---| -| the model | `ai` package (7 providers, one interface) | -| tools | every service endpoint, discovered from the registry | -| memory | the `store` (file, Postgres, NATS KV) | - -Every endpoint is automatically a tool, so the augmented LLM is the default, not something you assemble. - -## Workflow ↔ `flow` - -A [`Flow`](../ai-integration/index.md) is a workflow in Anthropic's exact sense: a **predefined path** — an event on a broker topic triggers a prompt with a fixed set of tools, deterministically. Use it when the task is well-defined and you want predictability. - -```go -f := micro.NewFlow("onboard-user", - micro.FlowTrigger("events.user.created"), - micro.FlowPrompt("New user {{.Data}} — create a workspace and send a welcome email."), - micro.FlowProvider("anthropic"), -) -``` - -### Flow triggers, Agent reasons - -A flow doesn't have to do the reasoning itself. Point it at an agent and it becomes a pure trigger — the event fires, the flow renders the prompt, and a registered agent handles it over RPC with its full capabilities (plan, delegate, memory, guardrails): - -```go -f := micro.NewFlow("onboard-user", - micro.FlowTrigger("events.user.created"), - micro.FlowPrompt("New user {{.Data}} — get them set up."), - micro.FlowAgent("conductor"), // the conductor agent reasons; the flow only triggers -) -``` - -This is the clean seam between the two halves of the taxonomy: the *workflow* (deterministic, event-driven) hands off to the *agent* (dynamic). One engine, two front doors — an event (`flow`) or a conversation (`agent.Ask`). - -### Ordered, durable steps - -A flow can be a **task made of ordered steps** rather than a single turn — the predefined path made explicit. Each step is checkpointed before and after, so if the process dies mid-run the run **resumes at the step it stopped on**, without re-running steps whose completion was successfully checkpointed. An interrupted step can repeat its side effects. This is durable execution, store-backed by default, with no separate workflow engine. - -```go -f := micro.NewFlow("checkout", - micro.FlowTrigger("events.order.placed"), - micro.FlowRetry(2), // retry each step; per-step override available - micro.FlowSteps( - micro.FlowStep{Name: "reserve", Run: micro.FlowCall("inventory", "Inventory.Reserve")}, - micro.FlowStep{Name: "charge", Run: micro.FlowCall("payment", "Payment.Charge")}, - micro.FlowStep{Name: "welcome", Run: micro.FlowDispatch("comms")}, // hand a step to an agent - ), - // The default file store must live on persistent storage across restarts. - // WithCheckpoint can supply another backend; no external-engine adapter is implied. -) -``` - -A step's action is an RPC (`FlowCall`), an agent hand-off (`FlowDispatch`), one model turn (`FlowLLM`), or any function. `State` carries a typed payload (`Set`/`Scan`) plus a `Stage` marker — the resume point. Runs are retained for success and failure (audit) unless you set `FlowDeleteOnSuccess`. On restart, `f.Pending(ctx)` lists incomplete runs and `f.Resume(ctx, runID)` continues one. See [examples/flow-durable](https://github.com/micro/go-micro/tree/master/examples/flow-durable). - -The pluggability is the usual go-micro shape: the built-in `Checkpoint` is store-backed (swap the store backend freely); implement the `Checkpoint` interface to delegate durability to an external engine. The default file store survives a process restart only while its files are retained. See [Durability and Recovery](durability.md) for waiting/input, retries, agent checkpoints, and replay limitations. - -## Agent ↔ `agent` - -An [`Agent`](plan-delegate.md) is an agent in Anthropic's exact sense: it **directs itself** — plans, calls tools, evaluates results, and decides the next step over many turns, with memory across them. Use it when you want flexibility and model-driven decisions. - -```go -a := micro.NewAgent("conductor", - micro.AgentServices("task"), - micro.AgentProvider("anthropic"), -) -a.Ask(ctx, "Plan the launch, create the tasks, and have comms notify the owner.") -``` - -### Long-running memory - -Agents use store-backed conversation memory by default, scoped under the agent's -name. That makes short restarts boring: the next `Ask` reloads the retained -history from the same store backend you already use for services and flows. -Long-running agents can also keep model context bounded without losing useful -prior context. If you want retrieval without summaries, enable bounded active -context plus a durable archive of every turn: - -```go -a := micro.NewAgent("conductor", - micro.AgentServices("task"), - micro.AgentProvider("anthropic"), - micro.AgentRetrievalMemory(40), // active messages kept in prompt context - micro.AgentMemoryRecallLimit(5), // archived turns recalled per Ask -) -``` - -`AgentRetrievalMemory(activeLimit)` switches the default memory to a store-backed -retriever. The active conversation is capped at `activeLimit`, every turn is -archived in the same scoped store used by the agent, and future asks inject -matching archived turns ahead of active context. The built-in ranking is -deterministic and credential-free for CI. - -When you also want a rolling summary in active context, use compacting memory: - -```go -a := micro.NewAgent("conductor", - micro.AgentServices("task"), - micro.AgentProvider("anthropic"), - micro.AgentCompactMemory(40, 12), // max active messages, recent messages kept verbatim - micro.AgentMemoryRecallLimit(5), // compacted turns recalled per Ask -) -``` - -`AgentCompactMemory(maxMessages, keepRecent)` switches the default memory to a -deterministic compactor. Once active history grows past `maxMessages`, older -turns move into the durable archive, a provider-neutral summary is injected into -active context, and the newest `keepRecent` messages stay verbatim. On future -asks, archived turns whose text matches the current request are recalled ahead of -the active context. Teams that need embeddings or a vector database can still -provide their own `AgentMemory` implementation. - -This is harness memory, not prompt-layer orchestration: services remain the -capabilities, agents remain the dynamic decision makers, and flows remain the -durable predefined paths. Compaction only keeps a scheduled or looping agent from -turning every past turn into model context while still letting it remember facts -that matter to the current service → agent → workflow run. - -Checkpointed agent runs and compacted memory share the same store-backed shape. -If a provider call fails after the prompt has been recorded, `agent.Resume` uses -the checkpointed run id and does not append that same user turn a second time; -completed tool results and recalled archived memory remain available for the -retry. - -## The patterns — most are already here - -Anthropic lists five workflow patterns. Go Micro implements the two richest ones natively, as services and tools, and the rest are ordinary compositions: - -| Pattern | Go Micro | -|---|---| -| **Routing** — classify input, dispatch to a specialist | `micro chat`'s router — discovers agents, classifies intent, routes over RPC | -| **Orchestrator-workers** — a central LLM breaks down a task, delegates to workers, synthesizes | the `agent` with **`plan`** (break down) + **`delegate`** (hand to workers) + reply (synthesize) — see [Plan & Delegate](plan-delegate.md) | -| **Prompt chaining** — sequential steps | chain flows, or steps in an agent's plan | -| **Parallelization** — independent subtasks at once | Go concurrency + multiple services/agents; fan out with `delegate` | -| **Evaluator-optimizer** — one LLM generates, another critiques in a loop | two agents over RPC (generator + evaluator) | - -The orchestrator-workers example is worth calling out: the conductor agent that plans, creates tasks, and delegates the notification to a `comms` agent **is** orchestrator-workers — built without a graph engine. See [examples/agent-plan-delegate](https://github.com/micro/go-micro/tree/master/examples/agent-plan-delegate). - -## Choosing - -Follow Anthropic's guidance: - -- Start with the **augmented LLM** (a single service call through a model). Most tasks need nothing more. -- Reach for a **workflow** (`flow`) when the path is well-defined and you want predictability. -- Reach for an **agent** (`agent`) when the task needs flexibility and model-driven decisions — and accept the higher cost and the need for guardrails. - -## Guardrails - -Anthropic is emphatic that autonomous agents need stopping conditions, human checkpoints, and sandboxed testing. Go Micro's agent has two built-in guardrails, both as plain options: - -**Stopping condition** — `MaxSteps` bounds the number of actions an agent may take per `Ask`. Once exceeded, further tool calls are refused and the model is told to stop and summarize. - -```go -micro.NewAgent("conductor", - micro.AgentServices("task"), - micro.AgentMaxSteps(8), // at most 8 tool calls per request -) -``` - -**Human-in-the-loop** — `ApproveTool` gates each action before it runs. Return `false` to block it; the reason is shown to the model so it can adapt. The internal `plan` tool is never gated (it's bookkeeping, not an action). - -```go -micro.NewAgent("conductor", - micro.AgentServices("task"), - micro.AgentApproveTool(func(tool string, input map[string]any) (bool, string) { - if strings.HasPrefix(tool, "billing_") { - return false, "billing actions require human sign-off" - } - return true, "" - }), -) -``` - -These are harness guardrails, not a separate policy engine — a counter and a callback on the path every tool call already takes. For anything that must be predictable, still prefer a **workflow**, and test agents against the [integration harness](https://github.com/micro/go-micro/tree/master/internal/harness/plan-delegate). - -## Why no graph DSL - -Anthropic: "be cautious with frameworks… understand the underlying code." Go Micro's answer is that there is no separate framework to understand — the harness is the service runtime. Workflows and agents are services, and tool use is RPC. `plan` and `delegate` are tools, not a graph DSL. The patterns above are code you can read, not a DSL you have to learn. That's the [direction we took going all in on AI](/blog/2026/06/04/going-all-in-on-model.html). - -## See also - -- [Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents) — Anthropic -- [Plan & Delegate](plan-delegate.md) — the agent's built-in tools -- [Agent Integration Patterns](agent-patterns.md) — multi-agent architectures -- [AI Integration](../ai-integration/index.md) — agents, flows, and the model interface diff --git a/internal/website/content/en/docs/guides/comparison.md b/internal/website/content/en/docs/guides/comparison.md index 22c634ad54..eab64955aa 100644 --- a/internal/website/content/en/docs/guides/comparison.md +++ b/internal/website/content/en/docs/guides/comparison.md @@ -155,8 +155,7 @@ through a sidecar from many languages. [Dapr Agents](https://docs.dapr.io/develo adds an agent framework on top of those runtime capabilities. Go Micro overlaps with Dapr on distributed-systems primitives, but the product -shape is different: Go Micro is a Go framework where services, agents, tools, -and flows are built from the same runtime. A service endpoint can become an +shape is different: Go Micro is a Go framework where services, agents and tools are built from the same runtime. A service endpoint can become an AI-callable tool, and an agent is itself a registered service with memory, guardrails, planning, delegation, MCP, and A2A around it. @@ -211,8 +210,6 @@ Kubernetes deployment first-class. itself an agent. 4. If your platform already uses Dapr, keep Dapr components behind the service boundary and let Go Micro present the agent/tool contract. -5. Move deterministic multi-step work into flows only after the service/tool - boundary is stable. ## vs Agent Frameworks (Google ADK) @@ -225,7 +222,7 @@ and supports multi-agent systems, evaluation, and deployment to Cloud Run / GKE. They overlap on agents but solve different problems. ADK is a library for building an agent process — you define an agent, its tools, and a model, then run and deploy it. Go Micro is the harness around agents once they operate real systems: service -discovery, inter-service RPC, pub/sub, durable flows, tool execution, and deployment. +discovery, inter-service RPC, pub/sub, tool execution, and deployment. Those pieces are out of scope for ADK, and you bring your own. In Go Micro an agent is built as an ordinary service: it registers in the registry, @@ -241,7 +238,6 @@ also gives you the discovery, RPC, pub/sub, config, and deployment around them. | **Inter-service RPC, load balancing, pub/sub** | Built-in | Not in scope | | **MCP** | Every service endpoint is automatically an MCP tool (no extra code) | MCP tools, wired explicitly | | **A2A** | Agents are A2A-reachable services | Supported | -| **Deterministic orchestration** | Flows | Graph workflows | | **Multi-agent** | Agents discover & call each other via the registry; `plan`/`delegate` built in | Composition, routing, workflow patterns | | **Evaluation suite** | Harnesses/conformance today; first-class evaluation is a gap | Yes (criteria, user/env simulation, metrics) | | **Context engineering** | Store-backed memory | "Context as source code" (auto filter/summarize/token tracking) | @@ -258,7 +254,7 @@ also gives you the discovery, RPC, pub/sub, config, and deployment around them. registered, discoverable, load-balanced, and deployed the same way - You want your existing services to become agent tools with **zero extra code** (every endpoint is an MCP tool automatically) -- You're building in Go and want one set of primitives for services, agents, and flows +- You're building in Go and want one set of primitives for services and agents ### They interoperate @@ -280,14 +276,12 @@ SDK you run alongside your services** — you compose agents and tools into grap conditional workflows, and your microservices (tRPC) live separately and are called into. Go Micro starts from the premise that **an agent is a service** — one runtime where every endpoint is automatically a tool, an agent registers and is discovered and -load-balanced like anything else, and workflows are durable code paths rather than a -graph DSL. The premise is that the line between "your services" and "your agents" is +load-balanced like anything else, and deterministic business logic stays in service code. The premise is that the line between "your services" and "your agents" is accidental complexity; remove it and there's less to wire and keep in sync. | | Go Micro | tRPC-Agent-Go | |---|----------|---------------| | **Primary unit** | A harnessed service (an agent is a service with an LLM inside) | An agent | -| **Orchestration** | Durable `flow` steps + `Loop` — plain code paths | Graph / Chain / Parallel / Cycle agents (graph DSL) | | **Services as tools** | Every endpoint is automatically an MCP tool | Function tools + MCP, wired explicitly | | **Service runtime** | Built in — agents *are* services (registry, RPC, load balancing, pub/sub) | Runs alongside your existing service stack (tRPC) | | **MCP / A2A** | Both, generated from the registry | Both | @@ -302,10 +296,10 @@ accidental complexity; remove it and there's less to wire and keep in sync. - You want first-class evaluation and self-evolution today, with a large team behind it ### When to choose Go Micro -- You want one runtime where services, agents, and flows are the same primitives — +- You want one runtime where services and agents are the same primitives — registered, discoverable, and deployed the same way - You want your existing services to become agent tools with zero extra code -- You prefer durable flows and plain code paths over a graph DSL, in a small, +- You prefer plain Go code paths in a small, independent framework you can hold in your head ### They interoperate diff --git a/internal/website/content/en/docs/guides/debugging-agents.md b/internal/website/content/en/docs/guides/debugging-agents.md index e67bec9bbf..aa4f976f06 100644 --- a/internal/website/content/en/docs/guides/debugging-agents.md +++ b/internal/website/content/en/docs/guides/debugging-agents.md @@ -1,16 +1,16 @@ --- title: Debugging your agent -description: "Use this guide when an agent surprises you: it answered without using a service, called the wrong endpoint, looped, lost memory, refused a tool, or behaved differently when a flow handed work to it." +description: "Use this guide when an agent surprises you: it answered without using a service, called the wrong endpoint, looped, lost memory, refused a tool." --- ```sh micro run # start services, agents, gateway, dashboard micro chat # reproduce one turn -micro inspect ... # read the recorded run or workflow history +micro inspect ... # read the recorded agent run history ``` Debug the lifecycle in the same order Go Micro runs it: first prove the service is registered and callable, then inspect the agent run that chose tools, then inspect -any workflow that handed off to the agent. +the services used by the agent. Use the recovery command that matches where you are in the first-agent journey: @@ -200,28 +200,6 @@ check that all of these are stable across restarts: - whether compaction/retrieval limits are intentionally hiding older turns from the active model context. -## 6. Inspect workflow handoffs - -If a flow triggered the agent, inspect the flow too. The flow history tells you -which durable stage dispatched to the agent and whether a run is still pending: - -```sh -micro inspect flow intake -micro inspect flow intake --pending -micro inspect flow intake --stage notify -micro inspect flow intake --json -``` - -The older flow-specific command remains available for listing runs: - -```sh -micro flow runs intake -``` - -Use the flow run id and the agent run id together when debugging handoffs: the -flow explains why work started and where it checkpointed; the agent run explains -which model/tool steps happened after the handoff. - ## 7. Add traces when metadata is not enough For local CLI debugging, `micro inspect` is the fastest path. For production or @@ -243,10 +221,9 @@ store prompt content. | Symptom | What to inspect | Common fix | | --- | --- | --- | | Agent answers without calling a service | `micro services`, direct `micro call`, then `micro inspect agent ` | Register the service, include it in `micro.AgentServices(...)`, or improve endpoint comments and examples. | -| Agent loops or burns steps | `micro inspect agent --status error` and wrapper logs | Add or lower `micro.AgentMaxSteps(...)` / `micro.AgentLoopLimit(...)`; move predictable work into a flow. | +| Agent loops or burns steps | `micro inspect agent --status error` and wrapper logs | Add or lower `micro.AgentMaxSteps(...)` / `micro.AgentLoopLimit(...)`; implement predictable work in a service. | | Tool is refused before it runs | Wrapper logs, `ToolResult.Refused`, `micro inspect agent --status refused` | Update `micro.AgentApproveTool(...)` policy or prompt the user for explicit approval before retrying. | | Memory is missing after restart | Agent name, store backend, `WithMemory`, compaction/retrieval settings | Use the default store-backed memory with a persistent store, or persist your custom memory backend. | -| Flow handoff appears stuck | `micro inspect flow --pending`, then `micro inspect agent ` | Resume or fail the pending flow run; confirm the dispatched agent completed or timed out. | | Provider failed or timed out | `micro inspect agent --status timeout` / `--status rate_limited` | Retry with the same provider/model, raise deadlines where appropriate, or enable provider retries for transient errors. | | Tool call appears as assistant text | Agent run history and provider conformance checks | Keep provider packages current; Go Micro normalizes provider-emitted text tool calls, and conformance tests guard this behavior. | @@ -256,7 +233,6 @@ When you cannot explain the run locally, include: ```sh micro inspect agent --limit 5 --json -micro inspect flow --limit 5 --json micro services micro call '{}' ``` diff --git a/internal/website/content/en/docs/guides/durability.md b/internal/website/content/en/docs/guides/durability.md index c2e042a632..6eb174e54a 100644 --- a/internal/website/content/en/docs/guides/durability.md +++ b/internal/website/content/en/docs/guides/durability.md @@ -1,125 +1,16 @@ --- -title: "Durability and Recovery" +title: "Agent durability" --- -# Durability and recovery +Agents can opt into checkpointing with `agent.WithCheckpoint` and +`agent.StoreCheckpoint`. Keep the store across restarts and recreate the agent +with the same name and configuration before resuming a run. -Go Micro implements checkpointed flow steps and opt-in checkpointed agent runs. -Conversation memory, execution checkpoints, and tracing are separate mechanisms. -This page describes the shipped contract; the original -[design note](https://github.com/micro/go-micro/blob/master/internal/docs/DURABLE_EXECUTION_DESIGN.md) -is historical, not an implementation checklist. +Completed tool results are reused on resume. A crash after an external action +but before its result is saved can still repeat that action. Make writes +idempotent; checkpointing does not provide exactly-once effects or a transaction +across services. Run one owner for each checkpointed execution. -## Storage and recovery boundaries - -| Mechanism | Default and persisted state | Recovery boundary | -|---|---|---| -| Agent memory | Store-backed conversation history, unless custom or in-memory memory is selected | Restores conversation context; does not by itself resume interrupted tool execution | -| Ordered flow | Store-backed `flow.Checkpoint` when `Steps` is non-empty | Saves before and after each step; resumes from the saved `State.Stage` | -| Agent run | Opt in with `agent.WithCheckpoint` / `micro.AgentWithCheckpoint` | Saves run input, status, completed tool results, and final response for explicit resume | -| OpenTelemetry | Configure a trace provider | Observes runs and steps; spans are not the checkpoint store or a recovery scheduler | - -`store.DefaultStore` is the file store under `~/micro/store/`. Its files must -survive the process/container lifetime; an ephemeral volume is not restart -recovery. `store.NewMemoryStore()` does not survive process exit. A custom store -or checkpoint backend determines its own persistence and failure guarantees. -`flow.StoreCheckpoint(store, scope)` isolates runs in database `flow`, table -`scope`; reuse the same backend and scope when recovering. - -Recovery is explicit. Reconstruct the flow/agent with compatible configuration -and call the appropriate resume API. Persisting a checkpoint does not install a -background recovery worker or migrate checkpoints when step names/configuration -change. - -## Flow runs, waiting, and retries - -`flow.Run` holds the run ID and parent ID, flow name, state (`Stage` and serialized -`Data`), step records, status, optional awaited input, and timestamps. Successful -and failed runs are retained unless `DeleteOnSuccess` is enabled. - -- `Resume(ctx, runID)` continues from the saved stage; a completed run is a no-op. - A step whose completion was successfully saved is skipped. A step still - recorded as `in_progress` can execute again. -- `Pending` excludes completed and `waiting` runs. `ResumePending` processes - pending runs oldest first and stops at the first error, returning its run ID. -- `Await` / `AwaitStep` save a `waiting` run and return cleanly. `Waiting` lists - those runs. `ResumeWith(ctx, runID, input)` uses the supplied string as the - awaited step's output state and continues at the next step; it does not merge - the string into the previous JSON payload automatically. -- `Retry(n)` allows up to `n` retries after the first attempt. A positive - `Step.Retry` overrides it; `Step.Retry == 0` inherits the flow default, so zero - does not disable an inherited retry policy. Context cancellation/deadlines - stop retries, including backoff waits. -- `Loop` is one flow step. Its iterations are not independently checkpointed by - the engine. `OnIteration` is a callback for application-owned progress; it does - not automatically make the loop resume at that iteration. - -A `Dispatch` step calls `Agent.Chat` and propagates the parent run ID. That -lineage is not an instruction to resume an existing child agent run: replaying -an interrupted dispatch can create another agent invocation. - -## Agent runs and tool replay - -With a checkpoint configured, `agent.Resume` returns a completed run's saved -response without invoking the model again. An unfinished resumable run re-enters -agent execution with its saved input and completed tool history; model work can -run again. `ResumeStreamAsk` supplies the streaming resume path. A human-input -pause requires `ResumeInput`, rather than plain `Resume`. - -Completed tool results are reused within the run by **tool name plus -JSON-serialized input**, not by the provider's tool-call ID. Identical calls in -one run therefore share a completed result. This is not a cross-run idempotency -key and does not guarantee that a model will choose the same arguments after a -restart. - -Agent pending runs exclude terminal `done`, `canceled`, and `expired` statuses. -Interrupted `timeout` and `rate_limited` runs remain pending and can resume with -a fresh context, reusing saved input and completed tool results. Paused runs can -still appear in pending results; an input-required pause needs the input helper, so an unattended -`ResumePending` loop can stop there. - -## What is not guaranteed - -- **No exactly-once external side effects.** A crash after an external action - succeeds but before its completion is saved can repeat that action. Flow - retries can repeat it too. Use application/callee idempotency or reconciliation - for payments, provisioning, and other irreversible actions. -- **No checkpoint transaction spanning an external service.** Flow checkpoint - errors are returned, but the agent tool wrapper's intermediate saves are - best-effort. Do not rely on replay suppression after a storage failure. -- **No multi-replica execution lease in the `Checkpoint` interface.** Its methods - are Save, Load, Delete, and List; coordinate concurrent recovery externally. -- **No universal external-engine adapter.** `Checkpoint` is an extension seam; - it does not itself provide a Temporal/Restate integration or their guarantees. - -Checkpoint payloads and tool results can contain application data. Conversation -memory and checkpoints are not made private merely by enabling tracing; choose -appropriate storage access, retention, and redaction for each separately. - -## No-secret verification - -From the repository root, run the existing deterministic tests: - -```sh -go test ./flow -run 'TestFlow(CheckpointResume|AwaitAndResumeWith|StepRetry|CheckpointSaveFailureStopsRun)' -go test ./agent -run 'Test(ResumeFailedCheckpointAfterFreshAgentRestart|ResumePendingAfterFreshAgentRestartDoesNotReplayCompletedTool|HumanInputPauseResumesSameRunWithInput|ResumeStreamAskDoesNotReplayCompletedTool)' -go test ./agent ./flow -run 'Test.*(OTel|Trace|Span)' -go run ./examples/agent-durable -``` - -These tests use controlled models/stores; the agent example uses an in-memory -store and demonstrates a checkpointed tool result being reused after a simulated -interruption. Fresh-agent tests reconstruct the agent over the same test store. -They are not process-kill, disk-loss, multi-replica, or real-provider guarantees. -For deployment validation, also exercise restart with the actual persistent -backend and volume configuration. - -## Source of truth - -- [Flow records, checkpoint backend, resume and retry](https://github.com/micro/go-micro/blob/master/flow/steps.go) -- [Loop boundary](https://github.com/micro/go-micro/blob/master/flow/loop.go) -- [Agent checkpoint and tool deduplication](https://github.com/micro/go-micro/blob/master/agent/checkpoint.go) -- [Agent execution and memory setup](https://github.com/micro/go-micro/blob/master/agent/agent.go) -- [Streaming resume](https://github.com/micro/go-micro/blob/master/agent/stream.go) -- [Default store](https://github.com/micro/go-micro/blob/master/store/store.go) -- [Remaining agent/flow design discussion](https://github.com/micro/go-micro/issues/4816) +Use `micro agent history` and `micro inspect agent` to inspect agent runs. +See the [durable agent example](https://github.com/micro/go-micro/tree/master/examples/agent-durable) +and [agent run records](agent-run-records.md). diff --git a/internal/website/content/en/docs/guides/flow-run-records.md b/internal/website/content/en/docs/guides/flow-run-records.md deleted file mode 100644 index de78dcb55f..0000000000 --- a/internal/website/content/en/docs/guides/flow-run-records.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Flow run records -description: "Inspect a versioned Go Micro flow execution and navigate its service and agent lineage." ---- - -A flow run record is the durable map of one workflow execution: how it started, -which steps ran, which services they called, and which agent runs they created. -List runs to find an id, then inspect the complete record: - -```sh -micro inspect flow daily-ops -micro inspect flow daily-ops --run -micro inspect flow daily-ops --run --json -``` - -The human view prints dispatch and trigger origin followed by every step. A -`flow.Call` step records its service and endpoint. A `flow.Dispatch` step records -the agent name and returned child run id. For each child it prints a command you -can follow directly: - -```sh -micro inspect agent --run -``` - -The JSON view emits the public `flow.RunRecord` contract: - -```json -{ - "schema_version": 1, - "run": { - "id": "flow-01J...", - "flow": "daily-ops", - "dispatch": "schedule", - "trigger": "daily-review", - "status": "done", - "steps": [ - {"name": "load", "status": "done", "service": "reports", "endpoint": "Reports.Load"}, - {"name": "summarize", "status": "done", "agent": "ops", "child_run_id": "agent-01J..."} - ] - } -} -``` - -Use `schema_version` before decoding records across Go Micro releases. Go -callers can load the same contract from any checkpoint implementation: - -```go -record, err := flow.LoadRunRecord(ctx, checkpoint, "daily-ops", runID) -``` - -Execution identity also travels in Go Micro RPC metadata. A service or agent can -call `model.RunInfoFrom(ctx)` to recover the flow run, current step, dispatch, and -trigger without changing its request schema. Agent runs replace the run id with -their own identity and retain the flow run as `parent_id`; their service tools -receive that same lineage. - -Unlike the agent event timeline, a flow checkpoint includes `state.data` and -truncated step results so it can resume work. Treat the whole record as -application data. Names, ids, errors, triggers, and endpoint names can also be -sensitive. Apply the same access controls and retention policy used for flow -checkpoints before exporting a record. diff --git a/internal/website/content/en/docs/guides/install-troubleshooting.md b/internal/website/content/en/docs/guides/install-troubleshooting.md index e2bb40f4bd..52ccef59f1 100644 --- a/internal/website/content/en/docs/guides/install-troubleshooting.md +++ b/internal/website/content/en/docs/guides/install-troubleshooting.md @@ -92,7 +92,7 @@ After install verification succeeds, continue in order: 2. [No-secret first-agent transcript](no-secret-first-agent.md) — prove an agent can use services without a provider key. 3. [Your First Agent](your-first-agent.md) — build and chat with your own service-backed agent. 4. [Debugging your agent](debugging-agents.md) — inspect registration, tool calls, run history, and provider failures. -5. [0→hero Reference](zero-to-hero.md) — walk the full services → agents → workflows lifecycle. +5. [0→hero Reference](zero-to-hero.md) — walk the full services → agents lifecycle. For repository contributors, `make install-smoke` runs the same installer seam against a local build without network access. diff --git a/internal/website/content/en/docs/guides/micro-loop.md b/internal/website/content/en/docs/guides/micro-loop.md index c54ae39416..e26cf6caad 100644 --- a/internal/website/content/en/docs/guides/micro-loop.md +++ b/internal/website/content/en/docs/guides/micro-loop.md @@ -112,6 +112,6 @@ Closes #5678 ``` Use the North Star to keep the queue honest: favor small improvements that move -developers through the services → agents → workflows lifecycle, and surface +developers through the services → agents lifecycle, and surface breaking API or brand/positioning decisions for humans instead of auto-merging them. diff --git a/internal/website/content/en/docs/guides/migration/v5-to-v6.md b/internal/website/content/en/docs/guides/migration/v5-to-v6.md index 6994854e9f..6accda2860 100644 --- a/internal/website/content/en/docs/guides/migration/v5-to-v6.md +++ b/internal/website/content/en/docs/guides/migration/v5-to-v6.md @@ -44,26 +44,8 @@ that an agent, not just a human on a trusted network, can reach an endpoint. - **Self-signed certs (local/dev):** opt out with `MICRO_TLS_INSECURE=true`, or call `tls.InsecureConfig()` directly. -## 3. `NewService` is the service constructor - -The service constructor is now symmetric with `NewAgent` and `NewFlow`: - -```go -service := micro.NewService("greeter", micro.Address(":8080")) -agent := micro.NewAgent("task-mgr", micro.AgentServices("task")) -flow := micro.NewFlow("onboard", micro.FlowTrigger("events.user.created")) -``` - -- `micro.New("greeter", ...)` still works as a **deprecated alias** — no rush, - but prefer `NewService`. -- The old name-less form `micro.NewService(micro.Name("greeter"), ...)` is - **removed**; pass the name positionally: `micro.NewService("greeter", ...)`. - -Generated services already use `NewService` — re-running `micro new` or -`micro run --prompt` emits the v6 form. - ## That's it -No other API changed. Agents, services, flows, the registry/broker/store +No other API changed. Agents, services, the registry/broker/store interfaces, MCP, A2A, and x402 all work as they did — just under `go-micro.dev/v6` and secure by default. diff --git a/internal/website/content/en/docs/guides/no-secret-first-agent.md b/internal/website/content/en/docs/guides/no-secret-first-agent.md index a649adbd8a..086aa64170 100644 --- a/internal/website/content/en/docs/guides/no-secret-first-agent.md +++ b/internal/website/content/en/docs/guides/no-secret-first-agent.md @@ -5,11 +5,11 @@ title: "No-secret first-agent transcript" This is the fastest first-agent success path when you do not have a provider key handy. It starts from the maintained `examples/support` app and uses the repository harness that CI already runs: real Go Micro services, registry, -broker, client, store, agent loop, flow handoff, and guardrail code with only the +broker, client, store, agent loop, and guardrail code with only the LLM provider mocked. Use it before the live-provider [Your First Agent](your-first-agent.md) -walkthrough when you want to see the services → agents → workflows lifecycle run +walkthrough when you want to see the services → agents lifecycle run end to end with no secrets. ## What this proves @@ -17,7 +17,6 @@ end to end with no secrets. - **Services** expose typed `customers`, `tickets`, and `notify` endpoints. - **The `support` agent** discovers those endpoints as tools and uses them to triage a ticket. -- **The `intake` flow** turns a `ticket.created` event into an agent run. - **The approval gate** intercepts the customer email action before the tool executes. @@ -61,7 +60,7 @@ support agent: Hi Alice — thanks for reaching out... ``` That single run is the no-secret version of the first-agent loop: a service -capability exists, an agent calls it as a tool, and workflow infrastructure can +capability exists, an agent calls it as a tool, and application code can trigger and inspect the work. ## CI-backed check @@ -74,7 +73,7 @@ go test ./examples/support -run TestRunSupportMockSmoke -count=1 ``` For the broader no-secret contract that also checks scaffold, chat/inspect CLI -boundaries, flow history, deploy dry-run, and mock provider conformance, run: +boundaries, agent history, deploy dry-run, and mock provider conformance, run: ```sh make harness diff --git a/internal/website/content/en/docs/guides/plan-delegate.md b/internal/website/content/en/docs/guides/plan-delegate.md index fb26eba763..9f34cc76cb 100644 --- a/internal/website/content/en/docs/guides/plan-delegate.md +++ b/internal/website/content/en/docs/guides/plan-delegate.md @@ -154,5 +154,5 @@ The full, runnable code is in [examples/agent-plan-delegate](https://github.com/ `plan` and `delegate` don't add a new layer to the framework — they're tools, the same primitive everything else uses. That's deliberate: services are the only abstraction, the LLM calls them as tools, and an agent's own capabilities are no exception. - [Agent Integration Patterns](agent-patterns.md) — Pattern 9 covers planning and delegation -- [AI Integration](../ai-integration/index.md) — agents, flows, and the model interface +- [AI Integration](../ai-integration/index.md) — agents and the model interface - [Store](../store.md) — where agent memory lives diff --git a/internal/website/content/en/docs/guides/provider-conformance.md b/internal/website/content/en/docs/guides/provider-conformance.md index 788f17748b..80ecffaac1 100644 --- a/internal/website/content/en/docs/guides/provider-conformance.md +++ b/internal/website/content/en/docs/guides/provider-conformance.md @@ -3,9 +3,9 @@ title: "Provider Conformance Matrix" --- Go Micro treats model providers as interchangeable pieces of the same agent -harness: services expose tools, agents reason over them, and workflows stitch the +harness: services expose tools and agents reason over them, connecting the work together. The conformance harness keeps that promise honest by running the -same deterministic services → agents → workflows scenarios against every +same deterministic services → agents scenarios against every configured provider. The live harness is in `internal/harness/provider-conformance`. It skips @@ -70,7 +70,7 @@ Use `-providers` to select a provider and `-harnesses` to narrow the scenario: ```sh go run ./internal/harness/provider-conformance \ -providers openai,anthropic \ - -harnesses agent-flow,plan-delegate + -harnesses agent,a2a-streaming ``` By default missing live-provider keys are reported as skips. Add @@ -102,6 +102,5 @@ go run ./internal/harness/provider-conformance \ ## Related docs - [The Agent Harness](agent-harness.md) -- [Agents and Workflows](agents-and-workflows.md) - [AI Provider Guide](ai-provider-guide.md) - [Roadmap](/docs/roadmap.html) diff --git a/internal/website/content/en/docs/guides/x402-payments.md b/internal/website/content/en/docs/guides/x402-payments.md index 74f23a222b..c6d7518be1 100644 --- a/internal/website/content/en/docs/guides/x402-payments.md +++ b/internal/website/content/en/docs/guides/x402-payments.md @@ -137,7 +137,6 @@ Leave those variables unset in normal CI; the live test skips unless the facilit ## See also -- [Building Effective Agents — Agents and Workflows](agents-and-workflows.md) - [MCP & AI Agents](../mcp.md) - [x402 — Coinbase Developer Docs](https://docs.cdp.coinbase.com/x402/welcome) · [x402 on Solana](https://solana.com/x402/what-is-x402) diff --git a/internal/website/content/en/docs/guides/your-first-agent.md b/internal/website/content/en/docs/guides/your-first-agent.md index 50a206fd0a..9d3b10d60d 100644 --- a/internal/website/content/en/docs/guides/your-first-agent.md +++ b/internal/website/content/en/docs/guides/your-first-agent.md @@ -19,7 +19,7 @@ If you want to run the lifecycle before copying code, start with the [no-secret go run ./examples/support ``` -It uses a deterministic mock model by default, so it needs no provider key, and it exercises the same shape this guide teaches: services become tools, an agent uses them, and a flow can trigger the work. Use the transcript for expected output, then use this guide when you are ready to build the smaller 0→1 version yourself. +It uses a deterministic mock model by default, so it needs no provider key, and it exercises the same shape this guide teaches: services become tools, an agent uses them. Use the transcript for expected output, then use this guide when you are ready to build the smaller 0→1 version yourself. ## What you'll build @@ -206,24 +206,7 @@ uses the `task` service before answering. and stored conversation history in memory. That is the core lifecycle: services provide capability, agents use the -capability, and the same runtime can later put the interaction behind a flow. - -## 5. Make it a workflow when the path is event-driven - -Once the prompt should run because something happened rather than because a -human typed a message, move the handoff into a flow: - -```go -flow := micro.NewFlow("task-triage", - micro.FlowTrigger("tasks.created"), - micro.FlowPrompt("Review this new task and decide the next action: {{.Data}}"), - micro.FlowProvider("openai"), - micro.FlowAPIKey(os.Getenv("OPENAI_API_KEY")), -) -``` - -Use flows for deterministic triggers and long-running orchestration; keep the -agent for judgment, tool use, and handoffs when the path is not known up front. +capability. ## Troubleshooting @@ -232,7 +215,7 @@ agent for judgment, tool use, and handoffs when the path is not known up front. | The agent says it cannot access tasks. | Confirm the agent was created with `micro.AgentServices("task")` and that `micro agent list` shows `assistant`. | | Tool calls use the wrong fields. | Add or improve doc comments and `@example` tags on the service methods. | | Plain service calls work but chat fails. | Check that your provider key is exported in the shell that runs `micro run`. | -| You need a no-secret reference path. | Run `make harness` from the Go Micro repository; it exercises the services → agents → workflows lifecycle with a mock provider. | +| You need a no-secret reference path. | Run `make harness` from the Go Micro repository; it exercises the services → agents lifecycle with a mock provider. | ## Next steps @@ -241,6 +224,4 @@ agent for judgment, tool use, and handoffs when the path is not known up front. - Run the [no-secret first-agent transcript](no-secret-first-agent.md) or [`examples/support`](https://github.com/micro/go-micro/tree/master/examples/support) for the no-secret support-desk lifecycle. - Run [`examples/agent-plan-delegate`](https://github.com/micro/go-micro/tree/master/examples/agent-plan-delegate) to see planning and delegation across agents. -- Read [Debugging your agent](debugging-agents.md) when a chat turn does not call the tool you expected, loops, refuses a call, loses memory, or fails after a flow handoff. -- Read [Agents and Workflows](agents-and-workflows.md) when you are ready to - compose agents behind durable flows. +- Read [Debugging your agent](debugging-agents.md) when a chat turn does not call the tool you expected, loops, refuses a call, loses memory, or fails during a tool call. diff --git a/internal/website/content/en/docs/guides/zero-to-hero.md b/internal/website/content/en/docs/guides/zero-to-hero.md index 834eab96c8..78ca035e31 100644 --- a/internal/website/content/en/docs/guides/zero-to-hero.md +++ b/internal/website/content/en/docs/guides/zero-to-hero.md @@ -3,7 +3,7 @@ title: "0→hero reference path" --- The 0→hero path is the maintained, no-secret reference for the Go Micro -services → agents → workflows lifecycle. It ties the CLI inner loop and the +services → agents lifecycle. It ties the CLI inner loop and the runtime harness together so a contributor can prove the framework still works as one system, not as separate demos. @@ -20,12 +20,12 @@ cloud credentials?" | First agent | `micro new`, `micro agent preflight`, `micro run`, `micro chat`, and `micro inspect agent ` stay available for the documented first-agent walkthrough. | `go test ./cmd/micro -run TestFirstAgentWalkthroughCLIBoundaries -count=1` | | Run | `micro run` remains the local development entry point. | `go test ./cmd/micro -run TestZeroToHeroCLIBoundaries -count=1` | | Chat | `micro chat` remains the interactive agent entry point. | `go test ./cmd/micro -run TestZeroToHeroCLIBoundaries -count=1` | -| Inspect | `micro inspect agent `, `micro agent history `, `micro inspect flow `, and `micro flow runs ` remain discoverable for run history; the no-secret debugging smoke seeds durable agent history and runs the documented inspect/history commands without provider keys. | `go test ./internal/harness/zero-to-hero-ci -run TestNoSecretFirstAgentDebuggingSmoke -count=1` | +| Inspect | `micro inspect agent ` and `micro agent history ` expose agent run history without provider keys. | `go test ./internal/harness/zero-to-hero-ci -run TestNoSecretFirstAgentDebuggingSmoke -count=1` | | Deploy | `micro deploy --dry-run prod` resolves the documented deploy target without touching remote infrastructure. | `go test ./internal/harness/zero-to-hero-ci -run TestZeroToHeroDeployDryRunCommandSmoke -count=1` | | Smallest first agent | `examples/first-agent` runs one service-backed agent with a deterministic mock model and no provider key. | `go test ./examples/first-agent -run TestRunFirstAgent -count=1` | -| Runtime reference app | `examples/support` runs typed services, an agent using those services as tools, an event-driven flow handoff, and an approval gate with only the model mocked. | `go test ./examples/support -run 'TestRunSupportMockSmoke|TestZeroToHeroReadmeDocumentsLifecycle|TestZeroToHeroInspectTranscript' -count=1` | -| Ordered 0→hero transcript | The maintained CI transcript walks scaffold → run/chat/inspect → support-agent chat → flow history → deploy dry-run without provider keys. | `make zero-to-hero-transcript` | -| Runtime harnesses | Real services, agents, durable flows, store-backed history, delegation, and A2A run with only the model mocked. | `./internal/harness/zero-to-hero-ci/run.sh` and `make provider-conformance-mock` | +| Runtime reference app | `examples/support` runs typed services, an agent using those services as tools, and an approval gate with only the model mocked. | `go test ./examples/support -run 'TestRunSupportMockSmoke|TestZeroToHeroReadmeDocumentsLifecycle|TestZeroToHeroInspectTranscript' -count=1` | +| Ordered 0→hero transcript | The maintained CI transcript walks scaffold → run/chat/inspect → support-agent chat → deploy dry-run without provider keys. | `make zero-to-hero-transcript` | +| Runtime harnesses | Real services, agents, store-backed history, delegation, and A2A run with only the model mocked. | `./internal/harness/zero-to-hero-ci/run.sh` and `make provider-conformance-mock` | ## Find the one-command entrypoint @@ -51,7 +51,7 @@ Then run the support-desk example when you want to see the full lifecycle in one go run ./examples/support ``` -It starts typed services, a support agent, an event-driven intake flow, and an approval gate with a deterministic mock model. Change one service method, agent prompt, or guardrail decision and run it again to learn the system by modifying a working path. +It starts typed services, a support agent, and an approval gate with a deterministic mock model. Change one service method, agent prompt, or guardrail decision and run it again to learn the system by modifying a working path. ## Run the whole no-secret path @@ -67,8 +67,7 @@ For the focused ordered transcript only, run: make zero-to-hero-transcript ``` -That target runs the scaffold contract, the CLI boundary smoke tests, the -0→hero runtime harnesses, the event-driven agent-flow harness, and mock provider +That target runs the scaffold contract, the CLI boundary smoke tests, runtime harnesses, and mock provider conformance. It is intentionally deterministic: no provider key, cloud account, SSH access, or remote service is required. @@ -92,7 +91,7 @@ go test ./cmd/micro/cli/new -run TestZeroToOne -count=1 # First-agent walkthrough boundary: scaffold, preflight, run, chat, inspect. go test ./cmd/micro -run TestFirstAgentWalkthroughCLIBoundaries -count=1 -# CLI inner-loop commands: run, chat, inspect, flow runs, deploy --dry-run. +# CLI inner-loop commands: run, chat, inspect, deploy --dry-run. go test ./cmd/micro -run TestZeroToHeroCLIBoundaries -count=1 go test ./cmd/micro/cli/deploy -run TestDeployDryRun -count=1 go test ./internal/harness/zero-to-hero-ci -run TestZeroToHeroDeployDryRunCommandSmoke -count=1 @@ -103,11 +102,9 @@ go test ./examples/first-agent -run TestRunFirstAgent -count=1 # Maintained 0→hero support-desk reference app. go test ./examples/support -run 'TestRunSupportMockSmoke|TestZeroToHeroReadmeDocumentsLifecycle|TestZeroToHeroInspectTranscript' -count=1 -# Durable services → agents → workflows reference scenarios. +# Durable services → agents reference scenarios. ./internal/harness/zero-to-hero-ci/run.sh -# Event-as-prompt agent flow. -go run ./internal/harness/agent-flow # Cross-provider semantics with the deterministic mock provider. make provider-conformance-mock @@ -120,27 +117,18 @@ make provider-conformance-mock assistant agent, and a deterministic mock model. - [`examples/support`](https://github.com/micro/go-micro/tree/master/examples/support) is the runnable support-desk story: customers, tickets, notify, a support - agent, an intake flow, and an approval gate in one no-secret example. + agent and an approval gate in one no-secret example. - [`examples/agent-plan-delegate`](https://github.com/micro/go-micro/tree/master/examples/agent-plan-delegate) is the smallest runnable planning/delegation example for multiple agents. -- [`internal/harness/plan-delegate`](https://github.com/micro/go-micro/tree/master/internal/harness/plan-delegate) - is the compact 0→hero scenario: real task and notify services, a conductor - agent, a comms agent, plan persistence, delegation, and a workflow handoff. -- [`internal/harness/universe`](https://github.com/micro/go-micro/tree/master/internal/harness/universe) - boots a larger mini-world: inventory, payment, order confirmation, a concierge - agent, durable checkpoint/resume, agent run history, flow run history, and A2A - reachability. -- [`internal/harness/agent-flow`](https://github.com/micro/go-micro/tree/master/internal/harness/agent-flow) - shows the event-driven path where a `user.created` event prompts an agent to - call services and complete onboarding. + Together these scenarios keep the North Star executable: services expose typed capabilities, agents use those capabilities with memory and guardrails, and -workflows compose the work over time. +agents can delegate to each other. ## Keeping the guide honest -If you change the CLI inner loop, durable flow APIs, agent run history, or the +If you change the CLI inner loop, agent run history, or the provider/tool semantics, update this guide and the harness in the same PR. The point of 0→hero is not a polished sample app that drifts from reality; it is a CI-verifiable contract that the documented lifecycle still works. diff --git a/internal/website/content/en/docs/interactive-agent.md b/internal/website/content/en/docs/interactive-agent.md index be409e89b9..0b37593668 100644 --- a/internal/website/content/en/docs/interactive-agent.md +++ b/internal/website/content/en/docs/interactive-agent.md @@ -164,8 +164,7 @@ are stored in the selected conversation and remain inspectable after completion. `/schedule 1h MESSAGE` saves a recurring request; `/schedules` lists definitions and `/unschedule ID` removes future dispatches. Go callers use -`agent.ScheduleTask`, `ListSchedules`, and `RemoveSchedule`. Each dispatch runs -through `flow.Scheduled` and creates an inspectable background agent task. +`agent.ScheduleTask`, `ListSchedules`, and `RemoveSchedule`. Each dispatch creates an inspectable background agent task. Schedule definitions and next dispatch times survive restarts. Intervals are at least one minute. Missed intervals coalesce into one dispatch; the next time is @@ -197,7 +196,7 @@ options without using the CLI. No product-specific assistant runtime is required | Memory | Compaction, archive search, and scoped cross-conversation keyword recall | | Background commands | Host-owned processes with list/stop/cleanup | | Work after UI exit | Submitted tasks on a running agent host | -| Scheduled work | Persisted intervals dispatched through flows | +| Scheduled work | Persisted intervals dispatched by the agent host | | Isolated commands | Optional Docker execution; host tools have separate policies | | Programmatic extension | Existing interfaces plus optional capabilities and ordinary tools | | Delegation | Existing agent delegation with visible local target/task and agent listing | diff --git a/internal/website/content/en/docs/project/execution-contract.md b/internal/website/content/en/docs/project/execution-contract.md deleted file mode 100644 index 0a6703160c..0000000000 --- a/internal/website/content/en/docs/project/execution-contract.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: "Execution Contract" -description: "The audited v6 execution boundaries and v7 compatibility decisions." ---- - -# Execution contract - -This is the shipped Stage 1 contract matrix tracked by -[#5044](https://github.com/micro/go-micro/issues/5044). It describes v6 as it -exists; it does not promise exactly-once effects or pre-approve a v7 API. An -invocation succeeding means its local boundary completed, not that an external -business effect is proven. - -## Boundary matrix - -| Boundary | Execution and state owner | Retry owner | Completion and cancellation | Persistence and recovery | Known gap / decision | -| --- | --- | --- | --- | --- | --- | -| Direct service RPC | Client and service handler | Caller/client wrappers | RPC response or error; the request context carries cancellation | None in the core RPC contract | Effects require an application idempotency key or reconciliation. No v7 break is required. | -| Direct agent `Ask` | Agent harness | Agent/model provider according to their configured limits | A response completes the run; errors are classified; context cancellation cancels active work | Opt-in checkpoint records run, tool results, and stage; `Resume` is explicit | Providers may still own tool iteration. Moving all iteration to the harness is a v7 break. | -| Streaming agent request | Agent harness and stream producer | Same as direct agent execution | Terminal event/error closes the stream; context or disconnected consumer cancels active delivery | Checkpoint and `ResumeStreamAsk` use the same run identity when configured | A single provider event contract is a v7 target. | -| Durable agent approval/input | Agent harness | The resumed run; approval itself is not retried | Waiting is a distinct paused error; denial and cancellation are not success | The pause and exact tool call are saved before returning; resume requires the run and approval/input identity | Keep and strengthen in v6. Hosts must use persistent storage for restart recovery. | -| Prompt-driven flow | Flow plus model provider | Provider/model behavior | `Execute` returns reply or error; context cancellation is an error | No ordered-step checkpoint boundary | Route adaptive tool use through the agent harness in v7; retain plain model transformations. | -| Ordered flow steps | Flow runner | Flow/step retry policy | Each step is `done` or `failed`; cancellation is currently represented as failure metadata | A shared run record saves completed steps; explicit `Resume` reuses them | Add a distinct cancelled/exhausted outcome compatibly where possible. | -| Agent-dispatch flow step | Flow owns step order; child agent owns adaptive work | Flow retries dispatch; agent owns its internal retries | RPC success completes the parent step; child run ID records lineage | Parent and child checkpoint independently | Prevent nested retries from multiplying effects; initially a v6 documentation/configuration fix. | -| Flow loop | Flow step owns the whole loop | Loop body and enclosing step policies | Reaching `LoopMax` currently returns the latest state as success | Only the enclosing step is checkpointed, so restart can repeat iterations | Persist progress and report exhaustion distinctly. Record-shape/outcome changes may require v7. | -| Broker-triggered flow | Broker callback invokes the flow | Broker-specific redelivery plus flow retry | The handler currently acknowledges by returning nil even when execution fails | Flow checkpoint can preserve ordered work, but acknowledgment is not tied to durable acceptance | Define acknowledgment after durable acceptance and deduplicate triggers; likely v7 for a portable broker contract. | - -## Identity and outcome vocabulary - -- **Run ID** identifies one agent or flow invocation. **Parent ID** and recorded - child run IDs preserve dispatch lineage; **step name** identifies work inside - an ordered run. Names must be unique within a flow. -- **Succeeded** means the invocation produced its declared result. It does not - prove an external effect unless the service supplies evidence. -- **Failed** means execution ended with an error. Machine-readable error kinds - should be preserved when available. -- **Cancelled** means the context ended by cancellation or deadline. It must not - be reported as success. -- **Waiting** means durable input or approval is required. It is non-terminal and - resumes only through an explicit matching operation. -- **Exhausted** means a retry, step, or loop budget ended before the requested - condition was met. It is distinct from success and policy refusal. -- **Ambiguous effect** means an external action may have completed before its - result was saved. Recovery must reconcile or reuse a stable idempotency key; - blindly replaying is not safe. - -Persisted status strings in v6 remain `running`, `waiting`, `done`, and `failed` -for compatibility. Cancellation and exhaustion can first be exposed through -error-kind metadata; a stored schema change requires versioning and migration. - -## Decision record - -1. **Flows own predefined order; agents own adaptive tool selection.** Plain - service steps and model transformations remain available. -2. **The boundary that schedules a retry owns its budget.** A parent must not - assume a child call is effect-free; retries need an idempotency key or an - explicitly safe operation. -3. **Save before acknowledging durable acceptance.** Broker delivery must not be - acknowledged merely because execution was attempted. -4. **Checkpoints prove recorded progress, not exactly-once effects.** Ambiguous - external work is reconciled by the capability owner. -5. **Service-only applications remain first-class.** Shared outcome types must - not introduce model or agent dependencies into RPC, registry, or broker APIs. - -## Compatibility decisions - -### Suitable for v6 - -- Preserve cancellation/error kinds and lineage consistently. -- Document retry ownership and require stable idempotency keys for effects. -- Add targeted restart tests around existing checkpoints and durable approval. -- Reject invalid resumes and make unsupported guarantees explicit. - -### Reserved for v7 unless proved otherwise - -- Make provider `Generate` one-turn-only and move tool iteration to the agent. -- Change portable broker acknowledgment semantics. -- Change persisted status/schema values or flow-loop record shape. -- Unify prompt-driven flow execution with the agent harness where public - behavior changes. - -The executable `make recovery-gate` fixture replaces a flow host while retaining -its checkpoint, preserves waiting state and lineage, injects duplicate concurrent -resume, models an ambiguous effect, exhausts a retry budget, and proves that -stable idempotency keys prevent duplicate final effects. This is the v6 recovery -baseline; a portable cross-host lease or compare-and-swap checkpoint contract -remains v7 work. - -The next executable increment is the complete composition tracked by -[#5049](https://github.com/micro/go-micro/issues/5049). Unlike the focused -recovery fixture, it joins real service RPC, agent dispatch through service -tools, durable approval, and an idempotent final operation in one inspectable -run. It remains a v6-compatible acceptance test; breaking provider and stored- -record changes stay behind the Stage 5 migration gate. diff --git a/internal/website/content/en/docs/quickstart.md b/internal/website/content/en/docs/quickstart.md index d9bf35cf62..802e62a371 100644 --- a/internal/website/content/en/docs/quickstart.md +++ b/internal/website/content/en/docs/quickstart.md @@ -89,4 +89,3 @@ Your service is running and can be called by other applications. You can stop he - [Services](services.md): service calls, discovery, and protobuf contracts. - [Agents](agents.md): define your own agent in Go. -- [Workflows](workflows.md): coordinate operations in a defined order. diff --git a/internal/website/content/en/docs/reference.md b/internal/website/content/en/docs/reference.md index 9ea068e0ec..c9477ed159 100644 --- a/internal/website/content/en/docs/reference.md +++ b/internal/website/content/en/docs/reference.md @@ -14,7 +14,6 @@ component or option. | Discovery and messaging | [registry](https://pkg.go.dev/go-micro.dev/v6/registry), [broker](https://pkg.go.dev/go-micro.dev/v6/broker) | | Storage and configuration | [store](https://pkg.go.dev/go-micro.dev/v6/store), [config](https://pkg.go.dev/go-micro.dev/v6/config) | | Models and agents | [model](https://pkg.go.dev/go-micro.dev/v6/model), [agent](https://pkg.go.dev/go-micro.dev/v6/agent) | -| Workflows | [flow](https://pkg.go.dev/go-micro.dev/v6/flow) | - [CLI commands](https://github.com/micro/go-micro/blob/master/cmd/micro/README.md) - [Examples](https://github.com/micro/go-micro/tree/master/examples) diff --git a/internal/website/content/en/docs/roadmap.md b/internal/website/content/en/docs/roadmap.md index e00e806fa2..6c0c1c2cd3 100644 --- a/internal/website/content/en/docs/roadmap.md +++ b/internal/website/content/en/docs/roadmap.md @@ -15,7 +15,7 @@ classification, and its required tests and documentation. Status is one of proposed, accepted, in progress, shipped, or deferred. Issue proposals must also identify effects on service-only applications, -agents, flows, gateways, provider plugins, and stored run/checkpoint formats. +agents, gateways, provider plugins, and stored run/checkpoint formats. Service-only use remains first-class and must not acquire an AI dependency to receive framework fixes. @@ -26,7 +26,6 @@ receive framework fixes. | gRPC-reflection MCP | Proposed | v6-compatible | No release commitment | | Kubernetes operator and CRDs | Proposed | v6-compatible | No release commitment | | v7 execution contract ([#5044](https://github.com/micro/go-micro/issues/5044)) | Shipped design baseline | mixed; see contract matrix | v6 documentation | -| Restartable service-agent-flow composition ([#5049](https://github.com/micro/go-micro/issues/5049)) | Shipped | v6-compatible fixture | v6 | ## Towards v7 — proposal @@ -41,7 +40,6 @@ The foundation is in place: - **Services** — register, discover, RPC, events; every endpoint is automatically an MCP tool. - **Agents** — a model with memory and tools that manages services, with `plan`, `delegate`, guardrails (`MaxSteps`, `LoopLimit`, `ApproveTool`), tool-execution middleware (`WrapTool`), run metadata, checkpoint/resume, and OpenTelemetry run spans built in. -- **Flows** — durable, event-driven workflows: ordered steps that checkpoint and resume after a crash. - **Interop** — the MCP gateway (services as tools) and the A2A gateway (agents as agents, both directions, including A2A streaming, push notifications, and multi-turn continuation), both generated from the registry; x402 for paid tools. - **Secure by default** — TLS verification on, state scoped per component. @@ -75,21 +73,6 @@ gap; it is not grounds to describe the runtime capability as unimplemented. AP2 mandate work remains a separate proposed foundation and is not a second flagship milestone. -## Shipped — complete composition - -The execution-contract audit, provider-free recovery gate, and single -restartable service-agent-flow composition tracked by -[#5049](https://github.com/micro/go-micro/issues/5049) are shipped. The fixture -calls real services, dispatches bounded agent work through service tools, pauses -for durable approval, and completes one idempotent final operation while -preserving inspectable lineage across replacement hosts. The race-enabled, -key-free fixture is a v6-compatible acceptance gate, not permission to begin -the breaking model/agent split. - -The [contract matrix](project/execution-contract.md) remains the compatibility -baseline. gRPC-reflection MCP and Kubernetes deployment remain candidates for -the next net-new capability; neither is accepted as a simultaneous flagship. - ## Shipped agent depth - **Durable agent loop.** Opt-in `Checkpoint` support now lets agent `Ask` and @@ -103,8 +86,6 @@ the next net-new capability; neither is accepted as a simultaneous flagship. - **gRPC-reflection MCP.** Derive MCP tools from external gRPC services through server reflection rather than requiring go-micro-native handlers. -- **Kubernetes operator and CRDs.** Reconcile `Agent`, `Service`, and `Flow` - resources into deployments connected to the registry. ## Later diff --git a/internal/website/content/en/docs/v7.md b/internal/website/content/en/docs/v7.md index acdc9c9c0b..021453c39e 100644 --- a/internal/website/content/en/docs/v7.md +++ b/internal/website/content/en/docs/v7.md @@ -1,156 +1,14 @@ --- -title: "Towards v7" -description: "A plan for consistent execution across services, agents, and flows." +title: "v7 direction" --- -Status: implementation plan, September 2026. Proposed contracts below are not -shipped guarantees or a committed release date. +Go Micro focuses on services and agents. Services expose typed capabilities; +agents use those capabilities to carry out work. -## Direction +The standalone flow package and its CLI commands have been removed. Agent +execution records, checkpoints, approvals and resume remain in `agent` and +`agent/run`. Existing agent checkpoints retain their storage format. -Go Micro began by making services communicate. Its next step is to coordinate -work across services and agents, with flows defining how that work proceeds. -Existing service-only applications remain first-class; AI is optional. - -| Component | Responsibility | -|-----------|----------------| -| Service | Typed capabilities, operations, application data, and idempotent effects | -| Agent | Goal-directed model/tool execution, memory, limits, and human interaction | -| Flow | Explicit steps, dependencies, verification, and recovery across services and agents | -| Model | Provider requests, responses, tool-call descriptions, and usage | - -The model row is a v7 target: v6 providers can execute tools inside `Generate`. -Moving that execution into the agent harness requires a public API migration. - -Apps are outputs or interfaces built using these components. The experimental -app package and example are removed; app definitions and hosting are outside -this plan. Mu remains a separate runtime, hosting Micro the assistant. Mu can -adopt framework components and contribute improvements without setting the -framework's product requirements. - -## What exists and where it diverges - -The audit starts from these concrete paths: - -- `agent/agent.go` owns agent execution and tool controls. CLI development chat - and routing now use that harness. Compatible provider generation loops share - protocol code, but providers still own tool iteration inside `Generate`. -- `flow/flow.go` supports agent dispatch, but prompt-driven flows also construct - a model with service tools directly. This remains a separate execution path. -- `flow/steps.go` provides service/model/agent step helpers, retry, verification, - waiting, and checkpoints. `agent/checkpoint.go` already reuses flow run records; - preserve that working composition before designing more abstractions. -- `flow/loop.go` checkpoints the whole loop as one step. Resume can repeat earlier - iterations, and reaching the cap currently returns the latest state as success. -- Flow broker handlers currently log execution failures and return nil. Delivery - acknowledgment and durable acceptance need an explicit contract. - -These are starting findings, not a claim that recovery is absent. Checkpointing, -completed-tool result reuse, run lineage, and human-input resume already exist. -The work is to make their guarantees consistent across entry points. - -## Delivery sequence - -### 1. Audit and specify the execution contract - -Status: shipped design baseline, tracked by -[#5044](https://github.com/micro/go-micro/issues/5044). The versioned -[contract matrix](project/execution-contract.md) is the initial deliverable and -records current behavior and compatibility decisions. - -Trace direct service calls, direct/streaming agent requests, prompt-driven flows, -ordered flow steps, broker dispatch, and resume. Record who owns retries, state, -completion, and cancellation at every boundary. - -Specify run/parent/step identity and distinguish successful completion, failure, -cancellation, waiting for input or approval, and limit exhaustion. Separate the -outcome of an invocation from proof that the intended business effect occurred. -Define how these outcomes map to current RPC responses and persisted records. - -Deliverable: a contract matrix and a short decision record identifying compatible -fixes versus v7 breaks. Reuse existing run metadata and checkpoint interfaces; -choose any shared internal implementation only after checking package cycles. - -### 2. Consolidate agent execution - -Route adaptive tool-using flows through the agent harness, with explicit tools, -provider settings, limits, and state scope. Keep deterministic service steps and -plain model transformations available. Flows own step order; the agent owns -adaptive tool selection. Define retry ownership so nesting does not silently -multiply model calls or service effects. - -Deliverable: equivalent guardrails, cancellation, and outcome reporting for CLI, -agent RPC, and flow-dispatched work. Add targeted mock-provider regressions at -those boundaries; no paid provider is required to prove composition. - -### 3. Make recovery boundaries explicit - -Status: v6 acceptance baseline shipped. The portable lease, atomic checkpoint, -and broker-acknowledgment contracts remain v7 design work. - -Preserve run identity, completed steps, child-run references, and consumed retry -budgets across restarts. Specify atomic persistence/ownership requirements so -concurrent resume attempts cannot independently advance the same run. Define -broker acknowledgment after durable acceptance and duplicate-trigger handling. -Persist loop progress or explicitly reject a durable guarantee for that path; -report exhaustion separately from successful completion. - -Treat an external action completed before its result was saved as ambiguous. -Use stable service idempotency keys or reconciliation; a checkpoint alone cannot -guarantee exactly-once external effects. Document unsupported cases rather than -silently replaying them. Durable behavior requires a persistent store and a host -that resumes work; memory-only defaults do not provide restart recovery. - -Deliverable: restart and failure-injection checks covering saved progress, -ambiguous effects, duplicate delivery, concurrent resume, and exhausted budgets. -The provider-free `make recovery-gate` fixture now enforces this v6 baseline: -replacement hosts retain progress, waiting state, and lineage; ambiguous and -concurrent operations use stable idempotency keys; exhausted retries fail. - -### 4. Prove one complete composition - -Status: shipped v6 acceptance fixture, tracked by -[#5049](https://github.com/micro/go-micro/issues/5049). This is the current -release stage; its fixture must keep passing before Stage 5 API work begins. - -Build one runnable Go-only workflow: a flow calls a service, asks an agent to -perform bounded work through service tools, waits for approval, then calls a -final service operation. Use a mock model by default and persistent local state. -Expose its run ID and status through existing inspection commands. - -Stop and restart the host at each boundary. Verify that completed recorded work -is reused, waiting work stays waiting, lineage survives, and an idempotent final -operation is not duplicated. Include a failed tool and a cancelled run. Document -an optional real-provider configuration separately. - -This is an acceptance fixture for the framework, not a new product or app layer. -It must run independently of Mu. - -The fixture is v6-compatible and must not imply exactly-once effects. It uses a -stable idempotency key at the final service boundary, exposes run and child-run -identity for inspection, and runs with the race detector as part of the release -gate. Live-provider coverage is optional and separate from the key-free CI path. -`make composition-gate` runs the complete fixture, and `make harness` includes -it in the standard deterministic release path. - -### 5. Complete the v7 model/agent split and migration - -Define one-turn provider results, including structured tool calls, continuation -state, usage, stop reasons, and streaming events. Move tool iteration into the -shared agent harness and run provider conformance checks against that contract. -Preserve provider-specific reasoning state and document streaming semantics. - -Publish migration guidance for direct `Generate` callers, provider plugins, -flow outcomes, and stored runs. Version stored formats and reject incompatible -records explicitly. Avoid changing RPC, registry, or broker APIs without a -specific demonstrated need. Compatible fixes from earlier stages can ship in v6. - -## Release gate - -v7 is ready when services, agents, and flows compose with documented execution -and recovery semantics, the restart fixture passes, and existing users have a -migration path. Package count and a new version number are not release goals. - -The developer experience should be straightforward: define capabilities, choose -agent-driven or predefined coordination, run the work, inspect its outcome, and -recover it under the same documented rules. +The next work is to make service discovery, agent execution, cancellation, +errors and inspection consistent across Go APIs, the CLI and gateways. Keep +interfaces small and prove changes through running applications. diff --git a/internal/website/content/en/docs/workflows.md b/internal/website/content/en/docs/workflows.md deleted file mode 100644 index ba35091132..0000000000 --- a/internal/website/content/en/docs/workflows.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: "Workflows" -params: - docs_main: true - exclude_search: false ---- - -A workflow runs named steps in order. Each step receives the previous step's -result. Use a workflow when you know the sequence; use an agent when a model -needs to choose what to do next. - -## Run two steps - -Keep the [notes service](services.md) running. Create `cmd/workflow/main.go`: - -```go -package main - -import ( - "context" - "fmt" - "log" - - "go-micro.dev/v6/flow" -) - -func main() { - f := flow.New("read-notes", flow.Steps( - flow.Step{Name: "list", Run: flow.Call("notes", "Notes.List")}, - flow.Step{Name: "print", Run: func(ctx context.Context, state flow.State) (flow.State, error) { - fmt.Println(state.String()) - return state, nil - }}, - )) - if err := f.Execute(context.Background(), "{}"); err != nil { - log.Fatal(err) - } -} -``` - -Run it from your project: - -```sh -go run ./cmd/workflow -``` - -The first step calls the service. The second prints its JSON response. A step -can call a service, dispatch work to an agent, or run your own Go function. - -## Retries and saved progress - -Flows save progress between steps. The default checkpoint uses a file store; -retain that data if you need to resume after a restart. Completed steps are -skipped on resume, but an interrupted step can run again. Make operations safe -to repeat before enabling retries. - -Calling `Execute` again starts a new run. To recover unfinished runs after -restarting, recreate the same flow with the same store and replace the -`Execute` call with: - -```go -if _, err := f.ResumePending(context.Background()); err != nil { - log.Fatal(err) -} -``` - -This resumes unfinished work; it does not start a new run. - -For configuration and recovery methods, see the -[flow API](https://pkg.go.dev/go-micro.dev/v6/flow). diff --git a/internal/website/data/docs.yaml b/internal/website/data/docs.yaml index 77a5d87184..968c4103f3 100644 --- a/internal/website/data/docs.yaml +++ b/internal/website/data/docs.yaml @@ -4,7 +4,5 @@ path: /docs/services - title: Agents path: /docs/agents -- title: Workflows - path: /docs/workflows - title: Reference path: /docs/reference diff --git a/internal/website/data/vanity.yaml b/internal/website/data/vanity.yaml index 2d447af131..cd85feee8c 100644 --- a/internal/website/data/vanity.yaml +++ b/internal/website/data/vanity.yaml @@ -132,7 +132,6 @@ modules: - go-micro.dev/v5/ai - go-micro.dev/v5/ai/anthropic - go-micro.dev/v5/ai/atlascloud - - go-micro.dev/v5/ai/flow - go-micro.dev/v5/ai/gemini - go-micro.dev/v5/ai/groq - go-micro.dev/v5/ai/mistral @@ -166,7 +165,6 @@ modules: - go-micro.dev/v5/cmd/micro/cli/new/template - go-micro.dev/v5/cmd/micro/cli/remote - go-micro.dev/v5/cmd/micro/cli/util - - go-micro.dev/v5/cmd/micro/flow - go-micro.dev/v5/cmd/micro/mcp - go-micro.dev/v5/cmd/micro/resource - go-micro.dev/v5/cmd/micro/run @@ -221,7 +219,6 @@ modules: - go-micro.dev/v5/examples/auth/client - go-micro.dev/v5/examples/auth/proto - go-micro.dev/v5/examples/auth/server - - go-micro.dev/v5/examples/flow-durable - go-micro.dev/v5/examples/graceful-stop - go-micro.dev/v5/examples/grpc-interop/client - go-micro.dev/v5/examples/grpc-interop/proto @@ -234,14 +231,10 @@ modules: - go-micro.dev/v5/examples/mcp/workflow - go-micro.dev/v5/examples/multi-service - go-micro.dev/v5/examples/web-service - - go-micro.dev/v5/flow - go-micro.dev/v5/gateway/a2a - go-micro.dev/v5/gateway/api - go-micro.dev/v5/gateway/mcp - go-micro.dev/v5/health - - go-micro.dev/v5/internal/harness/agent-flow - - go-micro.dev/v5/internal/harness/plan-delegate - - go-micro.dev/v5/internal/harness/universe - go-micro.dev/v5/internal/test - go-micro.dev/v5/internal/util/addr - go-micro.dev/v5/internal/util/backoff @@ -337,7 +330,6 @@ modules: - go-micro.dev/v6/cmd/micro/cli/new/template - go-micro.dev/v6/cmd/micro/cli/remote - go-micro.dev/v6/cmd/micro/cli/util - - go-micro.dev/v6/cmd/micro/flow - go-micro.dev/v6/cmd/micro/inspect - go-micro.dev/v6/cmd/micro/loop - go-micro.dev/v6/cmd/micro/mcp @@ -385,7 +377,6 @@ modules: - go-micro.dev/v6/debug/proto - go-micro.dev/v6/debug/stats - go-micro.dev/v6/debug/trace - - go-micro.dev/v6/deploy/kubernetes - go-micro.dev/v6/errors - go-micro.dev/v6/events - go-micro.dev/v6/events/natsjs @@ -399,8 +390,6 @@ modules: - go-micro.dev/v6/examples/auth/proto - go-micro.dev/v6/examples/auth/server - go-micro.dev/v6/examples/first-agent - - go-micro.dev/v6/examples/flow-durable - - go-micro.dev/v6/examples/flow-loop - go-micro.dev/v6/examples/graceful-stop - go-micro.dev/v6/examples/grpc-interop/client - go-micro.dev/v6/examples/grpc-interop/proto @@ -414,18 +403,14 @@ modules: - go-micro.dev/v6/examples/multi-service - go-micro.dev/v6/examples/support - go-micro.dev/v6/examples/web-service - - go-micro.dev/v6/flow - go-micro.dev/v6/gateway/a2a - go-micro.dev/v6/gateway/api - go-micro.dev/v6/gateway/mcp - go-micro.dev/v6/health - go-micro.dev/v6/internal/harness/a2a-stream-fallback - go-micro.dev/v6/internal/harness/a2a-streaming - - go-micro.dev/v6/internal/harness/agent-flow - go-micro.dev/v6/internal/harness/harnessutil - - go-micro.dev/v6/internal/harness/plan-delegate - go-micro.dev/v6/internal/harness/provider-conformance - - go-micro.dev/v6/internal/harness/universe - go-micro.dev/v6/internal/network - go-micro.dev/v6/internal/test - go-micro.dev/v6/internal/util/addr diff --git a/micro.go b/micro.go index cbf80ae6d4..c9e3f0250b 100644 --- a/micro.go +++ b/micro.go @@ -7,7 +7,6 @@ import ( "go-micro.dev/v6/agent" "go-micro.dev/v6/client" - "go-micro.dev/v6/flow" "go-micro.dev/v6/model" "go-micro.dev/v6/server" "go-micro.dev/v6/service" @@ -33,18 +32,9 @@ type AgentStream = agent.AgentStream // AgentOption configures an Agent. type AgentOption = agent.Option -// Flow coordinates predefined steps, service calls, and agent decisions. -type Flow = flow.Flow - // AgentRun records one agent execution. type AgentRun = agent.Run -// FlowRun is a checkpointed flow or agent run record. -type FlowRun = flow.Run - -// FlowOption configures a Flow. -type FlowOption = flow.Option - // Group is a set of services that share lifecycle management. type Group = service.Group @@ -279,112 +269,11 @@ func AgentResumeStreamAsk(ctx context.Context, a Agent, runID string) (AgentStre return agent.ResumeStreamAsk(ctx, a, runID) } -// NewFlow creates an event-driven LLM orchestration unit. -// -// f := micro.NewFlow("onboard-user", -// micro.FlowTrigger("events.user.created"), -// micro.FlowPrompt("New user: {{.Data}}. Send welcome email."), -// micro.FlowProvider("anthropic"), -// ) -// f.Register(service.Options().Registry, service.Options().Broker, service.Client()) -func NewFlow(name string, opts ...FlowOption) *Flow { - return flow.New(name, opts...) -} - -// FlowTrigger sets the broker topic that triggers the flow. -func FlowTrigger(topic string) FlowOption { return flow.Trigger(topic) } - -// FlowPrompt sets the prompt template. Use {{.Data}} for the event payload. -func FlowPrompt(p string) FlowOption { return flow.Prompt(p) } - -// FlowProvider sets the LLM provider. -func FlowProvider(p string) FlowOption { return flow.Provider(p) } - -// FlowAPIKey sets the API key for the LLM provider. -func FlowAPIKey(k string) FlowOption { return flow.APIKey(k) } - -// FlowAgent makes the flow hand each event to a named agent over RPC — -// the flow triggers, the agent reasons. Without it, the flow runs a -// single LLM step itself. -func FlowAgent(name string) FlowOption { return flow.Agent(name) } - -// FlowStep is one unit of a stepped flow. -type FlowStep = flow.Step - -// FlowState carries data across the steps of a flow run. -type FlowState = flow.State - -// FlowStepFunc performs one step's work. -type FlowStepFunc = flow.StepFunc - -// Checkpoint stores execution progress for recovery. +// Checkpoint stores agent execution progress for recovery. type Checkpoint = agent.Checkpoint -// FlowSteps makes the flow run an ordered list of steps per event, -// checkpointed between each, instead of a single LLM turn. -func FlowSteps(steps ...FlowStep) FlowOption { return flow.Steps(steps...) } - -// FlowRetry sets the flow-level retry count per step (a Step's own Retry -// overrides it). -func FlowRetry(n int) FlowOption { return flow.Retry(n) } - -// FlowRetryBackoff sets the delay between failed step attempts. -func FlowRetryBackoff(d time.Duration) FlowOption { return flow.RetryBackoff(d) } - -// FlowWithCheckpoint sets the durability backend for stepped runs. -// Stepped flows default to a store-backed checkpoint. -func FlowWithCheckpoint(c Checkpoint) FlowOption { return flow.WithCheckpoint(c) } - -// FlowDeleteOnSuccess removes a run's checkpoint on success (failed runs -// are always kept). Default: retain all. -func FlowDeleteOnSuccess() FlowOption { return flow.DeleteOnSuccess() } - -// FlowTraceProvider enables OpenTelemetry spans for stepped flow runs and steps. -func FlowTraceProvider(tp trace.TracerProvider) FlowOption { return flow.TraceProvider(tp) } - -// FlowCall is a step action: an RPC to a service endpoint, sending the -// state data as the request and storing the response. -func FlowCall(service, endpoint string) FlowStepFunc { return flow.Call(service, endpoint) } - -// FlowLLM is a step action: one augmented-LLM turn with the services as -// tools, storing the reply. -func FlowLLM(prompt string) FlowStepFunc { return flow.LLM(prompt) } - -// FlowDispatch is a step action: hand the state data to a registered -// agent over RPC, storing its reply. -func FlowDispatch(agent string) FlowStepFunc { return flow.Dispatch(agent) } - -// FlowLoopOption configures a FlowLoop. -type FlowLoopOption = flow.LoopOption - -// FlowLoopCondition decides whether a FlowLoop should stop, given the latest -// state and the iteration just completed. -type FlowLoopCondition = flow.LoopCondition - -// FlowLoop is a step action that runs body repeatedly until a stop condition -// is met or the iteration cap is reached — the agentic loop, with a -// guaranteed ceiling so it can't run away. Compose it as a FlowStep's Run. -func FlowLoop(body FlowStepFunc, opts ...FlowLoopOption) FlowStepFunc { - return flow.Loop(body, opts...) -} - -// FlowLoopMax sets a loop's hard iteration cap — the budget guardrail. -func FlowLoopMax(n int) FlowLoopOption { return flow.LoopMax(n) } - -// FlowUntil stops a loop when cond returns true (a code-defined exit). -func FlowUntil(cond FlowLoopCondition) FlowLoopOption { return flow.Until(cond) } - -// FlowUntilLLM stops a loop when the flow's model judges the goal met — the -// supervised "Ralph" loop. Requires a flow model (set FlowProvider/FlowAPIKey). -func FlowUntilLLM(question string) FlowLoopOption { return flow.UntilLLM(question) } - -// FlowOnIteration runs fn after each loop iteration (progress/observability). -func FlowOnIteration(fn func(iter int, state FlowState)) FlowLoopOption { - return flow.OnIteration(fn) -} - // StoreCheckpoint returns a store-backed Checkpoint whose run keys are -// namespaced under scope (the agent or workflow name). A nil store uses +// namespaced under scope (the agent name). A nil store uses // the default store. func StoreCheckpoint(s store.Store, scope string) Checkpoint { return agent.StoreCheckpoint(s, scope) From 2011621a6db81774b9cdceae3022f007573953e6 Mon Sep 17 00:00:00 2001 From: "Asim A." Date: Fri, 13 Nov 2026 09:40:45 +0000 Subject: [PATCH 2/2] Preserve vanity routes for published packages --- internal/website/data/vanity.yaml | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/internal/website/data/vanity.yaml b/internal/website/data/vanity.yaml index cd85feee8c..ebc77490a9 100644 --- a/internal/website/data/vanity.yaml +++ b/internal/website/data/vanity.yaml @@ -1,3 +1,4 @@ +# Preserve published package routes, including packages removed from the current source tree. # Auto-generated by scripts/generate-vanity-data.sh — do not edit manually. # Regenerate (and commit) when upstream micro/go-micro releases new tags. repository: https://github.com/micro/go-micro @@ -132,6 +133,7 @@ modules: - go-micro.dev/v5/ai - go-micro.dev/v5/ai/anthropic - go-micro.dev/v5/ai/atlascloud + - go-micro.dev/v5/ai/flow - go-micro.dev/v5/ai/gemini - go-micro.dev/v5/ai/groq - go-micro.dev/v5/ai/mistral @@ -165,6 +167,7 @@ modules: - go-micro.dev/v5/cmd/micro/cli/new/template - go-micro.dev/v5/cmd/micro/cli/remote - go-micro.dev/v5/cmd/micro/cli/util + - go-micro.dev/v5/cmd/micro/flow - go-micro.dev/v5/cmd/micro/mcp - go-micro.dev/v5/cmd/micro/resource - go-micro.dev/v5/cmd/micro/run @@ -219,6 +222,7 @@ modules: - go-micro.dev/v5/examples/auth/client - go-micro.dev/v5/examples/auth/proto - go-micro.dev/v5/examples/auth/server + - go-micro.dev/v5/examples/flow-durable - go-micro.dev/v5/examples/graceful-stop - go-micro.dev/v5/examples/grpc-interop/client - go-micro.dev/v5/examples/grpc-interop/proto @@ -231,10 +235,14 @@ modules: - go-micro.dev/v5/examples/mcp/workflow - go-micro.dev/v5/examples/multi-service - go-micro.dev/v5/examples/web-service + - go-micro.dev/v5/flow - go-micro.dev/v5/gateway/a2a - go-micro.dev/v5/gateway/api - go-micro.dev/v5/gateway/mcp - go-micro.dev/v5/health + - go-micro.dev/v5/internal/harness/agent-flow + - go-micro.dev/v5/internal/harness/plan-delegate + - go-micro.dev/v5/internal/harness/universe - go-micro.dev/v5/internal/test - go-micro.dev/v5/internal/util/addr - go-micro.dev/v5/internal/util/backoff @@ -330,6 +338,7 @@ modules: - go-micro.dev/v6/cmd/micro/cli/new/template - go-micro.dev/v6/cmd/micro/cli/remote - go-micro.dev/v6/cmd/micro/cli/util + - go-micro.dev/v6/cmd/micro/flow - go-micro.dev/v6/cmd/micro/inspect - go-micro.dev/v6/cmd/micro/loop - go-micro.dev/v6/cmd/micro/mcp @@ -377,6 +386,7 @@ modules: - go-micro.dev/v6/debug/proto - go-micro.dev/v6/debug/stats - go-micro.dev/v6/debug/trace + - go-micro.dev/v6/deploy/kubernetes - go-micro.dev/v6/errors - go-micro.dev/v6/events - go-micro.dev/v6/events/natsjs @@ -390,6 +400,8 @@ modules: - go-micro.dev/v6/examples/auth/proto - go-micro.dev/v6/examples/auth/server - go-micro.dev/v6/examples/first-agent + - go-micro.dev/v6/examples/flow-durable + - go-micro.dev/v6/examples/flow-loop - go-micro.dev/v6/examples/graceful-stop - go-micro.dev/v6/examples/grpc-interop/client - go-micro.dev/v6/examples/grpc-interop/proto @@ -403,14 +415,18 @@ modules: - go-micro.dev/v6/examples/multi-service - go-micro.dev/v6/examples/support - go-micro.dev/v6/examples/web-service + - go-micro.dev/v6/flow - go-micro.dev/v6/gateway/a2a - go-micro.dev/v6/gateway/api - go-micro.dev/v6/gateway/mcp - go-micro.dev/v6/health - go-micro.dev/v6/internal/harness/a2a-stream-fallback - go-micro.dev/v6/internal/harness/a2a-streaming + - go-micro.dev/v6/internal/harness/agent-flow - go-micro.dev/v6/internal/harness/harnessutil + - go-micro.dev/v6/internal/harness/plan-delegate - go-micro.dev/v6/internal/harness/provider-conformance + - go-micro.dev/v6/internal/harness/universe - go-micro.dev/v6/internal/network - go-micro.dev/v6/internal/test - go-micro.dev/v6/internal/util/addr