agent-nuvira 3.3.1 → 3.3.4

package/dist/parity/drivers.d.ts

@@ -0,0 +1,99 @@
+/**
+ * WS0 (#22) — the drivers that actually run a turn on each surface.
+ *
+ * WHY THESE LIVE IN `src/` NOW. They used to live in `tests/parity/drivers.ts`
+ * and reached the stub through `vi.spyOn` on the real engine — which made the
+ * harness unrunnable outside the test runner, and left "prove every surface at
+ * par" as something only CI could do. The requirement is a `nuvira parity`
+ * command, so the drivers had to become a thing production code can call.
+ *
+ * The seam is CONFIGURATION, not a mock. Every surface resolves its provider
+ * through the SAME shared `resolveProvider` (`src/cli/router.ts`), so a temp
+ * `buffconfig.json` naming `groq` with `providers.groq.baseUrl` pointed at a
+ * loopback OpenAI-compatible stub makes the whole stack run for real: the real
+ * ChatCommand, the real console, the real gateway registry, the real execute
+ * command and the real forked child, each with a REAL provider object (the Groq
+ * adapter). Only the server on the other end of the socket is a stub — the
+ * definition of `transport` depth in `./scenarios.ts`, and the same depth the
+ * forked child was already driven at.
+ *
+ * NO TEST SEAM WAS ADDED TO PRODUCTION CODE. The surfaces already accept what is
+ * needed: `answerOnce`/`ChatConsole.answer` take `provider`/`model`, the gateway
+ * derives the pair from its own config (`registry.ts:1797`), and the child reads
+ * its own `buffconfig.json`. Nothing in `chat.ts`, `chat-console.ts`,
+ * `gateway/registry.ts`, `execute.ts` or the spawner changed to make this work.
+ *
+ * ISOLATION IS THE POINT, AND IT IS PROCESS-LOCAL. A run points
+ * `NUVIRA_CONFIG_DIR` and `NUVIRA_MEMORY_DIR` at a throwaway directory for its
+ * whole life, so the stub never touches the developer's real profile — no real
+ * API key, no real response cache, no real model registry, no real gateway log.
+ * That is the same convention `src/config/paths.ts` documents and the same one
+ * the test drivers relied on. It cannot leak into a separately-running dashboard
+ * or gateway: a `nuvira parity` invocation is its own process.
+ *
+ * EVERY SURFACE'S OBSERVATION IS READ FROM THAT SURFACE'S OWN REPORT — the
+ * engine's return for the CLI, the console's result for the dashboard, the
+ * gateway's `inbound.chat` log record for the gateway, the command's result for
+ * execute, the child's own progress frames for the subagent. Nothing is
+ * reconstructed here, so a surface that stops reporting its status, attribution
+ * or tool calls goes red instead of quietly losing the fact.
+ */
+import type { ParityDriver, StubDepth } from './scenarios.js';
+import type { SurfaceId } from './surfaces.js';
+/**
+ * Where every driver stubs. Transport depth is not a compromise here — it is
+ * what makes the comparison honest: the provider OBJECT is the real adapter and
+ * the turn code above it is untouched. The runner folds `provider` and
+ * `transport` into one comparable class (`./scenarios.ts`, rule 1), so these
+ * observations compare with anything else that runs the real turn code.
+ */
+export declare const DRIVER_DEPTH: StubDepth;
+/** The provider id every surface is configured with, so the comparison is at-par. */
+export declare const PARITY_PROVIDER_TYPE = "groq";
+/** The one model the stub serves. The surfaces are pinned to it, so all five agree. */
+export declare const PARITY_MODEL = "parity-stub-model";
+/**
+ * The surfaces this module can drive. Declared as data so a caller can assert
+ * the driver list covers the registry without paying for a live harness — a
+ * surface missing here would otherwise be counted as neither covered nor
+ * blocked, the silent hole this harness exists to prevent.
+ */
+export declare const PARITY_DRIVER_SURFACES: readonly SurfaceId[];
+/** Where a declared hook appends the invocations it received (harness-owned). */
+export declare const TOOL_HOOK_LOG_VAR = "NUVIRA_TOOL_HOOK_LOG";
+/** Which tools a declared `before` hook vetoes (harness-owned). */
+export declare const TOOL_HOOK_DENY_VAR = "NUVIRA_TOOL_HOOK_DENY";
+/**
+ * A driver that exists only to record why it cannot run. Exported so a caller
+ * can pin the guard that a blocked surface is never silently invoked — the real
+ * driver list currently needs no blocks.
+ */
+export declare function blockedDriver(surface: SurfaceId, reason: string): ParityDriver;
+/** A live set of drivers plus the throwaway profile they run against. */
+export interface ParityHarness {
+    /** Every surface, in the order a parity report reads them. */
+    drivers: ParityDriver[];
+    /**
+     * The four surfaces that run in THIS process. A cross-surface verdict is read
+     * from this group: the forked child legitimately reports a different transport
+     * for a turn that asked for no tools (it has no tools installed in that case),
+     * which is a fact about the child, not a divergence — so the child is compared
+     * in the scenarios where that fact matches, exactly as the registry declares.
+     */
+    inProcess: ParityDriver[];
+    /** The forked-child driver on its own. */
+    subagent: ParityDriver[];
+    /** Restore the environment and delete the throwaway profile. */
+    dispose(): Promise<void>;
+}
+/**
+ * Build the real drivers.
+ *
+ * The environment is switched to a throwaway profile here and restored in
+ * `dispose()`. Every module that resolves `NUVIRA_CONFIG_DIR` / `NUVIRA_MEMORY_DIR`
+ * at call time (the config manager, the cache, the gateway log) therefore reads
+ * the isolated profile for the whole run, and the developer's real profile is
+ * untouched — the same hermetic convention the test suite uses.
+ */
+export declare function createParityHarness(): Promise<ParityHarness>;
+//# sourceMappingURL=drivers.d.ts.map

package/dist/parity/drivers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drivers.d.ts","sourceRoot":"","sources":["../../src/parity/drivers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAsDH,OAAO,KAAK,EAAE,YAAY,EAAkB,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC9E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE/C;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,EAAE,SAAuB,CAAC;AAEnD,qFAAqF;AACrF,eAAO,MAAM,oBAAoB,SAAS,CAAC;AAE3C,uFAAuF;AACvF,eAAO,MAAM,YAAY,sBAAsB,CAAC;AAKhD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,SAAS,EAMtD,CAAC;AA0UF,iFAAiF;AACjF,eAAO,MAAM,iBAAiB,yBAAyB,CAAC;AACxD,mEAAmE;AACnE,eAAO,MAAM,kBAAkB,0BAA0B,CAAC;AA6+B1D;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,YAAY,CAY9E;AAED,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB;;;;;;OAMG;IACH,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,0CAA0C;IAC1C,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,gEAAgE;IAChE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,aAAa,CAAC,CA8GlE"}