Implement the runtime kernel: agent loop, session supervisor, and the first reference plugin

.golangci.yml

@@ -22,6 +22,33 @@ linters:
     - unconvert
     - unparam
     - wastedassign
+    - depguard
+  settings:
+    depguard:
+      rules:
+        # internal/anthropic is the reference model-provider plugin. It
+        # runs out of process and is meant to be indistinguishable from a
+        # plugin a third party could write against pkg/ alone, so it may
+        # import only pkg/... and the standard library. Reaching into any
+        # other internal/ package would make it a privileged in-tree
+        # shortcut rather than a proof that the published SDK is
+        # sufficient — and the whole point of building it was to find out
+        # whether pkg/ really is.
+        #
+        # Scoped to non-test files: the integration tier legitimately
+        # imports internal/pluginruntime to launch the built binary the
+        # way the kernel does, which is the kernel-launches-plugin
+        # direction, not a dependency of the plugin itself.
+        anthropic-plugin-isolation:
+          list-mode: lax
+          files:
+            - "**/internal/anthropic/**"
+            - "!$test"
+          allow:
+            - github.com/pluggableharness/agent/internal/anthropic
+          deny:
+            - pkg: github.com/pluggableharness/agent/internal
+              desc: internal/anthropic is a reference plugin — it may import only pkg/... and the standard library, never another internal/ package (see internal/anthropic/CLAUDE.md)
   exclusions:
     rules:
       - path: _test\.go

.goreleaser.yaml

@@ -1,13 +1,37 @@
 # yaml-language-server: $schema=https://goreleaser.com/static/schema.json
 version: 2
 
-# No cmd/ binary exists yet — this is a plugin-host monorepo still in the
-# library/proto/spec stage (see go-layout.md). Builds are explicitly
-# skipped rather than left to auto-detect a main package that doesn't
-# exist. Flip this to false and add a `builds:` block once cmd/<binary>
-# exists.
+# Two binaries: the kernel and the reference Anthropic model provider.
+# Both are stamped through -ldflags rather than reading their identity
+# from a file at runtime, matching how internal/pluginhost's integration
+# fixture is built (`-X main.fixtureName=...`) — a plugin's Describe RPC
+# has to answer from the running process, since a dev_overrides binary has
+# no lock-file entry to read identity from
+# (configuration/lock-file.md#dev_overrides-and-identity-without-a-lock-entry).
 builds:
-  - skip: true
+  - id: agent
+    main: ./cmd/agent
+    binary: agent
+    env: [CGO_ENABLED=0]
+    goos: [linux, darwin, windows]
+    goarch: [amd64, arm64]
+    flags: [-trimpath]
+    ldflags:
+      - -s -w
+      - -X main.version={{ .Version }}
+
+  - id: anthropic
+    main: ./cmd/anthropic
+    binary: agent-provider-anthropic
+    env: [CGO_ENABLED=0]
+    goos: [linux, darwin, windows]
+    goarch: [amd64, arm64]
+    flags: [-trimpath]
+    ldflags:
+      - -s -w
+      # pluginVersion is what this plugin reports through Describe; the
+      # source stays the -X-able default in main.go for a checkout build.
+      - -X main.pluginVersion={{ .Version }}
 
 archives:
   - formats: [tar.gz]

api/pluggableharness/model/v1/events.proto

@@ -31,6 +31,9 @@ message StreamEvent {
     Stop stop = 8;
     // The completion failed.
     Error error = 9;
+    // A complete, vendor-encrypted reasoning block the kernel cannot
+    // interpret.
+    RedactedThinking redacted_thinking = 10;
   }
 
   // TextDelta carries one incremental fragment of assistant text output.
@@ -101,6 +104,20 @@ message StreamEvent {
     // The structured error, classified per model.md §8.
     ModelError error = 1;
   }
