@vibedgc/sdk 0.6.4

package/dist/policy.d.ts

@@ -0,0 +1,128 @@
+import type { PermissionAction, PermissionMode, PermissionRequest, RuntimePolicy, SandboxRequirement, SandboxSetting, SandboxStatus, UnhandledPolicy } from "./types.ts";
+export declare const DISPLAY: Readonly<Record<string, string>>;
+export declare const SESSION_POLICY_ENV = "DGC_SESSION_POLICY";
+/** Quote fnmatch metacharacters so a literal path or route matches only itself. */
+export declare function escapeGlob(text: string): string;
+/**
+ * fnmatch patterns that match every string except the allowed ones. An entry ending in `*`
+ * allows every string starting with the text before it. DGC rules can only deny, so an allowlist
+ * becomes denies of everything else.
+ */
+export declare function complementPatterns(allowed: Iterable<string>): string[];
+/** Like Python's Path.resolve(strict=False): symlinks resolved for the part that exists. */
+export declare function resolvePath(raw: string, cwd?: string | null): string | null;
+export declare function within(child: string, parent: string): boolean;
+export declare function looksLikeNetwork(command: string): boolean;
+/** True when a shell/python snippet is a file-write, not merely a read or `2>&1`. */
+export declare function looksLikeWrite(command: string): boolean;
+/** A validated {@link RuntimePolicy}. */
+export declare class Policy {
+    readonly network: "deny" | "allow";
+    readonly extraReadDirs: readonly string[];
+    readonly denyPathPrefixes: readonly string[];
+    readonly denyTools: readonly string[];
+    readonly allowTools: readonly string[] | null;
+    readonly redactEvents: boolean;
+    readonly shell: "sandboxed" | "screened";
+    constructor(options: RuntimePolicy);
+    writesDenied(): boolean;
+    /** True when this policy forbids the tool by name, independent of command screening. */
+    namedToolDenied(name: string, args?: Record<string, unknown>): boolean;
+    /** Throw when an `mcp__app__` route names none of the session's own tools. */
+    checkSessionTools(customTools: readonly string[]): void;
+    namedRules(): string[];
+    /**
+     * Named-tool, network-tool and write-path rules, plus command-screening globs (best-effort
+     * screening, not a boundary; what `shell: "screened"` applies in auto mode).
+     */
+    engineDenyRules(inspectBash?: boolean): string[];
+    /**
+     * Classify one permission request: "deny" (the policy forbids it), "once" (the policy itself
+     * allows it: a read in extraReadDirs, or a search clear of denied paths), "screen" (command
+     * text looks like a network call or file write; best effort), or null (no opinion).
+     */
+    evaluate(request: PermissionRequest, cwd: string | null): "deny" | "once" | "screen" | null;
+    /** "deny" when this policy forbids the call, "once" when it allows it itself, else null. */
+    decision(request: PermissionRequest, cwd?: string | null): PermissionAction | null;
+    pathVerdict(name: string, args: Record<string, unknown>, cwd: string | null): "deny" | "once" | null;
+    deniedPrefixes(cwd: string | null): string[];
+    extraDirs(cwd: string | null): string[];
+    /** True when a denied prefix sits inside a tree the agent may search. */
+    searchGuard(cwd: string | null): boolean;
+}
+/** Normalize the public policy option. */
+export declare function toPolicy(value: RuntimePolicy | Policy | undefined | null): Policy | null;
+/**
+ * Compile bash write/network globs only when nobody will answer a permission_request. Auto mode
+ * never raises one, so the engine must deny by itself. Kept for API compatibility.
+ */
+export declare function inspectBashForEngine(onPermission?: unknown, mode?: string): boolean;
+/** The policy's named-tool, network and path rules plus screening globs (see {@link Policy.engineDenyRules}). */
+export declare function engineDenyRules(policy: RuntimePolicy | Policy | undefined | null, opts?: {
+    inspectBash?: boolean;
+}): string[];
+/** "deny" when the policy forbids this request (including screened command text), else null. */
+export declare function policyDecision(policy: RuntimePolicy | Policy | undefined | null, request: PermissionRequest, cwd?: string | null): "deny" | null;
+/**
+ * Normalize `session({ permissions })` into [mode, unhandled]. `unhandled: "deny"`: a request the
+ * callback does not answer is denied and the agent carries on (no callback denies every request).
+ * `"callback"`: every request must go to your callback, so `session()` refuses to start without
+ * one; a request it still leaves unanswered (it threw, returned something else, or ran past
+ * `decisionTimeoutMs`) is denied and the run stops with `reason: "decision_failed"`.
+ */
+export declare function permissionSettings(value: unknown, mode: PermissionMode | undefined, defaultMode: PermissionMode, onPermission: unknown): [PermissionMode, UnhandledPolicy];
+/** Normalize `sandbox` ("required" | "preferred" | "off", or `{ requirement }`). */
+export declare function sandboxRequirement(value: SandboxSetting | undefined | null): SandboxRequirement;
+/** Fail early for "required" when this host plainly has no backend (the runtime decides finally). */
+export declare function sandboxPrecheck(requirement: SandboxRequirement): void;
+/** What one session's runtime is told, and how to confirm it took effect. */
+export declare class SessionPlan {
+    readonly env: Record<string, string>;
+    readonly requirement: SandboxRequirement;
+    readonly policy: Policy | null;
+    readonly notes: readonly string[];
+    /**
+     * The policy asks for a sandboxed shell that could still run (the mode is not plan) and the
+     * caller did not accept a weaker fallback: a runtime with no OS sandbox must then refuse the
+     * session rather than run the shell unconfined.
+     */
+    readonly strictShell: boolean;
+    constructor(env: Record<string, string>, requirement: SandboxRequirement, policy: Policy | null, notes?: readonly string[], strictShell?: boolean);
+    get payload(): string;
+    /**
+     * Check the ready handshake: the runtime read this policy and has the sandbox asked for.
+     * Throws DGCUnsupportedError when the runtime cannot honour it.
+     */
+    confirm(ready: Record<string, unknown>): SandboxStatus;
+    private confirmTools;
+}
+/**
+ * Turn a RuntimePolicy and sandbox choice into the runtime's per-session policy. It travels to
+ * `dgc serve` in the DGC_SESSION_POLICY environment variable; nothing is written to any config.
+ */
+export declare function compileSession(policy: Policy | null, options: {
+    cwd: string;
+    mode: PermissionMode;
+    sandbox: SandboxRequirement;
+    tools?: readonly string[];
+    /** Whether the workspace may grant this session capabilities (default false). */
+    trustWorkspace?: boolean;
+    /** False for an inheritUserState session (default true). */
+    isolated?: boolean;
+}): SessionPlan;
+/**
+ * Answer one permission_request: the policy first, then the callback. A policy deny is final; a
+ * request the policy raised only to check it ("once") is answered without the callback; command
+ * screening denies unless a reviewing callback is present outside auto mode. A denial the policy
+ * made carries a reason, so the runtime tells the model it was the application's policy (not "the
+ * user").
+ */
+export declare function resolvePermission(policy: Policy | null, request: PermissionRequest, options: {
+    cwd: string | null;
+    permissionMode: string;
+    onPermission: unknown;
+    ask: () => Promise<unknown>;
+}): Promise<{
+    action: PermissionAction;
+    reason: string;
+}>;