LibreChat/packages/api/src/plugins/runtime.spec.ts
Danny Avila 8ba76507ae
Some checks failed
Docker Dev Images Build / build (Dockerfile, librechat-dev, node) (push) Waiting to run
Docker Dev Images Build / build (Dockerfile.multi, librechat-dev-api, api-build) (push) Waiting to run
Sync Helm Chart Tags / Ignore non-main push (push) Waiting to run
Sync Helm Chart Tags / Sync chart tags (push) Waiting to run
Publish `librechat-data-provider` to NPM / pack (push) Has been cancelled
Publish `librechat-data-provider` to NPM / publish-npm (push) Has been cancelled
🧷 fix: Verify Scheduled HITL State Before Pausing (#15284)
* fix: require durable storage for scheduled HITL

* fix: verify scheduled HITL checkpoints before pause

* fix: narrow scheduled HITL capability checks

* fix: honor ask tool filters in schedule preflight

* fix: enforce durability across scheduled HITL resumes

* fix: scope scheduled HITL admission to active tools

* refactor: move scheduled HITL admission to TypeScript

* fix: close scheduled HITL admission gaps

* fix: bind scheduled pauses to current checkpoint

* fix: cap pending actions at binding deadline

* fix: reject expired pending actions

* fix: guard approval deadlines atomically
2026-08-27 11:16:24 -04:00

455 lines
15 KiB
TypeScript

import fs from 'fs';
import os from 'os';
import path from 'path';
import { HookRegistry, executeHooks } from '@librechat/agents';
import {
getDeploymentPluginHookCapabilities,
registerDeploymentPluginHooks,
hasDeploymentPluginHooks,
hasDeploymentPluginToolApprovalHooks,
} from './runtime';
import { getPluginHookSource, setPluginHookSource } from '~/agents/hooks';
import { initializeDeploymentPlugins } from './deployment';
import { PLUGIN_MANIFEST_SCHEMA_ID } from './constants';
let base: string;
let pluginsDir: string;
let dataDir: string;
const HOOKS_DOCUMENT = {
hooks: {
PreToolUse: [
{
matcher: '^write_file$',
hooks: [
{
type: 'command',
command: `printf '%s' '{"decision":"deny","reason":"guarded"}'`,
},
],
},
{
matcher: '^(Write|Edit)$',
hooks: [
{
type: 'command',
command: `node -e 'let d="";process.stdin.on("data",(c)=>{d+=c;}).on("end",()=>{const p=JSON.parse(d);const claudeShaped=p.tool_name==="Write"&&p.tool_input.file_path==="/workspace/report.md"&&p.tool_input.path===undefined;console.log(JSON.stringify(claudeShaped?{decision:"deny",reason:"alias-guarded"}:{}));});'`,
},
],
},
],
SessionStart: [
{
hooks: [
{ type: 'command', command: 'echo started >> "$PLUGIN_DATA/starts.log"' },
{ type: 'command', command: 'echo sibling >> "$PLUGIN_DATA/starts.log"' },
],
},
],
},
};
async function writePlugin(name: string, document: object = HOOKS_DOCUMENT): Promise<void> {
const root = path.join(pluginsDir, name);
await fs.promises.mkdir(path.join(root, 'ai.librechat', 'hooks'), { recursive: true });
await fs.promises.writeFile(
path.join(root, 'plugin.json'),
JSON.stringify({ $schema: PLUGIN_MANIFEST_SCHEMA_ID, name }),
);
await fs.promises.writeFile(
path.join(root, 'ai.librechat', 'hooks', 'hooks.json'),
JSON.stringify(document),
);
}
async function initialize(): Promise<void> {
await initializeDeploymentPlugins({
projectRoot: base,
env: {
DEPLOYMENT_PLUGINS_DIR: pluginsDir,
DEPLOYMENT_PLUGIN_DATA_DIR: dataDir,
},
hookCapabilities: getDeploymentPluginHookCapabilities({ DEPLOYMENT_PLUGIN_HOOKS: 'true' }),
});
}
async function fireRunStart(sessionId: string, sessionStartSource?: string): Promise<void> {
const registry = new HookRegistry();
registerDeploymentPluginHooks({ registry, context: { sessionId, sessionStartSource } });
await executeHooks({
registry,
input: { hook_event_name: 'RunStart', runId: `run-${Math.random()}`, messages: [] },
});
}
beforeEach(async () => {
base = await fs.promises.realpath(
await fs.promises.mkdtemp(path.join(os.tmpdir(), 'lc-plugin-runtime-')),
);
pluginsDir = path.join(base, 'plugin');
dataDir = path.join(base, 'data');
await fs.promises.mkdir(pluginsDir, { recursive: true });
});
afterEach(async () => {
await fs.promises.rm(base, { recursive: true, force: true });
/** Unconfigured missing directories reset the module registry to empty. */
await initializeDeploymentPlugins({ projectRoot: base, env: {} });
});
describe('getDeploymentPluginHookCapabilities', () => {
it('returns undefined unless DEPLOYMENT_PLUGIN_HOOKS is enabled', () => {
expect(getDeploymentPluginHookCapabilities({})).toBeUndefined();
expect(
getDeploymentPluginHookCapabilities({ DEPLOYMENT_PLUGIN_HOOKS: 'false' }),
).toBeUndefined();
expect(
getDeploymentPluginHookCapabilities({ DEPLOYMENT_PLUGIN_HOOKS: 'true' })?.handlerTypes.has(
'command',
),
).toBe(true);
});
});
describe('registerDeploymentPluginHooks', () => {
it('registers nothing when plugins loaded without hook capabilities', async () => {
await writePlugin('inert');
await initializeDeploymentPlugins({
projectRoot: base,
env: { DEPLOYMENT_PLUGINS_DIR: pluginsDir, DEPLOYMENT_PLUGIN_DATA_DIR: dataDir },
});
expect(hasDeploymentPluginHooks()).toBe(false);
const registry = new HookRegistry();
expect(registerDeploymentPluginHooks({ registry })).toBe(0);
});
it('executes a plugin command hook end-to-end through a run hook registry', async () => {
await writePlugin('guard');
await initialize();
expect(hasDeploymentPluginHooks()).toBe(true);
const registry = new HookRegistry();
const registered = registerDeploymentPluginHooks({
registry,
context: { sessionId: 'conversation-1' },
});
expect(registered).toBe(4);
const result = await executeHooks({
registry,
matchQuery: 'write_file',
input: {
hook_event_name: 'PreToolUse',
runId: 'run-1',
toolName: 'write_file',
toolInput: { path: '/etc/passwd' },
toolUseId: 'tool-1',
},
});
expect(result).toEqual(expect.objectContaining({ decision: 'deny', reason: 'guarded' }));
const unmatched = await executeHooks({
registry,
matchQuery: 'read_file',
input: {
hook_event_name: 'PreToolUse',
runId: 'run-1',
toolName: 'read_file',
toolInput: {},
toolUseId: 'tool-2',
},
});
expect(unmatched.decision).toBeUndefined();
});
it('fires Claude-alias matchers against runtime tool names with plugin-namespace payloads', async () => {
await writePlugin('alias');
await initialize();
const registry = new HookRegistry();
registerDeploymentPluginHooks({ registry, context: { sessionId: 'conversation-alias' } });
const result = await executeHooks({
registry,
matchQuery: 'create_file',
input: {
hook_event_name: 'PreToolUse',
runId: 'run-1',
toolName: 'create_file',
toolInput: { path: '/workspace/report.md' },
toolUseId: 'tool-1',
},
});
expect(result).toEqual(expect.objectContaining({ decision: 'deny', reason: 'alias-guarded' }));
});
it('keeps native payloads for matchers authored in the runtime namespace', async () => {
await writePlugin('native', {
hooks: {
PreToolUse: [
{
matcher: '^create_file$',
hooks: [
{
type: 'command',
command: `node -e 'let d="";process.stdin.on("data",(c)=>{d+=c;}).on("end",()=>{const p=JSON.parse(d);const nativeShaped=p.tool_name==="create_file"&&p.tool_input.path==="/workspace/native.md"&&p.tool_input.file_path===undefined;console.log(JSON.stringify(nativeShaped?{decision:"deny",reason:"native-guarded"}:{}));});'`,
},
],
},
],
},
});
await initialize();
const registry = new HookRegistry();
registerDeploymentPluginHooks({ registry, context: { sessionId: 'conversation-native' } });
const result = await executeHooks({
registry,
matchQuery: 'create_file',
input: {
hook_event_name: 'PreToolUse',
runId: 'run-1',
toolName: 'create_file',
toolInput: { path: '/workspace/native.md' },
toolUseId: 'tool-1',
},
});
expect(result).toEqual(expect.objectContaining({ decision: 'deny', reason: 'native-guarded' }));
});
it('keeps native payloads for the native alternative of a mixed-namespace matcher', async () => {
await writePlugin('mixed', {
hooks: {
PreToolUse: [
{
matcher: 'Bash|create_file',
hooks: [
{
type: 'command',
command: `node -e 'let d="";process.stdin.on("data",(c)=>{d+=c;}).on("end",()=>{const p=JSON.parse(d);const nativeShaped=p.tool_name==="create_file"&&p.tool_input.path==="/workspace/mixed.md"&&p.tool_input.file_path===undefined;console.log(JSON.stringify(nativeShaped?{decision:"deny",reason:"mixed-native"}:{}));});'`,
},
],
},
],
},
});
await initialize();
const registry = new HookRegistry();
registerDeploymentPluginHooks({ registry, context: { sessionId: 'conversation-mixed' } });
const result = await executeHooks({
registry,
matchQuery: 'create_file',
input: {
hook_event_name: 'PreToolUse',
runId: 'run-1',
toolName: 'create_file',
toolInput: { path: '/workspace/mixed.md' },
toolUseId: 'tool-1',
},
});
expect(result).toEqual(expect.objectContaining({ decision: 'deny', reason: 'mixed-native' }));
});
it('lets an overlapping once declaration fire after its sibling is spent', async () => {
const onceHandler = {
type: 'command',
command: 'echo fired >> "$PLUGIN_DATA/overlap.log"',
once: true,
};
await writePlugin('overlap', {
hooks: {
PreToolUse: [
{ matcher: 'write_file|read_file', hooks: [onceHandler] },
{ matcher: '^read_file$', hooks: [onceHandler] },
],
},
});
await initialize();
const firePreToolUse = async (toolName: string) => {
const registry = new HookRegistry();
registerDeploymentPluginHooks({ registry, context: { sessionId: 'conversation-overlap' } });
await executeHooks({
registry,
matchQuery: toolName,
input: {
hook_event_name: 'PreToolUse',
runId: `run-${Math.random()}`,
toolName,
toolInput: {},
toolUseId: 'tool-1',
},
});
};
/** Spends the broad declaration's once key. */
await firePreToolUse('write_file');
/**
* The spent broad declaration must not claim the per-input dedup slot,
* or the narrow declaration's independent once-key would never fire.
*/
await firePreToolUse('read_file');
await firePreToolUse('read_file');
const log = await fs.promises.readFile(path.join(dataDir, 'overlap', 'overlap.log'), 'utf8');
expect(log.trim().split('\n')).toHaveLength(2);
});
it('serves the run seam through the plugin hook source', async () => {
await writePlugin('seam');
await initialize();
setPluginHookSource({
hasHooks: hasDeploymentPluginHooks,
register: registerDeploymentPluginHooks,
});
const source = getPluginHookSource();
expect(source?.hasHooks()).toBe(true);
expect(hasDeploymentPluginToolApprovalHooks()).toBe(true);
expect(hasDeploymentPluginToolApprovalHooks(['unmatched_tool'])).toBe(false);
expect(hasDeploymentPluginToolApprovalHooks(['write_file'])).toBe(true);
const registry = new HookRegistry();
expect(source?.register({ registry, context: { sessionId: 'conversation-seam' } })).toBe(4);
setPluginHookSource(undefined);
expect(getPluginHookSource()).toBeUndefined();
});
it('fires every SessionStart handler once per conversation and per lifecycle source', async () => {
await writePlugin('session');
await initialize();
await fireRunStart('conversation-a');
await fireRunStart('conversation-a');
await fireRunStart('conversation-b');
/** A startup firing must not suppress the conversation's resume rebuild. */
await fireRunStart('conversation-a', 'resume');
await fireRunStart('conversation-a', 'resume');
const log = await fs.promises.readFile(path.join(dataDir, 'session', 'starts.log'), 'utf8');
const lines = log.trim().split('\n').sort();
expect(lines).toEqual(['sibling', 'sibling', 'sibling', 'started', 'started', 'started']);
});
it("reports the caller's working directory in hook payloads", async () => {
await writePlugin('cwd', {
hooks: {
PreToolUse: [
{
matcher: '^write_file$',
hooks: [
{
type: 'command',
command: `node -e 'let d="";process.stdin.on("data",(c)=>{d+=c;}).on("end",()=>{const p=JSON.parse(d);console.log(JSON.stringify({decision:"deny",reason:p.cwd+"|"+process.cwd()}));});'`,
},
],
},
],
},
});
await initialize();
const registry = new HookRegistry();
registerDeploymentPluginHooks({
registry,
context: { sessionId: 'conversation-cwd', cwd: '/workspace/session' },
});
const result = await executeHooks({
registry,
matchQuery: 'write_file',
input: {
hook_event_name: 'PreToolUse',
runId: 'run-1',
toolName: 'write_file',
toolInput: {},
toolUseId: 'tool-1',
},
});
/** Payload carries the session cwd; the process still runs from the plugin root. */
expect(result).toEqual(
expect.objectContaining({
reason: `/workspace/session|${path.join(pluginsDir, 'cwd')}`,
}),
);
});
it('presents Claude payloads to matcherless tool guards', async () => {
await writePlugin('wildcard', {
hooks: {
PreToolUse: [
{
hooks: [
{
type: 'command',
command: `node -e 'let d="";process.stdin.on("data",(c)=>{d+=c;}).on("end",()=>{const p=JSON.parse(d);const claudeShaped=p.tool_name==="Write"&&p.tool_input.file_path==="/workspace/wild.md"&&p.tool_input.path===undefined;console.log(JSON.stringify(claudeShaped?{decision:"deny",reason:"wildcard-guarded"}:{}));});'`,
},
],
},
],
},
});
await initialize();
const registry = new HookRegistry();
registerDeploymentPluginHooks({ registry, context: { sessionId: 'conversation-wild' } });
const result = await executeHooks({
registry,
matchQuery: 'create_file',
input: {
hook_event_name: 'PreToolUse',
runId: 'run-1',
toolName: 'create_file',
toolInput: { path: '/workspace/wild.md' },
toolUseId: 'tool-1',
},
});
expect(result).toEqual(
expect.objectContaining({ decision: 'deny', reason: 'wildcard-guarded' }),
);
});
it('persists once-only state per declaration across runs of the same conversation', async () => {
const onceHandler = {
type: 'command',
command: 'echo fired >> "$PLUGIN_DATA/once.log"',
once: true,
};
await writePlugin('oncely', {
hooks: {
PreToolUse: [
{ matcher: '^write_file$', hooks: [onceHandler] },
{ matcher: '^read_file$', hooks: [onceHandler] },
],
},
});
await initialize();
const firePreToolUse = async (sessionId: string, toolName: string) => {
const registry = new HookRegistry();
registerDeploymentPluginHooks({ registry, context: { sessionId } });
await executeHooks({
registry,
matchQuery: toolName,
input: {
hook_event_name: 'PreToolUse',
runId: `run-${Math.random()}`,
toolName,
toolInput: {},
toolUseId: 'tool-1',
},
});
};
await firePreToolUse('conversation-once', 'write_file');
await firePreToolUse('conversation-once', 'write_file');
/** A sibling declaration with an identical handler is independently once-only. */
await firePreToolUse('conversation-once', 'read_file');
await firePreToolUse('conversation-other', 'write_file');
const log = await fs.promises.readFile(path.join(dataDir, 'oncely', 'once.log'), 'utf8');
expect(log.trim().split('\n')).toHaveLength(3);
});
});