@cleocode/cleo 2026.4.158 → 2026.5.0

package/dist/dispatch/context/session-context.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Process-scoped session context for the CLEO dispatch layer.
+ *
+ * Each Claude Code conversation spawns its own process, so 5 concurrent
+ * agents = 5 isolated SessionContext instances with zero shared state.
+ * This replaces the fragile process.env.CLEO_SESSION_ID mechanism.
+ *
+ * @epic T4959
+ */
+/**
+ * Immutable snapshot of the bound session context.
+ */
+export interface SessionContext {
+    /** Active session ID. */
+    sessionId: string;
+    /** Session scope. */
+    scope: {
+        type: string;
+        epicId?: string;
+    };
+    /** Whether full audit logging is enabled for behavioral grading. */
+    gradeMode: boolean;
+    /** PID of the process that bound this context. */
+    agentPid: number;
+    /** ISO timestamp when this context was bound. */
+    boundAt: string;
+    /**
+     * Active CANT agent peer ID for Wave 2 memory isolation (T1086).
+     *
+     * Resolved at session-bind time from the CLEO_AGENT_PEER_ID environment
+     * variable (set by the orchestrator spawn shim) or from the currently-loaded
+     * CANT agent discovered via native-loader.ts.
+     *
+     * Defaults to `"global"` when no CANT agent is active, which means all
+     * memory writes are shared across all peers — the pre-Wave-2 behavior.
+     *
+     * Domain handlers read this via {@link getActivePeerId} and pass it through
+     * to brain-retrieval / brain-search as the `peerId` filter parameter.
+     */
+    activePeerId: string;
+}
+/**
+ * The fallback peer ID used when no CANT agent is active.
+ *
+ * All legacy (pre-Wave-2) memory entries carry this value, and any agent
+ * that does not declare an explicit peer ID writes to the global pool.
+ */
+export declare const GLOBAL_PEER_ID = "global";
+/**
+ * Resolve the active CANT peer ID for the current process.
+ *
+ * Resolution order (first match wins):
+ * 1. `CLEO_AGENT_PEER_ID` environment variable — set by the orchestrator
+ *    spawn shim when launching a sub-agent.
+ * 2. `CLEO_AGENT_ID` environment variable — legacy / manual override.
+ * 3. Falls back to `"global"` (backward-compatible, no isolation).
+ *
+ * This function is intentionally synchronous and pure — it never reads
+ * the filesystem or native-loader at call time so the dispatch hot path
+ * is not blocked by I/O. A future Wave 8 enhancement may wire the
+ * native-loader registry here for richer CANT-DSL-level resolution.
+ *
+ * @returns Resolved peer ID string (never empty, never undefined).
+ */
+export declare function resolveActivePeerId(): string;
+/**
+ * Get the active peer ID from the bound session context, or resolve it
+ * directly when no session is bound (e.g. one-shot CLI invocations).
+ *
+ * Callers in domain handlers SHOULD prefer this over reading the context
+ * directly — it handles the no-session edge case gracefully.
+ *
+ * @returns Active peer ID string (never empty).
+ */
+export declare function getActivePeerId(): string;
+/**
+ * Bind a session to the current process.
+ * Called by session.start mutation handler after successful session creation.
+ *
+ * Resolves {@link SessionContext.activePeerId} from the environment at bind
+ * time so all subsequent domain handler calls in this process use a stable
+ * peer ID for the entire session lifetime.
+ *
+ * @throws if a session is already bound (call unbindSession first).
+ */
+export declare function bindSession(ctx: Omit<SessionContext, 'agentPid' | 'boundAt' | 'activePeerId'> & {
+    activePeerId?: string;
+}): SessionContext;
+/**
+ * Get the currently bound session context, or null if none is bound.
+ */
+export declare function getBoundSession(): SessionContext | null;
+/**
+ * Check whether a session is currently bound.
+ */
+export declare function hasSession(): boolean;
+/**
+ * Unbind the current session context.
+ * Called by session.end mutation handler.
+ *
+ * @returns The unbound context, or null if nothing was bound.
+ */
+export declare function unbindSession(): SessionContext | null;
+/**
+ * Reset the session context (for testing only).
+ */
+export declare function resetSessionContext(): void;
+//# sourceMappingURL=session-context.d.ts.map

