dsh-decision-layer 0.7.1 → 0.7.3

package/lib/host/types.d.ts

@@ -0,0 +1,365 @@
+/**
+ * Shared types and guards for the host half.
+ *
+ * Three kinds of shape appear here, and they are deliberately kept apart:
+ *  - wire contracts (EvaluateInput / EvaluateResult) — the one protocol with the
+ *    adjudication backend, validated in backend.ts;
+ *  - configuration (ResolvedConfig / *Settings) — validated in config-store.ts;
+ *  - host runtime surfaces (HostContext, ToolExec, AgentLike) — our own
+ *    structural view of what the Cordis host hands us. They are declared here
+ *    instead of imported from @deepseek-ai/* so a host minor upgrade cannot
+ *    break compilation: every field is optional and every boundary re-validates.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export type JsonObject = Record<string, unknown>;
+export declare const isObject: (value: unknown) => value is JsonObject;
+export declare const isProbability: (value: unknown) => value is number;
+/** The stable reason code a backend failure carries, or a generic fallback. */
+export declare const errorReason: (error: unknown, fallback?: string) => string;
+export type ChoiceQuestion = {
+    type: 'choice';
+    instructions: unknown;
+    criteria: Record<string, unknown>;
+};
+export type ScoreQuestion = {
+    type: 'score';
+    instructions: unknown;
+    criteria: readonly unknown[];
+};
+export type NoulQuestion = {
+    type: 'noul';
+    instructions: unknown;
+    criteria?: unknown;
+};
+export type Question = ChoiceQuestion | ScoreQuestion | NoulQuestion;
+export type QuestionMap = Record<string, Question>;
+export type EvaluateInput = {
+    state: unknown;
+    questions: QuestionMap;
+};
+export type NoulAnswer = {
+    type: 'noul';
+    noul: number;
+};
+export type ScoredAnswer = {
+    confidence: number;
+    probabilities: Record<string, number>;
+};
+export type ScoreAnswer = ScoredAnswer & {
+    type: 'score';
+    score: number;
+};
+export type ChoiceAnswer = ScoredAnswer & {
+    type: 'choice';
+    choice: string;
+};
+export type Answer = NoulAnswer | ScoreAnswer | ChoiceAnswer;
+export type AnswerMap = Record<string, Answer>;
+export type EvaluateResult = {
+    model: string;
+    answers: AnswerMap;
+    usage?: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+};
+export type Evaluator = (input: EvaluateInput, options?: {
+    signal?: AbortSignal;
+}) => Promise<EvaluateResult>;
+export type CheckMode = 'observe' | 'steer';
+export type NarrowMode = 'observe' | 'enforce';
+export type BatchMode = 'auto' | 'single' | 'split';
+export type FeatureKey = 'gate' | 'check' | 'narrow' | 'complete';
+export type Severity = 'normal' | 'warn' | 'severe';
+export type DangerRuleAdditions = {
+    addToolNames?: string[];
+    removeToolNames?: string[];
+    addCommandPatterns?: string[];
+    addPathPatterns?: string[];
+};
+/** Compiled rules: the built-in patterns plus the configured additions. */
+export type DangerRuleSet = {
+    toolNames: readonly string[];
+    commandPatterns: readonly RegExp[];
+    pathPatterns: readonly RegExp[];
+};
+export type GateSettings = {
+    minConfidence?: number;
+};
+export type CheckSettings = {
+    mode?: CheckMode;
+    rubric?: string[];
+    lowScoreThreshold?: number;
+    minConfidence?: number;
+    trendMinConfidence?: number;
+    trendRun?: number;
+    trendSevereRun?: number;
+};
+export type NarrowSettings = {
+    mode?: NarrowMode;
+    threshold?: number;
+    keepPrefixes?: string[];
+    maxCandidates?: number;
+    batchMode?: BatchMode;
+};
+export type CompleteSettings = {
+    mode?: CheckMode;
+    minConditions?: number;
+    minConfidence?: number;
+};
+export type Features = Partial<Record<FeatureKey, boolean>>;
+/** What the backend needs from the config to make one request. */
+export type BackendConfig = {
+    url: string;
+    apiKey: string;
+    model: string;
+    httpApprovedUrl: string;
+};
+/** Fully resolved configuration; every field the decision points read. */
+export type ResolvedConfig = {
+    url: string;
+    apiKey: string;
+    model: string;
+    httpApprovedUrl: string;
+    dangerRules?: DangerRuleAdditions;
+    gateSettings?: GateSettings;
+    checkSettings?: CheckSettings;
+    narrowSettings?: NarrowSettings;
+    completeSettings?: CompleteSettings;
+    features?: Features;
+};
+/** What the config page may read back: the API key is reduced to a flag. */
+export type ConfigView = {
+    url: string;
+    model: string;
+    apiKeySet: boolean;
+    httpApprovedUrl: string;
+    dangerRules?: DangerRuleAdditions;
+    gateSettings?: GateSettings;
+    checkSettings?: CheckSettings;
+    narrowSettings?: NarrowSettings;
+    completeSettings?: CompleteSettings;
+    features?: Features;
+};
+/** The quality-trend knobs, shared by the live path and the log backtest. */
+export type TrendConfig = {
+    trendMinConfidence?: number;
+    trendRun?: number;
+    trendSevereRun?: number;
+    lowScoreThreshold?: number;
+};
+export type LogKind = 'gate' | 'check' | 'narrow' | 'complete';
+/**
+ * One decision-log row. Fields are optional because rows are also read back
+ * from disk: persisted snapshots are untrusted input, and only `kind` is
+ * enforced before a row is accepted.
+ */
+export type LogRow = {
+    id?: string;
+    at?: number;
+    kind: LogKind;
+    outcome?: string;
+    tool?: string;
+    suggestion?: string;
+    action?: string;
+    reason?: string;
+    subject?: string;
+    task?: string;
+    turn?: number;
+    step?: number;
+    command?: string;
+    path?: string;
+    mode?: string;
+    score?: number;
+    confidence?: number;
+    dropped?: number;
+    kept?: number;
+    applied?: boolean;
+    candidates?: number;
+    conditions?: number;
+    satisfied?: number;
+    unsatisfied?: number;
+    insufficient?: number;
+    steered?: boolean;
+    lowConfidence?: boolean;
+    tools?: string[];
+};
+/** The research-log sink record: the panel row plus its session tag. */
+export type SessionSinkRow = LogRow & {
+    sessionId: string;
+};
+export type SessionCounters = {
+    attempts: number;
+    failures: number;
+};
+export type GateCounters = SessionCounters & {
+    ask: number;
+    deny: number;
+    allow: number;
+    actual: {
+        allow: number;
+        deny: number;
+        error: number;
+    };
+};
+export type CheckCounters = SessionCounters & {
+    low: number;
+    run: number;
+    severity: Severity;
+};
+export type NarrowCounters = SessionCounters & {
+    applied: number;
+    dropped: number;
+};
+export type CompleteCounters = SessionCounters & {
+    unsatisfied: number;
+    satisfied: number;
+    insufficient: number;
+    steered: number;
+};
+/** Live per-session state (the durable snapshot's payload). */
+export type SessionState = {
+    enabled: boolean;
+    attempts: number;
+    failures: number;
+    gate: GateCounters;
+    check: CheckCounters;
+    narrow: NarrowCounters;
+    complete: CompleteCounters;
+    log: LogRow[];
+};
+/** The panel-facing projection; sections without attempts are omitted. */
+export type SessionSnapshot = {
+    enabled: boolean;
+    hasAutomaticDecisions: boolean;
+    attempts: number;
+    failures: number;
+    gate?: GateCounters;
+    check?: {
+        attempts: number;
+        failures: number;
+        low: number;
+        trend: {
+            run: number;
+            severity: Severity;
+        };
+    };
+    narrow?: NarrowCounters;
+    complete?: CompleteCounters;
+    log?: LogRow[];
+};
+/** The counter shape rebuilt from persisted JSONL, without the master switch. */
+export type SessionSeed = Omit<SessionState, 'enabled'>;
+/**
+ * The slice of the session store the decision points use. Every method is
+ * optional: a test or an older host may inject only the parts it cares about.
+ */
+export type SessionsFace = {
+    snapshot: (id: string) => SessionSnapshot;
+    log?: (id: string, entry: Record<string, unknown>) => void;
+    record?: (id: string, kind: 'gate', outcome: string) => void;
+    recordActual?: (id: string, outcome: 'allow' | 'deny' | 'error') => void;
+    recordCheck?: (id: string, outcome: string, trend?: Record<string, unknown>) => void;
+    recordNarrow?: (id: string, outcome: string, dropped: number, applied: boolean) => void;
+    recordComplete?: (id: string, outcome: string, detail?: Record<string, unknown>) => void;
+    ensureLoaded?: (id: string) => Promise<unknown>;
+    setEnabled?: (id: string, enabled: boolean) => void;
+};
+export type ToolCandidate = {
+    name: string;
+    description?: string;
+};
+/** Bounded, masked data for adjudication; background is never authorization. */
+export type ToolEvidence = {
+    tool: string;
+    outcome: 'ok' | 'error';
+    command?: string;
+    path?: string;
+    result?: string;
+};
+export type DecisionContext = {
+    request: string;
+    background: {
+        role: 'user' | 'assistant';
+        text: string;
+    }[];
+    progress: ToolEvidence[];
+};
+export type DecisionSnapshot = {
+    context: DecisionContext;
+    conditionsText: string;
+    evidence: ToolEvidence[];
+};
+export type AgentLike = {
+    session?: {
+        id?: string;
+        deriveMessages?: () => unknown;
+    };
+    steer?: (message: unknown) => unknown;
+    ctx?: {
+        tools?: {
+            restrict?: (options: {
+                allow: string[];
+            }) => (() => void) | undefined;
+        };
+    };
+};
+export type ToolExec = {
+    name?: string;
+    arguments?: unknown;
+    agent?: AgentLike;
+    signal?: AbortSignal;
+    [key: string]: unknown;
+};
+export type NextStep = () => unknown;
+export type ToolSchema = {
+    name: string;
+    description?: string;
+};
+export type ToolRegistration = {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    output: Record<string, unknown>;
+    timeoutMs?: number;
+    execute: (args: unknown, exec: ToolExec) => unknown;
+};
+export type SkillRegistration = {
+    name: string;
+    description: string;
+    content: string;
+    source: string;
+};
+export type ManagerRoute = {
+    kind: 'exact';
+    path: string;
+    handler: (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+};
+export type WebServerFace = {
+    port: number;
+    host?: string;
+    register: (route: ManagerRoute) => () => void;
+};
+export type WebFace = {
+    webServer: WebServerFace;
+};
+export type ToolsFace = {
+    guard?: (guard: (exec: ToolExec) => string | undefined) => unknown;
+    register: (tool: ToolRegistration) => unknown;
+    schemas?: (agent?: AgentLike) => unknown;
+};
+export type SkillsFace = {
+    register: (skill: SkillRegistration) => unknown;
+};
+/**
+ * The Cordis context our apply() needs. Handlers are typed per call site
+ * because each event carries a different payload; `never[]` here keeps them
+ * assignable without leaking `any` into the implementation.
+ */
+export type HostContext = {
+    on: (event: string, handler: (...args: never[]) => unknown) => (() => void) | undefined;
+    effect?: (install: () => (() => void) | void) => unknown;
+    tools: ToolsFace;
+    skills: SkillsFace;
+    inject: (keys: string[], install: (web: WebFace) => (() => void) | void) => unknown;
+};

package/lib/host/types.js

@@ -0,0 +1,11 @@
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const isProbability = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
+const errorReason = (error, fallback = "unreachable") => {
+  const reason = error?.reason;
+  return typeof reason === "string" ? reason : fallback;
+};
+export {
+  errorReason,
+  isObject,
+  isProbability
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-decision-layer",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "A structured decision layer for the DeepSeek Harness agent loop: a danger-call gate, output self-check, tool narrowing, and loop guard backed by a pluggable adjudication model.",
   "keywords": [
     "dsh",
@@ -14,11 +14,11 @@
   "license": "MIT",
   "type": "module",
   "icon": "./icon.svg",
-  "main": "./service/dsh.mjs",
+  "main": "./lib/host/index.js",
   "files": [
-    "service",
-    "skills",
+    "lib/host",
     "lib/client.js",
+    "skills",
     "locale/*.json",
     "docs/zh/DETAIL.md",
     "docs/en/DETAIL.md",
@@ -36,20 +36,25 @@
     "url": "https://github.com/xbzbing/dsh-decision-layer.git"
   },
   "scripts": {
-    "test": "node --test tests/*.test.mjs",
-    "build:client": "tsc -p tsconfig.client.json && node scripts/build-client.mjs",
-    "check": "npm run build:client && npm test",
+    "build": "node build.mjs",
+    "typecheck": "tsc -p tsconfig.host.json --noEmit && tsc -p tsconfig.client.json",
+    "test": "node build.mjs && node --test tests/*.test.mjs",
+    "check": "npm test && npm run pack:assert",
     "pack:assert": "node scripts/assert-pack.mjs"
   },
   "exports": {
-    ".": "./service/dsh.mjs",
+    ".": {
+      "types": "./lib/host/index.d.ts",
+      "default": "./lib/host/index.js"
+    },
     "./client": "./lib/client.js",
     "./locale/*.json": "./locale/*.json",
     "./package.json": "./package.json"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "~4.0.4",
-    "@deepseek-ai/dsh": ">=0.1.7-rc.2"
+    "@deepseek-ai/dsh": ">=0.1.7-rc.2",
+    "@deepseek-ai/dsh-llm": ">=0.1.7-rc.2"
   },
   "devDependencies": {
     "@deepseek-ai/dsh-client-locale": "0.1.7-rc.2",
@@ -58,6 +63,7 @@
     "@deepseek-ai/dsh-client-ui-renderer": "0.1.7-rc.2",
     "@deepseek-ai/dsh-client-ui-slots": "0.1.7-rc.2",
     "@testing-library/react": "^16.3.3",
+    "@types/node": "^20.19.0",
     "@types/react": "~18.3.1",
     "@types/react-dom": "~18.3.0",
     "esbuild": "^0.25.12",
@@ -80,5 +86,6 @@
       ],
       "platform": "web"
     }
-  }
+  },
+  "types": "./lib/host/index.d.ts"
 }

