@octane-xplat/mcp 0.16.0 → 0.17.0

package/README.md

@@ -61,12 +61,12 @@ Options: `--workspace` / `XPLAT_MCP_WORKSPACE` (default cwd), `--app` /
 | `xplat_select_app`                      | Explicitly bind an app by id/path/name. Ambiguous or unknown selections fail with the candidate list — the server never picks silently.                                                                        |
 | `xplat_capability_matrix`               | Per-platform capability entries: build, launch, logs, inspection, screenshot, interaction, and the rest are separate rows with status, detail, and alternatives.                                               |
 | `xplat_permissions`                     | Grant states per scope plus the action-time check result and recovery path.                                                                                                                                    |
-| `xplat_sessions`                        | Bound sessions: owned vs attached user-owned, state, build identity.                                                                                                                                           |
+| `xplat_sessions`                        | Retained sessions and launch progress; optional `sessionId` selects exact status, including failures and ended sessions.                                                                                                                                           |
 | `xplat_targets`                         | Launchable targets per platform (simulators, devices, host targets) with availability, missing-toolchain reasons, and busy/ownership state.                                                                    |
 | `xplat_build`                           | Build the bound app for one platform as a job — same commands `xplat build` runs. `requestKey` dedupes retries.                                                                                                |
-| `xplat_launch`                          | Owned dev session on one target as a job; completes at confirmed readiness, session owns the processes until `xplat_session_end`.                                                                              |
+| `xplat_launch`                          | Start an owned session and return its durable ID immediately; poll `xplat_sessions` for readiness, end with `xplat_session_end`.                                                                              |
 | `xplat_attach`                          | Bind a compatible already-running dev session (user-owned, preserved).                                                                                                                                         |
-| `xplat_logs`                            | Bounded ordered logs for a session or build job: cursor, limit, stream filter, truncation/reset indicators, `historical` flag for dead sessions.                                                               |
+| `xplat_diagnostics`                     | Retained session discovery; log pages under `logs`, native summaries under `reports`, explicit source `coverage`, and original report reads. Build/action jobs retain their own logs.                    |
 | `xplat_dev_actions`                     | The bound app's live development-action registry: instance identity, revision, declarations (contracts, effects, availability). Empty vs disconnected vs no-bridge are distinct states.                        |
 | `xplat_dev_action_invoke`               | Invoke an action against an exact app instance + registry revision. Pre-validates input, availability, grants and queue bounds; returns a job (`requestKey` dedupes retries).                                  |
 | `xplat_dev_action_status`               | Invocation status/result — same job data restricted to dev-action jobs, with instance/request identity.                                                                                                        |
@@ -102,7 +102,7 @@ snapshot availability, so readiness alone is not a successful retrieval.
 	"name": "xplat_docs_read",
 	"arguments": {
 		"package": "@octane-xplat/ui",
-		"path": "docs/verify/test-identifiers.md",
+		"path": "docs/testing/test-identifiers.md",
 		"limit": 2000
 	}
 }
@@ -197,8 +197,8 @@ cancel, ownership-safe cleanup, bounded logs, and capability-matrix entries.
 
 Readiness is probe/marker-confirmed (`ready` session state) — HTTP 200 for
 web, the host-start marker for macOS, `Successfully synced application` /
-first `CONSOLE` line for `ns run`. A timeout or pre-ready exit fails the job
-and ends the owned session honestly. Chromium is located via
+first `CONSOLE` line for `ns run`. A timeout or pre-ready exit marks the session `failed`
+and releases its owned resources. Chromium is located via
 `XPLAT_MCP_CHROMIUM`, the Playwright browser cache, or system installs;
 without it the web session still reports the server URL with an explicit
 `browser.launched: false`.
@@ -207,6 +207,21 @@ Physical iOS devices, Windows attach detection, and non-simulator iOS log
 taps are reported limitations, not silent gaps — the capability matrix
 carries the detail and an alternative.
 
