@octane-xplat/mcp 0.1.0 → 0.15.0

package/src/contracts/capabilities.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Explicit capability matrix — per platform and target, each capability is
+ * reported separately. Unsupported or unqualified capabilities stay visible
+ * with an explanation and a usable alternative, never hidden or faked.
+ */
+
+import type { AppRef, Platform, RuntimePrerequisite } from './identity'
+import type { PermissionScope } from './policy'
+
+/** The externally observable capability surface. */
+export const CAPABILITY_IDS: readonly CapabilityId[]
+
+export type CapabilityId =
+	/** Detected project identity, versions, guidance, prerequisites (package A). */
+	| 'project_status'
+	/** Project-scoped guidance retrieval. */
+	| 'guidance'
+	/** Version-bound documentation search/read (package B). */
+	| 'docs'
+	/** Exact/semantic code discovery (package C). */
+	| 'code_search'
+	/** Device/target enumeration with availability and ownership (package D). */
+	| 'target_discovery'
+	/** Authorized build for a development session (package D). */
+	| 'build'
+	/** Launch a built app on a target (package D). */
+	| 'launch'
+	/** Attach to an existing compatible development session (package D). */
+	| 'attach'
+	/** Bounded, cursor-paginated logs with gap indicators (package D). */
+	| 'logs'
+	/** Job status/cancellation without holding a tool call open (package A+D). */
+	| 'job_control'
+	/** Qualified host-state inspection (package E). */
+	| 'ui_inspection'
+	/** Screenshot capture — always permission-gated at action time (package E). */
+	| 'screenshot'
+	/** Scoped interactions with an explicit mechanism (package E). */
+	| 'interaction'
+	/** App-declared development actions: discovery + invocation (package G). */
+	| 'dev_actions'
+	/** Ownership-safe session end (package A+D). */
+	| 'session_end'
+	/** Session-scoped evidence with retain/delete (package A). */
+	| 'evidence'
+
+export type CapabilityStatus =
+	/** Usable now on this platform/target. */
+	| 'supported'
+	/** Works within stated coverage limits; `detail` names them. */
+	| 'partial'
+	/** Exists, but every use is checked against a permission grant at action time. */
+	| 'permission_gated'
+	/** Achievable on this platform but a provider or prerequisite is absent. */
+	| 'unavailable'
+	/** Not possible on this platform; `detail` says why. */
+	| 'unsupported'
+	/** Not yet qualified; never presented as ready. */
+	| 'unknown'
+
+/** A usable path when a capability is not supported here. */
+export interface CapabilityAlternative {
+	description: string
+	/** A concrete command the developer can run, when one exists. */
+	command?: string
+}
+
+export interface CapabilityEntry {
+	capability: CapabilityId
+	status: CapabilityStatus
+	/** Why the capability is limited, missing, or gated — or its coverage bounds. */
+	detail?: string
+	/** The grant checked at action time (screenshots: 'visual-capture'). */
+	requiresPermission?: PermissionScope
+	prerequisites?: RuntimePrerequisite[]
+	alternative?: CapabilityAlternative
+}
+
+export interface PlatformCapabilityMatrix {
+	platform: Platform
+	/** Whether the bound app declares this platform. */
+	declared: boolean
+	capabilities: CapabilityEntry[]
+}
+
+/**
+ * A platform adapter supplied by a runtime package (D/E/G). Providers return
+ * entries only for capabilities they implement; everything else keeps the
+ * honest default from `defaultCapabilityEntry`.
+ */
+export interface CapabilityProvider {
+	platform: Platform
+	describe(app: AppRef): CapabilityEntry[] | Promise<CapabilityEntry[]>
+}
+
+export declare function defaultCapabilityEntry(
+	capability: CapabilityId,
+	platform: Platform,
+): CapabilityEntry
+
+export interface CapabilityRegistry {
+	register(provider: CapabilityProvider): void
+	matrixFor(app: AppRef | null, platforms: Platform[]): Promise<PlatformCapabilityMatrix[]>
+}
+
+export declare function createCapabilityRegistry(): CapabilityRegistry

package/src/contracts/capabilities.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/capabilities'

