@octane-xplat/mcp 0.1.0 → 0.15.0

package/src/contracts/policy.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Permission/policy contract. Workspace scope and ordinary runtime actions
+ * reuse the existing task authorization — policy is established once, not
+ * re-requested per tool call. Grants are scoped, revocable, optionally
+ * expiring, and checked at action time. `visual-capture` is never part of
+ * any baseline: the screenshot capability can exist while every actual
+ * capture still requires explicit per-task developer approval.
+ */
+
+import type { ContractError } from './errors'
+
+export const PERMISSION_SCOPES: readonly PermissionScope[]
+
+export type PermissionScope =
+	/** Read the selected workspace: manifests, config, source inventory. */
+	| 'workspace'
+	/** Build, launch, attach, and interact with development sessions. */
+	| 'runtime-actions'
+	/** Screenshot capture and any visual inspection of captured pixels. Never granted by task authorization alone. */
+	| 'visual-capture'
+	/** Persist evidence artifacts beyond the MCP session. */
+	| 'evidence-retain'
+	/** Effects outside the app itself (external services, destructive resets). Never implied by runtime-actions. */
+	| 'external-effects'
+
+export type GrantSource =
+	/** The developer authorized this task; covers workspace + runtime-actions only. */
+	| 'task-authorization'
+	/** An explicit developer approval for this task (e.g. via client elicitation). */
+	| 'developer'
+	/** A server startup flag/environment setting the developer configured. */
+	| 'server-config'
+
+export type GrantState = 'granted' | 'denied' | 'required'
+
+export interface PermissionGrant {
+	scope: PermissionScope
+	state: GrantState
+	source?: GrantSource
+	grantedAt?: string
+	/** ISO timestamp after which the grant no longer applies; absent = session-bound. */
+	expiresAt?: string
+	/** False only for server-internal baseline entries; everything the developer grants is revocable. */
+	revocable: boolean
+	note?: string
+}
+
+export type RequireResult =
+	| { granted: true; grant: PermissionGrant }
+	| { granted: false; error: ContractError }
+
+/**
+ * The channel that asks the developer for a grant — wired to the client's
+ * elicitation support when available. Returns the resulting state.
+ */
+export type GrantElicitor = (
+	scope: PermissionScope,
+	reason: string,
+) => Promise<'granted' | 'denied'> | 'granted' | 'denied'
+
+export interface PolicyStoreOptions {
+	/** The developer authorized this task — grants workspace + runtime-actions for the session. */
+	taskAuthorization?: boolean
+	/** Extra grants from server configuration (env/flags), e.g. a pre-approved visual-capture. */
+	grants?: PermissionGrant[]
+	/** Optional elicitation channel used by `requestGrant`. */
+	elicit?: GrantElicitor
+}
+
+export interface PolicyStore {
+	/** Synchronous check used at action time. Expired grants are denied. */
+	require(scope: PermissionScope): RequireResult
+	/**
+	 * Resolve a grant, asking the developer through the elicitation channel when
+	 * one exists. Without a channel, returns `required` state plus the recovery
+	 * text telling the developer how to grant it.
+	 */
+	requestGrant(scope: PermissionScope, reason: string): Promise<RequireResult>
+	grant(scope: PermissionScope, grant?: Partial<PermissionGrant>): PermissionGrant
+	revoke(scope: PermissionScope): boolean
+	list(): PermissionGrant[]
+	/** Late-bind the elicitation channel (it needs a connected client). */
+	setElicitor(elicit: GrantElicitor): void
+}
+
+export declare function createPolicyStore(options?: PolicyStoreOptions): PolicyStore

package/src/contracts/policy.mjs

@@ -0,0 +1,3 @@
+// Runtime contract moved to @octane-xplat/cli (shared agent service layer).
+// This shim preserves the @octane-xplat/mcp ./contracts export surface.
+export * from '@octane-xplat/cli/mcp/contracts/policy'

