feat(xcode-ide): Persist bridge response artifacts (#396)

* ref(rendering): Finalize output from structured results

Make final tool rendering depend on explicit structured results instead of
streaming fragments. This keeps live progress transient and gives CLI, daemon,
and MCP output paths the same source of truth for final success, errors, and
text rendering.

Add a shared structured error shape and schema coverage so failures can be
rendered consistently without scraping fragment text.

* ref(build-run): Return explicit structured results

Update simulator, device, and macOS build-and-run flows to populate final
structured results directly. This removes the need to infer final status or
artifact paths from progress fragments while preserving live progress for
interactive renderers.

Adjust resource and test helpers around the new result contract.

* fix(filesystem): Prune workspace artifacts safely

Expand workspace filesystem cleanup so transient XcodeBuildMCP-owned files are
removed with ownership checks and bounded retention. This keeps generated
artifacts from accumulating while preserving files that belong to active
processes or other workspaces.

Add regression coverage for cleanup ownership and retention behavior.

* feat(xcode-ide): Persist bridge responses as artifacts

Save raw Xcode IDE bridge call results as transient workspace artifacts and
return concise structured summaries from the public tools. This prevents large
relayed payloads from being embedded in final text output while preserving the
full remote response for callers that need it.

Route Xcode IDE CLI commands through the generic output pipeline so text, JSON,
and JSONL modes share the same behavior as other tool commands.

* test(xcode-ide): Add bridge output snapshots

Add snapshot coverage for Xcode IDE list-tools and documentation-search output
across CLI text, MCP text, and CLI JSON modes. Normalize transient artifact
paths so the fixtures verify the public contract without depending on local
workspace directories.

* docs: Document output and cleanup rules

Update agent guidance for structured output terminology, streaming boundaries,
and workspace filesystem cleanup. Add the corresponding changelog entries for
the Xcode IDE artifact output and fragment-state removal.

* test(swift-package): Allow nonzero run duration

Avoid asserting an exact wall-clock duration for swift_package_run progress.
CI can legitimately report a small nonzero duration even when local runs finish
within the same millisecond.

* fix(rendering): Prevent fragment state from affecting final output

Remove fragment caching from render sessions and test results so streamed
fragments cannot be reused as final response state. Normalize xcode-ide tool
counts in snapshots to avoid environment-specific fixture churn.

Refs GH-360
Co-Authored-By: Codex <noreply@openai.com>

---------

Co-authored-by: Codex <noreply@openai.com>

Author: cameroncooke

AGENTS.md

@@ -54,6 +54,12 @@ ESM TypeScript project (`type: module`). Key layers:
 - No `.js` imports in `src/` (enforced by ESLint)
 - No barrel imports from `utils/index` - import from specific submodules (e.g., `src/utils/execution/index.ts`, `src/utils/logging/index.ts`)
 
+
+## Rendering and Streaming Contract
+- Streaming fragments are transient output only. They MUST NOT be used as internal state, cached for final responses, or promoted into final MCP/JSON/CLI text output.
+- Non-streaming runtimes/output modes, including MCP final responses, MUST render only from the final structured result and next-step metadata. If final output needs data, add it to the final result type instead of reading it from fragments.
+- Only streaming-capable renderers may observe fragment callbacks, and only to print live progress. Their fragment handling must not affect final structured output or final rendered text.
+
 ## Test Conventions
 - Vitest with colocated `__tests__/` directories using `*.test.ts`
 - Smoke tests in `src/smoke-tests/__tests__/` (separate Vitest config, serial execution)
@@ -88,6 +94,7 @@ When reading issues:
 - Use shared lock and atomic-write helpers for mutable shared files.
 - Prefer one-record-per-file registries over shared aggregate files.
 - Cleanup must verify ownership before deleting shared artifacts.
+- User-facing artifact/log paths in final text or structured output must use `displayPath()` from `src/utils/build-preflight.ts`, so paths are cwd-relative when possible or `~/...` instead of absolute home paths. Keep stored files at their real absolute paths; only normalize response/display values.
 
 ## Style
 - Keep answers short and concise
@@ -98,6 +105,7 @@ When reading issues:
 ## Docs
 - Do not commit transient investigation notes, prompt exports, or scratch analysis docs after the work is complete.
 - If an investigation leaves unresolved follow-up work, move it to a GitHub issue instead of preserving the transient doc in the branch.
+- Structured output JSON schemas are auto-published to the website/public schema mirror when merged; do not manually update public schema copies unless explicitly asked.
 
 ### Changelog
 Location: `CHANGELOG.md`

CHANGELOG.md

@@ -14,7 +14,9 @@
 
 ### Changed
 
+- Updated Xcode IDE `call-tool` output to save raw remote responses as transient workspace-state JSON artifacts, summarize text output without embedding large relayed payloads, and support `--output json` / `--output jsonl` through the generic CLI output path.
 - Centralized workspace log retention and startup/shutdown filesystem cleanup so XcodeBuildMCP-owned logs are pruned consistently while preserving active daemon and simulator OSLog outputs.
+- Removed internal streaming-fragment context flags so final tool state now comes from explicit structured outputs instead of transient progress fragments ([#360](https://github.com/getsentry/XcodeBuildMCP/issues/360)).
 
 ## [2.5.0-beta.1]
 

CLAUDE.md

@@ -29,6 +29,7 @@ When reading issues:
 - Use shared lock and atomic-write helpers for mutable shared files.
 - Prefer one-record-per-file registries over shared aggregate files.
 - Cleanup must verify ownership before deleting shared artifacts.
+- User-facing artifact/log paths in final text or structured output must use `displayPath()` from `src/utils/build-preflight.ts`, so paths are cwd-relative when possible or `~/...` instead of absolute home paths. Keep stored files at their real absolute paths; only normalize response/display values.
 
 ## Style
 - Keep answers short and concise
@@ -39,6 +40,7 @@ When reading issues:
 ## Docs
 - Do not commit transient investigation notes, prompt exports, or scratch analysis docs after the work is complete.
 - If an investigation leaves unresolved follow-up work, move it to a GitHub issue instead of preserving the transient doc in the branch.
+- Structured output JSON schemas are auto-published to the website/public schema mirror when merged; do not manually update public schema copies unless explicitly asked.
 
 ### Changelog
 Location: `CHANGELOG.md`
@@ -62,6 +64,12 @@ Use these sections under `## [Unreleased]`:
 - **Internal changes (from issues)**: `Fixed foo bar ([#123](https://github.com/cameroncook/XcodeBuildMCP/issues/123))`
 - **External contributions**: `Added feature X ([#456](https://github.com/cameroncook/XcodeBuildMCP/pull/456) by [@username](https://github.com/username))`
 
+
+## Rendering and Streaming Contract
+- Streaming fragments are transient output only. They MUST NOT be used as internal state, cached for final responses, or promoted into final MCP/JSON/CLI text output.
+- Non-streaming runtimes/output modes, including MCP final responses, MUST render only from the final structured result and next-step metadata. If final output needs data, add it to the final result type instead of reading it from fragments.
+- Only streaming-capable renderers may observe fragment callbacks, and only to print live progress. Their fragment handling must not affect final structured output or final rendered text.
+
 ## Test Execution Rules
 - When running long test suites (snapshot tests, smoke tests), ALWAYS write full output to a log file and read it afterwards. NEVER pipe through `tail` or `grep` directly — that loses output you may need to debug failures.
 - Pattern: `DEVICE_ID=... npm run test:snapshot 2>&1 | tee /tmp/snapshot-results.txt` then read `/tmp/snapshot-results.txt` with the native read tool.

manifests/tools/xcode_ide_call_tool.yaml

@@ -6,7 +6,7 @@ names:
 description: Call a remote Xcode IDE MCP tool.
 outputSchema:
   schema: xcodebuildmcp.output.xcode-bridge-call-result
-  version: "1"
+  version: '2'
 routing:
   stateful: true
 annotations:

manifests/tools/xcode_ide_list_tools.yaml

@@ -6,7 +6,7 @@ names:
 description: "Lists Xcode-IDE-only MCP capabilities (Use for: SwiftUI previews image capture, code snippet execution, issue Navigator/build logs, and window/tab context)."
 outputSchema:
   schema: xcodebuildmcp.output.xcode-bridge-tool-list
-  version: "1"
+  version: "2"
 routing:
   stateful: true
 annotations:

schemas/structured-output/xcodebuildmcp.output.error/1.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://xcodebuildmcp.com/schemas/structured-output/xcodebuildmcp.output.error/1.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "allOf": [
+    {
+      "$ref": "https://xcodebuildmcp.com/schemas/structured-output/_defs/common.schema.json#/$defs/errorConsistency"
+    }
+  ],
+  "properties": {
+    "schema": {
+      "const": "xcodebuildmcp.output.error"
+    },
+    "schemaVersion": {
+      "const": "1"
+    },
+    "didError": {
+      "const": true
+    },
+    "error": {
+      "type": "string",
+      "minLength": 1
+    },
+    "data": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "category": {
+          "enum": ["runtime", "validation", "schema"]
+        },
+        "code": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "required": ["category", "code"]
+    }
+  },
+  "required": ["schema", "schemaVersion", "didError", "error", "data"]
+}

