dsh-perm-gate 5.1.2 → 5.3.0

package/lib/runtime.d.ts

@@ -4,10 +4,12 @@ import type { ClassifierConfig } from './classifier.js';
 import { EventLog } from './events.js';
 import { RiskLearning } from './learning.js';
 import { type RiskRequest, type RiskVerdict } from './risk.js';
+import { type AskContext } from './ask-context.js';
 import { type HostLlmLike, type HostModelSelection } from './host-llm.js';
 import { type CompiledRuleEntry, type CompiledRuleset, type RuleAction } from './rule.js';
 import type { NetworkTarget } from './network.js';
 import { type SessionEventLike } from './preset.js';
+import { type UnattendedMode } from './unattended.js';
 /**
  * The gate's answer to the host's pre-execute waterfall.
  *
@@ -140,6 +142,26 @@ export interface PermGateRuntimeOptions extends PermGateConfig {
     readonly riskHook?: (req: RiskRequest) => Promise<RiskVerdict>;
     /** Optional live source of the Permissive tier (e.g. a DSH settings namespace). */
     readonly readPermissive?: () => PermissiveState;
+    /** Optional live source of the YOLO tier switch (never human-confirm; block-on-danger). */
+    readonly readYolo?: () => boolean;
+    /**
+     * Optional live source of the degraded-review switch: with no reviewer able to grade
+     * an ask, decide on the deterministic nets instead of parking it on a human.
+     */
+    readonly readRulesFallback?: () => boolean;
+    /**
+     * Optional live sources of the two `safenet` switches. Each says whether that
+     * implementation exists at all, and each owns exactly one preset (`permissive-mech` for
+     * pass, `permissive-snet` for ask), so flipping one cannot change another tier.
+     */
+    readonly readSafenetPass?: () => boolean;
+    readonly readSafenetAsk?: () => boolean;
+    /**
+     * Optional live source of the script-review switch: attach the body of every script a
+     * call runs to the review, so the grader and the human judge code, not a filename.
+     * Defaults to on (`config.scriptReview`).
+     */
+    readonly readScriptReview?: () => boolean;
     /** Optional live source of the llmAssist classifier setup. */
     readonly readClassifyConfig?: () => ClassifierConfig;
     /**
@@ -173,6 +195,23 @@ export interface PermGateRuntimeOptions extends PermGateConfig {
      * protective and never silently off); a non-empty array replaces the preset.
      */
     readonly readDenyKeywords?: () => readonly string[] | undefined;
+    /**
+     * Optional live source of the **appended** deny keywords. Unlike `readDenyKeywords`,
+     * which replaces the preset, this extends whatever list is live — the way to protect a
+     * long-tail secret without copying fifty preset entries into a profile.
+     */
+    readonly readDenyKeywordsExtra?: () => readonly string[] | undefined;
+    /**
+     * Optional live source of the user-declared credential paths, consulted by P0's read
+     * and mutation checks (see `config.credentialPaths`).
+     */
+    readonly readCredentialPaths?: () => readonly string[] | undefined;
+    /**
+     * Optional live source of the argument keys treated as document bodies / as operations,
+     * on top of the built-in lists (`extraContentArgKeys`, `extraOperationArgKeys`).
+     */
+    readonly readExtraContentArgKeys?: () => readonly string[] | undefined;
+    readonly readExtraOperationArgKeys?: () => readonly string[] | undefined;
     /**
      * Optional live source of the session's effective approval policy (`'ask'` /
      * `'never'`), normally `approval.effectivePolicy(agent.session)`. Under
@@ -409,6 +448,33 @@ export declare class PermGateRuntime {
     /** The host model-group selection, or undefined when unusable. */
     private hostModel;
     private livePermissive;
