@openvulcan/dsh-vulcancode 0.0.0-stage → 0.4.3

package/node_modules/@openvulcan/dsh-decision-guard/lib/decide.d.ts

@@ -0,0 +1,90 @@
+/**
+ * How the decision model's verdict, the optional LLM review and the session's attendance combine
+ * into what dsh does with a call. Nothing that fails or cannot be judged ever runs without either
+ * the LLM review or the user allowing it.
+ */
+import type { Verdict } from '@openvulcan/vulcan-decision';
+/** The decision model's answer, or why there is none. */
+export type FirstStage = {
+    readonly kind: 'verdict';
+    readonly verdict: Verdict;
+} | {
+    readonly kind: 'error';
+    readonly message: string;
+};
+/**
+ * The LLM review's answer.
+ *
+ * - `review`: the reviewer cannot confirm authorization and leaves it to the user (attended only).
+ * - `deny`: unsafe, unauthorized or matching a deny rule.
+ * - `forbid`: matching a rule the user absolutely forbids; refused without asking anyone.
+ */
+export type SecondStage = {
+    readonly kind: 'skipped';
+} | {
+    readonly kind: 'allow';
+} | {
+    readonly kind: 'review';
+    readonly reason?: string;
+} | {
+    readonly kind: 'deny';
+    readonly reason?: string;
+} | {
+    readonly kind: 'forbid';
+    readonly reason?: string;
+} | {
+    readonly kind: 'error';
+    readonly message: string;
+};
+/** What the decision model made of a call it did not allow; `unjudged` means it could not judge. */
+export type Stage = 'review' | 'block' | 'unjudged';
+/** Localized text for the approval prompt; dsh picks the entry for the UI locale. */
+export interface DisplayText {
+    readonly [locale: string]: string;
+    readonly en: string;
+    readonly zh: string;
+}
+/** What the approval prompt shows besides its headline; the client reads it to set focus and badges. */
+export interface PromptDetail {
+    readonly stage: Stage;
+    /** The LLM review's answer, when one was made. */
+    readonly review?: 'review' | 'deny' | 'error';
+    /** Reviewer's reason or failure message. */
+    readonly reviewReason?: string;
+    /** The button focused when the prompt opens. */
+    readonly focus: 'allow' | 'reject';
+}
+export type Outcome = {
+    readonly kind: 'run';
+} | {
+    readonly kind: 'ask';
+    readonly reason: string;
+    readonly display: DisplayText;
+    readonly detail: PromptDetail;
+} | {
+    readonly kind: 'deny';
+    readonly reason: string;
+};
+/** The settings and session facts {@link decide} needs. */
+export interface Situation {
+    /** Whether a human can be asked in this session. */
+    readonly attended: boolean;
+    /** Whether the LLM review is turned on. */
+    readonly llm: boolean;
+    /** Whether a `block` verdict also goes to the LLM review, which may then allow it. */
+    readonly llmOverridesBlock: boolean;
+}
+/** Name of the tool through which the agent explains its next call; see `intent.ts`. */
+export declare const INTENT_TOOL = "explain_tool_call";
+/** The stage of a call the decision model did not allow, or undefined when it runs. */
+export declare function stageOf(first: FirstStage): Stage | undefined;
+/** Whether the LLM review looks at a call of this stage. */
+export declare function wantsReview(stage: Stage, situation: Situation): boolean;
+/**
+ * - `allow` runs.
+ * - With the LLM review on, it decides first: allow runs, forbid is refused outright, and anything
+ *   else asks the user when someone is there and is refused otherwise.
+ * - A `block` the LLM may not override, and every stage with the LLM review off, asks the user
+ *   when someone is there and is refused otherwise.
+ */
+export declare function decide(tool: string, first: FirstStage, second: SecondStage, situation: Situation): Outcome;

package/node_modules/@openvulcan/dsh-decision-guard/lib/decide.js