package/src/contracts/sessions.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Session, job, and ownership contract.
+ *
+ * A session binds one app to one target. Sessions are either `owned` (this
+ * server started them — ending releases their resources) or `attached`
+ * (a development session the user already had running — ending detaches and
+ * 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
+ * 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
+ * states, and cancelling a job only signals that job's own operation — it
+ * must never kill an unrelated app.
+ */
+
+import type { ContractError } from './errors'
+import type { Platform } from './identity'
+
+export const SESSION_STATES: readonly SessionState[]
+export const JOB_STATES: readonly JobState[]
+export const JOB_TERMINAL_STATES: readonly JobState[]
+
+export type SessionState =
+	/** Bound but not yet ready for observation/interaction. */
+	| 'starting'
+	/** Ready — inspection, logs, and authorized interactions may proceed. */
+	| 'ready'
+	/** Lost contact; last-known data is historical evidence, never current state. */
+	| 'disconnected'
+	/** Ended — identity is stale; a new run is a new sessionId. */
+	| 'stopped'
+
+export type SessionOwnership =
+	/** Started by this server; end releases owned resources. */
+	| 'owned'
+	/** Pre-existing user session; end detaches and preserves it. */
+	| 'attached'
+
+/** Build/source identity attached to observations so a new install is never mistaken for the running process. */
+export interface BuildIdentity {
+	buildId?: string
+	revision?: string
+	label?: string
+}
+
+export interface SessionBinding {
+	sessionId: string
+	appId: string
+	platform: Platform
+	targetId: string
+	ownership: SessionOwnership
+	state: SessionState
+	createdAt: string
+	/** `fresh` = new process; `warm` = iteration that retained process/module/OS state. */
+	processKind: 'fresh' | 'warm' | null
+	buildIdentity?: BuildIdentity
+	detail?: string
+}
+
+export interface EndSessionResult {
+	sessionId: string
+	ended: boolean
+	/** Owned resources released (processes, ports, temp dirs) — reported by the adapter. */
+	released?: string[]
+	/** What was deliberately left running — e.g. an attached user-owned session. */
+	preserved?: string[]
+}
+
+export type JobState = 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelling' | 'cancelled'
+
+export interface JobProgress {
+	phase?: string
+	percent?: number
+	message?: string
+}
+
+export interface Job {
+	jobId: string
+	/** e.g. `build`, `launch`, `attach`, `dev-action`. */
+	kind: string
+	sessionId?: string
+	/** Idempotence key supplied by the caller or adapter. */
+	requestKey?: string
+	state: JobState
+	progress?: JobProgress
+	result?: unknown
+	error?: ContractError
+	createdAt: string
+	finishedAt?: string
+}
+
+/** Adapter-provided work for a job. Receives the cooperative-cancel signal. */
+export type JobRunner = (
+	signal: AbortSignal,
+	report: (progress: JobProgress) => void,
+) => Promise<unknown>
+
+export interface StartJobOptions {
+	kind: string
+	sessionId?: string
+	requestKey?: string
+	run?: JobRunner
+}
+
+export interface StartJobResult {
+	job: Job
+	/** True when an identical live job already existed and was returned instead of starting a duplicate. */
+	deduplicated: boolean
+}
+
+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: {
+		appId: string
+		platform: Platform
+		targetId: string
+		cleanup?: () => Promise<{ released?: string[] } | void> | { released?: string[] } | void
+		detail?: string
+	}): SessionBinding
+	/** Bind an existing user-owned development session — never restarted or terminated by this server. */
+	attach(input: {
+		appId: string
+		platform: Platform
+		targetId: string
+		processKind?: 'fresh' | 'warm'
+		buildIdentity?: BuildIdentity
+		detail?: string
+	}): SessionBinding
+	get(sessionId: string): SessionBinding | null
+	/** The binding if usable, else a ContractError: `stale_identity` (stopped) or `disconnected_runtime`. */
+	requireUsable(
+		sessionId: string,
+	): { usable: true; session: SessionBinding } | { usable: false; error: ContractError }
+	markReady(
+		sessionId: string,
+		meta?: { processKind?: 'fresh' | 'warm'; buildIdentity?: BuildIdentity },
+	): SessionBinding | null
+	markDisconnected(sessionId: string, detail?: string): SessionBinding | null
+	end(sessionId: string): Promise<EndSessionResult>
+	/** End every owned session and detach attached ones. */
+	shutdown(): Promise<EndSessionResult[]>
+	list(): SessionBinding[]
+}
+
+export interface JobRegistry {
+	start(options: StartJobOptions): StartJobResult
+	status(jobId: string): Job | null
+	setProgress(jobId: string, progress: JobProgress): Job | null
+	succeed(jobId: string, result?: unknown): Job | null
+	fail(jobId: string, error: ContractError): Job | null
+	/** Cooperative cancellation; returns the job's resulting state. */
+	cancel(jobId: string): Job | null
+	/** Live and finished jobs (finished history is bounded). */
+	list(): Job[]
+}
+
+export declare function createSessionRegistry(): SessionRegistry
+export declare function createJobRegistry(options?: { historyLimit?: number }): JobRegistry