+    /** Whether YOLO mode is live (never human-confirm). */
+    isYolo(): boolean;
+    /** Whether degraded review is live (no reviewer ⇒ rule-only gate). */
+    isRulesFallback(): boolean;
+    /** Whether script-body review is live (default on). */
+    isScriptReview(): boolean;
+    /**
+     * The scripts one call will run, read for review.
+     *
+     * `bash ./clean-home.sh` names a file; the operation is inside it. So the body is
+     * fetched (bounded, never executing anything) and handed to the same three reviewers
+     * the rest of the call is: the deterministic nets judge it (an irreversible body is
+     * `I` no model may clear), the grader is shown it (`script_contents`), and the human
+     * card says it was attached. When *every* named script was read, the call is no longer
+     * an unreadable payload — that is what lifts a workspace-outside script run out of the
+     * `U` tier instead of parking it as unknowable.
+     *
+     * Best-effort by construction: any read problem yields "nothing attached", which the
+     * tier machinery already treats as opaque. It must never throw into the decision path.
+     */
+    private scriptReviewFor;
+    /**
+     * Whether a risk grader is reachable: an injected hook, the host `llm` service in
+     * host mode, or a configured custom endpoint. When false, YOLO decides purely on the
+     * deterministic danger signal (fail-open for a non-dangerous ask).
+     */
+    private classifierUsable;
     /**
      * The session's selected permission preset, folded from its event log. The
      * fold is cached on the log's length plus the identity of its last event: a
@@ -463,6 +529,16 @@ export declare class PermGateRuntime {
      * An empty override is treated as "no meaningful override" (the blacklist is
      * protective and stays on); schemastery materializes unset arrays as `[]`. */
     private liveDenyKeywords;
+    /** The user-declared credential paths, as configured (may be empty). */
+    private liveCredentialPaths;
+    /**
+     * The configured additions to the two argument-key sets, or `undefined` when nothing was
+     * configured so `scan-text` keeps its built-in pair without rebuilding anything.
+     *
+     * Read per call: both settings are volatile, and a scan rule that only applies after a
+     * reload is a scan rule nobody can reason about while debugging a false positive.
+     */
+    private liveScanKeys;
     /**
      * The preset deny-keyword layer (inherited from dsh-approval-gate): a keyword
      * hit over the call's command/argument text vetoes it with `deny` before any
@@ -615,6 +691,94 @@ export declare class PermGateRuntime {
      * settled by {@link settleExecution} when the call actually executes.
      */
     refineAsk(exec: ToolExecutionLike, decision: PreToolDecisionLike): Promise<PreToolDecisionLike | undefined>;
