@fishwithcat/dsh-user-approval 0.0.0-stage → 0.2.2-alpha.2

package/lib/index.js

@@ -0,0 +1,272 @@
+import { randomUUID } from "node:crypto";
+import { Service } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
+import { z as z$1 } from "zod";
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
+import { scopeTarget } from "@deepseek-ai/dsh-scope";
+import { SessionSeq } from "@deepseek-ai/dsh-session";
+//#region lib/types/types.js
+/**
+* Wire-safe approval identifiers and outcome vocabulary, free of
+* cordis/service imports so browser type chains can
+* consume them without loading this package's Context augmentation.
+* @module @deepseek-ai/dsh-user-approval/types
+*/
+/**
+* Brand a string as an {@link ApprovalRequestId}.
+* @param id - the raw id string to brand.
+* @returns the same string carrying the brand.
+*/
+function ApprovalRequestId(id) {
+	return id;
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Service Definition for the approval capability seam, covering requests,
+* cancellation, audit, per-session policy, and remembered per-tool grants.
+* Missing answerers fail closed.
+* @module @deepseek-ai/dsh-user-approval
+*/
+/** Every {@link ApprovalOutcome}, for runtime normalization of answerer returns. */
+const OUTCOMES = [
+	"allowed-once",
+	"rejected",
+	"cancelled",
+	"unavailable"
+];
+/** Every {@link ApprovalPolicy}, for option advertisement and runtime validation of untrusted policy strings. */
+const APPROVAL_POLICIES = ["ask", "never"];
+/** Model-facing statement for the deterministic `'never'` policy. */
+const NEVER_SENTENCE = "Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`).";
+/** Model-facing statement for an interactive policy that may still fail closed. */
+const ASK_SENTENCE = "Approval prompts are enabled in this session: operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed.";
+/** Model-facing policy names in switch notices; a bare `never` reads as "approval is never granted". */
+const POLICY_NOTICE_NAMES = {
+	ask: "ask the user for approval",
+	never: "never ask the user for approval"
+};
+const approvalStateDefinition = {
+	key: "approvalState",
+	stateVersion: 1,
+	stateSchema: z$1.object({
+		policy: z$1.enum(["ask", "never"]).nullable(),
+		turnOpen: z$1.boolean()
+	}),
+	init: () => ({
+		policy: null,
+		turnOpen: false
+	}),
+	apply(state, event) {
+		switch (event.type) {
+			case "approval/policy": return state.policy === event.data.policy ? state : {
+				...state,
+				policy: event.data.policy
+			};
+			case "turn/start": return state.turnOpen ? state : {
+				...state,
+				turnOpen: true
+			};
+			case "turn/end": return state.turnOpen ? {
+				...state,
+				turnOpen: false
+			} : state;
+			default: return state;
+		}
+	}
+};
+/**
+* Append the sole durable representation of a session policy override. Invalid
+* values throw before the log changes; projected state follows the committed record.
+* @param session - the session the override belongs to.
+* @param policy - the policy in effect until the next switch.
+*/
+function setApprovalPolicy(session, policy) {
+	if (!APPROVAL_POLICIES.includes(policy)) throw new TypeError("approval policy must be one of \"ask\" or \"never\"");
+	session.append("approval/policy", { policy });
+}
+/**
+* Approval service that applies session policy and remembered per-tool grants
+* before answerers and logs every ask/outcome pair to the requesting session.
+* It exposes deterministic policy changes to the model through the
+* runtime-context snapshot and switch notices.
+*/
+var ApprovalService = class extends Service {
+	config;
+	static inject = ["sessionProjections"];
+	static Config = z.object({ policy: z.union(["ask", "never"]).default("ask") });
+	approvalProjectionHandle;
+	constructor(ctx, config) {
+		super(ctx, "approval");
+		this.config = config;
+	}
+	async [Service.init]() {
+		this.approvalProjectionHandle = await this.ctx.sessionProjections.register(approvalStateDefinition);
+		if (this.ctx.fiber.uid === null) return;
+		const effective = (agent) => this.effectivePolicy(agent.session);
+		await this.ctx.inject(["systemPrompt"], (scope) => {
+			scope.systemPrompt.context({
+				name: "approval:policy",
+				order: scope.systemPrompt.getContextOrder("APPROVAL_POLICY"),
+				text: (context) => {
+					const agent = context.agent;
+					if (agent === void 0) return "";
+					return effective(agent) === "never" ? NEVER_SENTENCE : ASK_SENTENCE;
+				}
+			});
+		});
+	}
+	/**
+	* Switch one live agent's policy and queue the transition for its next model
+	* step. Session initialization uses {@link setApprovalPolicy} directly
+	* because there is no previously visible policy to change.
+	* @param agent - the live agent whose policy is changing.
+	* @param policy - the new effective policy.
+	*/
+	setPolicy(agent, policy) {
+		const previous = this.effectivePolicy(agent.session);
+		if (previous === policy) return;
+		setApprovalPolicy(agent.session, policy);
+		agent.inject(createUserMessage({
+			content: [{
+				type: "text",
+				text: `The user changed the approval policy from "${POLICY_NOTICE_NAMES[previous]}" to "${POLICY_NOTICE_NAMES[policy]}".`
+			}],
+			source: { kind: "user-approval" }
+		}));
+	}
+	/**
+	* Ask the composed answerers to decide one readonly same-process request.
+	* The service borrows the request, agent, session, and live signal directly.
+	* A remembered grant for the tool resolves the ask `allowed-once` before any
+	* answerer sees it. The request requires an open turn because the audit pair
+	* must be enclosed by the durable log's commit/replay boundary; an idle ask
+	* rejects before appending anything. The answerer phase always produces an
+	* outcome: an aborted signal yields `'cancelled'`, a missing or throwing answerer yields
+	* `'unavailable'` (fail closed), and a rogue non-vocabulary return value is
+	* normalized to `'unavailable'`. A failure that prevents either audit append
+	* from committing still rejects because returning an unlogged decision would
+	* violate the pair. Session contains post-commit observer failures, so an
+	* authoritative append cannot reject the request or suppress its matching
+	* audit event.
+	* @param req - the pending decision (agent, tool identity, reason, signal).
+	* @returns the closed outcome; `'allowed-once'` is the only grant.
+	* @throws when no turn is open or either audit event fails before the session
+	*   append commit point.
+	*/
+	async request(req) {
+		const session = req.agent.session;
+		if (!this.approvalStateOf(session).turnOpen) throw new Error("approval.request() outside an open turn: the approval/asked + approval/decided audit pair must be turn-enclosed (a bare event between turns is crash-tail garbage on reload). Ask from inside the turn that needs the decision.");
+		const id = ApprovalRequestId(randomUUID());
+		session.append("approval/asked", {
+			id,
+			toolName: req.toolName,
+			...req.callId !== void 0 ? { callId: req.callId } : {},
+			...req.reason !== void 0 ? { reason: req.reason } : {}
+		});
+		const outcome = await this.decide(req, session);
+		const remembered = outcome === "allowed-once" && this.isGranted(req.agent, req.toolName);
+		session.append("approval/decided", {
+			id,
+			outcome,
+			...remembered ? { remembered: true } : {}
+		});
+		return outcome;
+	}
+	/**
+	* Remember one tool's approval for a session and its live descendants. Every
+	* later ask for that tool resolves `allowed-once` without consulting an
+	* answerer while the effective policy is `ask`; `never` still rejects first.
+	* Recording nothing when the grant already exists keeps replay and repeated
+	* Always allow choices from growing the log.
+	* @param session - the session whose subtree the grant covers.
+	* @param toolName - the tool whose future asks the grant covers.
+	* @throws when the tool name is empty.
+	*/
+	grant(session, toolName) {
+		if (toolName.trim() === "") throw new TypeError("approval grant requires a non-empty tool name");
+		if (this.grantedIn(session, toolName)) return;
+		session.append("approval/grant", { toolName });
+	}
+	/**
+	* Whether a remembered grant covers this Agent's ask for the tool. The walk
+	* reads the Agent's session, then each live ancestor through `parentSession`;
+	* a vanished ancestor ends it, so an orphaned child never inherits a grant it
+	* cannot prove.
+	* @param agent - the asking Agent.
+	* @param toolName - the tool being asked about.
+	* @returns true when the Agent or a live ancestor holds the grant.
+	*/
+	isGranted(agent, toolName) {
+		let current = agent;
+		for (;;) {
+			if (this.grantedIn(current.session, toolName)) return true;
+			const parentId = current.session.header.parentSession;
+			if (parentId === void 0) return false;
+			const parent = this.ctx.get("agents")?.get(parentId);
+			if (parent === void 0) return false;
+			current = parent;
+		}
+	}
+	/**
+	* Read one session's own grants without walking its lineage.
+	* @param session - session whose log supplies the grants.
+	* @param toolName - tool whose grant is sought.
+	* @returns whether this session recorded a grant for the tool.
+	*/
+	grantedIn(session, toolName) {
+		for (let seq = session.seq - 1; seq >= 0; seq -= 1) {
+			const event = session.eventAt(SessionSeq(seq));
+			if (event?.type === "approval/grant" && event.data.toolName === toolName) return true;
+		}
+		return false;
+	}
+	/**
+	* The session's effective policy: its projected override, else the
+	* configured default (the schema already defaulted an omitted policy to
+	* `'ask'`; the `??` only narrows the optional-input TYPE).
+	* @param session - the exact accepted session whose policy applies.
+	* @returns the policy every ask for this session resolves under right now.
+	*/
+	effectivePolicy(session) {
+		return this.overrideOf(session) ?? this.config.policy ?? "ask";
+	}
+	/**
+	* Read the session override without applying the configured default.
+	* @param session - session whose log supplies the override.
+	* @returns the last logged policy, or `undefined` without one.
+	*/
+	overrideOf(session) {
+		return this.approvalStateOf(session).policy ?? void 0;
+	}
+	approvalStateOf(session) {
+		return this.approvalProjectionHandle.stateOf(session);
+	}
+	/**
+	* Dispatch the waterfall, contained and raced against the request signal.
+	* @param req - the borrowed public request.
+	* @param session - the request agent's session used for policy lookup.
+	* @returns the normalized closed outcome.
+	*/
+	async decide(req, session) {
+		const signal = req.signal;
+		if (signal?.aborted) return "cancelled";
+		if (this.effectivePolicy(session) === "never") return "rejected";
+		if (this.isGranted(req.agent, req.toolName)) return "allowed-once";
+		const answer = Promise.resolve().then(() => this.ctx.waterfall(scopeTarget(req.agent, req.agent), "approval/request", req, () => Promise.resolve("unavailable"))).then((outcome) => OUTCOMES.includes(outcome) ? outcome : "unavailable", () => "unavailable");
+		if (signal === void 0) return answer;
+		return await new Promise((resolve) => {
+			const onAbort = () => {
+				signal.removeEventListener("abort", onAbort);
+				resolve("cancelled");
+			};
+			signal.addEventListener("abort", onAbort, { once: true });
+			answer.then((outcome) => {
+				signal.removeEventListener("abort", onAbort);
+				resolve(outcome);
+			});
+		});
+	}
+};
+//#endregion
+export { APPROVAL_POLICIES, ApprovalRequestId, ApprovalService, ApprovalService as default, setApprovalPolicy };

package/lib/types/index.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Service Definition for the approval capability seam, covering requests,
+ * cancellation, audit, per-session policy, and remembered per-tool grants.
+ * Missing answerers fail closed.
+ * @module @deepseek-ai/dsh-user-approval
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import { type ToolCallId } from '@deepseek-ai/dsh-llm';
+import type { ContextFormed } from '@deepseek-ai/dsh-llm';
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        'user-approval': {
+            kind: 'user-approval';
+        } & ContextFormed;
+    }
+}
+import { type Session } from '@deepseek-ai/dsh-session';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        approval: ApprovalService;
+    }
+}
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        /**
+         * The session's approval policy was switched — log-only, durable,
+         * replayable, never in the model transcript (the model learns the policy
+         * from the runtime-context snapshot and live switch notices). The LAST
+         * such event is the session's override.
+         * `source: 'delegation'` marks an override seeded into a child; an absent
+         * source is a runtime switch.
+         */
+        'approval/policy': {
+            policy: ApprovalPolicy;
+            /** Marks an override seeded into a child at delegation. */
+            source?: 'delegation';
+        };
+    }
+}
+import type { ApprovalOutcome, ApprovalRequestEvent } from './types.ts';
+export { ApprovalRequestId } from './types.ts';
+export type { ApprovalOutcome } from './types.ts';
+/**
+ * A session's approval policy — what happens to an {@link ApprovalService}
+ * ask BEFORE any interactive answerer sees it:
+ *
+ * - `'ask'` (the default) — delegate to the composed answerers; with none
+ *   composed the chain falls through to the fail-closed `'unavailable'`.
+ * - `'never'` — never prompt anyone: every ask resolves `'rejected'`
+ *   deterministically. The strict headless stance (CI, unattended runs) and
+ *   the policy whose outcome is knowable without asking.
+ */
+export type ApprovalPolicy = 'ask' | 'never';
+/** Every {@link ApprovalPolicy}, for option advertisement and runtime validation of untrusted policy strings. */
+export declare const APPROVAL_POLICIES: readonly ApprovalPolicy[];
+/**
+ * Append the sole durable representation of a session policy override. Invalid
+ * values throw before the log changes; projected state follows the committed record.
+ * @param session - the session the override belongs to.
+ * @param policy - the policy in effect until the next switch.
+ */
+export declare function setApprovalPolicy(session: Session, policy: ApprovalPolicy): void;
+/**
+ * Readonly same-process permission question. `callId` links to an already
+ * presented tool call, so arguments are not duplicated here.
+ */
+export interface ApprovalRequest extends ApprovalRequestEvent {
+    /**
+     * The agent on whose behalf the question is asked. Routes the question (a
+     * UI answerer only answers for agents it owns) and receives the audit
+     * events on its session log.
+     */
+    readonly agent: Agent;
+    /** The tool the question is about (presentation and audit). */
+    readonly toolName: string;
+    /**
+     * The exact tool call being decided, when the asker has one — lets a UI
+     * attach the prompt to the tool call it already streamed.
+     */
+    readonly callId?: ToolCallId;
+    /** The asker's human-readable explanation of WHY it is asking. */
+    readonly reason?: string;
+    /**
+     * Aborting withdraws the question: the request settles `'cancelled'`
+     * immediately and a late answer from a still-pending answerer is discarded.
+     */
+    readonly signal?: AbortSignal;
+}
+/** Plugin config. All optional — `static Config` supplies the defaults. */
+export interface Config {
+    /**
+     * The deployment's default {@link ApprovalPolicy} for sessions without an
+     * `approval/policy` override — `'ask'` delegates to the composed answerers
+     * (fail-closed with none); `'never'` auto-rejects every ask without
+     * prompting (the deterministic CI/unattended stance).
+     */
+    readonly policy?: ApprovalPolicy;
+}
+/**
+ * Approval service that applies session policy and remembered per-tool grants
+ * before answerers and logs every ask/outcome pair to the requesting session.
+ * It exposes deterministic policy changes to the model through the
+ * runtime-context snapshot and switch notices.
+ */
+export declare class ApprovalService extends Service {
+    config: Config;
+    static inject: string[];
+    static Config: z<Config>;
+    private approvalProjectionHandle;
+    constructor(ctx: Context, config: Config);
+    protected [Service.init](): Promise<void>;
+    /**
+     * Switch one live agent's policy and queue the transition for its next model
+     * step. Session initialization uses {@link setApprovalPolicy} directly
+     * because there is no previously visible policy to change.
+     * @param agent - the live agent whose policy is changing.
+     * @param policy - the new effective policy.
+     */
+    setPolicy(agent: Agent, policy: ApprovalPolicy): void;
+    /**
+     * Ask the composed answerers to decide one readonly same-process request.
+     * The service borrows the request, agent, session, and live signal directly.
+     * A remembered grant for the tool resolves the ask `allowed-once` before any
+     * answerer sees it. The request requires an open turn because the audit pair
+     * must be enclosed by the durable log's commit/replay boundary; an idle ask
+     * rejects before appending anything. The answerer phase always produces an
+     * outcome: an aborted signal yields `'cancelled'`, a missing or throwing answerer yields
+     * `'unavailable'` (fail closed), and a rogue non-vocabulary return value is
+     * normalized to `'unavailable'`. A failure that prevents either audit append
+     * from committing still rejects because returning an unlogged decision would
+     * violate the pair. Session contains post-commit observer failures, so an
+     * authoritative append cannot reject the request or suppress its matching
+     * audit event.
+     * @param req - the pending decision (agent, tool identity, reason, signal).
+     * @returns the closed outcome; `'allowed-once'` is the only grant.
+     * @throws when no turn is open or either audit event fails before the session
+     *   append commit point.
+     */
+    request(req: ApprovalRequest): Promise<ApprovalOutcome>;
+    /**
+     * Remember one tool's approval for a session and its live descendants. Every
+     * later ask for that tool resolves `allowed-once` without consulting an
+     * answerer while the effective policy is `ask`; `never` still rejects first.
+     * Recording nothing when the grant already exists keeps replay and repeated
+     * Always allow choices from growing the log.
+     * @param session - the session whose subtree the grant covers.
+     * @param toolName - the tool whose future asks the grant covers.
+     * @throws when the tool name is empty.
+     */
+    grant(session: Session, toolName: string): void;
+    /**
+     * Whether a remembered grant covers this Agent's ask for the tool. The walk
+     * reads the Agent's session, then each live ancestor through `parentSession`;
+     * a vanished ancestor ends it, so an orphaned child never inherits a grant it
+     * cannot prove.
+     * @param agent - the asking Agent.
+     * @param toolName - the tool being asked about.
+     * @returns true when the Agent or a live ancestor holds the grant.
+     */
+    isGranted(agent: Agent, toolName: string): boolean;
+    /**
+     * Read one session's own grants without walking its lineage.
+     * @param session - session whose log supplies the grants.
+     * @param toolName - tool whose grant is sought.
+     * @returns whether this session recorded a grant for the tool.
+     */
+    private grantedIn;
+    /**
+     * The session's effective policy: its projected override, else the
+     * configured default (the schema already defaulted an omitted policy to
+     * `'ask'`; the `??` only narrows the optional-input TYPE).
+     * @param session - the exact accepted session whose policy applies.
+     * @returns the policy every ask for this session resolves under right now.
+     */
+    effectivePolicy(session: Session): ApprovalPolicy;
+    /**
+     * Read the session override without applying the configured default.
+     * @param session - session whose log supplies the override.
+     * @returns the last logged policy, or `undefined` without one.
+     */
+    overrideOf(session: Session): ApprovalPolicy | undefined;
+    private approvalStateOf;
+    /**
+     * Dispatch the waterfall, contained and raced against the request signal.
+     * @param req - the borrowed public request.
+     * @param session - the request agent's session used for policy lookup.
+     * @returns the normalized closed outcome.
+     */
+    private decide;
+}
+export default ApprovalService;
+//# sourceMappingURL=index.d.ts.map