0xray 4.0.13 → 4.0.14

package/dist/nucleus/govern-http.js

@@ -0,0 +1,175 @@
+/**
+ * Nucleus HTTP Adapter — semantic convenience surface (Phase 0)
+ *
+ * IMPORTANT: MCP is the new standard (just as Dynamo is the established standard
+ * for the external governance signal). The canonical way for agents to call the
+ * nucleus is the first-class MCP tools (`govern_proposals`, `govern_reflection`)
+ * exposed by the governance MCP server (which already supports stdio + Streamable
+ * HTTP transport on /mcp and already delegates to the same GovernanceService).
+ *
+ * This module provides the *direct semantic convenience adapter*:
+ * - Pure `handleGovernRequest(body)` → returns the raw GovernanceResponse object.
+ * - Optional tiny Express app with `POST /govern` (and /health).
+ * - No full MCP JSON-RPC protocol overhead — ideal for curl, CI, simple bridges,
+ *   or anything that just wants the decision without speaking MCP.
+ *
+ * It reuses the exact same kernel (getGovernanceService + types) as the MCP path.
+ * Zero impact on the federation or existing MCP surfaces.
+ *
+ * Design goals:
+ * - Framework-agnostic pure handler (usable by Express, Fastify, raw http, tests, or in-process).
+ * - Only frameworkLogger.
+ * - Follows the thin-wrapper style of APITrigger.
+ *
+ * Usage (embeddable / in-process):
+ *   import { handleGovernRequest } from './nucleus/govern-http.js';
+ *   const result = await handleGovernRequest(req.body);
+ *
+ * Usage (standalone):
+ *   NUCLEUS_PORT=8787 node dist/nucleus/govern-http.js
+ */
+import express from 'express';
+import { getGovernanceService } from '../governance/governance-service.js';
+import { normalizeProposalWithSource, } from '../governance/governance-types.js';
+import { frameworkLogger } from '../core/framework-logger.js';
+const DEFAULT_PATH = '/govern';
+/**
+ * Pure handler. Can be used by any HTTP server (Express, Fastify, raw http, etc.)
+ * or called directly in tests / in-process.
+ */
+export async function handleGovernRequest(body, options) {
+    const request = body;
+    if (!request || !Array.isArray(request.proposals)) {
+        throw new Error('Invalid governance request: "proposals" array is required');
+    }
+    const svc = getGovernanceService();
+    // Merge caller options into the request options (prototype only — keeps surface tiny)
+    const mergedOptions = {};
+    if (request.options?.requireExternalDynamo !== undefined) {
+        mergedOptions.requireExternalDynamo = request.options.requireExternalDynamo;
+    }
+    if (options?.requireExternalDynamo !== undefined) {
+        mergedOptions.requireExternalDynamo = options.requireExternalDynamo;
+    }
+    const mergedRequest = {
+        ...request,
+        options: mergedOptions,
+    };
+    // Normalize each proposal to ensure source is present and valid
+    mergedRequest.proposals = mergedRequest.proposals.map((p) => normalizeProposalWithSource(p));
+    await frameworkLogger.log('nucleus-http', 'govern-request-received', 'info', {
+        proposalCount: mergedRequest.proposals.length,
+        hasContext: !!mergedRequest.context,
+        path: DEFAULT_PATH,
+    });
+    const response = await svc.govern(mergedRequest);
+    await frameworkLogger.log('nucleus-http', 'govern-response', 'success', {
+        overallDecision: response.overallDecision,
+        total: response.summary.total,
+        approved: response.summary.approved,
+        rejected: response.summary.rejected,
+    });
+    return response;
+}
+/* c8 ignore start -- adapter + auto-run are integration-level (tested in later slices / E2E) */
+/**
+ * Minimal Express app (prototype only).
+ * Mirrors the shape and logging discipline of APITrigger.
+ */
+export class GovernHTTPAdapter {
+    app;
+    config;
+    initialized = false;
+    constructor(config = {}) {
+        this.config = {
+            enabled: true,
+            path: DEFAULT_PATH,
+            apiKey: '',
+            port: 8787,
+            ...config,
+        };
+        this.app = express();
+    }
+    async initialize() {
+        if (this.initialized || !this.config.enabled)
+            return;
+        this.app.use(express.json({ limit: '5mb' }));
+        // Optional API key (same pattern as APITrigger for early internal use)
+        if (this.config.apiKey) {
+            this.app.use((req, res, next) => {
+                const key = req.headers['x-api-key'];
+                if (!key || key !== this.config.apiKey) {
+                    res.status(403).json({ error: 'Invalid or missing API key' });
+                    return;
+                }
+                next();
+            });
+        }
+        const governPath = this.config.path;
+        // The direct semantic /govern endpoint (convenience, not the MCP standard surface).
+        // Agents that speak MCP should use the governance MCP server's tools (or its /mcp endpoint).
+        this.app.post(governPath, async (req, res) => {
+            try {
+                const result = await handleGovernRequest(req.body);
+                res.status(200).json(result);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                await frameworkLogger.log('nucleus-http', 'govern-error', 'error', { message });
+                res.status(400).json({
+                    error: 'Governance request failed',
+                    message,
+                    overallDecision: 'reject',
+                });
+            }
+        });
+        // Tiny health surface (useful for the verification loop later)
+        this.app.get(governPath + '/health', (_req, res) => {
+            res.json({
+                status: 'ok',
+                surface: 'nucleus-http',
+                version: 'v3-prototype',
+                endpoint: governPath,
+                timestamp: new Date().toISOString(),
+            });
+        });
+        this.initialized = true;
+        await frameworkLogger.log('nucleus-http', 'adapter-initialized', 'success', {
+            path: governPath,
+            port: this.config.port,
+            apiKeyProtected: !!this.config.apiKey,
+        });
+    }
+    getApp() {
+        return this.app;
+    }
+    async listen() {
+        await this.initialize();
+        const port = this.config.port;
+        this.app.listen(port, () => {
+            // We intentionally use frameworkLogger here too; the listen callback is the one place
+            // a startup banner is acceptable if we ever add a structured one. For now the log above suffices.
+            void frameworkLogger.log('nucleus-http', 'listening', 'success', { port, path: this.config.path });
+        });
+    }
+    shutdown() {
+        this.initialized = false;
+    }
+}
+// Allow direct execution for the absolute smallest validation loop:
+//   node --loader ts-node/esm src/nucleus/govern-http.ts
+// (or after build: node dist/nucleus/govern-http.js)
+if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith('govern-http.ts')) {
+    const adapter = new GovernHTTPAdapter({
+        port: Number(process.env.NUCLEUS_PORT || 8787),
+        path: process.env.NUCLEUS_PATH || DEFAULT_PATH,
+    });
+    // Fire and forget — the listen method logs via frameworkLogger
+    void adapter.listen().catch(async (err) => {
+        await frameworkLogger.log('nucleus-http', 'listen-failed', 'error', {
+            error: err instanceof Error ? err.message : String(err),
+        });
+        process.exit(1);
+    });
+}
+/* c8 ignore stop */

