Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions pi-ask/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
- **Cancel with a comment and skip.** `c` on the review tab attaches a short reason to a cancellation. `s` declines one question without cancelling the form; skipped is neither an answer nor approval.
- **Configuration and keys.** New keys `behaviour.background`, `expiry.enabled` and `expiry.minSeconds`, plus keymaps `global.later`, `global.panelFocus`, `main.skip` and `main.cancelComment`. `/ask-settings` exposes the expiry toggles; schema changes apply on `/reload`. `/ask-panel` shows waiting and expired forms.
- **Hosts without the custom TUI** keep the blocking card flow: `background` blocks there and there is no countdown.
- **Fixed.** A failed journal read on attach or a failed countdown-stop write no longer breaks panel refresh or swallows the first keystroke, and a blocking reply that could not be saved now returns the form to the panel with an error notice and tells the agent not to re-ask.
- The default `ask_user` context footprint is 1,598 chars (≈ 400 tokens), or 1,534 (≈ 384) with expiry off, within the existing 450/420 token ceilings.

## 0.1.5
Expand Down
2 changes: 1 addition & 1 deletion pi-ask/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,7 @@ The later answer is a `pi-ask:answer` message that names the request and each qu

Every form, draft and outcome is journalled in the session. A form left open when Pi quit comes back in the panel on startup, resume or fork with its draft, and its answer reaches the agent once: delivery is decided from what the active branch already holds. The journal follows the active branch.

A receipt or completed tool result requires a successful journal write. Storage failures are reported rather than acknowledged; a panel form whose answer could not be saved stays editable for retry. Hiding the panel or temporarily covering it with a blocking form preserves its live editor, including typing not yet flushed to the journal.
A receipt or completed tool result requires a successful journal write. Storage failures are reported rather than acknowledged; a panel form whose answer could not be saved stays editable for retry. Only panel forms are retried in place: if a blocking form's answer (or cancel, defer or expiry) cannot be saved, the form returns to the panel at once with its draft and you get an error notice, and the tool returns an error telling the agent the reply was not saved, the form will reappear in your panel and it should not re-ask. The non-TUI (RPC and print) path also requires the journal write before it returns. Hiding the panel or temporarily covering it with a blocking form preserves its live editor, including typing not yet flushed to the journal.

Optional config: `~/.pi/agent/extensions/pi-ask.json`. `/answer` uses the current chat model unless `answer.extractionModels` is set. `PI_ASK_LOCALE=zh` localizes the dialog cards and result summaries (Simplified Chinese).

