@aibyzero/byz 0.1.5 → 0.1.6

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.1.6 - 2026-08-28
+
+### Added
+
+- Added same-session `/fast` hot switching with reversible model and thinking state, explicit user choices taking priority, and no changes to the active workflow or conversation ([#22](https://github.com/kingxiaozhe/byz/pull/22)).
+- Added opt-in `/prewalk` one-time handoff after the first successful built-in workspace edit or write, reusing the authenticated Fast target without changing the conversation or workflow ([#23](https://github.com/kingxiaozhe/byz/pull/23)).
+
 ## 0.1.5 - 2026-08-28
 
 ### Fixed

package/README.md

@@ -56,6 +56,39 @@ An explicit `--model` or `--thinking` option always wins. Continuing or resuming
 an existing session keeps that session's model and applies the Fast thinking
 default. Normal `byz` runs ignore `BYZ_FAST_MODEL` and remain unchanged.
 
+Inside an interactive session, Fast can be changed without restarting BYZ or
+starting a new conversation:
+
+```text
+/fast
+/fast on
+/fast off
+/fast status
+```
+
+`/fast on` snapshots the current model and thinking, then applies the same Fast
+defaults. `/fast off` restores that snapshot. The active workflow, conversation,
+session, skills, prompts, and tools do not change. Explicitly selecting a model
+or thinking level exits Fast and keeps that explicit choice. BYZ rejects Fast
+state changes while the agent is running, and an unavailable or unauthenticated
+configured model leaves the current state unchanged.
+
+## Prewalk
+
+Arm a one-time handoff when the current model should understand the task and perform the first successful workspace edit before Fast continues:
+
+```text
+/prewalk
+/prewalk status
+/prewalk cancel
+```
+
+`/prewalk` is available only in an interactive, trusted, idle session. It resolves and authenticates the same target used by Fast before arming. If `BYZ_FAST_MODEL` is unset, the current authenticated model remains selected and only thinking changes to `low` after the handoff.
+
+Only the first successful Pi built-in `edit` or `write` whose real target remains inside the current workspace consumes the armed state. Read-only tools, failed writes, extension tools with the same name, and file or directory symlink escapes do not trigger it. Parallel tool results are checked serially and can consume the state only once.
+
+Prewalk preserves the current conversation, session, workflow, skills, prompts, and tools. It does not add another model call for planning. An explicit model or thinking selection cancels an armed Prewalk and keeps the user's choice. Enabling Fast also cancels it; Prewalk refuses to arm when Fast is already active.
+
 ## Workflows
 
 ```bash

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
-import { prepareFastRuntimeArgs } from "./fast.js";
+import { createFastSessionController, prepareFastRuntimeArgs, selectFastRuntimeArgs } from "./fast.js";
+import { createPrewalkExtension } from "./prewalk.js";
 import { main } from "./runtime/bundle/index.js";
 import { handleByzUpdate } from "./update.js";
 import { createWorkflowSwitchExtension, shouldEnableWorkflowSwitch, shouldLoadWorkflow } from "./workflow-switch.js";
@@ -28,6 +29,7 @@ try {
 	if (isRootHelp) {
 		console.error("BYZ updates: byz update (npm-managed global installations only)");
 		console.error("BYZ Fast: --fast (thinking=low; optional model: BYZ_FAST_MODEL)");
+		console.error("BYZ Prewalk: /prewalk (one-time handoff after the first successful workspace edit/write)");
 		console.error("BYZ workflows: --workflow <cm|cm-plugin|none> (default: BYZ_WORKFLOW or cm)");
 		console.error(
 			"Commands: byz workflow list | byz workflow status [cm|cm-plugin|none] | byz workflow check <cm|cm-plugin>",
@@ -40,11 +42,11 @@ try {
 		// BYZ release metadata and package target stay independent from Pi.
 	} else {
 		const loadWorkflow = shouldLoadWorkflow(commandArgs);
-		const runtimeArgs = loadWorkflow ? fastRuntime.args : fastRuntime.commandArgs;
 		const isInteractive = shouldEnableWorkflowSwitch(commandArgs, {
 			stdinIsTTY: process.stdin.isTTY,
 			stdoutIsTTY: process.stdout.isTTY,
 		});
+		const runtimeArgs = selectFastRuntimeArgs(fastRuntime, { isInteractive, loadWorkflow });
 		if (fastRuntime.enabled && loadWorkflow && isInteractive) {
 			console.error(
 				`BYZ Fast: model=${fastRuntime.model}, thinking=${fastRuntime.thinking}, workflow=${parsedWorkflow.workflowId}`,
@@ -60,7 +62,18 @@ try {
 				initialWorkflowId: parsedRuntimeWorkflow.workflowId,
 				resolveResources,
 			});
-			await main(parsedRuntimeWorkflow.forwardedArgs, { byzWorkflowExtensionFactory: workflowExtension });
+			const fastController = createFastSessionController({
+				initiallyEnabled: fastRuntime.enabled,
+				initialUseConfiguredModel: fastRuntime.useConfiguredModel,
+				initialUseLowThinking: fastRuntime.useLowThinking,
+			});
+			const prewalkExtension = createPrewalkExtension({ fastController });
+			const byzExtension = (pi) => {
+				workflowExtension(pi);
+				fastController.extension(pi);
+				prewalkExtension(pi);
+			};
+			await main(parsedRuntimeWorkflow.forwardedArgs, { byzWorkflowExtensionFactory: byzExtension });
 		} else {
 			const prepared = await prepareWorkflowRuntimeArgs(runtimeArgs, { load: loadWorkflow });
 			await main(prepared.args);

package/dist/fast-session.js

@@ -0,0 +1,276 @@
+const FAST_COMMAND_USAGE = "Usage: /fast [on|off|status]";
+
+function parseFastModelReference(value) {
+	const separatorIndex = value.indexOf("/");
+	if (separatorIndex <= 0 || separatorIndex === value.length - 1) return undefined;
+	return {
+		provider: value.slice(0, separatorIndex),
+		modelId: value.slice(separatorIndex + 1),
+	};
+}
+
+function formatModel(model) {
+	return model ? `${model.provider}/${model.id}` : "none";
+}
+
+function modelsMatch(left, right) {
+	return left?.provider === right?.provider && left?.id === right?.id;
+}
+
+export function createFastSessionController({
+	env = process.env,
+	initiallyEnabled = false,
+	initialUseConfiguredModel = true,
+	initialUseLowThinking = true,
+} = {}) {
+	let active = false;
+	let snapshot;
+	let internalTransition = false;
+	let currentThinkingTransition;
+	let pi;
+	const ignoredThinkingTransitions = [];
+	const activeListeners = new Set();
+	const explicitSelectionListeners = new Set();
+
+	function notifyStatus(ctx) {
+		ctx.ui.notify(
+			`Fast: ${active ? "on" : "off"}; model=${formatModel(ctx.model)}; thinking=${pi.getThinkingLevel()}`,
+			"info",
+		);
+	}
+
+	async function emitListeners(listeners, event, ctx) {
+		for (const listener of listeners) await listener(event, ctx);
+	}
+
+	async function exitForExplicitSelection(event, ctx) {
+		if (internalTransition) return;
+		if (active) {
+			active = false;
+			snapshot = undefined;
+			await emitListeners(activeListeners, false, ctx);
+		}
+		await emitListeners(explicitSelectionListeners, event, ctx);
+	}
+
+	async function handleThinkingSelection(event, ctx) {
+		if (
+			currentThinkingTransition &&
+			event.previousLevel === currentThinkingTransition.previousLevel &&
+			event.level === pi.getThinkingLevel()
+		) {
+			currentThinkingTransition.consumed = true;
+			return;
+		}
+		const ignoredIndex = ignoredThinkingTransitions.findIndex(
+			(transition) => transition.previousLevel === event.previousLevel && transition.level === event.level,
+		);
+		if (ignoredIndex !== -1) {
+			ignoredThinkingTransitions.splice(ignoredIndex, 1);
+			return;
+		}
+		await exitForExplicitSelection(event, ctx);
+	}
+
+	function beginThinkingTransition() {
+		const transition = {
+			previousLevel: pi.getThinkingLevel(),
+			level: pi.getThinkingLevel(),
+			consumed: false,
+		};
+		currentThinkingTransition = transition;
+		return transition;
+	}
+
+	function finishThinkingTransition(transition) {
+		transition.level = pi.getThinkingLevel();
+		currentThinkingTransition = undefined;
+		if (!transition.consumed && transition.level !== transition.previousLevel) {
+			ignoredThinkingTransitions.push(transition);
+		}
+	}
+
+	function setThinkingInternally(level) {
+		if (pi.getThinkingLevel() === level) return;
+		const transition = beginThinkingTransition();
+		try {
+			pi.setThinkingLevel(level);
+		} finally {
+			finishThinkingTransition(transition);
+		}
+	}
+
+	async function setModelInternally(model) {
+		const transition = beginThinkingTransition();
+		try {
+			return await pi.setModel(model);
+		} finally {
+			finishThinkingTransition(transition);
+		}
+	}
+
+	function resolveTarget(
+		ctx,
+		{ requireAuth = false, requireModel = false, useConfiguredModel = true, useLowThinking = true } = {},
+	) {
+		const configuredModel = useConfiguredModel ? env.BYZ_FAST_MODEL?.trim() : undefined;
+		let model = ctx.model;
+		if (configuredModel) {
+			const reference = parseFastModelReference(configuredModel);
+			if (!reference) {
+				ctx.ui.notify(`Invalid BYZ_FAST_MODEL "${configuredModel}". Expected provider/model.`, "error");
+				return undefined;
+			}
+			model = ctx.modelRegistry.find(reference.provider, reference.modelId);
+			if (!model) {
+				ctx.ui.notify(`Fast model "${configuredModel}" was not found.`, "error");
+				return undefined;
+			}
+			if (!ctx.modelRegistry.hasConfiguredAuth(model)) {
+				ctx.ui.notify(`Fast model "${configuredModel}" has no configured authentication.`, "error");
+				return undefined;
+			}
+			if (!ctx.model) {
+				ctx.ui.notify("Fast cannot preserve the current model because no model is selected.", "error");
+				return undefined;
+			}
+		}
+		if (!model && requireModel) {
+			ctx.ui.notify("Fast cannot preserve the current model because no model is selected.", "error");
+			return undefined;
+		}
+		if (model && requireAuth && !ctx.modelRegistry.hasConfiguredAuth(model)) {
+			ctx.ui.notify(`Fast model "${formatModel(model)}" has no configured authentication.`, "error");
+			return undefined;
+		}
+		return {
+			configuredModel,
+			model,
+			thinking: useLowThinking ? "low" : pi.getThinkingLevel(),
+		};
+	}
+
+	async function applyTarget(ctx, target) {
+		internalTransition = true;
+		try {
+			if (target.model && !modelsMatch(ctx.model, target.model)) {
+				const changed = await setModelInternally(target.model);
+				if (!changed) {
+					ctx.ui.notify(`Fast model "${formatModel(target.model)}" has no configured authentication.`, "error");
+					return false;
+				}
+			}
+			setThinkingInternally(target.thinking);
+			return true;
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			ctx.ui.notify(`Fast target could not be applied: ${message}`, "error");
+			return false;
+		} finally {
+			internalTransition = false;
+		}
+	}
+
+	async function enable(ctx, { useConfiguredModel = true, useLowThinking = true } = {}) {
+		if (!ctx.isIdle()) {
+			ctx.ui.notify("Fast cannot change while the agent is busy.", "warning");
+			return;
+		}
+		if (active) {
+			notifyStatus(ctx);
+			return;
+		}
+
+		const target = resolveTarget(ctx, { useConfiguredModel, useLowThinking });
+		if (!target) return;
+		const nextSnapshot = {
+			model: ctx.model,
+			thinking: pi.getThinkingLevel(),
+		};
+		if (!(await applyTarget(ctx, target))) return;
+		snapshot = nextSnapshot;
+		active = true;
+		await emitListeners(activeListeners, true, ctx);
+		notifyStatus(ctx);
+	}
+
+	async function disable(ctx) {
+		if (!ctx.isIdle()) {
+			ctx.ui.notify("Fast cannot change while the agent is busy.", "warning");
+			return;
+		}
+		if (!active || !snapshot) {
+			notifyStatus(ctx);
+			return;
+		}
+
+		const originalTarget = { model: snapshot.model, thinking: snapshot.thinking };
+		if (!(await applyTarget(ctx, originalTarget))) return;
+		active = false;
+		snapshot = undefined;
+		await emitListeners(activeListeners, false, ctx);
+		notifyStatus(ctx);
+	}
+
+	function extension(extensionApi) {
+		pi = extensionApi;
+
+		pi.registerCommand("fast", {
+			description: "Switch Fast mode for the current session",
+			handler: async (args, ctx) => {
+				const action = args.trim().toLowerCase() || "status";
+				if (action === "status") {
+					notifyStatus(ctx);
+					return;
+				}
+				if (action === "on") {
+					await enable(ctx);
+					return;
+				}
+				if (action === "off") {
+					await disable(ctx);
+					return;
+				}
+				ctx.ui.notify(FAST_COMMAND_USAGE, "warning");
+			},
+		});
+
+		pi.on("model_select", exitForExplicitSelection);
+		pi.on("thinking_level_select", handleThinkingSelection);
+		if (initiallyEnabled) {
+			pi.on("session_start", async (_event, ctx) => {
+				await enable(ctx, {
+					useConfiguredModel: initialUseConfiguredModel,
+					useLowThinking: initialUseLowThinking,
+				});
+			});
+		}
+	}
+
+	return {
+		applyTarget,
+		extension,
+		formatTarget(target) {
+			return formatModel(target.model);
+		},
+		getThinkingLevel() {
+			return pi.getThinkingLevel();
+		},
+		isActive() {
+			return active;
+		},
+		onActiveChange(listener) {
+			activeListeners.add(listener);
+			return () => activeListeners.delete(listener);
+		},
+		onExplicitSelection(listener) {
+			explicitSelectionListeners.add(listener);
+			return () => explicitSelectionListeners.delete(listener);
+		},
+		resolveTarget,
+	};
+}
+
+export function createFastSwitchExtension(options) {
+	return createFastSessionController(options).extension;
+}

package/dist/fast.js

@@ -1,5 +1,7 @@
 import { getActiveByzOptionIndexes } from "./workflow-switch.js";
 
+export { createFastSessionController, createFastSwitchExtension } from "./fast-session.js";
+
 const SESSION_OPTIONS = new Set(["--continue", "-c", "--resume", "-r", "--session", "--session-id", "--fork"]);
 const THINKING_SUFFIX_PATTERN = /:(off|minimal|low|medium|high|xhigh|max)$/;
 
@@ -63,5 +65,12 @@ export function prepareFastRuntimeArgs(args, env = process.env) {
 		enabled: true,
 		model: explicitModel ?? (resumesSession ? "session" : configuredModel || "default"),
 		thinking: explicitThinking ?? modelThinking ?? "low",
+		useConfiguredModel: !hasModelOption && !resumesSession,
+		useLowThinking: !hasThinkingOption && !modelThinking,
 	};
 }
+
+export function selectFastRuntimeArgs(fastRuntime, { isInteractive, loadWorkflow }) {
+	if (isInteractive) return fastRuntime.commandArgs;
+	return loadWorkflow ? fastRuntime.args : fastRuntime.commandArgs;
+}

package/dist/prewalk.js

@@ -0,0 +1,150 @@
+import { realpath } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+
+const PREWALK_COMMAND_USAGE = "Usage: /prewalk [cancel|status]";
+const WRITE_TOOL_NAMES = new Set(["edit", "write"]);
+
+function hasBuiltinWriteTools(pi) {
+	const tools = new Map(pi.getAllTools().map((tool) => [tool.name, tool]));
+	return [...WRITE_TOOL_NAMES].every((name) => {
+		const sourceInfo = tools.get(name)?.sourceInfo;
+		return sourceInfo?.source === "builtin" && sourceInfo.path === `<builtin:${name}>`;
+	});
+}
+
+async function isWorkspacePath(cwd, inputPath) {
+	if (typeof inputPath !== "string" || inputPath.length === 0) return false;
+	try {
+		const [workspaceRoot, targetPath] = await Promise.all([realpath(cwd), realpath(resolve(cwd, inputPath))]);
+		const relativePath = relative(workspaceRoot, targetPath);
+		return (
+			relativePath.length > 0 &&
+			relativePath !== ".." &&
+			!relativePath.startsWith(`..${sep}`) &&
+			!isAbsolute(relativePath)
+		);
+	} catch {
+		return false;
+	}
+}
+
+export function createPrewalkExtension({ fastController }) {
+	if (!fastController) throw new Error("Prewalk requires the Fast session controller.");
+
+	return function prewalkExtension(pi) {
+		let state = "idle";
+		let target;
+		let candidateQueue = Promise.resolve();
+
+		function reset() {
+			state = "idle";
+			target = undefined;
+		}
+
+		function notifyStatus(ctx) {
+			if (state === "armed" && target) {
+				ctx.ui.notify(
+					`Prewalk: armed; target=${fastController.formatTarget(target)}; thinking=${target.thinking}`,
+					"info",
+				);
+				return;
+			}
+			ctx.ui.notify(`Prewalk: ${state === "switching" ? "switching" : "not armed"}.`, "info");
+		}
+
+		function cancel(ctx, message = "Prewalk: canceled.") {
+			if (state !== "armed") {
+				ctx.ui.notify("Prewalk: not armed.", "info");
+				return false;
+			}
+			reset();
+			ctx.ui.notify(message, "info");
+			return true;
+		}
+
+		function arm(ctx) {
+			if (!ctx.isIdle()) {
+				ctx.ui.notify("Prewalk cannot arm while the agent is busy.", "warning");
+				return;
+			}
+			if (!ctx.isProjectTrusted()) {
+				ctx.ui.notify("Prewalk requires a trusted project.", "warning");
+				return;
+			}
+			if (fastController.isActive()) {
+				ctx.ui.notify("Prewalk cannot arm while Fast is already on.", "warning");
+				return;
+			}
+			if (state === "armed") {
+				ctx.ui.notify("Prewalk is already armed.", "info");
+				return;
+			}
+			if (!hasBuiltinWriteTools(pi)) {
+				ctx.ui.notify("Prewalk requires the built-in edit and write tools.", "warning");
+				return;
+			}
+			const nextTarget = fastController.resolveTarget(ctx, { requireAuth: true, requireModel: true });
+			if (!nextTarget) return;
+			target = nextTarget;
+			state = "armed";
+			notifyStatus(ctx);
+		}
+
+		async function considerToolResult(event, ctx) {
+			if (state !== "armed" || !target) return;
+			if (event.isError || !WRITE_TOOL_NAMES.has(event.toolName)) return;
+			if (!hasBuiltinWriteTools(pi)) return;
+			if (!(await isWorkspacePath(ctx.cwd, event.input?.path))) return;
+			if (state !== "armed" || !target) return;
+
+			const consumedTarget = target;
+			state = "switching";
+			target = undefined;
+			const applied = await fastController.applyTarget(ctx, consumedTarget);
+			reset();
+			if (applied) {
+				ctx.ui.notify(
+					`Prewalk: handed off to ${fastController.formatTarget(consumedTarget)}; thinking=${fastController.getThinkingLevel()}.`,
+					"info",
+				);
+				return;
+			}
+			ctx.ui.notify("Prewalk: handoff failed and was canceled.", "error");
+		}
+
+		pi.registerCommand("prewalk", {
+			description: "Arm a one-time handoff to the Fast target after the first successful write",
+			handler: async (args, ctx) => {
+				const action = args.trim().toLowerCase();
+				if (!action) {
+					arm(ctx);
+					return;
+				}
+				if (action === "cancel") {
+					cancel(ctx);
+					return;
+				}
+				if (action === "status") {
+					notifyStatus(ctx);
+					return;
+				}
+				ctx.ui.notify(PREWALK_COMMAND_USAGE, "warning");
+			},
+		});
+
+		pi.on("tool_result", (event, ctx) => {
+			candidateQueue = candidateQueue.then(
+				() => considerToolResult(event, ctx),
+				() => considerToolResult(event, ctx),
+			);
+			return candidateQueue;
+		});
+
+		fastController.onExplicitSelection((_event, ctx) => {
+			if (state === "armed") cancel(ctx, "Prewalk: canceled after an explicit model or thinking change.");
+		});
+		fastController.onActiveChange((active, ctx) => {
+			if (active && state === "armed") cancel(ctx, "Prewalk: canceled because Fast was enabled.");
+		});
+	};
+}