package/dist/nucleus/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * xray Nucleus — barrel export
+ *
+ * Import from here for the stable nucleus surface:
+ *   import { handleGovernRequest, governSingle } from './nucleus/index.js';
+ */
+export { handleGovernRequest, governSingle, getGovernanceService, GovernHTTPAdapter, NUCLEUS_VERSION, NUCLEUS_DESCRIPTION, } from './kernel.js';
+export type { GovernHTTPConfig } from './govern-http.js';
+export type { GovernanceRequest, GovernanceResponse, GovernanceProposal, GovernanceVote, GovernanceResult, GovernanceContext, GovernOptions, ProposalType, } from '../governance/governance-types.js';
+export { pluginRegistry, } from './plugin-registry.js';
+export type { SkillPlugin, SkillToolPlugin, SkillProposalArgs, SkillPluginResult, ToolDefinition, } from './plugin-registry.js';
+export { scoreComplexity, routeToAgent, scoreAndRoute } from './thin-dispatch.js';
+export type { ComplexityMetrics, ComplexityScore, ComplexityLevel, ComplexityThresholds, } from './thin-dispatch.js';
+export { NUCLEUS_THIN_DISPATCH_VERSION } from './thin-dispatch.js';
+export { LEAD_DEV_RULES, isLeadDevModeActive, buildLeadDevPlan, buildSessionBootContext, shouldFlagFullTestSuite, } from './autonomy-kernel.js';
+export { registerDefaultPlugins } from './default-plugins.js';
+export type { DefaultPluginsResult } from './default-plugins.js';

