agents 0.25.0 → 0.26.0

package/dist/{harnesses → harness}/pi/index.d.ts

@@ -6,22 +6,18 @@ import {
 } from "../../capability-runner-DBAnGr6L.js";
 import { T as SkillSource } from "../../index-kbSUIer3.js";
 import {
+  AgentChange,
   AgentEventStream,
   Conversation,
-  ConversationId,
-  ConversationRetryPolicy,
   EntryRecord,
+  Extension,
   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";
+import { Api, Model, ModelThinkingLevel } from "@earendil-works/pi-ai";
 
-//#region src/harnesses/pi/context.d.ts
+//#region src/harness/pi/context.d.ts
 /**
  * pi's invocation context, as `@earendil-works/chord` defines it.
  *
@@ -34,44 +30,16 @@ import { ModelThinkingLevel } from "@earendil-works/pi-ai";
  *
  * 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.
+ * wrapped around one of these would not see its signal. pi-durable does not
+ * use `withContextValue` to wrap 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
+//#region src/harness/pi/types.d.ts
 /**
  * `PiHarness`'s own types: how the harness addresses sessions and reports
  * operations. Anything pi already publishes (input, transcript entries,
@@ -125,56 +93,59 @@ type PiSessionInfo = {
   readonly busy: boolean;
 };
 //#endregion
-//#region src/harnesses/pi/harness.d.ts
+//#region src/harness/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.
+ * What the factory is handed: the two things only the harness can build.
+ * Everything else `Harness.open` takes (models, registry, settings, env,
+ * onReport) the factory builds itself.
  */
 type PiHarnessContext = {
-  /** pi's storage over this object's SQLite, tables under the store prefix. */ readonly storage: SqliteStorage /** Background context, for the open itself. */;
+  /** pi's storage over this object's SQLite, its migrations already run. */ 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.
+ * Opens pi's `Harness`. The harness adopts what it returns.
  *
  * ```ts
- * harness: ({ storage, context }) =>
- *   Harness.open(storage, { models, registry }, context)
+ * harness: async ({ storage, context }) => {
+ *   const registry = createRegistry();
+ *   registry.install(await skills(sources));
+ *   return Harness.open(storage, { models, registry }, context);
+ * }
  * ```
  */
 type PiHarnessFactory = (
   context: PiHarnessContext
 ) => Harness | Promise<Harness>;
+/**
+ * A model, as pi-ai describes one: `createAI`'s `ai("@cf/…")` returns one.
+ *
+ * Only its `provider` and `id` are used. pi stores that reference with
+ * the session and resolves it, at each request, against the `Models` the
+ * factory opened pi with. So the model must be one those `Models` list,
+ * and options passed to `ai(id, options)` here, such as `fallback`, are not
+ * applied.
+ */
+type PiModel = Pick<Model<Api>, "provider" | "id">;
 /**
  * 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;
+  /**
+   * Model for new sessions, by its `provider` and `id`; it must be on the
+   * `Models` the factory opens pi with (see `PiModel`). Change one
+   * session's with `session.setModel`.
+   */
+  readonly model?: PiModel;
+  readonly thinkingLevel?: ModelThinkingLevel;
 };
 /** `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. */;
+  /** Opens pi's `Harness` over the storage this object prepared. */ readonly harness: PiHarnessFactory /** What a new session starts with. */;
   readonly defaults?: PiSessionDefaults;
-  readonly store?: PiSessionStoreOptions;
-  readonly timing?: PiWakeTiming;
 };
 /**
  * pi-durable hosted in a Durable Object, behind a small harness interface:
@@ -195,7 +166,7 @@ type PiHarnessOptions = {
  * restarts the object, pi reopens and resumes its own tasks, and the job
  * waits again.
  *
- * @experimental The API may change between releases.
+ * @beta The API may change between releases.
  */
 declare class PiHarness extends LifecycleCapability {
   #private;
@@ -236,8 +207,6 @@ declare class PiHarness extends LifecycleCapability {
   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,
@@ -252,6 +221,8 @@ declare class PiHarness extends LifecycleCapability {
     operationId: string,
     signal?: AbortSignal
   ): Promise<PiOperationResult>;
+  /** @internal The per-conversation defaults supported by pi-durable. */
+  agentDefaults(): AgentChange;
 }
 /** One pi conversation, addressed through the harness. */
 declare class PiSession {
@@ -280,7 +251,11 @@ declare class PiSession {
   abort(operationId?: string): Promise<boolean>;
   /** Start a new context, optionally from a handoff note. */
   reset(handoff?: string): Promise<void>;
-  setModel(model: ModelRef): Promise<void>;
+  /**
+   * Change this session's model, by its `provider` and `id`; it must be on
+   * the `Models` the factory opened pi with (see `PiModel`).
+   */
+  setModel(model: PiModel): 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. */
@@ -303,29 +278,52 @@ declare class PiSessions {
   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[];
+//#region src/harness/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 asynchronous 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/harness/pi/skills.d.ts
 /**
- * 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`.
+ * `agents/skills` sources as a pi extension, named `agents.skills`: the
+ * activation tools and a `skills` system prompt section. Install it on
+ * pi's registry in the harness factory.
+ *
+ * ```ts
+ * registry.install(await skills(sources));
+ * ```
  */
-declare function addSkills(
-  registry: Registry,
-  sources: readonly SkillSource[]
-): Promise<ResolvedSkills>;
+declare function skills(sources: readonly SkillSource[]): Promise<Extension>;
 //#endregion
 export {
   PiHarness,
   type PiHarnessContext,
   type PiHarnessFactory,
   type PiHarnessOptions,
+  type PiModel,
   type PiOperationResult,
   type PiPendingOperation,
   type PiPromptResponse,
@@ -338,11 +336,9 @@ export {
   type PiSessionStoreOptions,
   PiSessions,
   type PiSubmitOptions,
-  type PiWakeTiming,
   type PiWhenBusy,
   ROOT_SESSION,
-  type ResolvedSkills,
-  addSkills,
-  openPiSessionStore
+  openPiSessionStore,
+  skills
 };
 //# sourceMappingURL=index.d.ts.map