vgxness 0.1.0

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

@@ -0,0 +1,156 @@
+export const vgxnessOpenCodeDefaultAgent = 'vgxness-manager';
+export const vgxnessOpenCodeSddSubagents = [
+    'vgxness-sdd-explore',
+    'vgxness-sdd-propose',
+    'vgxness-sdd-spec',
+    'vgxness-sdd-design',
+    'vgxness-sdd-tasks',
+    'vgxness-sdd-apply',
+    'vgxness-sdd-verify',
+    'vgxness-sdd-archive',
+    'vgxness-sdd-init',
+    'vgxness-sdd-onboard',
+];
+export function createOpenCodeSddTaskPermissions() {
+    const taskPermissions = { '*': 'deny' };
+    for (const subagent of vgxnessOpenCodeSddSubagents)
+        taskPermissions[subagent] = 'allow';
+    return taskPermissions;
+}
+export function createOpenCodeDefaultAgentInstallPlan(input = {}) {
+    if (input.mcpOnly === true)
+        return { installsAgents: false, agentNames: [] };
+    return { installsAgents: true, agentNames: [vgxnessOpenCodeDefaultAgent, ...vgxnessOpenCodeSddSubagents], defaultAgent: vgxnessOpenCodeDefaultAgent };
+}
+export function createOpenCodeDefaultAgentConfig() {
+    const agents = {
+        [vgxnessOpenCodeDefaultAgent]: {
+            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' },
+            permission: { task: createOpenCodeSddTaskPermissions() },
+            prompt: vgxnessManagerPrompt,
+            reasoningEffort: 'high',
+            tools: { bash: true, delegate: true, delegation_list: true, delegation_read: true, edit: true, read: true, write: true },
+            variant: '',
+        },
+    };
+    const descriptions = {
+        'vgxness-sdd-explore': 'Investigate codebase and think through ideas',
+        'vgxness-sdd-propose': 'Create change proposals from explorations',
+        'vgxness-sdd-spec': 'Write detailed specifications from proposals',
+        'vgxness-sdd-design': 'Create technical design from proposals',
+        'vgxness-sdd-tasks': 'Break down specs and designs into implementation tasks',
+        'vgxness-sdd-apply': 'Implement code changes from task definitions',
+        'vgxness-sdd-verify': 'Validate implementation against specs',
+        'vgxness-sdd-archive': 'Archive completed change artifacts',
+        'vgxness-sdd-init': 'Bootstrap SDD context and project configuration',
+        'vgxness-sdd-onboard': 'Guide user through a complete SDD cycle using their real codebase',
+    };
+    for (const name of vgxnessOpenCodeSddSubagents) {
+        agents[name] = {
+            description: descriptions[name],
+            hidden: true,
+            mode: 'subagent',
+            model: 'openai/gpt-5.5',
+            prompt: createSddSubagentPrompt(name),
+            tools: { bash: true, edit: true, read: true, write: true },
+        };
+    }
+    return { defaultAgent: vgxnessOpenCodeDefaultAgent, agents };
+}
+function createSddSubagentPrompt(name) {
+    const phase = name.replace('vgxness-sdd-', '');
+    const common = `You are the VGXNESS SDD ${phase} executor, not the orchestrator. Do this phase's work yourself. Do NOT delegate, do NOT call task/delegate, and do NOT launch sub-agents. Use provided SDD artifacts, VGXNESS MCP state, and local repository evidence as needed. Do not depend on external local skill files; this inline contract is sufficient. Preserve unrelated user work, keep output concise, and report evidence.`;
+    const contracts = {
+        'vgxness-sdd-explore': 'Investigate codebase context, constraints, options, and risks. Do not implement code changes. Return findings and recommended next artifacts.',
+        'vgxness-sdd-propose': 'Create or refine a focused SDD proposal from exploration evidence. Do not implement code changes. Include scope, tradeoffs, non-goals, and acceptance direction.',
+        'vgxness-sdd-spec': 'Write requirements, acceptance criteria, edge cases, and out-of-scope items. Do not implement code changes.',
+        'vgxness-sdd-design': 'Create technical design grounded in the repository: affected modules, data shapes, safety, rollout, and verification. Do not implement code changes.',
+        'vgxness-sdd-tasks': 'Break approved spec/design into small ordered testable implementation tasks. Do not implement code changes.',
+        'vgxness-sdd-apply': 'Implement only assigned SDD tasks. Preserve unrelated dirty files and user work. Use focused tests when authorized. Report changed files, tests/evidence, and residual risks.',
+        'vgxness-sdd-verify': 'Validate implementation against SDD artifacts and task acceptance criteria. Prefer focused local tests and evidence review. Do not implement unrelated changes.',
+        'vgxness-sdd-archive': 'Archive completed SDD outcome with summary, verification evidence, follow-ups, and residual risks. Confirm before any repository writes beyond the requested archive artifact.',
+        '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]}`;
+}
+const vgxnessManagerPrompt = `# VGXNESS Manager - SDD Orchestrator Instructions
+
+Bind this to the dedicated \`vgxness-manager\` primary agent only. Do NOT apply it to executor phase agents such as \`vgxness-sdd-apply\` or \`vgxness-sdd-verify\`.
+
+## Role
+
+You are the VGXNESS SDD coordinator, not a monolithic executor. Keep one thin conversation thread, use VGXNESS MCP for durable state, delegate real phase work to the smallest appropriate SDD sub-agent, then synthesize results for the user.
+
+Act with the personality configured for VGXNESS: direct, practical, grounded in the repository, and willing to challenge weak assumptions. Preserve user control. Prefer small, safe, testable changes. Keep VGXNESS terminology and behavior clean; do not import concepts from unrelated orchestrator experiments.
+
+## MCP-First Operating Model
+
+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.
+
+## 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.
+- 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.
+
+## Request Type -> Minimum MCP Sequence
+
+| Request type | Minimum sequence |
+|---|---|
+| Start/resume/recover conversation | \`vgxness_session_restore\` with project + workspace directory -> use returned session summary/activity before asking for missing context or inferring from chat. |
+| Simple question or small explanation | Answer inline; search/get memory only if prior context is referenced; no run by default. |
+| SDD proposal/spec/design/tasks | \`vgxness_sdd_status\` or \`vgxness_sdd_next\` -> \`vgxness_sdd_ready\` -> \`vgxness_sdd_get_artifact\`/\`vgxness_sdd_list_artifacts\` -> \`vgxness_agent_resolve\` -> delegate exact phase subagent -> \`vgxness_sdd_save_artifact\` after accepted output. |
+| Apply/verify | Require/recover \`tasks\` for apply and \`apply-progress\` for verify; get relevant artifacts -> resolve exact subagent -> \`vgxness_run_start\` or recover run -> \`vgxness_run_preflight\` for writes/shell/git/tests -> delegate -> checkpoint -> save \`apply-progress\`/\`verify\` artifact -> finalize when outcome is clear. |
+| Config/provider/prompt changes | \`vgxness_manager_profile_get\` and/or \`vgxness_opencode_manager_payload\` first; use \`vgxness_manager_profile_set\` or OpenCode install only with explicit human authorization. |
+| Resume/diagnostics | Use \`vgxness_run_list\`, \`vgxness_run_get\`, \`vgxness_sdd_status\`, and artifact reads before inferring state from chat. |
+| Close/pause/handoff/compact conversation | \`vgxness_session_close\` with current session id, actor \`manager\`, and concise actionable summary -> final user response; if the id is unavailable, say so and include the summary in the final response. |
+
+## Delegation Rules
+
+Core principle: does this inflate the manager context without need? If yes, delegate. If no, keep it inline.
+
+Do not perform substantial multi-file implementation inline. Resolve/delegate phase work to exact allowed SDD subagents, synthesize results, and persist artifacts/checkpoints through MCP.
+
+| Action | Inline | Delegate |
+|--------|--------|----------|
+| Read to decide/verify 1-3 files | Yes | No |
+| Read to explore/understand 4+ files | No | Yes |
+| Read as preparation for writing | No | Yes, together with the write |
+| Write atomic one-file mechanical change | Yes | No |
+| Write with analysis, multiple files, or new logic | No | Yes |
+| Bash for state such as git, gh, status | Yes | No |
+| Bash for execution such as tests, installs, external tooling | No | Yes |
+
+## SDD Phase Mapping
+
+- Explore or investigate: \`vgxness-sdd-explore\`
+- Proposal: \`vgxness-sdd-propose\`
+- Spec: \`vgxness-sdd-spec\`
+- Design: \`vgxness-sdd-design\`
+- Tasks: \`vgxness-sdd-tasks\`
+- Apply implementation: \`vgxness-sdd-apply\`
+- Verify implementation: \`vgxness-sdd-verify\`
+- Archive completed work: \`vgxness-sdd-archive\`
+- Onboard/init: \`vgxness-sdd-onboard\` or \`vgxness-sdd-init\`
+
+## Safety Boundaries
+
+- Do not mutate provider config unless the user explicitly asks for provider configuration changes.
+- Do not mutate global OpenCode config or provider config unless the user explicitly asks for install/apply/configuration changes.
+- Do not write to \`openspec/\`.
+- Do not publish packages unless explicitly requested.
+- Never revert or overwrite user changes unless explicitly requested.
+- Keep unrelated dirty files out of commits.
+- Preserve \`permission.task\` as deny-by-default: only exact known SDD subagents are allowed; wildcard delegation remains denied.
+
+## Output Discipline
+
+Keep the manager response concise. Say what was delegated, what came back, what changed, and what remains.`;

package/dist/mcp/opencode-visibility.js

@@ -0,0 +1,102 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { resolveOpenCodeMcpInstallTarget } from './client-install-opencode-contract.js';
+import { SUPPORTED_VGX_MCP_TOOL_NAMES } from './schema.js';
+const serverName = 'vgxness';
+const expectedToolCount = SUPPORTED_VGX_MCP_TOOL_NAMES.length;
+export function createOpenCodeMcpVisibilityReport(options) {
+    const cwd = resolve(options.cwd);
+    const projectRoot = resolve(options.projectRoot ?? findNearestOpenCodeProjectRoot(cwd));
+    const targetScope = options.scope ?? 'project';
+    const projectTargetPath = join(projectRoot, '.opencode', 'opencode.json');
+    const cwdInsideProject = isPathInsideOrEqual(cwd, projectRoot);
+    const projectConfigExists = existsSync(projectTargetPath);
+    const projectHasVgxnessServer = projectConfigExists && readHasVgxnessServer(projectTargetPath);
+    const projectVisibleFromCurrentCwd = cwdInsideProject && projectConfigExists && projectHasVgxnessServer;
+    const userTarget = resolveOpenCodeMcpInstallTarget({ cwd: projectRoot, scope: 'user', env: options.env });
+    const userReport = userTarget.ok ? userVisibilityReport(userTarget.path, projectVisibleFromCurrentCwd) : undefined;
+    const selectedTargetPath = targetScope === 'user' && userTarget.ok ? userTarget.path : projectTargetPath;
+    const selectedReady = targetScope === 'user'
+        ? userReport?.configExists === true && userReport.hasVgxnessServer
+        : projectVisibleFromCurrentCwd;
+    return {
+        version: 1,
+        kind: 'mcp-doctor-opencode-visibility',
+        ready: selectedReady,
+        cwd,
+        projectRoot,
+        targetScope,
+        targetPath: selectedTargetPath,
+        targets: {
+            project: { path: projectTargetPath, configExists: projectConfigExists, hasVgxnessServer: projectHasVgxnessServer, visibleFromCurrentCwd: projectVisibleFromCurrentCwd },
+            ...(userReport !== undefined ? { user: userReport } : {}),
+        },
+        visibility: { cwdInsideProject, configExists: projectConfigExists, hasVgxnessServer: projectHasVgxnessServer },
+        expected: { serverName, toolCount: expectedToolCount, visibleFromCurrentCwd: selectedReady },
+        guidance: buildGuidance({
+            cwdInsideProject,
+            configExists: projectConfigExists,
+            hasVgxnessServer: projectHasVgxnessServer,
+            targetScope,
+            ...(userTarget.ok ? {} : { userTargetMessage: userTarget.message }),
+            userOverridden: userReport?.overriddenByProjectConfig === true,
+        }),
+        safety: { readOnly: true, writesProviderConfig: false, globalInstallDeferred: true },
+    };
+}
+function buildGuidance(state) {
+    const guidance = [
+        'Run `opencode mcp list` from inside the vgxness worktree to verify project-local MCP visibility.',
+        'After OpenCode starts inside vgxness, the expected connected-tools result is `vgxness` with the registered VGXNESS MCP tools from the current build.',
+        'Restart OpenCode if the project-local server is not listed after config changes.',
+    ];
+    if (state.targetScope === 'user') {
+        guidance.push('User scope targets `$HOME/.config/opencode/opencode.json` and this diagnostic reads it without writing provider config.');
+        guidance.push('Project OpenCode config can override user config for a workspace; inspect project config first when both define `mcp.vgxness`.');
+    }
+    if (state.userTargetMessage !== undefined)
+        guidance.push(state.userTargetMessage);
+    if (state.userOverridden)
+        guidance.push('Project OpenCode config can override user config for this workspace because both project and user targets define `mcp.vgxness`.');
+    if (!state.cwdInsideProject) {
+        guidance.push('The project-local `vgxness` server is not expected to appear from outside the worktree.');
+        guidance.push('Use `mcp install opencode --scope user --plan` to inspect the user config target without writing it.');
+    }
+    if (!state.configExists)
+        guidance.push('Expected project-local config `.opencode/opencode.json` was not found.');
+    if (state.configExists && !state.hasVgxnessServer)
+        guidance.push('Project-local config exists, but it does not define `mcp.vgxness`.');
+    return guidance;
+}
+function userVisibilityReport(targetPath, projectVisibleFromCurrentCwd) {
+    const configExists = existsSync(targetPath);
+    const hasVgxnessServer = configExists && readHasVgxnessServer(targetPath);
+    return { path: targetPath, configExists, hasVgxnessServer, overriddenByProjectConfig: projectVisibleFromCurrentCwd && hasVgxnessServer };
+}
+function readHasVgxnessServer(targetPath) {
+    try {
+        const parsed = JSON.parse(readFileSync(targetPath, 'utf8'));
+        return isRecord(parsed) && isRecord(parsed.mcp) && isRecord(parsed.mcp[serverName]);
+    }
+    catch {
+        return false;
+    }
+}
+function isPathInsideOrEqual(candidate, parent) {
+    const relativePath = relative(parent, candidate);
+    return relativePath === '' || (!relativePath.startsWith('..') && !relativePath.startsWith('/') && !relativePath.startsWith('\\'));
+}
+function findNearestOpenCodeProjectRoot(start) {
+    let current = resolve(start);
+    while (true) {
+        if (existsSync(join(current, '.opencode', 'opencode.json')))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return start;
+        current = parent;
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/mcp/schema.js

@@ -0,0 +1,234 @@
+import { z } from 'zod';
+import { sddPhases } from '../sdd/schema.js';
+export const SUPPORTED_VGX_MCP_TOOL_NAMES = [
+    'vgxness_sdd_status',
+    'vgxness_sdd_ready',
+    'vgxness_sdd_save_artifact',
+    'vgxness_sdd_get_artifact',
+    'vgxness_sdd_list_artifacts',
+    'vgxness_sdd_next',
+    'vgxness_memory_save',
+    'vgxness_memory_search',
+    'vgxness_memory_get',
+    'vgxness_memory_update',
+    'vgxness_session_start',
+    'vgxness_session_append_activity',
+    'vgxness_session_close',
+    'vgxness_session_restore',
+    'vgxness_agent_resolve',
+    'vgxness_agent_activate',
+    'vgxness_manager_profile_get',
+    'vgxness_manager_profile_set',
+    'vgxness_skill_payload',
+    'vgxness_opencode_manager_payload',
+    'vgxness_run_list',
+    'vgxness_run_get',
+    'vgxness_run_preflight',
+    'vgxness_run_start',
+    'vgxness_run_checkpoint',
+    'vgxness_run_finalize',
+];
+const scopes = ['project', 'personal'];
+const agentModes = ['agent', 'subagent'];
+const memoryTypes = ['architecture', 'decision', 'bugfix', 'pattern', 'config', 'discovery', 'learning', 'preference', 'manual'];
+const activityKinds = ['prompt', 'tool_call', 'artifact', 'summary', 'error'];
+const runStatuses = ['created', 'planned', 'running', 'needs-human', 'completed', 'failed', 'blocked', 'cancelled'];
+const finalRunStatuses = ['completed', 'failed', 'blocked', 'cancelled'];
+const runOutcomes = ['success', 'partial', 'failure', 'blocked', 'cancelled'];
+const permissionCategories = ['read', 'edit', 'shell', 'network', 'git', 'memory', 'external-directory', 'provider-tool', 'secrets'];
+const jsonValueSchema = z.lazy(() => z.union([
+    z.string(),
+    z.number().finite(),
+    z.boolean(),
+    z.null(),
+    z.array(jsonValueSchema),
+    z.record(z.string(), jsonValueSchema),
+]));
+export const VGX_MCP_TOOL_INPUT_SCHEMAS = {
+    vgxness_sdd_status: z.object({
+        project: z.string().min(1),
+        change: z.string().min(1),
+    }).passthrough(),
+    vgxness_sdd_ready: z.object({
+        project: z.string().min(1),
+        change: z.string().min(1),
+        phase: z.enum(sddPhases),
+    }).passthrough(),
+    vgxness_sdd_save_artifact: z.object({
+        project: z.string().min(1),
+        change: z.string().min(1),
+        phase: z.enum(sddPhases),
+        content: z.string().min(1),
+    }).passthrough(),
+    vgxness_sdd_get_artifact: z.object({
+        project: z.string().min(1),
+        change: z.string().min(1),
+        phase: z.enum(sddPhases),
+    }).passthrough(),
+    vgxness_sdd_list_artifacts: z.object({
+        project: z.string().min(1),
+        change: z.string().min(1),
+    }).passthrough(),
+    vgxness_sdd_next: z.object({
+        project: z.string().min(1),
+        change: z.string().min(1),
+    }).passthrough(),
+    vgxness_memory_save: z.object({
+        project: z.string().min(1),
+        scope: z.enum(scopes).optional(),
+        type: z.enum(memoryTypes),
+        title: z.string().min(1),
+        content: z.string().min(1),
+        topicKey: z.string().min(1).optional(),
+    }).passthrough(),
+    vgxness_memory_search: z.object({
+        project: z.string().min(1).optional(),
+        scope: z.enum(scopes).optional(),
+        type: z.enum(memoryTypes).optional(),
+        topicKey: z.string().min(1).optional(),
+        query: z.string().min(1).optional(),
+        limit: z.number().int().min(1).max(100),
+    }).passthrough(),
+    vgxness_memory_get: z.object({
+        id: z.string().min(1),
+    }).passthrough(),
+    vgxness_memory_update: z.object({
+        id: z.string().min(1),
+        type: z.enum(memoryTypes).optional(),
+        title: z.string().min(1).optional(),
+        content: z.string().min(1).optional(),
+        topicKey: z.string().min(1).optional(),
+    }).passthrough(),
+    vgxness_session_start: z.object({
+        id: z.string().min(1).optional(),
+        project: z.string().min(1),
+        directory: z.string().min(1).optional(),
+    }).passthrough(),
+    vgxness_session_append_activity: z.object({
+        sessionId: z.string().min(1),
+        actor: z.string().min(1),
+        kind: z.enum(activityKinds),
+        payloadJson: z.string().min(1),
+    }).passthrough(),
+    vgxness_session_close: z.object({
+        sessionId: z.string().min(1),
+        actor: z.string().min(1),
+        summary: z.string().trim().min(1),
+    }).passthrough(),
+    vgxness_session_restore: z.object({
+        project: z.string().min(1),
+        directory: z.string().min(1).optional(),
+    }).passthrough(),
+    vgxness_agent_resolve: z.object({
+        project: z.string().min(1).optional(),
+        scope: z.enum(scopes).optional(),
+        taskDescription: z.string().min(1).optional(),
+        intent: z.string().min(1).optional(),
+        desiredCapabilities: z.array(z.string().min(1)).optional(),
+        workflow: z.string().min(1).optional(),
+        phase: z.string().min(1).optional(),
+        providerAdapter: z.string().min(1).optional(),
+        mode: z.enum(agentModes).optional(),
+    }).passthrough(),
+    vgxness_agent_activate: z.object({
+        project: z.string().min(1),
+        scope: z.enum(scopes).optional(),
+        agentId: z.string().min(1).optional(),
+        userIntent: z.string().min(1),
+        workflow: z.string().min(1).optional(),
+        phase: z.string().min(1).optional(),
+        workspaceRoot: z.string().min(1).optional(),
+        maxSourceBytes: z.number().int().positive().optional(),
+        providerAdapter: z.string().min(1).optional(),
+    }).passthrough(),
+    vgxness_manager_profile_get: z.object({
+        project: z.string().min(1),
+        scope: z.enum(scopes).optional(),
+        managerName: z.string().min(1).optional(),
+    }).passthrough(),
+    vgxness_manager_profile_set: z.object({
+        project: z.string().min(1),
+        scope: z.enum(scopes),
+        managerName: z.string().min(1),
+        instructions: z.string().min(1),
+    }).passthrough(),
+    vgxness_skill_payload: z.object({
+        workspaceRoot: z.string().min(1),
+        maxSourceBytes: z.number().int().positive().optional(),
+        project: z.string().min(1).optional(),
+        scope: z.enum(scopes).optional(),
+        agentId: z.string().min(1).optional(),
+        agentName: z.string().min(1).optional(),
+        workflow: z.string().min(1).optional(),
+        phase: z.string().min(1).optional(),
+        providerAdapter: z.string().min(1).optional(),
+        runId: z.string().min(1).optional(),
+    }).passthrough(),
+    vgxness_opencode_manager_payload: z.object({
+        project: z.string().min(1),
+        scope: z.enum(scopes).optional(),
+        agentId: z.string().min(1).optional(),
+        agentName: z.string().min(1).optional(),
+        workspaceRoot: z.string().min(1).optional(),
+        maxSourceBytes: z.number().int().positive().optional(),
+    }).passthrough(),
+    vgxness_run_list: z.object({
+        project: z.string().min(1).optional(),
+        status: z.enum(runStatuses).optional(),
+        limit: z.number().int().min(1).max(100),
+    }).passthrough(),
+    vgxness_run_get: z.object({
+        id: z.string().min(1),
+    }).passthrough(),
+    vgxness_run_preflight: z.object({
+        runId: z.string().min(1),
+        category: z.enum(permissionCategories),
+        operation: z.string().min(1),
+        workspaceRoot: z.string().min(1).optional(),
+        targetPath: z.string().min(1).optional(),
+        providerToolName: z.string().min(1).optional(),
+        agent: z.object({
+            id: z.string().min(1),
+            name: z.string().min(1).optional(),
+            mode: z.enum(agentModes),
+            permissions: z.record(z.enum(permissionCategories), z.enum(['allow', 'ask', 'deny'])).optional(),
+        }).optional(),
+        sandboxStrategy: z.enum(['worktree']).optional(),
+        destructive: z.boolean().optional(),
+        external: z.boolean().optional(),
+        privileged: z.boolean().optional(),
+        ambiguous: z.boolean().optional(),
+    }).passthrough(),
+    vgxness_run_start: z.object({
+        project: z.string().min(1),
+        userIntent: z.string().min(1),
+        workflow: z.string().min(1),
+        phase: z.string().min(1),
+        selectedAgentId: z.string().min(1),
+        providerAdapter: z.string().min(1),
+        model: z.string().min(1),
+    }).passthrough(),
+    vgxness_run_checkpoint: z.object({
+        runId: z.string().min(1),
+        label: z.string().min(1),
+        state: jsonValueSchema,
+    }).passthrough(),
+    vgxness_run_finalize: z.object({
+        runId: z.string().min(1),
+        status: z.enum(finalRunStatuses),
+        outcome: z.enum(runOutcomes),
+        outcomeReason: z.string().min(1).optional(),
+    }).passthrough(),
+};
+export function successEnvelope(tool, value) {
+    return { ok: true, tool, value };
+}
+export function errorEnvelope(code, message, tool) {
+    const result = { ok: false, error: { code, message } };
+    if (tool !== undefined)
+        result.tool = tool;
+    return result;
+}
+export function isVgxMcpToolName(value) {
+    return typeof value === 'string' && SUPPORTED_VGX_MCP_TOOL_NAMES.includes(value);
+}

package/dist/mcp/stdio-server.js

@@ -0,0 +1,56 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createVgxMcpControlPlane } from './control-plane.js';
+import { SUPPORTED_VGX_MCP_TOOL_NAMES, VGX_MCP_TOOL_INPUT_SCHEMAS } from './schema.js';
+export async function startVgxMcpStdioServer(options = {}) {
+    const controlPlane = createVgxMcpControlPlane(options.databasePath === undefined ? {} : { databasePath: options.databasePath });
+    const mcpServer = new McpServer({ name: 'vgxness', version: '0.1.0' });
+    const transport = new StdioServerTransport();
+    let closed = false;
+    const close = async () => {
+        if (closed)
+            return;
+        closed = true;
+        process.off('SIGINT', closeOnSignal);
+        process.off('SIGTERM', closeOnSignal);
+        try {
+            await mcpServer.close();
+        }
+        finally {
+            controlPlane.close();
+        }
+    };
+    const closeOnSignal = () => {
+        void close().finally(() => {
+            process.exitCode = 0;
+        });
+    };
+    mcpServer.server.onclose = () => {
+        controlPlane.close();
+    };
+    registerVgxTools(mcpServer, controlPlane);
+    process.once('SIGINT', closeOnSignal);
+    process.once('SIGTERM', closeOnSignal);
+    await mcpServer.connect(transport);
+    return { close };
+}
+function registerVgxTools(server, controlPlane) {
+    for (const toolName of SUPPORTED_VGX_MCP_TOOL_NAMES) {
+        server.registerTool(toolName, {
+            title: toolName,
+            description: `VGX control-plane tool ${toolName}`,
+            inputSchema: VGX_MCP_TOOL_INPUT_SCHEMAS[toolName],
+        }, async (args) => toMcpTextResult(controlPlane.callVgxTool(toolName, argsForTool(args))));
+    }
+}
+function argsForTool(args) {
+    return args;
+}
+function toMcpTextResult(envelope) {
+    const result = {
+        content: [{ type: 'text', text: JSON.stringify(envelope, null, 2) }],
+    };
+    if (!envelope.ok)
+        result.isError = true;
+    return result;
+}