package/service/backend.mjs

@@ -1,127 +0,0 @@
-import { setTimeout as wait } from 'node:timers/promises';
-import { DEFAULT_MODEL } from './config-store.mjs';
-
-const REQUEST_LIMIT = 256 * 1024;
-const RESPONSE_LIMIT = 1024 * 1024;
-const isObject = value => value !== null && typeof value === 'object' && !Array.isArray(value);
-const isContent = value => typeof value === 'string' ? value.trim().length > 0 : isObject(value) || Array.isArray(value);
-const probability = value => typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1;
-
-// A backend failure carries a stable `reason` code so callers can surface the
-// specific cause (unreachable / http-error / invalid-response / config) instead
-// of a single generic error.
-function backendError(reason, message) {
-  const error = new Error(message);
-  error.reason = reason;
-  return error;
-}
-
-export function validateRequest(input) {
-  if (!isObject(input) || !isContent(input.state) || !isObject(input.questions)) throw new Error('Invalid state or questions');
-  const questions = Object.entries(input.questions);
-  if (questions.length < 1 || questions.length > 64) throw new Error('Invalid question count');
-  for (const [id, question] of questions) {
-    if (!id.trim() || id.length > 160 || !isObject(question) || !isContent(question.instructions)) throw new Error('Invalid question');
-    if (question.type === 'choice') {
-      if (!isObject(question.criteria) || Object.keys(question.criteria).length < 2 || Object.keys(question.criteria).length > 255 ||
-        Object.entries(question.criteria).some(([key, value]) => !key.trim() || (value !== null && !isContent(value)))) throw new Error('Invalid choice criteria');
-    } else if (question.type === 'score') {
-      if (!Array.isArray(question.criteria) || question.criteria.length < 2 || question.criteria.length > 10 || !question.criteria.every(isContent)) throw new Error('Invalid score criteria');
-    } else if (question.type !== 'noul' || (question.criteria !== undefined && (!isObject(question.criteria) || Object.keys(question.criteria).some(key => !['true', 'false'].includes(key))))) {
-      throw new Error('Invalid question type or criteria');
-    }
-  }
-  let encoded;
-  try {
-    encoded = JSON.stringify(input, (key, value) => {
-      if (typeof value === 'function' || typeof value === 'symbol' || typeof value === 'bigint' || (typeof value === 'number' && !Number.isFinite(value))) throw new Error('Invalid JSON');
-      return value;
-    });
-  } catch { throw new Error('Invalid JSON payload'); }
-  if (Buffer.byteLength(encoded) > REQUEST_LIMIT) throw new Error('Request too large');
-  return { state: input.state, questions: input.questions };
-}
-
-function validateAnswer(value, question) {
-  if (!isObject(value) || value.type !== question.type) throw backendError('invalid-response', 'Invalid response answer');
-  if (question.type === 'noul') {
-    if (!probability(value.noul)) throw backendError('invalid-response', 'Invalid response probability');
-    return { type: 'noul', noul: value.noul };
-  }
-  const keys = question.type === 'choice' ? Object.keys(question.criteria) : question.criteria.map((_, i) => String(i));
-  if (!isObject(value.probabilities) || !probability(value.confidence) ||
-    Object.keys(value.probabilities).length !== keys.length || keys.some(key => !probability(value.probabilities[key])) ||
-    Math.abs(keys.reduce((sum, key) => sum + value.probabilities[key], 0) - 1) > 0.02) throw backendError('invalid-response', 'Invalid response probabilities');
-  const common = { type: value.type, confidence: value.confidence, probabilities: Object.fromEntries(keys.map(key => [key, value.probabilities[key]])) };
-  if (question.type === 'choice') {
-    if (typeof value.choice !== 'string' || !keys.includes(value.choice)) throw backendError('invalid-response', 'Invalid response choice');
-    return { ...common, choice: value.choice };
-  }
-  if (typeof value.score !== 'number' || !Number.isFinite(value.score) || value.score < 0 || value.score > keys.length - 1) throw backendError('invalid-response', 'Invalid response score');
-  return { ...common, score: value.score };
-}
-
-function validateResponse(value, questions) {
-  if (!isObject(value) || !isObject(value.answers) || typeof value.model !== 'string') throw backendError('invalid-response', 'Invalid response');
-  const answers = Object.create(null);
-  for (const [id, question] of Object.entries(questions)) answers[id] = validateAnswer(value.answers[id], question);
-  return { model: value.model, answers, usage: isObject(value.usage) ? {
-    input_tokens: Number.isSafeInteger(value.usage.input_tokens) ? value.usage.input_tokens : 0,
-    output_tokens: Number.isSafeInteger(value.usage.output_tokens) ? value.usage.output_tokens : 0,
-  } : undefined };
-}
-
-async function boundedJson(response) {
-  const reader = response.body?.getReader();
-  if (!reader) throw backendError('invalid-response', 'Invalid response body');
-  const chunks = [];
-  let size = 0;
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      size += value.byteLength;
-      if (size > RESPONSE_LIMIT) throw backendError('invalid-response', 'Invalid response size');
-      chunks.push(value);
-    }
-  } finally { await reader.cancel().catch(() => {}); }
-  try { return JSON.parse(Buffer.concat(chunks).toString('utf8')); } catch { throw backendError('invalid-response', 'Invalid response JSON'); }
-}
-
-export function createBackend({ config, fetcher = globalThis.fetch, timeoutMs = 20_000, retryDelayMs = 200 }) {
-  if (typeof config !== 'function' || typeof fetcher !== 'function' ||
-    !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || !Number.isSafeInteger(retryDelayMs) || retryDelayMs < 0 || retryDelayMs > 5000) {
-    throw new Error('Invalid backend dependencies');
-  }
-  return {
-    async evaluate(input, { signal } = {}) {
-      const { state, questions } = validateRequest(input);
-      const settings = await config();
-      const key = settings.apiKey?.trim();
-      if (!key || /[\r\n]/.test(key)) throw backendError('config', 'API key is required');
-      let url;
-      try { url = new URL(settings.url); } catch { throw backendError('config', 'Invalid backend URL'); }
-      if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) throw backendError('config', 'Invalid backend URL');
-      if (url.protocol === 'http:' && settings.httpApprovedUrl !== settings.url) throw backendError('config', 'HTTP URL requires confirmation');
-      const model = settings.model || DEFAULT_MODEL;
-      if (typeof model !== 'string' || !model.trim() || /[\r\n]/.test(model)) throw backendError('config', 'Invalid model');
-      const endpoint = new URL(url.href);
-      endpoint.pathname = `${url.pathname.replace(/\/+$/, '')}/v1/systemone`;
-      if (endpoint.origin !== url.origin) throw backendError('config', 'Invalid backend endpoint');
-      const timeout = AbortSignal.timeout(timeoutMs);
-      const combined = signal ? AbortSignal.any([signal, timeout]) : timeout;
-      for (let attempt = 0; attempt < 3; attempt++) {
-        let reply;
-        try {
-          reply = await fetcher(endpoint.href, { method: 'POST', redirect: 'error', signal: combined,
-            headers: { authorization: `Bearer ${key}`, 'content-type': 'application/json' }, body: JSON.stringify({ state, questions, model }) });
-        } catch { throw backendError('unreachable', 'Backend request failed or timed out'); }
-        if (reply.ok) return validateResponse(await boundedJson(reply), questions);
-        await reply.body?.cancel().catch(() => {});
-        if (![429, 529].includes(reply.status) || attempt === 2) throw backendError('http-error', `Backend HTTP ${reply.status}`);
-        try { await wait(retryDelayMs * (attempt + 1), undefined, { signal: combined }); }
-        catch { throw backendError('unreachable', 'Backend request failed or timed out'); }
-      }
-    },
-  };
-}