Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions api/harness.go
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,26 @@ type Harness interface {
Run(ctx context.Context, s *Start, sink EventSink) error
}

// HarnessRunPreparer optionally prepares the transport or other resources for one Run before the
// host records its execution. PrepareRun must not invoke the harness, send Start, or perform any
// model or tool effect. An error therefore proves that no execution was delegated.
//
// On error an implementation must release anything it acquired and return no prepared run. A
// successful call transfers one prepared run to the caller. The host either calls Run exactly once
// or closes it without running it.
type HarnessRunPreparer interface {
PrepareRun(ctx context.Context) (PreparedHarnessRun, error)
}

// PreparedHarnessRun is one prepared Harness.Run. Run may be called exactly once. Close is
// idempotent and may race with Run: if Close wins, Run must fail without invoking the harness; if
// Run wins, Close cancels the active run. Close is also safe after Run returns. Implementations own
// cleanup and cannot report a second cleanup error.
type PreparedHarnessRun interface {
Run(ctx context.Context, s *Start, sink EventSink) error
Close()
}

// Descriptor is a harness's static contract.
type Descriptor struct {
ID string
Expand Down
10 changes: 10 additions & 0 deletions changelog/unreleased/harness-connect-preparation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
category: Fixed
Comment thread
Tatsinnit marked this conversation as resolved.
Resolved
---

- A new `Exec` over `Harness.Connect` now opens its actual stream before recording
`EXECUTION_START`. If Connect cannot be opened, no execution records are appended and retrying the
same session starts its first turn normally. The host still sends `Start` only after the start and
every input are durable; cancellation after successful preparation and send or receive failures
remain uncertain and keep any recorded attempt in later history. Go harness adapters can opt into
the same boundary with `api.HarnessRunPreparer` (`EXE-45`).
9 changes: 9 additions & 0 deletions changelog/unreleased/harness-run-preparer.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
---
category: Added
---

- Go harness adapters can implement `api.HarnessRunPreparer` to acquire the transport for one
execution before it is recorded, without invoking the harness or sending `Start`. The returned
`api.PreparedHarnessRun` is used at most once or closed; a concurrent close either prevents Run
or cancels it. `harnesswire.ClientHarness` implements the extension for its `Harness.Connect`
stream (`EXE-45`).
12 changes: 12 additions & 0 deletions changelog/unreleased/harnesswire-terminal-compat.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
---
category: Compatibility
---

- `Harness.Connect` now fails an execution for four wire shapes the host previously accepted: clean
closure without `EVENT_END`; harness-sent `EVENT_INPUT`, `EVENT_LIFECYCLE`, `EVENT_ERROR`, or an
unspecified/unknown kind; any frame after `EVENT_END`; and a harness-owned non-OK final RPC status
after `EVENT_END{COMPLETED}` while the caller remains live. Caller cancellation or deadline during
the bounded post-END telemetry flush does not replace a completed harness result (`WIRE-12`).
- A new `Exec` whose Connect preparation fails with `UNAVAILABLE` or `DEADLINE_EXCEEDED` while the
caller remains live now returns `UNAVAILABLE` with `agentsessions/HARNESS_UNAVAILABLE` and fixed
host text. Before this change it returned `INTERNAL` with the raw Connect diagnostic.
23 changes: 22 additions & 1 deletion controller/controller.go
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,11 @@ var ErrInvalidExecutionLog = errors.New("controller: invalid execution log")
// The original cause is retained for callers to distinguish cancellation from endpoint failure.
var ErrHarnessDescribeFailed = errors.New("controller: describe harness failed")

// ErrHarnessPrepareFailed identifies failure to prepare a harness run before its execution is
// recorded. The original cause is retained for callers to distinguish cancellation from endpoint
// failure. No Start send was attempted.
var ErrHarnessPrepareFailed = errors.New("controller: prepare harness run failed")

// ErrHarnessMismatch rejects replay/recovery with a different resolved harness name.
var ErrHarnessMismatch = errors.New("controller: harness does not match recorded invocation")

Expand Down Expand Up @@ -339,6 +344,22 @@ func (c *Controller) Exec(ctx context.Context, har api.Harness, inputs []api.Mes
}
}

run := har.Run
if preparer, ok := har.(api.HarnessRunPreparer); ok {
prepared, prepareErr := preparer.PrepareRun(ctx)
if prepareErr != nil {
if prepared != nil {
prepared.Close()
}
return fmt.Errorf("%w: %w", ErrHarnessPrepareFailed, prepareErr)
}
if prepared == nil {
return fmt.Errorf("%w: preparer returned nil", ErrHarnessPrepareFailed)
}
defer prepared.Close()
run = prepared.Run
}