package/src/contracts/sessions.mjs

@@ -0,0 +1,3 @@
+// Runtime contract moved to @octane-xplat/cli (shared agent service layer).
+// This shim preserves the @octane-xplat/mcp ./contracts export surface.
+export * from '@octane-xplat/cli/mcp/contracts/sessions'

package/src/contracts/status.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The project-status report — the single externally observable shape returned
+ * by `xplat_project_status` at setup time. Later packages fill their own
+ * slots through registered providers; absent providers read as
+ * `not_provided`, never as healthy or silently absent.
+ */
+
+import type {
+	CodeIndexStatus,
+	DocsStatus,
+	GuidanceStatus,
+	ProjectIdentity,
+	RuntimePrerequisite,
+} from './identity'
+
+import type { PlatformCapabilityMatrix } from './capabilities'
+import type { PermissionGrant } from './policy'
+
+export interface ServerInfo {
+	name: string
+	version: string
+}
+
+export interface ProjectStatusReport {
+	server: ServerInfo
+	identity: ProjectIdentity
+	guidance: GuidanceStatus
+	docs: DocsStatus
+	codeIndex: CodeIndexStatus
+	/** Prerequisites relevant to the detected apps' declared platforms. */
+	prerequisites: RuntimePrerequisite[]
+	/** Matrix for the workspace's declared platforms. */
+	capabilities: PlatformCapabilityMatrix[]
+	/** Current permission grants and their states. */
+	permissions: PermissionGrant[]
+	/** What this product deliberately does not do. */
+	boundaries: readonly string[]
+	/** Ordered next steps for the agent, tailored to the report's actual state. */
+	nextSteps: string[]
+}

package/src/contracts/status.mjs

@@ -0,0 +1,3 @@
+// Runtime contract moved to @octane-xplat/cli (shared agent service layer).
+// This shim preserves the @octane-xplat/mcp ./contracts export surface.
+export * from '@octane-xplat/cli/mcp/contracts/status'

package/src/discovery.mjs

@@ -0,0 +1,2 @@
+// Moved to @octane-xplat/cli (shared agent service layer); re-exported for compatibility.
+export * from '@octane-xplat/cli/mcp/discovery'

package/src/docs.mjs