schemas/structured-output/xcodebuildmcp.output.xcode-bridge-call-result/2.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://xcodebuildmcp.com/schemas/structured-output/xcodebuildmcp.output.xcode-bridge-call-result/2.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "allOf": [
+    {
+      "$ref": "https://xcodebuildmcp.com/schemas/structured-output/_defs/common.schema.json#/$defs/errorConsistency"
+    }
+  ],
+  "$defs": {
+    "relayedContentItem": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "type": { "type": "string" }
+      },
+      "required": ["type"]
+    },
+    "artifacts": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "rawResponseJsonPath": { "type": "string" }
+      },
+      "required": ["rawResponseJsonPath"]
+    }
+  },
+  "properties": {
+    "schema": { "const": "xcodebuildmcp.output.xcode-bridge-call-result" },
+    "schemaVersion": { "const": "2" },
+    "didError": { "type": "boolean" },
+    "error": { "type": ["string", "null"] },
+    "data": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "remoteTool": { "type": "string" },
+        "succeeded": { "type": "boolean" },
+        "content": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/relayedContentItem" }
+        },
+        "artifacts": { "$ref": "#/$defs/artifacts" }
+      },
+      "required": ["remoteTool", "succeeded", "content"]
+    }
+  },
+  "required": ["schema", "schemaVersion", "didError", "error", "data"]
+}