package/dist/dispatch/context/session-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-context.d.ts","sourceRoot":"","sources":["../../../src/dispatch/context/session-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,qBAAqB;IACrB,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,oEAAoE;IACpE,SAAS,EAAE,OAAO,CAAC;IACnB,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;;OAYG;IACH,YAAY,EAAE,MAAM,CAAC;CACtB;AAYD;;;;;GAKG;AACH,eAAO,MAAM,cAAc,WAAW,CAAC;AAEvC;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAM5C;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,IAAI,CAAC,cAAc,EAAE,UAAU,GAAG,SAAS,GAAG,cAAc,CAAC,GAAG;IACnE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GACA,cAAc,CAchB;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,cAAc,GAAG,IAAI,CAEvD;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,OAAO,CAEpC;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,IAAI,cAAc,GAAG,IAAI,CAIrD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C"}

package/dist/dispatch/context/session-context.js

@@ -0,0 +1,111 @@
+/**
+ * Process-scoped session context for the CLEO dispatch layer.
+ *
+ * Each Claude Code conversation spawns its own process, so 5 concurrent
+ * agents = 5 isolated SessionContext instances with zero shared state.
+ * This replaces the fragile process.env.CLEO_SESSION_ID mechanism.
+ *
+ * @epic T4959
+ */
+// ---------------------------------------------------------------------------
+// Module-level singleton
+// ---------------------------------------------------------------------------
+let _context = null;
+// ---------------------------------------------------------------------------
+// Peer ID resolution (T1086)
+// ---------------------------------------------------------------------------
+/**
+ * The fallback peer ID used when no CANT agent is active.
+ *
+ * All legacy (pre-Wave-2) memory entries carry this value, and any agent
+ * that does not declare an explicit peer ID writes to the global pool.
+ */
+export const GLOBAL_PEER_ID = 'global';
+/**
+ * Resolve the active CANT peer ID for the current process.
+ *
+ * Resolution order (first match wins):
+ * 1. `CLEO_AGENT_PEER_ID` environment variable — set by the orchestrator
+ *    spawn shim when launching a sub-agent.
+ * 2. `CLEO_AGENT_ID` environment variable — legacy / manual override.
+ * 3. Falls back to `"global"` (backward-compatible, no isolation).
+ *
+ * This function is intentionally synchronous and pure — it never reads
+ * the filesystem or native-loader at call time so the dispatch hot path
+ * is not blocked by I/O. A future Wave 8 enhancement may wire the
+ * native-loader registry here for richer CANT-DSL-level resolution.
+ *
+ * @returns Resolved peer ID string (never empty, never undefined).
+ */
+export function resolveActivePeerId() {
+    const envPeerId = process.env['CLEO_AGENT_PEER_ID'] ?? process.env['CLEO_AGENT_ID'] ?? null;
+    if (envPeerId && envPeerId.trim().length > 0) {
+        return envPeerId.trim();
+    }
+    return GLOBAL_PEER_ID;
+}
+/**
+ * Get the active peer ID from the bound session context, or resolve it
+ * directly when no session is bound (e.g. one-shot CLI invocations).
+ *
+ * Callers in domain handlers SHOULD prefer this over reading the context
+ * directly — it handles the no-session edge case gracefully.
+ *
+ * @returns Active peer ID string (never empty).
+ */
+export function getActivePeerId() {
+    return _context?.activePeerId ?? resolveActivePeerId();
+}
+/**
+ * Bind a session to the current process.
+ * Called by session.start mutation handler after successful session creation.
+ *
+ * Resolves {@link SessionContext.activePeerId} from the environment at bind
+ * time so all subsequent domain handler calls in this process use a stable
+ * peer ID for the entire session lifetime.
+ *
+ * @throws if a session is already bound (call unbindSession first).
+ */
+export function bindSession(ctx) {
+    if (_context) {
+        throw new Error(`Session already bound: ${_context.sessionId}. ` +
+            `Call unbindSession() before binding a new session.`);
+    }
+    _context = {
+        ...ctx,
+        agentPid: process.pid,
+        boundAt: new Date().toISOString(),
+        activePeerId: ctx.activePeerId ?? resolveActivePeerId(),
+    };
+    return _context;
+}
+/**
+ * Get the currently bound session context, or null if none is bound.
+ */
+export function getBoundSession() {
+    return _context;
+}
+/**
+ * Check whether a session is currently bound.
+ */
+export function hasSession() {
+    return _context !== null;
+}
+/**
+ * Unbind the current session context.
+ * Called by session.end mutation handler.
+ *
+ * @returns The unbound context, or null if nothing was bound.
+ */
+export function unbindSession() {
+    const prev = _context;
+    _context = null;
+    return prev;
+}
+/**
+ * Reset the session context (for testing only).
+ */
+export function resetSessionContext() {
+    _context = null;
+}
+//# sourceMappingURL=session-context.js.map

