0xray 4.0.12 → 4.0.13

package/dist/nucleus/govern-http.js

@@ -1,175 +0,0 @@
-/**
- * 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

@@ -1,17 +0,0 @@
-/**
- * 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

@@ -1,12 +0,0 @@
-/**
- * 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

@@ -1,51 +0,0 @@
-/**
- * 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

@@ -1,62 +0,0 @@
-/**
- * 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

@@ -1,70 +0,0 @@
-/**
- * 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;