@jsonstudio/llms 0.6.954 → 0.6.1164

package/dist/servertool/handlers/exec-command-guard.js

@@ -1,558 +1,10 @@
-import fs from 'node:fs/promises';
-import os from 'node:os';
-import path from 'node:path';
 import { registerServerToolHandler } from '../registry.js';
-import { cloneJson } from '../server-side-tools.js';
-import { buildEntryAwareFollowupPayload, dropToolByFunctionName, extractCapturedChatSeed } from './followup-request-builder.js';
-const FLOW_ID = 'exec_command_guard';
-const BASELINE_RULES = [
-    {
-        id: 'baseline-rm-rf-root',
-        reason: 'Destructive rm on filesystem root is not allowed',
-        regex: /(^|\s)(sudo\s+)?rm\b[^\n]*(\s|^)(-rf|-fr|--recursive)[^\n]*\s(--\s*)?(\/\s*$|\/\*\s*$)/i
-    },
-    {
-        id: 'baseline-rm-no-preserve-root',
-        reason: 'rm with --no-preserve-root is not allowed',
-        regex: /(^|\s)(sudo\s+)?rm\b[^\n]*--no-preserve-root\b/i
-    },
-    {
-        id: 'baseline-find-delete-root',
-        reason: 'find -delete on filesystem root is not allowed',
-        regex: /(^|\s)find\s+\/(\s|$)[^\n]*\s-delete(\s|$)/i
-    },
-    {
-        id: 'baseline-chmod-r-root',
-        reason: 'chmod -R on filesystem root is not allowed',
-        regex: /(^|\s)(sudo\s+)?chmod\b[^\n]*\s-R(\s|$)[^\n]*\s--?\s*\/(\s|$)/i
-    },
-    {
-        id: 'baseline-chown-r-root',
-        reason: 'chown -R on filesystem root is not allowed',
-        regex: /(^|\s)(sudo\s+)?chown\b[^\n]*\s-R(\s|$)[^\n]*\s--?\s*\/(\s|$)/i
-    },
-    {
-        id: 'baseline-disk-format',
-        reason: 'Disk/partition formatting commands are not allowed',
-        regex: /(^|\s)(sudo\s+)?(mkfs(\.|[a-z0-9_-]+)?|wipefs|fdisk|parted|sgdisk|shred)\b/i
-    },
-    {
-        id: 'baseline-dd-to-dev',
-        reason: 'dd writing to /dev is not allowed',
-        regex: /(^|\s)(sudo\s+)?dd\b[^\n]*\sof=\/dev\/[^\s]+/i
-    },
-    {
-        id: 'baseline-shutdown-reboot',
-        reason: 'System shutdown/reboot commands are not allowed',
-        regex: /(^|\s)(sudo\s+)?(shutdown|reboot|poweroff|halt|init)\b/i
-    }
-];
-const POLICY_CACHE = new Map();
-const POLICY_CACHE_TTL_MS = 3_000;
-const handler = async (ctx) => {
-    const toolCall = ctx.toolCall;
-    if (!toolCall) {
-        return null;
-    }
-    if (!ctx.options.reenterPipeline) {
-        return null;
-    }
-    const guardConfig = getExecCommandGuardConfig(ctx.adapterContext);
-    if (!guardConfig.enabled) {
-        return null;
-    }
-    const parsedArgs = parseToolArguments(toolCall);
-    const cmd = typeof parsedArgs.cmd === 'string' && parsedArgs.cmd.trim() ? parsedArgs.cmd.trim() : '';
-    const workdir = typeof parsedArgs.workdir === 'string' && parsedArgs.workdir.trim() ? parsedArgs.workdir.trim() : undefined;
-    if (!cmd) {
-        return null;
-    }
-    const decision = await evaluateExecCommandDeny({
-        cmd,
-        workdir,
-        policyFile: guardConfig.policyFile
-    });
-    if (!decision.blocked) {
-        return null;
-    }
-    const patched = injectExecCommandDeniedToolResult(ctx.base, toolCall, {
-        cmd,
-        workdir,
-        decision
-    });
-    const followupPayload = buildToolFollowupPayload(ctx.adapterContext, patched, ctx.options.entryEndpoint || ctx.adapterContext?.entryEndpoint || '/v1/chat/completions', {
-        dropToolName: 'exec_command'
-    });
-    if (!followupPayload) {
-        // Fail-closed: if we cannot perform reenter, do not intercept.
-        // (This should be rare because HubPipeline always provides capturedChatRequest.)
-        return null;
-    }
-    return {
-        chatResponse: patched,
-        execution: {
-            flowId: FLOW_ID,
-            followup: {
-                requestIdSuffix: ':exec_command_guard_followup',
-                payload: followupPayload
-            }
-        }
-    };
+const handler = async (_ctx) => {
+    // exec_command is executed by the client. ServerTool must not fabricate tool outputs
+    // or followups; client will run (or fail) and send the real tool_result in next request.
+    //
+    // Shape-only normalization is handled by tool-governor (validateToolCall + normalizedArgs)
+    // before the client receives the tool call.
+    return null;
 };
 registerServerToolHandler('exec_command', handler);
-function getExecCommandGuardConfig(adapterContext) {
-    const raw = adapterContext && typeof adapterContext === 'object'
-        ? adapterContext.execCommandGuard
-        : undefined;
-    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
-        return { enabled: false };
-    }
-    const cfg = raw;
-    const enabledRaw = cfg.enabled;
-    const enabled = enabledRaw === true ||
-        (typeof enabledRaw === 'string' && enabledRaw.trim().toLowerCase() === 'true') ||
-        (typeof enabledRaw === 'number' && enabledRaw === 1);
-    if (!enabled) {
-        return { enabled: false };
-    }
-    const policyFileRaw = cfg.policyFile;
-    const policyFile = typeof policyFileRaw === 'string' && policyFileRaw.trim() ? policyFileRaw.trim() : undefined;
-    return { enabled: true, ...(policyFile ? { policyFile } : {}) };
-}
-function parseToolArguments(toolCall) {
-    if (!toolCall.arguments || typeof toolCall.arguments !== 'string') {
-        return {};
-    }
-    try {
-        return JSON.parse(toolCall.arguments);
-    }
-    catch {
-        return {};
-    }
-}
-async function evaluateExecCommandDeny(options) {
-    const baseline = matchRegexRules(options.cmd, BASELINE_RULES);
-    if (baseline) {
-        return { blocked: true, ruleId: baseline.id, reason: baseline.reason, source: 'baseline', policyFile: options.policyFile };
-    }
-    const policyFile = typeof options.policyFile === 'string' && options.policyFile.trim() ? options.policyFile.trim() : '';
-    if (!policyFile) {
-        return { blocked: false };
-    }
-    const loaded = await loadPolicy(policyFile);
-    if (!loaded.policy) {
-        return {
-            blocked: false,
-            policyFile,
-            ...(loaded.error ? { policyNote: loaded.error } : {})
-        };
-    }
-    const combined = `${options.cmd}\nworkdir=${options.workdir ?? ''}`;
-    // Defaults: structured enforcement for common safety invariants (policy-controlled).
-    if (loaded.policy.denyOutsideProjectDestructive) {
-        const out = evaluateOutsideProjectDestructive({
-            cmd: options.cmd,
-            workdir: options.workdir,
-            allowedProjectRoots: loaded.policy.allowedProjectRoots
-        });
-        if (out) {
-            return {
-                blocked: true,
-                ruleId: out.id,
-                reason: out.reason,
-                source: 'policy-defaults',
-                policyFile
-            };
-        }
-    }
-    if (loaded.policy.gitSingleFileOnly) {
-        const out = evaluateGitSingleFileOnly(options.cmd);
-        if (out) {
-            return {
-                blocked: true,
-                ruleId: out.id,
-                reason: out.reason,
-                source: 'policy-defaults',
-                policyFile
-            };
-        }
-    }
-    if (loaded.policy.denyMassKill) {
-        const out = evaluateMassKill(options.cmd);
-        if (out) {
-            return {
-                blocked: true,
-                ruleId: out.id,
-                reason: out.reason,
-                source: 'policy-defaults',
-                policyFile
-            };
-        }
-    }
-    for (const rule of loaded.policy.rules) {
-        const targetText = rule.target === 'cmd+workdir' ? combined : options.cmd;
-        if (rule.regex.test(targetText)) {
-            return {
-                blocked: true,
-                ruleId: rule.id,
-                reason: rule.reason,
-                source: 'policy',
-                policyFile
-            };
-        }
-    }
-    return { blocked: false };
-}
-function matchRegexRules(cmd, rules) {
-    for (const rule of rules) {
-        try {
-            if (rule.regex.test(cmd)) {
-                return { id: rule.id, reason: rule.reason };
-            }
-        }
-        catch {
-            // ignore invalid regex evaluation
-        }
-    }
-    return null;
-}
-function injectExecCommandDeniedToolResult(base, toolCall, options) {
-    const cloned = cloneJson(base);
-    const existingOutputs = Array.isArray(cloned.tool_outputs)
-        ? cloned.tool_outputs
-        : [];
-    const payload = {
-        ok: false,
-        blocked: true,
-        tool: 'exec_command',
-        cmd: options.cmd,
-        ...(options.workdir ? { workdir: options.workdir } : {}),
-        ...(options.decision.ruleId ? { ruleId: options.decision.ruleId } : {}),
-        ...(options.decision.reason ? { reason: options.decision.reason } : {}),
-        ...(options.decision.source ? { source: options.decision.source } : {}),
-        ...(options.decision.policyFile ? { policyFile: options.decision.policyFile } : {}),
-        ...(options.decision.policyNote ? { policyNote: options.decision.policyNote } : {}),
-        guidance: 'Command execution is blocked by server policy. If you believe this is safe, adjust the exec_command deny policy file.'
-    };
-    cloned.tool_outputs = [
-        ...existingOutputs,
-        {
-            tool_call_id: toolCall.id,
-            name: 'exec_command',
-            content: JSON.stringify(payload)
-        }
-    ];
-    return cloned;
-}
-function buildToolFollowupPayload(adapterContext, chatResponse, entryEndpoint, options) {
-    const captured = adapterContext && typeof adapterContext === 'object'
-        ? adapterContext.capturedChatRequest
-        : undefined;
-    const seed = extractCapturedChatSeed(captured);
-    if (!seed) {
-        return null;
-    }
-    const assistantMessage = extractAssistantMessage(chatResponse);
-    if (!assistantMessage) {
-        return null;
-    }
-    const toolMessages = buildToolMessages(chatResponse);
-    if (!toolMessages.length) {
-        return null;
-    }
-    const reconstructed = [...seed.messages, assistantMessage, ...toolMessages];
-    const dropName = typeof options.dropToolName === 'string' ? options.dropToolName.trim() : '';
-    const filteredTools = dropToolByFunctionName(seed.tools, dropName);
-    return buildEntryAwareFollowupPayload({
-        entryEndpoint,
-        model: seed.model,
-        messages: reconstructed,
-        ...(filteredTools ? { tools: filteredTools } : {}),
-        ...(seed.parameters ? { parameters: seed.parameters } : {})
-    });
-}
-function extractAssistantMessage(chatResponse) {
-    const choices = Array.isArray(chatResponse.choices)
-        ? chatResponse.choices
-        : [];
-    if (!choices.length)
-        return null;
-    const firstChoice = choices[0] && typeof choices[0] === 'object' && !Array.isArray(choices[0])
-        ? choices[0]
-        : null;
-    if (!firstChoice)
-        return null;
-    const assistantMessage = firstChoice.message && typeof firstChoice.message === 'object'
-        ? firstChoice.message
-        : null;
-    return assistantMessage;
-}
-function buildToolMessages(chatResponse) {
-    const toolOutputs = Array.isArray(chatResponse.tool_outputs)
-        ? chatResponse.tool_outputs
-        : [];
-    const messages = [];
-    for (const entry of toolOutputs) {
-        if (!entry || typeof entry !== 'object' || Array.isArray(entry))
-            continue;
-        const record = entry;
-        const toolCallId = typeof record.tool_call_id === 'string' ? record.tool_call_id : undefined;
-        if (!toolCallId)
-            continue;
-        const name = typeof record.name === 'string' && record.name.trim() ? record.name.trim() : 'exec_command';
-        const rawContent = record.content;
-        let contentText;
-        if (typeof rawContent === 'string') {
-            contentText = rawContent;
-        }
-        else {
-            try {
-                contentText = JSON.stringify(rawContent ?? {});
-            }
-            catch {
-                contentText = String(rawContent ?? '');
-            }
-        }
-        messages.push({
-            role: 'tool',
-            tool_call_id: toolCallId,
-            name,
-            content: contentText
-        });
-    }
-    return messages;
-}
-function expandUserPath(inputPath) {
-    const p = inputPath.trim();
-    if (!p)
-        return p;
-    if (p === '~')
-        return os.homedir();
-    if (p.startsWith('~/') || p.startsWith('~\\')) {
-        return path.join(os.homedir(), p.slice(2));
-    }
-    return p;
-}
-async function loadPolicy(policyFile) {
-    const resolved = path.resolve(expandUserPath(policyFile));
-    const now = Date.now();
-    const cached = POLICY_CACHE.get(resolved);
-    if (cached && now - cached.loadedAt <= POLICY_CACHE_TTL_MS) {
-        if (cached.inFlight) {
-            await cached.inFlight;
-        }
-        return { policy: cached.policy, error: cached.error };
-    }
-    const state = cached ?? { loadedAt: 0 };
-    let inFlightResolve;
-    const inFlight = new Promise((resolve) => {
-        inFlightResolve = resolve;
-    });
-    POLICY_CACHE.set(resolved, { ...state, loadedAt: now, inFlight });
-    try {
-        const st = await fs.stat(resolved);
-        const mtimeMs = typeof st.mtimeMs === 'number' ? st.mtimeMs : undefined;
-        if (cached && cached.policy && typeof cached.mtimeMs === 'number' && typeof mtimeMs === 'number' && cached.mtimeMs === mtimeMs) {
-            POLICY_CACHE.set(resolved, { loadedAt: now, mtimeMs, policy: cached.policy });
-            return { policy: cached.policy };
-        }
-        const raw = await fs.readFile(resolved, 'utf8');
-        const parsed = raw.trim() ? JSON.parse(raw) : {};
-        const policy = parsePolicy(parsed, resolved);
-        POLICY_CACHE.set(resolved, { loadedAt: now, mtimeMs, policy });
-        return { policy };
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error ?? 'unknown');
-        POLICY_CACHE.set(resolved, { loadedAt: now, error: `[exec_command_guard] policy load failed: ${message}` });
-        return { error: `[exec_command_guard] policy load failed: ${message}` };
-    }
-    finally {
-        try {
-            inFlightResolve?.();
-        }
-        catch {
-            /* ignore */
-        }
-    }
-}
-function parsePolicy(raw, policyFile) {
-    const version = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw.version : undefined;
-    if (version !== 1) {
-        return {
-            version: 1,
-            policyFile,
-            allowedProjectRoots: [],
-            denyOutsideProjectDestructive: false,
-            gitSingleFileOnly: false,
-            denyMassKill: false,
-            rules: []
-        };
-    }
-    const allowedProjectRoots = [];
-    const rootsRaw = raw.allowedProjectRoots;
-    if (Array.isArray(rootsRaw)) {
-        for (const entry of rootsRaw) {
-            if (typeof entry === 'string' && entry.trim()) {
-                allowedProjectRoots.push(path.resolve(expandUserPath(entry.trim())));
-            }
-        }
-    }
-    const defaultsRaw = raw.defaults;
-    const defaults = defaultsRaw && typeof defaultsRaw === 'object' && !Array.isArray(defaultsRaw)
-        ? defaultsRaw
-        : {};
-    const denyOutsideProjectDestructive = defaults.denyOutsideProjectDestructive === true ||
-        (typeof defaults.denyOutsideProjectDestructive === 'string' &&
-            String(defaults.denyOutsideProjectDestructive).trim().toLowerCase() === 'true');
-    const gitSingleFileOnly = defaults.gitSingleFileOnly === true ||
-        (typeof defaults.gitSingleFileOnly === 'string' && String(defaults.gitSingleFileOnly).trim().toLowerCase() === 'true');
-    const denyMassKill = defaults.denyMassKill === true ||
-        (typeof defaults.denyMassKill === 'string' && String(defaults.denyMassKill).trim().toLowerCase() === 'true');
-    const rules = [];
-    const rulesRaw = raw.rules;
-    if (Array.isArray(rulesRaw)) {
-        for (const entry of rulesRaw) {
-            if (!entry || typeof entry !== 'object' || Array.isArray(entry))
-                continue;
-            const rule = entry;
-            const type = typeof rule.type === 'string' ? rule.type.trim().toLowerCase() : 'regex';
-            if (type !== 'regex')
-                continue;
-            const id = typeof rule.id === 'string' && rule.id.trim() ? rule.id.trim() : '';
-            const pattern = typeof rule.pattern === 'string' && rule.pattern.trim() ? rule.pattern.trim() : '';
-            if (!id || !pattern)
-                continue;
-            const flags = typeof rule.flags === 'string' ? rule.flags.trim() : 'i';
-            const targetRaw = typeof rule.target === 'string' ? rule.target.trim().toLowerCase() : 'cmd';
-            const target = targetRaw === 'cmd+workdir' ? 'cmd+workdir' : 'cmd';
-            let regex;
-            try {
-                regex = new RegExp(pattern, flags);
-            }
-            catch {
-                continue;
-            }
-            const reason = typeof rule.reason === 'string' && rule.reason.trim() ? rule.reason.trim() : undefined;
-            rules.push({ id, reason, target, regex });
-        }
-    }
-    return {
-        version: 1,
-        policyFile,
-        allowedProjectRoots,
-        denyOutsideProjectDestructive,
-        gitSingleFileOnly,
-        denyMassKill,
-        rules
-    };
-}
-function isSubPath(child, parent) {
-    const rel = path.relative(parent, child);
-    if (!rel)
-        return true;
-    return !rel.startsWith('..' + path.sep) && rel !== '..';
-}
-function evaluateOutsideProjectDestructive(options) {
-    const workdir = typeof options.workdir === 'string' && options.workdir.trim() ? path.resolve(expandUserPath(options.workdir.trim())) : '';
-    const roots = options.allowedProjectRoots;
-    if (!workdir || !roots.length) {
-        return null;
-    }
-    const inProject = roots.some((root) => isSubPath(workdir, root));
-    if (inProject) {
-        return null;
-    }
-    // Only enforce for clearly destructive operations (policy default).
-    const destructive = /(^|\s)(sudo\s+)?rm\b[^\n]*(\s|^)(-rf|-fr|-r|-f|--recursive)(\s|$)/i.test(options.cmd) ||
-        /(^|\s)find\b[^\n]*\s-delete(\s|$)/i.test(options.cmd);
-    if (!destructive) {
-        return null;
-    }
-    // If user is not in a project dir, deny destructive commands that reference absolute paths or home paths.
-    const targetsAbsoluteOrHome = /(^|\s)(\/|~\/)/.test(options.cmd) ||
-        /\s(\/|~\/)/.test(options.cmd);
-    if (!targetsAbsoluteOrHome) {
-        return null;
-    }
-    return {
-        id: 'policy-defaults-deny-outside-project-destructive',
-        reason: 'Destructive command outside allowed project roots is not allowed'
-    };
-}
-function evaluateGitSingleFileOnly(cmd) {
-    const trimmed = cmd.trim();
-    if (!/^git\s+(checkout|restore)\b/i.test(trimmed)) {
-        return null;
-    }
-    // Only enforce when pathspec is provided explicitly with "--" (safer parsing).
-    const idx = trimmed.indexOf(' -- ');
-    if (idx < 0) {
-        return {
-            id: 'policy-defaults-git-single-file-only',
-            reason: 'git checkout/restore is restricted to single-file pathspec using `-- <file>`'
-        };
-    }
-    const pathspec = trimmed.slice(idx + 4).trim();
-    if (!pathspec) {
-        return {
-            id: 'policy-defaults-git-single-file-only',
-            reason: 'git checkout/restore requires a single file pathspec'
-        };
-    }
-    if (pathspec === '.' || pathspec === './' || pathspec === '..' || pathspec === '../') {
-        return {
-            id: 'policy-defaults-git-single-file-only',
-            reason: 'Directory pathspec is not allowed for git checkout/restore'
-        };
-    }
-    if (/\s/.test(pathspec)) {
-        return {
-            id: 'policy-defaults-git-single-file-only',
-            reason: 'Multiple pathspecs are not allowed for git checkout/restore'
-        };
-    }
-    if (pathspec.endsWith('/') || pathspec.includes('*') || pathspec.includes('?')) {
-        return {
-            id: 'policy-defaults-git-single-file-only',
-            reason: 'Directory/glob pathspec is not allowed for git checkout/restore'
-        };
-    }
-    return null;
-}
-function evaluateMassKill(cmd) {
-    const trimmed = cmd.trim();
-    if (/^pkill\b/i.test(trimmed) || /^killall\b/i.test(trimmed)) {
-        return {
-            id: 'policy-defaults-deny-mass-kill',
-            reason: 'pkill/killall are not allowed'
-        };
-    }
-    if (!/^kill\b/i.test(trimmed)) {
-        return null;
-    }
-    // Allow kill by PID(s) only; deny name-based / pattern-based killing.
-    const parts = trimmed.split(/\s+/).slice(1);
-    if (!parts.length) {
-        return {
-            id: 'policy-defaults-deny-mass-kill',
-            reason: 'kill must target a specific PID'
-        };
-    }
-    const targets = parts.filter((p) => !p.startsWith('-'));
-    if (!targets.length) {
-        return {
-            id: 'policy-defaults-deny-mass-kill',
-            reason: 'kill must target a specific PID'
-        };
-    }
-    for (const t of targets) {
-        if (!/^[0-9]+$/.test(t)) {
-            return {
-                id: 'policy-defaults-deny-mass-kill',
-                reason: 'kill is restricted to PID-only targets'
-            };
-        }
-    }
-    return null;
-}