package/dist/nucleus/index.js

@@ -0,0 +1,12 @@
+/**
+ * xray Nucleus — barrel export
+ *
+ * Import from here for the stable nucleus surface:
+ *   import { handleGovernRequest, governSingle } from './nucleus/index.js';
+ */
+export { handleGovernRequest, governSingle, getGovernanceService, GovernHTTPAdapter, NUCLEUS_VERSION, NUCLEUS_DESCRIPTION, } from './kernel.js';
+export { pluginRegistry, } from './plugin-registry.js';
+export { scoreComplexity, routeToAgent, scoreAndRoute } from './thin-dispatch.js';
+export { NUCLEUS_THIN_DISPATCH_VERSION } from './thin-dispatch.js';
+export { LEAD_DEV_RULES, isLeadDevModeActive, buildLeadDevPlan, buildSessionBootContext, shouldFlagFullTestSuite, } from './autonomy-kernel.js';
+export { registerDefaultPlugins } from './default-plugins.js';

package/dist/nucleus/kernel.d.ts

@@ -0,0 +1,51 @@
+/**
+ * xray Nucleus — the callable governance kernel (Phase 1.1 facade)
+ *
+ * This is the primary, stable import surface for the v3 nucleus.
+ *
+ * Consumers (bridges, custom tools, the MCP governance server, future self-proposal
+ * engines, CLI, etc.) should import from here rather than reaching into
+ * governance-service.ts, govern-http.ts, or postprocessor internals directly.
+ *
+ * Goals:
+ * - Single place to import the core "govern" capability + supporting types.
+ * - Zero risk to the 41-server federation or existing bridges.
+ * - Easy to tree-shake / split later (e.g. "nucleus/core", "nucleus/http").
+ * - Documents the public kernel contract.
+ *
+ * Current surface (Phase 1.1):
+ * - handleGovernRequest: the pure semantic convenience handler (direct JSON in/out)
+ * - getGovernanceService: the underlying singleton (for advanced / in-process use)
+ * - Governance types
+ * - MetamorphosisEngine interface (for PostProcessor lifecycle integration)
+ *
+ * MCP remains the canonical standard surface (see governance.server.ts).
+ * The direct HTTP adapter (govern-http.ts) is a convenience on top of this kernel.
+ *
+ * Anti-goals (for this file):
+ * - No new business logic
+ * - No side effects on import
+ * - Does not pull in the full 25 knowledge-skill servers (dynamic via pluginRegistry only)
+ */
+import type { GovernOptions, GovernanceContext, GovernanceRequest, GovernanceResponse } from '../governance/governance-types.js';
+import { handleGovernRequest } from './govern-http.js';
+export { handleGovernRequest };
+export type { GovernHTTPConfig } from './govern-http.js';
+export { getGovernanceService } from '../governance/governance-service.js';
+export type { GovernanceRequest, GovernanceResponse, GovernanceProposal, GovernanceVote, GovernanceResult, GovernanceContext, GovernOptions, ProposalType, } from '../governance/governance-types.js';
+export type { MetamorphosisEngine, MetamorphosisProposal, } from '../types/metamorphosis.js';
+export { GovernHTTPAdapter } from './govern-http.js';
+export { pluginRegistry } from './plugin-registry.js';
+export type { SkillPlugin, SkillToolPlugin, SkillProposalArgs, SkillPluginResult } from './plugin-registry.js';
+/**
+ * High-level kernel description for introspection / docs.
+ */
+export declare const NUCLEUS_VERSION = "0.1.0";
+export declare const NUCLEUS_DESCRIPTION: string;
+/**
+ * Quick helper for the common case: govern a single proposal and get the overall decision.
+ * (Thin wrapper — real power users should use handleGovernRequest directly for batch + full response.)
+ */
+export declare function governSingle(proposal: Omit<GovernanceRequest['proposals'][0], 'id'> & {
+    id?: string;
+}, context?: GovernanceContext, options?: GovernOptions): Promise<GovernanceResponse>;

