@oisin-ee/pi-prewalk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Momokaya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# @oisin-ee/pi-prewalk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Prewalk starts with the active planner model. After the planning nudge, a successful `todo` call opens the handoff gate.
+The first subsequent `edit` or `write` result switches the session to the target model, even if that result failed.
+Nested calls through codemode also count. Without a callable `todo` tool, the gate is open.
+
+## Config
+
+Put `prewalk.json` in the pi agent directory:
+
+```json
+{
+  "enabled": true,
+  "target": { "model": "alias/luna", "thinking": "medium" }
+}
+```
+
+A trusted project's `.pi/prewalk.json` replaces matching user keys. Prewalk reads both files again at each input.
+The target needs a provider-qualified model ID and configured credentials. Alias models need the alias extension.
+
+## Controls
+
+Use `/prewalk` to arm from the active model. Use `/prewalk off` to cancel without changing the model or config.
+Use `/prewalk restart` to select the saved default and arm again. Use `/prewalk status` to inspect branch state and config errors.
+
+The startup flags are `--prewalk`, `--no-prewalk`, and `--prewalk-into provider/model`.
+Do not combine `--no-prewalk` with either arming flag.
+Flags affect only the startup session. New sessions use `enabled` from config. Resumed sessions do not arm automatically.
+
+For a Shepherdr child, add `"pi_args": ["--prewalk-into", "alias/luna"]` to its profile.
+To suppress configured prewalk for that child, use `"pi_args": ["--no-prewalk"]`.
+
+## State and context
+
+The active branch stores arm, handoff, and off entries. The extension does not keep a separate in-memory protocol state.
+After a handoff, `/new` restores the planner unless a later model or thinking selection replaced the handoff target.
+
+pi 1.3.0 permits persistent context edits only at actionable boundaries.
+Cancellation writes an off entry immediately. A context handler removes canceled planning steering before the next model request.
+The next turn or settlement boundary records the persistent removal.
+
+## Source
+
+The protocol and prompts adapt [oh-my-pi prewalk](https://github.com/can1357/oh-my-pi/tree/e7fe318/packages/coding-agent/src),
+including `session/prewalk.ts` and `prompts/system/prewalk-{plan,continue,checklist}.md`.
+The original project uses the MIT license. This package keeps the one-shot handoff semantics and adapts them to pi's branch entries.

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@oisin-ee/pi-prewalk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "A one-shot planner-to-executor handoff for pi, with branch-backed Rust rules.",
+  "keywords": [
+    "pi-extension",
+    "pi-package",
+    "prewalk"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oisin-ee/pi-prewalk.git",
+    "directory": "packages/pi-prewalk"
+  },
+  "files": [
+    "src/",
+    "!src/**/*.test.ts",
+    "!src/fixture.ts"
+  ],
+  "type": "module",
+  "devDependencies": {
+    "@earendil-works/pi-ai": "1.3.0",
+    "@earendil-works/pi-coding-agent": "1.3.0",
+    "@earendil-works/pi-tui": "1.3.0",
+    "typebox": "1.3.27"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "image": "https://raw.githubusercontent.com/oisin-ee/pi-prewalk/main/assets/prewalk.png"
+  }
 }

package/src/adapter.ts