package/src/contracts/code.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Code retrieval contract (work item C) — the provider seam the workspace
+ * context's `code` slot and the `xplat_code_search` / `xplat_code_read` tools
+ * consume.
+ *
+ * Rules carried by the design:
+ * - Exact search reads current source files directly — it stays usable while
+ *   the semantic index is absent, preparing, stale, or failed.
+ * - Semantic search is optional local acceleration (no remote embedding
+ *   without explicit opt-in). Similarity rank is relevance, never evidence of
+ *   correctness or platform support.
+ * - Results are leads: every hit carries a ref, provenance, and a freshness
+ *   marker so the agent can open current source before citing an API.
+ * - Secrets, private configuration, generated output, and paths outside the
+ *   permitted corpus scope are never served.
+ */
+
+import type { AppRef, Platform, SubsystemState, WorkspaceKind } from './identity'
+
+/** `app` = the bound application's own source; `framework` = its installed @octane-xplat package sources. */
+export type CodeCorpus = 'app' | 'framework'
+
+export type CodeSearchMode = 'auto' | 'exact' | 'semantic'
+
+/** Per-hit freshness: `current` means revalidated or read live just now. */
+export interface CodeFreshness {
+	state: 'current' | 'stale'
+	/** Content hash at serve time — a later read with a different hash drifted. */
+	contentHash?: string
+	mtimeMs?: number
+}
+
+export interface CodeHitProvenance {
+	source: 'app-source' | 'framework-source'
+	scope: 'release' | 'project'
+	package?: string | null
+	requestedVersion?: string | null
+	servedVersion?: string | null
+	match:
+		| 'exact'
+		| 'verified-compatible'
+		| 'outside-installed-binding'
+		| 'unavailable'
+		| 'tag-conflict'
+	offline?: boolean
+}
+
+export interface CodeHit {
+	/** `xplat-code://<corpus>/<key>` — open it with xplat_code_read. */
+	ref: string
+	corpus: CodeCorpus
+	package?: string
+	/** Corpus-relative path (app: workspace-relative; framework: package source root). */
+	path: string
+	line: number
+	endLine: number
+	excerpt: string
+	matchType: 'exact' | 'semantic'
+	score?: number
+	freshness: CodeFreshness
+	provenance: CodeHitProvenance
+	/** Index revision that produced a semantic hit. */
+	indexRevision?: number
+	provisional?: boolean
+}
+
+export interface SemanticIndexStatus {
+	state: SubsystemState
+	/** e.g. 'local-tfidf' — remote embedding is never used without opt-in. */
+	backend?: string
+	detail?: string
+	files?: number
+	chunks?: number
+	truncated?: boolean
+	revision?: number
+	/** Hits dropped because they failed revalidation against current source. */
+	droppedStale?: number
+}
+
+export interface CodeSearchArgs {
+	app: AppRef | null
+	workspaceKind?: WorkspaceKind
+	query: string
+	mode?: CodeSearchMode
+	corpus?: CodeCorpus | 'all'
+	platform?: Platform
+	package?: string
+	limit?: number
+}
+
+export interface CodeSearchResult {
+	status?: CodeResultStatus
+	mode: CodeSearchMode
+	results: CodeHit[]
+	semantic: SemanticIndexStatus
+	coverage: unknown
+	/** Working-tree freshness marker (HEAD + uncommitted count) when git is available. */
+	tree?: string
+}
+
+export interface CodeReadArgs {
+	app: AppRef | null
+	workspaceKind?: WorkspaceKind
+	ref?: string
+	corpus?: CodeCorpus
+	package?: string
+	path?: string
+	offset?: number
+	limit?: number
+}
+
+export type CodeResultStatus =
+	| 'selection-required'
+	| 'invalid-selection'
+	| 'invalid-ref'
+	| 'out-of-scope'
+	| 'excluded'
+	| 'unavailable'
+
+export interface CodeErrorResult {
+	status: CodeResultStatus
+	reason?: string
+	detail?: string
+	corpus?: string
+	path?: string
+}
+
+/** The provider contract injected as `options.code` on the workspace context. */
+export interface CodeProvider {
+	/** Fills the project-status `codeIndex` slot. */
+	status(app: AppRef | null): unknown
+	search(args: CodeSearchArgs): CodeSearchResult | CodeErrorResult | Promise<unknown>
+	read(args: CodeReadArgs): unknown | Promise<unknown>
+}

package/src/contracts/code.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/code'