package/dist/nucleus/kernel.js

@@ -0,0 +1,62 @@
+/**
+ * xray Nucleus — the callable governance kernel (Phase 1.1 facade)
+ *
+ * This is the primary, stable import surface for the v3 nucleus.
+ *
+ * Consumers (bridges, custom tools, the MCP governance server, future self-proposal
+ * engines, CLI, etc.) should import from here rather than reaching into
+ * governance-service.ts, govern-http.ts, or postprocessor internals directly.
+ *
+ * Goals:
+ * - Single place to import the core "govern" capability + supporting types.
+ * - Zero risk to the 41-server federation or existing bridges.
+ * - Easy to tree-shake / split later (e.g. "nucleus/core", "nucleus/http").
+ * - Documents the public kernel contract.
+ *
+ * Current surface (Phase 1.1):
+ * - handleGovernRequest: the pure semantic convenience handler (direct JSON in/out)
+ * - getGovernanceService: the underlying singleton (for advanced / in-process use)
+ * - Governance types
+ * - MetamorphosisEngine interface (for PostProcessor lifecycle integration)
+ *
+ * MCP remains the canonical standard surface (see governance.server.ts).
+ * The direct HTTP adapter (govern-http.ts) is a convenience on top of this kernel.
+ *
+ * Anti-goals (for this file):
+ * - No new business logic
+ * - No side effects on import
+ * - Does not pull in the full 25 knowledge-skill servers (dynamic via pluginRegistry only)
+ */
+import { handleGovernRequest } from './govern-http.js';
+// Re-export the pure handler (the main "call the nucleus" entry point)
+export { handleGovernRequest };
+// Re-export the canonical way to obtain the service (used by MCP, internal code, and advanced callers)
+export { getGovernanceService } from '../governance/governance-service.js';
+// Convenience re-export of the HTTP adapter for anyone who wants the tiny Express wrapper
+// (still considered "convenience", not core kernel)
+export { GovernHTTPAdapter } from './govern-http.js';
+// Plugin registry — dynamic skill and tool dispatch
+export { pluginRegistry } from './plugin-registry.js';
+/**
+ * High-level kernel description for introspection / docs.
+ */
+export const NUCLEUS_VERSION = '0.1.0'; // Phase 1 facade version
+export const NUCLEUS_DESCRIPTION = 'xray governance kernel — external Dynamo signal + 3-agent deliberation exposed as a callable library. ' +
+    'MCP is the standard surface; direct handleGovernRequest + HTTP adapter are convenience paths.';
+/**
+ * Quick helper for the common case: govern a single proposal and get the overall decision.
+ * (Thin wrapper — real power users should use handleGovernRequest directly for batch + full response.)
+ */
+export async function governSingle(proposal, context, options) {
+    const fullRequest = {
+        proposals: [
+            {
+                id: proposal.id || `prop-${Date.now()}`,
+                ...proposal,
+            },
+        ],
+        context,
+        ...(options ? { options } : {}),
+    };
+    return handleGovernRequest(fullRequest);
+}