package/dist/servertool/handlers/followup-request-builder.d.ts

@@ -1,4 +1,5 @@
 import type { JsonObject } from '../../conversion/hub/types/json.js';
+import type { ServerToolFollowupInjectionPlan } from '../types.js';
 export type CapturedChatSeed = {
     model?: string;
     messages: JsonObject[];
@@ -7,11 +8,18 @@ export type CapturedChatSeed = {
 };
 export declare function extractCapturedChatSeed(source: unknown): CapturedChatSeed | null;
 export declare function normalizeFollowupParameters(value: unknown): Record<string, unknown> | undefined;
-export declare function buildEntryAwareFollowupPayload(args: {
-    entryEndpoint: string;
-    model?: string;
-    messages: JsonObject[];
-    tools?: JsonObject[];
-    parameters?: Record<string, unknown>;
-}): JsonObject;
 export declare function dropToolByFunctionName(tools: JsonObject[] | undefined, dropName: string): JsonObject[] | undefined;
+/**
+ * Build a canonical followup request body from injection ops.
+ *
+ * Important: this returns a protocol-agnostic "chat-like" payload:
+ * { model, messages, tools?, parameters? }
+ *
+ * The followup is expected to re-enter HubPipeline at the chat-process entry,
+ * so we must not convert to /v1/responses or /v1/messages here.
+ */
+export declare function buildServerToolFollowupChatPayloadFromInjection(args: {
+    adapterContext: unknown;
+    chatResponse: JsonObject;
+    injection: ServerToolFollowupInjectionPlan;
+}): JsonObject | null;