@aefree/pi-unity 0.9.2 → 0.10.0

package/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project follows semantic versioning for public package releases.
 
+## [0.10.0] - 2026-08-14
+
+### Changed
+
+- Added a configurable 1–86,400-second timeout to `unity_pipeline_eval`, forwarding it to both Unity CLI and the host process.
+- Handle Pipeline 0.5's explicitly rejected initial-settling `Server Busy` envelopes with bounded retries for connected recompiles and tests, while preserving no-retry handling for ambiguous responses.
+
+## [0.9.3] - 2026-08-10
+
+### Added
+
+- Added an optional `automated` parameter to `unity_open_editor`, forwarding Unity Editor's `-automated` flag through both Unity CLI and direct Editor launch paths.
+
 ## [0.9.2] - 2026-08-08
 
 ### Changed

package/README.md

@@ -34,16 +34,16 @@ Use these tools with an already-open exact Unity project copy that has a reachab
 - `unity_project_status` — inspect lockfiles, matching Unity processes, Pipeline reachability, package version, and advertised commands without launching Unity.
 - `unity_pipeline_recompile` — recompile through Pipeline with exact-copy preflight, bounded polling, and compact compiler evidence.
 - `unity_pipeline_run_tests` — run one focused EditMode or PlayMode selection with bounded polling and aggregate results.
-- `unity_pipeline_eval` — execute bounded project-specific C# through Pipeline's Roslyn REPL.
+- `unity_pipeline_eval` — execute bounded project-specific C# through Pipeline's Roslyn REPL. It accepts `timeoutSeconds` from 1–86,400 seconds; a timeout is uncertain and does not cancel or retry Editor work.
 - `unity_pipeline_inspect` — dispatch supported package-owned inspection commands and return structured evidence.
 
 Connected recompilation follows Unity's Script Changes While Playing policy and never preemptively sends `editor_stop`. Connected tests may exit Play Mode through advertised `editor_stop` when necessary, then verify Edit Mode before dispatch. Play Mode exit is allowed by default; `/unity-playmode-exit allow|disallow|status` controls the current session.
 
-A timeout is uncertain: work may still be running. The tools do not silently cancel, retry, launch another Editor, or switch to batchmode.
+A timeout is uncertain: work may still be running. The tools do not silently cancel, retry, launch another Editor, or switch to batchmode. The sole exception is Pipeline 0.5's explicit initial-settling `Server Busy` rejection for `unity_pipeline_recompile` and `unity_pipeline_run_tests`, which is known not to have dispatched a main-thread command and is retried only within the configured deadline.
 
 ### Editor and batchmode
 
-- `unity_open_editor` — open the Unity Editor GUI.
+- `unity_open_editor` — open the Unity Editor GUI. Pass `automated: true` to add the Unity Editor `-automated` flag; this is distinct from the Unity CLI's own `--non-interactive` option.
 - `unity_launch_batchmode` — run a bounded batchmode command through Unity CLI or the direct Editor executable.
 - `unity_run_test_batch` — run one isolated or report-producing Unity Test Framework platform with generated XML and log paths.
 - `unity_inspect_artifacts` — summarize existing Unity Test Framework XML and Unity logs without launching Unity.

package/index.ts

@@ -103,6 +103,7 @@ type UnityLauncherPreference = "auto" | "unity-cli" | "editor-executable";
 const OPEN_EDITOR_PARAMS = Type.Object({
   path: Type.Optional(Type.String({ description: "Unity project path, workspace copy root, or folder containing project copies." })),
   unityEditorPath: Type.Optional(Type.String({ description: "Optional explicit Unity executable path override." })),
+  automated: Type.Optional(Type.Boolean({ default: false, description: "Pass Unity Editor's -automated flag when opening the project. Defaults to false." })),
   launcher: LAUNCHER_SCHEMA,
 });
 