package/dist/dispatch/context/session-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-context.js","sourceRoot":"","sources":["../../../src/dispatch/context/session-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAgCH,8EAA8E;AAC9E,yBAAyB;AACzB,8EAA8E;AAE9E,IAAI,QAAQ,GAA0B,IAAI,CAAC;AAE3C,8EAA8E;AAC9E,6BAA6B;AAC7B,8EAA8E;AAE9E;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,QAAQ,CAAC;AAEvC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,mBAAmB;IACjC,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,IAAI,CAAC;IAC5F,IAAI,SAAS,IAAI,SAAS,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7C,OAAO,SAAS,CAAC,IAAI,EAAE,CAAC;IAC1B,CAAC;IACD,OAAO,cAAc,CAAC;AACxB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,QAAQ,EAAE,YAAY,IAAI,mBAAmB,EAAE,CAAC;AACzD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CACzB,GAEC;IAED,IAAI,QAAQ,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,0BAA0B,QAAQ,CAAC,SAAS,IAAI;YAC9C,oDAAoD,CACvD,CAAC;IACJ,CAAC;IACD,QAAQ,GAAG;QACT,GAAG,GAAG;QACN,QAAQ,EAAE,OAAO,CAAC,GAAG;QACrB,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACjC,YAAY,EAAE,GAAG,CAAC,YAAY,IAAI,mBAAmB,EAAE;KACxD,CAAC;IACF,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU;IACxB,OAAO,QAAQ,KAAK,IAAI,CAAC;AAC3B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa;IAC3B,MAAM,IAAI,GAAG,QAAQ,CAAC;IACtB,QAAQ,GAAG,IAAI,CAAC;IAChB,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB;IACjC,QAAQ,GAAG,IAAI,CAAC;AAClB,CAAC"}

package/dist/dispatch/dispatcher.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Central Dispatcher -- Routes requests through middleware to domain handlers.
+ *
+ * The dispatcher is the single entry point for the CLI adapter.
+ * It resolves operations, validates parameters, runs the middleware pipeline,
+ * and delegates to the appropriate domain handler.
+ *
+ * Flow: DispatchRequest → resolve → param validation → middleware → handler
+ *
+ * ## T1088 — Dialectic Evaluator Hook (PSYCHE Wave 3)
+ *
+ * After each successful mutate operation, the dispatcher fires a background
+ * `evaluateDialectic` call via `setImmediate` if all of the following apply:
+ *
+ *   1. The response indicates `success: true`.
+ *   2. The request gateway is `"mutate"` (state-modifying user-facing commands).
+ *   3. A `sessionId` is present on the request (identifies conversation context).
+ *   4. The in-memory rate limiter allows the evaluation (1 per 10s per session).
+ *
+ * Errors from the background evaluation are caught and logged at `warn` level
+ * so they never affect the caller.
+ *
+ * @epic T4820
+ * @task T1088
+ */
+import type { DispatchRequest, DispatchResponse, DomainHandler, Middleware } from './types.js';
+export interface DispatcherConfig {
+    handlers: Map<string, DomainHandler>;
+    middlewares?: Middleware[];
+}
+export declare class Dispatcher {
+    private handlers;
+    private pipeline;
+    constructor(config: DispatcherConfig);
+    dispatch(request: DispatchRequest): Promise<DispatchResponse>;
+}
+//# sourceMappingURL=dispatcher.d.ts.map