+Launch accepts an optional exact target ID or platform name. Platform or omitted
+selection requires exactly one eligible target; ambiguity returns candidates.
+Use the same session ID for status, diagnostics, and cleanup:
+
+```js
+const launch = await client.callTool({name: "xplat_launch", arguments: {target: "ios"}});
+const {sessionId} = launch.structuredContent.data.session;
+await client.callTool({name: "xplat_sessions", arguments: {sessionId}});
+await client.callTool({name: "xplat_diagnostics", arguments: {sessionId}});
+await client.callTool({name: "xplat_session_end", arguments: {sessionId}});
+```
+
+Ending a session
+also cancels startup when it has not reached readiness.
+
 ## Inspect and interact with Chromium
 
 This development package adds `xplat_inspect`, `xplat_interact`, and

package/dist/runtime/tools.js

@@ -17,7 +17,7 @@ function registerRuntimeTools(server, context, respond) {
 		});
 	});
 	server.registerTool("xplat_build", {
-		description: "Build the bound app for one platform as a background job (the same commands `xplat build` runs). Returns a job id — poll xplat_job_status and read output with xplat_logs. Repeating with the same requestKey returns the live job instead of duplicating it.",
+		description: "Build the bound app for one platform as a background job (the same commands `xplat build` runs). Returns a job id — poll xplat_job_status and read output with xplat_diagnostics. Repeating with the same requestKey returns the live job instead of duplicating it.",
 		inputSchema: {
 			platform: z.enum(identity_exports.PLATFORMS),
 			requestKey: z.string().optional().describe("Idempotence key for retries")
@@ -36,17 +36,15 @@ function registerRuntimeTools(server, context, respond) {
 		});
 	});
 	server.registerTool("xplat_launch", {
-		description: "Start an owned development session: bind one app to one target and run the platform dev command as a job. The job completes when readiness is confirmed — a failed launch after a successful build reports accurately, and the session keeps the app alive until xplat_session_end.",
+		description: "Start an owned development session: return one durable session id immediately. Read launch progress and readiness through xplat_sessions; diagnostics use the same session id, including after shutdown.",
 		inputSchema: {
-			platform: z.enum(identity_exports.PLATFORMS),
-			targetId: z.string().optional().describe("Target from xplat_targets; required when several are available"),
+			target: z.string().optional().describe("Exact discovered target id or platform name; omit only when one eligible target exists"),
 			requestKey: z.string().optional().describe("Idempotence key for retries"),
 			browserMode: z.enum(["headless", "headed"]).optional().describe("Web only. Headed mode enables scoped OS keyboard input on qualified hosts; reserve desktop input before using it.")
 		}
-	}, async ({ platform, targetId, requestKey, browserMode }) => {
+	}, async ({ target, requestKey, browserMode }) => {
 		const result = await runtime.launch({
-			platform,
-			targetId,
+			target,
 			requestKey,
 			browserMode
 		});
@@ -77,12 +75,14 @@ function registerRuntimeTools(server, context, respond) {
 			data: result
 		});
 	});
