dsh-decision-layer 0.7.0 → 0.7.2

package/lib/host/task-completion.js

@@ -0,0 +1,148 @@
+import { createSteerOnce } from "./steer-once.js";
+import { errorReason, isObject, isProbability } from "./types.js";
+const MAX_STATE = 8 * 1024;
+const MAX_CONDITION = 512;
+const MAX_CONDITIONS = 20;
+const MAX_EVIDENCE = 40;
+const STEER_TEXT = "\u672C\u56DE\u5408\u4EFB\u52A1\u5B8C\u6210\u6838\u5BF9\u53D1\u73B0\u6709\u660E\u786E\u4EA4\u4ED8\u6761\u4EF6\u5C1A\u672A\u6EE1\u8DB3\uFF1A\u8BF7\u5BF9\u7167\u7528\u6237\u5217\u51FA\u7684\u6761\u4EF6\u9010\u9879\u590D\u6838\uFF0C\u8865\u5B8C\u672A\u5B8C\u6210\u7684\u90E8\u5206\u3002";
+function extractConditions(userText) {
+  const text = typeof userText === "string" ? userText : "";
+  if (!text.trim()) return [];
+  const conditions = [];
+  const push = (value) => {
+    const item = value.trim().replace(/\s+/g, " ").slice(0, MAX_CONDITION);
+    if (item && !conditions.includes(item)) conditions.push(item);
+  };
+  const lines = text.split(/\r?\n/);
+  let matchedStructured = false;
+  for (const line of lines) {
+    const numbered = line.match(/^\s*(?:[（(]?\d+[)）.、]|\d+\s*[.)、])\s+(.*)$/)?.[1];
+    const bullet = line.match(/^\s*[-*•]\s+(.*)$/)?.[1];
+    if (numbered?.trim()) {
+      push(numbered);
+      matchedStructured = true;
+    } else if (bullet?.trim()) {
+      push(bullet);
+      matchedStructured = true;
+    }
+  }
+  if (!matchedStructured) {
+    const compact = text.trim();
+    if (!/[\r\n]/.test(compact)) {
+      const parts = compact.split(/[、，,]/).map((part) => part.trim()).filter(Boolean);
+      if (parts.length >= 2) for (const part of parts) push(part);
+    }
+  }
+  return conditions.slice(0, MAX_CONDITIONS);
+}
+function completionQuestions(conditions, evidence, answer) {
+  const items = Array.isArray(conditions) ? conditions.slice(0, MAX_CONDITIONS) : [];
+  const tools = Array.isArray(evidence) ? evidence.filter((item) => isObject(item) && typeof item.tool === "string").slice(0, MAX_EVIDENCE).map((item) => ({ tool: item.tool.slice(0, 128), outcome: item.outcome === "error" ? "error" : "ok" })) : [];
+  const state = {
+    conditions: items.map((text, index) => ({ id: `c${index}`, text })),
+    toolEvidence: tools,
+    finalReply: String(answer ?? "").slice(0, MAX_STATE),
+    note: "\u5DE5\u5177\u8BC1\u636E\uFF08toolEvidence\uFF09\u662F\u5224\u5B9A\u4F9D\u636E\uFF1BfinalReply \u81EA\u79F0\u5B8C\u6210\u4E0D\u4F5C\u4E3A\u8BC1\u636E\u3002\u7F3A\u5C11\u8BC1\u636E\u65F6\u9009 insufficient_evidence\u3002"
+  };
+  const questions = Object.fromEntries(items.map((text, index) => [`c${index}`, {
+    type: "choice",
+    instructions: {
+      condition: text,
+      question: "\u6839\u636E\u5F53\u524D\u5DE5\u5177\u8BC1\u636E\u4E0E\u6700\u7EC8\u56DE\u590D\uFF0C\u8FD9\u4E2A\u4EA4\u4ED8\u6761\u4EF6\u7684\u5B8C\u6210\u60C5\u51B5\u5C5E\u4E8E\u54EA\u4E00\u79CD\uFF1F"
+    },
+    criteria: {
+      satisfied: "\u6709\u5DE5\u5177\u8BC1\u636E\u6216\u7528\u6237\u660E\u786E\u786E\u8BA4\u8868\u660E\u8BE5\u6761\u4EF6\u5DF2\u5B8C\u6210",
+      unsatisfied: "\u6709\u8BC1\u636E\u8868\u660E\u8BE5\u6761\u4EF6\u672A\u5B8C\u6210\u6216\u505A\u9519",
+      insufficient_evidence: "\u73B0\u6709\u8BC1\u636E\u4E0D\u8DB3\u4EE5\u5224\u65AD\u8BE5\u6761\u4EF6\u662F\u5426\u5B8C\u6210"
+    }
+  }]));
+  return { state, questions };
+}
+const DEFAULT_MIN_CONFIDENCE = 0.4;
+function createTaskCompletion({ evaluate, sessions, steer, settings, minConfidence = DEFAULT_MIN_CONFIDENCE } = {}) {
+  if (typeof evaluate !== "function") throw new Error("Task completion requires an evaluator");
+  const steerOnce = createSteerOnce();
+  const resolveSettings = async () => {
+    let raw = {};
+    try {
+      raw = (typeof settings === "function" ? await settings() : settings) ?? {};
+    } catch {
+      raw = {};
+    }
+    const mode = raw?.mode === "steer" ? "steer" : "observe";
+    const minConditions = Number.isSafeInteger(raw?.minConditions) && raw.minConditions >= 2 ? raw.minConditions : 2;
+    const confidenceFloor = isProbability(raw?.minConfidence) ? raw.minConfidence : minConfidence;
+    return { mode, minConditions, minConfidence: confidenceFloor };
+  };
+  const record = (turn, outcome, detail = {}) => {
+    const id = turn?.agent?.session?.id;
+    if (!sessions || typeof id !== "string" || typeof sessions.recordComplete !== "function") return;
+    try {
+      sessions.recordComplete(id, outcome, detail);
+    } catch {
+    }
+    if (typeof sessions.log !== "function") return;
+    try {
+      sessions.log(id, { kind: "complete", outcome, ...detail });
+    } catch {
+    }
+  };
+  const skip = { evaluated: false, steered: false };
+  return {
+    async review(turn) {
+      const output = typeof turn?.output === "string" ? turn.output.trim() : "";
+      const { mode, minConditions, minConfidence: confidenceFloor } = await resolveSettings();
+      const conditions = extractConditions(turn?.userText);
+      if (conditions.length < minConditions) return { ...skip };
+      const evidence = Array.isArray(turn?.evidence) ? turn.evidence : [];
+      if (evidence.length === 0) return { ...skip };
+      const id = turn?.agent?.session?.id;
+      if (sessions && typeof id === "string") {
+        try {
+          if (sessions.snapshot(id).enabled === false) return { ...skip };
+        } catch {
+          return { ...skip };
+        }
+      }
+      let answers;
+      try {
+        const result = await evaluate(completionQuestions(conditions, evidence, output), { signal: turn?.signal });
+        answers = isObject(result?.answers) ? result.answers : void 0;
+      } catch (error) {
+        record(turn, "error", { reason: errorReason(error) });
+        return { ...skip };
+      }
+      if (!answers) {
+        record(turn, "error", { reason: "invalid-response" });
+        return { ...skip };
+      }
+      let satisfied = 0, unsatisfied = 0, insufficient = 0;
+      let unsatisfiedMinConf = 1;
+      for (let index = 0; index < conditions.length; index++) {
+        const answer = answers[`c${index}`];
+        if (!isObject(answer) || answer.type !== "choice" || typeof answer.choice !== "string") {
+          insufficient++;
+          continue;
+        }
+        if (answer.choice === "satisfied") satisfied++;
+        else if (answer.choice === "unsatisfied") {
+          unsatisfied++;
+          if (isProbability(answer.confidence)) unsatisfiedMinConf = Math.min(unsatisfiedMinConf, answer.confidence);
+        } else insufficient++;
+      }
+      const outcome = unsatisfied > 0 ? "unsatisfied" : "ok";
+      const detail = { conditions: conditions.length, satisfied, unsatisfied, insufficient };
+      const confident = unsatisfied > 0 && unsatisfiedMinConf >= confidenceFloor;
+      const steered = mode === "steer" && confident && typeof steer === "function" && turn?.agent ? steerOnce.attempt(turn, () => steer(turn.agent, STEER_TEXT)) : false;
+      if (steered) detail.steered = true;
+      record(turn, outcome, detail);
+      return { evaluated: true, steered, satisfied, unsatisfied, insufficient };
+    }
+  };
+}
+export {
+  DEFAULT_MIN_CONFIDENCE,
+  completionQuestions,
+  createTaskCompletion,
+  extractConditions
+};