package/src/contracts/errors.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Shared error vocabulary for the Octane Xplat MCP server.
+ *
+ * Every tool failure is one of these codes — agents must be able to tell an
+ * invalid selection from a missing prerequisite, a busy target, a stale
+ * identity, a disconnected runtime, or a real execution failure. Each error
+ * names the smallest corrective action through `recovery`.
+ */
+
+export const CONTRACT_ERROR_CODES: readonly ContractErrorCode[]
+
+export type ContractErrorCode =
+	/** The named app, target, session, job, or option does not exist or does not apply. */
+	| 'invalid_selection'
+	/** Equally plausible choices would change the result — the developer must pick. Never resolved silently. */
+	| 'ambiguous_selection'
+	/** A required permission grant is absent, expired, or revoked. */
+	| 'permission_denied'
+	/** The platform/target does not support this capability; `alternative` may offer a usable path. */
+	| 'unsupported_capability'
+	/** A toolchain, device, or data prerequisite is missing; `recovery` names the smallest fix. */
+	| 'prerequisite_missing'
+	/** The target is owned by another session/agent, or a bounded queue is saturated. */
+	| 'target_busy'
+	/** The session, registry revision, or build identity changed since the caller bound it. */
+	| 'stale_identity'
+	/** The runtime disconnected; last-known state is historical evidence, never current state. */
+	| 'disconnected_runtime'
+	/** The operation ran and failed. */
+	| 'execution_failure'
+	/** The named resource (job, session, evidence record) does not exist. */
+	| 'not_found'
+	/** Cancellation won the race or was requested before/while running. */
+	| 'cancelled'
+	/** A bounded wait or execution timeout expired. */
+	| 'timeout'
+	/** An optional subsystem (docs index, code index, embeddings) is not provided or offline. */
+	| 'unavailable'
+
+/** The smallest corrective step a developer or agent can take. */
+export interface Recovery {
+	/** Imperative description, e.g. "Select an app with xplat_select_app". */
+	action: string
+	/** Optional concrete detail: a command, path, or env var. */
+	detail?: string
+}
+
+export interface ContractError {
+	code: ContractErrorCode
+	message: string
+	recovery?: Recovery
+	/** Whether retrying the same call could succeed without other changes. */
+	retryable?: boolean
+	/** Structured context, e.g. `candidates` for ambiguous_selection. */
+	context?: Record<string, unknown>
+}
+
+/** Success/failure envelope used by every MCP tool result's structuredContent. */
+export type ToolOutcome<T> = { ok: true; data: T } | { ok: false; error: ContractError }
+
+export declare function contractError(
+	code: ContractErrorCode,
+	message: string,
+	options?: { recovery?: Recovery; retryable?: boolean; context?: Record<string, unknown> },
+): ContractError
+
+export declare function ok<T>(data: T): ToolOutcome<T>
+export declare function fail(error: ContractError): ToolOutcome<never>
+export declare function isContractError(value: unknown): value is ContractError
+
+/** Normalize any thrown value into a ContractError (default code: execution_failure). */
+export declare function toContractError(
+	value: unknown,
+	fallbackCode?: ContractErrorCode,
+): ContractError

package/src/contracts/errors.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/errors'

