@silmaril-security/sdk 0.7.0 → 0.7.2

package/CHANGELOG.md

@@ -2,14 +2,30 @@
 
 All notable changes to the Silmaril Firewall TypeScript SDK are documented here.
 
+## 0.7.2 - 2026-10-05
+
+- Clear the attempt timeout immediately on caller cancellation, including when
+  retry-response body disposal never settles. This prevents residual timers
+  from keeping command-hook processes alive beyond their shared deadline.
+- Make retried-response cleanup respect caller cancellation and attempt timeouts
+  even when a stream cancellation promise never settles.
+
+## 0.7.1 - 2026-10-04
+
+- Reject malformed batch responses and result counts that do not match the
+  serialized request, including retried requests whose caller inputs change.
+
 ## 0.7.0 - 2026-09-30
 
 - Add optional Deep Agents middleware and protected constructors for root, general-purpose,
   declarative, and explicitly protected compiled subagents. The compiled graph factory
   records middleware installation and constructors reject unverified graphs.
+- Declare optional peer dependencies for Deep Agents:
+  `deepagents@^1.14.1`, `langchain@^1.5.10`, `@langchain/langgraph@^1.4.10`, and
+  existing `@langchain/core@>=0.3.0`.
 - Enforce input, tool-call, tool-result, and non-streamed model-output decisions in
-  Block mode with safe continuation and a repeated-denial cap. Shadow and Warn report
-  decisions without changing content.
+  Block mode with safe continuation and a repeated-denial cap (`maxBlockedAttempts`,
+  default `3`). Shadow and Warn report decisions without changing content.
 - Enable LangChain tool start/end callbacks by default and send the LangChain run ID
   as correlation metadata alongside a distinct classification request ID per event.
 

package/README.md

@@ -18,13 +18,13 @@ This SDK provides the low-level TypeScript interface for that workflow:
 - Classify user input, tool calls, tool responses, model output, or system
   prompt content.
 - Preserve hook and tool-name context for more accurate decisions.
-- Enforce backend-owned adaptive thresholds and effective Shadow, Warn, or
+- Honor backend threat and governance decisions and effective Shadow, Warn, or
   Block behavior in adapters.
 - Send each complete sanitized event in one request.
-- Preserve exact `metadata.conversationId` sequence identity and add one event ID.
+- On individual `classify()` calls, preserve exact `metadata.conversationId` as sequence identity and add one event ID.
 - Retry API rate-limit responses.
-- Optionally attach the firewall to Vercel AI SDK middleware and LangChain.js
-  callback flows.
+- Optionally attach the firewall to Vercel AI SDK middleware, LangChain.js
+  callback flows, and Deep Agents middleware/constructors.
 
 ## Install
 
@@ -37,7 +37,7 @@ npm install @silmaril-security/sdk
 For reproducible installs, pin a tagged release:
 
 ```sh
-npm install @silmaril-security/sdk@0.7.0
+npm install @silmaril-security/sdk@0.7.2
 ```
 
 Requires Node 20 or later.
@@ -63,10 +63,10 @@ Optional LangChain.js support:
 npm install @langchain/core @langchain/openai
 ```
 
-Optional Deep Agents support:
+Optional Deep Agents support (peer ranges shipped with `0.7.0`):
 
 ```sh
