vgxness 0.1.0 → 0.1.1-alpha.0

package/dist/mcp/control-plane.js

@@ -11,6 +11,8 @@ import { OpenCodeManagerPayloadService } from '../providers/opencode/manager-pay
 import { RunService } from '../runs/run-service.js';
 import { errorEnvelope, successEnvelope } from './schema.js';
 import { validateVgxMcpToolCall } from './validation.js';
+import { ProviderStatusService } from './provider-status.js';
+import { ProviderDoctorService } from './provider-doctor.js';
 export function callVgxTool(call, services) {
     const validated = validateVgxMcpToolCall(call);
     if (!validated.ok)
@@ -68,6 +70,14 @@ export function callVgxTool(call, services) {
             return toEnvelope(validated.tool, services.runs.appendCheckpoint(validated.input));
         case 'vgxness_run_finalize':
             return toEnvelope(validated.tool, services.runs.updateFinalStatus(validated.input));
+        case 'vgxness_provider_status':
+            if (services.providerStatus === undefined)
+                return errorEnvelope('validation_failed', 'Provider status service is not available', validated.tool);
+            return toEnvelope(validated.tool, services.providerStatus.getStatus(validated.input));
+        case 'vgxness_provider_doctor':
+            if (services.providerDoctor === undefined)
+                return errorEnvelope('validation_failed', 'Provider doctor service is not available', validated.tool);
+            return toEnvelope(validated.tool, services.providerDoctor.getDoctor(validated.input));
     }
     return errorEnvelope('validation_failed', 'Tool dispatch is not implemented');
 }
