@xingular/harness 1.3.1-unstable.9 → 1.4.0-unstable

package/dist/sdk/terminal/piExtension.js

@@ -14,6 +14,8 @@ import { askUserTool } from "../tools/askUser.js";
 import { TODO_WRITE, todoTool } from "../tools/todo.js";
 import { createStopGateState, handoffFields, sessionCheckModel, stopCheckpointReason, stopGate, stopGateNotice, stopOutcome, stopSummary, STOP_GATE_EXTENSION } from "../sessions/stopGate.js";
 import { launchSwitchOff } from "../sessions/completionCheck.js";
+import { GOAL_STATE_ENTRY, GOAL_TOOLS, goalTools } from "../sessions/goal.js";
+import { GOAL_EXTENSION, goalLoop, goalNotice } from "../sessions/goalLoop.js";
 import { createSliceState, DEFAULT_SLICE_POLICY, parseWorkSlice, sliceContinuation, workSliceGuard } from "../sessions/workSlice.js";
 import { DEFAULT_COMMAND_TIMEOUT_SECONDS, withCommandBudget } from "../core/commandBudget.js";
 import { SESSION_NAME, deriveSessionName, sessionNameTool } from "../tools/sessionName.js";
@@ -50,7 +52,7 @@ async function withParentCancellation(signal, work) {
         signal?.removeEventListener('abort', stop);
     }
 }