-npm install deepagents langchain @langchain/core @langchain/langgraph
+npm install "deepagents@^1.14.1" "langchain@^1.5.10" "@langchain/core@>=0.3.0" "@langchain/langgraph@^1.4.10"
 ```
 
 ## Configuration
@@ -119,15 +119,21 @@ console.log(`tool output: ${toolResult.prediction} ${toolResult.score.toFixed(4)
 ```
 
 `classify()` and `classifyBatch()` return the server's prediction, score, and
-internally applied threshold. Direct calls do not throw on malicious verdicts.
-The Vercel AI SDK and LangChain.js adapters use `result.threshold` and throw
-`FirewallBlockedException` when enforcement is enabled.
+diagnostic threshold. Direct calls do not throw on a `MALICIOUS` prediction or
+a governance block. The Vercel AI SDK and LangChain.js adapters throw
+`FirewallBlockedException` only when `prediction` is `MALICIOUS` or
+`governance.action` is `block`, and the effective mode is `block`.
+`result.threshold` is backend-returned diagnostic metadata carried on the
+result and the exception. Disabled and observe policy paths can retain the
+compatibility threshold. The adapters do not compare `score` to a local
+threshold.
 
 ## Concurrency and Cancellation
 
 A `Firewall` instance holds no per-request state, so one client can serve any
-number of concurrent calls in a runtime. Responses are matched to their own
-promise regardless of completion order:
+number of concurrent calls in a runtime. Concurrent calls are appropriate for
+independent events or different conversations. Responses are matched to their
+own promise regardless of completion order:
 
 ```ts
 const [userResult, toolResult] = await Promise.all([
@@ -136,6 +142,10 @@ const [userResult, toolResult] = await Promise.all([
 ]);
 ```
 
+Events that belong to one conversation are not independent. Send them with
+ordered individual `classify()` calls that share `metadata.conversationId`, and
+wait for each call before sending the next event for that conversation.
+
 Pass a `signal` to cancel one call without touching its siblings:
 
 ```ts
@@ -242,17 +252,16 @@ to each attempt and is combined with any caller-supplied `signal`.
 
 ## Backend Thresholding
 
-Customers do not tune score thresholds in the SDK. Tenant Firewall config owns
-the adaptive threshold schedule. The default backend config is
-`base_threshold=0.5`, `target_sequence_fpr=0.01`, and
-`max_adaptive_threshold=0.9`, which keeps the current schedule: 1 scoring
-opportunity uses `0.5`, 2 use about `0.6661`, 5 use about `0.8328`, and 10 or
-more are capped at `0.9`.
+Customers do not tune score thresholds in the SDK. The Firewall backend owns
+the threat decision and threshold policy. The current Cascade backend resolves
+decision thresholds from a tenant default or a hook-specific override; it does
+not raise them as text length, token-window count, batch size, or conversation
+length grows.
 
-The SDK does not send `threshold` in request payloads. The backend owns the
-applied threshold, which remains available on
-`BlockResult.threshold` and `FirewallBlockedException.threshold` as diagnostic
-metadata.
+The SDK does not send `threshold` in request payloads. `BlockResult.threshold`
+and `FirewallBlockedException.threshold` are backend-returned diagnostic
+metadata. Disabled and observe policy paths can retain the compatibility
+threshold.
 
 ## Modes
 
@@ -350,14 +359,21 @@ await fw.classify(text, {
 ```
 
 The SDK preserves caller metadata and adds a reserved `metadata.silmaril`
-namespace to every request. SDK-controlled fields are `sdk_language`,
-`sdk_version`, and `request_id`; batches additionally carry `input_index` for
-diagnostics and remain stateless. `governance` is also SDK-controlled whenever
-the typed governance option is supplied; it replaces any caller-provided
-`metadata.silmaril.governance` value. Exact `metadata.conversationId` is
-preserved as the backend sequence identity. No aliases are inspected. If
-callers provide `metadata.silmaril`, it must be an object and SDK-reserved keys
-are overwritten by the SDK.
+namespace to every request, including each batch item. SDK-controlled fields
+are `sdk_language`, `sdk_version`, and `request_id`; batches additionally
+carry `input_index` for diagnostics. `governance` is also SDK-controlled
+whenever the typed governance option is supplied; it replaces any
+caller-provided `metadata.silmaril.governance` value. On individual
+`classify()` calls, exact `metadata.conversationId` is preserved as the
+backend sequence identity. Batch items also preserve per-item metadata,
+including `metadata.conversationId`, but current Cascade treats each input
+independently and neither reads nor updates conversation history. Giving items
+the same `metadata.conversationId` does not connect them into a sequence. For
+conversation-aware checks, send complete events through ordered individual
+`classify()` calls with the same `metadata.conversationId`, and wait for each
+call before sending the next event for that conversation. No aliases are
+inspected. If callers provide `metadata.silmaril`, it must be an object and
+SDK-reserved keys are overwritten by the SDK.
 
 The `governance` option on `classify()` and per-item `governance` array on
 `classifyBatch()` send typed agent/resource context. `BlockResult.governance`
@@ -370,16 +386,22 @@ responses without governance remain valid.
 - `SilmarilApiError`: thrown when the firewall API responds with a non-2xx or redirect status. Carries `status`, `statusText`, a 64 KiB-capped `body`, and any parsed malformed-input diagnostics. The default error message omits the body to keep logs clean.
 - `FirewallBlockedException`: thrown by the Vercel AI SDK and LangChain.js adapters when a malicious or governance-block decision has effective Block mode. The message distinguishes governance-policy denials from threat-score denials. Carries `score`, `threshold`, `promptText`, and optional `runId`, `hook`, `toolName`, `toolCallId`, and `result`.
 
-`PromptBlockedException` remains as a deprecated alias for one release.
+`PromptBlockedException` remains as a deprecated alias of
+`FirewallBlockedException`.
 
 All SDK exception types extend `Error` and work with `instanceof`.
 
 ## Complete events
 
 `classify()` sanitizes invalid Unicode surrogate fragments and sends the full
-logical event once. The backend owns token-window processing and sequence
-ordering. `classifyBatch()` continues to send independent stateless texts as one
-batch request.
+logical event once. For conversation-aware checks, send those complete events
+through ordered individual `classify()` calls with the same
+`metadata.conversationId`, and wait for each call before sending the next
+event for that conversation. The backend owns token-window processing and
+sequence ordering for those individual calls. `classifyBatch()` sends
+independent texts in one request: each item keeps its metadata, including
+`metadata.conversationId`, but Cascade neither reads nor updates conversation
+history for the batch.
 
 ## Batch Classification
 
@@ -403,9 +425,36 @@ console.log(`classified ${results.length} items`);
 ```
 
 Batch requests preserve result order and can carry per-item hooks, tool names,
-and metadata. Hook, tool-name, and metadata arrays must match the number of
-texts. Each batch carries SDK metadata per item so the backend can apply
-tenant-owned thresholding.
+metadata, and governance. Hook, tool-name, metadata, and governance arrays must
+match the number of texts. Each batch item preserves caller metadata, including
+`metadata.conversationId`, and carries SDK metadata so the backend can apply
+tenant-owned thresholding. Current Cascade treats each input independently and
+neither reads nor updates conversation history. Giving items the same
+`metadata.conversationId` does not connect them into a sequence.
+
+For conversation-aware checks, send complete events through ordered individual
+`classify()` calls with the same `metadata.conversationId`. Wait for each call
+before sending the next event for that conversation:
+
+```ts
+const conversationId = "customer-conversation-123";
+
+const first = await fw.classify(firstEvent, {
+  hook: HookLabel.USER_INPUT,
+  metadata: { conversationId },
+});
+
+const second = await fw.classify(secondEvent, {
+  hook: HookLabel.TOOL_RESPONSE,
+  toolName: "read_file",
+  metadata: { conversationId },
+});
+```
+
+Batch responses must contain a `predictions` array with exactly one result per
+sent input. A missing array or mismatched count raises an `Error` before
+results are returned or blocking callbacks run. Retries use the original
+payload snapshot, even if caller-owned inputs change while the request is in flight.
 
 ## Migration Notes
 
@@ -416,7 +465,7 @@ tenant/backend config, adds SDK reconstruction metadata, renames blocking
 exceptions to `FirewallBlockedException`, keeps optional LangChain.js types out
 of the root package declarations, adds typed CJS/ESM export conditions, supports
 Vercel AI SDK v5 and v6. The deprecated
-`PromptBlockedException` alias remains available for one release.
+`PromptBlockedException` alias remains available.
 
 ## Vercel AI SDK Middleware
 
@@ -439,10 +488,13 @@ const { text } = await generateText({ model, prompt: "Hello" });
 console.log(text);
 ```
 
-Middleware scans input by default. Set `scanOutput: true` to classify model
-text, and `scanToolCalls: true` to classify tool-call arguments. Infrastructure
-errors and blocking decisions are fail-closed by default and bubble up to the
-caller.
+Middleware scans input by default (`scanInput` defaults to true). It classifies
+that message's tool-result parts as `tool_response` only when the newest prompt
+message is a tool message. Otherwise it classifies the latest user message as
+`user_input` and does not scan earlier tool results. Set `scanOutput: true` to
+classify model text, and `scanToolCalls: true` to classify tool-call arguments
+on generate results. Infrastructure errors and blocking decisions are
+fail-closed by default and bubble up to the caller.
 
 When `scanOutput: true` is combined with streaming, output is classified in the
 stream's `flush` after all deltas have been emitted, so blocking is advisory:
@@ -473,11 +525,11 @@ await model.invoke("Hello");
 
 The LangChain handler is fail-open by default: infrastructure errors are logged
 and the LLM call proceeds. Set `failOpen: false` to make API errors bubble up.
-Blocking decisions still throw `FirewallBlockedException` unless shadow mode is
-enabled. `PromptBlockedException` continues to work as a deprecated alias for
-one release.
+Blocking decisions throw `FirewallBlockedException` only when the effective mode
+is Block; Shadow and Warn preserve the host flow.
+`PromptBlockedException` continues to work as a deprecated alias.
 Model-start, tool-start, and tool-end hooks are enabled by default; retriever
-hooks remain opt-in. The LangChain run ID is sent as
+and model-end (`LLM_END`) hooks remain opt-in. The LangChain run ID is sent as
 `metadata.langgraph.run_id`; every classification gets a distinct
 `metadata.silmaril.request_id`. Supply `conversationId` to the handler for
 sequence identity; it sends `metadata.conversationId`. Callback blocks throw
@@ -515,17 +567,19 @@ model, tools })` and pass its returned spec through
 `protectedCompiledSubagents`. That factory installs middleware before
 compilation. The parent constructor verifies the exact graph and Firewall
 client; it rejects arbitrary compiled runnables. Root custom middleware does
-not automatically reach every subagent.
+not automatically reach every subagent. For custom agent construction, import
+`createDeepAgentsMiddleware` from the same adapter subpath.
 
 The middleware checks input before model use, tool calls before execution,
 tool results before the next model call, and non-streamed model output before
 the graph consumes it. In Block mode, denied tool interactions become a fixed
 safe `ToolMessage` with the original call ID. The agent can choose an allowed
-alternative; repeated denials end with a fixed safe response. Denied model
-output is replaced. Shadow and Warn report decisions through `onClassify`
-without replacing content. Classification errors allow model and tool execution
-by default; set `silmaril: { failOpen: false }` to require a successful
-classification. Already emitted streaming text cannot be recalled.
+alternative; after `maxBlockedAttempts` denials (default `3`), the middleware
+returns a fixed safe final response. Denied model output is replaced. Shadow
+and Warn report decisions through `onClassify` without replacing content.
+Classification errors allow model and tool execution by default; set
+`silmaril: { failOpen: false }` to require a successful classification. Already
+emitted streaming text cannot be recalled.
 
 ## Retries
 

package/dist/index.cjs

@@ -818,7 +818,7 @@ function sanitizeText(text) {
 }
 
 // src/firewall.ts
-var SDK_VERSION = "0.7.0";
+var SDK_VERSION = "0.7.2";
 var DEFAULT_TIMEOUT_MS = 1e4;
 var DEFAULT_MAX_RETRIES = 5;
 var MAX_BACKOFF_SECONDS = 30;
@@ -962,7 +962,7 @@ async function readCappedErrorBody(response) {
   }
   return new TextDecoder().decode(body);
 }
-async function discardResponseBody(response) {
+async function releaseDiscardedResponseBody(response) {
   try {
     if (response.body) {
       if (!response.body.locked) {
@@ -974,6 +974,19 @@ async function discardResponseBody(response) {
   } catch {
   }
 }
+async function discardResponseBody(response, signal) {
+  signal.throwIfAborted();
+  let onAbort;
+  const aborted = new Promise((_resolve, reject) => {
+    onAbort = () => reject(signal.reason);
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+  try {
+    await Promise.race([releaseDiscardedResponseBody(response), aborted]);
+  } finally {
+    signal.removeEventListener("abort", onAbort);
+  }
+}
 function isAbortLikeError(error) {
   if (typeof error !== "object" || error === null) {
     return false;
@@ -999,6 +1012,7 @@ function createAttemptSignal(timeoutMs, callerSignal) {
     );
   }, timeoutMs);
   const onCallerAbort = () => {
+    clearTimeout(timer);
     controller.abort(callerSignal?.reason);
   };
   callerSignal?.addEventListener("abort", onCallerAbort, { once: true });
@@ -1109,6 +1123,14 @@ var Firewall = class {
       })
     );
     const data = await this.postWithRetry(payload, options.signal);
+    if (!Array.isArray(data.predictions)) {
+      throw new Error("Firewall: response predictions must be an array");
+    }
+    if (data.predictions.length !== payload.texts.length) {
+      throw new Error(
+        `Firewall: response predictions length ${data.predictions.length} does not match submitted texts length ${payload.texts.length}`
+      );
+    }
     return data.predictions.map((p) => blockResultFromResponse(p, requestedMode));
   }
   asLangChainHandler(options = {}) {
@@ -1148,7 +1170,7 @@ var Firewall = class {
             attemptSignal.signal
           );
         }
-        await discardResponseBody(response);
+        await discardResponseBody(response, attemptSignal.signal);
       } finally {
         attemptSignal.dispose();
       }