@osolmaz/pi-workflows 0.12.1 → 0.13.0

package/docs/plans/2026-08-23-assistant-agent-completion-plan.md

@@ -0,0 +1,701 @@
+---
+title: Add assistant completion to agent workflows
+author: Onur Solmaz <2453968+osolmaz@users.noreply.github.com>
+date: 2026-08-23
+status: implemented
+---
+
+## Selected design
+
+Keep `agent` as the only model-work node.
+
+Use the existing `expectedOutput` key to select a visible assistant response:
+
+```ts
+agent({
+  prompt: ({ input }) => `Summarize this:\n${JSON.stringify(input)}`,
+  expectedOutput: assistantMessage(),
+});
+```
+
+The two behaviors are:
+
+- **Current agent:** the model calls `workflow submit`; the submitted JSON becomes the node output.
+- **Assistant agent:** the model writes a normal assistant response; its exact visible text becomes the node output, and the workflow follows its normal edge.
+
+The assistant mode is not a decision or checkpoint. It schedules one model turn, waits until that turn fully settles, records the result, and continues.
+
+This needs no Pi API change and no new node type.
+
+---
+
+# Implementation plan
+
+## 1. Record the completion-mode contract
+
+### Change
+
+Document that `agent` supports two mutually exclusive completion methods:
+
+1. Workflow-tool submission.
+2. Visible assistant response.
+
+Define these rules:
+
+- Existing agents keep their current workflow-tool behavior.
+- Assistant completion is explicit through `expectedOutput: assistantMessage()`.
+- Output-transforming `validate` is invalid with `assistantMessage()`.
+- The assistant node output is the exact visible text.
+- The text must be non-empty. A character limit applies only when the author sets `maxChars`.
+- The node follows its configured edge after the assistant turn settles.
+- It does not ask for human input and does not create a checkpoint.
+- Intermediate tool-call assistant messages do not complete the node.
+- Aborted, failed, and tool-only turns do not complete the node.
+- A visible response is not retried after validation failure because that would show duplicate answers.
+- Session-bound assistant output is unavailable to detached jobs without an origin session.
+
+### Where
+
+- New canonical plan under `docs/plans/`.
+- `docs/workflows.md`
+- `docs/WORKFLOW_STEP_MESSAGES.md`
+- `docs/WORKFLOW_COMPOSITION.md`
+- `docs/SQLITE_STATE.md`
+
+### Verification
+
+The documents distinguish assistant completion from:
+
+- `workflow submit`;
+- `notify`;
+- root `presentationPrompt`;
+- `checkpoint`;
+- `humanDecision()`.
+
+---
+
+## 2. Extend the public `agent()` definition
+
+### Change
+
+Add a public assistant output builder:
+
+```ts
+assistantMessage();
+```
+
+Make `AgentNodeDefinition` a type-safe union:
+
+```ts
+type SubmittedAgentNodeDefinition = {
+  nodeType: "agent";
+  prompt: ...;
+  expectedOutput?: string;
+  validate?: ...;
+};
+
+type AssistantAgentNodeDefinition = {
+  nodeType: "agent";
+  prompt: ...;
+  expectedOutput: AssistantMessageOutput;
+  validate?: never;
+};
+```
+
+Keep the existing submitted-agent API unchanged. This is an additive mode, not a compatibility shim.
+
+`assistantMessage()` adds no Pi Workflows character limit by default. Authors can opt in with `assistantMessage({ maxChars: 2_000 })`. When supplied, `maxChars` must be a positive integer. A specific workflow such as `plain-summary` can set its own explicit limit.
+
+### Where
+
+- `src/workflows/types.ts`
+- `src/workflows/definition.ts`
+- `src/workflows/schema.ts`
+- `src/workflows/index.ts`
+- Type-level tests
+
+### Verification
+
+Type tests prove:
+
+- existing agents still compile;
+- assistant agents compile;
+- `assistantMessage()` plus `validate` does not compile;
+- omitted limits remain omitted in the definition;
+- invalid explicit limits fail during definition validation;
+- no new node type appears in graph or run records.
+
+---
+
+## 3. Add completion mode to the executor contract
+
+### Change
+
+Extend `AgentStepContract` with:
+
+```ts
+completion: "submit" | "assistant";
+maxOutputChars?: number;
+```
+
+For existing submitted agents:
+
+- append the current workflow step contract;
+- keep `accept(output)`;
+- keep nudges when the model settles without submitting.
+
+For assistant agents:
+
+- do not append workflow-submit instructions;
+- append a short assistant completion contract;
+- tell the model to answer normally and not call `workflow submit`;
+- capture only visible text blocks;
+- complete after `agent_settled`;
+- return the exact text as `AgentStepSubmission.output`.
+
+Example model contract:
+
+```text
+Reply with a normal assistant message.
+Do not call the workflow tool to complete this step.
+Your visible reply becomes the workflow step output.
+```
+
+When the author supplies `maxChars`, append that explicit limit to the model contract.
+
+### Where
+
+- `src/workflows/types.ts`
+- `src/workflows/engine.ts`
+- `src/extension/step-message.ts`
+- `src/extension/executor.ts`
+
+### Verification
+
+Engine tests prove both completion modes use the same `agent` node type and route through ordinary edges.
+
+---
+
+## 4. Capture the interactive assistant response
+
+### Change
+
+Extend `ConversationStepExecutor` to track the pending completion mode.
+
+For assistant completion:
+
+1. Mark the conversation before sending the prompt.
+2. Deliver the existing compact workflow step message.
+3. Record `message_end`, then use the later `turn_end` message after all documented message replacements have run.
+4. Keep the latest finalized assistant message from the current attempt.
+5. Ignore thinking blocks and tool calls.
+6. Wait for `agent_settled`.
+7. Reject aborted, errored, empty, or tool-only outcomes.
+8. Check the character limit when the author supplied one.
+9. Record the conversation range.
+10. Resolve the node with the exact assistant text.
+
+Do not set `suppressWorkflowAssistantTail` for this mode. The response must stay visible.
+
+When the model calls `workflow submit` during an assistant step, return a clear error:
+
+> This step completes with a normal assistant response. Do not submit workflow output.
+
+Updates can remain unavailable for assistant completion unless later evidence shows a real need.
+
+### Where
+
+- `src/extension/executor.ts`
+- `src/extension/index.ts`
+- `src/extension/session-events.ts`
+- `src/extension/recorder.ts`
+- `src/extension/step-message.ts`
+
+### Verification
+
+Tests cover:
+
+- one visible assistant message;
+- exact captured text;
+- text mixed with thinking;
+- tool call followed by final text;
+- several tool turns;
+- auto-retry before final settlement;
+- empty response;
+- length stop;
+- provider error;
+- user Escape;
+- timeout and cancellation;
+- incorrect `workflow submit`;
+- parent continuation only after settlement.
+
+---
+
+## 5. Make recovery duplicate-safe
+
+### Change
+
+Bind the assistant response to the existing run, node, and attempt IDs.
+
+The custom workflow prompt already carries those IDs. Extend its message details with the completion mode.
+
+Record an attempt-scoped assistant completion receipt containing:
+
+- run ID;
+- node ID;
+- attempt ID;
+- assistant session entry ID;
+- text digest;
+- bounded text;
+- conversation range.
+
+Before redelivering an unfinished assistant step, inspect the current session branch:
+
+- If the matching prompt has a completed assistant child, validate and adopt it.
+- If the matching prompt exists without a completed assistant response, resume the attempt.
+- If no matching prompt exists, send it.
+- Never adopt a response from another attempt or branch.
+
+Use existing run state, trace, and session recording. Do not add a new store.
+
+### Where
+
+- `src/workflows/types.ts`
+- `src/workflows/store.ts`
+- `src/workflows/engine.ts`
+- `src/extension/recorder.ts`
+- `src/extension/executor.ts`
+- SQLite run projection and recovery tests
+
+### Verification
+
+Crash tests cover:
+
+- before prompt delivery;
+- after prompt delivery;
+- during streaming;
+- after `message_end` but before `agent_settled`;
+- after settlement but before node persistence;
+- after node persistence but before routing;
+- process restart;
+- session reload;
+- claim loss;
+- stale branch response;
+- repeated loop visits to the same node.
+
+Each case produces at most one visible assistant response.
+
+---
+
+## 6. Handle interactive and detached execution honestly
+
+### Change
+
+Assistant completion needs a conversation where the user can see the assistant response.
+
+Add an executor capability that distinguishes:
+
+- session-visible execution;
+- detached execution.
+
+The interactive Pi executor supports assistant completion.
+
+A detached WorkflowHost must not run such a node in an invisible RPC child. It must:
+
+- park the run before the node;
+- leave it claimable by the origin Pi session;
+- resume when that session is available.
+
+A controller child or detached run with no origin session must fail clearly before prompting:
+
+> Assistant completion requires an origin Pi session.
+
+Do not replace the response with a workflow notification.
+
+Direct RPC clients can support assistant completion because RPC exposes `message_end` and `agent_settled` events to the client.
+
+### Where
+
+- `src/workflows/types.ts`
+- `src/workflows/engine.ts`
+- `src/host/runner.ts`
+- `src/host/rpc-executor.ts`
+- `src/host/rpc-bridge.ts` only if the bridge needs completion metadata
+- Queue and host tests
+
+### Verification
+
+Tests prove:
+
+- interactive TUI works;
+- direct RPC captures the assistant response;
+- a detached host parks before visible output;
+- the origin session resumes and emits it once;
+- a detached run without an origin session fails clearly;
+- no assistant response is silently converted into a notification.
+
+---
+
+## 7. Add the general `plain-summary` workflow
+
+### Change
+
+Create a reusable built-in workflow with this input:
+
+```ts
+type PlainSummaryInput = {
+  source: unknown;
+  purpose: string;
+  mustInclude?: string[];
+  maxChars?: number;
+  maxSentences?: number;
+  format?: "paragraphs" | "bullets" | "mixed";
+};
+```
+
+Use strict limits:
+
+- serialized source: at most 50,000 characters;
+- purpose: at most 1,000 characters;
+- up to 32 required points;
+- each required point: at most 500 characters;
+- `maxChars`: default 2,000, maximum 10,000;
+- `maxSentences`: default 5, maximum 20.
+
+The workflow uses one assistant-completion agent. Its prompt says:
+
+- use only the supplied source;
+- start with the main point;
+- use short, complete sentences;
+- use common, concrete words;
+- keep technical terms only when needed;
+- do not invent facts;
+- do not add a meta introduction;
+- include every required point;
+- obey the requested format and limits;
+- do not use tools;
+- do not call the workflow tool.
+
+Do not import or depend on OnurPi’s personal `amk` skill. Put the stable plain-writing rules directly in this public workflow.
+
+Return:
+
+```ts
+type PlainSummaryResult = {
+  text: string;
+};
+```
+
+The text is both:
+
+- the visible assistant message;
+- the included workflow’s result.
+
+The workflow has no `notify` node and no `presentationPrompt`, because its assistant agent already presents the result.
+
+### Where
+
+- `src/builtins/plain-summary.workflow.ts`
+- `src/builtins/index.ts`
+- `src/builtins/catalog.ts`
+- `examples/workflows/plain-summary.workflow.ts`
+- `test/builtin-plain-summary.test.ts`
+
+### Verification
+
+Test it:
+
+- standalone;
+- included in a parent;
+- nested;
+- repeated in a loop;
+- with paragraphs, bullets, and mixed output;
+- with missing required facts;
+- with excessive input;
+- with excessive output;
+- with hostile instructions inside `source`;
+- with cancellation;
+- with no duplicate final presentation.
+
+---
+
+## 8. Make Autoplan record every considered plan
+
+### Change
+
+Autoplan cannot summarize plans that exist only in hidden model reasoning. Make every candidate explicit in the durable `propose` output.
+
+Change `propose` to return a bounded candidate list:
+
+```ts
+{
+  candidates: [
+    {
+      id: "stable-id",
+      title: "short title",
+      gist: "plain description",
+      solution: "full proposal",
+      rationale: "why it could work",
+      parts: ["part"],
+      tradeoffs: ["trade-off"],
+    },
+  ];
+}
+```
+
+Require two through four practical candidates.
+
+Keep the separate ideal stage. Treat the ideal as another named candidate during selection.
+
+When `previousPlan` exists, require the proposal stage to identify whether it remains a candidate or was rejected by new evidence.
+
+Change `choose` to return:
+
+```ts
+{
+  status: "ready",
+  selectedId: "candidate-id-or-ideal",
+  why: "reason",
+  rejected: [
+    { "id": "other-id", "reason": "why it was not selected" }
+  ],
+  compromises: ["compromise"]
+}
+```
+
+Validate that:
+
+- the selected ID exists;
+- every non-selected candidate appears exactly once under `rejected`;
+- no unknown candidate appears;
+- no candidate is omitted;
+- the previous plan is accounted for when supplied.
+
+“All proposed plans” means these explicit records. It does not include or request hidden chain-of-thought.
+
+### Where
+
+- `src/builtins/autoplan.workflow.ts`
+- `test/builtin-autoplan.test.ts`
+- Autoplan docs and skill text
+
+### Verification
+
+Tests cover candidate completeness, stable IDs, ideal selection, practical selection, previous-plan treatment, duplicate rejection entries, missing candidates, and blocked selection.
+
+---
+
+## 9. Compose `plain-summary` into Autoplan
+
+### Change
+
+Add `plain-summary` as an included workflow.
+
+For a successful selection, pass:
+
+- the chosen candidate;
+- why it was chosen;
+- the detailed implementation plan;
+- every rejected candidate;
+- every rejection reason;
+- the relationship to the ideal;
+- important limits and compromises.
+
+Require the visible response to contain:
+
+1. A plain explanation of the chosen plan.
+2. A short list of the main implementation steps.
+3. One-line summaries of all rejected plans and why each lost.
+4. A clear note when the recommendation is still awaiting approval.
+
+Use a bounded format, for example:
+
+- maximum 2,500 characters;
+- maximum 12 sentences;
+- mixed paragraph and bullets.
+
+For a blocked selection, run the same summarizer with:
+
+- the blocker;
+- all considered candidates;
+- why none can meet the goal.
+
+Route both successful and blocked paths through the summarizer.
+
+Remove Autoplan’s root `presentationPrompt`. Otherwise it would create a second assistant response.
+
+Preserve the full technical outputs in `AutoplanReady` and add:
+
+```ts
+plainSummary: {
+  text: string;
+}
+```
+
+### Where
+
+- `src/builtins/autoplan.workflow.ts`
+- `test/builtin-autoplan.test.ts`
+- `docs/workflows.md`
+- `skills/autoplan/SKILL.md`
+
+### Verification
+
+A real-Pi mock-provider test proves:
+
+- Autoplan emits one plain assistant message;
+- it does not call `workflow submit` for the summary node;
+- the message includes the chosen plan;
+- every explicit rejected plan is present;
+- the detailed plan remains in durable SQLite run state;
+- no long second presentation appears;
+- a parent workflow continues after the summary settles.
+
+---
+
+## 10. Preserve behavior when Autoplan is included elsewhere
+
+### Change
+
+Check every current Autoplan composition:
+
+- shared plan-change workflow;
+- Autoimplement redesign;
+- Monitor repair planning.
+
+The summary will appear before documentation and human approval. Its wording must say “recommended plan” or “plan selected for approval,” not “approved plan.”
+
+Human approval remains separate. The summary does not answer or bypass `humanDecision()`.
+
+### Where
+
+- `src/builtins/plan-change.workflow.ts`
+- `src/builtins/autoimplement.workflow.ts`
+- `src/builtins/monitor.workflow.ts`
+- Related tests
+
+### Verification
+
+Tests prove:
+
+- the summary appears before approval;
+- Telegram and Pi still receive the actual human decision;
+- the summary cannot satisfy that decision;
+- approval, stop, replan, timeout, and skip routes remain unchanged;
+- replanning emits one new summary for the new candidate set.
+
+---
+
+## 11. Update snapshots, rendering, and revisions
+
+### Change
+
+Show assistant-completion agents as ordinary agent nodes, with a small completion marker in piw and expanded details.
+
+Do not add a node color or node type.
+
+Update definition snapshots to include:
+
+```json
+{
+  "nodeType": "agent",
+  "expectedOutput": {
+    "kind": "assistant-message",
+    "maxChars": 2000
+  }
+}
+```
+
+Omit `maxChars` from the snapshot when the author did not set it.
+
+Bump affected built-ins:
+
+- `plain-summary`: revision 1;
+- `autoplan`: revision 2;
+- Autoimplement and Monitor revisions if their compiled mounted-source graphs change.
+
+Use the alpha hard-cutover policy for unfinished runs whose definitions changed. Keep terminal SQLite runs readable.
+
+### Where
+
+- `src/workflows/store.ts`
+- `src/render/`
+- `src/viewer/`
+- `src/extension/widget.ts`
+- `src/builtins/catalog.ts`
+- Snapshot and revision tests
+
+### Verification
+
+The widget and piw show the node as an agent and clearly state “assistant response.” Old terminal runs still render. Incompatible unfinished runs get clear restart guidance.
+
+---
+
+## 12. Full verification
+
+Run focused tests first:
+
+```bash
+npx vitest run test/executor.test.ts
+npx vitest run test/rpc-executor.test.ts test/rpc-executor-flow.test.ts
+npx vitest run test/engine.test.ts test/store.test.ts
+npx vitest run test/builtin-plain-summary.test.ts test/builtin-autoplan.test.ts
+npx vitest run test/extension.test.ts test/step-message.test.ts
+```
+
+Then run all required repository gates:
+
+```bash
+npm run check
+npm run test:e2e
+npx slophammer-ts@latest dry .
+npx slophammer-ts@latest check . --only ts.dependency-boundaries-required
+```
+
+The real-Pi end-to-end test must verify the session transcript directly:
+
+- one assistant-completion prompt;
+- one normal assistant message;
+- no summary `workflow submit` call;
+- one following parent step;
+- no duplicate summary after reload;
+- no workflow notification containing the summary.
+
+Run Pi Reviewer until no P0 or P1 findings remain, then verify CI.
+
+---
+
+## Compatibility and release
+
+This is a compatible public capability addition to `agent()` and a new built-in workflow. At the current `0.12.1` baseline, the likely release is `0.13.0`.
+
+Existing submitted-agent workflows remain valid. No legacy adapter or second agent implementation is added.
+
+Autoplan’s structured proposal and selection outputs change in place. Its built-in revision must change, and unfinished older runs must restart.
+
+Do not update OnurPi, install the release, or change another repository as part of this implementation unless separately authorized.
+
+---
+
+## Main risks
+
+| Risk                                                   | Mitigation                                                                                                                                                                    |
+| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Duplicate assistant response after a crash             | Bind prompt and response to run/node/attempt IDs and reconcile the session branch before redelivery.                                                                          |
+| Parent advances before the assistant finishes          | Resolve assistant mode only from `agent_settled`.                                                                                                                             |
+| Tool-only response completes the node                  | Require non-empty final visible text after tool activity settles.                                                                                                             |
+| A workflow receives more text than it needs            | Set `maxChars` explicitly for that workflow. Keep the general API unlimited by default and do not retry an already visible response.                                          |
+| Detached host produces an invisible assistant response | Park before the node and require the origin Pi session.                                                                                                                       |
+| Summary bypasses human approval                        | Keep it as an agent output; human decisions remain protected checkpoints.                                                                                                     |
+| “All plans” implies hidden reasoning                   | Include every explicit candidate record and never request hidden reasoning.                                                                                                   |
+| Generic summary leaks source data into chat            | Document that callers choose the source and that the assistant response becomes normal session state.                                                                         |
+| Extra model cost                                       | Autoplan replaces its existing final presentation turn, so standalone use should not add a second final model call. Included use intentionally adds one visible summary turn. |
+
+## Contract impact
+
+- **Session state:** one normal assistant message for each assistant-completion node.
+- **Run state:** exact text, output mode, conversation range, recovery receipt, and the optional author-supplied character limit.
+- **Other persistent data:** none beyond existing SQLite workflow state and Pi session entries.
+- **Pi internals:** none.
+- **Pi API:** existing documented message and lifecycle events only.
+- **pi-workflows API:** additive `expectedOutput: assistantMessage()` mode for `agent()` and the new composable `plain-summary` workflow.