@openvulcan/dsh-vulcancode 0.0.0-stage → 0.4.0

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

@@ -0,0 +1,572 @@
+import path from 'node:path';
+import Schema from '@deepseek-ai/schemastery';
+import { AUTO_PRESET } from '@deepseek-ai/dsh-permission-presets';
+import { resolveDshHome } from '@deepseek-ai/dsh-home-paths';
+import { RUN_CODE_NAME } from '@deepseek-ai/dsh-tools';
+import { DecisionEngine, DecisionHome, DOWNLOAD_SOURCES, PACK_IDS, POLICY_VERSION, renderCall, } from '@openvulcan/vulcan-decision';
+import { translateCall } from './calls.js';
+import { decide, stageOf, wantsReview } from './decide.js';
+import { IntentStore, intentTool } from './intent.js';
+import { reviewCall } from './review.js';
+import { handle, Panel, ROUTE_PREFIX, ROUTES, ServiceAccount } from './panel.js';
+import { RecordStore } from './records.js';
+import { installSessionState, MAX_PROMPT_CHARS } from './session-state.js';
+export { PROJECTION_KEY, REVIEW_PROMPT_COMMAND, REVIEW_PROMPT_RECORD, UNATTENDED_COMMAND, UNATTENDED_RECORD, } from './session-state.js';
+export const name = 'vulcan-decision-guard';
+export const inject = ['llm', 'permissionPresets', 'sessionProjections', 'sessions', 'tools', 'workingDirectory'];
+/** Longest approval countdown the settings accept, in seconds. */
+const MAX_ASK_TIMEOUT = 3600;
+export const Config = Schema.object({
+    mode: Schema.union(['auto-preset', 'standalone'])
+        .default('auto-preset')
+        .description('auto-preset: appears as the Auto permission preset. standalone: judges every session on top of its preset.')
+        .volatile(),
+    backend: Schema.union(['cloud', 'local'])
+        .default('cloud')
+        .description('cloud: OpenVulcan judges calls after you sign in. local: an installed model runs on this machine.')
+        .volatile(),
+    cloudModel: Schema.string()
+        .default('')
+        .description('Cloud decision model id; empty uses the first model OpenVulcan lists for the account.')
+        .volatile(),
+    cloudEndpoint: Schema.string()
+        .description('Cloud endpoint id to always use; omitted uses the fastest measured one.')
+        .volatile(),
+    localPack: Schema.union(PACK_IDS)
+        .description('Runtime pack that runs the local model.')
+        .volatile(),
+    localModel: Schema.string()
+        .description('Installed local model id.')
+        .volatile(),
+    downloadSource: Schema.union(DOWNLOAD_SOURCES)
+        .default('official')
+        .description('Where runtime packs download from: official hosts, or cn mirrors.')
+        .volatile(),
+    review: Schema.union(['session', 'custom', 'off'])
+        .default('session')
+        .description('LLM review of calls the decision model did not allow. session: the session model. custom: reviewProvider and reviewModel. off: no review.')
+        .volatile(),
+    reviewProvider: Schema.string()
+        .description('Provider of the review model when review is custom.')
+        .volatile(),
+    reviewModel: Schema.string()
+        .description('Review model when review is custom.')
+        .volatile(),
+    allowRules: Schema.string().role('textarea').default('')
+        .description('Natural-language rules for calls the LLM review should allow.')
+        .volatile(),
+    denyRules: Schema.string().role('textarea').default('')
+        .description('Natural-language rules for calls the LLM review should deny; the user is still asked when present.')
+        .volatile(),
+    forbidRules: Schema.string().role('textarea').default('')
+        .description('Natural-language rules for calls the LLM review refuses without asking anyone.')
+        .volatile(),
+    llmOverridesBlock: Schema.boolean()
+        .default(false)
+        .description('Whether calls the decision model blocks also go to the LLM review, which may then allow them.')
+        .volatile(),
+    reviewPrompt: Schema.string().role('textarea').max(MAX_PROMPT_CHARS).default('')
+        .description('Default additional guidance the LLM review follows while the user is present; a session may replace it.')
+        .volatile(),
+    unattendedPolicy: Schema.string().role('textarea').max(MAX_PROMPT_CHARS).default('')
+        .description('Deny policy offered when a session turns unattended mode on: what must never run while the user is away.')
+        .volatile(),
+    recordDecisions: Schema.boolean()
+        .default(false)
+        .description('Keep a local decision log with the original call arguments, in the plugin data directory.')
+        .volatile(),
+    askTimeout: Schema.natural().max(MAX_ASK_TIMEOUT)
+        .default(0)
+        .description('Seconds an approval prompt waits before the call is refused; 0 waits for the user.')
+        .volatile(),
+    crossProjectWrites: Schema.union(['allow', 'review'])
+        .default('allow')
+        .description('Ordinary writes outside the project: allow them, or ask first.')
+        .volatile(),
+    databaseReset: Schema.union(['confirm', 'allow'])
+        .default('confirm')
+        .description('Database drops, truncations and unrestricted data writes: confirm first, or allow.')
+        .volatile(),
+    projectReset: Schema.union(['confirm', 'allow'])
+        .default('confirm')
+        .description('Deleting or resetting the whole current project or its history: confirm first, or allow.')
+        .volatile(),
+});
+/** Settings namespace of dsh's locale plugin, whose `preference` is the chosen interface language. */
+const LOCALE_SETTINGS = 'locale';
+/** Preset that sessions still on `auto` move to when the guard is removed. */
+const FALLBACK_PRESET = 'workspace-write';
+/** Structured error identity of a final denial. */
+const DENIED_INFO = { name: 'VulcanDecisionDeniedError', code: 'VULCAN_DECISION_DENIED' };
+/**
+ * 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 const PROMPT_KEY = 'x-vulcan-decision';
+/** Install the Vulcan Decision gate and, in `auto-preset` mode, the Auto preset. */
+export async function apply(ctx, config) {
+    // Retain the injected services while this context drains on disposal.
+    const permissionPresets = ctx.permissionPresets;
+    const sessions = ctx.sessions;
+    const llm = ctx.llm;
+    const tools = ctx.tools;
+    const account = new ServiceAccount(() => ctx.get('openvulcanAccount'));
+    const engine = new DecisionEngine({ home: new DecisionHome(path.join(resolveDshHome(), 'vulcan-decision')), account });
+    const intents = new IntentStore();
+    const lifecycle = new AbortController();
+    let accepting = true;
+    let releasing = false;
+    let ownsAuto = false;
+    const sessionState = await installSessionState(ctx);
+    const records = new RecordStore(engine.home);
+    /** Append one finished call off the gate's path; a failure is only logged. */
+    const keep = (record) => {
+        setImmediate(() => {
+            try {
+                records.append(record);
+            }
+            catch (error) {
+                ctx.logger.warn(`cannot keep a decision record: ${messageOf(error)}`);
+            }
+        });
+    };
+    const governs = (exec) => {
+        const agent = exec.agent;
+        if (agent === undefined)
+            return false;
+        // The outer run_code transport is not an action; its inner tool calls are judged.
+        if (exec.parent === undefined && exec.name === RUN_CODE_NAME)
+            return false;
+        if (config.mode.get() === 'standalone')
+            return true;
+        return ownsAuto && permissionPresets.current(agent.session) === AUTO_PRESET;
+    };
+    /** Nobody can be asked: the session is marked unattended, or its approval policy never asks. */
+    const unattended = (agent) => {
+        if (sessionState(agent.session).unattended)
+            return true;
+        const approval = ctx.get('approval');
+        return approval !== undefined && (approval.overrideOf(agent.session) ?? approval.config.policy ?? 'ask') === 'never';
+    };
+    const options = () => ({
+        cross_project_writes: config.crossProjectWrites.get(),
+        database_reset: config.databaseReset.get(),
+        project_reset: config.projectReset.get(),
+    });
+    const engineSettings = () => {
+        const pack = config.localPack.get();
+        const model = config.localModel.get();
+        const endpoint = config.cloudEndpoint.get();
+        return {
+            backend: config.backend.get(),
+            cloudModel: config.cloudModel.get(),
+            ...endpoint === undefined || endpoint === '' ? {} : { cloudEndpoint: endpoint },
+            ...pack === undefined || model === undefined || model === '' ? {} : { local: { pack, model } },
+            options: options(),
+        };
+    };
+    const panel = new Panel(engine, {
+        engine: engineSettings, downloadSource: () => config.downloadSource.get(), accountPlugin: () => account.available(),
+    }, records);
+    /**
+     * The user's own text the review reads: the session's review prompt, else the system default,
+     * while attended; the deny policy the session confirmed while unattended. A session that never
+     * asks because of its approval policy, not the unattended switch, reads the default deny policy.
+     */
+    const reviewText = (agent, attended) => {
+        const state = sessionState(agent.session);
+        if (attended)
+            return state.reviewPrompt ?? config.reviewPrompt.get();
+        return state.unattended ? state.denyPolicy : config.unattendedPolicy.get();
+    };
+    /**
+     * The interface language the user chose in dsh's settings, or undefined when it follows the
+     * browser, which the Host cannot see.
+     */
+    const interfaceLanguage = () => {
+        const descriptor = ctx.get('settings')?.describe().find(item => item.ns === LOCALE_SETTINGS);
+        const value = descriptor?.value;
+        const preference = typeof value === 'object' && value !== null ? value['preference'] : undefined;
+        return typeof preference === 'string' && preference !== '' ? preference : undefined;
+    };
+    /** The provider and model that review this agent's calls. */
+    const reviewRoute = (agent) => {
+        if (config.review.get() === 'custom') {
+            const provider = config.reviewProvider.get();
+            const model = config.reviewModel.get();
+            return provider === undefined || model === undefined || provider === '' || model === ''
+                ? 'no review model is chosen in the settings'
+                : { provider, model };
+        }
+        const route = agent.session.requestHeader()?.config;
+        return route === undefined ? 'the session has no model route to review with' : { provider: route.provider, model: route.model };
+    };
+    const gate = async (exec, signal) => {
+        // `governs` established that the call has an agent.
+        const agent = exec.agent;
+        const judgedAtMs = Date.now();
+        const project = await ctx.workingDirectory.ensure(agent, signal).catch(() => undefined);
+        const translation = translateCall(exec.name, exec.arguments, project);
+        if (translation.kind === 'allow')
+            return 'run';
+        // The statement belongs to this call whatever happens to it.
+        const intent = intents.take(agent.session.id, exec.name);
+        const settings = engineSettings();
+        const decisionOptions = settings.options;
+        const call = { ...project === undefined ? {} : { project }, tool: translation.tool, arguments: translation.arguments };
+        const judgeStarted = performance.now();
+        const first = await abortable(engine.judge(call, settings), signal).then(verdict => ({ kind: 'verdict', verdict }), (error) => ({ kind: 'error', message: messageOf(error) }));
+        if (signal.aborted)
+            return 'cancel';
+        const judgeMs = performance.now() - judgeStarted;
+        const situation = {
+            attended: !unattended(agent),
+            llm: config.review.get() !== 'off',
+            llmOverridesBlock: config.llmOverridesBlock.get(),
+        };
+        let review;
+        // The record is built only when the log is on, since it renders the call again.
+        const log = (ending) => {
+            if (!config.recordDecisions.get())
+                return;
+            keep({
+                judgedAtMs,
+                sessionId: agent.session.id,
+                ...project === undefined ? {} : { workspaceRoot: project },
+                toolName: exec.name,
+                arguments: JSON.stringify(exec.arguments) ?? 'null',
+                attended: situation.attended,
+                judge: judgeOf(first, judgeMs, settings, call),
+                ...review === undefined ? {} : { review },
+                outcome: ending,
+            });
+        };
+        const stage = stageOf(first);
+        if (stage === undefined)
+            return { outcome: { kind: 'run' }, intent, log: () => { log('judge_allowed'); } };
+        let second = { kind: 'skipped' };
+        if (wantsReview(stage, situation)) {
+            const route = reviewRoute(agent);
+            const reviewStarted = performance.now();
+            second = typeof route === 'string'
+                ? { kind: 'error', message: route }
+                : await reviewCall(llm, {
+                    provider: route.provider,
+                    model: route.model,
+                    attended: situation.attended,
+                    language: interfaceLanguage(),
+                    project,
+                    options: decisionOptions,
+                    rules: { allow: config.allowRules.get(), deny: config.denyRules.get(), forbid: config.forbidRules.get() },
+                    prompt: reviewText(agent, situation.attended),
+                    stage,
+                    tool: exec.name,
+                    arguments: exec.arguments,
+                    intent,
+                    history: agent.session.deriveMessages(),
+                }, signal);
+            if (signal.aborted)
+                return 'cancel';
+            review = reviewOf(second, performance.now() - reviewStarted);
+        }
+        const outcome = decide(exec.name, first, second, situation);
+        // A run or a refusal was settled here; only a question's ending is known later.
+        const settled = outcome.kind === 'run'
+            ? 'review_allowed'
+            : outcome.kind === 'deny'
+                ? second.kind === 'forbid' || second.kind === 'deny' || second.kind === 'review' ? 'review_denied' : 'unattended_denied'
+                : undefined;
+        return {
+            outcome,
+            intent,
+            log: (ending) => {
+                const kept = settled ?? ending;
+                if (kept !== undefined)
+                    log(kept);
+            },
+        };
+    };
+    /** Ask the user through dsh's approval service, refusing the call when the countdown runs out. */
+    const askUser = async (exec, ask, intent, signal) => {
+        const approval = ctx.get('approval');
+        if (approval === undefined) {
+            return { decision: denied(`${ask.reason}. No approval channel is available, so the call was not executed.`), ending: 'not_asked' };
+        }
+        const seconds = config.askTimeout.get();
+        const countdown = seconds > 0 ? AbortSignal.timeout(seconds * 1000) : undefined;
+        const payload = {
+            v: 1,
+            ...ask.detail,
+            ...intent === undefined ? {} : { intent },
+            preview: previewOf(exec.arguments),
+            ...countdown === undefined ? {} : { timeoutMs: seconds * 1000 },
+        };
+        let result;
+        try {
+            result = await approval.request({
+                agent: exec.agent,
+                toolName: exec.name,
+                callId: exec.callId,
+                reason: ask.reason,
+                displayReason: { ...ask.display, [PROMPT_KEY]: JSON.stringify(payload) },
+                signal: countdown === undefined ? signal : AbortSignal.any([signal, countdown]),
+            });
+        }
+        catch (error) {
+            return { decision: denied(`${ask.reason}. The user could not be asked (${messageOf(error)}), so the call was not executed.`), ending: 'not_asked' };
+        }
+        if (signal.aborted)
+            return { decision: { kind: 'cancel' } };
+        switch (result) {
+            case 'allowed-once':
+                return { decision: { kind: 'allow' }, ending: 'user_allowed' };
+            case 'rejected':
+                return { decision: denied(`The user rejected tool "${exec.name}". The call was not executed.`), ending: 'user_denied' };
+            case 'cancelled':
+                return countdown?.aborted === true
+                    ? { decision: denied(`${ask.reason}. Nobody answered the approval prompt within ${seconds} seconds, so the call was not executed.`), ending: 'approval_expired' }
+                    : { decision: denied(`${ask.reason}. The approval prompt was withdrawn, so the call was not executed.`), ending: 'not_asked' };
+            case 'unavailable':
+                return { decision: denied(`${ask.reason}. No approval channel answered, so the call was not executed.`), ending: 'not_asked' };
+        }
+    };
+    let stopIntentTool;
+    /** The intent tool is offered while the LLM review is on. */
+    const syncIntentTool = () => {
+        const wanted = accepting && config.review.get() !== 'off';
+        if (wanted && stopIntentTool === undefined) {
+            stopIntentTool = tools.register(intentTool(intents, exec => governs(exec) && config.review.get() !== 'off'));
+        }
+        else if (!wanted && stopIntentTool !== undefined) {
+            stopIntentTool();
+            stopIntentTool = undefined;
+            intents.clear();
+        }
+    };
+    let stopAuto;
+    let claiming = false;
+    let reportedHeld = false;
+    /**
+     * Register `auto` unless another integration (usually Auto review) already holds it. Called at
+     * start, whenever the catalog changes and when the mode switches to `auto-preset`, so the slot is
+     * taken once the other integration leaves.
+     */
+    const claimAuto = () => {
+        if (config.mode.get() !== 'auto-preset' || !accepting || releasing || stopAuto !== undefined || claiming)
+            return;
+        if (permissionPresets.catalog().options.some(option => option.value === AUTO_PRESET)) {
+            if (!reportedHeld) {
+                reportedHeld = true;
+                ctx.logger.warn('the Auto permission preset is held by another integration, usually Auto review; Vulcan Decision takes it once that integration is disabled');
+            }
+            return;
+        }
+        claiming = true;
+        try {
+            const stop = permissionPresets.registerAuto(() => {
+                if (!accepting || releasing)
+                    throw new Error('vulcan-decision-guard: the Auto preset is being withdrawn');
+            });
+            ownsAuto = true;
+            reportedHeld = false;
+            stopAuto = async () => {
+                ownsAuto = false;
+                await stop();
+            };
+        }
+        catch (error) {
+            // A concurrent registration won the slot; the plugin keeps loading.
+            ctx.logger.warn(`cannot register the Auto permission preset: ${messageOf(error)}`);
+        }
+        finally {
+            claiming = false;
+        }
+    };
+    /** Move sessions still on `auto` to the fallback preset, then withdraw the registration. */
+    const releaseAuto = async () => {
+        const stop = stopAuto;
+        if (stop === undefined || releasing)
+            return;
+        releasing = true;
+        try {
+            for (const session of sessions.list()) {
+                if (permissionPresets.current(session) === AUTO_PRESET)
+                    permissionPresets.set(session, FALLBACK_PRESET);
+            }
+            stopAuto = undefined;
+            await stop();
+        }
+        finally {
+            releasing = false;
+        }
+    };
+    /** Apply a settings change that affects what is registered. */
+    const syncSettings = () => {
+        syncIntentTool();
+        if (config.mode.get() === 'auto-preset') {
+            claimAuto();
+            return;
+        }
+        releaseAuto().catch((error) => {
+            ctx.logger.warn(`cannot withdraw the Auto permission preset: ${messageOf(error)}`);
+        });
+    };
+    // A new sign-in or a sign-out invalidates the endpoints measured for the previous account.
+    ctx.inject(['openvulcanAccount'], (child) => {
+        child.effect(() => child.openvulcanAccount.onChange(() => { engine.cloud.reset(); }));
+    });
+    // The settings panel's routes live inside dsh's authenticated connection, when there is one.
+    ctx.inject(['connection'], (child) => {
+        for (const [method, route, handler] of ROUTES) {
+            child.effect(() => child.connection.fetch.register({
+                path: `${ROUTE_PREFIX}${route}`,
+                methods: [method],
+                requestBody: 'buffered',
+                fetch: request => handle(panel, handler, request),
+            }));
+        }
+    });
+    // This plugin ships its own page under Settings › Auto approval, so schema-generated pages are turned off.
+    ctx.inject(['settings'], (child) => {
+        child.effect(() => child.settings.configure({ auto: false }, ctx.fiber));
+    });
+    ctx.effect(function* () {
+        const stopListener = ctx.on('tools/pre-execute', async (exec, next) => {
+            if (!governs(exec))
+                return next();
+            if (!accepting || lifecycle.signal.aborted)
+                return { kind: 'cancel' };
+            const signal = AbortSignal.any([exec.signal, lifecycle.signal]);
+            const gated = await gate(exec, signal);
+            if (gated === 'cancel')
+                return { kind: 'cancel' };
+            if (gated === 'run')
+                return next();
+            const { outcome, intent, log } = gated;
+            switch (outcome.kind) {
+                case 'run':
+                    log();
+                    return next();
+                case 'deny':
+                    log();
+                    return denied(outcome.reason);
+                case 'ask': {
+                    // A later listener's denial, cancellation or own question takes precedence over asking.
+                    const downstream = await next();
+                    if (downstream.kind !== 'allow') {
+                        if (downstream.kind === 'deny')
+                            log('host_denied');
+                        return downstream;
+                    }
+                    const settled = await askUser(exec, outcome, intent, signal);
+                    if (settled.ending !== undefined)
+                        log(settled.ending);
+                    return settled.decision;
+                }
+            }
+        }, { prepend: true });
+        yield stopListener;
+        yield ctx.on('permission-presets/catalog-changed', claimAuto);
+        yield ctx.on('loader/volatile-update', syncSettings);
+        claimAuto();
+        syncIntentTool();
+        // Measure the cloud endpoints at start and again once a measurement is older than its interval.
+        const measure = () => {
+            if (config.backend.get() === 'cloud')
+                panel.endpoints().catch(() => { });
+        };
+        measure();
+        const measuring = setInterval(measure, 60_000);
+        yield () => clearInterval(measuring);
+        // Load the local model now so the first tool call does not wait for it.
+        const warm = engineSettings();
+        if (warm.backend === 'local' && warm.local !== undefined) {
+            engine.local.warm(warm.local).catch((error) => {
+                ctx.logger.warn(`local decision model did not load: ${messageOf(error)}`);
+            });
+        }
+        // Disposers start in reverse order, so this runs first.
+        yield async () => {
+            accepting = false;
+            syncIntentTool();
+            try {
+                await releaseAuto();
+            }
+            finally {
+                lifecycle.abort(new Error('vulcan-decision-guard integration disposed'));
+                panel.close();
+                engine.stop();
+            }
+        };
+    }, 'vulcan-decision-guard lifecycle');
+}
+/** Longest call preview the approval card shows. */
+const MAX_PREVIEW_CHARS = 1200;
+/** A shell command as it was written, otherwise the arguments as JSON. */
+function previewOf(args) {
+    const command = typeof args === 'object' && args !== null ? args['command'] : undefined;
+    const text = typeof command === 'string' ? command : JSON.stringify(args, null, 2) ?? '';
+    return text.length <= MAX_PREVIEW_CHARS ? text : `${text.slice(0, MAX_PREVIEW_CHARS)}…`;
+}
+/** Settle with `promise`, or reject as soon as `signal` aborts; the work itself is not stopped. */
+function abortable(promise, signal) {
+    if (signal.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        const abort = () => reject(signal.reason);
+        signal.addEventListener('abort', abort, { once: true });
+        promise.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort));
+    });
+}
+/** The decision model's part of a record; the trace is kept whenever the call renders. */
+function judgeOf(first, elapsedMs, settings, call) {
+    let rendered;
+    try {
+        rendered = renderCall(call);
+    }
+    catch {
+        rendered = undefined;
+    }
+    const verdict = first.kind === 'verdict' ? first.verdict : undefined;
+    const model = verdict?.model ?? (settings.backend === 'cloud' ? settings.cloudModel : settings.local?.model ?? '');
+    return {
+        ...verdict === undefined ? { error: first.kind === 'error' ? first.message : '' } : { label: verdict.decision },
+        ...verdict?.reason_code === undefined ? {} : { reasonCode: verdict.reason_code },
+        elapsedMs: Math.round(elapsedMs),
+        ...rendered === undefined
+            ? {}
+            : {
+                trace: {
+                    backend: settings.backend,
+                    model,
+                    ...verdict === undefined ? {} : { via: verdict.via },
+                    policyVersion: POLICY_VERSION,
+                    settings: settings.options,
+                    rendered,
+                    ...verdict?.logits === undefined ? {} : { logits: verdict.logits },
+                    ...verdict?.input_tokens === undefined ? {} : { inputTokens: verdict.input_tokens },
+                },
+            },
+    };
+}
+/** The review LLM's part of a record. */
+function reviewOf(second, elapsedMs) {
+    const elapsed = Math.round(elapsedMs);
+    switch (second.kind) {
+        case 'skipped':
+            return undefined;
+        case 'error':
+            return { error: second.message, elapsedMs: elapsed };
+        case 'allow':
+            return { verdict: 'allow', elapsedMs: elapsed };
+        default:
+            return { verdict: second.kind, ...second.reason === undefined ? {} : { reason: second.reason }, elapsedMs: elapsed };
+    }
+}
+function denied(reason) {
+    return { kind: 'deny', reason, info: DENIED_INFO };
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

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

@@ -0,0 +1,22 @@
+/**
+ * The intent tool: the agent states the purpose of its next call of a tool, and that statement
+ * goes to the LLM review and the approval prompt with the call. It does not go to the decision
+ * model, and it never authorizes anything by itself; the reviewer is told so.
+ *
+ * Statements are kept in memory per session until the next judged call of the named tool takes
+ * them. One per tool: a newer statement replaces an older one.
+ */
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import { type ToolExecution } from '@deepseek-ai/dsh-tools';
+/** Pending statements by session, then by tool name. */
+export declare class IntentStore {
+    #private;
+    put(session: SessionId, tool: string, purpose: string): void;
+    /** Remove and return the statement for this session's next call of `tool`. */
+    take(session: SessionId, tool: string): string | undefined;
+    clear(): void;
+}
+/** Whether the guard reviews this execution's calls with an LLM right now. */
+export type ReviewsWithLlm = (exec: ToolExecution) => boolean;
+/** The tool definition; `reviews` decides whether a statement is kept or not needed. */
+export declare function intentTool(store: IntentStore, reviews: ReviewsWithLlm): import("@deepseek-ai/dsh-tools").ToolDefinition;

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

@@ -0,0 +1,77 @@
+/**
+ * The intent tool: the agent states the purpose of its next call of a tool, and that statement
+ * goes to the LLM review and the approval prompt with the call. It does not go to the decision
+ * model, and it never authorizes anything by itself; the reviewer is told so.
+ *
+ * Statements are kept in memory per session until the next judged call of the named tool takes
+ * them. One per tool: a newer statement replaces an older one.
+ */
+import { defineTool } from '@deepseek-ai/dsh-tools';
+import { INTENT_TOOL } from './decide.js';
+const MAX_PURPOSE_CHARS = 2000;
+/** Pending statements by session, then by tool name. */
+export class IntentStore {
+    #pending = new Map();
+    put(session, tool, purpose) {
+        let tools = this.#pending.get(session);
+        if (tools === undefined) {
+            tools = new Map();
+            this.#pending.set(session, tools);
+        }
+        tools.set(tool, purpose);
+    }
+    /** Remove and return the statement for this session's next call of `tool`. */
+    take(session, tool) {
+        const tools = this.#pending.get(session);
+        const purpose = tools?.get(tool);
+        if (purpose === undefined)
+            return undefined;
+        tools.delete(tool);
+        if (tools.size === 0)
+            this.#pending.delete(session);
+        return purpose;
+    }
+    clear() {
+        this.#pending.clear();
+    }
+}
+/** The tool definition; `reviews` decides whether a statement is kept or not needed. */
+export function intentTool(store, reviews) {
+    return defineTool({
+        name: INTENT_TOOL,
+        description: 'Explain to the permission reviewer (Vulcan Decision) why your next call of a tool is needed and what it will do. '
+            + 'Use it before a call the reviewer may question, or after the review denied a call you still need, then make the call. '
+            + 'The explanation goes to the reviewer and is shown to the user with that call; it does not grant permission by itself, '
+            + 'so describe the real purpose and effect.',
+        parameters: {
+            tool: { type: 'string', required: true, description: 'Exact name of the tool you will call next, for example "bash".' },
+            purpose: { type: 'string', required: true, description: 'Why the call is needed and what it will change, in one or two sentences.' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    recorded: { type: 'boolean', required: true },
+                },
+            },
+            render: (args, value) => [{
+                    type: 'text',
+                    text: value.recorded
+                        ? `Recorded. The reviewer will see this purpose with your next "${args.tool}" call; make that call now.`
+                        : 'This session\'s calls are not reviewed by an LLM, so no explanation is needed; make the call directly.',
+                }],
+        },
+        execute(args, exec) {
+            const agent = exec.agent;
+            if (agent === undefined || !reviews(exec))
+                return Promise.resolve({ recorded: false });
+            const purpose = args.purpose.trim();
+            if (purpose === '')
+                throw new Error('purpose must not be empty');
+            store.put(agent.session.id, args.tool.trim(), purpose.length <= MAX_PURPOSE_CHARS ? purpose : purpose.slice(0, MAX_PURPOSE_CHARS));
+            return Promise.resolve({ recorded: true });
+        },
+        presentCall: args => ({ card: 'generic', title: `Explain the next ${args.tool} call`, kind: 'other', rawInput: args.purpose }),
+    });
+}