package/dist/dispatch/dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/dispatch/dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAMH,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAmC/F,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACrC,WAAW,CAAC,EAAE,UAAU,EAAE,CAAC;CAC5B;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,QAAQ,CAAa;gBAEjB,MAAM,EAAE,gBAAgB;IAO9B,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;CA4IpE"}

package/dist/dispatch/dispatcher.js

@@ -0,0 +1,172 @@
+/**
+ * Central Dispatcher -- Routes requests through middleware to domain handlers.
+ *
+ * The dispatcher is the single entry point for the CLI adapter.
+ * It resolves operations, validates parameters, runs the middleware pipeline,
+ * and delegates to the appropriate domain handler.
+ *
+ * Flow: DispatchRequest → resolve → param validation → middleware → handler
+ *
+ * ## T1088 — Dialectic Evaluator Hook (PSYCHE Wave 3)
+ *
+ * After each successful mutate operation, the dispatcher fires a background
+ * `evaluateDialectic` call via `setImmediate` if all of the following apply:
+ *
+ *   1. The response indicates `success: true`.
+ *   2. The request gateway is `"mutate"` (state-modifying user-facing commands).
+ *   3. A `sessionId` is present on the request (identifies conversation context).
+ *   4. The in-memory rate limiter allows the evaluation (1 per 10s per session).
+ *
+ * Errors from the background evaluation are caught and logged at `warn` level
+ * so they never affect the caller.
+ *
+ * @epic T4820
+ * @task T1088
+ */
+import { getLogger, getProjectRoot } from '@cleocode/core';
+import { createDispatchMeta } from './lib/meta.js';
+import { compose } from './middleware/pipeline.js';
+import { resolve, validateRequiredParams } from './registry.js';
+// ============================================================================
+// T1088: In-memory rate limiter for dialectic evaluation
+// ============================================================================
+/** Rate limit window in milliseconds (1 evaluation per 10 seconds per session). */
+const DIALECTIC_RATE_LIMIT_MS = 10_000;
+/** In-memory last-evaluation timestamp per session ID. */
+const _dialecticLastEvalMs = new Map();
+/**
+ * Check whether a new dialectic evaluation is allowed for a session.
+ *
+ * Rate limit: 1 evaluation per `DIALECTIC_RATE_LIMIT_MS` per session.
+ * Records the timestamp when allowed.
+ *
+ * @param sessionId - The session to check.
+ * @returns `true` when the evaluation is allowed.
+ */
+function isDialecticEvalAllowed(sessionId) {
+    const last = _dialecticLastEvalMs.get(sessionId) ?? 0;
+    const now = Date.now();
+    if (now - last < DIALECTIC_RATE_LIMIT_MS) {
+        return false;
+    }
+    _dialecticLastEvalMs.set(sessionId, now);
+    return true;
+}
+export class Dispatcher {
+    handlers;
+    pipeline;
+    constructor(config) {
+        this.handlers = config.handlers;
+        this.pipeline = config.middlewares?.length
+            ? compose(config.middlewares)
+            : (_req, next) => next();
+    }
+    async dispatch(request) {
+        const startTime = Date.now();
+        // 1. Resolve operation from registry
+        const resolved = resolve(request.gateway, request.domain, request.operation);
+        if (!resolved) {
+            return {
+                meta: createDispatchMeta(request.gateway, request.domain, request.operation, startTime, request.source, request.requestId),
+                success: false,
+                error: {
+                    code: 'E_INVALID_OPERATION',
+                    message: `Unknown operation: ${request.gateway}:${request.domain}.${request.operation}`,
+                },
+            };
+        }
+        // 2. Validate required params
+        const missing = validateRequiredParams(resolved.def, request.params);
+        if (missing.length > 0) {
+            return {
+                meta: createDispatchMeta(request.gateway, resolved.domain, resolved.operation, startTime, request.source, request.requestId),
+                success: false,
+                error: {
+                    code: 'E_MISSING_PARAMS',
+                    message: `Missing required parameters: ${missing.join(', ')}`,
+                    details: { missing },
+                },
+            };
+        }
+        // 3. Look up domain handler
+        const handler = this.handlers.get(resolved.domain);
+        if (!handler) {
+            return {
+                meta: createDispatchMeta(request.gateway, resolved.domain, resolved.operation, startTime, request.source, request.requestId),
+                success: false,
+                error: {
+                    code: 'E_NO_HANDLER',
+                    message: `No handler for domain: ${resolved.domain}`,
+                },
+            };
+        }
+        // 4. Run middleware pipeline with terminal handler
+        const terminal = async () => {
+            if (request.gateway === 'query') {
+                return handler.query(resolved.operation, request.params);
+            }
+            else {
+                return handler.mutate(resolved.operation, request.params);
+            }
+        };
+        const response = await this.pipeline(request, terminal);
+        // 5. Stamp timing and tracing metadata
+        response.meta.duration_ms = Date.now() - startTime;
+        response.meta.requestId = request.requestId;
+        response.meta.source = request.source;
+        // 6. Stamp session identity (T4959)
+        if (request.sessionId) {
+            response.meta.sessionId = request.sessionId;
+        }
+        // 7. T1088: Background dialectic evaluation hook
+        //
+        // Fires asynchronously via setImmediate so the response is returned to the
+        // caller immediately.  Conditions:
+        //   a) Response was successful
+        //   b) This was a mutate (state-modifying, user-facing) operation
+        //   c) A session ID is present (needed for narrative + source tagging)
+        //   d) Rate limiter allows this session to be evaluated right now
+        //
+        // The userMessage is synthesised from the operation + params since the
+        // raw CLI string is not available at this layer.  Future Wave 4 work can
+        // thread the original raw command string through DispatchRequest.
+        if (response.success &&
+            request.gateway === 'mutate' &&
+            request.sessionId &&
+            isDialecticEvalAllowed(request.sessionId)) {
+            const capturedRequest = request;
+            const capturedSessionId = request.sessionId;
+            setImmediate(() => {
+                // Lazy import to avoid loading the evaluator at startup (it pulls in
+                // the Vercel AI SDK and zod which add ~50ms to cold start).
+                Promise.all([
+                    import('@cleocode/core/memory/dialectic-evaluator.js'),
+                    import('@cleocode/core/store/nexus-sqlite.js'),
+                    import('@cleocode/core/store/memory-sqlite.js'),
+                ])
+                    .then(async ([{ evaluateDialectic, applyInsights }, { getNexusDb }, { getBrainDb }]) => {
+                    const projectRoot = getProjectRoot();
+                    const turn = {
+                        userMessage: `cleo ${capturedRequest.domain} ${capturedRequest.operation} ${JSON.stringify(capturedRequest.params ?? {})}`,
+                        systemResponse: `Operation succeeded in domain "${capturedRequest.domain}".`,
+                        activePeerId: capturedRequest.params?.['peerId'] ?? 'global',
+                        sessionId: capturedSessionId,
+                    };
+                    const insights = await evaluateDialectic(turn);
+                    const [nexusDb, brainDb] = await Promise.all([getNexusDb(), getBrainDb()]);
+                    await applyInsights(insights, nexusDb, brainDb, {
+                        sessionId: capturedSessionId,
+                        activePeerId: turn.activePeerId,
+                        projectRoot,
+                    });
+                })
+                    .catch((err) => {
+                    const log = getLogger('dialectic-hook');
+                    log.warn({ err }, 'dialectic-evaluator failed');
+                });
+            });
+        }
+        return response;
+    }
+}
+//# sourceMappingURL=dispatcher.js.map

