@yaag/runtime 0.10.0 → 0.11.0

package/src/types.ts

@@ -1,7 +1,9 @@
 import type { Static, TSchema } from "typebox";
 import type { ModelSpec, ThinkingLevel, ThinkingSpec } from "./model/index.ts";
+import type { CompactionResult } from "./transport/index.ts";
 
 export type { ThinkingLevel } from "./model/index.ts";
+export type { CompactionResult } from "./transport/index.ts";
 
 /** Options for spawning one Agent (ADR-0001, ADR-0009, ADR-0026). */
 export interface SpawnOptions {
@@ -88,6 +90,25 @@ export interface ResolvedSpawnOptions extends Omit<SpawnOptions, "model" | "thin
   readonly thinking?: ThinkingLevel;
 }
 
+/**
+ * What a fork may change about the Agent it copies (ADR-0044).
+ *
+ * A fork inherits the source's resolved spawn options verbatim: model,
+ * thinking, tools, skills, system prompt, extensions and Ask defaults. `name`
+ * is the exception — the child always gets a fresh auto-name unless this object
+ * names one. The fork source becomes the child's default `parent`.
+ *
+ * The inherited model is the concrete one the source settled on, so the child
+ * never re-runs the source's fallback list; `fork({ model })` is the way out.
+ * A fork of a Worktree Agent gets its own fresh worktree, branched from the
+ * source's branch, so only committed state transfers. The child re-runs the
+ * ADR-0026 Tool Contract probe against its own effective options.
+ */
+export interface ForkOptions extends SpawnOptions {
+  /** true = pi's default compaction; a string = pi custom instructions. */
+  readonly compact?: boolean | string;
+}
+
 /** Topology-only fields that may change when spawning an Agent Definition. */
 export interface SpawnOverrides {
   /** Log and event label. Defaults to the definition's name; duplicates are suffixed. */
@@ -201,4 +222,25 @@ export interface Handle {
     options: StructuredAskOptions<Schema>,
   ): Promise<Static<Schema>>;
   ask(prompt: string, options?: AskOptions): Promise<string>;
+
+  /**
+   * Spawns a new Agent from a copy of this Agent's session (ADR-0044).
+   *
+   * The fork point is a settled Ask boundary: a call while an Ask is in flight
+   * rejects with `FORK_DURING_ASK`. An Agent that died mid-Ask, or that holds
+   * no session file, rejects with `FORK_REFUSED`. An Agent that exited cleanly
+   * stays forkable, so a program can build context, let the Agent exit, then
+   * fork its final state many times.
+   */
+  fork(overrides?: ForkOptions): Promise<Handle>;
+
+  /**
+   * Replaces this Agent's context with a summary of it (ADR-0043).
+   *
+   * `instructions` becomes pi's `customInstructions`. A call while an Ask is in
+   * flight rejects with `COMPACT_DURING_ASK`; a refusal from pi rejects with
+   * `COMPACT_FAILED`. The result reports what the summary call cost; each field
+   * is null when pi reported nothing for it.
+   */
+  compact(instructions?: string): Promise<CompactionResult>;
 }