@@ -0,0 +1,84 @@
+// Docs tool registration (MCP adapter). The provider itself lives in the
+// shared service layer at @octane-xplat/cli/mcp/docs-provider — the CLI's
+// `docs`/`guidance` commands project the same service.
+import { z } from 'zod'
+import { contractError, toContractError } from './contracts/errors.mjs'
+import { PLATFORMS } from './contracts/identity.mjs'
+import { resolveSelection } from './status.mjs'
+
+export function registerDocsTools(server, context, respond) {
+	const run = (method) => async (args) => {
+		const permission = context.policy.require('workspace')
+		if (!permission.granted) {
+			return respond({ ok: false, error: permission.error })
+		}
+
+		const selection = resolveSelection(context)
+		if (selection.state !== 'bound') {
+			return respond({
+				ok: false,
+				error: contractError(
+					selection.state === 'ambiguous' ? 'ambiguous_selection' : 'invalid_selection',
+					'Bind an app with xplat_select_app before retrieving docs.',
+				),
+			})
+		}
+
+		try {
+			const data = await context.docs.serviceFor(selection.app)[method](args)
+			return respond({ ok: true, data })
+		} catch (error) {
+			return respond({ ok: false, error: toContractError(error) })
+		}
+	}
+
+	server.registerTool(
+		'xplat_docs_search',
+		{
+			description:
+				'Search the selected app’s installed-version docs. Results include version/snapshot provenance, unavailable packages, conflicts, and separately labeled project guidance.',
+			inputSchema: {
+				query: z.string().trim().min(1).max(500),
+				package: z.string().optional(),
+				version: z
+					.string()
+					.optional()
+					.describe('Explicit comparison version, visibly outside the installed binding.'),
+				platform: z.enum(PLATFORMS).optional(),
+				corpus: z
+					.enum(['guide', 'recipe', 'design-note', 'implementation-note'])
+					.optional()
+					.default('guide'),
+				limit: z.number().int().min(1).max(50).optional(),
+			},
+		},
+		run('search'),
+	)
+
+	server.registerTool(
+		'xplat_docs_read',
+		{
+			description:
+				'Read a bounded documentation page from a search ref, or package and path, preserving its version binding.',
+			inputSchema: {
+				ref: z.string().optional(),
+				package: z.string().optional(),
+				path: z.string().optional(),
+				version: z.string().optional(),
+				offset: z.number().int().min(0).optional(),
+				limit: z.number().int().min(1).max(20000).optional(),
+			},
+		},
+		run('read'),
+	)
+
+	server.registerTool(
+		'xplat_guidance',
+		{
+			description:
+				'Retrieve tailored guidance for the selected app’s actual installed package versions.',
+			inputSchema: {},
+		},
+		run('guidance'),
+	)
+}

package/src/inspection/service.mjs

@@ -0,0 +1,5 @@
+// The inspection service moved to @octane-xplat/cli (shared agent service
+// layer); the MCP tool registration lives in ./tools.mjs. Both names are
+// re-exported here so existing importers keep working.
+export { createInspectionService } from '@octane-xplat/cli/mcp/inspection/service'
+export { registerInspectionTools } from './tools.mjs'

package/src/inspection/tools.mjs

@@ -0,0 +1,53 @@
+// Inspection tool registration (MCP adapter). The service lives in the
+// shared layer at @octane-xplat/cli/mcp/inspection/service; this file only
+// binds it to MCP tools.
+import { z } from 'zod'
+
+export function registerInspectionTools(server, context, respond) {
+	const control = z.object({ kind: z.enum(['id', 'testID']), name: z.string().min(1).max(200) })
+	const run = (method) => async (args) => {
+		const data = await context.inspection[method](args)
+		return data.error ? respond({ ok: false, error: data.error }) : respond({ ok: true, data })
+	}
+
+	server.registerTool(
+		'xplat_inspect',
+		{
+			description:
+				'Bounded main-document named DOM hosts in the owned Chromium session. Explicit id/testID selector; duplicates fail. Password/private values are redacted. Includes document/session/build identity and coverage.',
+			inputSchema: {
+				sessionId: z.string(),
+				control: control.optional(),
+				offset: z.number().int().min(0).optional(),
+				limit: z.number().int().min(1).max(100).optional(),
+			},
+		},
+		run('inspect'),
+	)
+
+	server.registerTool(
+		'xplat_interact',
+		{
+			description:
+				'Send scoped input to one stable control from an inspected document. dom-event sends a CDP mouse click; os-input sends Space/Enter via the macOS event system to owned headed Chromium. Reserve desktop input for OS actions. Input delivery is not an app assertion.',
+			inputSchema: {
+				sessionId: z.string(),
+				documentId: z.string(),
+				control,
+				mechanism: z.enum(['dom-event', 'os-input']),
+				key: z.enum(['Space', 'Enter']).optional().default('Space'),
+			},
+		},
+		run('interact'),
+	)
+
+	server.registerTool(
+		'xplat_screenshot',
+		{
+			description:
+				'Capture the owned Chromium viewport only with a current visual-capture grant. Returns a session-scoped artifact and provenance; capability discovery never grants approval.',
+			inputSchema: { sessionId: z.string() },
+		},
+		run('screenshot'),
+	)
+}