+    /**
+     * YOLO resolution of an `ask`: never raise a human. A **dangerous** ask — an
+     * irreversible / unlearnable / opaque call (deterministic), or an `llmAssist`
+     * hard-risk verdict when a grader is reachable — is **blocked** (`deny`), and the
+     * caller feeds the reason back to the main LLM as a user message. Every other ask
+     * is **allowed** (returns `undefined` → passthrough), so ordinary work keeps moving
+     * without a human. This is the mirror of `askAnswerable`'s never-passthrough (which
+     * blanket-allows under `approval: never`): YOLO allows the benign but actively
+     * intercepts the dangerous — "尽力自动拦截所有危险命令".
+     */
+    resolveYolo(exec: ToolExecutionLike, decision: PreToolDecisionLike): Promise<PreToolDecisionLike | undefined>;
+    /**
+     * The review model's pass over one ask, shared by every tier that lets a model
+     * speak for the human. `answered: false` means no reviewer is configured or it was
+     * unreachable — what that *means* is the one thing the tiers disagree about, so the
+     * caller decides (YOLO falls back to the mechanical conclusion, the human tiers keep
+     * the popup, the mechanical tier never gets here).
+     */
+    private modelJudge;
+    /**
+     * Which implementation, if any, owns this call's permission preset.
+     *
+     * One preset, one switch: `permissive-mech` is the mechanical takeover of asks,
+     * `permissive-snet` the model-free ask, `permissive-yolo` the model-backed human-free
+     * tier. Any other preset — including one whose switch is off — returns `null` and runs the
+     * ordinary flow, because a tier with no implementation behind it must not start behaving
+     * like some other tier.
+     */
+    unattendedModeOf(exec: ToolExecutionLike): UnattendedMode | null;
+    /** The mechanical human-free tier for this call (`permissive-mech`, switch on). */
+    isSafetyNet(exec: ToolExecutionLike): boolean;
+    /**
+     * The model-free ask tier for this call (`permissive-snet`, switch on): the mechanical
+     * screen still runs and its doubts ride along with the ask, but no grader is consulted
+     * and the decision stays with a person.
+     */
+    isSafetyNetAsk(exec: ToolExecutionLike): boolean;
+    /**
+     * One frozen view of a call for the human-free tiers: the same context the popup
+     * would have shown (script bodies included), plus the salted digest fields the
+     * grader path expects.
+     */
+    private unattendedContextFor;
+    /**
+     * The mechanical floor — what the deterministic nets can NAME about an ask, or `null`
+     * when nothing is nameable. Every tier classifies with this one judge; the tiers differ
+     * only in what they then do with the answer:
+     *
+     * | tier | 机械点名了危险 | 机械没点名 |
+     * | --- | --- | --- |
+     * | 人工确认（`permissive` / `permissive-full`） | 仍然问人，把信号作为疑点列出 | 问人（`llmAssist` 开着时模型可先精化） |
+     * | `safenetAsk`（`permissive-snet`） | 问人，列疑点 | 问人，**一次模型都不叫** |
+     * | `safenetPass`（`permissive-mech`） | 直接拦 + 回喂 | 直接放行，一次模型都不叫 |
+     * | `yolo`（`permissive-yolo`） | 直接拦（模型无法洗白，也不花这次调用） | 问模型；模型不在则按机械结论处置并标注 |
+     *
+     * The human tier not auto-blocking on a hit is deliberate: the same net that reads
+     * `rm -rf` of a home directory as irreversible also reads a project's own aggressive
+     * cleanup that way, and a person can tell those apart. Nobody is watching in the two
+     * human-free tiers, so there the cost of a false positive is accepted.
+     */
+    private mechanicalJudge;
+    /**
+     * The mechanical tier (`permissive-mech`, behind the `safenetPass` switch) — a
+     * human-free ask settled by the deterministic nets ALONE, with **no model call at all**.
+     * Two equivalent ways to name it: the reviewed form of `approval: never` (that preset
+     * passes every ask with nothing judging it; this one passes only what the nets cannot
+     * condemn), and YOLO with the model taken away — which is also what YOLO itself falls
+     * back to when no reviewer answers.
+     *
+     * It shares {@link mechanicalJudge} with every other tier's first pass: an opaque
+     * payload, irreversible act, or unlearnable destruction is blocked and the reason fed
+     * back to the main LLM. Everything the nets cannot name simply runs. It never softens a
+     * deterministic deny — those arrive already denied — and it never raises a human prompt.
+     */
+    resolveSafetyNet(exec: ToolExecutionLike, decision: PreToolDecisionLike): PreToolDecisionLike | undefined;
+    /**
+     * Degraded resolution of an `ask` when **no reviewer answered it** — either none is
+     * configured or the configured one could not reach a verdict. Instead of leaving the
+     * call on a human seam nobody is watching, it decides on the deterministic nets alone,
+     * the way a static policy gate does: an irreversible (`I`-tier) / unlearnable /
+     * opaque call is **blocked** (the caller feeds the reason back to the main LLM), and
+     * everything else runs. Unlike {@link resolveYolo} no model is consulted at all — this
+     * is what automatic review becomes when the model is missing, not a mode the operator
+     * picks while one is working. Never softens a deterministic deny: those arrive here
+     * already denied, and a rule-only `ask` is by construction something the rules could
+     * not condemn.
+     */
+    resolveRulesDegrade(exec: ToolExecutionLike, decision: PreToolDecisionLike, ctx?: AskContext): PreToolDecisionLike | undefined;
     /**
      * One frozen view of a call, built the same way for every ask path so the
      * popup cannot disagree with what the grader was shown.