package/dist/nucleus/lead-dev-plan-persistence.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Todo-level lead-dev plan persistence — spawn gate survives beyond 4h mtime
+ * while outstanding todos remain. SSOT for plan todo status sync.
+ */
+import type { LeadDevPlan, LeadDevTodo } from './autonomy-kernel.js';
+export interface PersistedLeadDevPlan extends LeadDevPlan {
+    persistedAt?: string;
+    sessionId?: string;
+    planGeneration?: number;
+}
+export interface SpawnTodoValidation {
+    valid: boolean;
+    reason?: string;
+    gate?: string;
+    hint?: Record<string, unknown>;
+    expectedTodoId?: string | null;
+}
+export declare const DEFAULT_PLAN_STALE_MS: number;
+export declare const DEFAULT_PLAN_ARCHIVE_MARKER_MS: number;
+export declare function leadDevPlanStatePath(projectRoot?: string): string;
+export declare function loadLeadDevPlanStaleMs(projectRoot?: string): number;
+export declare function loadLeadDevPlanArchiveMarkerMs(projectRoot?: string): number;
+/**
+ * Mandatory synthesis consults (s.1–s.3) must stay spawnable until complete —
+ * never treat an active realignment plan as stale while consult todos remain.
+ */
+export declare function isProtectedSynthesisRealignmentPlan(plan: PersistedLeadDevPlan): boolean;
+/**
+ * Stale when every outstanding todo is still pending and plan age exceeds TTL.
+ * In-progress or completed todos imply active work — plan stays valid.
+ */
+export declare function isLeadDevPlanStale(plan: PersistedLeadDevPlan, projectRoot?: string): boolean;
+export declare function archiveStaleLeadDevPlan(projectRoot?: string): {
+    archived: boolean;
+    archivePath?: string;
+    reason?: string;
+};
+/** Recent stale archival — keeps spawn-plan-stale gate after session-start cleanup. */
+export declare function findRecentStalePlanArchive(projectRoot?: string, maxAgeMs?: number): {
+    archivePath: string;
+    archivedAt: string;
+} | null;
+export declare function loadPersistedLeadDevPlan(projectRoot?: string): PersistedLeadDevPlan | null;
+export declare function savePersistedLeadDevPlan(plan: PersistedLeadDevPlan, projectRoot?: string): string;
+export declare function allPlanTodos(plan: PersistedLeadDevPlan): LeadDevTodo[];
+export declare function getOutstandingTodos(plan: PersistedLeadDevPlan): LeadDevTodo[];
+/** First outstanding todo in phase order */
+export declare function getNextRequiredTodo(plan: PersistedLeadDevPlan): LeadDevTodo | null;
+/**
+ * Plan valid for spawn when active and either:
+ * - outstanding todos remain (ignores 4h mtime), or
+ * - all todos complete and persistedAt within TTL
+ */
+export declare function hasValidLeadDevPlanForSpawn(projectRoot?: string, _sessionId?: string | null): boolean;
+export declare function isSynthesisRealignmentPlan(plan: PersistedLeadDevPlan): boolean;
+export declare function getSynthesisConsultTodos(plan: PersistedLeadDevPlan): LeadDevTodo[];
+export declare function areSynthesisConsultTodosComplete(plan: PersistedLeadDevPlan): boolean;
+export declare function updatePlanTodoStatus(todoId: string, status: LeadDevTodo['status'], projectRoot?: string, sessionId?: string | null): boolean;
+export declare function bindPlanToSession(sessionId: string, projectRoot?: string): PersistedLeadDevPlan | null;
+export interface SpawnToolInput {
+    prompt?: string;
+    description?: string;
+    task?: string;
+    subagent_type?: string;
+    agent?: string;
+    delegationId?: string;
+    planTodoId?: string;
+}
+export declare function validateSpawnMatchesTodo(toolInput: SpawnToolInput, projectRoot?: string, expectedTodo?: LeadDevTodo | null, sessionId?: string | null): SpawnTodoValidation;
+export declare function markTodoInProgressOnSpawn(toolInput: SpawnToolInput, projectRoot?: string, sessionId?: string | null): string | null;