@@ -0,0 +1,108 @@
+/**
+ * How the decision model's verdict, the optional LLM review and the session's attendance combine
+ * into what dsh does with a call. Nothing that fails or cannot be judged ever runs without either
+ * the LLM review or the user allowing it.
+ */
+/** Name of the tool through which the agent explains its next call; see `intent.ts`. */
+export const INTENT_TOOL = 'explain_tool_call';
+/** The stage of a call the decision model did not allow, or undefined when it runs. */
+export function stageOf(first) {
+    if (first.kind === 'error')
+        return 'unjudged';
+    if (first.verdict.decision === 'allow')
+        return undefined;
+    return first.verdict.decision;
+}
+/** Whether the LLM review looks at a call of this stage. */
+export function wantsReview(stage, situation) {
+    return situation.llm && (stage !== 'block' || situation.llmOverridesBlock);
+}
+/**
+ * - `allow` runs.
+ * - With the LLM review on, it decides first: allow runs, forbid is refused outright, and anything
+ *   else asks the user when someone is there and is refused otherwise.
+ * - A `block` the LLM may not override, and every stage with the LLM review off, asks the user
+ *   when someone is there and is refused otherwise.
+ */
+export function decide(tool, first, second, situation) {
+    const stage = stageOf(first);
+    if (stage === undefined)
+        return { kind: 'run' };
+    const subject = subjectOf(tool, first, stage);
+    if (second.kind === 'allow')
+        return { kind: 'run' };
+    if (second.kind === 'forbid') {
+        return { kind: 'deny', reason: `${subject}, and its review found that it breaks a rule the user absolutely forbids${detail(second.reason)}. ${retryHint(tool)}` };
+    }
+    if (!situation.attended) {
+        switch (second.kind) {
+            case 'deny':
+                return { kind: 'deny', reason: `${subject}, and its review denied it${detail(second.reason)}. ${retryHint(tool)}` };
+            case 'review':
+                // The unattended reviewer is told it has only two answers; a third is still not an allow.
+                return { kind: 'deny', reason: `${subject}, and its review did not allow it${detail(second.reason)}. ${retryHint(tool)}` };
+            case 'error':
+                return { kind: 'deny', reason: `${subject}, and its review failed: ${second.message}. No one is available to confirm the call in this unattended session, so it was not executed.` };
+            case 'skipped':
+                return { kind: 'deny', reason: `${subject}. No one is available to confirm the call in this unattended session, so it was not executed.` };
+        }
+    }
+    const display = displayOf(first, stage, second);
+    switch (second.kind) {
+        case 'review':
+            return ask(`${subject}; its review leaves the decision to the user${detail(second.reason)}`, display, {
+                stage, review: 'review', focus: 'allow', ...reasonOf(second.reason),
+            });
+        case 'deny':
+            return ask(`${subject}; its review denied it${detail(second.reason)}`, display, {
+                stage, review: 'deny', focus: 'reject', ...reasonOf(second.reason),
+            });
+        case 'error':
+            return ask(`${subject}; its review failed: ${second.message}`, display, {
+                stage, review: 'error', reviewReason: second.message, focus: stage === 'review' ? 'allow' : 'reject',
+            });
+        case 'skipped':
+            return ask(`${subject}; the user decides`, display, { stage, focus: stage === 'review' ? 'allow' : 'reject' });
+    }
+}
+function subjectOf(tool, first, stage) {
+    if (first.kind === 'error')
+        return `Vulcan Decision could not judge tool "${tool}" (${first.message})`;
+    if (stage === 'review')
+        return `Vulcan Decision flagged tool "${tool}" as needing confirmation`;
+    return first.verdict.reason_code === 'input_token_limit'
+        ? `Vulcan Decision blocked tool "${tool}" because the call is too long to judge`
+        : `Vulcan Decision blocked tool "${tool}" as unsafe`;
+}
+function displayOf(first, stage, second) {
+    const model = first.kind === 'error'
+        ? { en: `Vulcan Decision could not judge this call (${first.message})`, zh: `Vulcan Decision 无法判定此调用（${first.message}）` }
+        : stage === 'review'
+            ? { en: 'Vulcan Decision asks you to confirm this call', zh: 'Vulcan Decision 需要你确认此调用' }
+            : first.verdict.reason_code === 'input_token_limit'
+                ? { en: 'Vulcan Decision blocked this call because it is too long to judge', zh: '此调用过长，Vulcan Decision 无法判定，已拦截' }
+                : { en: 'Vulcan Decision blocked this call as unsafe', zh: 'Vulcan Decision 认为此调用不安全，已拦截' };
+    switch (second.kind) {
+        case 'review':
+            return { en: `${model.en}; the LLM review leaves it to you.`, zh: `${model.zh}；LLM 复核交由你决定。` };
+        case 'deny':
+            return { en: `${model.en}; the LLM review denied it.`, zh: `${model.zh}；LLM 复核未放行。` };
+        case 'error':
+            return { en: `${model.en}; the LLM review failed.`, zh: `${model.zh}；LLM 复核失败。` };
+        default:
+            return { en: `${model.en}.`, zh: `${model.zh}。` };
+    }
+}
+function ask(reason, display, detail) {
+    return { kind: 'ask', reason, display, detail };
+}
+function detail(reason) {
+    return reason === undefined ? '' : `: ${reason}`;
+}
+function reasonOf(reason) {
+    return reason === undefined ? {} : { reviewReason: reason };
+}
+/** Every LLM denial tells the agent how to explain itself and ask again. */
+function retryHint(tool) {
+    return `The call was not executed. If it is needed and the reviewer misread it, call ${INTENT_TOOL} with tool "${tool}" and the purpose of the call, then make the call again.`;
+}