package/src/runtime/logs.mjs

@@ -0,0 +1,2 @@
+// Moved to @octane-xplat/cli (shared agent service layer); re-exported for compatibility.
+export * from '@octane-xplat/cli/mcp/runtime/logs'

package/src/runtime/process.mjs

@@ -0,0 +1,2 @@
+// Moved to @octane-xplat/cli (shared agent service layer); re-exported for compatibility.
+export * from '@octane-xplat/cli/mcp/runtime/process'

package/src/runtime/service.mjs

@@ -0,0 +1,2 @@
+// Moved to @octane-xplat/cli (shared agent service layer); re-exported for compatibility.
+export * from '@octane-xplat/cli/mcp/runtime/service'

package/src/runtime/targets.mjs

@@ -0,0 +1,2 @@
+// Moved to @octane-xplat/cli (shared agent service layer); re-exported for compatibility.
+export * from '@octane-xplat/cli/mcp/runtime/targets'

package/src/runtime/tools.mjs

@@ -0,0 +1,126 @@
+// Runtime MCP tools (work item D). Thin bindings over the runtime service —
+// all session/job/ownership behavior lives in service.mjs and the shared
+// contracts.
+
+import { z } from 'zod'
+import { PLATFORMS } from '../contracts/identity.mjs'
+
+export function registerRuntimeTools(server, context, respond) {
+	const runtime = context.runtime
+
+	server.registerTool(
+		'xplat_targets',
+		{
+			description:
+				'Discover launchable targets for the bound app: simulators, emulators, devices and host targets with availability, missing-toolchain reasons, and session busy/ownership state.',
+			inputSchema: {
+				platform: z.enum(PLATFORMS).optional().describe('Limit to one platform'),
+			},
+		},
+		async ({ platform }) => {
+			const result = await runtime.listTargets({ platform })
+			return result.error
+				? respond({ ok: false, error: result.error })
+				: respond({ ok: true, data: result })
+		},
+	)
+
+	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.',
+			inputSchema: {
+				platform: z.enum(PLATFORMS),
+				requestKey: z.string().optional().describe('Idempotence key for retries'),
+			},
+		},
+		async ({ platform, requestKey }) => {
+			const result = await runtime.build({ platform, requestKey })
+			return result.error
+				? respond({ ok: false, error: result.error })
+				: respond({ ok: true, data: result })
+		},
+	)
+
+	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.',
+			inputSchema: {
+				platform: z.enum(PLATFORMS),
+				targetId: z
+					.string()
+					.optional()
+					.describe('Target from xplat_targets; required when several are available'),
+				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 }) => {
+			const result = await runtime.launch({ platform, targetId, requestKey, browserMode })
+			return result.error
+				? respond({ ok: false, error: result.error })
+				: respond({ ok: true, data: result })
+		},
+	)
+
+	server.registerTool(
+		'xplat_attach',
+		{
+			description:
+				'Attach to a compatible development session that is already running — never restarts or terminates it. Reports candidates per platform; attach binds a preserved user-owned session.',
+			inputSchema: {
+				platform: z.enum(PLATFORMS),
+				targetId: z
+					.string()
+					.optional()
+					.describe('Candidate target; required when several are attachable'),
+			},
+		},
+		async ({ platform, targetId }) => {
+			const result = await runtime.attach({ platform, targetId })
+			return result.error
+				? respond({ ok: false, error: result.error })
+				: respond({ ok: true, 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.',
+			inputSchema: {
+				sessionId: z.string().optional(),
+				jobId: z.string().optional(),
+				cursor: z.number().optional().describe('Continue after this record seq'),
+				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 })
+			return result.error
+				? respond({ ok: false, error: result.error })
+				: respond({ ok: true, data: result })
+		},
+	)
+}