package/src/contracts/evidence.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Evidence and retention contract.
+ *
+ * Evidence is session-scoped by default: when the MCP session ends, its
+ * artifacts are deleted. The developer may explicitly retain selected
+ * artifacts with a stated expiration or until manual deletion, and may delete
+ * retained evidence sooner. Deleting server artifacts cannot erase an
+ * external agent-client transcript that recorded them — that note travels
+ * with every retain/delete result (`TRANSCRIPT_LIMITATION_NOTE`).
+ *
+ * Every observation carries provenance: app, platform, target, session,
+ * build/source identity, capture time, and — for interactions — the
+ * mechanism. `handler-dispatch` and `dom-event` evidence must never be
+ * presented as OS-input verification (`isOsInputEvidence`).
+ */
+
+import type { BuildIdentity } from './sessions'
+import type { Platform } from './identity'
+import type { ContractError } from './errors'
+
+export const EVIDENCE_KINDS: readonly EvidenceKind[]
+export const INTERACTION_MECHANISMS: readonly InteractionMechanism[]
+/** Included in retain/delete results: deletion here never touches the client transcript. */
+export const TRANSCRIPT_LIMITATION_NOTE: string
+
+export type EvidenceKind =
+	| 'log'
+	| 'screenshot'
+	| 'inspection'
+	| 'interaction'
+	| 'measurement'
+	| 'assertion'
+	| 'job'
+	| 'note'
+
+export type InteractionMechanism =
+	/** App handler invoked directly — proves handler behavior only. */
+	| 'handler-dispatch'
+	/** Synthesized DOM/platform events — proves event-path behavior, not OS hit-testing. */
+	| 'dom-event'
+	/** Real OS input path — can support OS-level claims. */
+	| 'os-input'
+	/** Not an interaction record. */
+	| 'none'
+
+export interface EvidenceProvenance {
+	appId?: string
+	platform?: Platform
+	targetId?: string
+	sessionId?: string
+	buildIdentity?: BuildIdentity
+	/** ISO capture time. */
+	capturedAt: string
+	mechanism?: InteractionMechanism
+}
+
+export type EvidenceRetention =
+	/** Deleted when the MCP session ends (the default). */
+	| { scope: 'session' }
+	/** Kept until `expiresAt` (null = until manual deletion). */
+	| { scope: 'retained'; expiresAt: string | null }
+
+export interface EvidenceRecord {
+	id: string
+	kind: EvidenceKind
+	summary: string
+	provenance: EvidenceProvenance
+	/** File path under the evidence root, for binary/large artifacts. */
+	artifactPath?: string
+	/** Small structured payload kept in memory. */
+	data?: unknown
+	retention: EvidenceRetention
+	createdAt: string
+}
+
+export interface RetainResult {
+	record: EvidenceRecord
+	transcriptNote: string
+}
+
+export interface DeleteResult {
+	deleted: boolean
+	transcriptNote: string
+}
+
+export interface EvidenceStore {
+	record(input: {
+		kind: EvidenceKind
+		summary: string
+		provenance: Omit<EvidenceProvenance, 'capturedAt'> & { capturedAt?: string }
+		data?: unknown
+		/** Write this content as the artifact file (utf8). */
+		artifact?: string | Uint8Array
+		/** Suggested artifact file name; sanitized. */
+		artifactName?: string
+	}): EvidenceRecord
+	list(filter?: { sessionId?: string; kind?: EvidenceKind }): EvidenceRecord[]
+	/** Move a record out of session scope. `expiresAt` ISO string or null for manual deletion. */
+	retain(
+		id: string,
+		options?: { expiresAt?: string | null },
+	): RetainResult | { error: ContractError }
+	delete(id: string): DeleteResult | { error: ContractError }
+	/** Delete retained records past their expiration. */
+	sweepExpired(now?: Date): number
+	/** Session end: delete every session-scoped record and its artifact file. */
+	closeSession(): { deleted: number }
+	/** Absolute path of the evidence root for this server session. */
+	readonly root: string
+}
+
+/** True only for evidence captured through the real OS input path. */
+export declare function isOsInputEvidence(record: EvidenceRecord): boolean
+
+export declare function createEvidenceStore(options: { root: string }): EvidenceStore

package/src/contracts/evidence.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/evidence'

