pi-interactive-shell 0.8.2 → 0.10.0

package/examples/skills/codex-cli/SKILL.md

@@ -23,7 +23,7 @@ description: OpenAI Codex CLI reference. Use when running codex in interactive_s
 
 | Flag | Description |
 |------|-------------|
-| `-m, --model <model>` | Switch model (default: `gpt-5.3-codex`) |
+| `-m, --model <model>` | Switch model (default: `gpt-5.3-codex`). Options include `gpt-5.4` (newer, more thorough) and `gpt-5.3-codex` (faster) |
 | `-c <key=value>` | Override config.toml values (dotted paths, parsed as TOML) |
 | `-p, --profile <name>` | Use config profile from config.toml |
 | `-s, --sandbox <mode>` | Sandbox policy: `read-only`, `workspace-write`, `danger-full-access` |
@@ -66,19 +66,27 @@ Define profiles for different projects/modes with `[profiles.<name>]` sections.
 
 Do NOT pass `-s` / `--sandbox` flags. Codex's `read-only` and `workspace-write` sandbox modes apply OS-level filesystem restrictions that break basic shell operations inside the PTY -- zsh can't even create temp files for here-documents, so every write attempt fails with "operation not permitted." The interactive shell overlay already provides supervision (user watches in real-time, Ctrl+Q to kill, Ctrl+T to transfer output), making Codex's sandbox redundant.
 