// Record every invocation before inputs so recovery can detect partially committed turns.
config := bytes.Clone(c.startConfig)
last := expectedLastSeq
Expand Down Expand Up @@ -388,7 +409,7 @@ func (c *Controller) Exec(ctx context.Context, har api.Harness, inputs []api.Mes
ResumeFromSeq: c.startResumeFromSeq,
}
sink := &liveSink{c: c, executionID: executionID, modelDefault: model, modelPolicy: c.invocationPolicy(model), guard: &sinkGuard{}, desc: &desc, har: har, calls: make(map[string]bool), runCtx: runCtx}
runErr := har.Run(runCtx, start, sink)
runErr := run(runCtx, start, sink)
stop := sink.guard.close()
if stop != nil {
if runErr == nil || !errors.Is(stop, api.ErrApprovalParked) {
Expand Down
186 changes: 186 additions & 0 deletions controller/prepare_run_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,186 @@
package controller_test

import (
"context"
"errors"
"testing"

"github.com/agent-primitives/sessions/api"
"github.com/agent-primitives/sessions/controller"
"github.com/agent-primitives/sessions/eventlog"
)

type preparedRunHarness struct {
executionConfigHarness
prepareErr error
prepareValueOnErr bool
prepare, runs, closes int
beforeRun func()
runErr error
}

func (h *preparedRunHarness) PrepareRun(context.Context) (api.PreparedHarnessRun, error) {
h.prepare++
if h.prepareErr != nil {
if h.prepareValueOnErr {
return &testPreparedRun{h: h}, h.prepareErr
}
return nil, h.prepareErr
}
return &testPreparedRun{h: h}, nil
}

type testPreparedRun struct {
h *preparedRunHarness
used bool
closed bool
}

func (r *testPreparedRun) Run(ctx context.Context, start *api.Start, sink api.EventSink) error {
if r.used {
return errors.New("prepared run reused")
}
r.used = true
r.h.runs++
if r.h.beforeRun != nil {
r.h.beforeRun()
}
if r.h.runErr != nil {
return r.h.runErr
}
return r.h.Run(ctx, start, sink)
}

func (r *testPreparedRun) Close() {
if !r.closed {
r.closed = true
r.h.closes++
}
}

func TestExecPreparesHarnessBeforeFirstAppend(t *testing.T) {
log := eventlog.AsStore(eventlog.New())
c, err := controller.New(log, echoModel)
if err != nil {
t.Fatal(err)
}
h := &preparedRunHarness{}
h.beforeRun = func() {
recs, err := log.Read(1)
if err != nil {
t.Fatal(err)
}
if len(recs) != 2 || recs[0].Event.Kind != api.EventExecutionStart || recs[1].Event.Kind != api.EventInput {
t.Fatalf("prepared Run saw records %+v, want committed start and input", recs)
}
}
if err := c.Exec(t.Context(), h, []api.Message{msg("hello")}, 0); err != nil {
t.Fatal(err)
}
if h.prepare != 1 || h.runs != 1 || h.closes != 1 {
t.Fatalf("prepare/run/close=%d/%d/%d, want 1/1/1", h.prepare, h.runs, h.closes)
}
}

func TestExecPrepareFailureLeavesJournalUntouched(t *testing.T) {
log := eventlog.AsStore(eventlog.New())
c, err := controller.New(log, echoModel)
if err != nil {
t.Fatal(err)
}
cause := errors.New("connect failed before Start")
h := &preparedRunHarness{prepareErr: cause}
err = c.Exec(t.Context(), h, []api.Message{msg("hello")}, 0)
if !errors.Is(err, controller.ErrHarnessPrepareFailed) || !errors.Is(err, cause) {
t.Fatalf("Exec=%v, want preparation failure retaining %v", err, cause)
}
if head, headErr := log.Head(); headErr != nil || head != 0 {
t.Fatalf("head=%d err=%v, want untouched journal", head, headErr)
}
if h.prepare != 1 || h.runs != 0 || h.closes != 0 {
t.Fatalf("prepare/run/close=%d/%d/%d, want 1/0/0", h.prepare, h.runs, h.closes)
}
}

func TestExecDefensivelyClosesPreparedValueReturnedWithError(t *testing.T) {
log := eventlog.AsStore(eventlog.New())
c, err := controller.New(log, echoModel)
if err != nil {
t.Fatal(err)
}
cause := errors.New("prepare failed after allocation")
h := &preparedRunHarness{prepareErr: cause, prepareValueOnErr: true}
err = c.Exec(t.Context(), h, nil, 0)
if !errors.Is(err, controller.ErrHarnessPrepareFailed) || !errors.Is(err, cause) {
t.Fatalf("Exec=%v, want preparation failure retaining %v", err, cause)
}
if h.prepare != 1 || h.runs != 0 || h.closes != 1 {
t.Fatalf("prepare/run/close=%d/%d/%d, want 1/0/1", h.prepare, h.runs, h.closes)
}
}

func TestExecClosesPreparedRunWhenAppendFails(t *testing.T) {
cause := errors.New("append failed")
log := rejectAppendStore{Store: eventlog.AsStore(eventlog.New()), err: cause}
c, err := controller.New(log, echoModel)
if err != nil {
t.Fatal(err)
}
h := &preparedRunHarness{}
err = c.Exec(t.Context(), h, []api.Message{msg("hello")}, 0)
if !errors.Is(err, cause) || errors.Is(err, controller.ErrHarnessPrepareFailed) {
t.Fatalf("Exec=%v, want append failure %v", err, cause)
}
if h.prepare != 1 || h.runs != 0 || h.closes != 1 {
t.Fatalf("prepare/run/close=%d/%d/%d, want 1/0/1", h.prepare, h.runs, h.closes)
}
}

func TestExecClosesPreparedRunWhenInputAppendFails(t *testing.T) {
cause := errors.New("input append failed")
base := eventlog.AsStore(eventlog.New())
log := &failInputStore{Store: base, failAt: 2, err: cause}
c, err := controller.New(log, echoModel)
if err != nil {
t.Fatal(err)
}
h := &preparedRunHarness{}
err = c.Exec(t.Context(), h, []api.Message{msg("one"), msg("two")}, 0)
if !errors.Is(err, cause) || errors.Is(err, controller.ErrHarnessPrepareFailed) {
t.Fatalf("Exec=%v, want input append failure %v", err, cause)
}
if h.prepare != 1 || h.runs != 0 || h.closes != 1 {
t.Fatalf("prepare/run/close=%d/%d/%d, want 1/0/1", h.prepare, h.runs, h.closes)
}
recs, readErr := base.Read(1)
if readErr != nil {
t.Fatal(readErr)
}
if len(recs) != 2 || recs[0].Event.Kind != api.EventExecutionStart || recs[1].Event.Kind != api.EventInput {
t.Fatalf("records=%+v, want existing incomplete invocation", recs)
}
}

func TestExecPreparedRunFailureRemainsDurable(t *testing.T) {
log := eventlog.AsStore(eventlog.New())
c, err := controller.New(log, echoModel)
if err != nil {
t.Fatal(err)
}
cause := errors.New("Start send outcome unknown")
h := &preparedRunHarness{runErr: cause}
err = c.Exec(t.Context(), h, []api.Message{msg("hello")}, 0)
if !errors.Is(err, cause) || errors.Is(err, controller.ErrHarnessPrepareFailed) {
t.Fatalf("Exec=%v, want Run failure %v without preparation marker", err, cause)
}
recs, readErr := log.Read(1)
if readErr != nil {
t.Fatal(readErr)
}
if len(recs) != 3 || recs[0].Event.Kind != api.EventExecutionStart || recs[1].Event.Kind != api.EventInput || recs[2].Event.Kind != api.EventError {
t.Fatalf("records=%+v, want durable failed execution", recs)
}
if h.prepare != 1 || h.runs != 1 || h.closes != 1 {
t.Fatalf("prepare/run/close=%d/%d/%d, want 1/1/1", h.prepare, h.runs, h.closes)
}
}
11 changes: 11 additions & 0 deletions docs/harness-authoring.md
Original file line number Diff line number Diff line change
Expand Up @@ -135,6 +135,17 @@ empty/`echo` fallback. Old sessions/journals stay unchanged; see

The host hands you a `Start` and an `EventSink`.

An out-of-process adapter can implement the optional Go interface `api.HarnessRunPreparer` to open
the actual transport for one `Run` before the host records a new execution. Preparation must not
invoke the harness or send `Start`; its only positive guarantee is that a preparation error happened
before delegation. The host closes an unused preparation and calls a successful prepared run at most
once, after `EXECUTION_START` and every `INPUT` are durable. `harnesswire.ClientHarness` implements
this for `Harness.Connect`. A wrapper around it must forward the optional interface to keep that
pre-journal boundary. A failed `Send(Start)` or later receive is not proof of non-delivery and stays
a durable failed execution (`EXE-45`). In particular, successfully opening a client stream does not
prove that a router or harness will accept `Start`; a refusal surfaced by Send or Recv remains
uncertain and is not filtered from later history.

<!-- doccheck: skip excerpt of api.Start; the real definition is in api/harness.go -->
```go
type Start struct {
Expand Down
Loading
Loading