package/node_modules/@openvulcan/dsh-decision-guard/lib/index.d.ts

@@ -0,0 +1,129 @@
+import type { Context, Volatile } from '@deepseek-ai/cordis';
+import Schema from '@deepseek-ai/schemastery';
+import { type DecisionOptions, type DownloadSource, type PackId } from '@openvulcan/vulcan-decision';
+export { PROJECTION_KEY, REVIEW_PROMPT_COMMAND, REVIEW_PROMPT_RECORD, UNATTENDED_COMMAND, UNATTENDED_RECORD, type GuardSessionView, } from './session-state.js';
+export declare const name = "vulcan-decision-guard";
+export declare const inject: string[];
+/**
+ * How users turn the guard on.
+ *
+ * - `auto-preset`: register dsh's single `auto` permission preset; sessions that select it are
+ *   judged and run with the preset's Full access sandbox.
+ * - `standalone`: judge every session on top of whatever preset it selected.
+ */
+export type Mode = 'auto-preset' | 'standalone';
+/**
+ * Where verdicts come from: OpenVulcan's cloud endpoints (the default, needing only a sign-in), or
+ * a model on this machine run by an installed runtime pack.
+ */
+export type Backend = 'cloud' | 'local';
+/**
+ * Which LLM reviews calls the decision model did not allow.
+ *
+ * - `session`: the session's current model.
+ * - `custom`: `reviewProvider` and `reviewModel`.
+ * - `off`: no LLM review; the user is asked, or the call is refused when nobody can be asked.
+ */
+export type Review = 'session' | 'custom' | 'off';
+/**
+ * Every field is volatile: dsh's settings forms expose only volatile fields, and a change applies
+ * without restarting the plugin. Read each value when an operation starts.
+ */
+export interface Config {
+    mode: Volatile<Mode>;
+    backend: Volatile<Backend>;
+    /** Cloud model id; empty uses the first model OpenVulcan lists for the account. */
+    cloudModel: Volatile<string>;
+    /** Endpoint id the user locked; absent uses the measured best one. */
+    cloudEndpoint: Volatile<string | undefined>;
+    /** Installed runtime pack for the local backend. */
+    localPack: Volatile<PackId | undefined>;
+    /** Installed model id for the local backend. */
+    localModel: Volatile<string | undefined>;
+    /** Download host for runtime packs: the official hosts, or mirrors in China. */
+    downloadSource: Volatile<DownloadSource>;
+    review: Volatile<Review>;
+    reviewProvider: Volatile<string | undefined>;
+    reviewModel: Volatile<string | undefined>;
+    allowRules: Volatile<string>;
+    denyRules: Volatile<string>;
+    forbidRules: Volatile<string>;
+    llmOverridesBlock: Volatile<boolean>;
+    /** System default additional review prompt while the user is present; a session may replace it. */
+    reviewPrompt: Volatile<string>;
+    /** Deny policy offered when a session turns unattended mode on; the session keeps what the user confirmed. */
+    unattendedPolicy: Volatile<string>;
+    /** Whether calls are kept in the local decision log. */
+    recordDecisions: Volatile<boolean>;
+    /** Seconds an approval prompt waits before the call is refused; 0 waits for the user. */
+    askTimeout: Volatile<number>;
+    crossProjectWrites: Volatile<DecisionOptions['cross_project_writes']>;
+    databaseReset: Volatile<DecisionOptions['database_reset']>;
+    projectReset: Volatile<DecisionOptions['project_reset']>;
+}
+export declare const Config: Schema<Schemastery.ObjectS<NoInfer<{
+    mode: Schema<"auto-preset" | "standalone", "auto-preset" | "standalone", "volatile-defined">;
+    backend: Schema<"local" | "cloud", "local" | "cloud", "volatile-defined">;
+    cloudModel: Schema<string, string, "volatile-defined">;
+    cloudEndpoint: Schema<string, string, "volatile">;
+    localPack: Schema<"onnx-cpu" | "onnx-cuda" | "torch-cpu" | "torch-cu128", "onnx-cpu" | "onnx-cuda" | "torch-cpu" | "torch-cu128", "volatile">;
+    localModel: Schema<string, string, "volatile">;
+    downloadSource: Schema<"cn" | "official", "cn" | "official", "volatile-defined">;
+    review: Schema<"off" | "session" | "custom", "off" | "session" | "custom", "volatile-defined">;
+    reviewProvider: Schema<string, string, "volatile">;
+    reviewModel: Schema<string, string, "volatile">;
+    allowRules: Schema<string, string, "volatile-defined">;
+    denyRules: Schema<string, string, "volatile-defined">;
+    forbidRules: Schema<string, string, "volatile-defined">;
+    llmOverridesBlock: Schema<boolean, boolean, "volatile-defined">;
+    reviewPrompt: Schema<string, string, "volatile-defined">;
+    unattendedPolicy: Schema<string, string, "volatile-defined">;
+    recordDecisions: Schema<boolean, boolean, "volatile-defined">;
+    askTimeout: Schema<number, number, "volatile-defined">;
+    crossProjectWrites: Schema<"allow" | "review", "allow" | "review", "volatile-defined">;
+    databaseReset: Schema<"allow" | "confirm", "allow" | "confirm", "volatile-defined">;
+    projectReset: Schema<"allow" | "confirm", "allow" | "confirm", "volatile-defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    mode: Schema<"auto-preset" | "standalone", "auto-preset" | "standalone", "volatile-defined">;
+    backend: Schema<"local" | "cloud", "local" | "cloud", "volatile-defined">;
+    cloudModel: Schema<string, string, "volatile-defined">;
+    cloudEndpoint: Schema<string, string, "volatile">;
+    localPack: Schema<"onnx-cpu" | "onnx-cuda" | "torch-cpu" | "torch-cu128", "onnx-cpu" | "onnx-cuda" | "torch-cpu" | "torch-cu128", "volatile">;
+    localModel: Schema<string, string, "volatile">;
+    downloadSource: Schema<"cn" | "official", "cn" | "official", "volatile-defined">;
+    review: Schema<"off" | "session" | "custom", "off" | "session" | "custom", "volatile-defined">;
+    reviewProvider: Schema<string, string, "volatile">;
+    reviewModel: Schema<string, string, "volatile">;
+    allowRules: Schema<string, string, "volatile-defined">;
+    denyRules: Schema<string, string, "volatile-defined">;
+    forbidRules: Schema<string, string, "volatile-defined">;
+    llmOverridesBlock: Schema<boolean, boolean, "volatile-defined">;
+    reviewPrompt: Schema<string, string, "volatile-defined">;
+    unattendedPolicy: Schema<string, string, "volatile-defined">;
+    recordDecisions: Schema<boolean, boolean, "volatile-defined">;
+    askTimeout: Schema<number, number, "volatile-defined">;
+    crossProjectWrites: Schema<"allow" | "review", "allow" | "review", "volatile-defined">;
+    databaseReset: Schema<"allow" | "confirm", "allow" | "confirm", "volatile-defined">;
+    projectReset: Schema<"allow" | "confirm", "allow" | "confirm", "volatile-defined">;
+}>>, "plain">;
+/**
+ * Key of the approval prompt's `displayReason` entry that carries {@link PromptPayload} as JSON.
+ * dsh resolves the prompt text by locale and never reads this key; this plugin's composer card
+ * does. Also restated in `client/index.tsx`.
+ */
+export declare const PROMPT_KEY = "x-vulcan-decision";
+/** What this plugin's approval card reads from {@link PROMPT_KEY}. */
+export interface PromptPayload {
+    readonly v: 1;
+    readonly stage: 'review' | 'block' | 'unjudged';
+    readonly review?: 'review' | 'deny' | 'error';
+    readonly reviewReason?: string;
+    readonly focus: 'allow' | 'reject';
+    readonly intent?: string;
+    /** The call's command or arguments, shortened. */
+    readonly preview: string;
+    /** Countdown length; absent when the prompt waits for the user. */
+    readonly timeoutMs?: number;
+}
+/** Install the Vulcan Decision gate and, in `auto-preset` mode, the Auto preset. */
+export declare function apply(ctx: Context, config: Config): Promise<void>;