@octane-xplat/mcp 0.1.0 → 0.16.0

package/types/contracts/actions.d.ts

@@ -0,0 +1,209 @@
+/**
+ * App-declared development-action contract (design: plans/octane-xplat-mcp.md,
+ * "App-declared development actions").
+ *
+ * The app owns action semantics; the framework owns discovery and invocation.
+ * A dev-mode app announces a registry snapshot (identity + revision + typed
+ * declarations) over a platform bridge; this server lists the live registry
+ * and invokes actions through that same bridge. The declaration is the single
+ * source of truth: handler, runtime-validatable input/result contracts, and
+ * metadata all travel in one announcement — there are no MCP-side per-action
+ * definitions.
+ *
+ * Wire invariants:
+ * - Every registry carries `appInstanceId` — each running app realm (tab,
+ *   window, device process) is a distinct invocation destination. Calls are
+ *   never silently shared or redirected.
+ * - `revision` increments on every registry change (add/change/remove, owner
+ *   disposal, hot reload). Invocation presents the revision it read; a stale
+ *   revision is rejected with `stale_identity` before anything runs.
+ * - Announcements are heartbeats: a stopped heartbeat marks the instance
+ *   `disconnected` — a live app with zero actions still announces, so an
+ *   empty registry is always distinguishable from a disconnected runtime.
+ */
+
+import type { ContractError } from './errors'
+import type { Platform } from './identity'
+
+export const DEV_ACTIONS_PROTOCOL = 'xplat-dev-actions'
+export const DEV_ACTIONS_PROTOCOL_VERSION = 1
+/** Heartbeat interval the app-side bridge uses; instances quieter than this ×3 are stale. */
+export const DEV_ACTIONS_ANNOUNCE_INTERVAL_MS: number
+export const DEV_ACTIONS_STALE_AFTER_MS: number
+/** Bounded pending-invocation queue per instance; saturation returns `target_busy`. */
+export const DEV_ACTIONS_QUEUE_LIMIT: number
+/** Cap on overlapping invocations per instance (declared `overlap` actions). */
+export const DEV_ACTIONS_OVERLAP_LIMIT: number
+/** Default and maximum execution timeouts. */
+export const DEV_ACTIONS_DEFAULT_TIMEOUT_MS: number
+export const DEV_ACTIONS_MAX_TIMEOUT_MS: number
+
+// ---------- declaration contract ----------
+
+/** Runtime-validatable field subset. `fields`/`items` allow one level of structure. */
+export interface DevActionField {
+	type: 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array'
+	description?: string
+	/** Applied when the caller omits the field. */
+	default?: unknown
+	/** Closed value set. */
+	enum?: readonly unknown[]
+	minLength?: number
+	maxLength?: number
+	/** Regular expression source (must compile). */
+	pattern?: string
+	minimum?: number
+	maximum?: number
+	minItems?: number
+	maxItems?: number
+	/** For `object`: named nested fields. Defaults apply to top-level fields only. */
+	fields?: Record<string, DevActionField>
+	/** For `array`: element contract. */
+	items?: DevActionField
+}
+
+/** Named typed fields. `{}` (or omitted) means the action takes no arguments. */
+export interface DevActionFields {
+	fields?: Record<string, DevActionField>
+}
+
+/**
+ * Disclosed effect categories — the agent reads these to decide whether an
+ * action fits the existing authorization. `externalEffects` maps to the
+ * `external-effects` permission scope and is checked at invocation time.
+ */
+export interface DevActionEffects {
+	/** Plain-language summary of what the action changes. */
+	summary: string
+	auth?: boolean
+	navigation?: boolean
+	appState?: boolean
+	testData?: boolean
+	/** Effects outside the app itself — external test services, destructive resets. */
+	externalEffects?: boolean
+}
+
+export type DevActionConcurrency =
+	/** Default: actions for one app instance run one at a time through a bounded queue. */
+	| 'serialized'
+	/** The app declares this action safe to overlap with other executions. */
+	| 'overlap'
+
+export interface DevActionExecution {
+	concurrency?: DevActionConcurrency
+	/** Cooperative cancellation supported by the handler. */
+	cancellable?: boolean
+	/** Safe to retry (idempotent). Non-retryable actions never auto-rerun. */
+	retryable?: boolean
+	/** Per-action execution deadline; bounded by DEV_ACTIONS_MAX_TIMEOUT_MS. */
+	timeoutMs?: number
+}
+
+export interface DevActionDeclaration {
+	/** Stable machine identity, e.g. `auth.login-as-test-admin`. */
+	id: string
+	title: string
+	/** When to use it and what successful completion means. */
+	description: string
+	input?: DevActionFields
+	result?: DevActionFields
+	effects: DevActionEffects
+	availability?: {
+		/** Platforms this action applies to; absent = all. */
+		platforms?: Platform[]
+		/** Readiness conditions outside platform selection (free text). */
+		readyWhen?: string
+	}
+	execution?: DevActionExecution
+}
+
+/** Declared action plus its live availability, as announced by the app. */
+export interface DevActionListing extends DevActionDeclaration {
+	availability?: {
+		platforms?: Platform[]
+		readyWhen?: string
+		/** Live readiness verdict from the app. */
+		ready: boolean
+		/** Why it is unavailable right now. */
+		reason?: string
+	}
+}
+
+// ---------- registry announcement ----------
+
+export interface DevActionRegistryAnnouncement {
+	protocol: typeof DEV_ACTIONS_PROTOCOL
+	version: number
+	/** Unique per app realm — survives hot reload, never crosses processes. */
+	appInstanceId: string
+	/** App-supplied label for the developer, e.g. package name or window title. */
+	appLabel?: string
+	platform: Platform
+	revision: number
+	announcedAt: string
+	actions: DevActionListing[]
+}
+
+// ---------- invocation ----------
+
+export interface DevActionInvocationRequest {
+	/** Stable request identity — retries with the same requestId must not re-run the effect. */
+	requestId: string
+	appInstanceId: string
+	actionId: string
+	/** The registry revision the caller discovered; rejected when stale. */
+	registryRevision: number
+	input: Record<string, unknown>
+}
+
+export type DevActionInvocationStatus =
+	| 'succeeded'
+	| 'failed'
+	| 'cancelled'
+	/** The app may or may not have run the action; reported, never silently retried. */
+	| 'unknown'
+
+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 }
+	/** What the app knows changed before a failure/cancellation; absent = unknown. */
+	partialEffects?: string[]
+	completedAt: string
+}
+
+/** What `validateActionInput` returns. */
+export type DevActionInputResult =
+	| { ok: true; value: Record<string, unknown> }
+	| { ok: false; errors: string[] }
+
+// ---------- validators (shared with the app-side implementation) ----------
+
+/** Declaration sanity: id shape, required metadata, compilable field patterns. */
+export declare function validateActionDeclaration(action: unknown): string[]
+
+/** Type-check + apply defaults + reject undeclared fields. */
+export declare function validateActionInput(
+	contract: DevActionFields | undefined,
+	input: unknown,
+): DevActionInputResult
+
+/** Result-contract validation. An invalid output fails explicitly — it does not undo a ran action. */
+export declare function validateActionOutput(
+	contract: DevActionFields | undefined,
+	output: unknown,
+): DevActionInputResult
+
+/** Structural check on an announcement payload. */
+export declare function isDevActionAnnouncement(
+	value: unknown,
+): value is DevActionRegistryAnnouncement
+
+/** Live availability for an announced action on a given platform. */
+export declare function actionAvailability(
+	action: DevActionListing,
+	platform: Platform,
+): { ready: boolean; reason?: string }

package/types/contracts/boundaries.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Product boundaries — what this server deliberately does not do, surfaced in
+ * the project-status report so agents don't probe for excluded features.
+ */
+
+export const PRODUCT_BOUNDARIES: readonly string[]

package/types/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/types/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/types/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/types/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