vgxness 1.5.0 → 1.5.1

package/dist/mcp/control-plane.js

@@ -63,6 +63,8 @@ export function callVgxTool(call, services) {
             return toEnvelope(validated.tool, services.memory.closeSession(validated.input, memoryContext(validated.input.sessionId)));
         case 'vgxness_session_restore':
             return toEnvelope(validated.tool, services.memory.restoreSession(validated.input));
+        case 'vgxness_context_cockpit':
+            return toEnvelope(validated.tool, services.memory.getContextCockpit(validated.input));
         case 'vgxness_agent_resolve':
             return toEnvelope(validated.tool, services.agents.resolveAgents(validated.input));
         case 'vgxness_agent_activate':

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

@@ -1,5 +1,5 @@
 export const vgxnessOpenCodeDefaultAgent = 'vgxness-manager';
-export const vgxnessOpenCodePromptContractVersion = 4;
+export const vgxnessOpenCodePromptContractVersion = 6;
 export const vgxnessOpenCodeInstructionsPath = 'AGENTS.md';
 export const vgxnessOpenCodeSddSubagents = [
     'vgxness-sdd-explore',
@@ -65,7 +65,7 @@ export function createOpenCodeDefaultAgentConfig() {
 }
 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 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. Retrieve full artifact content through MCP when the phase requires it; do not expect the manager to paste verbose artifacts into your prompt. 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.',
@@ -102,8 +102,8 @@ Coach while coordinating: teach briefly when helpful, explain practical tradeoff
 Normal SDD progression happens inside OpenCode through conversation, VGXNESS MCP, and hidden SDD subagents. Do not tell users to run terminal SDD phase commands for daily flow. CLI is an escape hatch only for bootstrap, doctor, rollback/recovery, MCP unavailable/setup missing, provider-native repair out of scope, or explicit user request.
 
 ## MCP playbook
-- For starting, resuming, or recovering context: \`vgxness_session_restore\` with project + workspace before inferring state. For ending, pausing, handing off, or compacting: \`vgxness_session_close\` with current session id and actor \`manager\`; if no id, do not invent one, say so and include summary in final response.
-- SDD artifacts: list/read with \`vgxness_sdd_get_artifact\`/\`vgxness_sdd_list_artifacts\`; save phase output with \`vgxness_sdd_save_artifact\` only after the appropriate flow. SDD artifacts are not generic memory.
+- For starting, resuming, or recovering context: prefer \`vgxness_context_cockpit\` with project + workspace; treat \`vgxness_session_restore\` as one signal inside the cockpit, not authoritative truth. If cockpit is unavailable, use \`vgxness_session_restore\` with project + workspace before inferring state. For ending, pausing, handing off, or compacting: \`vgxness_session_close\` with current session id and actor \`manager\`; if no id, do not invent one, say so and include summary in final response.
+- SDD artifacts: list/read with \`vgxness_sdd_get_artifact\`/\`vgxness_sdd_list_artifacts\`; use \`payloadMode: "compact"\` by default for manager-facing reads/lists so the primary context stays clean. Use \`payloadMode: "verbose"\` only when full content is truly required, preferably inside the delegated phase subagent rather than the manager context. Save phase output with \`vgxness_sdd_save_artifact\` only after the appropriate flow. SDD artifacts are not generic memory.
 - Acceptance/readiness: confirm explicit human acceptance, use \`vgxness_sdd_accept_artifact\` only for explicit human acceptance, then \`vgxness_sdd_get_readiness\`/readiness tools before reporting state. Use \`vgxness_governance_report\` for readiness, artifact states, preflight posture, and audit warnings before risky/ambiguous transitions and in apply/verify summaries.
 - Memory: call \`vgxness_memory_search\`/\`vgxness_memory_get\` when prior work or unclear project context is referenced; call \`vgxness_memory_save\` for durable discoveries, decisions, bug fixes, config, patterns, or preferences; use \`vgxness_memory_update\` only to correct/evolve a known id. Do not duplicate full SDD artifacts as memory.
 - Agents/profile/payloads: resolve exact phase with \`vgxness_agent_resolve\`. \`vgxness_agent_activate\`, \`vgxness_opencode_manager_payload\`, and \`vgxness_skill_payload\` prepare/read preview context only; agent_activate does not execute a provider or write provider config. Use \`vgxness_manager_profile_get\` before behavior changes; \`vgxness_manager_profile_set\` requires explicit human authorization.

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

@@ -1,3 +1,4 @@
+import { vgxnessOpenCodePromptContractVersion } from './opencode-default-agent-config.js';
 export const PROVIDER_HEALTH_SAFETY = {
     readOnly: true,
     writesProviderConfig: false,
@@ -29,6 +30,7 @@ export const REQUIRED_PROVIDER_NATIVE_MCP_TOOLS = [
     'vgxness_memory_search',
     'vgxness_memory_get',
     'vgxness_memory_save',
+    'vgxness_context_cockpit',
     'vgxness_session_restore',
     'vgxness_session_close',
 ];
@@ -40,7 +42,7 @@ export function normalizeProviderHealthInput(input) {
         workspaceRoot: input.workspaceRoot?.trim() || process.cwd(),
         env: input.env ?? process.env,
         change: input.change?.trim() ?? '',
-        expectedPromptContractVersion: input.expectedPromptContractVersion ?? 4,
+        expectedPromptContractVersion: input.expectedPromptContractVersion ?? vgxnessOpenCodePromptContractVersion,
         payloadMode: input.payloadMode ?? 'compact',
     };
 }

package/dist/mcp/schema.js

@@ -21,6 +21,7 @@ export const SUPPORTED_VGX_MCP_TOOL_NAMES = [
     'vgxness_session_append_activity',
     'vgxness_session_close',
     'vgxness_session_restore',
+    'vgxness_context_cockpit',
     'vgxness_agent_resolve',
     'vgxness_agent_activate',
     'vgxness_manager_profile_get',
@@ -60,6 +61,7 @@ export const EXPOSED_VGX_MCP_TOOL_NAMES = [
     'session_append_activity',
     'session_close',
     'session_restore',
+    'context_cockpit',
     'agent_resolve',
     'agent_activate',
     'manager_profile_get',
@@ -257,6 +259,13 @@ export const VGX_MCP_TOOL_INPUT_SCHEMAS = {
         directory: z.string().min(1).optional(),
     })
         .passthrough(),
+    vgxness_context_cockpit: z
+        .object({
+        project: z.string().min(1),
+        directory: z.string().min(1).optional(),
+        limit: z.number().int().min(1).max(100).optional(),
+    })
+        .passthrough(),
     vgxness_agent_resolve: z
         .object({
         project: z.string().min(1).optional(),

package/dist/mcp/stdio-server.js

@@ -59,6 +59,8 @@ function descriptionForTool(publicToolName) {
         return 'Read-only run resume advisory inspect; plan-only and does not execute resume logic, invoke providers, write provider config, mutate retry/abandon/attempt state, or reconstruct sandboxes, worktrees, sessions, or transcripts.';
     if (publicToolName === 'run_resume_gate')
         return 'Read-only run resume gate advisory; plan-only and does not execute resume logic, invoke providers, write provider config, admit retries, abandon or mutate attempts, or reconstruct sandboxes, worktrees, sessions, or transcripts.';
+    if (publicToolName === 'context_cockpit')
+        return 'Read-only context cockpit for start/resume/recovery; returns latest restorable session plus bounded memory previews without traces, provider config writes, repository writes, runs, artifacts, or session mutations.';
     if (publicToolName === 'sdd_cockpit')
         return 'Read-only SDD cockpit summary with next decision, explicit acceptance state, metadata-only artifact summaries, and aggregate blockers.';
     const toolName = toInternalVgxMcpToolName(publicToolName);

package/dist/mcp/validation.js

@@ -66,6 +66,8 @@ export function validateVgxMcpToolCall(call) {
             return validationSuccess(tool.value, validateSessionCloseInput(input, tool.value));
         case 'vgxness_session_restore':
             return validationSuccess(tool.value, validateSessionRestoreInput(input, tool.value));
+        case 'vgxness_context_cockpit':
+            return validationSuccess(tool.value, validateContextCockpitInput(input, tool.value));
         case 'vgxness_agent_resolve':
             return validationSuccess(tool.value, validateAgentResolveInput(input, tool.value));
         case 'vgxness_agent_activate':
@@ -234,6 +236,26 @@ function validateSddCockpitInput(input, tool) {
         return record;
     return readProjectAndChange(record.value, tool);
 }
+function validateContextCockpitInput(input, tool) {
+    const record = inputRecord(input, tool, ['project', 'directory', 'limit']);
+    if (!record.ok)
+        return record;
+    const project = readNonEmptyString(record.value, 'project', tool);
+    if (!project.ok)
+        return project;
+    const result = { project: project.value };
+    const directory = readOptionalNonEmptyString(record.value, 'directory', tool);
+    if (!directory.ok)
+        return directory;
+    if (directory.value !== undefined)
+        result.directory = directory.value;
+    if (record.value.limit !== undefined) {
+        if (typeof record.value.limit !== 'number' || !Number.isSafeInteger(record.value.limit) || record.value.limit < 1 || record.value.limit > 100)
+            return validationFailure('limit must be an integer between 1 and 100', tool);
+        result.limit = record.value.limit;
+    }
+    return { ok: true, value: result };
+}
 function readProjectAndChange(record, tool) {
     const project = readNonEmptyString(record, 'project', tool);
     if (!project.ok)

package/dist/memory/memory-service.js

@@ -50,6 +50,54 @@ export class MemoryService {
         const result = this.observations.searchPreviews(filters);
         return this.record(result, context, { operation: 'observation.search', targetType: 'observation', topicKey: filters.topicKey });
     }
+    /** Read memory previews without writing provenance traces. */
+    searchObservationPreviewsNoTrace(filters) {
+        return this.observations.searchPreviews(filters);
+    }
+    /** Read compact current context without writing traces or mutating durable state. */
+    getContextCockpit(input) {
+        const limit = normalizeContextLimit(input.limit);
+        const memories = this.searchObservationPreviewsNoTrace({ project: input.project, limit });
+        if (!memories.ok)
+            return { ok: false, error: memories.error };
+        const session = this.restoreSession(input.directory === undefined ? { project: input.project } : { project: input.project, directory: input.directory });
+        if (!session.ok && session.error.code !== 'not_found')
+            return { ok: false, error: session.error };
+        const latestRestorableSession = session.ok ? session.value : undefined;
+        const newestMemoryUpdatedAt = memories.value[0]?.updatedAt;
+        const latestSessionEndedAt = latestRestorableSession?.endedAt;
+        const stale = latestRestorableSession === undefined || (newestMemoryUpdatedAt !== undefined && latestSessionEndedAt !== undefined && newestMemoryUpdatedAt > latestSessionEndedAt);
+        const staleness = {
+            stale,
+            reason: latestRestorableSession === undefined ? 'no-restorable-session' : stale ? 'memory-newer-than-session' : 'current',
+            ...(newestMemoryUpdatedAt === undefined ? {} : { newestMemoryUpdatedAt }),
+            ...(latestSessionEndedAt === undefined ? {} : { latestSessionEndedAt }),
+        };
+        return {
+            ok: true,
+            value: {
+                version: 1,
+                kind: 'context-cockpit',
+                project: input.project,
+                ...(input.directory === undefined ? {} : { directory: input.directory }),
+                ...(latestRestorableSession === undefined ? {} : { latestRestorableSession }),
+                memoryPreviews: memories.value,
+                staleness,
+                optionalSectionsOmitted: ['sdd', 'runs'],
+                notes: ['SDD and run summaries are omitted because safe no-trace metadata-only aggregation is not part of this cockpit path yet.'],
+                safety: {
+                    readOnly: true,
+                    recordsTraces: false,
+                    mutatesSessions: false,
+                    mutatesMemories: false,
+                    mutatesArtifacts: false,
+                    mutatesRuns: false,
+                    writesProviderConfig: false,
+                    mutatesRepository: false,
+                },
+            },
+        };
+    }
     listObservationRevisions(id, context) {
         const result = this.observations.listRevisions(id);
         return this.record(result, context, { operation: 'observation.revisions.list', targetType: 'observation', targetId: id });
@@ -140,3 +188,10 @@ class MemoryServiceTransactionRollback extends Error {
         super('Memory service transaction rolled back');
     }
 }
+function normalizeContextLimit(limit) {
+    if (limit === undefined)
+        return 5;
+    if (!Number.isFinite(limit))
+        return 5;
+    return Math.max(1, Math.min(100, Math.trunc(limit)));
+}

package/dist/memory/repositories/sessions.js

@@ -39,7 +39,7 @@ export class SessionRepository {
           AND summary IS NOT NULL
           AND TRIM(summary) <> ''
           AND (@directory IS NULL OR directory = @directory)
-        ORDER BY ended_at DESC
+        ORDER BY ended_at DESC, started_at DESC, id DESC
         LIMIT 1
       `)
                 .get({ project: input.project, directory: input.directory ?? null });

package/package.json

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