@tduyng/pi-prewalk 0.0.0-stage → 0.0.2

package/src/logic.ts

@@ -0,0 +1,384 @@
+import { tmpdir } from 'node:os'
+import { resolve, sep } from 'node:path'
+import type { PrewalkMode } from './config.js'
+
+export const STATE_TYPE = 'prewalk'
+
+export const SKILL_BLOCK_PREFIX = '<skill '
+
+export const PLAN_TOOL_NAME = 'prewalk_plan'
+
+export const MAX_PLAN_STEPS = 20
+
+export const MAX_PLAN_FACTS = 100
+
+export const PLANNING_BRIEF = `You are the planner for this task. A cheaper, weaker model implements your plan from this same context. It will not re-derive anything and it cannot recover from a vague step.
+1. Explore the relevant code until you understand the change fully. Prefer rg/fd with narrow scope over broad reads. Use web_search for facts the codebase does not hold, never to look up the fix, and record what you learn in the plan's facts.
+2. Call ${PLAN_TOOL_NAME} once, carrying everything the implementer would otherwise have to work out again: the facts you established (with file:line), and for each step its file, the exact anchor text to edit at, what changes, and the command that verifies it. If a step needs a judgement call the implementer cannot make, make it now or split the step.
+3. Then land the first step's edit yourself and run its verification. Work autonomously until the task is complete. Do not stop to ask for plan approval.
+4. A task longer than ${MAX_PLAN_STEPS} steps plans its first phase only. When the executor finishes, the task comes back to you for review in this same context, and you plan the next phase then.`
+
+export const EDIT_TOOLS = new Set(['edit', 'write', 'multiedit', 'notebookedit'])
+
+export const READ_ONLY_TOOLS = new Set(['read', 'grep', 'find', 'ls', 'glob'])
+
+export type PlanStep = {
+    file: string
+    change: string
+    anchor?: string
+    verify?: string
+}
+
+export type PrewalkPlan = {
+    summary: string
+    facts: string[]
+    steps: PlanStep[]
+    check: string
+    outOfScope: string[]
+}
+
+export type ModelRef = { provider: string; id: string }
+
+const MIN_SUFFIX = 3
+
+export function makeSpecPredicate(models: readonly ModelRef[]): (token: string) => boolean {
+    return (token) => {
+        const lower = token.toLowerCase()
+        if (models.some((m) => modelRef(m).toLowerCase() === lower || m.id.toLowerCase() === lower)) {
+            return true
+        }
+        if (lower.length < MIN_SUFFIX) return false
+        return models.filter((m) => m.id.toLowerCase().endsWith(lower)).length === 1
+    }
+}
+
+export type PrewalkState = {
+    executor: string
+    planner: string | null
+    swapped: boolean
+    forced: ForceRoute | null
+    inFlight: boolean
+    plan: PrewalkPlan | null
+    planDemanded: boolean
+    stepIndex: number
+    /** Failed tool results in a row on the step in flight, which is what a wall looks like. */
+    failures: number
+    /** Upgrades spent on this task, so a wall cannot ping-pong between the models. */
+    escalations: number
+    /** The last failure, trimmed, which is what the planner reads when it takes the task back. */
+    wall: string | null
+    reviewing: boolean
+}
+
+export const MAX_WALL_CHARS = 400
+
+export type EscalationBar = { failures: number; upgrades: number }
+
+export const ESCALATION_BAR: EscalationBar = { failures: 3, upgrades: 2 }
+
+export const PLANNER_GRACE_CALLS = 3
+
+/** Below this a prompt is a redirect rather than a task: `go on` stays, `fix tests` routes. */
+export const MIN_PROMPT_CHARS = 8
+
+export function shouldAsk(text: string): boolean {
+    return text.trim().length >= MIN_PROMPT_CHARS
+}
+
+export type PrewalkRole = 'planner' | 'executor'
+
+export type ForceRoute = 'plan' | 'run'
+
+export type ParsedPrewalkArgs =
+    | { kind: 'bare' }
+    | { kind: 'status' }
+    | { kind: 'stop' }
+    | { kind: 'models' }
+    | { kind: 'mode'; mode: PrewalkMode }
+    | { kind: 'role'; role: PrewalkRole; chain: string[] }
+    | { kind: 'force'; route: ForceRoute; task: string }
+    | { kind: 'start'; planner: string | null; executor: string | null; task: string }
+
+const STOP_WORDS = new Set(['stop', 'cancel', 'clear', 'off', 'done'])
+const STATUS_WORDS = new Set(['status', 'state', '?'])
+const MODEL_LIST_WORDS = new Set(['models', 'list', 'ls'])
+const MODE_WORDS = new Set(['mode', 'routing'])
+const ROLE_WORDS = new Set<string>(['planner', 'executor'])
+const ARM_WORDS = new Set(['on', 'auto', 'arm'])
+const AUTO_WORDS = new Set(['auto', 'on', 'routed'])
+const PLAN_MODE_WORDS = new Set(['plan', 'classic'])
+const OFF_MODE_WORDS = new Set(['off', 'none', 'cheap'])
+const ROUTE_WORDS = new Map<string, ForceRoute>([
+    ['plan', 'plan'],
+    ['run', 'run'],
+    ['cheap', 'run']
+])
+
+function parseMode(text: string): PrewalkMode | null {
+    const word = splitFirstToken(text.trim().toLowerCase())[0]
+    if (OFF_MODE_WORDS.has(word)) return 'off'
+    if (AUTO_WORDS.has(word) || PLAN_MODE_WORDS.has(word)) return 'plan'
+    return null
+}
+
+function leadingModelSpecs(text: string, isModelSpec: (token: string) => boolean): string[] {
+    const chain: string[] = []
+    let rest = text
+    while (rest !== '') {
+        const [token, after] = splitFirstToken(rest)
+        if (!isModelSpec(token)) break
+        chain.push(token)
+        rest = after
+    }
+    return chain
+}
+
+function splitFirstToken(text: string): [string, string] {
+    const space = text.search(/\s/)
+    if (space === -1) return [text, '']
+    return [text.slice(0, space), text.slice(space).trim()]
+}
+
+export function parseArgs(args: string, isModelSpec: (token: string) => boolean): ParsedPrewalkArgs {
+    const trimmed = args.trim()
+    if (trimmed === '') return { kind: 'bare' }
+    const lower = trimmed.toLowerCase()
+    if (STOP_WORDS.has(lower)) return { kind: 'stop' }
+    if (STATUS_WORDS.has(lower)) return { kind: 'status' }
+    let rest = trimmed
+    const [head, afterHead] = splitFirstToken(trimmed)
+    if (ARM_WORDS.has(head.toLowerCase())) rest = afterHead
+    if (rest === '') return { kind: 'start', planner: null, executor: null, task: '' }
+    const [first, afterFirst] = splitFirstToken(rest)
+    if (!isModelSpec(first)) {
+        const word = first.toLowerCase()
+        if (MODEL_LIST_WORDS.has(word)) return { kind: 'models' }
+        const forced = ROUTE_WORDS.get(word)
+        if (forced !== undefined) return { kind: 'force', route: forced, task: afterFirst }
+        if (ROLE_WORDS.has(word)) {
+            const role: PrewalkRole = word === 'planner' ? 'planner' : 'executor'
+            return { kind: 'role', role, chain: leadingModelSpecs(afterFirst, isModelSpec) }
+        }
+        if (MODE_WORDS.has(word)) {
+            const mode = parseMode(afterFirst)
+            return mode === null ? { kind: 'status' } : { kind: 'mode', mode }
+        }
+        return { kind: 'start', planner: null, executor: null, task: rest }
+    }
+    const [second, afterSecond] = splitFirstToken(afterFirst)
+    if (second !== '' && isModelSpec(second)) {
+        return { kind: 'start', planner: first, executor: second, task: afterSecond }
+    }
+    return { kind: 'start', planner: null, executor: first, task: afterFirst }
+}
+
+export type UserTextMessage = {
+    role: string
+    toolName?: string
+    content?: string | Array<{ type: string; text?: string }>
+}
+
+export function contextForModel<T extends UserTextMessage>(state: PrewalkState, messages: T[]): T[] {
+    if (state.plan !== null) replaceLatestPlanResult(messages, renderHandoff(state.plan))
+    return messages
+}
+
+export function wallBrief(plan: PrewalkPlan, stepIndex: number, failures: number): string {
+    const total = plan.steps.length
+    const step = Math.min(stepIndex + 1, total)
+    return `${NUDGE_PREFIX} ${failures} failures on step ${step}/${total}. The planner model takes this task back from the next request until its next edit: find the cause and fix it, or call ${PLAN_TOOL_NAME} with the steps that are left.`
+}
+
+export function reviewPrompt(plan: PrewalkPlan, stepIndex: number): string {
+    const total = plan.steps.length
+    return [
+        `${NUDGE_PREFIX} Review. The executor stopped with ${Math.min(stepIndex, total)}/${total} plan steps matched. Its edits are in the transcript above, so do not re-read files you can see there.`,
+        `1. Run \`git diff --stat\` and the final check \`${plan.check}\`.`,
+        '2. Check the work against the goal and fix any defect yourself.',
+        `3. If the goal needs work the plan did not cover, call ${PLAN_TOOL_NAME} with the remaining steps and land the first one.`,
+        '4. If the work is correct and complete, reply in one line.'
+    ].join('\n')
+}
+
+export function isScratchPath(path: string, cwd: string): boolean {
+    if (path === '') return false
+    const full = resolve(cwd, path)
+    const under = (root: string) => full === root || full.startsWith(root + sep)
+    return under(resolve(tmpdir())) && !under(resolve(cwd))
+}
+
+const HANDOFF_RULES = [
+    "Work the steps in order: make the edit, run that step's verify, then move to the next.",
+    'Read a file only to get the exact text you are about to edit, or when an anchor does not match. Do not re-explore; the findings above already settled what the code does.',
+    'Change nothing the steps do not name. No renames, no refactors, no extra error handling, no new files.',
+    'If a step keeps failing, report the exact error rather than switching to a different approach. Repeated failures on one step hand the task back to the planner.',
+    'When every step is done, run the final check and report what it printed.'
+]
+
+export function renderHandoff(plan: PrewalkPlan): string {
+    const lines = [
+        '[prewalk plan] The exploration above settled this plan. It is authoritative: follow it, do not redesign it.',
+        '',
+        `Goal: ${plan.summary}`
+    ]
+    if (plan.facts.length > 0) {
+        lines.push('', 'Established by the exploration (do not re-derive):')
+        for (const fact of plan.facts) lines.push(`- ${fact}`)
+    }
+    lines.push('', 'Steps, in order:')
+    plan.steps.forEach((step, i) => {
+        lines.push(`${i + 1}. ${step.file}: ${step.change}`)
+        if (step.anchor) lines.push(`   anchor: ${step.anchor}`)
+        if (step.verify) lines.push(`   verify: ${step.verify}`)
+    })
+    if (plan.outOfScope.length > 0) {
+        lines.push('', `Out of scope, do not touch: ${plan.outOfScope.join('; ')}`)
+    }
+    lines.push('', `Final check: ${plan.check}`, '', 'How to work this plan:')
+    for (const rule of HANDOFF_RULES) lines.push(`- ${rule}`)
+    return lines.join('\n')
+}
+
+function replaceLatestPlanResult(messages: readonly UserTextMessage[], text: string): void {
+    const latest = messages.findLast((m) => m.toolName === PLAN_TOOL_NAME)
+    if (latest) latest.content = Array.isArray(latest.content) ? [{ type: 'text', text }] : text
+}
+
+export type SwapDecision = 'ignore' | 'demand-plan' | 'swap'
+
+export function swapDecision(
+    state: PrewalkState,
+    toolName: string,
+    inert = false,
+    demandedThisTurn = false
+): SwapDecision {
+    if (state.swapped || state.reviewing || inert) return 'ignore'
+    const name = toolName.toLowerCase()
+    if (!EDIT_TOOLS.has(name) && name !== 'bash') return 'ignore'
+    if (state.plan === null && (!state.planDemanded || demandedThisTurn)) return 'demand-plan'
+    return 'swap'
+}
+
+export const PLAN_DEMAND_REASON = `Before this edit, call ${PLAN_TOOL_NAME} once. A cheaper model takes over the moment the plan lands and implements it without re-reading what you read, so the plan carries what you know: the findings it cannot re-derive (with file:line), and for each step its file, the exact anchor text, the change, and the command that verifies it. Then repeat this edit.`
+
+function samePath(stepFile: string, editedPath: string): boolean {
+    const a = stepFile.replace(/\\/g, '/').replace(/^\.\//, '')
+    const b = editedPath.replace(/\\/g, '/')
+    return a === b || b.endsWith(`/${a}`) || a.endsWith(`/${b}`)
+}
+
+export function planProgress(plan: PrewalkPlan, stepIndex: number, matched: number) {
+    const total = plan.steps.length
+    const index = matched === -1 ? stepIndex : matched + 1
+    const next = plan.steps[index]
+    if (!next) {
+        return {
+            index,
+            footer: `[prewalk] ${total}/${total} steps done. Run the final check (${plan.check}) and report what it prints.`
+        }
+    }
+    const head =
+        matched === -1
+            ? `[prewalk] still on step ${stepIndex + 1}/${total}:`
+            : `[prewalk] step ${matched + 1}/${total} done. Next, step ${index + 1}/${total}:`
+    const parts = [`${head} ${next.file}: ${next.change}`]
+    if (next.anchor) parts.push(`anchor: ${next.anchor}`)
+    if (next.verify) parts.push(`verify: ${next.verify}`)
+    return { index, footer: parts.join('\n') }
+}
+
+export function stepForPath(plan: PrewalkPlan, stepIndex: number, path: string): number {
+    for (let i = stepIndex; i < plan.steps.length; i++) {
+        const step = plan.steps[i]
+        if (step && samePath(step.file, path)) return i
+    }
+    return -1
+}
+
+const COMMAND_TOKEN = /[^\s'"`;|&<>()]+/g
+
+export function stepForCommand(plan: PrewalkPlan, stepIndex: number, command: string): number {
+    const tokens: string[] = command.match(COMMAND_TOKEN) ?? []
+    for (const token of tokens) {
+        const full = stepForPath(plan, stepIndex, token)
+        if (full !== -1) return full
+    }
+    for (let i = stepIndex; i < plan.steps.length; i++) {
+        const step = plan.steps[i]
+        if (!step) continue
+        const base = step.file.replace(/\\/g, '/').split('/').pop() ?? ''
+        if (base !== '' && tokens.includes(base)) return i
+    }
+    return -1
+}
+
+export const NUDGE_PREFIX = '[prewalk]'
+
+export function continuationNudge(plan: PrewalkPlan, stepIndex: number): string {
+    const total = plan.steps.length
+    const next = plan.steps[stepIndex]
+    if (!next) {
+        return `${NUDGE_PREFIX} All ${total} steps done. Run the final check (\`${plan.check}\`) and report what it prints.`
+    }
+    const verify = next.verify ? ` Run \`${next.verify}\` to verify.` : ''
+    return `${NUDGE_PREFIX} The plan is not finished (${stepIndex}/${total} steps done). Continue with step ${stepIndex + 1}/${total}: ${next.file}: ${next.change}.${verify}`
+}
+
+export function modelRef(model: ModelRef): string {
+    return `${model.provider}/${model.id}`
+}
+
+export function resolveModelSpec<T extends ModelRef>(
+    models: readonly T[],
+    spec: string
+): { model: T } | { error: string } {
+    const lower = spec.toLowerCase()
+    const exact = models.filter((m) => modelRef(m).toLowerCase() === lower || m.id.toLowerCase() === lower)
+    if (exact.length === 1 && exact[0]) return { model: exact[0] }
+    if (exact.length > 1) return { error: ambiguous(exact, spec) }
+    const suffix = models.filter((m) => m.id.toLowerCase().endsWith(lower))
+    if (suffix.length === 1 && suffix[0]) return { model: suffix[0] }
+    if (suffix.length > 1) return { error: ambiguous(suffix, spec) }
+    return { error: `no model matching "${spec}"` }
+}
+
+function ambiguous(matches: readonly ModelRef[], spec: string): string {
+    const providers = [...new Set(matches.map((m) => m.provider))].join(', ')
+    return `"${spec}" matches ${matches.length} models (${providers}). Use provider/id.`
+}
+
+export function shortName(ref: string): string {
+    const slash = ref.indexOf('/')
+    return slash === -1 ? ref : ref.slice(slash + 1)
+}
+
+function badgeName(ref: string): string {
+    const slash = ref.lastIndexOf('/')
+    return slash === -1 ? ref : ref.slice(slash + 1)
+}
+
+export function statusBadge(state: PrewalkState): string {
+    const pair = `${badgeName(state.planner ?? '?')}->${badgeName(state.executor)}`
+    if (!state.inFlight && state.plan === null) return `prewalk route ${pair}`
+    if (state.plan === null) return `prewalk ${state.swapped ? 'run' : 'plan'} ${pair}`
+    const total = state.plan.steps.length
+    if (state.reviewing) return `prewalk review ${state.stepIndex}/${total}`
+    if (!state.swapped) return `prewalk replan ${state.stepIndex}/${total}`
+    return state.stepIndex >= total ? `prewalk done ${total}/${total}` : `prewalk exec ${state.stepIndex}/${total}`
+}
+
+export function statusLabel(state: PrewalkState): string {
+    const planner = state.planner ? shortName(state.planner) : 'the current model'
+    const executor = shortName(state.executor)
+    if (state.plan === null) {
+        if (!state.inFlight) return `Prewalk routing between ${planner} and ${executor}, waiting for a task`
+        return state.swapped
+            ? `Prewalk running this task on ${executor}, no plan written`
+            : `Prewalk planning on ${planner}, swap to ${executor} on first edit`
+    }
+    const total = state.plan.steps.length
+    return state.stepIndex >= total
+        ? `Prewalk done, ${total}/${total} steps, on ${executor}`
+        : `Prewalk ${state.stepIndex}/${total} on ${executor}`
+}
+

package/src/outcomes.ts

@@ -0,0 +1,127 @@
+import type { SessionEntry } from '@earendil-works/pi-coding-agent'
+import { Validator } from 'ata-validator'
+import { t } from 'ata-validator/t'
+
+import { PLAN_TOOL_NAME, STATE_TYPE } from './logic.js'
+
+export type RouteName = 'plan' | 'run'
+
+export interface RouteRecord {
+    route: RouteName
+    /** True when a person chose the route, which makes it a control rather than evidence. */
+    forced: boolean
+    turns: number
+    cost: number
+    edits: number
+    /** The plan's own `check` ran in a shell call, which only a planned task can have. */
+    checked: boolean
+    models: string[]
+}
+
+const BashCall = t.object({ command: t.string() })
+const isBashCall = new Validator(BashCall).isValidObject
+
+const StoredPlan = t.object({ check: t.string() })
+
+const StoredState = t.object({
+    forced: t.optional(t.union([t.literal('plan'), t.literal('run')])),
+    plan: t.optional(StoredPlan)
+})
+const isStoredState = new Validator(StoredState).isValidObject
+
+const EditTools = new Set(['edit', 'write', 'multiedit', 'notebookedit'])
+
+type Span = RouteRecord & { check: string | null }
+
+function openSpan(route: RouteName | null, forced: boolean): Span {
+    return {
+        route: route ?? 'run',
+        forced,
+        turns: 0,
+        cost: 0,
+        edits: 0,
+        checked: false,
+        models: [],
+        check: null
+    }
+}
+
+/**
+ * Every task prewalk routed, read back off the session transcript.
+ *
+ * A task is the span from one user prompt to the next. The route comes from the
+ * state entry in force when the prompt landed.
+ */
+export function routesOf(entries: readonly SessionEntry[]): RouteRecord[] {
+    const records: RouteRecord[] = []
+    let armed = false
+    let byHand: RouteName | null = null
+    let span: Span | null = null
+
+    const close = (): void => {
+        if (span === null) return
+        const { check: _check, ...record } = span
+        records.push(record)
+        span = null
+    }
+
+    for (const entry of entries) {
+        if (entry.type === 'custom' && entry.customType === STATE_TYPE && isStoredState(entry.data)) {
+            armed = true
+            if (entry.data.forced !== undefined) byHand = entry.data.forced
+            if (span !== null && entry.data.plan !== undefined) span.check = entry.data.plan.check
+            continue
+        }
+        if (entry.type !== 'message') continue
+        if (entry.message.role === 'user') {
+            close()
+            span = armed ? openSpan(byHand, byHand !== null) : null
+            byHand = null
+            continue
+        }
+        if (entry.message.role !== 'assistant' || span === null) continue
+
+        const message = entry.message
+        span.turns += 1
+        span.cost += message.usage.cost.total
+        if (span.models.at(-1) !== message.model) span.models.push(message.model)
+        for (const block of message.content) {
+            if (block.type !== 'toolCall') continue
+            if (EditTools.has(block.name)) span.edits += 1
+            if (block.name === PLAN_TOOL_NAME) span.route = 'plan'
+            if (block.name !== 'bash' || span.check === null) continue
+            if (isBashCall(block.arguments) && block.arguments.command.includes(span.check)) {
+                span.checked = true
+            }
+        }
+    }
+    close()
+    return records
+}
+
+export interface RouteSummary {
+    route: RouteName
+    tasks: number
+    byHand: number
+    edits: number
+    checked: number
+    totalCost: number
+    medianCost: number
+}
+
+export function summarizeRoutes(records: readonly RouteRecord[]): RouteSummary[] {
+    const routes: RouteName[] = ['plan', 'run']
+    return routes.map((route) => {
+        const forRoute = records.filter((record) => record.route === route)
+        const costs = forRoute.map((record) => record.cost).toSorted((a, b) => a - b)
+        return {
+            route,
+            tasks: forRoute.length,
+            byHand: forRoute.filter((record) => record.forced).length,
+            edits: forRoute.reduce((sum, record) => sum + record.edits, 0),
+            checked: forRoute.filter((record) => record.checked).length,
+            totalCost: forRoute.reduce((sum, record) => sum + record.cost, 0),
+            medianCost: costs.length === 0 ? 0 : (costs[Math.floor(costs.length / 2)] ?? 0)
+        }
+    })
+}