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

package/lib/types/index.js

@@ -0,0 +1,290 @@
+/**
+ * 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 { randomUUID } from 'node:crypto';
+import { Service } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import { z as zod } from 'zod';
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { scopeTarget } from '@deepseek-ai/dsh-scope';
+import { SessionSeq } from '@deepseek-ai/dsh-session';
+import { ApprovalRequestId } from "./types.js";
+export { ApprovalRequestId } from "./types.js";
+/** 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. */
+export 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: zod.object({
+        policy: zod.enum(['ask', 'never']).nullable(),
+        turnOpen: zod.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.
+ */
+export 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.
+ */
+export class ApprovalService 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);
+        // Registration can finish after an unload has started. Do not add effects then.
+        if (this.ctx.fiber.uid === null)
+            return;
+        const effective = (agent) => this.effectivePolicy(agent.session);
+        // The complete current value travels after retained history, so switching
+        // policy does not rewrite the stable system-prompt cache prefix.
+        await this.ctx.inject(['systemPrompt'], (scope) => {
+            scope.systemPrompt.context({
+                name: 'approval:policy',
+                order: scope.systemPrompt.getContextOrder('APPROVAL_POLICY'),
+                text: (context) => {
+                    const agent = context.agent;
+                    // A bare assemble() (tests, diagnostics) has no session to state.
+                    if (agent === undefined)
+                        return '';
+                    const policy = effective(agent);
+                    return policy === '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 !== undefined ? { callId: req.callId } : {},
+            ...req.reason !== undefined ? { reason: req.reason } : {},
+        });
+        const outcome = await this.decide(req, session);
+        // A grant recorded while the answerer was deciding (the TUI's Always
+        // allow) covers this request too: mark the decision so the transcript and
+        // watch viewer can show that the tool will not prompt again.
+        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 === undefined)
+                return false;
+            const parent = this.ctx.get('agents')?.get(parentId);
+            if (parent === undefined)
+                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) {
+            // oxlint-disable-next-line typescript/no-deprecated -- Existing Session history read; migration deferred.
+            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 ?? undefined;
+    }
+    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';
+        // The 'never' policy is decided HERE, before any dispatch: a listener
+        // registered with `prepend: true` after this service mounts would sit
+        // ahead of any gate LISTENER, so a listener-shaped gate cannot keep the
+        // documented promise that 'never' rejects deterministically regardless
+        // of registration order — only the service's own request path can.
+        if (this.effectivePolicy(session) === 'never')
+            return 'rejected';
+        // A remembered grant is part of the session policy: it decides before any
+        // answerer so a UI that already answered Always allow never sees the ask.
+        if (this.isGranted(req.agent, req.toolName))
+            return 'allowed-once';
+        // Enter the promise chain BEFORE dispatching: a listener that throws
+        // SYNCHRONOUSLY (before its first await) must land in the same rejection
+        // path as an async one — `Promise.resolve(call())` would let it escape
+        // the containment into the caller.
+        const answer = Promise.resolve().then(() => this.ctx.waterfall(scopeTarget(req.agent, req.agent), 'approval/request', req, () => Promise.resolve('unavailable'))).then(
+        // Normalize a rogue (non-vocabulary) answerer return to the fail-closed
+        // outcome instead of leaking it into callers' closed-union switches.
+        outcome => OUTCOMES.includes(outcome) ? outcome : 'unavailable', 
+        // A throwing answerer must fail the QUESTION closed, not the caller's
+        // tool call open — the seam contains its callbacks.
+        () => 'unavailable');
+        if (signal === undefined)
+            return answer;
+        return await new Promise((resolve) => {
+            const onAbort = () => {
+                signal.removeEventListener('abort', onAbort);
+                resolve('cancelled');
+            };
+            signal.addEventListener('abort', onAbort, { once: true });
+            void answer.then((outcome) => {
+                signal.removeEventListener('abort', onAbort);
+                // After an abort won the race this resolve is a settled-promise no-op:
+                // the late answer is discarded by construction.
+                resolve(outcome);
+            });
+        });
+    }
+}
+export default ApprovalService;
+//# sourceMappingURL=index.js.map

package/lib/types/types.d.ts

