HarnessError

Errors a harness reports when it cannot do what it was asked: start or resume a session, run or continue a turn, or change the session’s lifecycle. A failure the agent reports during a turn, such as its model rejecting a key, arrives in the turn’s stream as an error part, and the turn finishes with the reason error. Only generate and generateObject, which return a whole turn, fail on it, with TurnFailedError. An answer that does not match the schema generateObject asked for fails as Effect AI’s generateObject fails: with an AiError whose reason is its StructuredOutputError.

HarnessError says which agent failed and holds the reason, so callers can recover from one reason with Effect.catchReason("HarnessError", "NotFoundError", ...). The operation that failed is the one the caller ran, which its span names. Each reason has a description, what happened in the words of whoever reports it, and says with isRetryable whether trying again may succeed, as the reasons of AiError do.

Since v0.1.0

Errors

AgentContractError (class)

The agent sent the harness something it cannot read: an event it cannot translate, a call of a tool the host does not have, or a saved state it cannot decode.

Signature

declare class AgentContractError

Source

Since v0.1.0

HarnessError (class)

The error every harness operation fails with: which agent failed, and why.

Example (Recovering from one reason)

import { Session } from "@amends-dev/harness"
import { Effect } from "effect"

declare const session: Session.Session

const answer = session.generate({ prompt: "Hello" }).pipe(
  Effect.map((result) => result.text),
  Effect.catchReason("HarnessError", "UnavailableError", (error) =>
    Effect.succeed(`The agent is away: ${error.message}`)
  )
)

Signature

declare class HarnessError

Source

Since v0.1.0

HarnessErrorReason

Why a harness failed: one of the errors above, which HarnessError.reason holds.

Signature

declare const HarnessErrorReason: Schema.toTaggedUnion<
  "_tag",
  readonly [
    typeof UnsupportedError,
    typeof NotFoundError,
    typeof SessionReleasedError,
    typeof TurnInProgressError,
    typeof NoTurnError,
    typeof TurnFailedError,
    typeof AgentContractError,
    typeof UnavailableError,
    typeof UnknownError
  ]
>

Source

Since v0.1.0

HarnessErrorReason (type alias)

Signature

type HarnessErrorReason = typeof HarnessErrorReason.Type

Source

Since v0.1.0

NoTurnError (class)

The session has no turn for the operation: none running to suspend, or none to continue.

Signature

declare class NoTurnError

Source

Since v0.1.0

NotFoundError (class)

Something the agent was asked about does not exist, such as a session it lost.

Signature

declare class NotFoundError

Source

Since v0.1.0

SessionReleasedError (class)

The session was released: Harness.createSession picks it up again from what that returned, as resumeFrom.

Signature

declare class SessionReleasedError

Source

Since v0.1.0

TurnFailedError (class)

The agent reported that the turn failed, with the error of its error part.

Signature

declare class TurnFailedError

Source

Since v0.1.0

TurnInProgressError (class)

The session runs a turn, or holds one suspendTurn cut short, so it cannot start another, detach, or compact until the turn ends.

Signature

declare class TurnInProgressError

Source

Since v0.1.0

UnavailableError (class)

The agent cannot be reached right now, as when its bridge does not answer or its sandbox is gone. Trying again may succeed.

Signature

declare class UnavailableError

Source

Since v0.1.0

UnknownError (class)

The harness failed for a reason none of the others names, such as a sandbox it could not make a directory in.

Signature

declare class UnknownError

Source

Since v0.1.0

UnsupportedError (class)

The agent cannot do what it was asked, such as answer in JSON, compact on request, or work without a sandbox.

Signature

declare class UnsupportedError

Source

Since v0.1.0