-export default async function (pi, planRun, getSession) {
+export default async function (pi, planRun, getSession, goal) {
     await terminalCall('startup', { phase: 'Pi extension loaded' });
     let context = null;
     let nativeSubagents = false;
@@ -190,8 +192,8 @@ export default async function (pi, planRun, getSession) {
     // `XINGULAR_WORK_SLICE=off` at launch leaves terminal replies unbounded, as before PROP-0041.
     // One stop-gate state per terminal session; each reply resets it.
     const gateState = createStopGateState();
-    // A completion check's model request counts with the reply's usage, like any other request.
-    gateState.recordUsage = (raw) => {
+    // A goal-claim check's model request counts with the reply's usage, like any other request.
+    const recordCheckUsage = (raw) => {
         const message = raw;
         const reported = message.usage;
         if (!reported)
@@ -488,20 +490,72 @@ export default async function (pi, planRun, getSession) {
             continue: true
         };
     });
-    // The stop gate (ADR-0069, ADR-0071), after subagent delivery and plan repair so it sees their
-    // continuations: a terminal reply that ends with open todo items, or that the completion check finds
-    // unfinished, is sent back up to its cap. Plan replies are not gated.
+    // The stop gate (ADR-0069), after subagent delivery and plan repair so it sees their
+    // continuations: a terminal reply that ends with open todo items is sent back up to its cap.
+    // Plan replies are not gated.
     if (!launchSwitchOff('XINGULAR_STOP_GATE'))
         stopGate({
             state: gateState,
             active: () => !planRun?.active,
             sliceEnded: () => sliceState.endedBy !== null,
             failed: () => Boolean(failure),
-            check: launchSwitchOff('XINGULAR_COMPLETION_CHECK') ? null : sessionCheckModel,
             onEvent: (event) => {
                 void terminalCall('notice', { kind: 'notify', level: 'info', extension: STOP_GATE_EXTENSION, text: stopGateNotice(event) }).catch(() => undefined);
             }
         })(pi);
+    // A /goal (ADR-0072): while one is active, a reply that would end continues in place. After the
+    // stop gate, so open todo items are nudged first; its claim check is the only completion check.
+    if (goal) {
+        for (const spec of goalTools(() => goal))
+            pi.registerTool({
+                name: spec.name,
+                label: spec.label,
+                description: spec.description,
+                parameters: spec.parameters(Type),
+                async execute(_id, input) {
+                    const result = await spec.execute(input);
+                    return { content: [{ type: 'text', text: typeof result === 'string' ? result : result.text }], details: undefined };
+                }
+            });
+        // The goal's tools are offered to the model only while a goal exists.
+        const syncGoalTools = (state) => {
+            const active = pi.getActiveTools();
+            const wanted = state !== null && state.status !== 'complete';
+            const has = GOAL_TOOLS.some((name) => active.includes(name));
+            if (wanted && !GOAL_TOOLS.every((name) => active.includes(name)))
+                pi.setActiveTools([...active, ...GOAL_TOOLS.filter((name) => !active.includes(name))]);
+            else if (!wanted && has)
+                pi.setActiveTools(active.filter((name) => !GOAL_TOOLS.includes(name)));
+        };
+        const unsubscribe = goal.subscribe((state) => {
+            try {
+                pi.appendEntry(GOAL_STATE_ENTRY, { goal: state });
+                syncGoalTools(state);
+            }
+            catch {
+                // The session is closing; the next one restores from its own branch.
+            }
+        });
+        pi.on('session_shutdown', () => { unsubscribe(); });
+        pi.on('session_start', (_event, ctx) => {
+            // A goal is restored from the branch, and waits for the person: nothing resumes by itself.
+            const entries = (ctx.sessionManager.getBranch?.() ?? []);
+            const saved = [...entries].reverse().find((entry) => entry.type === 'custom' && entry.customType === GOAL_STATE_ENTRY)?.data?.goal ?? null;
+            goal.restore(saved && (saved.status === 'active') ? { ...saved, status: 'paused', claimed: false } : saved);
+            syncGoalTools(goal.get());
+        });
+        goalLoop({
+            controller: goal,
+            check: launchSwitchOff('XINGULAR_COMPLETION_CHECK') ? null : sessionCheckModel,
+            active: () => !planRun?.active,
+            sliceEnded: () => sliceState.endedBy !== null,
+            failed: () => Boolean(failure),
+            recordUsage: recordCheckUsage,
+            onEvent: (event) => {
+                void terminalCall('notice', { kind: 'notify', level: 'info', extension: GOAL_EXTENSION, text: goalNotice(event) }).catch(() => undefined);
+            }
+        })(pi);
+    }
     // After the stop gate, which stays silent at a slice boundary: a reply that did work and reached
     // its budget continues as the next slice of the same run (ADR-0070).
     if (slicePolicy.enabled)
@@ -510,11 +564,12 @@ export default async function (pi, planRun, getSession) {
             state: sliceState,
             active: () => !planRun?.active,
             failed: () => Boolean(failure),
-            blocked: () => gateState.verdict?.verdict === 'needs_person',
+            blocked: () => goal?.get()?.status === 'blocked',
+            goalActive: () => goal?.active() === true,
             todo: () => gateState.todo,
-            next: () => handoffFields(gateState).next,
+            next: () => handoffFields(gateState, goal?.get() ?? null).next,
             onContinue: (ended) => {
-                void terminalCall('checkpoint', { summary: `Work slice ${ended.slice} reached its limit after ${ended.steps} steps; the reply continues.`, ...handoffFields(gateState), files: [], checks: [], decisions: [], slice: ended.slice, reason: 'budget' }).catch(() => undefined);
+                void terminalCall('checkpoint', { summary: `Work slice ${ended.slice} reached its limit after ${ended.steps} steps; the reply continues.`, ...handoffFields(gateState, goal?.get() ?? null), files: [], checks: [], decisions: [], slice: ended.slice, reason: 'budget' }).catch(() => undefined);
                 void terminalCall('notice', { kind: 'notify', level: 'info', extension: STOP_GATE_EXTENSION, text: `Work slice ${ended.slice} reached ${ended.limit ?? 'its limit'}; continuing with slice ${ended.slice + 1} of up to ${slicePolicy.maxSlices}.` }).catch(() => undefined);
             }
         })(pi);
@@ -725,13 +780,13 @@ export default async function (pi, planRun, getSession) {
         // A reply that ended with open todo items is not completed either (ADR-0069): it stopped for the
         // person, or the stop gate's nudges ran out. The harness writes its checkpoint from the todo list.
         const aborted = event.aborted || messageAborted;
-        const stop = !sliceState.endedBy && !failure && !aborted && !planRun?.active ? stopOutcome(gateState) : null;
+        const stop = !sliceState.endedBy && !failure && !aborted && !planRun?.active ? stopOutcome(gateState, goal?.get() ?? null) : null;
         if (stop) {
-            await terminalCall('checkpoint', { summary: stopSummary(stop), ...handoffFields(gateState), files: [], checks: [], decisions: [], slice: sliceState.slice, reason: stopCheckpointReason(stop) }).catch(() => undefined);
+            await terminalCall('checkpoint', { summary: stopSummary(stop), ...handoffFields(gateState, goal?.get() ?? null), files: [], checks: [], decisions: [], slice: sliceState.slice, reason: stopCheckpointReason(stop) }).catch(() => undefined);
         }
         else if (sliceState.endedBy && !failure && !aborted) {
             // The guard ended the reply and promised the model the harness would keep its state.
-            await terminalCall('checkpoint', { summary: `The reply stopped after ${sliceState.steps} steps at its work-slice boundary.`, ...handoffFields(gateState), files: [], checks: [], decisions: [], slice: sliceState.slice, reason: sliceState.endedBy }).catch(() => undefined);
+            await terminalCall('checkpoint', { summary: `The reply stopped after ${sliceState.steps} steps at its work-slice boundary.`, ...handoffFields(gateState, goal?.get() ?? null), files: [], checks: [], decisions: [], slice: sliceState.slice, reason: sliceState.endedBy }).catch(() => undefined);
         }
         const reason = sliceState.endedBy ? 'slice_complete' : stop?.code;
         const code = sliceState.endedBy === 'compaction-thrash' ? 'compaction_thrash' : sliceState.endedBy === 'budget' ? 'slice_budget' : stop?.code;

package/dist/sdk/terminal/terminals.js

@@ -28,6 +28,7 @@ import { isActiveStatus } from "../sessions/contracts.js";
 import { findRun, listRuns, loadRun, readEvents, recordedSubagents, saveRun, updateRun } from "../sessions/runStore.js";
 import { combineWorkspaceScope, inspectRunWorkspaceWrite } from "../sessions/workspaceBoundary.js";
 import { TODO_WRITE } from "../tools/todo.js";
+import { GOAL_TOOLS } from "../sessions/goal.js";
 import { DEFAULT_TOOL_NAMES } from "../tools/definitions.js";
 import { harnessTools } from "../tools/harnessTools.js";
 import { HARNESS_PLUGINS } from "../plugins/builtin.js";
@@ -880,7 +881,7 @@ export class Terminals {
         }
         if (inspection.outside)
             return { allowed: false, requiresApproval: true, rememberable: false, standing: 'switch', reason: inspection.reason, workspaceRoot };
-        if (name === SESSION_NAME || name === TODO_WRITE || name === SPAWN_SUBAGENT || name === WAIT_SUBAGENTS || READ_ONLY_TOOLS.has(name) || this.worldReadOnly.has(name) || this.options.apps.toolNames.includes(name) || ['bash', 'edit', 'write'].includes(name)) {
+        if (name === SESSION_NAME || name === TODO_WRITE || GOAL_TOOLS.includes(name) || name === SPAWN_SUBAGENT || name === WAIT_SUBAGENTS || READ_ONLY_TOOLS.has(name) || this.worldReadOnly.has(name) || this.options.apps.toolNames.includes(name) || ['bash', 'edit', 'write'].includes(name)) {
             return { allowed: true, workspaceRoot };
         }
         return { allowed: false, requiresApproval: true, rememberable: true, reason: 'This native action requires approval.', workspaceRoot };

package/dist/sdk/terminal/tui/commands.d.ts

@@ -25,6 +25,8 @@ export interface TerminalCommandHost {
     todo(): Promise<readonly TodoEntry[]>;
     showTodo(items: readonly TodoEntry[]): void;
     plan(brief: string): void;
+    /** Runs `/goal` and returns the text to show (ADR-0072). */
+    goal(argument: string): Promise<string>;
     /** Asks a side question in its own tool-free session; empty text dismisses the one showing. */
     btw(question: string): Promise<void>;
     shutdown(): void;

package/dist/sdk/terminal/tui/commands.js

@@ -227,6 +227,9 @@ export function createTerminalCommands(host) {
                     host.plan(argument);
                     break;
                 }
+                case 'goal':
+                    host.ui.notify(await host.goal(argument), 'info');
+                    break;
                 case 'quit':
                     host.shutdown();
                     break;

package/dist/sdk/terminal/tui/goalCommand.d.ts

@@ -0,0 +1,19 @@
+import { GOAL_CUSTOM_TYPE, type GoalController } from "../../sessions/goal.js";
+export interface GoalCommandDeps {
+    controller: GoalController;
+    /** True when no reply is running. */
+    idle(): boolean;
+    /** Sends a hidden message and starts a reply with it. */
+    start(content: string): Promise<void>;
+    /** Sends a hidden message into the running reply. */
+    steer(content: string): Promise<void>;
+    /** Records a hidden message without starting a reply. */
+    note(content: string): Promise<void>;
+    /** Stops the running reply. */
+    interrupt(): Promise<void>;
+    confirm(title: string, message: string): Promise<boolean>;
+    input(title: string, value: string): Promise<string | undefined>;
+}
+export { GOAL_CUSTOM_TYPE };
+/** Runs one `/goal` and returns the text to show the person. */
+export declare function runGoalCommand(argument: string, deps: GoalCommandDeps): Promise<string>;

package/dist/sdk/terminal/tui/goalCommand.js

@@ -0,0 +1,83 @@
+// `/goal` in the terminal (ADR-0072): set, view, edit, pause, resume and clear a goal. Adapted from
+// OpenAI Codex (Apache-2.0; see NOTICE.md): codex-rs/tui/src/chatwidget/slash_dispatch.rs and
+// goal_menu.rs. The model never creates a goal: the person does, here.
+import { GOAL_CUSTOM_TYPE, GoalError, continuationPrompt, goalSummary, objectiveUpdatedPrompt, parseGoalCommand, provenanceText } from "../../sessions/goal.js";
+export { GOAL_CUSTOM_TYPE };
+/** Runs one `/goal` and returns the text to show the person. */
+export async function runGoalCommand(argument, deps) {
+    const { controller } = deps;
+    const command = parseGoalCommand(argument);
+    try {
+        switch (command.kind) {
+            case 'error': return command.message;
+            case 'show': return goalSummary(controller.get());
+            case 'set': {
+                const existing = controller.get();
+                if (existing && existing.status !== 'complete') {
+                    const replace = await deps.confirm('Replace goal?', `The current goal is not finished:\n${existing.objective}\n\nReplace it with the new one and start it now?`);
+                    if (!replace)
+                        return 'Kept the current goal.';
+                }
+                // A reply that is running stops first: the new goal starts from a clean boundary.
+                if (!deps.idle())
+                    await deps.interrupt();
+                const goal = controller.set(command.objective, command.limits);
+                await deps.start(`${provenanceText('set', goal)}\n\n${continuationPrompt(goal)}`);
+                return `Goal active\nObjective: ${goal.objective}`;
+            }
+            case 'edit': {
+                const existing = controller.get();
+                if (!existing)
+                    return 'No goal to edit. Use /goal <objective>.';
+                const objective = command.objective ?? await deps.input('Edit goal', existing.objective);
+                if (!objective?.trim())
+                    return 'Goal unchanged.';
+                const goal = controller.edit(objective);
+                const content = `${provenanceText('edited', goal)}\n\n${objectiveUpdatedPrompt(goal)}`;
+                if (deps.idle())
+                    await deps.start(`${provenanceText('edited', goal)}\n\n${continuationPrompt(goal)}`);
+                else
+                    await deps.steer(content);
+                return `Goal updated\nObjective: ${goal.objective}`;
+            }
+            case 'pause': {
+                const goal = controller.get();
+                if (!goal)
+                    return 'No goal to pause.';
+                if (!deps.idle())
+                    await deps.interrupt();
+                const paused = controller.pause();
+                await deps.note(provenanceText('paused', paused));
+                return `Goal ${paused?.status === 'paused' ? 'paused' : `is ${paused?.status.replace('_', ' ')}`}. Use /goal resume to continue.`;
+            }
+            case 'resume': {
+                const goal = controller.get();
+                if (!goal)
+                    return 'No goal to resume.';
+                if (goal.status === 'complete')
+                    return 'The goal is complete. Set a new one with /goal <objective>.';
+                const resumed = controller.resume();
+                const content = `${provenanceText('resumed', resumed)}\n\n${continuationPrompt(resumed)}`;
+                if (deps.idle())
+                    await deps.start(content);
+                else
+                    await deps.steer(content);
+                return 'Goal active';
+            }
+            case 'clear': {
+                if (!controller.get())
+                    return 'No goal to clear.';
+                if (!deps.idle() && controller.active())
+                    await deps.interrupt();
+                controller.clear();
+                await deps.note(provenanceText('cleared', null));
+                return 'Goal cleared';
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof GoalError)
+            return error.message;
+        throw error;
+    }
+}

package/dist/sdk/terminal/tui/runtime.d.ts

@@ -1,4 +1,5 @@
 import { type AgentSession, type AgentSessionEventListener, type AgentSessionRuntime, type AgentSessionServices, type ExtensionUIContext } from '@earendil-works/pi-coding-agent';
+import { GoalController } from "../../sessions/goal.js";
 import type { SessionAccount } from "../accountsMenu.js";
 import type { QuestionAnswer } from "../../sessions/registry.js";
 import type { TerminalQuestion } from "./questions.js";
@@ -104,6 +105,8 @@ export interface TerminalRuntime {
     installationDeviceId(): Promise<string>;
     reload(): Promise<void>;
     interrupt(): Promise<void>;
+    /** This session's /goal (ADR-0072). */
+    readonly goal: GoalController;
     dispose(): Promise<void>;
 }
 /** Saved native history stays in the prepared project folder, including symlink targets. */

package/dist/sdk/terminal/tui/runtime.js

@@ -2,6 +2,7 @@ import { createAgentSession, createAgentSessionRuntime, DefaultResourceLoader, M
 import { closeSync, existsSync, openSync, readSync, realpathSync } from 'node:fs';
 import { isAbsolute, join, relative, resolve, sep } from 'node:path';
 import terminalExtension from "../piExtension.js";
+import { GoalController } from "../../sessions/goal.js";
 import { terminalCredentialStore } from "../credentialStore.js";
 import { normalModeTools, normalToolsForBranch, planModeTools, PLAN_TOOLS_ENTRY, QUESTION_TOOL_NAMES } from "./planMode.js";
 import { claimTerminalControl, controlCall } from "../control.js";
@@ -159,6 +160,7 @@ export async function createTerminalRuntime(args, host) {
         return sessionUiContext(host.ui, () => !disposed && generation === uiGeneration);
     };
     const planRun = { active: false, allowedTools: new Set() };
+    const goal = new GoalController();
     let currentMode = 'normal';
     let pendingApply = false;
     const choiceStore = {
@@ -223,7 +225,7 @@ export async function createTerminalRuntime(args, host) {
             additionalSkillPaths: prepared.skills, additionalPromptTemplatePaths: prepared.prompts,
             additionalThemePaths: prepared.themes,
             extensionFactories: [
-                { name: 'harness-terminal-bridge', factory: pi => terminalExtension(pi, planRun, () => native.session), hidden: true },
+                { name: 'harness-terminal-bridge', factory: pi => terminalExtension(pi, planRun, () => native.session, goal), hidden: true },
                 // A model picked in the terminal reaches Pi as this event. A restore is not a pick.
                 { name: 'harness-mode-choices', factory: pi => { pi.on('model_select', event => { if (event.source !== 'restore')
                         void modeChoices.record(recordingMode(), { model: `${event.model.provider}/${event.model.id}` }); }); }, hidden: true },
@@ -462,7 +464,11 @@ export async function createTerminalRuntime(args, host) {
                 } });
             host.changed();
         }),
+        goal,
         async interrupt() {
+            // The person stopping a running goal pauses it, as in Codex; /goal resume continues.
+            if (goal.active() && !native.session.isIdle)
+                goal.pause();
             // Bash executions use their own abort controllers, outside Pi's agent tool loop.
             native.session.abortBash();
             // Socket-backed questions and approvals must settle before Pi can finish aborting tools.

package/dist/sdk/tools/askUser.js

@@ -19,7 +19,7 @@ export function askUserTool(run) {
         name: ASK_USER,
         label: 'Ask the user',
         description: 'Ask the user one to five related questions in one request and wait until they answer the batch. Give each question a concise 1–2 word label and aim to keep each question to 25 words or fewer. ' +
-            'Every question must offer 1–6 short choices, each with a helpful description of 25 words or fewer, and at least one choice must be marked recommended: true. Recommendations are visual only: they never preselect an answer, and submitted choices keep their original labels. Mark at most one recommended choice for a single-choice question, or several when multiSelect is true. Every question also includes a free-text “Something else” answer. Set multiSelect when several can apply. When a UI diagram helps compare choices, set uiSketch: true and give every choice a detailed, bounded ASCII wireframe. Use ASCII tables and panel borders to show the affected element with relevant neighboring UI, readable labels and spacing. Keep each panel’s outer `+` corners in fixed columns, include side edges at those same columns on every content row, and run horizontal borders corner to corner; if a title sits in a top border, leave at least two dashes on both sides. Keep framing consistent across alternatives and concentrate detail on what changes. Do not substitute a symbolic logo or one-line illustration. The preview supplies its outer border; draw internal borders only for actual UI panels. Use it when you need a decision, not for small talk.',
+            'Every question must offer 1–6 short choices, each with a helpful description of 25 words or fewer, and at least one choice must be marked recommended: true. Recommendations are visual only: they never preselect an answer, and submitted choices keep their original labels. Mark at most one recommended choice for a single-choice question, or several when multiSelect is true. Every question also includes a free-text “Something else” answer. Set multiSelect when several can apply. When a UI diagram helps compare choices, set uiSketch: true and give every choice a detailed, bounded ASCII wireframe. Use ASCII tables and panel borders to show the affected element with relevant neighboring UI, readable labels and spacing. Keep each panel’s outer `+` corners in fixed columns, include side edges at those same columns on every content row, and run horizontal borders corner to corner; if a title sits in a top border, leave at least two dashes on both sides. Keep framing consistent across alternatives and concentrate detail on what changes. Do not substitute a symbolic logo or one-line illustration. The preview supplies its outer border; draw internal borders only for actual UI panels. Use it when you need a decision the request and the files do not answer, not for small talk and never to ask permission for work inside the request. If no answer arrives, continue with your best judgment instead of asking again or treating the turn as blocked.',
         parameters: (Type) => Type.Object({
             questions: Type.Array(Type.Object({
                 summary: Type.String({ description: 'A concise label of one or two words' }),

package/dist/sdk/tools/todo.js

@@ -4,7 +4,8 @@ import { todoItemSchema, MAX_TODO_ITEMS } from "../sessions/contracts.js";
 export const TODO_WRITE = 'todo_write';
 /** The trigger the prompt and the tool description share, so progress guidance cannot drift. */
 export const TODO_GUIDANCE = 'If the work has several distinct steps or will take more than one tool call, call todo_write before your first other tool call with the steps you know so far, and keep the list current as steps start and finish. ' +
-    'Keep the list true at all times: mark a step completed only once it is done and checked, and add steps you discover. An open step is work to do in this reply, not something to report; never mark unfinished work completed. ' +
+    'The list shows the person your progress; it is not the scope of the work. The request, and any document it points to, is the scope: add steps as the work shows them, list the steps of a handoff or plan instead of folding them into one "remaining work" item, and never stop because the list is short or done. ' +
+    'Keep the list true at all times: mark a step completed only once it is done and checked, and never mark unfinished work completed. An open step is work to do in this reply, not something to report. Before you end the turn, compare the request, not the list, with what is done and checked, and do whatever is still yours to do. ' +
     'The person follows your work from it, and a subagent’s todo list shows as its progress in the person’s list of subagents.';
 /** The event a run writes; `checklist.updated` is the pre-rename name, still read for old runs. */
 const TODO_EVENTS = new Set(['todo.updated', 'checklist.updated']);