package/dist/dispatch/dispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatcher.js","sourceRoot":"","sources":["../../src/dispatch/dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAGhE,+EAA+E;AAC/E,yDAAyD;AACzD,+EAA+E;AAE/E,mFAAmF;AACnF,MAAM,uBAAuB,GAAG,MAAM,CAAC;AAEvC,0DAA0D;AAC1D,MAAM,oBAAoB,GAAG,IAAI,GAAG,EAAkB,CAAC;AAEvD;;;;;;;;GAQG;AACH,SAAS,sBAAsB,CAAC,SAAiB;IAC/C,MAAM,IAAI,GAAG,oBAAoB,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACtD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,IAAI,GAAG,GAAG,IAAI,GAAG,uBAAuB,EAAE,CAAC;QACzC,OAAO,KAAK,CAAC;IACf,CAAC;IACD,oBAAoB,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IACzC,OAAO,IAAI,CAAC;AACd,CAAC;AAWD,MAAM,OAAO,UAAU;IACb,QAAQ,CAA6B;IACrC,QAAQ,CAAa;IAE7B,YAAY,MAAwB;QAClC,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;QAChC,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,WAAW,EAAE,MAAM;YACxC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC;YAC7B,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,OAAwB;QACrC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAE7B,qCAAqC;QACrC,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;QAC7E,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,OAAO;gBACL,IAAI,EAAE,kBAAkB,CACtB,OAAO,CAAC,OAAO,EACf,OAAO,CAAC,MAAM,EACd,OAAO,CAAC,SAAS,EACjB,SAAS,EACT,OAAO,CAAC,MAAM,EACd,OAAO,CAAC,SAAS,CAClB;gBACD,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE;oBACL,IAAI,EAAE,qBAAqB;oBAC3B,OAAO,EAAE,sBAAsB,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,SAAS,EAAE;iBACxF;aACF,CAAC;QACJ,CAAC;QAED,8BAA8B;QAC9B,MAAM,OAAO,GAAG,sBAAsB,CAAC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QACrE,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,OAAO;gBACL,IAAI,EAAE,kBAAkB,CACtB,OAAO,CAAC,OAAO,EACf,QAAQ,CAAC,MAAM,EACf,QAAQ,CAAC,SAAS,EAClB,SAAS,EACT,OAAO,CAAC,MAAM,EACd,OAAO,CAAC,SAAS,CAClB;gBACD,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE;oBACL,IAAI,EAAE,kBAAkB;oBACxB,OAAO,EAAE,gCAAgC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;oBAC7D,OAAO,EAAE,EAAE,OAAO,EAAE;iBACrB;aACF,CAAC;QACJ,CAAC;QAED,4BAA4B;QAC5B,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACnD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO;gBACL,IAAI,EAAE,kBAAkB,CACtB,OAAO,CAAC,OAAO,EACf,QAAQ,CAAC,MAAM,EACf,QAAQ,CAAC,SAAS,EAClB,SAAS,EACT,OAAO,CAAC,MAAM,EACd,OAAO,CAAC,SAAS,CAClB;gBACD,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE;oBACL,IAAI,EAAE,cAAc;oBACpB,OAAO,EAAE,0BAA0B,QAAQ,CAAC,MAAM,EAAE;iBACrD;aACF,CAAC;QACJ,CAAC;QAED,mDAAmD;QACnD,MAAM,QAAQ,GAAG,KAAK,IAA+B,EAAE;YACrD,IAAI,OAAO,CAAC,OAAO,KAAK,OAAO,EAAE,CAAC;gBAChC,OAAO,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;YAC3D,CAAC;iBAAM,CAAC;gBACN,OAAO,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;YAC5D,CAAC;QACH,CAAC,CAAC;QAEF,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAExD,uCAAuC;QACvC,QAAQ,CAAC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;QACnD,QAAQ,CAAC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QAC5C,QAAQ,CAAC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAEtC,oCAAoC;QACpC,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;YACtB,QAAQ,CAAC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;QAC9C,CAAC;QAED,iDAAiD;QACjD,EAAE;QACF,2EAA2E;QAC3E,mCAAmC;QACnC,+BAA+B;QAC/B,kEAAkE;QAClE,uEAAuE;QACvE,kEAAkE;QAClE,EAAE;QACF,uEAAuE;QACvE,yEAAyE;QACzE,kEAAkE;QAClE,IACE,QAAQ,CAAC,OAAO;YAChB,OAAO,CAAC,OAAO,KAAK,QAAQ;YAC5B,OAAO,CAAC,SAAS;YACjB,sBAAsB,CAAC,OAAO,CAAC,SAAS,CAAC,EACzC,CAAC;YACD,MAAM,eAAe,GAAG,OAAO,CAAC;YAChC,MAAM,iBAAiB,GAAG,OAAO,CAAC,SAAS,CAAC;YAE5C,YAAY,CAAC,GAAG,EAAE;gBAChB,qEAAqE;gBACrE,4DAA4D;gBAC5D,OAAO,CAAC,GAAG,CAAC;oBACV,MAAM,CAAC,8CAA8C,CAAC;oBACtD,MAAM,CAAC,sCAAsC,CAAC;oBAC9C,MAAM,CAAC,uCAAuC,CAAC;iBAChD,CAAC;qBACC,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,iBAAiB,EAAE,aAAa,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,EAAE;oBACrF,MAAM,WAAW,GAAG,cAAc,EAAE,CAAC;oBACrC,MAAM,IAAI,GAAG;wBACX,WAAW,EAAE,QAAQ,eAAe,CAAC,MAAM,IAAI,eAAe,CAAC,SAAS,IAAI,IAAI,CAAC,SAAS,CAAC,eAAe,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE;wBAC1H,cAAc,EAAE,kCAAkC,eAAe,CAAC,MAAM,IAAI;wBAC5E,YAAY,EAAG,eAAe,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAwB,IAAI,QAAQ;wBACpF,SAAS,EAAE,iBAAiB;qBAC7B,CAAC;oBAEF,MAAM,QAAQ,GAAG,MAAM,iBAAiB,CAAC,IAAI,CAAC,CAAC;oBAC/C,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC;oBAC3E,MAAM,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE;wBAC9C,SAAS,EAAE,iBAAiB;wBAC5B,YAAY,EAAE,IAAI,CAAC,YAAY;wBAC/B,WAAW;qBACZ,CAAC,CAAC;gBACL,CAAC,CAAC;qBACD,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;oBACtB,MAAM,GAAG,GAAG,SAAS,CAAC,gBAAgB,CAAC,CAAC;oBACxC,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,EAAE,4BAA4B,CAAC,CAAC;gBAClD,CAAC,CAAC,CAAC;YACP,CAAC,CAAC,CAAC;QACL,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF"}

