@aefree/pi-unity 0.9.0

package/src/optional-integration-rendezvous.ts

@@ -0,0 +1,124 @@
+/**
+ * Minimal adapter for the published capability-registry global protocol.
+ *
+ * Optional Pi packages have independent Node module roots, so provider packages
+ * must rendezvous through the protocol's documented `globalThis[Symbol.for()]`
+ * root rather than importing their contract from pi-unity's module root. This
+ * adapter only manages pi-unity's known-valid records; schema validation remains
+ * owned by each consuming package's contract.
+ */
+const ROOT_PROTOCOL = "@aefree/pi-capability-registry/root";
+const ROOT_PROTOCOL_VERSION = 1;
+
+export type OptionalRegistrationToken = Readonly<{
+  registryKey: string;
+  contractVersion: 1;
+  scope: object;
+  ownerKey: string;
+  id: string;
+  nonce: number;
+}>;
+
+type StoredRecord = Readonly<{ nonce: number; record: Readonly<Record<string, unknown>> }>;
+type ScopedState = { sequence: number; records: Map<string, StoredRecord> };
+type VersionState = { version: 1; scopes: WeakMap<object, ScopedState> };
+type RegistryRoot = { protocol: string; protocolVersion: number; registryKey: string; versions: Map<unknown, unknown> };
+
+export type OptionalIntegrationRegistryV1 = Readonly<{
+  register: (scope: object, record: Readonly<Record<string, unknown>>) => OptionalRegistrationToken;
+  unregister: (token: OptionalRegistrationToken) => boolean;
+}>;
+
+export function isOptionalIntegrationActive(pi: { getActiveTools?: () => string[] }, toolName: string): boolean {
+  return pi.getActiveTools?.().includes(toolName) ?? false;
+}
+
+/**
+ * Returns no registry when the owning integration is absent. If its advertised
+ * tool is present, create or validate that integration's actual global contract
+ * root. A malformed root is an installed/broken contract and throws visibly.
+ */
+export function createOptionalIntegrationRegistryV1(
+  registryKey: string,
+  integrationName: string,
+): OptionalIntegrationRegistryV1 {
+  const globalRecord = globalThis as typeof globalThis & Record<symbol, unknown>;
+  const symbol = Symbol.for(registryKey);
+  let candidate = globalRecord[symbol];
+  if (candidate === undefined) {
+    candidate = {
+      protocol: ROOT_PROTOCOL,
+      protocolVersion: ROOT_PROTOCOL_VERSION,
+      registryKey,
+      versions: new Map(),
+    } satisfies RegistryRoot;
+    globalRecord[symbol] = candidate;
+  }
+  const root = assertRegistryRoot(candidate, registryKey, integrationName);
+  let stateCandidate = root.versions.get(1);
+  if (stateCandidate === undefined) {
+    stateCandidate = { version: 1, scopes: new WeakMap<object, ScopedState>() } satisfies VersionState;
+    root.versions.set(1, stateCandidate);
+  }
+  const version = assertVersionState(stateCandidate, registryKey, integrationName);
+
+  return Object.freeze({
+    register(scope, record) {
+      if ((typeof scope !== "object" && typeof scope !== "function") || scope === null) {
+        throw new TypeError(`${integrationName} contract requires a session scope object.`);
+      }
+      const owner = record.owner as Record<string, unknown> | undefined;
+      if (typeof record.id !== "string" || typeof owner?.packageName !== "string" || typeof owner.packageRoot !== "string") {
+        throw new TypeError(`pi-unity attempted an invalid ${integrationName} contract registration.`);
+      }
+      let scoped = version.scopes.get(scope);
+      if (scoped === undefined) {
+        scoped = { sequence: 0, records: new Map() };
+        version.scopes.set(scope, scoped);
+      }
+      const ownerKey = `${owner.packageName}\0${owner.packageRoot}\0${record.id}`;
+      for (const current of scoped.records.values()) {
+        if (current.record.id === record.id && current.record.owner !== owner && ownerKeyFor(current.record) !== ownerKey) {
+          throw new TypeError(`Provider id '${record.id}' conflicts in ${integrationName} contract '${registryKey}'.`);
+        }
+      }
+      const nonce = scoped.sequence + 1;
+      scoped.records.set(ownerKey, { nonce, record });
+      scoped.sequence = nonce;
+      return Object.freeze({ registryKey, contractVersion: 1, scope, ownerKey, id: record.id, nonce });
+    },
+    unregister(token) {
+      if (!token || token.registryKey !== registryKey || token.contractVersion !== 1) return false;
+      const scoped = version.scopes.get(token.scope);
+      const current = scoped?.records.get(token.ownerKey);
+      if (current === undefined || current.nonce !== token.nonce || current.record.id !== token.id) return false;
+      scoped!.records.delete(token.ownerKey);
+      return true;
+    },
+  });
+}
+
+function ownerKeyFor(record: Readonly<Record<string, unknown>>): string {
+  const owner = record.owner as Record<string, unknown>;
+  return `${String(owner.packageName)}\0${String(owner.packageRoot)}\0${String(record.id)}`;
+}
+
+function assertRegistryRoot(value: unknown, registryKey: string, integrationName: string): RegistryRoot {
+  if (value === null || typeof value !== "object") throw brokenContract(integrationName, registryKey);
+  const root = value as Partial<RegistryRoot>;
+  if (root.protocol !== ROOT_PROTOCOL || root.protocolVersion !== ROOT_PROTOCOL_VERSION || root.registryKey !== registryKey || !(root.versions instanceof Map)) {
+    throw brokenContract(integrationName, registryKey);
+  }
+  return root as RegistryRoot;
+}
+
+function assertVersionState(value: unknown, registryKey: string, integrationName: string): VersionState {
+  if (value === null || typeof value !== "object") throw brokenContract(integrationName, registryKey);
+  const state = value as Partial<VersionState>;
+  if (state.version !== 1 || !(state.scopes instanceof WeakMap)) throw brokenContract(integrationName, registryKey);
+  return state as VersionState;
+}
+
+function brokenContract(integrationName: string, registryKey: string): TypeError {
+  return new TypeError(`${integrationName} advertises an incompatible capability-registry contract for '${registryKey}'.`);
+}

