dsh-auto-review 0.4.0

package/lib/types/projection.js

@@ -0,0 +1,197 @@
+/**
+ * Host projection unit for the `autoReview` panel value: folds the log-only
+ * `autoReview/*` events into one wire-JSON whole value the browser review
+ * panel reads via `useProjection('autoReview')`. Pure mathematics only — the
+ * framework owns subscriptions, watermarks, change feeds, and persistence.
+ * The fold mirrors the `events.ts` pure folds (budgets, statistics, denials).
+ * @module dsh-auto-review/projection
+ */
+import { z } from 'zod';
+/** How many verdict rows the panel carries. */
+const RECENT_CAP = 8;
+/** How many approve candidates the panel offers. */
+const DENIES_CAP = 5;
+const VERDICT_VIEW_SCHEMA = z.object({
+    reviewId: z.string(),
+    toolName: z.string(),
+    at: z.number(),
+    durationMs: z.number().int().nonnegative(),
+    decision: z.union([z.literal('allow'), z.literal('deny')]).optional(),
+    riskLevel: z.union([z.literal('low'), z.literal('medium'), z.literal('high')]).optional(),
+    escalation: z.literal('risk-policy').optional(),
+    fallback: z.string().optional(),
+    outcome: z.union([z.literal('allowed-once'), z.literal('rejected'), z.literal('cancelled'), z.literal('unavailable')]).optional(),
+    reason: z.string().optional(),
+});
+const DENY_VIEW_SCHEMA = z.object({
+    reviewId: z.string(),
+    toolName: z.string(),
+    reason: z.string().optional(),
+});
+const CIRCUIT_VIEW_SCHEMA = z.object({
+    action: z.union([z.literal('delegate'), z.literal('reject'), z.literal('abort-turn')]),
+    trip: z.object({
+        kind: z.union([z.literal('consecutive'), z.literal('window')]),
+        count: z.number().int().positive(),
+    }),
+    toolName: z.string(),
+}).nullable();
+/** Strict wire schema — validates the `view` output before it leaves the host. */
+export const AUTO_REVIEW_PROJECTION_SCHEMA = z.object({
+    enabled: z.boolean(),
+    verdictsUsed: z.number().int().nonnegative(),
+    failuresUsed: z.number().int().nonnegative(),
+    allows: z.number().int().nonnegative(),
+    denies: z.number().int().nonnegative(),
+    fallbacks: z.number().int().nonnegative(),
+    neverRejects: z.number().int().nonnegative(),
+    avgDurationMs: z.number().int().nonnegative(),
+    circuit: CIRCUIT_VIEW_SCHEMA,
+    recent: z.array(VERDICT_VIEW_SCHEMA),
+    recentDenies: z.array(DENY_VIEW_SCHEMA),
+});
+/**
+ * State for the empty log. `enabled` starts at the resolved
+ * `enableByDefault` — the projection cannot know the plugin config on its
+ * own, so the unit is built per mount by {@link makeAutoReviewProjection}.
+ * @param enabledByDefault - the resolved `enableByDefault` config value.
+ */
+export function initAutoReviewProjection(enabledByDefault) {
+    return {
+        enabled: enabledByDefault,
+        turnOpen: false,
+        verdictsUsed: 0,
+        failuresUsed: 0,
+        allows: 0,
+        denies: 0,
+        fallbacks: 0,
+        neverRejects: 0,
+        durationSum: 0,
+        decided: 0,
+        circuit: null,
+        recent: [],
+        recentDenies: [],
+    };
+}
+/** One verdict event as its panel row. */
+function verdictView(data, at) {
+    const view = {
+        reviewId: String(data.reviewId),
+        toolName: data.toolName,
+        at,
+        durationMs: data.durationMs,
+    };
+    if (data.decision !== undefined)
+        view.decision = data.decision;
+    if (data.riskLevel !== undefined)
+        view.riskLevel = data.riskLevel;
+    if (data.escalation !== undefined)
+        view.escalation = data.escalation;
+    if (data.fallback !== undefined)
+        view.fallback = data.fallback;
+    if (data.outcome !== undefined)
+        view.outcome = data.outcome;
+    if (data.reason !== undefined)
+        view.reason = data.reason;
+    return view;
+}
+/** One denial event as its approve row. */
+function denyView(data) {
+    const view = {
+        reviewId: String(data.reviewId),
+        toolName: data.toolName,
+    };
+    if (data.reason !== undefined)
+        view.reason = data.reason;
+    return view;
+}
+/**
+ * Pure transition: previous state + one committed event → next state.
+ * Uninterested events return the same state reference.
+ * @param state - the state covering all prior events.
+ * @param event - the next committed session event.
+ * @returns the next state (same reference when the event is not this unit's).
+ */
+export function applyAutoReview(state, event) {
+    switch (event.type) {
+        case 'turn/start':
+            return state.turnOpen
+                ? state
+                : { ...state, turnOpen: true, verdictsUsed: 0, failuresUsed: 0, circuit: null };
+        case 'turn/end':
+            return state.turnOpen ? { ...state, turnOpen: false } : state;
+        case 'autoReview/state':
+            return state.enabled === event.data.enabled ? state : { ...state, enabled: event.data.enabled };
+        case 'autoReview/circuit':
+            return {
+                ...state,
+                circuit: { action: event.data.action, trip: event.data.trip, toolName: event.data.toolName },
+            };
+        case 'autoReview/rejection':
+            return { ...state, neverRejects: state.neverRejects + 1 };
+        case 'autoReview/verdict': {
+            const data = event.data;
+            const decision = data.decision !== undefined;
+            const failure = data.fallback !== undefined && data.fallback !== 'cancelled';
+            const denial = data.decision === 'deny' || data.escalation === 'risk-policy';
+            const row = verdictView(data, event.time);
+            return {
+                ...state,
+                verdictsUsed: state.turnOpen && decision ? state.verdictsUsed + 1 : state.verdictsUsed,
+                failuresUsed: state.turnOpen && failure ? state.failuresUsed + 1 : state.failuresUsed,
+                allows: state.allows + (data.decision === 'allow' ? 1 : 0),
+                denies: state.denies + (data.decision === 'deny' ? 1 : 0),
+                fallbacks: state.fallbacks + (decision ? 0 : 1),
+                durationSum: state.durationSum + (decision ? data.durationMs : 0),
+                decided: state.decided + (decision ? 1 : 0),
+                recent: [row, ...state.recent].slice(0, RECENT_CAP),
+                recentDenies: denial
+                    ? [denyView(data), ...state.recentDenies].slice(0, DENIES_CAP)
+                    : state.recentDenies,
+            };
+        }
+        default:
+            return state;
+    }
+}
+/** State → wire payload (the read-side projection). */
+export function viewAutoReview(state) {
+    return {
+        enabled: state.enabled,
+        verdictsUsed: state.verdictsUsed,
+        failuresUsed: state.failuresUsed,
+        allows: state.allows,
+        denies: state.denies,
+        fallbacks: state.fallbacks,
+        neverRejects: state.neverRejects,
+        avgDurationMs: state.decided === 0 ? 0 : Math.round(state.durationSum / state.decided),
+        circuit: state.circuit,
+        recent: state.recent,
+        recentDenies: state.recentDenies,
+    };
+}
+/**
+ * Build the registered unit for one mount. The unit's initial `enabled` is
+ * the mount's resolved `enableByDefault` (the pure `init` cannot see plugin
+ * config otherwise), and the panel therefore reports the same switch state
+ * the answerer applies. Registrants sharing the `autoReview` key share one
+ * unit; the first mount's default wins, which only matters for a double
+ * mount with conflicting `enableByDefault` values.
+ * @param enabledByDefault - the resolved `enableByDefault` config value.
+ * @returns the projection unit for `ctx.sessionProjections.register`.
+ */
+export function makeAutoReviewProjection(enabledByDefault) {
+    return {
+        key: 'autoReview',
+        // zod v4's `.optional()` output carries `| undefined`, which exact-optional
+        // property types reject; the runtime validation is what matters on the wire.
+        schema: AUTO_REVIEW_PROJECTION_SCHEMA,
+        init: () => initAutoReviewProjection(enabledByDefault),
+        apply: applyAutoReview,
+        view: viewAutoReview,
+        // v2: `init.enabled` follows `enableByDefault` (was hardcoded true) and the
+        // wire gained the cumulative `neverRejects` counter.
+        stateVersion: 2,
+    };
+}
+//# sourceMappingURL=projection.js.map

