pi-continual-harness 0.1.0

package/README.md

@@ -0,0 +1,95 @@
+# pi-continual-harness
+
+Online self-improvement layer for the [pi](https://pi.dev) coding agent.
+
+This package owns **only the online optimizer layer**: a unified, in-trajectory
+harness-state store (prompt notes, memory, skill descriptions, sub-agent specs)
+plus a manual `/refine` that proposes **evidence-backed structured CRUD deltas**.
+
+It deliberately does **not** reinvent storage or offline refinement. It composes
+with:
+
+- **[pi-reflect](https://github.com/jo-inc/pi-reflect)** — offline transcript
+  → behavioral-file refinement (the "deep" path).
+- **pi-mem / pi-memory** — durable memory storage.
+
+The durable markdown export (`.pi/harness-state.md`) is the composition seam:
+pi-reflect can read and refine it, pi-mem can ingest it.
+
+## Why
+
+Grounded in two lines of research:
+
+- **Continual Harness** (arXiv [2605.09998](https://arxiv.org/abs/2605.09998)) —
+  reset-free online CRUD over prompt / sub-agents / skills / memory drawn from
+  the trajectory. Distinct from prompt-optimization methods that need episode
+  resets.
+- **ACE — Agentic Context Engineering** (arXiv
+  [2510.04618](https://arxiv.org/abs/2510.04618)) — context as an evolving
+  playbook. Key design lesson applied here: the optimizer emits **structured,
+  itemized deltas**, never prose prompt rewrites, to prevent context collapse
+  and brevity bias.
+
+Prime Intellect's Prime Agent ships a Continual Harness built on pi; this
+package is a minimal, package-shaped take on the same idea — **online only**,
+leaving offline and storage to the packages that already do them well.
+
+## Install
+
+```
+pi install git:github.com/<owner>/pi-continual-harness
+```
+
+Or drop `src/index.ts` into `~/.pi/agent/extensions/`.
+
+## Usage
+
+```
+/refine              # review last 25 turns, propose deltas
+/refine 50           # review last 50 turns
+/refine 25 --commit  # also export durable state to ~/.pi/agent/harness-state.md
+```
+
+The model-facing tools:
+
+- `harness_list [kind]` — read current state (optionally filtered by kind).
+- `harness_mutate { deltas: [...] }` — apply a batch of `create` / `update` /
+  `delete` deltas. Every `create` requires `evidence`.
+
+Active items are injected into the system prompt each turn as a structured
+block, appended to (never replacing) the base prompt.
+
+## How it works
+
+1. `/refine` gathers recent trajectory evidence from the current session branch.
+2. It sends a steering user message asking the agent to propose evidence-backed
+   CRUD deltas via `harness_mutate`.
+3. The agent calls the tools; each accepted delta updates the in-memory state,
+   which is snapshotted to the session via `appendEntry("harness-state", ...)`.
+4. Because pi's session tree branches at any entry, `/tree` navigation gives
+   rollback to any pre-refinement point for free — no bespoke snapshot system.
+
+This reuses the existing agent loop (no nested/hidden model calls), is
+model-agnostic, and keeps every delta visible and reviewable in the transcript.
+
+## Scope and non-goals
+
+- **In scope:** unified state store, online `/refine`, structured deltas,
+  prompt injection, branching rollback, durable markdown export.
+- **Out of scope (compose instead):** durable storage engines (pi-mem), offline
+  deep refinement of behavioral files (pi-reflect), live sub-agent
+  orchestration (pi-boss / pi-room). Sub-agent *specs* are stored as data only.
+
+## Status
+
+Scaffold (0.1.0). Extension points to grow into:
+
+- A pluggable delta proposer (currently the agent itself, via steering).
+- Project-local vs global durable paths.
+- Optional `turn_end` auto-trigger behind a setting (intentionally off by
+  default — autonomous self-mutation is a sharp edge).
+- Importance decay/prune policy.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "pi-continual-harness",
+  "version": "0.1.0",
+  "description": "Online self-improvement layer for pi. A unified, in-trajectory harness-state store (prompt notes, memory, skill descriptions, sub-agent specs) with a manual /refine that proposes evidence-backed structured CRUD deltas. Composes with pi-reflect (offline) and pi-mem (storage); owns only the online optimizer layer. Inspired by Continual Harness (arXiv 2605.09998) and ACE (arXiv 2510.04618).",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi.dev",
+    "pi-extension",
+    "continual-harness",
+    "self-improvement",
+    "refine",
+    "memory",
+    "harness",
+    "agent"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "main": "src/index.ts",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pungggi/pi-continual-harness.git"
+  },
+  "homepage": "https://github.com/pungggi/pi-continual-harness#readme",
+  "bugs": {
+    "url": "https://github.com/pungggi/pi-continual-harness/issues"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.74.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.74.0",
+    "@earendil-works/pi-ai": ">=0.74.0",
+    "typebox": ">=1.0.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm run test"
+  }
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+// pi-continual-harness — online self-improvement layer for pi.
+//
+// Owns ONLY the online optimizer layer over a unified harness-state store.
+// Composes with pi-reflect (offline refinement) and pi-mem (storage); does not
+// reinvent either. Manual /refine only — no autonomous mutation.
+//
+// See README for design rationale and the research it is grounded in.
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerInjection } from "./inject.js";
+import { registerRefine } from "./refine.js";
+import { registerTools } from "./tools.js";
+import { getState, reconstruct, STATE_ENTRY } from "./store.js";
+
+export default function continualHarness(pi: ExtensionAPI): void {
+  // Rebuild in-memory state from the current branch on every session start /
+  // reload / resume / fork. This is what makes refinements branch-local and
+  // rollback-able via /tree.
+  pi.on("session_start", async (_event, ctx) => {
+    reconstruct(ctx.sessionManager.getBranch() as Iterable<unknown>);
+    const n = getState().items.length;
+    if (n > 0) {
+      ctx.ui.notify(`Continual Harness: ${n} item(s) restored`, "info");
+    }
+  });
+
+  registerInjection(pi);
+  registerTools(pi);
+  registerRefine(pi);
+}
+
+export { STATE_ENTRY };

package/src/inject.ts

@@ -0,0 +1,49 @@
+// before_agent_start: inject the active harness state as a structured block
+// appended to the base system prompt. Never rewrites or replaces the base —
+// only appends, matching Continual Harness's "immutable base + supplemental".
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getState } from "./store.js";
+import type { ComponentKind } from "./types.js";
+
+const ORDER: ComponentKind[] = ["prompt", "memory", "skill", "subagent"];
+
+const TITLES: Record<ComponentKind, string> = {
+  prompt: "Self-improved prompt notes",
+  memory: "Remembered facts",
+  skill: "Available skill notes",
+  subagent: "Reusable sub-agent specs",
+};
+
+export function renderHarnessBlock(): string {
+  const state = getState();
+  if (state.items.length === 0) return "";
+
+  const sections: string[] = [];
+  for (const kind of ORDER) {
+    const items = state.items.filter((i) => i.kind === kind && i.active);
+    if (items.length === 0) continue;
+    const bullets = items
+      .map((i) => `- [${i.id}] ${i.content}`)
+      .join("\n");
+    sections.push(`### ${TITLES[kind]}\n${bullets}`);
+  }
+  if (sections.length === 0) return "";
+
+  return [
+    "",
+    "## Continual Harness state",
+    "Self-improved notes accumulated from past trajectories via /refine.",
+    "Treat these as durable working context. Update them with the harness_mutate tool when they are wrong or stale.",
+    "",
+    sections.join("\n\n"),
+  ].join("\n");
+}
+
+export function registerInjection(pi: ExtensionAPI): void {
+  pi.on("before_agent_start", async (event) => {
+    const block = renderHarnessBlock();
+    if (!block) return;
+    return { systemPrompt: event.systemPrompt + "\n" + block };
+  });
+}

package/src/refine.ts

@@ -0,0 +1,115 @@
+// /refine — the online optimizer. Manual only (no turn_end auto-trigger).
+//
+// Flow:
+//  1. Gather recent trajectory evidence from the current branch.
+//  2. Send a steering user message that asks the agent to propose evidence-
+//     backed CRUD deltas via harness_mutate (and to inspect state with
+//     harness_list first).
+//  3. The agent does the reasoning and calls the tools. Each accepted delta is
+//     recorded as a session entry, so /tree gives rollback for free.
+//
+// Why a steering message instead of a nested LLM call: it reuses the existing
+// agent loop, is model-agnostic, and keeps every delta visible and reviewable
+// in the transcript. No hidden model calls.
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { exportDurable, REFINE_ENTRY } from "./store.js";
+
+const DEFAULT_LOOKBACK_TURNS = 25;
+const DEFAULT_EVIDENCE_BYTES = 16000;
+
+// Minimal entry shape for trajectory walking; kept loose to avoid coupling to
+// pi's internal session entry types.
+type AnyEntry = {
+  type?: string;
+  customType?: string;
+  message?: {
+    role?: string;
+    content?: Array<{ type?: string; text?: string }>;
+  };
+};
+
+export function registerRefine(pi: ExtensionAPI): void {
+  pi.registerCommand("refine", {
+    description:
+      "Online self-improvement: review recent trajectory and propose evidence-backed CRUD deltas to the harness state. Usage: /refine [lookback-turns] [--commit]",
+    handler: async (args, ctx) => {
+      const { lookback, commit } = parseArgs(args);
+      ctx.ui.setStatus("harness", `Refining (last ${lookback} turns)…`);
+
+      const evidence = gatherEvidence(ctx, lookback);
+      const prompt = buildSteeringPrompt(evidence, lookback);
+
+      // Record that a refinement was kicked off (audit trail; branchable).
+      pi.appendEntry(REFINE_ENTRY, { lookback, commit, startedAt: Date.now() });
+
+      if (commit) {
+        // Flush current state to the durable file first so the agent refines
+        // against the same view pi-reflect / pi-mem would see.
+        try {
+          const path = await exportDurable();
+          ctx.ui.notify(`Durable state exported to ${path}`, "info");
+        } catch (err) {
+          ctx.ui.notify(`Durable export failed: ${(err as Error).message}`, "warning");
+        }
+      }
+
+      pi.sendUserMessage(prompt);
+      ctx.ui.setStatus("harness", undefined);
+    },
+  });
+}
+
+function parseArgs(args: string): { lookback: number; commit: boolean } {
+  const parts = args.trim().split(/\s+/).filter(Boolean);
+  let lookback = DEFAULT_LOOKBACK_TURNS;
+  let commit = false;
+  for (const p of parts) {
+    if (p === "--commit") commit = true;
+    else if (/^\d+$/.test(p)) lookback = Math.max(1, Math.min(200, Number(p)));
+  }
+  return { lookback, commit };
+}
+
+function gatherEvidence(ctx: ExtensionCommandContext, lookback: number): string {
+  const entries = ctx.sessionManager.getBranch() as AnyEntry[];
+  const messages = entries.filter((e) => e.type === "message" && e.message);
+  const recent = messages.slice(-lookback * 2); // ~2 entries per turn (user+assistant)
+  const lines: string[] = [];
+  let bytes = 0;
+  for (const e of recent) {
+    const role = e.message?.role ?? "?";
+    const text = (e.message?.content ?? [])
+      .map((c) => c.text ?? "")
+      .join(" ")
+      .replace(/\s+/g, " ")
+      .trim();
+    if (!text) continue;
+    const line = `[${role}] ${text}`;
+    if (bytes + line.length > DEFAULT_EVIDENCE_BYTES) {
+      lines.push("[…truncated…]");
+      break;
+    }
+    lines.push(line);
+    bytes += line.length;
+  }
+  return lines.join("\n") || "(no recent trajectory evidence found)";
+}
+
+function buildSteeringPrompt(evidence: string, lookback: number): string {
+  return [
+    `/refine (online self-improvement, last ${lookback} turns as evidence)`,
+    "",
+    "Review the trajectory evidence below. Identify DURABLE, REUSABLE corrections — things that will help in future turns, not one-off fixes. Then update the Continual Harness state.",
+    "",
+    "Steps:",
+    "1. Call harness_list to see the current state.",
+    "2. Call harness_mutate with small, surgical CRUD deltas. Every create MUST include concrete evidence from the trajectory. Prefer updating existing items over creating duplicates; delete items that are wrong, stale, or contradicted.",
+    "3. Keep prompt notes terse and behavioral. Memory facts should be specific. Skill/sub-agent entries should describe reusable patterns, not one task.",
+    "",
+    "Constraints: never rewrite the whole store; ground every change in evidence; if nothing durable is worth recording, say so and do nothing.",
+    "",
+    "## Trajectory evidence",
+    evidence,
+  ].join("\n");
+}

package/src/store.ts

@@ -0,0 +1,169 @@
+// The unified harness-state store.
+//
+// Two persistence layers:
+//  1. Session-scoped (the core): the full state is snapshotted via
+//     pi.appendEntry("harness-state", ...) after every mutation and
+//     reconstructed on session_start from the current branch. Because pi's
+//     session tree branches at any entry, navigating /tree to before a
+//     refinement and resuming gives rollback for free.
+//  2. Durable (the composition seam): exportDurable() writes the active items
+//     to a markdown file pi-reflect can read and refine offline, and pi-mem can
+//     ingest. Best-effort; the package works without it.
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import type { AppliedDelta, ComponentKind, Delta, HarnessItem, HarnessState } from "./types.js";
+
+const STATE_ENTRY = "harness-state";
+const REFINE_ENTRY = "harness-refinement";
+
+const DEFAULT_DURABLE_PATH = join(homedir(), ".pi", "agent", "harness-state.md");
+
+const IMPORTANCE_FLOOR = 0.3;
+
+// Module-scoped state. Rebuilt on every session_start, so it tracks the active
+// branch. Mutations are synchronous, so concurrent tool calls cannot interleave
+// inside a single mutation.
+let state: HarnessState = { items: [] };
+let version = 0;
+
+export function getState(): HarnessState {
+  return state;
+}
+
+export function listItems(kind?: ComponentKind): HarnessItem[] {
+  return kind ? state.items.filter((i) => i.kind === kind) : state.items;
+}
+
+function genId(): string {
+  return `h_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 7)}`;
+}
+
+function clamp(n: number): number {
+  return Math.max(0, Math.min(1, n));
+}
+
+/** Apply a single delta against the in-memory state. Does not persist. */
+function applyOne(delta: Delta): AppliedDelta {
+  if (delta.op === "create") {
+    const now = Date.now();
+    const item: HarnessItem = {
+      id: genId(),
+      kind: delta.kind,
+      content: delta.content,
+      evidence: delta.evidence,
+      importance: clamp(delta.importance ?? 0.5),
+      active: true,
+      createdAt: now,
+      updatedAt: now,
+    };
+    state.items.push(item);
+    return { op: "create", item };
+  }
+
+  if (delta.op === "update") {
+    const idx = state.items.findIndex((i) => i.id === delta.id);
+    if (idx < 0) throw new Error(`update: no item with id ${delta.id}`);
+    const before = state.items[idx]!;
+    const after: HarnessItem = {
+      ...before,
+      content: delta.content ?? before.content,
+      evidence: delta.evidence ?? before.evidence,
+      importance: clamp(delta.importance ?? before.importance),
+      active: delta.active ?? before.active,
+      updatedAt: Date.now(),
+    };
+    state.items[idx] = after;
+    return { op: "update", before, after };
+  }
+
+  // delete
+  const idx = state.items.findIndex((i) => i.id === delta.id);
+  if (idx < 0) throw new Error(`delete: no item with id ${delta.id}`);
+  state.items.splice(idx, 1);
+  return { op: "delete", id: delta.id, reason: delta.reason };
+}
+
+/**
+ * Apply a batch of deltas. All-or-nothing: if any delta throws, nothing is
+ * applied. Returns the applied deltas and the new version.
+ */
+export function applyDeltas(
+  deltas: Delta[],
+  persist: (snapshot: HarnessState, version: number) => void,
+): AppliedDelta[] {
+  const snapshotBefore = { items: state.items.map((i) => ({ ...i })) };
+  const applied: AppliedDelta[] = [];
+  try {
+    for (const d of deltas) applied.push(applyOne(d));
+  } catch (err) {
+    // Roll back in-memory state on failure.
+    state = snapshotBefore;
+    throw err;
+  }
+  version += 1;
+  persist(state, version);
+  return applied;
+}
+
+/** Reconstruct state from the current branch's last harness-state snapshot. */
+export function reconstruct(entries: Iterable<unknown>): void {
+  let last: HarnessState | undefined;
+  for (const raw of entries) {
+    const entry = raw as { type?: string; customType?: string; data?: { state?: HarnessState } };
+    if (entry.type === "custom" && entry.customType === STATE_ENTRY && entry.data?.state) {
+      last = entry.data.state;
+    }
+  }
+  state = last ? { items: last.items.map((i) => ({ ...i })) } : { items: [] };
+  version = 0;
+}
+
+/** Decrement importance of inactive/low-signal items; prune below the floor. */
+export function decayAndPrune(persist: (snapshot: HarnessState, version: number) => void): {
+  pruned: number;
+} {
+  const before = state.items.length;
+  state.items = state.items.filter((i) => i.importance >= IMPORTANCE_FLOOR);
+  version += 1;
+  persist(state, version);
+  return { pruned: before - state.items.length };
+}
+
+export { STATE_ENTRY, REFINE_ENTRY, IMPORTANCE_FLOOR };
+
+// ---- Durable export (composition seam with pi-reflect / pi-mem) -------------
+
+export async function exportDurable(path = DEFAULT_DURABLE_PATH): Promise<string> {
+  const lines: string[] = ["# Continual Harness State", ""];
+  const kinds: ComponentKind[] = ["prompt", "memory", "skill", "subagent"];
+  for (const kind of kinds) {
+    const items = state.items.filter((i) => i.kind === kind && i.active);
+    if (items.length === 0) continue;
+    lines.push(`## ${titleFor(kind)}`, "");
+    for (const i of items) {
+      lines.push(`- **[${i.id}]** (importance ${i.importance.toFixed(2)}) ${i.content}`);
+      lines.push(`  - evidence: ${i.evidence}`);
+    }
+    lines.push("");
+  }
+  if (lines.length <= 2) lines.push("_(no active items)_", "");
+  const body = lines.join("\n");
+  await mkdir(dirname(path), { recursive: true }).catch(() => {});
+  await writeFile(path, body, "utf8");
+  return path;
+}
+
+function titleFor(kind: ComponentKind): string {
+  switch (kind) {
+    case "prompt":
+      return "Supplemental prompt notes";
+    case "memory":
+      return "Memory facts";
+    case "skill":
+      return "Skill descriptions";
+    case "subagent":
+      return "Sub-agent specs";
+  }
+}

package/src/tools.ts

@@ -0,0 +1,110 @@
+// Model-facing tools. Two tools, kept lean for prompt economy:
+//  - harness_list:  read items (optionally by kind).
+//  - harness_mutate: apply a batch of structured CRUD deltas.
+//
+// Deltas — not prose rewrites — are the unit of self-improvement (ACE).
+// Each create requires `evidence`, so the model must ground every addition.
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import { applyDeltas, getState, listItems } from "./store.js";
+import type { AppliedDelta, ComponentKind, Delta } from "./types.js";
+
+const KIND_VALUES = ["prompt", "memory", "skill", "subagent"] as const;
+
+const CreateShape = Type.Object({
+  op: Type.Literal("create"),
+  kind: StringEnum(KIND_VALUES),
+  content: Type.String({ description: "The note/fact/description/spec text." }),
+  evidence: Type.String({
+    description: "Why this belongs in the harness state, grounded in trajectory evidence.",
+  }),
+  importance: Type.Optional(Type.Number({ minimum: 0, maximum: 1 })),
+});
+
+const UpdateShape = Type.Object({
+  op: Type.Literal("update"),
+  id: Type.String({ description: "Existing item id, e.g. h_..." }),
+  content: Type.Optional(Type.String()),
+  evidence: Type.Optional(Type.String()),
+  importance: Type.Optional(Type.Number({ minimum: 0, maximum: 1 })),
+  active: Type.Optional(Type.Boolean()),
+});
+
+const DeleteShape = Type.Object({
+  op: Type.Literal("delete"),
+  id: Type.String(),
+  reason: Type.String({ description: "Why this item is being removed." }),
+});
+
+const DeltaShape = Type.Union([CreateShape, UpdateShape, DeleteShape]);
+
+export function registerTools(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "harness_list",
+    label: "List harness state",
+    description:
+      "List items in the Continual Harness state (self-improved prompt notes, memory, skill descriptions, sub-agent specs). Optionally filter by kind.",
+    promptSnippet: "Read Continual Harness self-improvement state",
+    promptGuidelines: [
+      "Call harness_list before proposing changes so you operate on current state.",
+    ],
+    parameters: Type.Object({
+      kind: Type.Optional(StringEnum(KIND_VALUES)),
+    }),
+    async execute(_toolCallId, params) {
+      const kind = params.kind as ComponentKind | undefined;
+      const items = listItems(kind);
+      return {
+        content: [
+          {
+            type: "text",
+            text:
+              items.length === 0
+                ? "Harness state is empty."
+                : items
+                    .map(
+                      (i) =>
+                        `[${i.id}] (${i.kind}, importance ${i.importance.toFixed(2)}, ${i.active ? "active" : "inactive"}) ${i.content}\n  evidence: ${i.evidence}`,
+                    )
+                    .join("\n"),
+          },
+        ],
+        details: { count: items.length, items },
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "harness_mutate",
+    label: "Mutate harness state",
+    description:
+      "Apply a batch of structured CRUD deltas to the Continual Harness state. Each create requires evidence grounded in trajectory. Prefer many small surgical deltas over wholesale rewrites.",
+    promptSnippet: "Propose evidence-backed CRUD deltas to self-improvement state",
+    promptGuidelines: [
+      "Use harness_mutate during /refine or when you notice a durable, reusable correction. Ground every create in evidence. Prefer small surgical deltas.",
+    ],
+    parameters: Type.Object({
+      deltas: Type.Array(DeltaShape, { minItems: 1, maxItems: 20 }),
+    }),
+    async execute(_toolCallId, params) {
+      const deltas = params.deltas as Delta[];
+      const applied: AppliedDelta[] = applyDeltas(deltas, (snapshot, ver) => {
+        pi.appendEntry("harness-state", { state: snapshot, version: ver });
+      });
+      const summary = summarize(applied);
+      return {
+        content: [{ type: "text", text: summary }],
+        details: { applied, version: getState().items.length },
+      };
+    },
+  });
+}
+
+function summarize(applied: AppliedDelta[]): string {
+  const created = applied.filter((a) => a.op === "create").length;
+  const updated = applied.filter((a) => a.op === "update").length;
+  const deleted = applied.filter((a) => a.op === "delete").length;
+  return `Applied ${applied.length} delta(s): ${created} created, ${updated} updated, ${deleted} deleted.`;
+}

package/src/types.ts

@@ -0,0 +1,66 @@
+// Continual Harness — core types.
+//
+// Design notes (see README for the full rationale):
+//  - Four components per Continual Harness (arXiv 2605.09998): prompt, memory,
+//    skill, sub-agent spec. Each item carries `evidence` grounding it in the
+//    trajectory and an `importance` fitness signal (ACE-style).
+//  - Mutations are expressed as structured CRUD deltas, never as prose prompt
+//    rewrites. This follows ACE (arXiv 2510.04618): itemized, deterministic
+//    merges prevent context collapse and brevity bias.
+//  - The store is session-scoped (reset-free, online). A durable markdown
+//    export is the composition seam with pi-reflect / pi-mem (see store.ts).
+
+/** The four Continual Harness components. */
+export type ComponentKind = "prompt" | "memory" | "skill" | "subagent";
+
+/** A single item in the unified harness store. */
+export interface HarnessItem {
+  id: string;
+  kind: ComponentKind;
+  /** Payload: a prompt note, a memory fact, a skill description, or a sub-agent spec. */
+  content: string;
+  /** Why this item exists, grounded in trajectory evidence. Required for every create. */
+  evidence: string;
+  /** Fitness signal in [0,1]. Items below a threshold can be pruned/deactivated. */
+  importance: number;
+  /** Whether the item is injected into the system prompt each turn. */
+  active: boolean;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface HarnessState {
+  items: HarnessItem[];
+}
+
+/** Structured CRUD delta. The unit of self-improvement. */
+export type Delta =
+  | {
+      op: "create";
+      kind: ComponentKind;
+      content: string;
+      evidence: string;
+      importance?: number;
+    }
+  | {
+      op: "update";
+      id: string;
+      content?: string;
+      evidence?: string;
+      importance?: number;
+      active?: boolean;
+    }
+  | { op: "delete"; id: string; reason: string };
+
+/** Result of applying a single delta; returned to the model for confirmation. */
+export type AppliedDelta =
+  | { op: "create"; item: HarnessItem }
+  | { op: "update"; before: HarnessItem; after: HarnessItem }
+  | { op: "delete"; id: string; reason: string };
+
+export const KIND_LABEL: Record<ComponentKind, string> = {
+  prompt: "Supplemental prompt notes",
+  memory: "Memory facts",
+  skill: "Skill descriptions",
+  subagent: "Sub-agent specs",
+};