package/src/pi-unity-settings.ts

@@ -0,0 +1,88 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export type PiUnitySettings = {
+  /** Allows pi-unity to close a running Unity process that targets the resolved project before a batchmode launch. */
+  allowCloseRunningUnityProcess: boolean;
+  /** Keeps automatic process closing constrained to Unity Test Framework runs unless explicitly disabled. */
+  closeRunningUnityProcessOnlyForTests: boolean;
+  /** Maximum time to wait for the closed Unity process to exit before failing the launch. */
+  closeRunningUnityProcessTimeoutMs: number;
+};
+
+export type PiUnitySettingsContext = {
+  cwd: string;
+  isProjectTrusted?: () => boolean;
+};
+
+export type LoadPiUnitySettingsOptions = {
+  globalSettingsPath?: string;
+  projectSettingsPath?: string;
+  env?: NodeJS.ProcessEnv;
+};
+
+export const DEFAULT_PI_UNITY_SETTINGS: PiUnitySettings = {
+  allowCloseRunningUnityProcess: false,
+  closeRunningUnityProcessOnlyForTests: true,
+  closeRunningUnityProcessTimeoutMs: 30_000,
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+async function readJsonFile(filePath: string): Promise<Record<string, unknown>> {
+  try {
+    const raw = await readFile(filePath, "utf8");
+    const parsed: unknown = JSON.parse(raw);
+    return isRecord(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function getPiUnitySettingsRecord(settings: Record<string, unknown>): Record<string, unknown> {
+  return isRecord(settings.piUnity) ? settings.piUnity : {};
+}
+
+function getGlobalSettingsPath(env: NodeJS.ProcessEnv = process.env): string {
+  const configuredAgentDir = env.PI_CODING_AGENT_DIR?.trim();
+  const agentDir = configuredAgentDir && configuredAgentDir.length > 0
+    ? configuredAgentDir
+    : join(homedir(), ".pi", "agent");
+  return join(agentDir, "settings.json");
+}
+
+function getProjectSettingsPath(cwd: string): string {
+  return join(cwd, ".pi", "settings.json");
+}
+
+export function normalizePiUnitySettings(raw: Record<string, unknown>): PiUnitySettings {
+  const timeout = typeof raw.closeRunningUnityProcessTimeoutMs === "number" && Number.isFinite(raw.closeRunningUnityProcessTimeoutMs)
+    ? Math.max(1_000, Math.min(120_000, Math.trunc(raw.closeRunningUnityProcessTimeoutMs)))
+    : DEFAULT_PI_UNITY_SETTINGS.closeRunningUnityProcessTimeoutMs;
+
+  return {
+    allowCloseRunningUnityProcess: raw.allowCloseRunningUnityProcess === true,
+    closeRunningUnityProcessOnlyForTests: raw.closeRunningUnityProcessOnlyForTests !== false,
+    closeRunningUnityProcessTimeoutMs: timeout,
+  };
+}
+
+export async function loadPiUnitySettings(
+  ctx: PiUnitySettingsContext,
+  options: LoadPiUnitySettingsOptions = {},
+): Promise<PiUnitySettings> {
+  const globalPath = options.globalSettingsPath ?? getGlobalSettingsPath(options.env);
+  const globalSettings = getPiUnitySettingsRecord(await readJsonFile(globalPath));
+  let mergedSettings: Record<string, unknown> = { ...globalSettings };
+
+  if (ctx.isProjectTrusted?.() === true) {
+    const projectPath = options.projectSettingsPath ?? getProjectSettingsPath(ctx.cwd);
+    const projectSettings = getPiUnitySettingsRecord(await readJsonFile(projectPath));
+    mergedSettings = { ...mergedSettings, ...projectSettings };
+  }
+
+  return normalizePiUnitySettings(mergedSettings);
+}

package/src/unity-artifact-profile.ts

@@ -0,0 +1,110 @@
+import { access } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import * as path from "node:path";
+import type {
+  ArtifactCandidateV1,
+  ArtifactProfileV1,
+  ArtifactValidationResultV1,
+} from "@aefree/pi-project-artifacts/contracts/v1";
+
+export const UNITY_ARTIFACT_PROFILE_ID_V1 = "unity.artifacts.v1" as const;
+export const UNITY_RENDER_PIPELINES = ["builtin", "urp", "hdrp", "custom", "agnostic"] as const;
+
+const OWNER = Object.freeze({
+  packageName: "@aefree/pi-unity",
+  packageVersion: "0.8.3",
+  packageRoot: path.resolve(fileURLToPath(new URL("..", import.meta.url))),
+  registeredBy: "index.ts",
+});
+
+/**
+ * Optional project-artifacts enrichment. These fields describe and validate
+ * metadata but never authorize raw discovery/filtering. Artifact paths already
+ * distinguish solutions from memories, while generic tags/module/component
+ * metadata remains project-owned and schema-open.
+ */
+export function createUnityArtifactProfileV1(): ArtifactProfileV1 {
+  return Object.freeze({
+    contractVersion: 1,
+    id: UNITY_ARTIFACT_PROFILE_ID_V1,
+    kind: "artifact-profile",
+    owner: OWNER,
+    artifactKinds: Object.freeze(["solution", "memory"]),
+    fields: Object.freeze([
+      { name: "engine", type: "string", indexed: true, filterable: true, enumValues: Object.freeze(["unity"]) },
+      { name: "unity_version", type: "string", indexed: true, filterable: true },
+      { name: "unity_packages", type: "string_list", indexed: true, filterable: true },
+      { name: "render_pipeline", type: "string", indexed: true, filterable: true, enumValues: UNITY_RENDER_PIPELINES },
+      { name: "platforms", type: "string_list", indexed: true, filterable: true },
+    ]),
+    validators: Object.freeze([{
+      id: "unity.artifact-metadata.v1",
+      async validate(_context, request) {
+        if (request.signal.aborted) return { outcome: "unavailable", code: "aborted", retryable: true };
+        return validateUnityArtifactMetadata(request.artifact);
+      },
+    }]),
+    async appliesTo(_context, request) {
+      if (request.signal.aborted) return false;
+      // A conventional docs path is not Unity authority. Require direct project
+      // evidence before contributing definitions or validation confidence.
+      try {
+        await access(path.join(request.workspaceRoot, "ProjectSettings", "ProjectVersion.txt"));
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  });
+}
+
+/** Validate only declared Unity fields that are present; all fields are optional. */
+export function validateUnityArtifactMetadata(artifact: ArtifactCandidateV1): ArtifactValidationResultV1 {
+  const frontmatter = artifact.frontmatter;
+  const issues: { code: string; field: string; summary: string }[] = [];
+
+  validateEnumString(frontmatter, "engine", ["unity"], issues);
+  validateNonEmptyString(frontmatter, "unity_version", issues);
+  validateStringList(frontmatter, "unity_packages", issues);
+  validateEnumString(frontmatter, "render_pipeline", UNITY_RENDER_PIPELINES, issues);
+  validateStringList(frontmatter, "platforms", issues);
+
+  return issues.length === 0 ? { outcome: "valid" } : { outcome: "invalid", issues };
+}
+
+function validateNonEmptyString(
+  frontmatter: Readonly<Record<string, unknown>>,
+  field: string,
+  issues: { code: string; field: string; summary: string }[],
+): void {
+  const value = frontmatter[field];
+  if (value === undefined) return;
+  if (typeof value !== "string" || value.trim() === "") {
+    issues.push({ code: `unity_${field}_invalid`, field, summary: `Unity ${field} must be a non-empty string when present.` });
+  }
+}
+
+function validateEnumString(
+  frontmatter: Readonly<Record<string, unknown>>,
+  field: string,
+  values: readonly string[],
+  issues: { code: string; field: string; summary: string }[],
+): void {
+  const value = frontmatter[field];
+  if (value === undefined) return;
+  if (typeof value !== "string" || !values.includes(value)) {
+    issues.push({ code: `unity_${field}_invalid`, field, summary: `Unity ${field} must be one of: ${values.join(", ")}.` });
+  }
+}
+
+function validateStringList(
+  frontmatter: Readonly<Record<string, unknown>>,
+  field: string,
+  issues: { code: string; field: string; summary: string }[],
+): void {
+  const value = frontmatter[field];
+  if (value === undefined) return;
+  if (!Array.isArray(value) || value.length === 0 || value.some((item) => typeof item !== "string" || item.trim() === "")) {
+    issues.push({ code: `unity_${field}_invalid`, field, summary: `Unity ${field} must be a non-empty list of non-empty strings when present.` });
+  }
+}

package/src/unity-batchmode.ts

@@ -0,0 +1,355 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { hasUnityCommandLineFlag } from "./unity-core";
+
+export type UnityBatchmodeInvocation = {
+  isTestRun: boolean;
+  usesNoGraphics: boolean;
+  testPlatform?: string;
+  testFilter?: string;
+  testCategory?: string;
+  testResultsPath?: string;
+  logFilePath?: string;
+};
+
+export type UnityFailedTest = {
+  name: string;
+  message?: string;
+  stackTrace?: string;
+};
+
+export type UnityParsedTestResults = {
+  total?: number;
+  passed?: number;
+  failed?: number;
+  skipped?: number;
+  inconclusive?: number;
+  durationSeconds?: number;
+  failedTests: UnityFailedTest[];
+};
+
+export type UnityBatchmodeArtifacts = {
+  testResultsPath?: string;
+  logFilePath?: string;
+  testResultsXml?: string;
+  logText?: string;
+  testResultsBytes?: number;
+  logBytes?: number;
+  logExcerpt?: string;
+  warnings: string[];
+};
+
+export function parseUnityBatchmodeInvocation(args: string[]): UnityBatchmodeInvocation {
+  const getValue = (flag: string): string | undefined => {
+    for (let index = 0; index < args.length; index += 1) {
+      const value = args[index];
+      if (value === flag) {
+        return args[index + 1];
+      }
+      if (value.startsWith(`${flag}=`)) {
+        return value.slice(flag.length + 1);
+      }
+    }
+    return undefined;
+  };
+
+  return {
+    isTestRun: hasUnityCommandLineFlag(args, "-runTests"),
+    usesNoGraphics: hasUnityCommandLineFlag(args, "-nographics"),
+    testPlatform: getValue("-testPlatform"),
+    testFilter: getValue("-testFilter"),
+    testCategory: getValue("-testCategory"),
+    testResultsPath: getValue("-testResults"),
+    logFilePath: getValue("-logFile"),
+  };
+}
+
+function decodeXmlText(value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  const trimmed = value.trim();
+  const withoutCdata = trimmed.replace(/^<!\[CDATA\[([\s\S]*?)\]\]>$/u, "$1");
+  return withoutCdata
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&amp;/g, "&")
+    .trim();
+}
+
+function parseAttributes(tagSource: string): Record<string, string> {
+  const attributes: Record<string, string> = {};
+  const attributeRegex = /(\w[\w:-]*)\s*=\s*"([^"]*)"/g;
+  for (const match of tagSource.matchAll(attributeRegex)) {
+    const key = match[1];
+    const value = match[2] ?? "";
+    attributes[key] = value;
+  }
+  return attributes;
+}
+
+function truncateEvidence(value: string | undefined, maxChars: number): string | undefined {
+  if (!value) return undefined;
+  return value.length <= maxChars ? value : `${value.slice(0, Math.max(0, maxChars - 1))}…`;
+}
+
+function parseOptionalNumber(value: string | undefined): number | undefined {
+  if (!value) return undefined;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+export function parseUnityTestResultsXml(xml: string): UnityParsedTestResults | null {
+  const testRunMatch = xml.match(/<test-run\b([^>]*)>/i);
+  const testRunCloseIndex = xml.search(/<\/test-run\s*>/i);
+  if (!testRunMatch || testRunCloseIndex < (testRunMatch.index ?? 0) + testRunMatch[0].length) {
+    return null;
+  }
+
+  const rootAttributes = parseAttributes(testRunMatch[1] ?? "");
+  const failedTests: UnityFailedTest[] = [];
+
+  const testCaseRegex = /<test-case\b([^>]*)>([\s\S]*?)<\/test-case>/gi;
+  for (const match of xml.matchAll(testCaseRegex)) {
+    const attributes = parseAttributes(match[1] ?? "");
+    const body = match[2] ?? "";
+    const result = String(attributes.result ?? attributes.label ?? "").toLowerCase();
+    const success = String(attributes.success ?? "").toLowerCase();
+    const isFailure = result === "failed" || success === "false";
+    if (!isFailure) continue;
+
+    const failureMessage = body.match(/<message[^>]*>([\s\S]*?)<\/message>/i);
+    const stackTrace = body.match(/<stack-trace[^>]*>([\s\S]*?)<\/stack-trace>/i);
+    if (failedTests.length < 50) {
+      failedTests.push({
+        name: truncateEvidence(attributes.fullname ?? attributes.name ?? "(unknown test)", 500) ?? "(unknown test)",
+        message: truncateEvidence(decodeXmlText(failureMessage?.[1]), 1_000),
+        stackTrace: truncateEvidence(decodeXmlText(stackTrace?.[1]), 4_000),
+      });
+    }
+  }
+
+  const skipped = parseOptionalNumber(rootAttributes.skipped) ?? parseOptionalNumber(rootAttributes.inconclusive);
+
+  const parsed: UnityParsedTestResults = {
+    total: parseOptionalNumber(rootAttributes.total) ?? parseOptionalNumber(rootAttributes.testcasecount),
+    passed: parseOptionalNumber(rootAttributes.passed),
+    failed: parseOptionalNumber(rootAttributes.failed),
+    skipped,
+    inconclusive: parseOptionalNumber(rootAttributes.inconclusive),
+    durationSeconds: parseOptionalNumber(rootAttributes.duration),
+    failedTests,
+  };
+  if (parsed.total === undefined && parsed.passed === undefined && parsed.failed === undefined && parsed.failedTests.length === 0) {
+    return null;
+  }
+  return parsed;
+}
+
+function buildArtifactCandidates(cwd: string, projectRoot: string, rawPath: string): string[] {
+  if (path.isAbsolute(rawPath)) {
+    return [path.normalize(rawPath)];
+  }
+
+  const candidates = [
+    path.resolve(cwd, rawPath),
+    path.resolve(projectRoot, rawPath),
+  ].map((value) => path.normalize(value));
+
+  return Array.from(new Set(candidates));
+}
+
+async function readFirstExistingText(pathsToTry: string[]): Promise<{ path?: string; text?: string }> {
+  for (const candidate of pathsToTry) {
+    try {
+      const text = await fs.readFile(candidate, "utf8");
+      return { path: candidate, text };
+    } catch {
+      // Try next candidate.
+    }
+  }
+  return {};
+}
+
+export async function loadUnityBatchmodeArtifacts(
+  cwd: string,
+  projectRoot: string,
+  invocation: UnityBatchmodeInvocation,
+): Promise<UnityBatchmodeArtifacts> {
+  const warnings: string[] = [];
+  const artifacts: UnityBatchmodeArtifacts = { warnings };
+
+  if (invocation.testResultsPath) {
+    const result = await readFirstExistingText(buildArtifactCandidates(cwd, projectRoot, invocation.testResultsPath));
+    if (result.path && result.text !== undefined) {
+      artifacts.testResultsPath = result.path;
+      artifacts.testResultsXml = result.text;
+    } else {
+      warnings.push(`Unity test results file was not found: ${invocation.testResultsPath}`);
+    }
+  }
+
+  if (invocation.logFilePath && invocation.logFilePath !== "-") {
+    const result = await readFirstExistingText(buildArtifactCandidates(cwd, projectRoot, invocation.logFilePath));
+    if (result.path && result.text !== undefined) {
+      artifacts.logFilePath = result.path;
+      artifacts.logText = result.text;
+    } else {
+      warnings.push(`Unity log file was not found: ${invocation.logFilePath}`);
+    }
+  }
+
+  return artifacts;
+}
+
+export function summarizeTextForAgent(value: string | undefined, maxLines = 40, maxChars = 4000): string | undefined {
+  if (!value) return undefined;
+  const trimmed = value.trim();
+  if (!trimmed) return undefined;
+
+  const lines = trimmed.split(/\r?\n/);
+  const selected = lines.length > maxLines ? lines.slice(-maxLines) : lines;
+  let text = selected.join("\n");
+  if (text.length > maxChars) {
+    text = text.slice(text.length - maxChars);
+  }
+
+  const omittedLines = lines.length - selected.length;
+  const prefix = omittedLines > 0 ? `[showing last ${selected.length} of ${lines.length} lines]\n` : "";
+  return `${prefix}${text}`;
+}
+
+export function formatParsedTestResultsForAgent(results: UnityParsedTestResults): string[] {
+  const counts: string[] = [];
+  if (results.total !== undefined) counts.push(`total=${results.total}`);
+  if (results.passed !== undefined) counts.push(`passed=${results.passed}`);
+  if (results.failed !== undefined) counts.push(`failed=${results.failed}`);
+  if (results.skipped !== undefined) counts.push(`skipped=${results.skipped}`);
+  if (results.inconclusive !== undefined) counts.push(`inconclusive=${results.inconclusive}`);
+  if (results.durationSeconds !== undefined) counts.push(`duration=${results.durationSeconds}s`);
+
+  const lines = counts.length > 0 ? [`Results: ${counts.join(", ")}`] : [];
+  if (results.failedTests.length > 0) {
+    lines.push("Failed tests:");
+    for (const failed of results.failedTests.slice(0, 8)) {
+      lines.push(`- ${failed.name}`);
+      if (failed.message) {
+        lines.push(`  ${failed.message.split(/\r?\n/)[0]}`);
+      }
+    }
+    if (results.failedTests.length > 8) {
+      lines.push(`- ... ${results.failedTests.length - 8} more failed tests`);
+    }
+  }
+  return lines;
+}
+
+export type UnityBatchmodeAgentTextInput = {
+  displayProjectPath: string;
+  unityVersion: string;
+  editorPath: string;
+  exitCode: number;
+  killed: boolean;
+  invocation: UnityBatchmodeInvocation;
+  artifacts: UnityBatchmodeArtifacts;
+  parsedTestResults?: UnityParsedTestResults | null;
+  stdout?: string;
+  stderr?: string;
+  warning?: string;
+  singleProcessWarning: string;
+};
+
+export function hasKnownPositiveExecutedTestCount(
+  parsedTestResults?: UnityParsedTestResults | null,
+): boolean {
+  return parsedTestResults?.total !== undefined
+    && Number.isFinite(parsedTestResults.total)
+    && parsedTestResults.total > 0;
+}
+
+export function isPassingUnityTestEvidence(
+  parsedTestResults?: UnityParsedTestResults | null,
+): boolean {
+  return hasKnownPositiveExecutedTestCount(parsedTestResults)
+    && (parsedTestResults?.failed ?? 0) === 0
+    && (parsedTestResults?.failedTests.length ?? 0) === 0;
+}
+
+export function deriveUnityArtifactInspectionStatus(
+  hasLoadedArtifacts: boolean,
+  invocation: UnityBatchmodeInvocation,
+  parsedTestResults?: UnityParsedTestResults | null,
+): "passed" | "failed" {
+  if (!hasLoadedArtifacts) return "failed";
+  if (invocation.isTestRun && !isPassingUnityTestEvidence(parsedTestResults)) return "failed";
+  return "passed";
+}
+
+export function deriveUnityBatchmodeStatus(
+  exitCode: number,
+  killed: boolean,
+  invocation: UnityBatchmodeInvocation,
+  parsedTestResults?: UnityParsedTestResults | null,
+): "passed" | "failed" | "killed" {
+  if (killed) return "killed";
+  if (invocation.isTestRun && !isPassingUnityTestEvidence(parsedTestResults)) return "failed";
+  if (parsedTestResults && ((parsedTestResults.failed ?? 0) > 0 || parsedTestResults.failedTests.length > 0)) {
+    return "failed";
+  }
+  return exitCode === 0 ? "passed" : "failed";
+}
+
+function getOutcomeLabel(input: UnityBatchmodeAgentTextInput): "passed" | "failed" | "killed" {
+  return deriveUnityBatchmodeStatus(input.exitCode, input.killed, input.invocation, input.parsedTestResults);
+}
+
+function getBatchmodeVariantLabel(invocation: UnityBatchmodeInvocation): "Unity (headless)" | "Unity (graphics)" {
+  return invocation.usesNoGraphics ? "Unity (headless)" : "Unity (graphics)";
+}
+
+export function buildUnityBatchmodeAgentText(input: UnityBatchmodeAgentTextInput): string {
+  const outcome = getOutcomeLabel(input);
+  const batchmodeVariant = getBatchmodeVariantLabel(input.invocation);
+  const lines = [
+    `${batchmodeVariant} ${outcome} for ${input.displayProjectPath} using Unity ${input.unityVersion}.`,
+    `Editor: ${input.editorPath}`,
+    `Exit code: ${input.exitCode}`,
+    `Mode: ${batchmodeVariant}`,
+    input.singleProcessWarning,
+  ];
+
+  if (input.invocation.isTestRun) {
+    lines.push("Run type: Unity Test Framework");
+    if (input.invocation.testPlatform) lines.push(`Test platform: ${input.invocation.testPlatform}`);
+    if (input.invocation.testFilter) lines.push(`Test filter: ${input.invocation.testFilter}`);
+    if (input.invocation.testCategory) lines.push(`Test category: ${input.invocation.testCategory}`);
+  }
+
+  if (input.parsedTestResults) {
+    lines.push(...formatParsedTestResultsForAgent(input.parsedTestResults));
+  }
+  if (input.invocation.isTestRun && !hasKnownPositiveExecutedTestCount(input.parsedTestResults)) {
+    lines.push(input.parsedTestResults?.total === 0
+      ? "Unity reported zero executed tests; this batch is not passing evidence."
+      : "Unity did not report a known positive executed-test count; this batch is not passing evidence.");
+  }
+
+  if (input.artifacts.testResultsPath) lines.push(`Test results: ${input.artifacts.testResultsPath}`);
+  if (input.artifacts.logFilePath) lines.push(`Log file: ${input.artifacts.logFilePath}`);
+  for (const artifactWarning of input.artifacts.warnings) lines.push(artifactWarning);
+  if (input.invocation.testResultsPath && input.artifacts.testResultsXml && !input.parsedTestResults) {
+    lines.push(`Unity test results XML could not be parsed: ${input.artifacts.testResultsPath ?? input.invocation.testResultsPath}`);
+  }
+  if (input.warning) lines.push(input.warning);
+
+  const preferredOutput = input.parsedTestResults
+    ? undefined
+    : summarizeTextForAgent(input.stderr) ?? summarizeTextForAgent(input.stdout) ?? summarizeTextForAgent(input.artifacts.logText);
+
+  if (preferredOutput) {
+    lines.push("Relevant output:");
+    lines.push(preferredOutput);
+  }
+
+  return lines.join("\n");
+}