package/lib/types/projection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection.js","sourceRoot":"","sources":["../../src/projection.ts"],"names":[],"mappings":"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"}

package/lib/types/review.d.ts

@@ -0,0 +1,141 @@
+/**
+ * The reviewer subagent: one-shot in-process child with a read-only tool
+ * allow-list and a structured verdict schema, raced against the configured
+ * timeout and the request's cancellation signal. Any failure resolves to a
+ * {@link ReviewFailure} — the caller applies the fallback policy, never a
+ * grant (fail closed by default).
+ * @module dsh-auto-review/review
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { CallId } from '@deepseek-ai/dsh-llm';
+import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session';
+import type { ApprovalRequest } from '@deepseek-ai/dsh-user-approval';
+import { type ObjectJsonSchema } from '@deepseek-ai/dsh-tools';
+import type { AutoReviewFallback } from './events.ts';
+import { AutoReviewCircuitId, AutoReviewRejectionId, AutoReviewVerdictId } from './events.ts';
+import type { ContextBudgetConfig, ResolvedConfig, RiskLevel } from './config.ts';
+/** A reviewer verdict, validated against the closed decision vocabulary. */
+export interface ReviewerVerdict {
+    readonly decision: 'allow' | 'deny';
+    readonly reason: string;
+    readonly riskLevel?: RiskLevel;
+    /** The reviewer child's session id (its own log is auditable). */
+    readonly reviewerSessionId?: SessionId;
+    /** The explicitly configured reviewer model, when one was set. */
+    readonly model?: string;
+}
+/**
+ * A review that produced no verdict. The caller maps the failure to the
+ * configured fallback policy.
+ */
+export interface ReviewFailure {
+    readonly fallback: AutoReviewFallback;
+    readonly error: string;
+    readonly reviewerSessionId?: SessionId;
+    readonly model?: string;
+}
+/** The closed result of one review attempt. */
+export type ReviewResolution = ReviewerVerdict | ReviewFailure;
+/** Distinguish a verdict resolution from a failure. */
+export declare function isReviewFailure(resolution: ReviewResolution): resolution is ReviewFailure;
+/** Object-rooted verdict schema enforced on the child's structured_output capture. */
+export declare const VERDICT_SCHEMA: ObjectJsonSchema;
+/**
+ * Recursively redact sensitive values from a JSON value: any object key
+ * matching {@link SENSITIVE_KEY_PATTERN} has its value replaced.
+ * @param value - the detached JSON value to sanitize.
+ * @returns a detached copy with sensitive values redacted.
+ */
+export declare function sanitizeArguments(value: unknown): unknown;
+/**
+ * The already-presented call arguments, parsed and key-redacted, as pretty
+ * JSON — the raw material for both the reviewer prompt section and the
+ * `arguments` risk-rule field.
+ * @param events - the requesting session's log.
+ * @param callId - the call to render.
+ * @returns the sanitized JSON text, or undefined when the log lacks a parseable call.
+ */
+export declare function sanitizedArgumentsText(events: readonly SessionEvent[], callId: CallId): string | undefined;
+/**
+ * Render the tool-call context for the reviewer: the already-streamed call
+ * arguments (parsed, redacted, truncated) or a note when the log lacks them.
+ * @param events - the requesting session's log.
+ * @param callId - the call to render.
+ * @param maxChars - the preview cap (shared with reason truncation).
+ * @returns the prompt section text.
+ */
+export declare function renderCallContext(events: readonly SessionEvent[], callId: CallId | undefined, maxChars: number): string;
+/**
+ * Build the compact-transcript section for the reviewer: the tail of the
+ * session's user/assistant messages and tool calls/results, most recent
+ * last, bounded by {@link ContextBudgetConfig}. `turns: 0` yields an empty
+ * section. Tool-call arguments and tool-result text enter verbatim (they are
+ * already-presented transcript content); the presented call of the pending
+ * request is redacted separately in {@link renderCallContext}.
+ * @param events - the requesting session's log.
+ * @param budget - how much context to include.
+ * @returns the prompt section text (empty when disabled).
+ */
+export declare function buildContextSection(events: readonly SessionEvent[], budget: ContextBudgetConfig): string;
+/** Context of a pending human override, passed into the reviewer prompt. */
+export interface OverrideContext {
+    readonly reviewId: AutoReviewVerdictId;
+    readonly toolName: string;
+}
+/**
+ * Truncate a string to a character budget without cutting surrogate pairs.
+ * @param text - the string to cap.
+ * @param maxChars - the positive budget.
+ * @returns the capped string.
+ */
+export declare function truncate(text: string, maxChars: number): string;
+/**
+ * Build the reviewer prompt: role, the pending request's tool/reason/context/
+ * workspace, the resolved risk rules, the ruling policy text, the optional
+ * human-override context, and the verdict contract.
+ * @param request - the pending approval request.
+ * @param config - resolved config (rules, guidance, budgets).
+ * @param override - a pending human one-shot override, when one applies.
+ * @returns the exact prompt text block.
+ */
+export declare function buildReviewPrompt(request: ApprovalRequest, config: ResolvedConfig, override?: OverrideContext): string;
+/**
+ * Validate the provider-validated structured capture against the closed
+ * verdict vocabulary. The subagent seam validates against the schema, but its
+ * result is typed `unknown`; this is the boundary that narrows it.
+ * @param value - the captured structured value.
+ * @param reasonMaxChars - the reason cap.
+ * @returns the verdict, or undefined when the value cannot be a verdict.
+ */
+export declare function parseVerdict(value: unknown, reasonMaxChars: number): ReviewerVerdict | undefined;
+/**
+ * Run one review attempt: start a one-shot reviewer child on the configured
+ * provider, await its structured verdict, and race both the configured
+ * timeout and the request signal. Every failure path resolves to a
+ * {@link ReviewFailure} — never to a grant.
+ * @param ctx - the plugin context (`ctx.subagents` and the request's parent agent).
+ * @param config - resolved config (provider, timeout, tools, model, budgets).
+ * @param request - the pending approval request (parent, signal, and evidence).
+ * @param reviewerSessions - the runtime's live reviewer session ids, so the
+ *   answerer can refuse the child's own approval asks while the review runs.
+ * @param override - a pending human one-shot override, when one applies.
+ * @returns the verdict or the failure.
+ */
+export declare function runReview(ctx: Context, config: ResolvedConfig, request: ApprovalRequest, reviewerSessions: Set<SessionId>, override?: OverrideContext): Promise<ReviewResolution>;
+/**
+ * Mint one verdict id. Wrapped for testability (audit uniqueness is a UUID).
+ * @returns a fresh branded id.
+ */
+export declare function newVerdictId(): AutoReviewVerdictId;
+/**
+ * Mint one circuit-trip id. Wrapped for testability (audit uniqueness is a UUID).
+ * @returns a fresh branded id.
+ */
+export declare function newCircuitId(): AutoReviewCircuitId;
+/**
+ * Mint one hard-disable rejection id. Wrapped for testability (audit
+ * uniqueness is a UUID).
+ * @returns a fresh branded id.
+ */
+export declare function newRejectionId(): AutoReviewRejectionId;
+//# sourceMappingURL=review.d.ts.map

package/lib/types/review.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review.d.ts","sourceRoot":"","sources":["../../src/review.ts"],"names":[],"mappings":"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"}