@@ -0,0 +1,294 @@
+import type { Action, ConfigReport, Event, Facts, Selection, State } from "./wasm.ts";
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { BoundaryResult, SessionBoundaryDraft } from "@earendil-works/pi-coding-agent";
+import type { Context, Files, Host } from "./ports.ts";
+import { branchRecords, calls } from "./branch.ts";
+import type { CallEvidence } from "./branch.ts";
+import { decide } from "./wasm.ts";
+
+/**
+ * Resolves an exact qualified ID with configured credentials.
+ * @param {string} id Qualified ID.
+ * @param {Context} ctx Context.
+ * @returns {Model<Api> | undefined} Available model.
+ */
+const model = (id: string, ctx: Context): Model<Api> | undefined =>
+    ctx.modelRegistry
+      .getAvailable()
+      .find((candidate) => `${candidate.provider}/${candidate.id}` === id),
+  /**
+   * Records pi's effective thinking after selection.
+   * @param {State} state Proposed state.
+   * @param {Selection | undefined} selected Effective selection.
+   * @returns {State} Effective state.
+   */
+  effectiveState = (state: State, selected: Selection | undefined): State => {
+    if (selected && state.kind === "handoff") {
+      return Object.assign({}, state, { target: selected });
+    }
+    return selected && state.kind === "arm"
+      ? Object.assign({}, state, { planner: selected })
+      : state;
+  },
+  /**
+   * Maps one action to a pi draft.
+   * @param {Action} action Core action.
+   * @param {Selection | undefined} selected Effective selection.
+   * @returns {SessionBoundaryDraft[]} Zero or one draft.
+   */
+  drafts = (action: Action, selected: Selection | undefined): SessionBoundaryDraft[] => {
+    switch (action.kind) {
+      case "store": {
+        return [
+          {
+            customType: `prewalk-${action.state.kind}`,
+            data: effectiveState(action.state, selected),
+            type: "custom",
+          },
+        ];
+      }
+      case "prompt": {
+        return [
+          {
+            content: action.content,
+            customType: action.name,
+            display: false,
+            type: "custom_message",
+          },
+        ];
+      }
+      case "scrub": {
+        return [{ replacement: null, targetId: action.id, type: "context_edit" }];
+      }
+      case "select":
+      case "notify": {
+        return [];
+      }
+      default: {
+        return [];
+      }
+    }
+  },
+  /**
+   * Persists non-boundary entries. Scrubs persist at the next boundary.
+   * @param {Host} pi Host authority.
+   * @param {readonly SessionBoundaryDraft[]} entries Drafts.
+   */
+  persist = (pi: Host, entries: readonly SessionBoundaryDraft[]): void => {
+    for (const entry of entries) {
+      if (entry.type === "custom") {
+        pi.appendEntry(entry.customType, entry.data);
+      } else if (entry.type === "custom_message") {
+        pi.sendMessage(entry);
+      }
+    }
+  };
+
+/** No in-memory arm, gate, handoff, or continuation state. */
+class Adapter {
+  readonly #pi: Host;
+  readonly #files: Files;
+  readonly #notified = new Set<string>();
+
+  /**
+   * @param {Host} pi Session authority.
+   * @param {Files} files File readers.
+   */
+  public constructor(pi: Host, files: Files) {
+    this.#pi = pi;
+    this.#files = files;
+  }
+
+  /**
+   * @param {Event} event Protocol event.
+   * @param {Context} ctx Context.
+   * @returns {Facts} Boundary input.
+   */
+  #facts(event: Event, ctx: Context): Facts {
+    const report = this.#files.config(ctx),
+      into = event.kind === "start" && event.reason === "startup" ? event.flags.into : undefined,
+      target = into ?? report.config.target?.model,
+      todo = this.#pi
+        .getAllTools()
+        .find((tool) => tool.name === "todo" && tool.exposure !== "hidden"),
+      callable =
+        todo &&
+        (todo.exposure === "codemode" ||
+          todo.exposure === "deferred" ||
+          this.#pi.getActiveTools().includes("todo"));
+    return {
+      available: ctx.modelRegistry
+        .getAvailable()
+        .map((candidate) => `${candidate.provider}/${candidate.id}`),
+      branch: branchRecords(ctx.sessionManager.getBranch()),
+      current: ctx.model
+        ? { model: `${ctx.model.provider}/${ctx.model.id}`, thinking: this.#pi.getThinkingLevel() }
+        : undefined,
+      default: this.#default(ctx),
+      event,
+      previous: [],
+      report,
+      target_available: target !== undefined && model(target, ctx) !== undefined,
+      todo: Boolean(callable),
+      todo_owner: todo?.sourceInfo.path ?? "none",
+    };
+  }
+
+  /**
+   * @param {Context} ctx Context.
+   * @returns {Selection | undefined} Usable default.
+   */
+  #default(ctx: Context): Selection | undefined {
+    const settings = this.#pi.getSettings(),
+      id = `${settings.defaultProvider ?? ""}/${settings.defaultModel ?? ""}`;
+    return model(id, ctx)
+      ? { model: id, thinking: settings.defaultThinkingLevel ?? "medium" }
+      : undefined;
+  }
+
+  /**
+   * @param {ConfigReport} report Config report.
+   * @param {Context} ctx Context.
+   */
+  #errors(report: ConfigReport, ctx: Context): void {
+    for (const error of report.errors) {
+      if (!this.#notified.has(error)) {
+        this.#notified.add(error);
+        ctx.ui.notify(error, "warning");
+      }
+    }
+  }
+
+  /**
+   * @param {Event} event Event.
+   * @param {Context} ctx Context.
+   * @param {readonly SessionBoundaryDraft[] | undefined} prior Existing boundary drafts.
+   * @returns {Promise<BoundaryResult>} Boundary result.
+   */
+  public async run(
+    event: Event,
+    ctx: Context,
+    prior?: readonly SessionBoundaryDraft[],
+  ): Promise<BoundaryResult> {
+    const facts = this.#facts(event, ctx);
+    this.#errors(facts.report, ctx);
+    return this.#apply(facts, ctx, prior);
+  }
+
+  /**
+   * Excludes this turn's persisted results from the historical gate evidence.
+   * @param {TurnEndEvent} event Completed turn.
+   * @param {Context} ctx Context.
+   * @returns {Promise<BoundaryResult>} Boundary result.
+   */
+  public async turn(
+    event: Readonly<{
+      toolResults: readonly CallEvidence[];
+      toolResultEntryIds: readonly string[];
+      entries: readonly SessionBoundaryDraft[];
+    }>,
+    ctx: Context,
+  ): Promise<BoundaryResult> {
+    const facts = this.#facts(
+      { calls: event.toolResults.flatMap((result) => calls(result)), kind: "turn" },
+      ctx,
+    );
+    facts.branch = branchRecords(
+      ctx.sessionManager
+        .getBranch()
+        .filter((entry) => !event.toolResultEntryIds.includes(entry.id)),
+    );
+    this.#errors(facts.report, ctx);
+    return this.#apply(facts, ctx, event.entries);
+  }
+
+  /**
+   * @param {string | undefined} path Previous session file.
+   * @param {Context} ctx Fresh context.
+   * @returns {Promise<void>} Completion.
+   */
+  public async newSession(path: string | undefined, ctx: Context): Promise<void> {
+    const facts = this.#facts(
+      {
+        flags: { into: undefined, no_prewalk: false, prewalk: false },
+        kind: "start",
+        reason: "new",
+      },
+      ctx,
+    );
+    this.#errors(facts.report, ctx);
+    try {
+      facts.previous = path === undefined ? [] : branchRecords(this.#files.previous(path));
+    } catch (error) {
+      ctx.ui.notify(
+        `Prewalk: cannot read previous session: ${error instanceof Error ? error.message : String(error)}`,
+        "warning",
+      );
+    }
+    await this.#apply(facts, ctx);
+  }
+
+  /**
+   * @param {Selection} selection Selection.
+   * @param {Context} ctx Context.
+   * @returns {Promise<Selection | undefined>} Effective selection, or failure.
+   */
+  async #select(selection: Selection, ctx: Context): Promise<Selection | null> {
+    const resolved = model(selection.model, ctx);
+    if (!resolved || !(await this.#pi.setModel(resolved))) {
+      ctx.ui.notify(
+        `Prewalk: cannot select ${selection.model}. Active model stays unchanged.`,
+        "warning",
+      );
+      return null;
+    }
+    this.#pi.setThinkingLevel(selection.thinking);
+    return { model: selection.model, thinking: this.#pi.getThinkingLevel() };
+  }
+
+  /**
+   * @param {readonly Action[]} actions Decisions.
+   * @param {Context} ctx Context.
+   */
+  static #notices(actions: readonly Action[], ctx: Context): void {
+    for (const action of actions) {
+      if (action.kind === "notify") {
+        ctx.ui.notify(action.message, "info");
+      }
+    }
+  }
+
+  /**
+   * Maps a protocol result to pi. Core decisions contain at most one selection.
+   * @param {Facts} facts Input.
+   * @param {Context} ctx Context.
+   * @param {readonly SessionBoundaryDraft[] | undefined} prior Existing boundary drafts.
+   * @returns {Promise<BoundaryResult>} Boundary result.
+   */
+  async #apply(
+    facts: Facts,
+    ctx: Context,
+    prior?: readonly SessionBoundaryDraft[],
+  ): Promise<BoundaryResult> {
+    const decision = decide(facts),
+      selection = decision.actions.find((action) => action.kind === "select"),
+      selected = selection ? await this.#select(selection.selection, ctx) : undefined,
+      entries = [
+        ...(prior ?? []),
+        ...decision.actions.flatMap((action) => drafts(action, selected ?? undefined)),
+      ];
+    if (selection && !selected) {
+      if (facts.event.kind === "start" && facts.event.reason === "new") {
+        return this.#apply(Object.assign({}, facts, { previous: [] }), ctx, prior);
+      }
+      return { entries: [...(prior ?? [])] };
+    }
+    Adapter.#notices(decision.actions, ctx);
+    if (prior === undefined) {
+      persist(this.#pi, entries);
+    }
+    return decision.again ? { continue: true, entries } : { entries };
+  }
+}
+
+export { Adapter };