+
+  // RedactedThinking carries one complete, vendor-encrypted reasoning
+  // block — not an incremental fragment, unlike ThinkingDelta: the
+  // vendor emits the block whole because its contents are deliberately
+  // opaque, so there is nothing to accumulate. MUST be emitted whenever
+  // the vendor produces reasoning content it requires be echoed back
+  // verbatim on a later turn (model.md §4/§5); the kernel MUST store and
+  // round-trip it without inspecting it, into ContentBlock's
+  // RedactedThinkingBlock.data. Only emitted when the target model's
+  // ThinkingSpec.supported is true.
+  message RedactedThinking {
+    // The opaque, vendor-encrypted bytes. The kernel never inspects this.
+    bytes data = 1;
+  }
 }
 
 // StopReason classifies why a StreamCompletion ended, per model.md §4.

api/pluggableharness/tool/v1/types.proto

@@ -136,6 +136,15 @@ message ToolSchema {
   // TOOL_KIND_DATA_SOURCE operations are implicitly safe to retry
   // regardless of this field.
   bool idempotent = 10;
+
+  // Declares that the model calling this operation MUST be treated as an
+  // immediate, successful DoneCheck once this call's post-tool-call hook
+  // has fired, independent of whether other tool_use blocks were present
+  // in the same message — see
+  // agent-loop/turn-algorithm.md#done-detection. MAY, per operation; MAY
+  // be true only on a TOOL_KIND_RESOURCE operation. Absent or false means
+  // this operation does not terminate the turn.
+  bool terminates_turn = 11;
 }
 
 // ToolCall is one request to execute an operation, per tool.md §4.

cmd/agent/main.go

@@ -0,0 +1,117 @@
+// Command agent is the PluggableHarness kernel binary.
+//
+// This build runs exactly one non-interactive session: it loads agent.hcl,
+// launches every resolved provider plugin, runs -prompt to completion,
+// prints the session's final message to stdout, and exits. The interactive
+// command docs/specifications/architecture.md#cli-shape describes arrives
+// with the frontend plugin category; there is no REPL here yet.
+//
+// Everything below is wiring, per .claude/rules/go-layout.md: flags in,
+// one internal/kernel.Run call, an exit code out.
+package main
+
+import (
+	"context"
+	"errors"
+	"flag"
+	"fmt"
+	"os"
+	"os/signal"
+	"runtime/debug"
+	"syscall"
+
+	"github.com/pluggableharness/agent/internal/kernel"
+)
+
+// Exit codes. 130 for a SIGINT follows the shell convention (128 + SIGINT),
+// so a piped invocation can tell an operator's Ctrl-C apart from a real
+// failure; 2 for a usage error matches flag's own convention.
+const (
+	exitOK       = 0
+	exitFailure  = 1
+	exitUsage    = 2
+	exitCanceled = 130
+)
+
+// version is overridden at release time via -ldflags; a `go build` from a
+// checkout reports whatever the module's own build info knows.
+var version = ""
+
+func main() { os.Exit(run()) }
+
+// run parses flags, runs one session, and maps the outcome to an exit
+// code. It exists separately from main so every path returns rather than
+// calling os.Exit from inside a nested scope, which would skip deferred
+// cleanup.
+func run() int {
+	fs := flag.NewFlagSet("agent", flag.ContinueOnError)
+	fs.SetOutput(os.Stderr)
+
+	var (
+		configPath  = fs.String("config", kernel.DefaultConfigFile, "path to the agent.hcl config file")
+		profile     = fs.String("profile", "", `agent_profile block to run under (default "default")`)
+		prompt      = fs.String("prompt", "", "the prompt to run (required: this build has no interactive mode)")
+		logLevel    = fs.String("log-level", "", "override settings.log_level (trace|debug|info|warn|error)")
+		showVersion = fs.Bool("version", false, "print the version and exit")
+	)
+
+	if err := fs.Parse(os.Args[1:]); err != nil {
+		// flag already wrote the message and the usage text.
+		if errors.Is(err, flag.ErrHelp) {
+			return exitOK
+		}
+		return exitUsage
+	}
+	if *showVersion {
+		_, _ = fmt.Fprintln(os.Stdout, buildVersion())
+		return exitOK
+	}
+	if *prompt == "" {
+		_, _ = fmt.Fprintln(os.Stderr, "agent: -prompt is required")
+		fs.Usage()
+		return exitUsage
+	}
+
+	// The one cancellation root: everything below derives from it, so a
+	// signal reaches the model stream, the tool calls, and the plugin
+	// subprocesses through the same context internal/kernel already
+	// threads everywhere.
+	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer stop()
+
+	err := kernel.Run(ctx, kernel.Options{
+		ConfigPath: *configPath,
+		Profile:    *profile,
+		Prompt:     *prompt,
+		LogLevel:   *logLevel,
+		Stdout:     os.Stdout,
+		Stderr:     os.Stderr,
+	})
+	switch {
+	case err == nil:
+		return exitOK
+	case errors.Is(err, context.Canceled):
+		// A real SIGINT is a normal exit, not a failure to report: the
+		// kernel already persisted the session as cancelled and logged
+		// why.
+		return exitCanceled
+	default:
+		// The one sanctioned non-slog write in the tree: a config-load
+		// or path-resolution failure happens before logging is wired at
+		// all, so slog.Default() would still be stdlib's.
+		_, _ = fmt.Fprintln(os.Stderr, "agent:", err)
+		return exitFailure
+	}
+}
+
+// buildVersion reports the release version when one was stamped in, and
+// falls back to the module's own recorded build info otherwise.
+func buildVersion() string {
+	if version != "" {
+		return version
+	}
+	if info, ok := debug.ReadBuildInfo(); ok && info.Main.Version != "" {
+		return info.Main.Version
+	}
+	return "(devel)"
+}