package/src/contracts/identity.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Project identity contract — what the server detects and reports about the
+ * developer's workspace during setup, and the shape of the project-status
+ * report every later package (docs, code, runtime) plugs into.
+ */
+
+export const PLATFORMS: readonly Platform[]
+
+/** The six release-boundary targets. `web` means Chromium acceptance checks. */
+export type Platform = 'web' | 'ios' | 'android' | 'macos' | 'linux' | 'windows'
+
+/** A detected application inside the selected workspace. */
+export interface AppRef {
+	/** Stable identity for selection and binding: workspace-relative root path ('.' for the root app). */
+	id: string
+	/** package.json name, falling back to the directory basename. */
+	name: string
+	/** Absolute path. */
+	root: string
+	/** Path relative to the workspace root. */
+	relativeRoot: string
+	/**
+	 * `consumer-app` — a deployable Octane Xplat application (the primary setup path).
+	 * `framework-package` — a package inside the octane-xplat framework repository
+	 * (identified separately, never silently treated as the consumer app).
+	 */
+	kind: 'consumer-app' | 'framework-package'
+	/** Platforms this app declares (from its config and dependencies). */
+	platforms: Platform[]
+}
+
+/** Where a package version came from. `installed` is the only version that binds docs. */
+export type VersionSource = 'installed' | 'workspace' | 'lockfile' | 'unresolved'
+
+export interface PackageVersion {
+	/** e.g. `@octane-xplat/ui`. */
+	name: string
+	version: string | null
+	source: VersionSource
+	/** The declared range in the app's manifest, when it differs from the resolved version. */
+	declared?: string
+}
+
+export interface FrameworkBinding {
+	packages: PackageVersion[]
+	/**
+	 * `installed` — resolved from the app's actual node_modules (binds documentation).
+	 * `provisional` — lockfile/declared only; the real install could not be verified.
+	 * `unresolved` — no version information at all.
+	 */
+	status: 'installed' | 'provisional' | 'unresolved'
+	/** Set when the lockfile and the actual installation disagree; installation wins. */
+	discrepancy?: string
+}
+
+export interface GuidanceSource {
+	kind: 'agents-md' | 'claude-md' | 'devin' | 'framework' | 'other'
+	/** Workspace-relative path. */
+	path: string
+}
+
+/** Project-level guidance the agent should read; never mixed into generic docs results. */
+export interface GuidanceStatus {
+	sources: GuidanceSource[]
+}
+
+/** Optional-subsystem readiness. `not_provided` = no provider registered yet. */
+export type SubsystemState = 'ready' | 'preparing' | 'stale' | 'unavailable' | 'not_provided'
+
+export interface DocsStatus {
+	state: SubsystemState
+	/** e.g. which version binding is active, or why docs are unavailable. */
+	detail?: string
+}
+
+export interface CodeIndexStatus {
+	state: SubsystemState
+	detail?: string
+	/** Human-readable freshness marker (index revision vs working tree). */
+	freshness?: string
+}
+
+export type PrerequisiteStatus = 'satisfied' | 'missing' | 'unknown'
+
+export interface RuntimePrerequisite {
+	/** Stable id: `node`, `git`, `pnpm`, `xcode`, `adb`, `nativescript-cli`, `chromium`, … */
+	id: string
+	name: string
+	status: PrerequisiteStatus
+	/** e.g. the found version, or where it was looked for. */
+	detail?: string
+	/** The smallest corrective action when missing/unknown. */
+	remedy?: string
+	/** Platforms this prerequisite gates; absent = server-wide. */
+	platforms?: Platform[]
+}
+
+/** The workspace as a whole. */
+export type WorkspaceKind =
+	/** A consumer application workspace (single- or multi-app monorepo). */
+	| 'consumer'
+	/** The octane-xplat framework repository itself — framework sources are a separate corpus. */
+	| 'framework-repo'
+	/** No Octane Xplat app detected. */
+	| 'empty'
+
+export interface WorkspaceInfo {
+	root: string
+	kind: WorkspaceKind
+}
+
+/**
+ * App selection state. `ambiguous` is a first-class state: the server never
+ * silently picks among multiple apps — the developer (via the agent) must choose.
+ */
+export type AppSelection =
+	| { state: 'bound'; app: AppRef; reason: 'explicit' | 'sole-app' | 'configured' | 'preference' }
+	| { state: 'ambiguous'; candidates: AppRef[] }
+	| { state: 'none'; reason: 'no-apps' | 'workspace-not-found' }
+
+export interface ProjectIdentity {
+	workspace: WorkspaceInfo
+	apps: AppRef[]
+	selection: AppSelection
+	/** Framework versions for the bound app (null while selection is ambiguous/none). */
+	framework: FrameworkBinding | null
+}

package/src/contracts/identity.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/identity'

package/src/contracts/index.d.ts

@@ -0,0 +1,11 @@
+export * from './errors'
+export * from './identity'
+export * from './capabilities'
+export * from './policy'
+export * from './sessions'
+export * from './evidence'
+export * from './boundaries'
+export * from './status'
+export * from './code'
+export * from './actions'
+export * from './inspection'

package/src/contracts/index.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/index'

package/src/contracts/inspection.d.ts

@@ -0,0 +1,45 @@
+import type { EvidenceRecord } from './evidence'
+
+/** Qualified scope of Chromium inspection; never a universal component tree. */
+export const CHROMIUM_INSPECTION_COVERAGE: string
+
+/** Select exactly one named DOM host. Duplicate names fail rather than choosing the first. */
+export interface StableControl {
+	kind: 'id' | 'testID'
+	name: string
+}
+
+export interface InspectedHost {
+	id: string | null
+	testID: string | null
+	tag: string
+	role: string | null
+	/** Bounded to 500 characters; password and data-xplat-private hosts are redacted. */
+	text: string
+	value: string | null
+	checked: boolean | null
+	disabled: boolean
+	hidden: boolean
+	sensitive: boolean
+	focused: boolean
+	hitTarget: boolean
+	/** Main-document CSS pixels, relative to the viewport. */
+	frame: { x: number; y: number; width: number; height: number }
+}
+
+/** Returned by xplat_inspect; documentId must accompany subsequent interactions. */
+export interface HostInspection {
+	documentId: string
+	controls: InspectedHost[]
+	coverage: string
+	limitations: string[]
+	total: number
+	nextOffset: number | null
+	evidence: EvidenceRecord
+}
+
+/** Input submission proves delivery only; observe and assert the intended state separately. */
+export interface HostInteraction extends HostInspection {
+	inputSent: true
+	assertion: string
+}

package/src/contracts/inspection.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/inspection'