-Use explicit flags to control model and behavior per-run:
+Use explicit flags to control model and behavior per-run.
+
+For delegated fire-and-forget runs, prefer `mode: "dispatch"` so the agent is notified automatically when Codex completes.
 
 ```typescript
-// Interactive with prompt
+// Delegated run with gpt-5.4 (recommended for thorough work)
+interactive_shell({
+  command: 'codex -m gpt-5.4 -a never "Review this codebase for security issues"',
+  mode: "dispatch"
+})
+
+// Faster run with gpt-5.3-codex
 interactive_shell({
-  command: 'codex -m gpt-5.3-codex -a never "Review this codebase for security issues"',
-  mode: "hands-free"
+  command: 'codex -m gpt-5.3-codex -a never "Quick refactor task"',
+  mode: "dispatch"
 })
 
-// Override reasoning effort for a single run
+// Override reasoning effort for complex tasks
 interactive_shell({
-  command: 'codex -m gpt-5.3-codex -c model_reasoning_effort="xhigh" -a never "Complex refactor task"',
-  mode: "hands-free"
+  command: 'codex -m gpt-5.4 -c model_reasoning_effort="xhigh" -a never "Complex architecture review"',
+  mode: "dispatch"
 })
 
 // Headless - use bash instead

package/examples/skills/gpt-5-4-prompting/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: gpt-5-4-prompting
+description: How to write system prompts and instructions for GPT-5.4. Use when constructing or tuning prompts targeting GPT-5.4.
+---
+
+# GPT-5.4 Prompting Guide
+
+GPT-5.4 unifies reasoning, coding, and agentic capabilities into a single frontier model. It's extremely persistent, highly token-efficient, and delivers more human-like outputs than its predecessors. However, it has new failure modes: it moves fast without solid plans, expands scope aggressively, and can prematurely declare tasks complete—sometimes falsely claiming success. Prompts must account for these behaviors.
+
+## Output shape
+
+Always include.
+
+```
+<output_verbosity_spec>
+- Default: 3-6 sentences or <=5 bullets for typical answers.
+- Simple yes/no questions: <=2 sentences.
+- Complex multi-step or multi-file tasks:
+  - 1 short overview paragraph
+  - then <=5 bullets tagged: What changed, Where, Risks, Next steps, Open questions.
+- Avoid long narrative paragraphs; prefer compact bullets and short sections.
+- Do not rephrase the user's request unless it changes semantics.
+</output_verbosity_spec>
+```
+
+## Scope constraints
+
+Critical. GPT-5.4's primary failure mode is scope expansion—it adds features, refactors beyond the ask, and "helpfully" extends tasks. Fence it in hard.
+
+```
+<design_and_scope_constraints>
+- Implement EXACTLY and ONLY what the user requests. Nothing more.
+- No extra features, no "while I'm here" improvements, no UX embellishments.
+- Do NOT expand the task scope under any circumstances.
+- If you notice adjacent issues or opportunities, note them in your summary but DO NOT act on them.
+- If any instruction is ambiguous, choose the simplest valid interpretation.
+- Style aligned to the existing design system. Do not invent new patterns.
+- Do NOT invent colors, shadows, tokens, animations, or new UI elements unless explicitly requested.
+</design_and_scope_constraints>
+```
+
+## Verification requirements
+
+Critical. GPT-5.4 can declare tasks complete prematurely or claim success when the implementation is incorrect. Force explicit verification.
+
+```
+<verification_requirements>
+- Before declaring any task complete, perform explicit verification:
+  - Re-read the original requirements
+  - Check that every requirement is addressed in the actual code
+  - Run tests or validation steps if available
+  - Confirm the implementation actually works, don't assume
+- Do NOT claim success based on intent—verify actual outcomes.
+- If you cannot verify (no tests, can't run code), say so explicitly.
+- When reporting completion, include concrete evidence: test results, verified file contents, or explicit acknowledgment of what couldn't be verified.
+- If something failed or was skipped, say so clearly. Do not obscure failures.
+</verification_requirements>
+```
+
+## Context loading
+
+Always include. GPT-5.4 is faster and may skip reading in favor of acting. Force thoroughness.
+
+```
+<context_loading>
+- Read ALL files that will be modified—in full, not just the sections mentioned in the task.
+- Also read key files they import from or that depend on them.
+- Absorb surrounding patterns, naming conventions, error handling style, and architecture before writing any code.
+- Do not ask clarifying questions about things that are answerable by reading the codebase.
+- If modifying existing code, understand the full context before making changes.
+</context_loading>
+```
+
+## Plan-first mode
+
+Include for multi-file work, refactors, or tasks with ordering dependencies. GPT-5.4 produces good natural-language plans but may skip validation steps.
+
+```
+<plan_first>
+- Before writing any code, produce a brief implementation plan:
+  - Files to create vs. modify
+  - Implementation order and prerequisites
+  - Key design decisions and edge cases
+  - Acceptance criteria for "done"
+  - How you will verify each step
+- Execute the plan step by step. After each step, verify it worked before proceeding.
+- If the plan is provided externally, follow it faithfully—the job is execution, not second-guessing.
+- Do NOT skip verification steps even if you're confident.
+</plan_first>
+```
+
+## Long-context handling
+
+GPT-5.4 supports up to 1M tokens, but accuracy degrades beyond ~512K. Handle long inputs carefully.
+
+```
+<long_context_handling>
+- For inputs longer than ~10k tokens:
+  - First, produce a short internal outline of the key sections relevant to the task.
+  - Re-state the constraints explicitly before answering.
+  - Anchor claims to sections ("In the 'Data Retention' section...") rather than speaking generically.
+- If the answer depends on fine details (dates, thresholds, clauses), quote or paraphrase them.
+- For very long contexts (200K+ tokens):
+  - Be extra vigilant about accuracy—retrieval quality degrades.
+  - Cross-reference claims against multiple sections.
+  - Prefer citing specific locations over making sweeping statements.
+</long_context_handling>
+```
+
+## Tool usage
+
+```
+<tool_usage_rules>
+- Prefer tools over internal knowledge whenever:
+  - You need fresh or user-specific data (tickets, orders, configs, logs).
+  - You reference specific IDs, URLs, or document titles.
+- Parallelize independent tool calls when possible to reduce latency.
+- After any write/update tool call, verify the outcome—do not assume success.
+- After any write/update tool call, briefly restate:
+  - What changed
+  - Where (ID or path)
+  - Verification performed or why verification was skipped
+</tool_usage_rules>
+```
+
+## Backwards compatibility hedging
+
+GPT-5.4 tends to preserve old patterns and add compatibility shims. Use **"cutover"** to signal a clean break.
+
+Instead of:
+> "Rewrite this and don't worry about backwards compatibility"
+
+Say:
+> "This is a cutover. No backwards compatibility. Rewrite using only Python 3.12+ features and current best practices. Do not preserve legacy code, polyfills, or deprecated patterns."
+
+## Quick reference
+
+- **Constrain scope aggressively.** GPT-5.4 expands tasks beyond the ask. "ONLY what is requested, nothing more."
+- **Force verification.** Don't trust "done"—require evidence. "Verify before claiming complete."
+- **Use cutover language.** "Cutover," "no fallbacks," "exactly as specified" get cleaner results.
+- **Plan mode helps.** Explicit plan-first prompts ensure verification steps.
+- **Watch for false success claims.** In agent harnesses, add explicit validation steps. Don't let it self-report completion.
+- **Steer mid-task.** GPT-5.4 handles redirects well. Be direct: "Stop. That's out of scope." / "Verify that actually worked."
+- **Use domain jargon.** "Cutover," "golden-path," "no fallbacks," "domain split," "exactly as specified" trigger precise behavior.
+- **Long context degrades.** Above ~512K tokens, cross-reference claims and cite specific sections.
+- **Token efficiency is real.** 5.4 uses fewer tokens per problem—but verify it didn't skip steps to get there.
+
+## Example: implementation task prompt
+
+```
+<system>
+You are implementing a feature in an existing codebase. Follow these rules strictly.
+
+<design_and_scope_constraints>
+- Implement EXACTLY and ONLY what the user requests. Nothing more.
+- No extra features, no "while I'm here" improvements.
+- If you notice adjacent issues, note them in your summary but DO NOT act on them.
+</design_and_scope_constraints>
+
+<context_loading>
+- Read ALL files that will be modified—in full.
+- Also read key files they import from or depend on.
+- Absorb patterns before writing any code.
+</context_loading>
+
+<verification_requirements>
+- Before declaring complete, verify each requirement is addressed in actual code.
+- Run tests if available. If not, state what couldn't be verified.
+- Include concrete evidence of completion in your summary.
+</verification_requirements>
+
+<output_verbosity_spec>
+- Brief updates only on major phases or blockers.
+- Final summary: What changed, Where, Risks, Next steps.
+</output_verbosity_spec>
+</system>
+```
+
+## Example: code review prompt
+
+```
+<system>
+You are reviewing code changes. Be thorough but stay in scope.
+
+<context_loading>
+- Read every changed file in full, not just the diff hunks.
+- Also read files they import from and key dependents.
+</context_loading>
+
+<review_scope>
+- Review for: bugs, logic errors, race conditions, resource leaks, null hazards, error handling gaps, type mismatches, dead code, unused imports, pattern inconsistencies.
+- Fix issues you find with direct code edits.
+- Do NOT refactor or restructure code that wasn't flagged in the review.
+- If adjacent code looks problematic, note it but don't touch it.
+</review_scope>
+
+<verification_requirements>
+- After fixes, verify the code still works. Run tests if available.
+- In your summary, list what was found, what was fixed, and what couldn't be verified.
+</verification_requirements>
+</system>
+```

package/handoff-utils.ts

@@ -0,0 +1,92 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+import type { InteractiveShellConfig } from "./config.js";
+import type { InteractiveShellOptions, InteractiveShellResult } from "./types.js";
+import type { PtyTerminalSession } from "./pty-session.js";
+
+export function captureCompletionOutput(
+	session: PtyTerminalSession,
+	config: InteractiveShellConfig,
+): InteractiveShellResult["completionOutput"] {
+	const result = session.getTailLines({
+		lines: config.completionNotifyLines,
+		ansi: false,
+		maxChars: config.completionNotifyMaxChars,
+	});
+	return {
+		lines: result.lines,
+		totalLines: result.totalLinesInBuffer,
+		truncated: result.lines.length < result.totalLinesInBuffer || result.truncatedByChars,
+	};
+}
+
+export function captureTransferOutput(
+	session: PtyTerminalSession,
+	config: InteractiveShellConfig,
+): InteractiveShellResult["transferred"] {
+	const result = session.getTailLines({
+		lines: config.transferLines,
+		ansi: false,
+		maxChars: config.transferMaxChars,
+	});
+	return {
+		lines: result.lines,
+		totalLines: result.totalLinesInBuffer,
+		truncated: result.lines.length < result.totalLinesInBuffer || result.truncatedByChars,
+	};
+}
+
+export function maybeBuildHandoffPreview(
+	session: PtyTerminalSession,
+	when: "exit" | "detach" | "kill" | "timeout" | "transfer",
+	config: InteractiveShellConfig,
+	overrides?: Pick<InteractiveShellOptions, "handoffPreviewEnabled" | "handoffPreviewLines" | "handoffPreviewMaxChars">,
+): InteractiveShellResult["handoffPreview"] | undefined {
+	const enabled = overrides?.handoffPreviewEnabled ?? config.handoffPreviewEnabled;
+	if (!enabled) return undefined;
+	const lines = overrides?.handoffPreviewLines ?? config.handoffPreviewLines;
+	const maxChars = overrides?.handoffPreviewMaxChars ?? config.handoffPreviewMaxChars;
+	if (lines <= 0 || maxChars <= 0) return undefined;
+	const result = session.getTailLines({ lines, ansi: false, maxChars });
+	return { type: "tail", when, lines: result.lines };
+}
+
+export function maybeWriteHandoffSnapshot(
+	session: PtyTerminalSession,
+	when: "exit" | "detach" | "kill" | "timeout" | "transfer",
+	config: InteractiveShellConfig,
+	context: { command: string; cwd?: string },
+	overrides?: Pick<InteractiveShellOptions, "handoffSnapshotEnabled" | "handoffSnapshotLines" | "handoffSnapshotMaxChars">,
+): InteractiveShellResult["handoff"] | undefined {
+	const enabled = overrides?.handoffSnapshotEnabled ?? config.handoffSnapshotEnabled;
+	if (!enabled) return undefined;
+	const lines = overrides?.handoffSnapshotLines ?? config.handoffSnapshotLines;
+	const maxChars = overrides?.handoffSnapshotMaxChars ?? config.handoffSnapshotMaxChars;
+	if (lines <= 0 || maxChars <= 0) return undefined;
+
+	const baseDir = join(getAgentDir(), "cache", "interactive-shell");
+	mkdirSync(baseDir, { recursive: true });
+	const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+	const pid = session.pid;
+	const filename = `snapshot-${timestamp}-pid${pid}.log`;
+	const transcriptPath = join(baseDir, filename);
+	const tailResult = session.getTailLines({
+		lines,
+		ansi: config.ansiReemit,
+		maxChars,
+	});
+	const header = [
+		`# interactive-shell snapshot (${when})`,
+		`time: ${new Date().toISOString()}`,
+		`command: ${context.command}`,
+		`cwd: ${context.cwd ?? ""}`,
+		`pid: ${pid}`,
+		`exitCode: ${session.exitCode ?? ""}`,
+		`signal: ${session.signal ?? ""}`,
+		`lines: ${tailResult.lines.length} (requested ${lines}, maxChars ${maxChars})`,
+		"",
+	].join("\n");
+	writeFileSync(transcriptPath, header + tailResult.lines.join("\n") + "\n", { encoding: "utf-8" });
+	return { type: "snapshot", when, transcriptPath, linesWritten: tailResult.lines.length };
+}