package/dist/dispatch/domains/_base.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Shared base helpers for domain handlers.
+ * DRY utility -- extracts the 4 common patterns found in all domain handlers.
+ *
+ * All functions are standalone (not a class) to match the function-based helper style.
+ * Handlers call these instead of re-implementing wrapEngineResult, errorResponse, etc.
+ *
+ * @epic T5671
+ * @task T1427 — typed param narrowing helpers (Wave D · T962)
+ */
+import type { ProblemDetails } from '@cleocode/core';
+import type { DispatchResponse } from '../types.js';
+/**
+ * Engine result shape accepted by wrapResult.
+ * Matches the union of what all engine functions return.
+ */
+export interface EngineResult {
+    success: boolean;
+    data?: unknown;
+    page?: import('@cleocode/lafs').LAFSPage;
+    error?: {
+        code: string;
+        message: string;
+        details?: unknown;
+        exitCode?: number;
+        fix?: string;
+        alternatives?: Array<{
+            action: string;
+            command: string;
+        }>;
+        problemDetails?: ProblemDetails;
+    };
+}
+/**
+ * Wrap a native engine result into a DispatchResponse.
+ * Handles success data, page metadata, and structured errors.
+ */
+export declare function wrapResult(result: EngineResult, gateway: string, domain: string, operation: string, startTime: number): DispatchResponse;
+/**
+ * Return a standard error response.
+ */
+export declare function errorResult(gateway: string, domain: string, operation: string, code: string, message: string, startTime: number): DispatchResponse;
+/**
+ * Return a standard "unsupported operation" error response.
+ */
+export declare function unsupportedOp(gateway: string, domain: string, operation: string, startTime: number): DispatchResponse;
+/**
+ * Extract limit and offset pagination params from a params dict.
+ */
+export declare function getListParams(params?: Record<string, unknown>): {
+    limit?: number;
+    offset?: number;
+};
+/**
+ * Extract a string param from a raw `Record<string, unknown>` params dict.
+ *
+ * @param params - Raw params object (may be undefined).
+ * @param key    - Param key to extract.
+ * @returns The string value, or `undefined` when absent or not a string.
+ */
+export declare function paramString(params: Record<string, unknown> | undefined, key: string): string | undefined;
+/**
+ * Extract a required string param. Returns an empty string when missing so the
+ * caller's `if (!value)` guard still fires naturally.
+ *
+ * @param params - Raw params object (may be undefined).
+ * @param key    - Param key to extract.
+ * @returns The string value, or `''` when absent or not a string.
+ */
+export declare function paramStringRequired(params: Record<string, unknown> | undefined, key: string): string;
+/**
+ * Extract a number param from a raw `Record<string, unknown>` params dict.
+ *
+ * @param params - Raw params object (may be undefined).
+ * @param key    - Param key to extract.
+ * @returns The number value, or `undefined` when absent or not a number.
+ */
+export declare function paramNumber(params: Record<string, unknown> | undefined, key: string): number | undefined;
+/**
+ * Extract a boolean param from a raw `Record<string, unknown>` params dict.
+ *
+ * @param params - Raw params object (may be undefined).
+ * @param key    - Param key to extract.
+ * @returns The boolean value, or `undefined` when absent or not a boolean.
+ */
+export declare function paramBool(params: Record<string, unknown> | undefined, key: string): boolean | undefined;
+/**
+ * Extract a string-array param from a raw `Record<string, unknown>` params dict.
+ *
+ * @param params - Raw params object (may be undefined).
+ * @param key    - Param key to extract.
+ * @returns The string array, or `undefined` when absent or not an array.
+ *
+ * @remarks
+ * Items are assumed to be strings; non-string array elements are filtered out.
+ */
+export declare function paramStringArray(params: Record<string, unknown> | undefined, key: string): string[] | undefined;
+/**
+ * Handle a caught error: extract message and return an internal error response.
+ * Callers should log the error themselves (with their domain-specific logger)
+ * before or after calling this.
+ */
+export declare function handleErrorResult(gateway: string, domain: string, operation: string, error: unknown, startTime: number): DispatchResponse;
+//# sourceMappingURL=_base.d.ts.map

package/dist/dispatch/domains/_base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_base.d.ts","sourceRoot":"","sources":["../../../src/dispatch/domains/_base.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGpD;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,gBAAgB,EAAE,QAAQ,CAAC;IACzC,KAAK,CAAC,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,YAAY,CAAC,EAAE,KAAK,CAAC;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAC1D,cAAc,CAAC,EAAE,cAAc,CAAC;KACjC,CAAC;CACH;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,gBAAgB,CAoBlB;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,gBAAgB,CAMlB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,gBAAgB,CAMlB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAKA;AAWD;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC3C,GAAG,EAAE,MAAM,GACV,MAAM,GAAG,SAAS,CAGpB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC3C,GAAG,EAAE,MAAM,GACV,MAAM,CAGR;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC3C,GAAG,EAAE,MAAM,GACV,MAAM,GAAG,SAAS,CAGpB;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC3C,GAAG,EAAE,MAAM,GACV,OAAO,GAAG,SAAS,CAGrB;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC3C,GAAG,EAAE,MAAM,GACV,MAAM,EAAE,GAAG,SAAS,CAItB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,GAChB,gBAAgB,CAOlB"}