package/src/branch.ts

@@ -0,0 +1,69 @@
+import type { Record as BranchRecord, Call } from "./wasm.ts";
+import type { SessionEntry, SessionMessageEntry } from "@earendil-works/pi-coding-agent";
+import { parse_state } from "./wasm.ts";
+
+/** Only the fields the protocol reads from tool results. */
+interface CallEvidence {
+  readonly toolName: string;
+  readonly isError: boolean;
+  readonly nestedCalls?: {
+    readonly calls: readonly { readonly name: string; readonly status: string }[];
+  };
+}
+
+/**
+ * Extracts call evidence, including calls without transcript entries.
+ * @param {ToolResultMessage} result A completed outer tool result.
+ * @returns {Call[]} Nested calls followed by the outer result.
+ */
+const calls = (result: CallEvidence): Call[] => [
+    ...(result.nestedCalls?.calls.map((call) => ({
+      name: call.name,
+      success: call.status === "ok",
+    })) ?? []),
+    { name: result.toolName, success: !result.isError },
+  ],
+  /**
+   * Translates message evidence.
+   * @param {SessionMessageEntry} entry A transcript entry.
+   * @returns {BranchRecord[]} Relevant messages.
+   */
+  messageRecords = (entry: SessionMessageEntry): BranchRecord[] => {
+    if (entry.message.role === "toolResult") {
+      return [{ calls: calls(entry.message), kind: "calls" }];
+    }
+    return entry.message.role === "user" ? [{ kind: "user" }] : [];
+  },
+  /**
+   * Translates a pi entry. Rust validates protocol payloads.
+   * @param {SessionEntry} entry One branch entry.
+   * @returns {BranchRecord[]} Protocol evidence.
+   */
+  entryRecords = (entry: SessionEntry): BranchRecord[] => {
+    if (
+      entry.type === "custom" &&
+      ["prewalk-arm", "prewalk-handoff", "prewalk-off"].includes(entry.customType)
+    ) {
+      return [{ kind: "state", state: parse_state(entry.data) }];
+    }
+    if (entry.type === "custom_message" && entry.customType.startsWith("prewalk-")) {
+      return [{ id: entry.id, kind: "prompt", name: entry.customType }];
+    }
+    if (entry.type === "context_edit" && entry.replacement === null) {
+      return [{ id: entry.targetId, kind: "scrub" }];
+    }
+    if (entry.type === "model_change" || entry.type === "thinking_level_change") {
+      return [{ kind: "selection" }];
+    }
+    return entry.type === "message" ? messageRecords(entry) : [];
+  },
+  /**
+   * Translates the active branch in transcript order.
+   * @param {readonly SessionEntry[]} entries Current branch, oldest first.
+   * @returns {BranchRecord[]} Protocol evidence.
+   */
+  branchRecords = (entries: readonly SessionEntry[]): BranchRecord[] =>
+    entries.flatMap((entry) => entryRecords(entry));
+
+export { branchRecords, calls };
+export type { CallEvidence };