package/lib/host/types.d.ts

@@ -0,0 +1,343 @@
+/**
+ * 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;
+    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;
+};
+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/locale/en.json

@@ -1,6 +1,7 @@
 {
   "meta": {
     "title": "Decision Layer",
-    "description": "A structured decision layer for the DeepSeek Harness agent loop: a danger-call gate, output self-check, and loop guard backed by a pluggable adjudication model."
+    "description": "A structured decision layer for the DeepSeek Harness agent loop: a danger-call gate, output self-check, tool narrowing, task-completion review, and loop guard backed by a pluggable adjudication model.",
+    "detail": "docs/en/DETAIL.md"
   }
 }

package/locale/zh.json

@@ -1,6 +1,7 @@
 {
   "meta": {
     "title": "决策层",
-    "description": "为 DeepSeek Harness agent 循环提供的结构化决策层：危险调用门控、产出自检与防循环，由可插拔的裁决模型驱动。"
+    "description": "为 DeepSeek Harness agent 循环提供的结构化决策层：危险调用门控、产出自检、工具收窄、任务完成核对与防循环，由可插拔的裁决模型驱动。",
+    "detail": "docs/zh/DETAIL.md"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-decision-layer",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "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,12 +14,14 @@
   "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",
     "icon.svg",
     "cordis.patch.yml",
     "README.md",
@@ -34,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",
@@ -56,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",
@@ -78,5 +86,6 @@
       ],
       "platform": "web"
     }
-  }
+  },
+  "types": "./lib/host/index.d.ts"
 }