cmd/anthropic/main.go

@@ -0,0 +1,55 @@
+// Command anthropic is the Anthropic model-provider plugin.
+//
+// It is a hashicorp/go-plugin subprocess: the kernel launches it, speaks
+// pluggableharness.model.v1.ModelService to it over gRPC, and kills it at
+// session end. It is never run directly by a human — started from a
+// shell it simply prints go-plugin's handshake line and waits.
+//
+// Everything here is wiring, per .claude/rules/go-layout.md: build the
+// provider, hand it to pkg/model's service adapter, serve. All real logic
+// lives in internal/anthropic.
+package main
+
+import (
+	"github.com/pluggableharness/agent/internal/anthropic"
+	commonv1 "github.com/pluggableharness/agent/pkg/common/proto/v1"
+	"github.com/pluggableharness/agent/pkg/model"
+	"github.com/pluggableharness/agent/pkg/plugin"
+)
+
+// Identity this build reports through the Describe RPC.
+//
+// These are variables rather than constants so a release build can stamp
+// them with -ldflags (see .goreleaser.yaml), matching how
+// internal/pluginhost's integration fixture is built. Describe has to
+// answer from the running process because a dev_overrides binary has no
+// agent.lock.hcl entry for the kernel to read identity from
+// (configuration/lock-file.md#dev_overrides-and-identity-without-a-lock-entry).
+var (
+	pluginName    = "anthropic"
+	pluginVersion = "0.0.0"
+	pluginSource  = "github.com/pluggableharness/agent-provider-anthropic"
+)
+
+func main() {
+	identity := plugin.Identity{
+		Name:    pluginName,
+		Version: pluginVersion,
+		Source:  pluginSource,
+	}
+
+	// The callback handle is constructed here and handed to both
+	// plugin.Serve and the model service, but is deliberately never
+	// dialed from main: pkg/plugin's "callback-timing trap" means
+	// Callback.Client may only be called from inside an RPC handler,
+	// after go-plugin has begun serving the broker.
+	callback := plugin.NewCallback()
+	provider := anthropic.New()
+
+	plugin.Serve(plugin.Config{
+		Identity: identity,
+		Category: commonv1.Category_CATEGORY_MODEL,
+		Callback: callback,
+		Services: []plugin.Service{model.NewService(provider, identity, callback)},
+	})
+}

docs/specifications/agent-loop/turn-algorithm.md