package/src/config.ts

@@ -0,0 +1,68 @@
+import {
+  CURRENT_SESSION_VERSION,
+  SessionManager,
+  getAgentDir,
+} from "@earendil-works/pi-coding-agent";
+import type { ConfigReport } from "./wasm.ts";
+import type { Context } from "./ports.ts";
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+import { configure } from "./wasm.ts";
+import path from "node:path";
+import { readFileSync } from "node:fs";
+
+/**
+ * Reads optional config, preserving permission and I/O errors.
+ * @param {string} file Config file path.
+ * @returns {string | undefined} Source, or undefined for a missing file.
+ */
+const source = (file: string): string | undefined => {
+    try {
+      return readFileSync(file, "utf8");
+    } catch (error) {
+      if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+        return undefined;
+      }
+      throw error;
+    }
+  },
+  /**
+   * Reads live config. Untrusted project files never reach Rust.
+   * @param {Context} ctx Current context.
+   * @returns {ConfigReport} Validated config and errors.
+   */
+  readConfig = (ctx: Context): ConfigReport => {
+    try {
+      const userPath = path.join(getAgentDir(), "prewalk.json"),
+        projectPath = path.join(ctx.cwd, ".pi", "prewalk.json"),
+        user = source(userPath),
+        project = ctx.isProjectTrusted() ? source(projectPath) : undefined;
+      return configure(user, project);
+    } catch (error) {
+      return {
+        config: { enabled: false, target: undefined },
+        errors: [`prewalk.json: ${error instanceof Error ? error.message : String(error)}`],
+      };
+    }
+  },
+  /**
+   * Opens only current-version sessions, preventing migration writes.
+   * @param {string} file Outgoing session path supplied by pi.
+   * @returns {SessionEntry[]} Previous active branch.
+   */
+  previousBranch = (file: string): SessionEntry[] => {
+    const [line] = readFileSync(file, "utf8").split("\n"),
+      first: unknown = JSON.parse(line ?? "null");
+    if (
+      typeof first !== "object" ||
+      first === null ||
+      !("version" in first) ||
+      first.version !== CURRENT_SESSION_VERSION
+    ) {
+      throw new Error(
+        "Previous session is not a current-version pi session. Refusing a migration during restore.",
+      );
+    }
+    return SessionManager.open(file).getBranch();
+  };
+
+export { previousBranch, readConfig };