@@ -0,0 +1,99 @@
+/**
+ * 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
+ */
+import type { Branded } from '@deepseek-ai/dsh-brand';
+import type { Scoped } from '@deepseek-ai/dsh-scope';
+import type { Agent } from '@deepseek-ai/dsh-agent/types';
+import type { ToolCallId } from '@deepseek-ai/dsh-llm/brand';
+/**
+ * Pairs one `approval/asked` audit event with its `approval/decided`.
+ * Service-issued (one fresh id per {@link ApprovalService.request} call).
+ */
+export type ApprovalRequestId = Branded<'ApprovalRequestId'>;
+/**
+ * Brand a string as an {@link ApprovalRequestId}.
+ * @param id - the raw id string to brand.
+ * @returns the same string carrying the brand.
+ */
+export declare function ApprovalRequestId(id: string): ApprovalRequestId;
+/**
+ * Closed approval outcomes: a one-shot grant, explicit rejection, withdrawn
+ * request, or unavailable answerer. Callers fail closed on `unavailable`.
+ */
+export type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable';
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        /**
+         * The session remembered one tool's approval — log-only state, not a
+         * surface event. Later asks for the same tool from this session or a live
+         * descendant resolve `allowed-once` without consulting an answerer while
+         * the effective policy is `ask`. Absence means no remembered grant.
+         */
+        'approval/grant': {
+            toolName: string;
+        };
+        /**
+         * An approval question was put to the answerer chain — log-only audit
+         * (like `hook/*`; NOT a surface event, carries no `surfaceOp`). `id` pairs
+         * it with the `approval/decided` that always follows; `toolName` is the
+         * tool the question is about, `callId` the exact tool call when the asker
+         * had one, `reason` the asker's human-readable explanation (e.g. a hook's
+         * permission-decision reason).
+         */
+        'approval/asked': {
+            id: ApprovalRequestId;
+            toolName: string;
+            callId?: ToolCallId;
+            reason?: string;
+        };
+        /**
+         * The outcome of a prior `approval/asked` (same `id`) — log-only audit.
+         * Exactly one per ask, appended when the outcome is known: a decision, a
+         * cancellation, or the fail-closed `'unavailable'`.
+         */
+        'approval/decided': {
+            id: ApprovalRequestId;
+            outcome: ApprovalOutcome;
+            /**
+             * The `allowed-once` outcome was covered by a remembered grant for the
+             * asked-about tool, so the same session would allow it again without a
+             * prompt. One-shot grants and non-grants omit this field.
+             */
+            remembered?: true;
+        };
+    }
+}
+/** Client-safe payload declared for the approval answerer waterfall. */
+export interface ApprovalRequestEvent {
+    /** Agent identity projected to the corresponding Client Context in transit. */
+    readonly agent: Agent;
+    /** Tool whose operation requires a decision. */
+    readonly toolName: string;
+    /** Exact tool call being decided, when available. */
+    readonly callId?: ToolCallId;
+    /** Human-readable reason supplied by the asker. */
+    readonly reason?: string;
+    /** Localized presentation only; never persisted in approval audit events. */
+    readonly displayReason?: {
+        readonly en: string;
+        readonly [locale: string]: string;
+    };
+    /** Cancellation lifetime of the pending request. */
+    readonly signal?: AbortSignal;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Events {
+        /**
+         * Ask composed answerers for one decision. Return an outcome to claim the
+         * request or call `next()` to delegate. Scope-filtered dispatch
+         * (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+         * @param req - pending approval request.
+         * @mode waterfall
+         */
+        'approval/request'(this: Scoped<Agent>, req: ApprovalRequestEvent, next: () => Promise<ApprovalOutcome>): Promise<ApprovalOutcome>;
+    }
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -0,0 +1,15 @@
+/**
+ * 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.
+ */
+export function ApprovalRequestId(id) {
+    return id;
+}
+//# sourceMappingURL=types.js.map

package/locale/de.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Benutzergenehmigungsdienst",
+    "description": "Fordern Sie vom Benutzer eine Betriebsberechtigung an und geben Sie das Genehmigungsergebnis zurück."
+  }
+}

package/locale/en.json

@@ -0,0 +1,5 @@
+{
+  "meta": {
+    "title": "user-approval"
+  }
+}

package/locale/es.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Servicio de aprobación de usuarios",
+    "description": "Solicite autorización de operación al usuario y devuelva el resultado de la aprobación."
+  }
+}

package/locale/fr.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Service d'approbation des utilisateurs",
+    "description": "Demander l'autorisation d'opération à l'utilisateur et renvoyer le résultat de l'approbation."
+  }
+}

package/locale/ja.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "ユーザー承認サービス",
+    "description": "操作の許可をユーザーに求め、今回の承認結果を返します。"
+  }
+}

package/locale/pt.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Serviço de aprovação de usuário",
+    "description": "Solicite autorização de operação ao usuário e retorne o resultado da aprovação."
+  }
+}

package/locale/ru.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Служба утверждения пользователей",
+    "description": "Запросить авторизацию операции у пользователя и вернуть результат утверждения."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "用户审批服务",
+    "description": "向用户请求操作授权，并返回本次审批结果。"
+  }
+}

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@fishwithcat/dsh-user-approval",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "User-approval seam (ctx.approval) for the DeepSeek Harness: one-shot permission decisions dispatched to composed answerers over the approval/request waterfall, fail-closed by default",
+  "version": "0.2.2-alpha.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/FishwithCat/deepseek-harness-tui",
+    "directory": "packages/interaction/user-approval"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json"
+  },
+  "files": [
+    "locale/*.json",
+    "lib/index.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-brand": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-llm": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-scope": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-session": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-system-prompt": "0.2.2-alpha.3",
+    "@deepseek-ai/cordis": "~4.0.6-alpha.2",
+    "@deepseek-ai/dsh-session-projection": "0.2.2-alpha.3"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "~3.18.6-alpha.2",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-brand": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-llm": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-scope": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-session": "0.2.2-alpha.3",
+    "@deepseek-ai/dsh-system-prompt": "0.2.2-alpha.3",
+    "@deepseek-ai/cordis": "~4.0.6-alpha.2",
+    "@deepseek-ai/dsh-session-projection": "0.2.2-alpha.3"
+  }
+}