@@ -147,6 +148,7 @@ const PIPELINE_TEST_PARAMS = Type.Object({
 const PIPELINE_EVAL_PARAMS = Type.Object({
   path: Type.Optional(Type.String({ maxLength: 1000, description: "Unity project path, workspace copy root, or folder containing project copies." })),
   code: Type.String({ minLength: 1, maxLength: 4000, description: "Bounded C# source for advertised Pipeline eval. Roslyn compiles it on the connected Editor main thread; include an explicit return value when evidence is needed." }),
+  timeoutSeconds: Type.Optional(Type.Integer({ minimum: 1, maximum: 86400, default: 12, description: "Connected eval deadline in seconds (maximum 24 hours). A timeout is uncertain and does not retry or cancel Unity work." })),
 }, { additionalProperties: false });
 
 const PIPELINE_INSPECTION_PARAMS = Type.Object({
@@ -1469,7 +1471,7 @@ export default function freeUnityPi(pi: ExtensionAPI) {
       }, {
         execute: createPlanningUnityCliExecutor(pi),
         signal,
-        timeout: 12_000,
+        timeout: (params.timeoutSeconds ?? 12) * 1000,
       });
       throwIfAborted(signal);
       const text = result.outcome === "dispatched"
@@ -1578,7 +1580,7 @@ export default function freeUnityPi(pi: ExtensionAPI) {
   pi.registerTool({
     name: "unity_open_editor",
     label: "Unity Open Editor",
-    description: "Open the Unity Editor GUI for a Unity project copy.",
+    description: "Open the Unity Editor GUI for a Unity project copy, optionally passing Unity Editor's -automated flag.",
     promptSnippet: "Open the Unity Editor GUI for a resolved Unity project when the user explicitly asks for the editor to open.",
     promptGuidelines: [
       "Use this tool only when the user explicitly wants the Unity Editor GUI opened.",
@@ -1605,11 +1607,12 @@ export default function freeUnityPi(pi: ExtensionAPI) {
         launch = launchUnityCliOpenDetached(candidate.projectRoot, {
           editorVersion: candidate.unityVersion,
           editorPath: params.unityEditorPath,
+          automated: params.automated,
         });
       } else {
         await assertUnityProjectNotBusy(candidate.projectRoot);
         editorPath = await resolveUnityEditorPath(candidate.unityVersion, { overridePath: params.unityEditorPath });
-        launch = launchUnityEditorDetached(editorPath, candidate.projectRoot);
+        launch = launchUnityEditorDetached(editorPath, candidate.projectRoot, { automated: params.automated });
       }
       const text = buildEditorLaunchSummary(ctx.cwd, candidate, editorPath, discoveryWarning, launcher);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aefree/pi-unity",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "type": "module",
   "exports": {
     ".": "./index.ts"

package/skills/unity-pipeline-workflows/SKILL.md

@@ -16,7 +16,7 @@ Use one typed tool call for each supported connected operation:
 
 These tools resolve the exact copy, require advertised commands, inspect lifecycle state, dispatch once, validate identity, and poll internally with a fixed deadline. Do not recreate their wait loops with `bash`, `unity recompile_status`, or `unity test_status` calls.
 
-A timeout or malformed response is uncertain: the Unity operation may still be running. Do not cancel, retry, launch batchmode, close the Editor, or claim a result without a new user-authorized decision.
+A timeout or malformed response is uncertain: the Unity operation may still be running. Do not cancel, retry, launch batchmode, close the Editor, or claim a result without a new user-authorized decision. The only automatic retry is Pipeline 0.5's explicit initial-settling `Server Busy` response for `unity_pipeline_recompile` or `unity_pipeline_run_tests`, which confirms that a main-thread command was rejected before dispatch.
 
 ## Preconditions and boundaries
 
@@ -49,4 +49,4 @@ Normally call the typed tools, not raw CLI commands. If a typed tool is unavaila
 
 Use `unity_run_test_batch` for a closed project, intentional isolation/CI, category or multiple filters, or required NUnit XML/log evidence. State the reason for that route. Do not use batchmode as an automatic fallback after an uncertain connected dispatch.
 
-Use the typed compile/test tools when their polling and terminal evidence fit the task. Advertised Pipeline `eval` remains available through `unity_pipeline_eval` for bounded project-specific inspection or operations outside those typed workflows; it is an assistance surface, not a forbidden fallback or a substitute for the typed tools' completion protocol. Eval compiles arbitrary C# with Roslyn on the Editor main thread, so ordinary properties and local-variable snippets are valid; it is not expression-only or reliably statically read-only. Prefer typed tools for their stronger evidence, but let user intent and project guidance govern mutations. Lifecycle, persistent-setting, destructive, asset, scene-save, package, build, and test mutations require explicit authorization.
+Use the typed compile/test tools when their polling and terminal evidence fit the task. Advertised Pipeline `eval` remains available through `unity_pipeline_eval` for bounded project-specific inspection or operations outside those typed workflows; its `timeoutSeconds` range is 1–86,400 seconds, and a timeout remains uncertain without cancellation or retry. It is an assistance surface, not a forbidden fallback or a substitute for the typed tools' completion protocol. Eval compiles arbitrary C# with Roslyn on the Editor main thread, so ordinary properties and local-variable snippets are valid; it is not expression-only or reliably statically read-only. Prefer typed tools for their stronger evidence, but let user intent and project guidance govern mutations. Lifecycle, persistent-setting, destructive, asset, scene-save, package, build, and test mutations require explicit authorization.

package/src/unity-cli.ts

@@ -18,6 +18,8 @@ export type UnityCliLaunchOptions = {
   timeoutSeconds?: number;
   cliCommand?: string;
   useGraphics?: boolean;
+  /** Forward Unity Editor's -automated flag through `unity open --args`. */
+  automated?: boolean;
 };
 
 export type UnityCliPipelineInstance = {
@@ -80,6 +82,7 @@ function appendUnityCliEditorOptions(args: string[], options: UnityCliLaunchOpti
 export function createUnityCliOpenCommand(projectRoot: string, options: UnityCliLaunchOptions = {}): UnityCliCommand {
   const args = [...unityCliBaseArgs(), "open", projectRoot];
   appendUnityCliEditorOptions(args, options);
+  if (options.automated) args.push("--args", "-automated");
   return {
     command: resolveUnityCliCommand(options),
     args,

package/src/unity-core.ts

@@ -64,8 +64,13 @@ export function buildUnityEditorCandidates(
   ];
 }
 
-export function buildUnityOpenEditorArgs(projectRoot: string): string[] {
-  return ["-projectPath", projectRoot];
+export type UnityOpenEditorArgsOptions = {
+  /** Pass Unity Editor's -automated flag. */
+  automated?: boolean;
+};
+
+export function buildUnityOpenEditorArgs(projectRoot: string, options: UnityOpenEditorArgsOptions = {}): string[] {
+  return ["-projectPath", projectRoot, ...(options.automated ? ["-automated"] : [])];
 }
 
 export type UnityBatchmodeArgsOptions = {

package/src/unity-launch.ts

@@ -7,6 +7,7 @@ import {
   buildUnityOpenEditorArgs,
   normalizeUnityEditorOverride,
   type SupportedPlatform,
+  type UnityOpenEditorArgsOptions,
 } from "./unity-core";
 import { createUnityCliOpenCommand, type UnityCliLaunchOptions } from "./unity-cli";
 
@@ -47,8 +48,12 @@ export async function resolveUnityEditorPath(
   );
 }
 
-export function launchUnityEditorDetached(editorPath: string, projectRoot: string): { pid: number | undefined; args: string[]; command: string } {
-  const args = buildUnityOpenEditorArgs(projectRoot);
+export function launchUnityEditorDetached(
+  editorPath: string,
+  projectRoot: string,
+  options: UnityOpenEditorArgsOptions = {},
+): { pid: number | undefined; args: string[]; command: string } {
+  const args = buildUnityOpenEditorArgs(projectRoot, options);
   const child = spawn(editorPath, args, {
     detached: true,
     stdio: "ignore",

package/src/unity-pipeline.ts

@@ -145,6 +145,17 @@ function diagnostics(result: RecordValue): string[] {
   });
   return [...new Set(values)].slice(0, UNITY_PIPELINE_MAX_DIAGNOSTICS);
 }
+/** True only for Pipeline 0.5's explicit rejected outer envelope, before a main-thread command is dispatched. */
+export function isUnityPipelineInitialSettlingBusy(output: string): boolean {
+  let outer: RecordValue | undefined;
+  try { outer = record(JSON.parse(output)); } catch { return false; }
+  const data = record(outer?.data);
+  return outer?.success === false
+    && string(field(data ?? {}, "error"))?.toLowerCase() === "server busy"
+    && statusOf(data ?? {}) === "busy"
+    && field(data ?? {}, "retryable") === true;
+}
+
 export function normalizeUnityPipelineCompile(output: string): NormalizedCompile {
   const parsed = parseUnityPipelineEnvelope(output);
   if (parsed.malformed) return { state: "uncertain", diagnostics: [], failed: false };
@@ -316,6 +327,19 @@ async function executeCommand(deps: PipelineDependencies, projectRoot: string, c
   if (deadline !== undefined) ensureBeforeDeadline(deadline, now, command);
   return result;
 }
+async function dispatchMainThreadCommand(deps: PipelineDependencies, projectRoot: string, command: "recompile" | "run_tests", args: string[], operation: string, signal: AbortSignal | undefined, deadline: number, now: () => number, sleep: (milliseconds: number, signal?: AbortSignal) => Promise<void>): Promise<UnityCliExecResult> {
+  for (let attempt = 0; ; attempt += 1) {
+    const response = await executeCommand(deps, projectRoot, command, args, signal, deadline, now);
+    if (!isUnityPipelineInitialSettlingBusy(response.stdout)) return response;
+    const remaining = deadline - now();
+    if (remaining <= 0) throw new Error(`Unity Pipeline server remained busy while settling; ${operation} was not started before the deadline.`);
+    const delay = Math.min(UNITY_PIPELINE_BACKOFF_SECONDS[Math.min(attempt, UNITY_PIPELINE_BACKOFF_SECONDS.length - 1)]! * 1000, remaining);
+    await sleep(delay, signal);
+    throwIfAborted(signal);
+    if (now() >= deadline) throw new Error(`Unity Pipeline server remained busy while settling; ${operation} was not started before the deadline.`);
+  }
+}
+
 async function requirePreflight(deps: PipelineDependencies, projectRoot: string, unityVersion: string, commands: string[], operation: "recompile" | "tests", signal: AbortSignal | undefined, deadline: number, now: () => number, allowAutonomousExitPlayMode = true): Promise<{ capabilities: UnityCliProjectCapabilities; exitedPlayMode: boolean; playModeHandling: UnityPipelinePlayModeHandling; scriptChangesWhilePlaying?: UnityScriptChangesWhilePlayingPolicy }> {
   const capabilities = await inspectWithDeadline(deps, projectRoot, unityVersion, signal, deadline, now, "preflight");
   const error = capabilityError(capabilities, commands); if (error) throw new Error(error);
@@ -404,7 +428,7 @@ export async function runUnityPipelineRecompile(request: UnityPipelineCompileReq
   const lifecyclePrefix = playModeOutcomeText(preflight);
   ensureBeforeDeadline(deadline, now, "recompile before dispatch");
   throwIfAborted(signal);
-  const dispatched = await executeCommand(deps, projectRoot, "recompile", [], signal, deadline, now);
+  const dispatched = await dispatchMainThreadCommand(deps, projectRoot, "recompile", [], "recompile", signal, deadline, now, sleep);
   if (dispatched.error) throw new Error("Unity Pipeline recompile dispatch failed; operation may not have started.");
   let state = normalizeUnityPipelineCompile(dispatched.stdout);
   if (state.state === "uncertain") throw new Error("Unity Pipeline recompile dispatch returned malformed or uncertain evidence; operation may have started.");
@@ -421,6 +445,7 @@ export async function runUnityPipelineRecompile(request: UnityPipelineCompileReq
     if (identityState === "temporary_disconnect") continue;
     const response = await executeCommand(deps, projectRoot, "recompile_status", [], signal, deadline, now);
     if (response.error) continue; // Domain reload can briefly disconnect the same exact copy.
+    if (isUnityPipelineInitialSettlingBusy(response.stdout)) continue;
     state = normalizeUnityPipelineCompile(response.stdout);
     if (state.state === "failed") throw new Error(`Unity recompile failed: ${state.diagnostics.join("; ") || "compiler failure reported"}`);
     if (state.state === "completed" || state.state === "up_to_date") return { text: `${lifecyclePrefix}Unity recompile completed for ${projectRoot} in ${elapsed(start, now).toFixed(1)}s; 0 compiler errors.`,  details: { projectRoot, operation: "recompile", terminalState: state.state, elapsedSeconds: elapsed(start, now), compilationTriggered: true, ...playModeDetails(preflight) } };
@@ -448,7 +473,7 @@ export async function runUnityPipelineTests(request: UnityPipelineTestRequest, d
   }
   const args = ["--mode", request.testPlatform === "EditMode" ? "editor" : "playmode", ...(request.testFilter ? ["--filter", request.testFilter, "--filter_type", "testName"] : []), "--async_tests", "true"];
   ensureBeforeDeadline(deadline, now, "tests before dispatch"); throwIfAborted(signal);
-  const dispatched = await executeCommand(deps, projectRoot, "run_tests", args, signal, deadline, now);
+  const dispatched = await dispatchMainThreadCommand(deps, projectRoot, "run_tests", args, "tests", signal, deadline, now, sleep);
   if (dispatched.error) throw new Error("Unity Pipeline test dispatch failed; test run may not have started.");
   let state = normalizeUnityPipelineTest(dispatched.stdout);
   if (state.state === "uncertain" || state.state === "inactive") throw new Error("Unity Pipeline test dispatch returned inactive, malformed, or uncertain evidence; test run may not have started.");
@@ -473,6 +498,7 @@ export async function runUnityPipelineTests(request: UnityPipelineTestRequest, d
     if (identityState === "temporary_disconnect") continue;
     const response = await executeCommand(deps, projectRoot, "test_status", [], signal, deadline, now);
     if (response.error) continue;
+    if (isUnityPipelineInitialSettlingBusy(response.stdout)) continue;
     state = normalizeUnityPipelineTest(response.stdout);
     if (!checkCorrelation(expected, state.correlation)) throw new Error("Unity Pipeline test status was displaced by a different run; operation state is uncertain.");
     if (state.state === "failed" || state.state === "cancelled") throw new Error(`Unity ${request.testPlatform} tests failed: ${state.failures.join("; ") || state.state}.`);