@shieldaai/agent-guard-scenarios 0.1.0-alpha.0 → 0.1.0-alpha.1

package/README.md

@@ -11,12 +11,16 @@ console.table(report.results);
 console.log(scenarioCatalog);
 ```
 
-Run selected scenarios with `runConformance({ scenarioIds: ['S05', 'S08'] })`. The default suite executes malicious and benign variants of all ten scenarios. It checks handler invocations and synthetic effects, not merely decision objects. Fixtures do not use real credentials, models, network services or destructive operations.
+Run selected scenarios with `runConformance({ scenarioIds: ['S05', 'S08'] })`. The default suite executes malicious and benign variants of all ten scenarios. It checks handler invocations and synthetic effects, not merely decision objects. The built-in fixtures use no credentials, model calls, network services or destructive operations. A custom adapter is responsible for its own I/O.
 
 The scenarios cover unauthorized tools/resources, delegation, protected administration, sensitive export, action-bound approval, metadata drift, outbound secrets/canaries, revocation/control failures, tenants and budgets. The [scenario specification](https://github.com/ShieldaAI/agent-guard/blob/main/docs/scenarios.md) explains each boundary.
 
+The catalog version identifies the executed acceptance checks independently of the package version; compare reports using their `catalogVersion`. Version `1.1.0` strengthens the existing S08 race assertions and S10 charging checks and adds the per-variant timeout. It retains ten scenario identifiers and twenty paired cases. A pass from an older catalog does not establish coverage of newly added assertions.
+
 To exercise a compatible implementation, supply `createGuard(options)` in the options object. The factory must honor the provided clock and secret configuration and return the structural `GuardLike` API. Denials use the exported `GuardError` and its documented reason codes. Each fixture receives an isolated instance; no shared factory state is required.
 
+Each malicious or benign variant has a five-second asynchronous timeout. Override it with `caseTimeoutMs`, a positive integer up to `2147483647`. A timed-out variant receives a failed result and the runner continues with the next variant. The timer cannot interrupt blocking JavaScript or cancel unfinished adapter work; an adapter may retain resources or continue running after its result is reported. Use process isolation if the implementation under test needs a hard execution limit.
+
 A passing report applies to these fixtures in one process. It is not a security certification, injection-detector benchmark, MCP transport test or proof that a production agent cannot bypass its integration. Errors after actual handler invocation are tested separately from denials that must prevent invocation.
 
 Apache-2.0. Copyright 2026 ShieldaAI contributors.

package/dist/catalog.d.ts

@@ -1,5 +1,5 @@
 /** Version of the synthetic acceptance cases, independent of package releases. */
-export declare const SCENARIO_CATALOG_VERSION: '1.0.0';
+export declare const SCENARIO_CATALOG_VERSION: '1.1.0';
 export type ScenarioId = 'S01' | 'S02' | 'S03' | 'S04' | 'S05' | 'S06' | 'S07' | 'S08' | 'S09' | 'S10';
 export interface ScenarioDefinition {
     readonly id: ScenarioId;
@@ -9,5 +9,5 @@ export interface ScenarioDefinition {
     readonly benign: string;
     readonly limitations: readonly string[];
 }
-/** Immutable descriptive catalog. Execution is opt-in through runConformance(). */
+/** Read-only scenario descriptions. Call runConformance() to run the fixtures. */
 export declare const scenarioCatalog: readonly ScenarioDefinition[];

package/dist/catalog.js

@@ -1,5 +1,5 @@
 /** Version of the synthetic acceptance cases, independent of package releases. */
-export const SCENARIO_CATALOG_VERSION = '1.0.0';
+export const SCENARIO_CATALOG_VERSION = '1.1.0';
 const definitions = [
     {
         id: 'S01', title: 'Deny unknown tools and unauthorized resources',
@@ -72,7 +72,7 @@ const definitions = [
         limitations: ['Quotas are local and nondurable; the provider must enforce declared upper costs and handlers must honor cancellation.'],
     },
 ];
-/** Immutable descriptive catalog. Execution is opt-in through runConformance(). */
+/** Read-only scenario descriptions. Call runConformance() to run the fixtures. */
 export const scenarioCatalog = Object.freeze(definitions.map((entry) => Object.freeze({
     ...entry,
     malicious: Object.freeze([...entry.malicious]),

package/dist/index.d.ts

@@ -2,14 +2,16 @@ import { AgentGuard, type GuardOptions } from '@shieldaai/agent-guard';
 import { SCENARIO_CATALOG_VERSION, type ScenarioId } from './catalog.js';
 export { SCENARIO_CATALOG_VERSION, scenarioCatalog } from './catalog.js';
 export type { ScenarioDefinition, ScenarioId } from './catalog.js';
-/** Structural surface required from a compatible guard adapter. */
+/** Methods an adapter must provide to run the conformance suite. */
 export type GuardLike = Pick<AgentGuard, 'registerTool' | 'approveTool' | 'createTask' | 'delegateTask' | 'revokeTask' | 'setPolicy' | 'prepare' | 'approve' | 'execute' | 'snapshot'>;
 export type ConformanceGuardFactory = (options: GuardOptions) => GuardLike;
 export interface ConformanceOptions {
     /** Omit to execute all ten scenarios. Each selected scenario runs both variants. */
     readonly scenarioIds?: readonly ScenarioId[];
+    /** Time limit per variant in milliseconds; defaults to 5000. Timeout does not cancel adapter work. */
+    readonly caseTimeoutMs?: number;
     /**
-     * Supply a fresh isolated guard per call; defaults to the public AgentGuard implementation.
+     * Return a new guard for each call. Defaults to the public AgentGuard implementation.
      * Compatible adapters must preserve these APIs and throw this core package's GuardError
      * with the documented reason codes. The provided clock and secret configuration must be honored.
      */
@@ -35,8 +37,8 @@ export interface ConformanceReport {
     readonly results: readonly ConformanceCaseResult[];
 }
 /**
- * Run synthetic effects against this installation's public core API.
- * This validates the listed local fixtures, not a deployment, transport, or universal injection defense.
- * No network, credentials, filesystem writes, model calls, or external effects are used.
+ * Run the catalog fixtures against AgentGuard or the supplied adapter.
+ * The default implementation uses in-memory effects only. A custom adapter is
+ * responsible for its own I/O; the runner cannot isolate or cancel it.
  */
 export declare function runConformance(options?: ConformanceOptions): Promise<ConformanceReport>;

package/dist/index.js

@@ -28,11 +28,11 @@ function deferred() {
     const promise = new Promise((done) => { resolve = done; });
     return { promise, resolve };
 }
-async function bounded(promise, label) {
+async function bounded(promise, label, timeoutMs = 1500) {
     let timer;
     try {
         return await Promise.race([promise, new Promise((_, reject) => {
-                timer = setTimeout(() => reject(new CheckFailure(label)), 1500);
+                timer = setTimeout(() => reject(new CheckFailure(label)), timeoutMs);
             })]);
     }
     finally {
@@ -341,20 +341,23 @@ const cases = {
                 const prepared = await f.guard.prepare(task, { tool: 'delete_record', args: { resource: RECORD_A } });
                 const approvalId = f.approve(prepared);
                 wait = true;
-                const pending = f.guard.execute(prepared, { approvalId });
-                // Observe early settlement immediately, including when testing a broken implementation.
-                const observed = pending.then(() => undefined, () => undefined);
-                try {
-                    await bounded(Promise.race([entered.promise, observed.then(() => { throw new CheckFailure('execution settled before policy barrier'); })]), 'policy barrier not reached');
-                    if (change === 'revoke')
-                        f.guard.revokeTask(task);
-                    else
-                        f.guard.setPolicy(() => 'allow');
-                }
-                finally {
-                    release.resolve();
-                }
-                await c.denied(() => pending, `${change} during asynchronous policy`, change === 'revoke' ? 'TASK_REVOKED' : 'POLICY_CHANGED');
+                await c.denied(async () => {
+                    const pending = f.guard.execute(prepared, { approvalId });
+                    // Observe early settlement immediately, including when testing a broken implementation.
+                    const observed = pending.then(() => undefined, () => undefined);
+                    try {
+                        await bounded(Promise.race([entered.promise, observed.then(() => { throw new CheckFailure('execution settled before policy barrier'); })]), 'policy barrier not reached');
+                        if (change === 'revoke')
+                            f.guard.revokeTask(task);
+                        else
+                            f.guard.setPolicy(() => 'allow');
+                    }
+                    finally {
+                        release.resolve();
+                    }
+                    return pending;
+                }, `${change} during asynchronous policy`, change === 'revoke' ? 'TASK_REVOKED' : 'POLICY_CHANGED');
+                c.assert(f.ledger.length === 0, `${change} during asynchronous policy leaves the ledger empty`);
             }
             const f = fixture(c);
             f.remove();
@@ -485,6 +488,13 @@ const cases = {
             await f.invoke(task, 'read_document', { resource: GUIDE });
             const snapshot = f.guard.snapshot(task);
             c.assert(snapshot.calls === 2 && snapshot.concurrent === 0 && snapshot.spent === 2 && snapshot.reserved === 0, 'completed work reconciles usage and releases slots');
+            const omitted = fixture(c);
+            omitted.read({ maxCost: 3 });
+            const omittedTask = omitted.task(readGrant(), { budget: omitted.budget({ maxCost: 6 }) });
+            await omitted.invoke(omittedTask, 'read_document', { resource: GUIDE });
+            await omitted.invoke(omittedTask, 'read_document', { resource: GUIDE });
+            const omittedSnapshot = omitted.guard.snapshot(omittedTask);
+            c.assert(omittedSnapshot.calls === 2 && omittedSnapshot.spent === 6 && omittedSnapshot.reserved === 0 && omittedSnapshot.concurrent === 0, 'omitted actual cost charges the full declared maximum');
             const cancel = fixture(c);
             const entered = deferred();
             let observed = false;
@@ -532,11 +542,11 @@ const cases = {
             c.assert(deadlineObserved && deadline.guard.snapshot(deadlineTask).concurrent === 0, 'deadline signals cooperative cancellation and releases slot');
             const failed = fixture(c);
             let first = true;
-            failed.read({ execute: () => { c.handlerInvocations += 1; if (first) {
+            failed.read({ maxCost: 3, execute: () => { c.handlerInvocations += 1; if (first) {
                     first = false;
                     throw new Error('synthetic failure');
                 } return { value: 'recovered' }; } });
-            const failedTask = failed.task(readGrant(), { budget: failed.budget({ maxConcurrent: 1 }) });
+            const failedTask = failed.task(readGrant(), { budget: failed.budget({ maxConcurrent: 1, maxCost: 9 }) });
             let rejected = false;
             try {
                 await failed.invoke(failedTask, 'read_document', { resource: GUIDE });
@@ -545,16 +555,22 @@ const cases = {
                 rejected = true;
             }
             c.assert(rejected && failed.guard.snapshot(failedTask).calls === 1 && failed.guard.snapshot(failedTask).concurrent === 0, 'failed handler counts attempt and releases concurrency');
+            c.assert(failed.guard.snapshot(failedTask).spent === 3 && failed.guard.snapshot(failedTask).reserved === 0, 'failed handler retains the full declared charge');
             c.assert(await failed.invoke(failedTask, 'read_document', { resource: GUIDE }) === 'recovered', 'next authorized call can use released slot');
+            c.assert(failed.guard.snapshot(failedTask).spent === 6 && failed.guard.snapshot(failedTask).concurrent === 0, 'recovery retains both admitted charges and releases concurrency');
         },
     },
 };
 /**
- * Run synthetic effects against this installation's public core API.
- * This validates the listed local fixtures, not a deployment, transport, or universal injection defense.
- * No network, credentials, filesystem writes, model calls, or external effects are used.
+ * Run the catalog fixtures against AgentGuard or the supplied adapter.
+ * The default implementation uses in-memory effects only. A custom adapter is
+ * responsible for its own I/O; the runner cannot isolate or cancel it.
  */
 export async function runConformance(options = {}) {
+    const caseTimeoutMs = options.caseTimeoutMs === undefined ? 5000 : options.caseTimeoutMs;
+    if (!Number.isSafeInteger(caseTimeoutMs) || caseTimeoutMs < 1 || caseTimeoutMs > 2_147_483_647) {
+        throw new TypeError('caseTimeoutMs must be an integer from 1 through 2147483647');
+    }
     const selected = options.scenarioIds ?? scenarioCatalog.map((scenario) => scenario.id);
     if (selected.length === 0 || new Set(selected).size !== selected.length || selected.some((id) => !Object.hasOwn(cases, id))) {
         throw new TypeError('scenarioIds must be a nonempty list of distinct catalog identifiers');
@@ -565,7 +581,7 @@ export async function runConformance(options = {}) {
             const checks = new Checks(options.createGuard);
             let failure;
             try {
-                await cases[scenarioId][variant](checks);
+                await bounded(cases[scenarioId][variant](checks), 'case exceeded its asynchronous timeout', caseTimeoutMs);
             }
             catch (error) {
                 failure = error instanceof CheckFailure ? error.message

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shieldaai/agent-guard-scenarios",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.1",
   "description": "Executable protective scenarios and conformance fixtures for agent tool executors.",
   "license": "Apache-2.0",
   "type": "module",
@@ -43,9 +43,10 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "prepack": "node ../../scripts/build.mjs",
     "prepublishOnly": "node ../../scripts/release-check.mjs"
   },
   "dependencies": {
-    "@shieldaai/agent-guard": "0.1.0-alpha.0"
+    "@shieldaai/agent-guard": "0.1.0-alpha.1"
   }
 }