schemas/structured-output/xcodebuildmcp.output.xcode-bridge-tool-list/2.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://xcodebuildmcp.com/schemas/structured-output/xcodebuildmcp.output.xcode-bridge-tool-list/2.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "allOf": [
+    {
+      "$ref": "https://xcodebuildmcp.com/schemas/structured-output/_defs/common.schema.json#/$defs/errorConsistency"
+    }
+  ],
+  "$defs": {
+    "artifacts": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "rawResponseJsonPath": { "type": "string" }
+      },
+      "required": ["rawResponseJsonPath"]
+    }
+  },
+  "properties": {
+    "schema": { "const": "xcodebuildmcp.output.xcode-bridge-tool-list" },
+    "schemaVersion": { "const": "2" },
+    "didError": { "type": "boolean" },
+    "error": { "type": ["string", "null"] },
+    "data": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "toolCount": { "type": "integer", "minimum": 0 },
+        "artifacts": { "$ref": "#/$defs/artifacts" }
+      },
+      "required": ["toolCount"]
+    }
+  },
+  "required": ["schema", "schemaVersion", "didError", "error", "data"]
+}

src/cli.ts

@@ -32,6 +32,23 @@ function findTopLevelCommand(argv: string[]): string | undefined {
   return undefined;
 }
 
+function findGlobalSocketOverride(argv: string[]): string | undefined {
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === '--socket') {
+      const value = argv[index + 1];
+      return value && !value.startsWith('-') ? value : undefined;
+    }
+
+    if (token.startsWith('--socket=')) {
+      const value = token.slice('--socket='.length);
+      return value || undefined;
+    }
+  }
+
+  return undefined;
+}
+
 async function buildLightweightYargsApp(): Promise<ReturnType<typeof import('yargs').default>> {
   const yargs = (await import('yargs')).default;
   const { hideBin } = await import('yargs/helpers');
@@ -120,10 +137,12 @@ async function main(): Promise<void> {
 
   const { workspaceRoot, workspaceKey } = result;
 
-  const defaultSocketPath = getSocketPath({
-    cwd: result.runtime.cwd,
-    projectConfigPath: result.configPath,
-  });
+  const socketPath =
+    findGlobalSocketOverride(process.argv.slice(2)) ??
+    getSocketPath({
+      cwd: result.runtime.cwd,
+      projectConfigPath: result.configPath,
+    });
 
   const cliExposedWorkflowIds = await listCliWorkflowIdsFromManifest({
     excludeWorkflows: ['session-management', 'workflow-discovery'],
@@ -133,7 +152,7 @@ async function main(): Promise<void> {
 
   // CLI uses a manifest-resolved catalog plus daemon-backed xcode-ide dynamic tools.
   const catalog = await buildCliToolCatalog({
-    socketPath: defaultSocketPath,
+    socketPath,
     workspaceRoot,
     cliExposedWorkflowIds,
     discoveryMode,
@@ -142,7 +161,7 @@ async function main(): Promise<void> {
   const yargsApp = buildYargsApp({
     catalog,
     runtimeConfig: result.runtime.config,
-    defaultSocketPath,
+    defaultSocketPath: socketPath,
     workspaceRoot,
     workspaceKey,
     workflowNames: cliExposedWorkflowIds,