@@ -121,6 +131,8 @@ function createServices(database) {
         opencodeManagerPayload,
         activation: new AgentActivationService({ agents, managerProfiles, runs, opencodeManagerPayload }),
         runs,
+        providerStatus: new ProviderStatusService({ sdd: new SddWorkflowService(memory, { actor: 'mcp-control-plane' }) }),
+        providerDoctor: new ProviderDoctorService(),
     };
 }
 function getManagerProfileEnvelope(input, services) {

package/dist/mcp/index.js

@@ -7,4 +7,7 @@ export * from './client-install-opencode-contract.js';
 export * from './client-install-opencode.js';
 export * from './doctor.js';
 export * from './opencode-visibility.js';
+export * from './provider-health-types.js';
+export * from './provider-status.js';
+export * from './provider-doctor.js';
 export * from '../providers/opencode/manager-payload.js';

package/dist/mcp/opencode-default-agent-config.js

@@ -1,4 +1,5 @@
 export const vgxnessOpenCodeDefaultAgent = 'vgxness-manager';
+export const vgxnessOpenCodePromptContractVersion = 2;
 export const vgxnessOpenCodeSddSubagents = [
     'vgxness-sdd-explore',
     'vgxness-sdd-propose',
@@ -28,7 +29,7 @@ export function createOpenCodeDefaultAgentConfig() {
             description: 'VGXNESS SDD Manager - coordinates MCP state and SDD sub-agents, avoids inline execution when delegation is safer',
             mode: 'primary',
             model: 'openai/gpt-5.5',
-            options: { reasoningEffort: 'high' },
+            options: { reasoningEffort: 'high', vgxnessPromptContractVersion: vgxnessOpenCodePromptContractVersion },
             permission: { task: createOpenCodeSddTaskPermissions() },
             prompt: vgxnessManagerPrompt,
             reasoningEffort: 'high',
@@ -54,6 +55,7 @@ export function createOpenCodeDefaultAgentConfig() {
             hidden: true,
             mode: 'subagent',
             model: 'openai/gpt-5.5',
+            options: { vgxnessPromptContractVersion: vgxnessOpenCodePromptContractVersion },
             prompt: createSddSubagentPrompt(name),
             tools: { bash: true, edit: true, read: true, write: true },
         };
@@ -75,7 +77,7 @@ function createSddSubagentPrompt(name) {
         'vgxness-sdd-init': 'Bootstrap SDD context and project setup safely. Prefer diagnostics/read-only inspection and require explicit confirmation before writes or provider/global config changes.',
         'vgxness-sdd-onboard': 'Guide the user through the SDD cycle with the smallest missing decision at each step. Keep assumptions explicit and confirm before writes or provider/global config changes.',
     };
-    return `${common}\n\nPhase contract: ${contracts[name]}`;
+    return `${common}\n\nPhase contract: ${contracts[name]}\n\nProvider-native daily progression: daily SDD progression happens inside OpenCode through conversation, VGXNESS MCP, and hidden SDD subagents. Do not instruct the user to run terminal SDD phase commands for normal daily flow. Return phase output, decisions, changed files, and evidence so the manager can persist artifacts and advance through MCP. Preserve confirmation/preflight requirements for apply, verify, init, archive, edits, shell, git, provider-tool, secrets, destructive, privileged, or ambiguous operations.`;
 }
 const vgxnessManagerPrompt = `# VGXNESS Manager - SDD Orchestrator Instructions
 
@@ -91,15 +93,21 @@ Act with the personality configured for VGXNESS: direct, practical, grounded in
 
 Use the \`vgxness\` MCP server as the source of durable workflow state. MCP tools coordinate and persist. OpenCode sub-agent delegation performs phase work. Do not rely on external \`sdd-*\` skill files; default manager and subagent contracts are inline.
 
+## Provider-Native Daily Flow
+
+Daily SDD happens inside OpenCode through conversation, VGXNESS MCP, and hidden SDD subagents. Use \`vgxness_provider_status\` for configured/phase/next questions and \`vgxness_provider_doctor\` for OpenCode MCP/manager health. CLI is an escape hatch for bootstrap, doctor, rollback, recovery, MCP unavailable/setup missing, provider-native repair being out of scope, or an explicit user request. For normal daily progression, do not tell the user to run terminal SDD phase commands; advance by checking MCP state, delegating hidden phase subagents, and persisting accepted outputs through MCP.
+
 ## MCP Tool Playbook
 
 - SDD state and artifacts: use \`vgxness_sdd_status\`, \`vgxness_sdd_next\`, and \`vgxness_sdd_ready\` before advancing phases; read prerequisites with \`vgxness_sdd_get_artifact\` or \`vgxness_sdd_list_artifacts\`; persist accepted phase output with \`vgxness_sdd_save_artifact\`. SDD artifacts are not generic memory.
+- Provider status/doctor: use \`vgxness_provider_status\` for provider configuration, phase, and next-action questions; use \`vgxness_provider_doctor\` for read-only OpenCode MCP/manager health checks. These tools report only and do not install, repair, or mutate provider config.
 - Session lifecycle: when starting, resuming, or recovering context, call \`vgxness_session_restore\` with the project and workspace directory before inferring state from chat. Before ending, pausing, handing off, or compacting, call \`vgxness_session_close\` with the current session id, actor \`manager\`, and a concise actionable summary. If no current session id is available, do not invent one; state that clearly and preserve the actionable summary in the final response.
 - Memory: use \`vgxness_memory_search\` at the start when the user references previous work, remembered decisions, prior solutions, or unclear project context; use \`vgxness_memory_get\` for full relevant results; use \`vgxness_memory_save\` immediately after durable discoveries, decisions, bug fixes, configuration changes, patterns, or preferences; use \`vgxness_memory_update\` when correcting/evolving a known observation id. Do not duplicate full SDD artifacts as memory.
 - Agents: use \`vgxness_agent_resolve\` with project/scope/workflow/phase/provider/mode before substantial SDD phase execution. \`vgxness_agent_activate\` prepares provider-ready context/run payloads only; it does not execute a provider or write provider config.
 - Manager/profile and payloads: use \`vgxness_manager_profile_get\` before changing manager behavior. \`vgxness_manager_profile_set\` is a persistent behavior change and requires explicit human confirmation. \`vgxness_skill_payload\` builds context only and does not install skill files. \`vgxness_opencode_manager_payload\` is a read-only preview; it does not install, execute, load seeds, or write provider config.
 - Runs: simple questions do not require runs by default. For significant implementation, verification, risky, or multi-step delegated work, create or recover state with \`vgxness_run_start\`, \`vgxness_run_list\`, and \`vgxness_run_get\`; record progress with \`vgxness_run_checkpoint\`; call \`vgxness_run_preflight\` before edit, shell, git, network, external-directory, provider-tool, secrets, privileged, destructive, or ambiguous operations; close clear outcomes with \`vgxness_run_finalize\`.
 - Safety: do not call MCP with unsupported execution/config fields such as \`executeProvider\` or \`writesProviderConfig\`. Do not mutate provider/global OpenCode config unless the user explicitly asks for install/apply/configuration changes.
+- Terminal leakage: do not give terminal SDD phase commands for normal daily flow. Mention CLI only as an escape hatch for bootstrap, doctor, rollback, recovery, MCP unavailable/setup missing, provider-native repair being out of scope, or an explicit user request.
 
 ## Request Type -> Minimum MCP Sequence
 

package/dist/mcp/provider-doctor.js

@@ -0,0 +1,121 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { PROVIDER_HEALTH_SAFETY, REQUIRED_PROVIDER_NATIVE_MCP_TOOLS, normalizeProviderHealthInput, providerHealthFailure, rollupProviderDoctor } from './provider-health-types.js';
+import { vgxnessOpenCodeDefaultAgent, vgxnessOpenCodeSddSubagents } from './opencode-default-agent-config.js';
+import { inspectProjectConfigPaths } from './provider-status.js';
+export class ProviderDoctorService {
+    runDoctor(input = {}) {
+        return this.getDoctor(input);
+    }
+    getDoctor(input = {}) {
+        const normalized = normalizeProviderHealthInput(input);
+        if (normalized.providerAdapter !== 'opencode')
+            return providerHealthFailure(`Unsupported provider adapter: ${normalized.providerAdapter}`);
+        const paths = inspectProjectConfigPaths(normalized.workspaceRoot);
+        const before = snapshotPaths(paths.map((path) => path.path), normalized.workspaceRoot);
+        const readableJson = paths.filter((path) => path.parsed);
+        const config = readFirstConfig(readableJson[0]?.path);
+        const checks = [
+            { id: 'workspace-root', status: existsSync(normalized.workspaceRoot) ? 'pass' : 'fail', detail: `Workspace root ${existsSync(normalized.workspaceRoot) ? 'exists' : 'does not exist'}: ${normalized.workspaceRoot}` },
+            { id: 'provider-supported', status: 'pass', detail: 'OpenCode provider adapter selected.' },
+            configReadableCheck(readableJson.length, paths.filter((path) => path.exists).length),
+            mcpEntryCheck(config),
+            defaultAgentCheck(config),
+            subagentsCheck(config),
+            delegationCheck(config),
+            { id: 'mcp-current-call', status: 'pass', detail: 'Current MCP call reached the VGXNESS control-plane.' },
+            { id: 'mcp-required-tools', status: 'pass', detail: `Required provider-native tools are registered: ${REQUIRED_PROVIDER_NATIVE_MCP_TOOLS.join(', ')}.` },
+            promptContractCheck(config, normalized.expectedPromptContractVersion),
+            readonlySafetyCheck(before, snapshotPaths(paths.map((path) => path.path), normalized.workspaceRoot)),
+        ];
+        return {
+            ok: true,
+            value: {
+                version: 1,
+                kind: 'provider-doctor',
+                project: normalized.project,
+                providerAdapter: normalized.providerAdapter,
+                scope: normalized.scope,
+                workspaceRoot: normalized.workspaceRoot,
+                status: rollupProviderDoctor(checks.map((check) => check.status)),
+                checks,
+                checkedPaths: paths.map((path) => path.path),
+                safety: PROVIDER_HEALTH_SAFETY,
+            },
+        };
+    }
+}
+function readFirstConfig(path) {
+    if (path === undefined)
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        return isRecord(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function configReadableCheck(readableCount, existingCount) {
+    if (existingCount === 0)
+        return { id: 'opencode-config-readable', status: 'not-configured', detail: 'No OpenCode project config path exists.', remediation: 'Choose an explicit setup/install action if provider configuration should be created.' };
+    if (readableCount === 0)
+        return { id: 'opencode-config-readable', status: 'fail', detail: 'OpenCode config exists but no JSON config could be parsed.' };
+    return { id: 'opencode-config-readable', status: existingCount === 1 ? 'pass' : 'warn', detail: `Found ${existingCount} OpenCode config path(s), ${readableCount} readable JSON config(s).` };
+}
+function mcpEntryCheck(config) {
+    const mcp = isRecord(config?.mcp) ? config.mcp : undefined;
+    const entry = mcp?.vgxness;
+    if (entry === undefined)
+        return { id: 'opencode-mcp-entry', status: 'fail', detail: 'No vgxness MCP server entry was found in readable OpenCode JSON config.', remediation: 'Use explicit setup/install outside provider status/doctor if you want to mutate provider config.' };
+    if (isRecord(entry) && entry.enabled === false)
+        return { id: 'opencode-mcp-entry', status: 'fail', detail: 'The vgxness MCP server entry exists but is disabled.' };
+    return { id: 'opencode-mcp-entry', status: 'pass', detail: 'Found enabled vgxness MCP server entry in readable OpenCode JSON config.' };
+}
+function defaultAgentCheck(config) {
+    const agents = isRecord(config?.agent) ? config.agent : undefined;
+    if (config?.default_agent !== vgxnessOpenCodeDefaultAgent || !isRecord(agents?.[vgxnessOpenCodeDefaultAgent]))
+        return { id: 'opencode-default-agent', status: 'fail', detail: 'OpenCode default_agent is not vgxness-manager or the manager config is missing.' };
+    return { id: 'opencode-default-agent', status: 'pass', detail: 'OpenCode default agent points to vgxness-manager.' };
+}
+function subagentsCheck(config) {
+    const agents = isRecord(config?.agent) ? config.agent : undefined;
+    const missing = vgxnessOpenCodeSddSubagents.filter((name) => !isRecord(agents?.[name]) || agents[name]?.hidden !== true);
+    if (missing.length > 0)
+        return { id: 'opencode-sdd-subagents', status: 'fail', detail: `Missing or non-hidden SDD subagents: ${missing.join(', ')}.` };
+    return { id: 'opencode-sdd-subagents', status: 'pass', detail: 'All expected SDD subagents exist and are hidden.' };
+}
+function delegationCheck(config) {
+    const manager = isRecord(config?.agent) && isRecord(config.agent[vgxnessOpenCodeDefaultAgent]) ? config.agent[vgxnessOpenCodeDefaultAgent] : undefined;
+    const permission = isRecord(manager?.permission) && isRecord(manager.permission.task) ? manager.permission.task : undefined;
+    if (permission?.['*'] !== 'deny')
+        return { id: 'opencode-delegation-permissions', status: 'fail', detail: 'Manager task permission wildcard is not deny.' };
+    const missing = vgxnessOpenCodeSddSubagents.filter((name) => permission[name] !== 'allow');
+    if (missing.length > 0)
+        return { id: 'opencode-delegation-permissions', status: 'fail', detail: `Manager cannot delegate to expected subagents: ${missing.join(', ')}.` };
+    return { id: 'opencode-delegation-permissions', status: 'pass', detail: 'Manager task permission is deny-by-default and allows exact SDD subagents.' };
+}
+function promptContractCheck(config, expected) {
+    const agents = isRecord(config?.agent) ? config.agent : undefined;
+    const names = [vgxnessOpenCodeDefaultAgent, ...vgxnessOpenCodeSddSubagents];
+    const mismatched = names.filter((name) => promptContractVersion(agents?.[name]) !== expected);
+    if (mismatched.length > 0)
+        return { id: 'prompt-contract-version', status: 'warn', detail: `Prompt contract version mismatch for: ${mismatched.join(', ')}. Expected ${expected}.` };
+    return { id: 'prompt-contract-version', status: 'pass', detail: `Prompt contract version ${expected} is present on manager and subagents.` };
+}
+function readonlySafetyCheck(before, after) {
+    return JSON.stringify(before) === JSON.stringify(after)
+        ? { id: 'provider-config-readonly-safety', status: 'pass', detail: 'Provider config path existence and mtimes were unchanged; no repair/install/write occurred.' }
+        : { id: 'provider-config-readonly-safety', status: 'fail', detail: 'Provider config path existence or mtimes changed during read-only doctor.' };
+}
+function snapshotPaths(paths, workspaceRoot) {
+    const unique = [...paths, `${workspaceRoot}/.vgx`];
+    return Object.fromEntries(unique.map((path) => [path, existsSync(path) ? statSync(path).mtimeMs : false]));
+}
+function promptContractVersion(value) {
+    if (!isRecord(value) || !isRecord(value.options))
+        return undefined;
+    return typeof value.options.vgxnessPromptContractVersion === 'number' ? value.options.vgxnessPromptContractVersion : undefined;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/mcp/provider-health-types.js

@@ -0,0 +1,67 @@
+export const PROVIDER_HEALTH_SAFETY = {
+    readOnly: true,
+    writesProviderConfig: false,
+    writesProjectFiles: false,
+    createsVgxDirectory: false,
+    savesArtifacts: false,
+    savesMemory: false,
+    recordsCheckpoints: false,
+    installsPackages: false,
+    runsRepair: false,
+    executesProvider: false,
+};
+export const REQUIRED_PROVIDER_MCP_TOOLS = ['vgxness_provider_status', 'vgxness_provider_doctor'];
+export const REQUIRED_PROVIDER_NATIVE_MCP_TOOLS = [
+    'vgxness_provider_status',
+    'vgxness_provider_doctor',
+    'vgxness_sdd_status',
+    'vgxness_sdd_next',
+    'vgxness_sdd_ready',
+    'vgxness_sdd_get_artifact',
+    'vgxness_sdd_list_artifacts',
+    'vgxness_sdd_save_artifact',
+    'vgxness_agent_resolve',
+    'vgxness_run_start',
+    'vgxness_run_checkpoint',
+    'vgxness_run_finalize',
+    'vgxness_run_preflight',
+    'vgxness_memory_search',
+    'vgxness_memory_get',
+    'vgxness_memory_save',
+    'vgxness_session_restore',
+    'vgxness_session_close',
+];
+export function normalizeProviderHealthInput(input) {
+    return {
+        project: input.project?.trim() || 'vgxness',
+        scope: input.scope ?? 'project',
+        providerAdapter: input.providerAdapter ?? 'opencode',
+        workspaceRoot: input.workspaceRoot?.trim() || process.cwd(),
+        change: input.change?.trim() ?? '',
+        expectedPromptContractVersion: input.expectedPromptContractVersion ?? 2,
+    };
+}
+export function rollupProviderHealth(statuses) {
+    if (statuses.some((status) => status === 'fail'))
+        return 'failed';
+    if (statuses.some((status) => status === 'not-configured'))
+        return 'not-configured';
+    if (statuses.some((status) => status === 'warn'))
+        return 'warning';
+    return 'ready';
+}
+export function providerHealthFailure(message) {
+    const error = { code: 'validation_failed', message };
+    return { ok: false, error };
+}
+export function rollupProviderDoctor(statuses) {
+    if (statuses.length === 0 || statuses.every((status) => status === 'skip'))
+        return 'skipped';
+    if (statuses.some((status) => status === 'fail'))
+        return 'failed';
+    if (statuses.some((status) => status === 'warn' || status === 'not-configured'))
+        return 'degraded';
+    if (statuses.some((status) => status === 'skip'))
+        return 'unknown';
+    return 'healthy';
+}

package/dist/mcp/provider-status.js

@@ -0,0 +1,152 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { PROVIDER_HEALTH_SAFETY, REQUIRED_PROVIDER_MCP_TOOLS, normalizeProviderHealthInput, providerHealthFailure, rollupProviderHealth } from './provider-health-types.js';
+import { vgxnessOpenCodeDefaultAgent, vgxnessOpenCodePromptContractVersion, vgxnessOpenCodeSddSubagents } from './opencode-default-agent-config.js';
+const projectConfigTargets = ['.opencode/opencode.json', 'opencode.json', '.opencode/opencode.jsonc', 'opencode.jsonc'];
+export class ProviderStatusService {
+    deps;
+    constructor(deps = {}) {
+        this.deps = deps;
+    }
+    getStatus(input = {}) {
+        const normalized = normalizeProviderHealthInput(input);
+        if (normalized.providerAdapter !== 'opencode')
+            return providerHealthFailure(`Unsupported provider adapter: ${normalized.providerAdapter}`);
+        const paths = inspectProjectConfigPaths(normalized.workspaceRoot);
+        const mcpEntry = inspectOpenCodeMcpEntry(paths);
+        const providerConfig = readFirstParsedConfig(paths);
+        const managerConfigured = hasConfiguredManager(providerConfig);
+        const subagentsConfigured = hasConfiguredSubagents(providerConfig);
+        const tools = requiredToolPresence();
+        const configStatus = resolveConfigStatus(paths, mcpEntry, managerConfigured, subagentsConfigured);
+        const status = rollupProviderHealth([configStatus, ...tools.map((tool) => (tool.present ? 'pass' : 'fail'))]);
+        const sdd = normalized.change.length > 0 ? this.readSdd(normalized.project, normalized.change) : undefined;
+        return {
+            ok: true,
+            value: {
+                version: 1,
+                kind: 'provider-status',
+                project: normalized.project,
+                providerAdapter: normalized.providerAdapter,
+                scope: normalized.scope,
+                workspaceRoot: normalized.workspaceRoot,
+                status,
+                summary: summarizeStatus(status, mcpEntry),
+                nextAction: nextActionFor(status, mcpEntry, sdd?.next),
+                checkedPaths: paths.map((path) => path.path),
+                config: { status: configStatus, paths, mcpEntry },
+                ...(sdd === undefined ? {} : { sdd }),
+                mcpRequiredTools: tools,
+                safety: PROVIDER_HEALTH_SAFETY,
+            },
+        };
+    }
+    readSdd(project, change) {
+        if (this.deps.sdd === undefined)
+            return { change };
+        const status = this.deps.sdd.getStatus({ project, change });
+        const next = this.deps.sdd.getNext({ project, change });
+        return { change, ...(status.ok ? { status: status.value } : {}), ...(next.ok ? { next: next.value } : {}) };
+    }
+}
+function readFirstParsedConfig(paths) {
+    const parsedPath = paths.find((path) => path.parsed);
+    if (parsedPath === undefined)
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(parsedPath.path, 'utf8'));
+        return isRecord(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function inspectProjectConfigPaths(workspaceRoot) {
+    return projectConfigTargets.map((relativePath) => inspectConfigPath(relativePath, join(workspaceRoot, relativePath)));
+}
+function inspectConfigPath(label, path) {
+    if (!existsSync(path))
+        return { label, path, exists: false, readable: false, parsed: false, status: 'not-configured', detail: 'Config path does not exist.' };
+    if (label.endsWith('.jsonc'))
+        return { label, path, exists: true, readable: true, parsed: false, status: 'warn', detail: 'JSONC config exists but is not parsed by this read-only status check.' };
+    try {
+        JSON.parse(readFileSync(path, 'utf8'));
+        return { label, path, exists: true, readable: true, parsed: true, status: 'pass', detail: 'Config exists and parses as JSON.' };
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        return { label, path, exists: true, readable: false, parsed: false, status: 'fail', detail: `Config could not be read or parsed: ${message}` };
+    }
+}
+function inspectOpenCodeMcpEntry(paths) {
+    const parsedPath = paths.find((path) => path.parsed);
+    if (parsedPath === undefined)
+        return { configured: false, status: 'not-configured', serverName: 'vgxness', detail: 'No readable OpenCode JSON config was found.' };
+    try {
+        const config = JSON.parse(readFileSync(parsedPath.path, 'utf8'));
+        const entry = typeof config.mcp === 'object' && config.mcp !== null ? config.mcp.vgxness : undefined;
+        const configured = entry !== undefined;
+        const enabled = !isRecord(entry) || entry.enabled !== false;
+        return configured
+            ? { configured: true, status: enabled ? 'pass' : 'warn', serverName: 'vgxness', enabled, detail: `MCP server entry found in ${parsedPath.label}${enabled ? '' : ' but it is disabled'}.` }
+            : { configured: false, status: 'not-configured', serverName: 'vgxness', detail: `No vgxness MCP server entry found in ${parsedPath.label}.` };
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        return { configured: false, status: 'fail', serverName: 'vgxness', detail: `Unable to inspect MCP entry: ${message}` };
+    }
+}
+function requiredToolPresence() {
+    return REQUIRED_PROVIDER_MCP_TOOLS.map((tool) => ({ tool, present: true }));
+}
+function resolveConfigStatus(paths, mcpEntry, managerConfigured, subagentsConfigured) {
+    if (paths.some((path) => path.status === 'fail') || mcpEntry.status === 'fail')
+        return 'fail';
+    if (paths.filter((path) => path.exists).length > 1)
+        return 'warn';
+    if (mcpEntry.status === 'not-configured')
+        return 'not-configured';
+    if (!managerConfigured || !subagentsConfigured)
+        return 'warn';
+    if (paths.some((path) => path.status === 'warn'))
+        return 'warn';
+    return 'pass';
+}
+function summarizeStatus(status, mcpEntry) {
+    if (status === 'ready')
+        return 'OpenCode provider config is readable and the vgxness MCP entry is present.';
+    if (status === 'not-configured')
+        return mcpEntry.detail;
+    if (status === 'warning')
+        return 'OpenCode provider config has warnings; no changes were made.';
+    return 'OpenCode provider status check found a blocking issue; no changes were made.';
+}
+function nextActionFor(status, mcpEntry, sddNext) {
+    if (sddNext !== undefined)
+        return { kind: 'advance-sdd', message: 'Continue the next SDD phase inside OpenCode using MCP status/ready/artifact tools and hidden SDD subagents.' };
+    if (status === 'ready')
+        return { kind: 'continue', message: 'Continue using the provider; no read-only follow-up is required.' };
+    if (status === 'not-configured' && !mcpEntry.configured)
+        return { kind: 'setup-required', message: 'Review the reported config paths and choose an explicit provider setup action if you want configuration changes.' };
+    return { kind: 'review', message: 'Review the failed or warning checks before attempting provider setup.' };
+}
+function hasConfiguredManager(config) {
+    if (config === undefined)
+        return false;
+    const agent = isRecord(config.agent) ? config.agent : undefined;
+    return config.default_agent === vgxnessOpenCodeDefaultAgent && isRecord(agent?.[vgxnessOpenCodeDefaultAgent]) && promptContractVersion(agent[vgxnessOpenCodeDefaultAgent]) === vgxnessOpenCodePromptContractVersion;
+}
+function hasConfiguredSubagents(config) {
+    if (config === undefined)
+        return false;
+    const agent = isRecord(config.agent) ? config.agent : undefined;
+    return vgxnessOpenCodeSddSubagents.every((name) => isRecord(agent?.[name]) && agent[name]?.hidden === true && promptContractVersion(agent[name]) === vgxnessOpenCodePromptContractVersion);
+}
+function promptContractVersion(value) {
+    if (!isRecord(value) || !isRecord(value.options))
+        return undefined;
+    return typeof value.options.vgxnessPromptContractVersion === 'number' ? value.options.vgxnessPromptContractVersion : undefined;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/mcp/schema.js

@@ -27,6 +27,8 @@ export const SUPPORTED_VGX_MCP_TOOL_NAMES = [
     'vgxness_run_start',
     'vgxness_run_checkpoint',
     'vgxness_run_finalize',
+    'vgxness_provider_status',
+    'vgxness_provider_doctor',
 ];
 const scopes = ['project', 'personal'];
 const agentModes = ['agent', 'subagent'];
@@ -219,6 +221,20 @@ export const VGX_MCP_TOOL_INPUT_SCHEMAS = {
         outcome: z.enum(runOutcomes),
         outcomeReason: z.string().min(1).optional(),
     }).passthrough(),
+    vgxness_provider_status: z.object({
+        project: z.string().min(1).optional(),
+        scope: z.enum(scopes).optional(),
+        providerAdapter: z.literal('opencode').optional(),
+        workspaceRoot: z.string().min(1).optional(),
+        change: z.string().min(1).optional(),
+    }).passthrough(),
+    vgxness_provider_doctor: z.object({
+        project: z.string().min(1).optional(),
+        scope: z.enum(scopes).optional(),
+        providerAdapter: z.literal('opencode').optional(),
+        workspaceRoot: z.string().min(1).optional(),
+        expectedPromptContractVersion: z.number().int().positive().optional(),
+    }).passthrough(),
 };
 export function successEnvelope(tool, value) {
     return { ok: true, tool, value };

package/dist/mcp/stdio-server.js

@@ -38,11 +38,18 @@ function registerVgxTools(server, controlPlane) {
     for (const toolName of SUPPORTED_VGX_MCP_TOOL_NAMES) {
         server.registerTool(toolName, {
             title: toolName,
-            description: `VGX control-plane tool ${toolName}`,
+            description: descriptionForTool(toolName),
             inputSchema: VGX_MCP_TOOL_INPUT_SCHEMAS[toolName],
         }, async (args) => toMcpTextResult(controlPlane.callVgxTool(toolName, argsForTool(args))));
     }
 }
+function descriptionForTool(toolName) {
+    if (toolName === 'vgxness_provider_status')
+        return 'Read-only provider status report; inspects OpenCode config paths without installing, repairing, or writing files.';
+    if (toolName === 'vgxness_provider_doctor')
+        return 'Read-only provider doctor checks; reports OpenCode MCP configuration health without repair/install side effects.';
+    return `VGX control-plane tool ${toolName}`;
+}
 function argsForTool(args) {
     return args;
 }

package/dist/mcp/validation.js

@@ -77,8 +77,50 @@ export function validateVgxMcpToolCall(call) {
             return validationSuccess(tool.value, validateRunCheckpointInput(input, tool.value));
         case 'vgxness_run_finalize':
             return validationSuccess(tool.value, validateRunFinalizeInput(input, tool.value));
+        case 'vgxness_provider_status':
+            return validationSuccess(tool.value, validateProviderHealthInput(input, tool.value));
+        case 'vgxness_provider_doctor':
+            return validationSuccess(tool.value, validateProviderHealthInput(input, tool.value));
     }
 }
+function validateProviderHealthInput(input, tool) {
+    const record = inputRecord(input ?? {}, tool, ['project', 'scope', 'providerAdapter', 'workspaceRoot', 'change', 'expectedPromptContractVersion']);
+    if (!record.ok)
+        return record;
+    const result = {};
+    const project = readOptionalNonEmptyString(record.value, 'project', tool);
+    if (!project.ok)
+        return project;
+    if (project.value !== undefined)
+        result.project = project.value;
+    const scope = readOptionalOneOf(record.value, 'scope', scopes, tool);
+    if (!scope.ok)
+        return scope;
+    if (scope.value !== undefined)
+        result.scope = scope.value;
+    const providerAdapter = readOptionalOneOf(record.value, 'providerAdapter', ['opencode'], tool);
+    if (!providerAdapter.ok)
+        return providerAdapter;
+    if (providerAdapter.value !== undefined)
+        result.providerAdapter = providerAdapter.value;
+    const workspaceRoot = readOptionalNonEmptyString(record.value, 'workspaceRoot', tool);
+    if (!workspaceRoot.ok)
+        return workspaceRoot;
+    if (workspaceRoot.value !== undefined)
+        result.workspaceRoot = workspaceRoot.value;
+    const change = readOptionalNonEmptyString(record.value, 'change', tool);
+    if (!change.ok)
+        return change;
+    if (change.value !== undefined)
+        result.change = change.value;
+    const expectedPromptContractVersion = record.value.expectedPromptContractVersion;
+    if (expectedPromptContractVersion !== undefined) {
+        if (typeof expectedPromptContractVersion !== 'number' || !Number.isSafeInteger(expectedPromptContractVersion) || expectedPromptContractVersion <= 0)
+            return validationFailure('expectedPromptContractVersion must be a positive safe integer', tool);
+        result.expectedPromptContractVersion = expectedPromptContractVersion;
+    }
+    return { ok: true, value: result };
+}
 export function validateVgxMcpToolInput(tool, input) {
     return validateVgxMcpToolCall({ tool, input });
 }
@@ -574,6 +616,11 @@ function readNonEmptyString(record, field, tool) {
         return validationFailure(`${field} must not be empty`, tool);
     return value;
 }
+function readOptionalNonEmptyString(record, field, tool) {
+    if (record[field] === undefined)
+        return { ok: true, value: undefined };
+    return readNonEmptyString(record, field, tool);
+}
 function readChange(record, tool) {
     const change = readNonEmptyString(record, 'change', tool);
     if (!change.ok)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vgxness",
-  "version": "0.1.0",
+  "version": "0.1.1-alpha.0",
   "description": "Alpha CLI and MCP control plane for guided AI-agent workflows, SDD, memory, and OpenCode setup.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {