Agent

A conversation’s agent: its stored choices (pi.agent), resolved against the registry and the settings.

The stored state holds only names and plain values: the model, the thinking level, the selected extensions, a tool filter, instructions, and the working directory. Code comes from the registry by name at each resolution, so a stored choice survives restarts and reloads; a name that is not installed is skipped until it is.

import { Agent, Conversation, type Ids, type Tool } from "@effective-harness/core"
import * as Effect from "effect/Effect"

declare const id: Ids.ConversationId
declare const Read: Tool.Any

const program = Effect.gen(function* () {
  yield* Conversation.configure(id, { model: { provider: "anthropic", modelId: "claude-sonnet-5-5" }, tools: [Read] })
  const agent = yield* Agent.get(id)
  agent.tools.map((tool) => tool.name) // ["read"]
})

Since v0.0.0

---

utils

Agent (interface)

A conversation’s agent, resolved against a registry snapshot and the settings.

Signature

export interface Agent<T extends Tool.Any = Tool.Any> {
  readonly model?: ModelRef
  readonly thinkingLevel: ThinkingLevel
  readonly extensions: ReadonlyArray<Extension.Extension<T>>
  /** The tools offered: the selected extensions' tools, wrapped, then filtered. */
  readonly tools: ReadonlyArray<T>
  /** Extension sections, then `instructions` when set. */
  readonly sections: ReadonlyArray<Extension.Section<T>>
  readonly instructions?: string
  readonly cwd?: string
}

Source

Since v0.0.0

AgentChange (interface)

A change of the stored choices. A given field replaces the stored one, null clears it, undefined changes nothing. Extension and tool objects stand for their names.

Signature

export interface AgentChange {
  readonly model?: ModelRef | null
  readonly thinkingLevel?: ThinkingLevel | null
  readonly extensions?:
    ReadonlyArray<Named> | { readonly add?: ReadonlyArray<Named>; readonly remove?: ReadonlyArray<Named> } | null
  readonly tools?: ReadonlyArray<Named> | { readonly remove: ReadonlyArray<Named> } | null
  readonly instructions?: string | null
  readonly cwd?: string | null
}

Source

Since v0.0.0

AgentDoc

The built-in agent state (pi.agent). Rewindable with asOf, so a fork starts with the agent its parent had at the fork entry. Every change stores a complete base.

Signature

declare const AgentDoc: State.ConversationDefinition<any>

Source

Since v0.0.0

AgentState

The stored choices of one conversation. Unset fields follow the host.

Signature

declare const AgentState: any

Source

Since v0.0.0

AgentState (type alias)

Signature

type AgentState = typeof AgentState.Type

Source

Since v0.0.0

ModelRef

A model by provider and ID, as stored; the ModelCatalog resolves it to an effect/ai model.

Signature

declare const ModelRef: any

Source

Since v0.0.0

ModelRef (type alias)

Signature

type ModelRef = typeof ModelRef.Type

Source

Since v0.0.0

ThinkingLevel

Signature

declare const ThinkingLevel: any

Source

Since v0.0.0

ThinkingLevel (type alias)

Signature

type ThinkingLevel = typeof ThinkingLevel.Type

Source

Since v0.0.0

applyChange

Apply a change to stored choices.

Signature

declare const applyChange: (state: AgentState, change: AgentChange) => AgentState

Source

Since v0.0.0

configure

Change a conversation’s stored choices in the current transaction.

Signature

declare const configure: (conversationId: ConversationId, change: AgentChange) => any

Source

Since v0.0.0

created

The built-in part of every commit that creates or forks a conversation, for pi.agent: a fork keeps its asOf copy; a new task-owned conversation copies the stored agent of its owner task’s conversation; a new ownerless one starts empty.

Signature

declare const created: (record: ConversationRecord) => any

Source

Since v0.0.0

get

A conversation’s agent, resolved now from its committed pi.agent (absent reads as {}), the current registry snapshot and the settings. Never writes. Resolution problems, such as a wrapper whose target is gone, go to report (default: a logged warning).

Signature

declare const get: (
  conversationId: ConversationId,
  options?: { readonly report?: (cause: Cause.Cause<unknown>) => Effect.Effect<void> }
) => Effect.Effect<Agent, ReadError, Session | Registry | Settings>

Source

Since v0.0.0

hooks

The handlers of the selected extensions’ hooks for tasks named taskName, in extension order.

Signature

declare const hooks: (agent: Agent, taskName: string) => ReadonlyArray<object>

Source

Since v0.0.0

resolve

Resolve stored choices (absent: every field unset) against a registry snapshot and settings. Problems with wrappers are collected in problems.

Signature

declare const resolve: (
  state: AgentState | undefined,
  snapshot: Snapshot,
  settings: Resolved,
  problems?: Array<unknown>
) => Agent

Source

Since v0.0.0

stored

The stored choices; {} when absent.

Signature

declare const stored: (conversationId: ConversationId) => Effect.Effect<AgentState, ReadError, Session>

Source

Since v0.0.0