Conversation

Conversations: append-only transcripts of immutable entries, with their agent, context and live work.

Creation (root, create, fork) commits atomically: the conversation, its ownership, the creation hook’s state, the agent change, and whatever init writes.

Since v0.0.0

---

utils

ContextView

Signature

declare const ContextView: ContextView

Source

Since v0.0.0

CreateOptions (interface)

What the creating commit applies after the creation hook.

Signature

export interface CreateOptions<E = never> {
  /** Applied with `Agent.configure` after the creation hook's copy. */
  readonly agent?: Agent.AgentChange
  /** Runs last in the creating commit. Table reads fail with `ReadAfterWrite` there; state access works. */
  readonly init?: (conversationId: ConversationId) => Effect.Effect<void, E, Tx.Tx>
}

Source

Since v0.0.0

abort

Abort the conversation’s work: withdraw its queued inputs and mark every live non-background task that ordinary traversal reaches (with background: true, every task it reaches and the queued inputs of their conversations), then wait until the conversation is idle.

Signature

declare const abort: (
  id: ConversationId,
  options?: { readonly background?: boolean }
) => Effect.Effect<void, SchedulerClosed | CommitError, Scheduler.Scheduler>

Source

Since v0.0.0

agent

The conversation’s agent, resolved now; see Agent.get.

Signature

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

Source

Since v0.0.0

compact

Start a manual compaction in one commit and return its task (pi spec §8.7). It summarizes the older part of the model context while the conversation keeps working, then places the summary through a write submission: at once when idle, otherwise at the next boundary, or stale when a newer head cut the context first. Its result (Live.CompactionResult, through Task.await) carries that submission’s ID, or nothing when there was nothing to compact. instructions add a focus to the summarization prompt.

Signature

declare const compact: (id: ConversationId, instructions?: string) => Effect.Effect<TaskId, CommitError, Harness>

Source

Since v0.0.0

configure

Change the conversation’s stored agent choices in their own commit; see Agent.configure.

Signature

declare const configure: (
  id: ConversationId,
  change: Agent.AgentChange
) => Effect.Effect<A, CommitError | E, Session.Session | Exclude<R, Tx.Tx>>

Source

Since v0.0.0

context

The conversation’s active transcript and the messages of its next model request, optionally cut off at a visible entry. The bounds are captured on the commit line; the entries are read after it.

Signature

declare const context: (
  id: ConversationId,
  options?: { readonly at?: EntryId }
) => Effect.Effect<ContextView, StorageFailure | SessionPoisoned | EntryNotVisible, Session.Session>

Source

Since v0.0.0

create

Create a conversation with explicitly selected ownership (default: ownerless).

Signature

declare const create: <E = never>(
  options?: CreateOptions<E> & { readonly ownership?: ConversationOwnership }
) => Effect.Effect<ConversationRecord, CommitError | E, Session.Session>

Source

Since v0.0.0

entries

Every visible entry of the conversation, oldest first, including inherited ones.

Signature

declare const entries: (
  id: ConversationId
) => Effect.Effect<ReadonlyArray<EntryRecord>, StorageFailure, Session.Session>

Source

Since v0.0.0

fork

Fork a conversation at one of its visible entries (see Tx.forkConversation). The fork starts with the agent its parent had at that entry; agent and init apply after that.

Signature

declare const fork: <E = never>(
  parent: ConversationId,
  at: EntryId,
  options?: CreateOptions<E> & { readonly ownership?: ConversationOwnership }
) => Effect.Effect<ConversationRecord, CommitError | E, Session.Session>

Source

Since v0.0.0

get

The committed conversation record.

Signature

declare const get: (
  id: ConversationId
) => Effect.Effect<Option.Option<ConversationRecord>, StorageFailure, Session.Session>

Source

Since v0.0.0

page

One page of the conversation’s visible entries, newest first, including entries inherited from fork ancestors. Pass the returned next cursor to continue.

Signature

declare const page: (
  id: ConversationId,
  limit: number,
  cursor?: Cursor
) => Effect.Effect<Page<EntryRecord>, StorageFailure, Session.Session>

Source

Since v0.0.0

root

The root conversation (ID 1). The first call creates it, with the creation hook, agent and init, in one commit. Later calls, including after a restart, return it and ignore the options.

Signature

declare const root: <E = never>(
  options?: CreateOptions<E>
) => Effect.Effect<ConversationRecord, CommitError | E, Session.Session>

Source

Since v0.0.0

submit

Admit a user input or a passive entry write in one commit (pi spec §6). An idle conversation places input as a user entry and starts a run; a busy one queues it in pi.inbox for the next boundary: followUp (default) after the run’s answer, steer after its current tool round, or reject with ConversationBusy. A repeated requestId returns the existing submission. Await it with Submission.wait.

Signature

declare const submit: (
  id: ConversationId,
  draft: SubmissionDraft
) => Effect.Effect<SubmissionId, CommitError | ConversationBusy, Harness>

Source

Since v0.0.0

view

The conversation’s view: its active entries and built-in state (pi.agent, pi.live, pi.inbox, pi.usage) as one JSON value; see View.get.

Signature

declare const view: (
  conversationId: ConversationId
) => Effect.Effect<View.ConversationView, ConversationNotFound | ReadError, Session.Session>

Source

Since v0.0.0

waitForIdle

Wait until the conversation has no live non-background work.

Signature

declare const waitForIdle: (id: ConversationId) => Effect.Effect<void, SchedulerClosed, Scheduler.Scheduler>

Source

Since v0.0.0

watch

Watch the conversation’s view: its current value, then JSON Patch frames per commit; see View.watch.

Signature

declare const watch: (
  conversationId: ConversationId
) => Effect.Effect<View.Watch, ConversationNotFound | ReadError, Session.Session | Effect>

Source

Since v0.0.0