agents 0.23.0 → 0.25.0

package/dist/harnesses/pi/index.d.ts

@@ -0,0 +1,348 @@
+import {
+  _ as LifecycleJobContext,
+  n as CapabilityStartContext,
+  s as LifecycleCapability,
+  v as LifecycleJobOutcome
+} from "../../capability-runner-DBAnGr6L.js";
+import { T as SkillSource } from "../../index-kbSUIer3.js";
+import {
+  AgentEventStream,
+  Conversation,
+  ConversationId,
+  ConversationRetryPolicy,
+  EntryRecord,
+  Harness,
+  ModelRef,
+  Registry,
+  ToolRegistration,
+  Tx,
+  UserInput
+} from "@earendil-works/pi-durable";
+import { SqliteStorage } from "@earendil-works/pi-durable/storage/sqlite";
+import { ModelThinkingLevel } from "@earendil-works/pi-ai";
+
+//#region src/harnesses/pi/context.d.ts
+/**
+ * pi's invocation context, as `@earendil-works/chord` defines it.
+ *
+ * pi-durable takes a chord `Context` on every call but does not re-export
+ * the type or its constructors. The harness needs only a background context
+ * and a way to add an abort signal, so both are inlined here instead of
+ * depending on chord directly. A chord `Context` is a plain structural
+ * interface (an abort signal, keyed values, and a name), so these interoperate
+ * with chord's own contexts inside pi.
+ *
+ * One limit: chord's own derived contexts read the abort signal through a
+ * private key rather than `abortSignal`, so a chord `withContextValue`
+ * wrapped around one of these would not see its signal. pi 0.99.2 never
+ * wraps a caller's context that way; `withAbortSignal` and `withCancel`
+ * read `abortSignal` and work.
+ *
+ * If pi-durable starts re-exporting chord's context helpers, replace this
+ * file with those.
+ */
+type Context$1 = Parameters<Harness["close"]>[0];
+//#endregion
+//#region src/harnesses/pi/session-store.d.ts
+/**
+ * pi's session store on a Durable Object's SQLite database.
+ *
+ * pi owns its sessions: conversations, entries, tasks, submissions, and
+ * documents live in pi's own schema, created and migrated by pi's portable
+ * `SqliteStorage`. This file only supplies the synchronous database facade
+ * pi asks for, over `ctx.storage.sql`, and moves pi's tables under a prefix
+ * so they cannot collide with the SDK's or the host's tables in the same
+ * object.
+ *
+ * It is the Durable Object counterpart of `agents/sessions` for a harness
+ * that brings its own session model, and has nothing pi-harness specific in
+ * it: any harness built on pi-durable can open its storage with it.
+ */
+type PiSessionStoreOptions = {
+  /**
+   * Prefix for every table and index pi creates. Must not start with `_cf_`,
+   * which Durable Objects reserve. Default `pi_`.
+   */
+  readonly prefix?: string;
+};
+/** Open pi-durable's storage over this object's SQLite database. */
+declare function openPiSessionStore(
+  storage: DurableObjectStorage,
+  options?: PiSessionStoreOptions
+): Promise<SqliteStorage>;
+//#endregion
+//#region src/harnesses/pi/types.d.ts
+/**
+ * `PiHarness`'s own types: how the harness addresses sessions and reports
+ * operations. Anything pi already publishes (input, transcript entries,
+ * events) is pi's type, used directly.
+ */
+/** A pi conversation, addressed by its id as a string. The root is `"1"`. */
+type PiSessionId = string;
+/**
+ * What a submission does when the session is already running.
+ *
+ * - `followUp` (default): answered after the current run, as its own run.
+ * - `steer`: joins the running work after the current tool round.
+ */
+type PiWhenBusy = "followUp" | "steer";
+type PiSubmitOptions = {
+  /** Default: the root session. */ readonly session?: PiSessionId /** Idempotency key. Submitting the same id twice returns the same receipt. */;
+  readonly operationId?: string;
+  readonly whenBusy?: PiWhenBusy;
+};
+type PiSessionOptions = {
+  /** Default: the root session. */ readonly session?: PiSessionId;
+};
+/** Returned once a submission is durable. It says nothing about the model yet. */
+type PiReceipt = {
+  readonly operationId: string;
+  readonly session: PiSessionId /** False when this operation id was already submitted. */;
+  readonly accepted: boolean;
+};
+/** How one operation ended. */
+type PiOperationResult = {
+  readonly operationId: string;
+  readonly session: PiSessionId /** `done`: answered. `unanswered`: failed, aborted, or withdrawn. */;
+  readonly status:
+    | "done"
+    | "unanswered" /** Why an unanswered operation ended, in pi's words. */;
+  readonly reason?: string /** The final assistant text, when answered. */;
+  readonly text?: string;
+};
+type PiPromptResponse = PiOperationResult & {
+  /** The session's active transcript after the operation. */ readonly messages: readonly EntryRecord[];
+};
+/** A submission pi has not settled yet. */
+type PiPendingOperation = {
+  readonly operationId: string;
+  readonly session: PiSessionId /** `queued` in pi's inbox, or `running` as part of the current run. */;
+  readonly status: "queued" | "running";
+};
+type PiSessionInfo = {
+  readonly id: PiSessionId /** The session this one was forked from. */;
+  readonly parent?: PiSessionId;
+  readonly busy: boolean;
+};
+//#endregion
+//#region src/harnesses/pi/harness.d.ts
+/** The root session's id. */
+declare const ROOT_SESSION: PiSessionId;
+/**
+ * What the harness factory is handed. The store is already open and pi's
+ * migrations have run, so a factory only has to decide how to call
+ * `Harness.open` — or call something else that satisfies the same contract.
+ */
+type PiHarnessContext = {
+  /** pi's storage over this object's SQLite, tables under the store prefix. */ readonly storage: SqliteStorage /** Background context, for the open itself. */;
+  readonly context: Context$1;
+};
+/**
+ * Builds pi's `Harness`. Return value is adopted as-is: the caller owns the
+ * registry (tools, system prompt, hooks, skills), `models`, `env`,
+ * `onReport` and anything else `HarnessOptions` grows.
+ *
+ * ```ts
+ * harness: ({ storage, context }) =>
+ *   Harness.open(storage, { models, registry }, context)
+ * ```
+ */
+type PiHarnessFactory = (
+  context: PiHarnessContext
+) => Harness | Promise<Harness>;
+/**
+ * Applied to a session the first time it is created. Without a model, a
+ * session's generation fails as unanswered until `session.setModel` sets one.
+ */
+type PiSessionDefaults = {
+  /** Model for new sessions. Change one session's with `session.setModel`. */ readonly model?: ModelRef;
+  readonly thinkingLevel?: ModelThinkingLevel /** pi's generation retries for new sessions. */;
+  readonly retry?: ConversationRetryPolicy;
+};
+/**
+ * How long the wake waits and when it hands a wait to the alarm. Defaults
+ * suit a real deployment; a test shortens them so a suite does not sit on
+ * the real heartbeat.
+ */
+type PiWakeTiming = {
+  /** A pi wait further away than this goes to the alarm. Default 60_000. */ readonly sleepThresholdMs?: number /** Longest one wake waits inside an alarm. Default 600_000. */;
+  readonly waitBudgetMs?: number /** Heartbeat while waiting, and the re-check for background work. Default 30_000. */;
+  readonly heartbeatMs?: number;
+};
+/** `PiHarness`'s options. Only `harness`, which opens pi, is required. */
+type PiHarnessOptions = {
+  /** Opens pi's `Harness` over the store this object prepared. */ readonly harness: PiHarnessFactory /** Applied to new sessions. */;
+  readonly defaults?: PiSessionDefaults;
+  readonly store?: PiSessionStoreOptions;
+  readonly timing?: PiWakeTiming;
+};
+/**
+ * pi-durable hosted in a Durable Object, behind a small harness interface:
+ * `harness.prompt()`, `harness.sessions`, `harness.session(id)`. How a session reaches a
+ * client (sockets, SSE, RPC) is the host's glue, built on `session.events()`.
+ *
+ * pi owns everything about a run: the transcript, the inbox of steers and
+ * follow-ups, generation and tool tasks, retries, crash recovery, and the
+ * live view. It keeps all of it in its own tables in this object's SQLite
+ * database (see `session-store.ts`).
+ *
+ * What pi cannot do on a Durable Object is wake itself: its scheduler runs
+ * in memory, and an evicted object has no memory. The harness is that wake,
+ * with one Lifecycle job per session. Input goes to pi once, in `submit()`,
+ * after the session's job is scheduled. The job waits while pi has live
+ * tasks in the session, rescheduling itself as a heartbeat, and completes
+ * when there are none. An eviction mid-run leaves the job due, so its alarm
+ * restarts the object, pi reopens and resumes its own tasks, and the job
+ * waits again.
+ *
+ * @experimental The API may change between releases.
+ */
+declare class PiHarness extends LifecycleCapability {
+  #private;
+  readonly sessions: PiSessions;
+  constructor(options: PiHarnessOptions);
+  onStart(_context: CapabilityStartContext): Promise<void>;
+  onJob(context: LifecycleJobContext): Promise<LifecycleJobOutcome | void>;
+  /** Close pi's in-memory resources. Durable state is untouched. */
+  dispose(): Promise<void>;
+  /** A handle on one session. No I/O until you call it. */
+  session(id?: PiSessionId): PiSession;
+  /** Submit a prompt and wait for its answer. */
+  prompt(
+    input: UserInput,
+    options?: PiSubmitOptions
+  ): Promise<PiPromptResponse>;
+  /** Durably submit a prompt. Resolves before the model runs. */
+  submit(input: UserInput, options?: PiSubmitOptions): Promise<PiReceipt>;
+  /** Stop one operation, or everything running in a session. */
+  abort(
+    options?: PiSessionOptions & {
+      readonly operationId?: string;
+    }
+  ): Promise<boolean>;
+  wait(
+    operationId: string,
+    options?: PiSessionOptions & {
+      readonly signal?: AbortSignal;
+    }
+  ): Promise<PiOperationResult>;
+  /** The session's active transcript, as pi's entries. */
+  messages(options?: PiSessionOptions): Promise<EntryRecord[]>;
+  /** Submissions pi has not settled yet, oldest first. */
+  pending(options?: PiSessionOptions): Promise<PiPendingOperation[]>;
+  /** The opened pi Harness, for anything the interface does not cover. */
+  pi(): Promise<Harness>;
+  /** @internal */
+  conversation(session: PiSessionId): Promise<Conversation>;
+  /** @internal */
+  storage(): Promise<SqliteStorage>;
+  /** @internal Configure a new session like the root. */
+  initSession(tx: Tx, id: ConversationId): Promise<void>;
+  /** @internal */
+  enqueue(
+    session: PiSessionId,
+    input: UserInput,
+    options: PiSubmitOptions
+  ): Promise<PiReceipt>;
+  /** @internal Withdraw a queued input, or abort the run it joined. */
+  withdraw(session: PiSessionId, operationId: string): Promise<boolean>;
+  /** @internal Wait for pi to settle an operation, by its request id. */
+  settled(
+    session: PiSessionId,
+    operationId: string,
+    signal?: AbortSignal
+  ): Promise<PiOperationResult>;
+}
+/** One pi conversation, addressed through the harness. */
+declare class PiSession {
+  #private;
+  readonly id: PiSessionId;
+  constructor(harness: PiHarness, id: PiSessionId);
+  /** Durably submit a prompt. Resolves before the model runs. */
+  submit(input: UserInput, options?: PiSubmitOptions): Promise<PiReceipt>;
+  /** Submit and wait for the answer and the updated transcript. */
+  prompt(
+    input: UserInput,
+    options?: PiSubmitOptions
+  ): Promise<PiPromptResponse>;
+  /** Join the running work after its current tool round. */
+  steer(
+    input: UserInput,
+    options?: Omit<PiSubmitOptions, "whenBusy">
+  ): Promise<PiReceipt>;
+  /** Wait for an operation to settle. Aborting `signal` stops only the wait. */
+  wait(operationId: string, signal?: AbortSignal): Promise<PiOperationResult>;
+  /**
+   * Withdraw one queued operation (or abort the run it joined), or, with no
+   * id, abort the session: pi withdraws queued inputs and aborts the
+   * running work.
+   */
+  abort(operationId?: string): Promise<boolean>;
+  /** Start a new context, optionally from a handoff note. */
+  reset(handoff?: string): Promise<void>;
+  setModel(model: ModelRef): Promise<void>;
+  /** The active transcript, as pi's entries since the newest reset. */
+  messages(): Promise<EntryRecord[]>;
+  /** pi's agent events for this session: a snapshot, then one batch per commit. */
+  events(context?: Context$1): Promise<AgentEventStream>;
+  busy(): Promise<boolean>;
+}
+/** Every pi conversation in this object. */
+declare class PiSessions {
+  #private;
+  constructor(harness: PiHarness);
+  get(id: PiSessionId): PiSession;
+  /** A new top-level session, configured like the root. */
+  create(): Promise<PiSession>;
+  /** A new session that sees `from`'s history up to its newest entry. */
+  fork(from: PiSessionId): Promise<PiSession>;
+  /**
+   * Every conversation, including ones subagent tools own. Read from pi's
+   * storage directly: the Harness has no conversation listing.
+   */
+  list(): Promise<PiSessionInfo[]>;
+}
+//#endregion
+//#region src/harnesses/pi/skills.d.ts
+/** Skills resolved from `agents/skills` sources for one process lifetime. */
+type ResolvedSkills = {
+  /** Changes when any source's fingerprint changes. */ readonly fingerprint: string /** Model-facing activation tools; empty when there are no skills. */;
+  readonly tools: readonly ToolRegistration[] /** System-prompt catalog, or null when there are no skills. */;
+  readonly catalog: string | null;
+  readonly warnings: readonly string[];
+};
+/**
+ * Register `agents/skills` sources on a pi registry: the activation tools
+ * and a "skills" system prompt section. Resolution reads the sources, so a
+ * host awaits this in its `harness` factory, before `Harness.open`.
+ */
+declare function addSkills(
+  registry: Registry,
+  sources: readonly SkillSource[]
+): Promise<ResolvedSkills>;
+//#endregion
+export {
+  PiHarness,
+  type PiHarnessContext,
+  type PiHarnessFactory,
+  type PiHarnessOptions,
+  type PiOperationResult,
+  type PiPendingOperation,
+  type PiPromptResponse,
+  type PiReceipt,
+  PiSession,
+  type PiSessionDefaults,
+  type PiSessionId,
+  type PiSessionInfo,
+  type PiSessionOptions,
+  type PiSessionStoreOptions,
+  PiSessions,
+  type PiSubmitOptions,
+  type PiWakeTiming,
+  type PiWhenBusy,
+  ROOT_SESSION,
+  type ResolvedSkills,
+  addSkills,
+  openPiSessionStore
+};
+//# sourceMappingURL=index.d.ts.map