Tool

Tools the model can call. A tool has a name, a description, a Schema of its parameters, and an execute effect that runs with the ToolCall service of the call. Each call runs as a durable pi.tool task: its intent is committed before execute, and a crash during execute reruns it only when the tool declares replay: "safe".

Applications may attach their own fields to a tool ({ ...tool, snippet }) and read them typed in their sections.

import { Tool } from "@effective-harness/core"
import * as Effect from "effect/Effect"
import * as Schema from "effect/Schema"

const Read = Tool.make("read", {
  description: "Read a file",
  parameters: Schema.Struct({ path: Schema.String }),
  execute: ({ path }) => Effect.succeed(Tool.text(`contents of ${path}`))
})

Since v0.0.0

---

utils

Any (type alias)

A tool of any parameter type, as extensions hold them.

Signature

type Any = Tool<any>

Source

Since v0.0.0

Result (interface)

What a tool returns.

Signature

export interface Result {
  readonly content: ReadonlyArray<TextContent | ImageContent>
  /** Structured details for UIs; never sent to the model. */
  readonly details?: Json
  /** An error result: the model sees the content as a failure. */
  readonly isError?: boolean
  /** Ends the run after this tool round, instead of asking the model again. */
  readonly control?: { readonly terminate?: boolean }
  /** Usage of the tool's own model calls, if any. */
  readonly usage?: Usage
}

Source

Since v0.0.0

Tool (interface)

Signature

export interface Tool<A = any> {
  readonly name: string
  readonly description: string
  readonly parameters: Schema.Codec<A, any, never, never>
  /** Runs the call. A failure becomes an error result the model sees. */
  readonly execute: (args: A) => Effect.Effect<Result, unknown, ToolCall>
  /**
   * `"safe"`: a call interrupted by a crash runs again after recovery. Default `"unsafe"`: the model gets an
   * `interrupted` result with the output so far.
   */
  readonly replay?: "safe" | "unsafe"
  /** `"sequential"` calls run one at a time, after the parallel ones of the same round. */
  readonly executionMode?: "parallel" | "sequential"
  /** Bounds of the streamed output and the result. Default: 50 KiB, 2000 lines, keeping the beginning. */
  readonly outputLimits?: {
    readonly maxBytes?: number
    readonly maxLines?: number
    readonly retain?: "head" | "tail"
  }
}

Source

Since v0.0.0

declaration

The declaration offered to the model: name, description, and the JSON Schema of the parameters.

Signature

declare const declaration: (tool: Any) => ToolDeclaration

Source

Since v0.0.0

decodeArguments

Decode a call’s arguments with the tool’s parameters schema.

Signature

declare const decodeArguments: <A>(tool: Tool<A>, args: unknown) => any

Source

Since v0.0.0

make

Define a tool.

Signature

declare const make: <A>(name: string, options: Omit<Tool<A>, "name">) => Tool<A>

Source

Since v0.0.0

text

A result with one text part.

Signature

declare const text: (value: string, options?: Omit<Result, "content">) => Result

Source

Since v0.0.0