@@ -93,7 +93,7 @@ Injecting a structured "final answer" turn — disabling tools and forcing text-
 
 The kernel MUST support implicit done detection: a model response containing no `tool_use` blocks ends the turn loop successfully. This is the dominant pattern across surveyed harnesses and requires no cooperation from tool providers, which matters for a microkernel where tool providers are third-party and heterogeneous.
 
-An explicit terminal-tool pattern is more reliable in harnesses that use it, because it lets a tool provider carry a structured completion report. The kernel MUST support this as an opt-in: any tool provider MAY declare a resource with a `terminates_turn: bool` schema annotation; if the model calls such a tool, the kernel treats it as `DoneCheck` success immediately after that call's `post-tool-call` hook, independent of whether other `tool_use` blocks were present in the same message. Implicit no-tool-calls remains the MUST-support baseline; explicit terminal tools are an additive MAY, resolving the tension between LLM providers that don't reliably call a terminal tool and tool providers that want a structured completion signal by keeping implicit detection as the non-negotiable floor and layering explicit termination on top where a tool provider opts in.
+An explicit terminal-tool pattern is more reliable in harnesses that use it, because it lets a tool provider carry a structured completion report. The kernel MUST support this as an opt-in: any tool provider MAY declare a resource with a `terminates_turn: bool` schema annotation (the `ToolSchema.terminates_turn` field, [`tool/data-types.md#terminates_turn`](../tool/data-types.md#terminates_turn)); if the model calls such a tool, the kernel treats it as `DoneCheck` success immediately after that call's `post-tool-call` hook, independent of whether other `tool_use` blocks were present in the same message. Implicit no-tool-calls remains the MUST-support baseline; explicit terminal tools are an additive MAY, resolving the tension between LLM providers that don't reliably call a terminal tool and tool providers that want a structured completion signal by keeping implicit detection as the non-negotiable floor and layering explicit termination on top where a tool provider opts in.
 
 ### Doom-loop detection
 

docs/specifications/event-bus.md

@@ -42,7 +42,7 @@ No other wildcard form exists in v1 — no mid-string wildcard, no multi-segment
 ## Delivery semantics
 
 - **Best-effort, not guaranteed.** A `Publish` call returns as soon as the kernel has fanned the event out to every currently-subscribed stream's queue; it does not wait for any subscriber to actually receive or process the event, and a subscriber that connects after a `Publish` call already returned never sees that event. There is no backlog and no replay — this is `internal/eventbus`'s own ephemeral contract, inherited unchanged.
-- **Per-subscriber ordering only.** A single `Subscribe` stream sees events matching its filters in the order they were published; there is no ordering guarantee across two different `Subscribe` streams, and no ordering guarantee relative to `ReadEvents` or anything hook-dispatch related. Nothing here carries a `sequence` number — [`determinism.md`](../.claude/rules/determinism.md)'s ordering-authority rule governs persisted, replay-critical ordering, and this bus persists nothing and participates in no replay, so it is deliberately outside that rule's scope, exactly as `internal/eventbus`'s own design notes already state.
+- **Per-subscriber ordering only.** A single `Subscribe` stream sees events matching its filters in the order they were published; there is no ordering guarantee across two different `Subscribe` streams, and no ordering guarantee relative to `ReadEvents` or anything hook-dispatch related. Nothing here carries a `sequence` number — `.claude/rules/determinism.md`'s ordering-authority rule governs persisted, replay-critical ordering, and this bus persists nothing and participates in no replay, so it is deliberately outside that rule's scope, exactly as `internal/eventbus`'s own design notes already state.
 - **Observe-only, never a veto.** Unlike a hook subscriber in `veto` mode, a bus subscriber cannot block, modify, or reject the event it received — the bus has no response channel for that at all. A slow or broken subscriber can only ever affect itself (see "Backpressure" below), never the publisher or any other subscriber.
 
 ## Backpressure

docs/specifications/model/conformance.md

@@ -31,6 +31,7 @@ On the wire, each category maps to a `grpc/codes.Code`: `context_length_exceeded
 | `image` (vision) | MUST support where `supports_vision = true`; MUST reject cleanly where `false` | |
 | `document` | MUST support where `supports_documents = true`; MUST reject cleanly where `false` | [`data-types.md#canonical-message--content-block-schema`](data-types.md#canonical-message--content-block-schema) — mirrors `image`/`supports_vision`'s rule |
 | Extended thinking/reasoning | MAY, capability-gated via `ThinkingSpec` | declare `mode` precisely, don't collapse to a bool |
+| `StreamEvent.redacted_thinking` | MUST, for a vendor that emits vendor-encrypted reasoning blocks | [`data-types.md#streamevent`](data-types.md#streamevent) — a whole block, never fragmented; stored and echoed back verbatim or the vendor rejects the whole conversation on a later turn |
 | Prompt caching | MAY, capability-gated via `CachingSpec` | declare `mode` (explicit vs. implicit) |
 | Cache breakpoints (`StreamCompletionRequest.cache_breakpoints`) | MUST honor where `CachingSpec.mode = CACHING_MODE_EXPLICIT_MARKERS`; MUST ignore otherwise | [`protocol.md#cache-breakpoint-placement-policy`](protocol.md#cache-breakpoint-placement-policy) — placement is a kernel decision, never the plugin's |
 | Parallel tool calls in one turn | SHOULD declare via `supports_parallel_tool_calls` | kernel serializes calls if absent/false |

docs/specifications/model/data-types.md

@@ -113,6 +113,9 @@ StreamEvent = oneof {
                                                              // MUST be emitted if the vendor's
                                                              // thinking blocks carry an integrity
                                                              // signature
+  redacted_thinking    { data: bytes }                     // a complete vendor-encrypted
+                                                             // reasoning block, not a fragment;
+                                                             // only when ThinkingSpec.supported
   tool_call_start      { id: string, name: string }
   tool_call_delta       { id: string, arguments_fragment: string }  // partial-JSON accumulation
   tool_call_done        { id: string }
@@ -152,6 +155,7 @@ Per [`architecture.md`](../architecture.md#canonical-message--tool-schema-format
 - `document` — inline non-image document content (e.g. a PDF), carrying `data: bytes`, `media_type: string`, and an optional `filename`. MUST be supported by every plugin for a model where `ModelSpec.supports_documents == true`; MUST be rejected with a clear `invalid_request` error (not silently dropped) if sent to a model where it's `false` — the same rule `image`/`supports_vision` already establishes, applied to a second, independent capability flag.
 - `tool_use` / `tool_result` — MUST be supported wherever `supports_tool_use == true`.
 - `thinking` / `redacted_thinking` — only relevant where `ThinkingSpec.supported == true`. **A `thinking` block MAY carry an opaque, vendor-specific integrity token** (e.g. a cryptographic signature) that the plugin must store verbatim and echo back unmodified on the next turn, or the vendor API will reject the request. The kernel and state backend MUST treat this token as an opaque blob — never inspected, re-derived, or reformatted, just round-tripped. On the wire, this is [`StreamEvent`](#streamevent)'s `thinking_signature` variant (`bytes`) — see [`examples.md`](examples.md).
+- A `redacted_thinking` block is the whole-block analogue of that rule: reasoning content the vendor encrypts outright, opaque even as text, that the plugin MUST still store verbatim and echo back unmodified on a later turn or the vendor rejects the entire conversation — not just the affected block. On the wire it arrives as [`StreamEvent`](#streamevent)'s `redacted_thinking` variant carrying `data: bytes`, and unlike `thinking_delta` it is never fragmented across events: there is nothing for the kernel to accumulate, so the vendor emits the block whole and the plugin forwards it whole into `ContentBlock`'s `redacted_thinking`. A plugin serving a vendor that produces such blocks MUST emit this variant rather than dropping the content or flattening it into a `thinking` block.
 
 Each model-provider adapter owns its own lossy translation between this canonical form and its vendor's wire format (e.g. OpenAI has no `thinking` block equivalent — an adapter targeting OpenAI simply never emits one).