package/headless-monitor.ts

@@ -1,13 +1,18 @@
+import { stripVTControlCharacters } from "node:util";
 import type { PtyTerminalSession } from "./pty-session.js";
 import type { InteractiveShellConfig } from "./config.js";
 
+/** Runtime options for monitoring a headless dispatch session. */
 export interface HeadlessMonitorOptions {
 	autoExitOnQuiet: boolean;
 	quietThreshold: number;
 	gracePeriod?: number;
 	timeout?: number;
+	/** Original session start time in ms since epoch, preserved when a foreground session moves headless. */
+	startedAt?: number;
 }
 
+/** Completion payload emitted when a headless dispatch session finishes. */
 export interface HeadlessCompletionInfo {
 	exitCode: number | null;
 	signal?: number;
@@ -21,7 +26,7 @@ export interface HeadlessCompletionInfo {
 }
 
 export class HeadlessDispatchMonitor {
-	readonly startTime = Date.now();
+	readonly startTime: number;
 	private _disposed = false;
 	private quietTimer: ReturnType<typeof setTimeout> | null = null;
 	private timeoutTimer: ReturnType<typeof setTimeout> | null = null;
@@ -38,8 +43,13 @@ export class HeadlessDispatchMonitor {
 		private options: HeadlessMonitorOptions,
 		private onComplete: (info: HeadlessCompletionInfo) => void,
 	) {
+		this.startTime = options.startedAt ?? Date.now();
 		this.subscribe();
 
+		if (options.autoExitOnQuiet) {
+			this.resetQuietTimer();
+		}
+
 		if (options.timeout && options.timeout > 0) {
 			this.timeoutTimer = setTimeout(() => {
 				this.handleCompletion(null, undefined, true);
@@ -57,9 +67,12 @@ export class HeadlessDispatchMonitor {
 
 	private subscribe(): void {
 		this.unsubscribe();
-		this.unsubData = this.session.addDataListener(() => {
+		this.unsubData = this.session.addDataListener((data) => {
 			if (this.options.autoExitOnQuiet) {
-				this.resetQuietTimer();
+				const visible = stripVTControlCharacters(data);
+				if (visible.trim().length > 0) {
+					this.resetQuietTimer();
+				}
 			}
 		});
 		this.unsubExit = this.session.addExitListener((exitCode, signal) => {