Expand Down
59 changes: 55 additions & 4 deletions pi-ask/src/ask-tool.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ import {
import { getAskConfigStore } from "./config/store.ts";
import { type AskFeatures, NO_ASK_FEATURES } from "./features.ts";
import { buildAskParamsSchema, stripSchemaDescriptions } from "./schema.ts";
import { toFormSnapshot } from "./journal/journal.ts";
import { AskJournalWriteError, describeExpiryStopFailure, toFormSnapshot } from "./journal/journal.ts";
import { type AskRuntime, createAskRuntime } from "./runtime.ts";
import {
createExpiryTimer,
Expand Down Expand Up @@ -62,7 +62,7 @@ export function registerAskTool(pi: ExtensionAPI, options: AskToolOptions = {})
}

async function executeAskTool(
{ background, clock, flushers, journal, live }: AskRuntime,
{ background, clock, flushers, journal, live, returning, unsaved }: AskRuntime,
features: AskFeatures,
toolCallId: string,
params: AskParams,
Expand Down Expand Up @@ -125,6 +125,13 @@ async function executeAskTool(
// A stopped countdown is journalled, so no rebuild can bring it back.
timer?.subscribe({
stop: (reason) => journal.recordExpiryStop(requestId, reason),
failed: (error) => {
if (error instanceof AskJournalWriteError) {
ctx.ui.notify(describeExpiryStopFailure(error), "error");
return true;
}
return false;
},
});
const openForm = () =>
runAskFlow(ctx, params, {
Expand Down Expand Up @@ -152,18 +159,62 @@ async function executeAskTool(
if (background && result.status === "deferred") {
// "Answer later": the form keeps its request-order place in the queue
// and its draft; the answer follows as a message.
journal.recordDefer(requestId);
saved(ctx, background, unsaved, requestId, "deferred", () =>
journal.recordDefer(requestId)
);
background.enqueue(ctx, requestId, "deferred");
return successfulResponse(receipt(validation.state, "deferred", requestId));
}
const outcome = journal.recordOutcome(requestId, result, "tool");
const outcome = saved(ctx, background, unsaved, requestId, result.status, () =>
journal.recordOutcome(requestId, result, "tool")
);
// The tool result follows this return; until it lands on the branch the
// answer must not also be adopted as an orphan.
returning.add(requestId);
if (result.status === "expired") {
// It can now be reopened for a late correction.
background?.formEnded(ctx);
}
return successfulResponse(outcome.result);
}

const UNSAVED: Record<string, string> = {
cancelled: "cancellation",
deferred: "deferral",
expired: "expiry",
};

/**
* The user's reply is gone from the screen but not in the journal. Put the
* form back in the panel at once, tell the user, and tell the agent not to
* ask again.
*/
function saved<T>(
ctx: ExtensionContext,
background: AskRuntime["background"],
unsaved: Set<string>,
requestId: string,
status: string,
write: () => T
): T {
try {
return write();
} catch (error) {
if (error instanceof AskJournalWriteError) {
const what = UNSAVED[status] ?? "answer";
unsaved.add(requestId);
try {
background?.formEnded(ctx);
ctx.ui.notify(`${error.message} The form is back in your panel.`, "error");
} catch {
// The screen is gone; the journal still holds the form.
}
error.message += ` The user's ${what} was not saved; the form will reappear in their panel. Do not re-ask.`;
Comment thread
GaganSD marked this conversation as resolved.
Resolved
}
throw error;
}
}

/** A receipt names the form and carries no answers, not even drafted ones. */
function receipt(
state: AskState,
Expand Down
78 changes: 69 additions & 9 deletions pi-ask/src/background.ts
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ import {
} from "./delivery.ts";
import { askStrings } from "./i18n.ts";
import { ASK_ANSWER_MESSAGE_TYPE } from "./journal/entries.ts";
import { AskJournalWriteError, readAskJournal } from "./journal/journal.ts";
import { AskJournalWriteError, describeExpiryStopFailure, readAskJournal } from "./journal/journal.ts";
import {
type AskJournalRecord,
getRecord,
Expand Down Expand Up @@ -121,9 +121,12 @@ export function registerAskBackground(
"agent_before_settle",
(event, ctx) => background.boundary(ctx, event)
);
pi.on("agent_settled", (event, ctx) =>
background.settled(ctx, event.aborted)
);
pi.on("agent_settled", (event, ctx) => {
// Every result of the run has landed, or never will. Landed results
// are excluded by the branch itself; this only ends the hold.
runtime.returning.clear();
background.settled(ctx, event.aborted);
});
// A manual compaction keeps Pi busy without a run; pick up afterwards.
pi.on("session_compact", (_event, ctx) => background.poke(ctx));
pi.registerMessageRenderer?.(
Expand All @@ -139,12 +142,22 @@ export function registerAskBackground(
return background;
}

/** Pi's own error for an extension context used after reload or replacement. */
function isRecoverableReadError(error: unknown): boolean {
return (
error instanceof Error &&
error.message.startsWith("This extension ctx is stale after")
);
}

export function createAskBackground(
pi: Pick<ExtensionAPI, "sendMessage">,
{ clock, flushers, journal, live }: AskRuntime
{ clock, flushers, journal, live, returning, unsaved }: AskRuntime
): AskBackground {
const now = clock?.now ?? Date.now;
const delivery = createAskDelivery(pi);
const delivery = createAskDelivery(pi, {
isLive: (requestId) => live.has(requestId) || returning.has(requestId),
});
const recorders = new Map<string, (state: AskState) => void>();
// Content key of the draft each loaded form last started from or wrote,
// to tell whether a re-read branch still agrees with what is on screen.
Expand Down Expand Up @@ -218,9 +231,39 @@ export function createAskBackground(
return recorder;
}

/**
* Forms whose save failed are held in memory. Once the journal accepts a
* `defer` for one, it is an ordinary queued form and survives a reload.
*/
function persistUnsaved(current: ExtensionContext) {
if (unsaved.size === 0) {
return;
}
const journalState = readAskJournal(current);
for (const requestId of [...unsaved]) {
const record = getRecord(journalState, requestId);
if (!record) {
continue;
}
if (!isOpen(record) || record.deferred) {
unsaved.delete(requestId);
} else if (!live.has(requestId)) {
try {
journal.recordDefer(requestId);
unsaved.delete(requestId);
} catch (error) {
if (!(error instanceof AskJournalWriteError)) {
throw error;
}
}
}
}
}

function readQueue(current: ExtensionContext) {
persistUnsaved(current);
const journalState = readAskJournal(current);
const pending = pendingForms(journalState, live, reopened);
const pending = pendingForms(journalState, live, reopened, unsaved);
records = new Map(pending.map((record) => [record.requestId, record]));
for (const requestId of recorders.keys()) {
if (!records.has(requestId)) {
Expand Down Expand Up @@ -567,8 +610,18 @@ export function createAskBackground(
}
reconcileBranch(next);
refresh((queue, hidden) => ({ type: "sync", queue, hidden }));
delivery.attach(next);
poke(next);
try {
delivery.attach(next);
} catch (error) {
// A stale context or an unreadable branch is retried by the next
// pump or lifecycle event; nothing stale is kept. Anything else
// is a bug: surface it once the panel has refreshed.
if (!isRecoverableReadError(error)) {
throw error;
}
} finally {
poke(next);
}
},
poke,
formEnded(next) {
Expand All @@ -584,6 +637,13 @@ export function createAskBackground(
const timer = createExpiryTimer(options.timeoutSeconds, clock);
timer.subscribe({
stop: (reason) => journal.recordExpiryStop(requestId, reason),
failed: (error) => {
if (error instanceof AskJournalWriteError) {
ctx?.ui.notify(describeExpiryStopFailure(error), "error");
return true;
}
return false;
},
expire: () => expire(requestId),
});
timers.set(requestId, timer);
Expand Down
34 changes: 25 additions & 9 deletions pi-ask/src/delivery.ts
Original file line number Diff line number Diff line change
Expand Up @@ -164,7 +164,8 @@ function answerMessage(outcome: AskOutcomeEntry) {
}

export function createAskDelivery(
pi: Pick<ExtensionAPI, "sendMessage">
pi: Pick<ExtensionAPI, "sendMessage">,
{ isLive = () => false }: { isLive?: (requestId: string) => boolean } = {}
): AskDelivery {
// Sent in this process, potentially still being written by a run. Cleared
// only when idle or a new run starts; the branch then proves delivery.
Expand All @@ -175,8 +176,30 @@ export function createAskDelivery(
// Only tool outcomes already orphaned at attach can become messages.
// Eligibility lasts until branch evidence proves delivery, not one plan.
let adopted = new Set<string>();
// An attach whose journal read failed: adoption is retried before the
// next plan, and nothing from the previous branch stays eligible.
let adoptionPending = false;

function adopt(ctx: DeliveryContext) {
adopted = new Set<string>();
adoptionPending = true;
adopted = new Set(
undeliveredOutcomes(readAskJournal(ctx), { unrecordedTool: true })
// A call still returning its result is not an orphan.
.filter(
({ outcome }) =>
outcome.channel === "tool" && !isLive(outcome.requestId)
)
.map(({ outcome }) => outcome.outcomeId)
);
adoptionPending = false;
watching = true;
}

function plan(ctx: DeliveryContext, situation: AskDeliverySituation) {
if (adoptionPending) {
adopt(ctx);
}
if (!watching) {
return;
}
Expand Down Expand Up @@ -219,14 +242,7 @@ export function createAskDelivery(
post() {
watching = true;
},
attach(ctx) {
adopted = new Set(
undeliveredOutcomes(readAskJournal(ctx), { unrecordedTool: true })
.filter(({ outcome }) => outcome.channel === "tool")
.map(({ outcome }) => outcome.outcomeId)
);
watching = true;
},
attach: adopt,
started() {
// No prior run can still be writing a send. Do not send here: this
// run's starting message is recorded before its first boundary.
Expand Down
6 changes: 6 additions & 0 deletions pi-ask/src/journal/journal.ts
Original file line number Diff line number Diff line change
Expand Up @@ -142,6 +142,12 @@ export class AskJournalWriteError extends Error {
}
}

/** User-facing text for a countdown stop that could not be journalled. */
export function describeExpiryStopFailure(error: AskJournalWriteError): string {
const cause = error.cause instanceof Error ? error.cause.message : String(error.cause);
return `Could not save the ask_user countdown stop (${cause}). The countdown is stopped for now, but a reload may restore it; fix session storage.`;
}

/** Journal backed by the session file; successful writes are required. */
export function createSessionAskJournal(
pi: Pick<ExtensionAPI, "appendEntry">,
Expand Down
10 changes: 9 additions & 1 deletion pi-ask/src/journal/replay.ts
Original file line number Diff line number Diff line change
Expand Up @@ -202,13 +202,21 @@ export function queuedForms(state: AskJournalState): AskJournalRecord[] {
export function pendingForms(
state: AskJournalState,
live: ReadonlySet<string> = new Set(),
reopened: ReadonlySet<string> = new Set()
reopened: ReadonlySet<string> = new Set(),
unsaved: ReadonlySet<string> = new Set()
): AskJournalRecord[] {
const waiting = new Set(
[...queuedForms(state), ...interruptedForms(state)]
.filter((record) => record.deferred || !live.has(record.requestId))
.map((record) => record.requestId)
);
// A form whose save failed was promised back; later messages do not
// supersede it, but one still on screen is not waiting yet.
for (const record of state.records) {
if (isOpen(record) && unsaved.has(record.requestId) && !live.has(record.requestId)) {
waiting.add(record.requestId);
}
}
// An expired form joins the queue only once the user asked for it.
for (const record of reopenableForms(state)) {
if (reopened.has(record.requestId)) {
Expand Down
14 changes: 14 additions & 0 deletions pi-ask/src/runtime.ts
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,18 @@ export interface AskRuntime {
* skips them: an open form is not an interrupted one.
*/
live: Set<string>;
/**
* Blocking calls whose outcome is journalled but whose tool result may
* not be on the branch yet, identified by request id. The result is
* about to arrive, so the answer must not also be sent as a message.
*/
returning: Set<string>;
/**
* Blocking forms whose outcome or deferral could not be journalled. The
* agent was told they will reappear, so the panel keeps them even after
* the conversation moves on, until a `defer` entry makes that durable.
*/
unsaved: Set<string>;
}

export function createAskRuntime(
Expand All @@ -35,5 +47,7 @@ export function createAskRuntime(
flushers: new Set(),
journal: createSessionAskJournal(pi, clock && { now: clock.now }),
live: new Set(),
returning: new Set(),
unsaved: new Set(),
};
}
Loading
Loading