-	server.registerTool("xplat_logs", {
-		description: "Bounded, ordered log read for a session or build job. Cursor-paginated: pass the previous nextCursor to continue; truncated/dropped flags reveal gaps and reset marks a restarted capture. A stopped or disconnected session reports its capture as historical.",
+	server.registerTool("xplat_diagnostics", {
+		description: "List retained sessions or read logs and existing native report summaries. Log cursors do not page reports; reportId with sessionId reads a retained original. Session selectors include retained logs and native reports; standalone build jobs have log captures only.",
 		inputSchema: {
+			reportId: z.string().optional(),
+			platform: z.enum(identity_exports.PLATFORMS).optional(),
 			sessionId: z.string().optional(),
 			jobId: z.string().optional(),
-			cursor: z.number().optional().describe("Continue after this record seq"),
+			cursor: z.number().int().nonnegative().optional(),
 			limit: z.number().int().positive().max(5e3).optional(),
 			stream: z.enum([
 				"stdout",
@@ -90,22 +90,8 @@ function registerRuntimeTools(server, context, respond) {
 				"lifecycle"
 			]).optional()
 		}
-	}, async ({ sessionId, jobId, cursor, limit, stream }) => {
-		if (!sessionId && !jobId) return respond({
-			ok: false,
-			error: {
-				code: "invalid_selection",
-				message: "Pass a sessionId or a jobId.",
-				recovery: { action: "Use xplat_sessions or a build/launch job id." }
-			}
-		});
-		const result = runtime.readLogs({
-			sessionId,
-			jobId,
-			cursor,
-			limit,
-			stream
-		});
+	}, async (args) => {
+		const result = await runtime.readDiagnostics(args);
 		return result.error ? respond({
 			ok: false,
 			error: result.error

package/dist/server.js

@@ -15,7 +15,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 //#region src/server.ts
 var SERVER_VERSION = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "../package.json"), "utf8")).version;
-var INSTRUCTIONS = "MCP server for Octane Xplat apps. Call xplat_project_status first — it reports detected apps, framework versions, guidance, prerequisites, and capabilities. If several apps are detected, ask the developer which to use and bind it with xplat_select_app; never guess. With a dev-mode app running, xplat_dev_actions lists the app-declared action registry and xplat_dev_action_invoke runs one against an exact instance and registry revision. For runtime work, check xplat_capability_matrix then xplat_targets; xplat_launch starts an owned session as a job and xplat_attach binds a session you already run. Results always say what was actually checked; a successful build is not proof of behavior.";
+var INSTRUCTIONS = "MCP server for Octane Xplat apps. Call xplat_project_status first — it reports detected apps, framework versions, guidance, prerequisites, and capabilities. If several apps are detected, ask the developer which to use and bind it with xplat_select_app; never guess. With a dev-mode app running, xplat_dev_actions lists the app-declared action registry and xplat_dev_action_invoke runs one against an exact instance and registry revision. For runtime work, check xplat_capability_matrix then xplat_targets; xplat_launch returns a durable session identity and launch progress and xplat_attach binds a session you already run. Results always say what was actually checked; a successful build is not proof of behavior.";
 var respond = (outcome) => ({
 	structuredContent: outcome,
 	isError: outcome.ok === false,
@@ -129,9 +129,12 @@ function createXplatMcpServer(context) {
 		});
 	});
 	server.registerTool("xplat_sessions", {
-		description: "List bound sessions: owned sessions the server started and attached user-owned sessions. Runtime tools bind one app to one target; attached sessions are preserved on end.",
-		inputSchema: {}
-	}, async () => ok({ sessions: context.sessions.list() }));
+		description: "List retained sessions or read exact sessionId status, including launch progress, failures and ended sessions. Attached user-owned apps are preserved on end.",
+		inputSchema: { sessionId: z.string().optional() }
+	}, async ({ sessionId }) => {
+		const result = sessionId ? context.runtime.sessionStatus(sessionId) : context.runtime.listSessions();
+		return result.error ? fail(result.error) : ok(result);
+	});
 	server.registerTool("xplat_job_status", {
 		description: "Bounded status query for a job started by a runtime tool.",
 		inputSchema: { jobId: z.string() }
@@ -150,9 +153,12 @@ function createXplatMcpServer(context) {
 		description: "End a session with ownership-safe cleanup: owned sessions release their resources; attached user-owned sessions are detached and preserved.",
 		inputSchema: { sessionId: z.string() }
 	}, async ({ sessionId }) => {
-		const usable = context.sessions.requireUsable(sessionId);
-		if (!usable.usable && usable.error.code === "not_found") return fail(usable.error);
-		return ok({ result: await context.runtime.endSession(sessionId) });
+		try {
+			const result = await context.runtime.endSession(sessionId);
+			return result.error ? fail(result.error) : ok({ result });
+		} catch (error) {
+			return fail((0, errors_exports.toContractError)(error));
+		}
 	});
 	server.registerTool("xplat_dev_actions", {
 		description: "List the bound app's declared development actions — the live registry announced by a running dev app: stable ids, titles, input/result contracts, effects, availability with reasons, and the registry revision. Never executes an action. An empty registry is reported distinctly from a disconnected app.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octane-xplat/mcp",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "MCP server for Octane Xplat consumer apps — project identity, capability discovery, permission and evidence contracts.",
   "license": "MIT",
   "repository": {
@@ -34,7 +34,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.31.0",
-    "@octane-xplat/cli": "0.16.0",
+    "@octane-xplat/cli": "0.17.0",
     "yaml": "2.9.1",
     "zod": "4.6.5"
   },

package/src/context.ts

@@ -30,13 +30,16 @@ export interface RuntimeService {
 	listTargets(args: { platform?: Platform }): Promise<any>
 	build(args: { platform: Platform; requestKey?: string }): Promise<any>
 	launch(args: {
-		platform: Platform
-		targetId?: string
+		target?: string
 		requestKey?: string
 		browserMode?: 'headless' | 'headed'
 	}): Promise<any>
+	listSessions(): any
+	sessionStatus(sessionId: string): any
 	attach(args: { platform: Platform; targetId?: string }): Promise<any>
-	readLogs(args: {
+	readDiagnostics(args: {
+		reportId?: string
+		platform?: Platform
 		sessionId?: string
 		jobId?: string
 		cursor?: number

package/src/runtime/tools.ts

@@ -39,7 +39,7 @@ export function registerRuntimeTools(
 		'xplat_build',
 		{
 			description:
-				'Build the bound app for one platform as a background job (the same commands `xplat build` runs). Returns a job id — poll xplat_job_status and read output with xplat_logs. Repeating with the same requestKey returns the live job instead of duplicating it.',
+				'Build the bound app for one platform as a background job (the same commands `xplat build` runs). Returns a job id — poll xplat_job_status and read output with xplat_diagnostics. Repeating with the same requestKey returns the live job instead of duplicating it.',
 			inputSchema: {
 				platform: z.enum(PLATFORMS as Platform[]),
 				requestKey: z.string().optional().describe('Idempotence key for retries'),
@@ -57,13 +57,14 @@ export function registerRuntimeTools(
 		'xplat_launch',
 		{
 			description:
-				'Start an owned development session: bind one app to one target and run the platform dev command as a job. The job completes when readiness is confirmed — a failed launch after a successful build reports accurately, and the session keeps the app alive until xplat_session_end.',
+				'Start an owned development session: return one durable session id immediately. Read launch progress and readiness through xplat_sessions; diagnostics use the same session id, including after shutdown.',
 			inputSchema: {
-				platform: z.enum(PLATFORMS as Platform[]),
-				targetId: z
+				target: z
 					.string()
 					.optional()
-					.describe('Target from xplat_targets; required when several are available'),
+					.describe(
+						'Exact discovered target id or platform name; omit only when one eligible target exists',
+					),
 				requestKey: z.string().optional().describe('Idempotence key for retries'),
 				browserMode: z
 					.enum(['headless', 'headed'])
@@ -73,8 +74,8 @@ export function registerRuntimeTools(
 					),
 			},
 		},
-		async ({ platform, targetId, requestKey, browserMode }) => {
-			const result = await runtime.launch({ platform, targetId, requestKey, browserMode })
+		async ({ target, requestKey, browserMode }) => {
+			const result = await runtime.launch({ target, requestKey, browserMode })
 			return result.error
 				? respond({ ok: false, error: result.error })
 				: respond({ ok: true, data: result })
@@ -103,31 +104,22 @@ export function registerRuntimeTools(
 	)
 
 	server.registerTool(
-		'xplat_logs',
+		'xplat_diagnostics',
 		{
 			description:
-				'Bounded, ordered log read for a session or build job. Cursor-paginated: pass the previous nextCursor to continue; truncated/dropped flags reveal gaps and reset marks a restarted capture. A stopped or disconnected session reports its capture as historical.',
+				'List retained sessions or read logs and existing native report summaries. Log cursors do not page reports; reportId with sessionId reads a retained original. Session selectors include retained logs and native reports; standalone build jobs have log captures only.',
 			inputSchema: {
+				reportId: z.string().optional(),
+				platform: z.enum(PLATFORMS as Platform[]).optional(),
 				sessionId: z.string().optional(),
 				jobId: z.string().optional(),
-				cursor: z.number().optional().describe('Continue after this record seq'),
+				cursor: z.number().int().nonnegative().optional(),
 				limit: z.number().int().positive().max(5000).optional(),
 				stream: z.enum(['stdout', 'stderr', 'lifecycle']).optional(),
 			},
 		},
-		async ({ sessionId, jobId, cursor, limit, stream }) => {
-			if (!sessionId && !jobId) {
-				return respond({
-					ok: false,
-					error: {
-						code: 'invalid_selection',
-						message: 'Pass a sessionId or a jobId.',
-						recovery: { action: 'Use xplat_sessions or a build/launch job id.' },
-					},
-				})
-			}
-
-			const result = runtime.readLogs({ sessionId, jobId, cursor, limit, stream })
+		async (args) => {
+			const result = await runtime.readDiagnostics(args)
 			return result.error
 				? respond({ ok: false, error: result.error })
 				: respond({ ok: true, data: result })

package/src/server.ts

@@ -31,7 +31,7 @@ const INSTRUCTIONS =
 	'MCP server for Octane Xplat apps. Call xplat_project_status first — it reports detected apps, framework versions, guidance, prerequisites, and capabilities. ' +
 	'If several apps are detected, ask the developer which to use and bind it with xplat_select_app; never guess. ' +
 	'With a dev-mode app running, xplat_dev_actions lists the app-declared action registry and xplat_dev_action_invoke runs one against an exact instance and registry revision. ' +
-	'For runtime work, check xplat_capability_matrix then xplat_targets; xplat_launch starts an owned session as a job and xplat_attach binds a session you already run. ' +
+	'For runtime work, check xplat_capability_matrix then xplat_targets; xplat_launch returns a durable session identity and launch progress and xplat_attach binds a session you already run. ' +
 	'Results always say what was actually checked; a successful build is not proof of behavior.'
 
 const respond: Respond = (outcome) => ({
@@ -216,10 +216,15 @@ export function createXplatMcpServer(context: WorkspaceContext) {
 		'xplat_sessions',
 		{
 			description:
-				'List bound sessions: owned sessions the server started and attached user-owned sessions. Runtime tools bind one app to one target; attached sessions are preserved on end.',
-			inputSchema: {},
+				'List retained sessions or read exact sessionId status, including launch progress, failures and ended sessions. Attached user-owned apps are preserved on end.',
+			inputSchema: { sessionId: z.string().optional() },
+		},
+		async ({ sessionId }) => {
+			const result = sessionId
+				? context.runtime.sessionStatus(sessionId)
+				: context.runtime.listSessions()
+			return result.error ? fail(result.error) : ok(result)
 		},
-		async () => ok({ sessions: context.sessions.list() }),
 	)
 
 	server.registerTool(
@@ -261,12 +266,12 @@ export function createXplatMcpServer(context: WorkspaceContext) {
 			inputSchema: { sessionId: z.string() },
 		},
 		async ({ sessionId }) => {
-			const usable = context.sessions.requireUsable(sessionId)
-			if (!usable.usable && usable.error.code === 'not_found') {
-				return fail(usable.error)
+			try {
+				const result = await context.runtime.endSession(sessionId)
+				return result.error ? fail(result.error) : ok({ result })
+			} catch (error) {
+				return fail(toContractError(error))
 			}
-
-			return ok({ result: await context.runtime.endSession(sessionId) })
 		},
 	)
 

package/types/contracts/actions.d.ts

@@ -163,13 +163,26 @@ export type DevActionInvocationStatus =
 	/** The app may or may not have run the action; reported, never silently retried. */
 	| 'unknown'
 
+/** One handler's failure as structured data — which owner threw, and the error it threw. */
+export interface DevActionFailure {
+	/** 0-based position, in attach order, of the failing handler among the action's handlers at dispatch. */
+	handler: number
+	/** Optional owner label (e.g. component name) supplied at attach time. */
+	label?: string
+	name: string
+	message: string
+	stack?: string
+	/** Stack with frames resolved to original source positions by the dev server; present only when at least one frame resolved (web today). */
+	sourceStack?: string
+}
+
 export interface DevActionOutcome {
 	requestId: string
 	status: DevActionInvocationStatus
 	/** Structured result validated against the declared result contract. */
 	result?: Record<string, unknown>
 	/** Machine-readable failure detail; mapped to ContractError codes server-side. */
-	error?: { code: string; message: string }
+	error?: { code: string; message: string; failures?: DevActionFailure[] }
 	/** What the app knows changed before a failure/cancellation; absent = unknown. */
 	partialEffects?: string[]
 	completedAt: string

package/types/contracts/sessions.d.ts

@@ -7,7 +7,7 @@
  * preserves it). Restarting always establishes a new session identity; tools
  * refuse operations against stopped or disconnected sessions.
  *
- * Jobs are bounded units of work (build, launch, dev-action, …) whose status
+ * Jobs are bounded units of work (build, dev-action, …) whose status
  * is queryable without holding a tool call open. Repeating a request with the
  * same `requestKey` returns the live job instead of duplicating it.
  * Cancellation is cooperative: `cancelling` and `cancelled` are distinct
@@ -25,6 +25,8 @@ export const JOB_TERMINAL_STATES: readonly JobState[]
 export type SessionState =
 	/** Bound but not yet ready for observation/interaction. */
 	| 'starting'
+	/** Launch failed; retained diagnostics remain readable. */
+	| 'failed'
 	/** Ready — inspection, logs, and authorized interactions may proceed. */
 	| 'ready'
 	/** Lost contact; last-known data is historical evidence, never current state. */
@@ -57,6 +59,7 @@ export interface SessionBinding {
 	processKind: 'fresh' | 'warm' | null
 	buildIdentity?: BuildIdentity
 	detail?: string
+	launch?: { phase?: string; error?: ContractError; [key: string]: unknown }
 }
 
 export interface EndSessionResult {
@@ -78,7 +81,7 @@ export interface JobProgress {
 
 export interface Job {
 	jobId: string
-	/** e.g. `build`, `launch`, `attach`, `dev-action`. */
+	/** e.g. `build`, `dev-action`. */
 	kind: string
 	sessionId?: string
 	/** Idempotence key supplied by the caller or adapter. */
@@ -113,6 +116,7 @@ export interface StartJobResult {
 export interface SessionRegistry {
 	/** Start a server-owned session in `starting` state. `cleanup` runs on end/shutdown and must only release resources this session created. */
 	bindOwned(input: {
+		sessionId?: string
 		appId: string
 		platform: Platform
 		targetId: string
@@ -133,6 +137,9 @@ export interface SessionRegistry {
 	requireUsable(
 		sessionId: string,
 	): { usable: true; session: SessionBinding } | { usable: false; error: ContractError }
+	watch(fn: (session: SessionBinding) => void): () => void
+	setLaunch(sessionId: string, progress: Record<string, unknown>): void
+	markFailed(sessionId: string, error: ContractError): void
 	markReady(
 		sessionId: string,
 		meta?: { processKind?: 'fresh' | 'warm'; buildIdentity?: BuildIdentity },