ToolSourceError

Errors a tool source reports when it cannot do what it was asked: tell which tools it has, or run one. A tool that ran and reported its own failure is one of them, as CallFailedError.

ToolSourceError says which source failed and holds the reason, so callers can recover from one reason with Effect.catchReason("ToolSourceError", "AuthenticationError", ...), as a host does to ask for a connection again. 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. modelMessage is what a model reads of it. The descriptions of InvalidInputError and CallFailedError are written for it, to say what to correct and what the tool said. The description of any other reason may name an address or another internal, so the model reads only its default message.

Since v0.1.0

Constructors

reasonFromHttpClientError

Why a request that got no answer failed: a server that could not be reached is unavailable, and anything else about the request is unknown.

Signature

declare const reasonFromHttpClientError: (error: HttpClientError.HttpClientError) => ToolSourceErrorReason

Source

Since v0.1.0

Errors

AuthenticationError (class)

The source’s credentials are missing, invalid, or not allowed to do this.

Signature

declare class AuthenticationError

Source

Since v0.1.0

CallFailedError (class)

The tool ran and reported that it failed. Its description is what the tool said.

Signature

declare class CallFailedError

Source

Since v0.1.0

InvalidInputError (class)

The input does not match the tool’s parameters. Its description says what to correct.

Signature

declare class InvalidInputError

Source

Since v0.1.0

InvalidResponseError (class)

The source answered in a way its protocol does not allow, such as a result that is not JSON.

Signature

declare class InvalidResponseError

Source

Since v0.1.0

NotFoundError (class)

The source has no tool of the name it was asked to run, such as one it has removed since.

Signature

declare class NotFoundError

Source

Since v0.1.0

ToolSourceError (class)

What every operation of a tool source fails with: the source that failed, by its name, and the reason. Only an UnavailableError is worth trying again, as isRetryable says.

Example (Recovering from one reason)

import type { ToolSource } from "@amends-dev/toolkit"
import { Effect } from "effect"

declare const github: ToolSource.ToolSource
declare const askToConnectAgain: Effect.Effect<void>

// A refused credential is the connection's to fix; the other reasons stay failures.
const definitions = github.discover.pipe(
  Effect.catchReason("ToolSourceError", "AuthenticationError", () => Effect.as(askToConnectAgain, []))
)

Signature

declare class ToolSourceError

Source

Since v0.1.0

ToolSourceErrorReason

Why a tool source failed: one of the errors above, which ToolSourceError.reason holds.

Signature

declare const ToolSourceErrorReason: Schema.toTaggedUnion<
  "_tag",
  readonly [
    typeof AuthenticationError,
    typeof NotFoundError,
    typeof InvalidInputError,
    typeof CallFailedError,
    typeof UnavailableError,
    typeof InvalidResponseError,
    typeof UnsupportedError,
    typeof UnknownError
  ]
>

Source

Since v0.1.0

ToolSourceErrorReason (type alias)

Signature

type ToolSourceErrorReason = typeof ToolSourceErrorReason.Type

Source

Since v0.1.0

UnavailableError (class)

The source cannot answer now: it said that it is down or busy, or it could not be reached. The only reason worth trying again.

Signature

declare class UnavailableError

Source

Since v0.1.0

UnknownError (class)

The source failed in a way no other reason names, such as a defect in its code or a request that could not be sent. The model reads only that the source failed.

Signature

declare class UnknownError

Source

Since v0.1.0

UnsupportedError (class)

The source does not do what was asked, such as running a tool that asks for input first, returning an answer of a media type a tool cannot return, or speaking the server’s protocol.

Signature

declare class UnsupportedError

Source

Since v0.1.0