pi-continual-harness 0.5.1 → 0.6.0

package/README.md

@@ -178,9 +178,16 @@ for auto-refine via `proposer` in the [config](#configuration). Both paths are
 audited: the `harness-refinement` entry records which proposer ran and how many
 deltas it applied directly.
 
-A dedicated-model proposer (a hidden LLM call) is the obvious next alternate
-the interface supports, but is intentionally not shipped — non-visible model
-spend is a tradeoff kept as a separate decision (see `docs/ROADMAP.md`).
+A dedicated-model proposer — one that makes its own (hidden) LLM call to
+produce deltas directly — is the obvious next alternate. This package still
+does **not** ship one (hidden model spend is a tradeoff kept as a separate
+decision; see `docs/ROADMAP.md`), but it now **enables** one: when a model is
+available, `/refine` injects a one-shot `complete(prompt, opts?)` into
+`ProposeInput` and records any `modelCall` telemetry a proposer returns
+(model, tokens, latency, ok/error) in the `harness-refinement` audit entry —
+so a companion package can ship a dedicated-model proposer whose spend stays
+**audited, not hidden**. Both `complete` and `modelCall` are optional;
+`steering` and `dedupe` ignore them, so the default behavior is unchanged.
 
 Register your own proposer from another extension (the registry is re-exported
 from the package entry):
@@ -190,7 +197,9 @@ import { registerProposer } from "pi-continual-harness";
 
 registerProposer({
   name: "my-proposer",
-  async propose({ evidence, state }) {
+  async propose({ evidence, state, complete }) {
+    // `complete` is injected when a model is available (undefined otherwise);
+    // a dedicated-model proposer calls it and returns deltas + modelCall telemetry.
     /* inspect evidence + state, return deltas (and/or a steering message) */
     return { deltas: [/* { delta, rationale } */] };
   },
@@ -228,8 +237,10 @@ Then `"my-proposer"` is selectable via `/refine --proposer my-proposer` or
 
 Open extension points (see `docs/ROADMAP.md`):
 
-- A dedicated-model proposer (interface ready; the hidden-model-spend tradeoff
-  is a separate decision).
+- A dedicated-model proposer (the enabler landed: `complete` injection +
+  `modelCall` telemetry; the proposer logic itself is left to a companion
+  package — the hidden-model-spend tradeoff is resolved by making the spend
+  audited rather than shipping it invisible).
 - Correction-side outcome signals (promotion is shipped; autonomous demotion
   is high-false-positive, so it is served by `/harness drop`, `prune --decay`,
   and the `dedupe` proposer — a fuzzy `corrections` proposer is the natural

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-continual-harness",
-  "version": "0.5.1",
+  "version": "0.6.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",

package/src/index.ts

@@ -47,13 +47,26 @@ export default function continualHarness(pi: ExtensionAPI): void {
 
 export { STATE_ENTRY };
 
+// Core domain types (re-exported so companion packages — e.g. a dedicated-model
+// proposer — can build and validate deltas without reaching into internal paths).
+export {
+  type AppliedDelta,
+  type ComponentKind,
+  type Delta,
+  type HarnessItem,
+  type HarnessState,
+} from "./types.js";
+
 // Public extension API: other extensions can register their own delta proposer
 // (see src/proposer.ts) and it becomes selectable via /refine --proposer <name>
 // or the `proposer` config key.
 export {
   listProposers,
   registerProposer,
+  type CompleteOptions,
+  type CompleteResult,
   type DeltaProposer,
+  type ModelCallTelemetry,
   type ProposeInput,
   type ProposedDelta,
   type ProposeResult,

package/src/proposer.ts

@@ -14,15 +14,50 @@
 //     overlap, keeping the higher-importance one. Pure function of state —
 //     deterministic, no model call, fully testable.
 //
-// A dedicated-model proposer (a hidden LLM call) is the obvious next alternate
-// the interface supports, but is intentionally NOT shipped here: it is the one
-// tradeoff (non-visible model spend) the roadmap flags as a separate decision.
+// The interface supports a dedicated-model proposer — one that makes its own
+// hidden LLM call to produce deltas directly, instead of delegating to the
+// agent via a steering message. This package does NOT ship one (hidden model
+// spend is a tradeoff the roadmap keeps as a separate decision), but it DOES
+// inject a one-shot `complete` into ProposeInput when a model is available, so a
+// companion package can register one. The closure is built by runRefine from
+// ctx.modelRegistry; telemetry a proposer returns is recorded in the refine
+// audit entry, so the spend stays visible (audited, not hidden).
 //
 // Extension is open: call registerProposer() from your own extension to add a
 // named proposer, then select it via /refine --proposer <name> or config.
 
 import type { Delta, HarnessItem, HarnessState } from "./types.js";
 
+/** Options for the one-shot model completion injected into ProposeInput. */
+export interface CompleteOptions {
+  /** Resolve and use this model id ("provider/id" or a bare id) instead of the
+   *  active session model. Falls back to the active model if unresolvable. */
+  modelId?: string;
+  /** System prompt wrapping the user prompt. */
+  systemPrompt?: string;
+  /** Max output tokens for the completion (maps to the provider maxTokens). */
+  maxOutputTokens?: number;
+}
+
+/** Result of a one-shot model completion. */
+export interface CompleteResult {
+  /** The assistant's text response. */
+  text: string;
+  /** Token usage, when the provider reports it (for the audit trail). */
+  usage?: { input: number; output: number };
+}
+
+/** Telemetry from a dedicated model call, surfaced in the refine audit entry so
+ *  hidden model spend is visible (which model, tokens, latency, ok/error). */
+export interface ModelCallTelemetry {
+  model?: string;
+  inputTokens?: number;
+  outputTokens?: number;
+  latencyMs?: number;
+  ok: boolean;
+  error?: string;
+}
+
 /** Inputs to a proposer. */
 export interface ProposeInput {
   /** Recent trajectory evidence (the same string /refine gathers). */
@@ -32,6 +67,11 @@ export interface ProposeInput {
   state: HarnessState;
   /** Lookback window in turns. */
   lookback: number;
+  /** One-shot model completion, injected by runRefine when a model is available.
+   *  Dedicated-model proposers call this to make a hidden completion; rule-based
+   *  and steering proposers ignore it. Undefined when no model is resolvable, so
+   *  a model proposer can no-op (and record an audited failure) rather than throw. */
+  complete?: (prompt: string, opts?: CompleteOptions) => Promise<CompleteResult>;
 }
 
 /** A single delta plus a human-readable reason for the audit trail. */
@@ -49,6 +89,10 @@ export interface ProposeResult {
    * A proposer MAY return both — deltas are applied first, then steering sent.
    */
   steeringMessage?: string;
+  /** Telemetry from a dedicated model call, recorded in the refine audit entry so
+   *  hidden model spend is visible. Set by dedicated-model proposers; ignored by
+   *  rule-based/steering ones. */
+  modelCall?: ModelCallTelemetry;
 }
 
 /** A strategy for turning evidence + state into (or toward) harness deltas. */

package/src/refine.ts

@@ -18,8 +18,10 @@
 // model spend is a tradeoff the roadmap keeps as a separate decision).
 
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Context, Model, TextContent } from "@earendil-works/pi-ai";
 import { applyDeltas, exportDurable, REFINE_ENTRY, snapshotState } from "./store.js";
 import { getProposer } from "./proposer.js";
+import type { CompleteOptions, CompleteResult } from "./proposer.js";
 
 const DEFAULT_EVIDENCE_BYTES = 16000;
 export const DEFAULT_LOOKBACK_TURNS = 25;
@@ -82,9 +84,17 @@ export async function runRefine(
   ctx.ui.setStatus("harness", `Refining (last ${lookback} turns)… [${proposer.name}]`);
 
   const evidence = gatherEvidence(ctx, lookback);
+  // Inject a one-shot model completion (built from ctx) so dedicated-model
+  // proposers can make a hidden LLM call. Undefined when no model is resolvable.
+  const complete = buildComplete(ctx);
   // Pass a defensive copy: proposers are a public extension point and must not
   // be able to mutate the live store outside applyDeltas (no audit / no rollback).
-  const result = await proposer.propose({ evidence, state: snapshotState(), lookback });
+  const result = await proposer.propose({
+    evidence,
+    state: snapshotState(),
+    lookback,
+    ...(complete ? { complete } : {}),
+  });
   const proposedDeltas = result.deltas ?? [];
 
   let applied = 0;
@@ -110,6 +120,9 @@ export async function runRefine(
     proposer: proposer.name,
     applied,
     rationales: proposedDeltas.map((d) => d.rationale),
+    // Hidden model spend made visible: dedicated-model proposers report what the
+    // call cost (model, tokens, latency, ok/error). Absent for rule-based/steering.
+    ...(result.modelCall ? { modelCall: result.modelCall } : {}),
   });
 
   if (commit) {
@@ -180,3 +193,62 @@ function gatherEvidence(ctx: ExtensionContext, lookback: number): string {
   }
   return lines.join("\n") || "(no recent trajectory evidence found)";
 }
+
+// ---- one-shot model completion injection (for dedicated-model proposers) -------
+//
+// runRefine builds this closure from ctx.modelRegistry + ctx.model and passes it
+// into ProposeInput.complete. A dedicated-model proposer (shipped as a companion
+// package) calls it to produce deltas directly via a hidden completion; the
+// telemetry it returns is recorded in the refine audit entry so the spend stays
+// visible. Rule-based/steering proposers ignore it.
+
+/** Resolve a model id ("provider/id" or a bare id) against the registry, falling
+ *  back to the active session model. Returns undefined if nothing resolves. */
+function resolveModel(ctx: ExtensionContext, modelId?: string): Model<any> | undefined {
+  const registry = ctx.modelRegistry;
+  if (modelId && registry) {
+    const slash = modelId.indexOf("/");
+    if (slash >= 0) {
+      const found = registry.find(modelId.slice(0, slash), modelId.slice(slash + 1));
+      if (found) return found;
+    }
+    const byId =
+      registry.getAvailable().find((m) => m.id === modelId) ??
+      registry.getAll().find((m) => m.id === modelId);
+    if (byId) return byId;
+  }
+  return ctx.model;
+}
+
+/** Build the one-shot completion closure injected into ProposeInput, or undefined
+ *  when no model can be resolved (so a model proposer can no-op gracefully).
+ *  Honors the agent abort signal and a per-call token budget. */
+function buildComplete(
+  ctx: ExtensionContext,
+): ((prompt: string, opts?: CompleteOptions) => Promise<CompleteResult>) | undefined {
+  const registry = ctx.modelRegistry;
+  const active = ctx.model;
+  if (!registry || (!active && registry.getAvailable().length === 0)) return undefined;
+
+  return async (prompt, opts) => {
+    const model = resolveModel(ctx, opts?.modelId);
+    if (!model) throw new Error("no model available for proposer completion");
+    const context: Context = {
+      ...(opts?.systemPrompt !== undefined ? { systemPrompt: opts.systemPrompt } : {}),
+      messages: [{ role: "user", content: prompt, timestamp: Date.now() }],
+    };
+    const assistant = await registry.complete(model, context, {
+      ...(opts?.maxOutputTokens !== undefined ? { maxTokens: opts.maxOutputTokens } : {}),
+      ...(ctx.signal ? { signal: ctx.signal } : {}),
+    });
+    const text = assistant.content
+      .filter((c): c is TextContent => c.type === "text")
+      .map((c) => c.text)
+      .join("");
+    const usage = assistant.usage;
+    return {
+      text,
+      ...(usage ? { usage: { input: usage.input, output: usage.output } } : {}),
+    };
+  };
+}