@paxmod/guard 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,57 @@
+Apache License
+
+Version 2.0, January 2004
+
+http://www.apache.org/licenses/ 
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2026 Paxmod

package/README.md

@@ -1,3 +1,193 @@
-# Temporary Holding Version
+# PaxmodGuard (`@paxmod/guard`)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Safety checks for AI companions, chatbots and kids' game chat, running on your own CPU. No API key, no network calls after the first model download, and no message ever leaves your server.
+
+```bash
+npm install @paxmod/guard
+```
+
+```js
+import { createGuard } from "@paxmod/guard";
+
+const guard = await createGuard(); // downloads the model once (about 220 MB) to ~/.cache/paxmod-guard
+
+// 1. Check what the user sent before your model sees it
+const input = await guard.checkInput(userMessage);
+if (input.crisisReply) return input.crisisReply; // self-harm risk: answer with crisis support, not the persona
+if (input.labels.includes("jailbreak")) return "Let's keep things friendly.";
+
+// 2. Check what your bot wrote before the user sees it
+const reply = await llm.generate(userMessage);
+const output = await guard.checkOutput(reply);
+if (output.flagged) return regenerateOrRefuse(output.labels);
+return reply;
+```
+
+Needs about 1 GB of memory: run it in a container or on a server, not in small serverless functions.
+
+Each check takes about 10 to 40 ms on an ordinary CPU (two threads), so it fits inside a chat turn. The model is a 0.3B
+multilingual encoder (fine-tuned from mmBERT); it reads a single message, a message with the turns before it, or a whole
+conversation.
+
+## Game and community chat, with context
+
+```js
+// One message between players, with the lines before it
+const r = await guard.checkChat("wanna add me on snap", {
+  context: [{ role: "player", speaker: "B", text: "im 12" }],
+});
+
+// A whole conversation: patterns no single message shows, such as grooming
+const c = await guard.checkConversation([
+  { role: "player", speaker: "A", text: "how old r u" },
+  { role: "player", speaker: "B", text: "12" },
+  { role: "player", speaker: "A", text: "cool im 24. dont tell ur mom we talk ok" },
+]);
+```
+
+## Vercel AI SDK
+
+One line: the user's message is checked before your model runs, and the model's reply before the user sees it.
+
+```js
+import { streamText, wrapLanguageModel } from "ai";
+import { guardMiddleware } from "@paxmod/guard/ai-sdk";
+
+const model = wrapLanguageModel({ model: yourModel, middleware: guardMiddleware() });
+const result = streamText({ model, messages });
+```
+
+- A user message showing self-harm risk gets the crisis reply instead of a model call.
+- Jailbreaks and sexual content involving minors are refused. Pass `block` to choose your own labels.
+- A harmful model reply is replaced with a safe fallback, and the finish reason becomes `content-filter`. When streaming, each text block is held until it is complete and checked as a whole, so a partial harmful reply never reaches the user.
+
+## OpenAI Agents SDK
+
+```js
+import { Agent, run, InputGuardrailTripwireTriggered } from "@openai/agents";
+import { guardInput, guardOutput } from "@paxmod/guard/openai-agents";
+
+const agent = new Agent({ name: "Companion", instructions, inputGuardrails: [guardInput()], outputGuardrails: [guardOutput()] });
+
+try {
+  const result = await run(agent, message);
+} catch (e) {
+  if (e instanceof InputGuardrailTripwireTriggered) {
+    reply(e.result.output.outputInfo.crisisReply ?? "Let's talk about something else.");
+  }
+}
+```
+
+The input guardrail runs before the agent, so a tripped run never calls your model.
+
+## Mastra
+
+A local replacement for an LLM-based moderation processor: milliseconds instead of a model call.
+
+```js
+import { paxmodGuard } from "@paxmod/guard/mastra";
+
+const guard = paxmodGuard();
+const agent = new Agent({ id: "companion", name: "Companion", instructions, model, inputProcessors: [guard], outputProcessors: [guard] });
+
+const result = await agent.generate(message);
+if (result.tripwire) reply(result.tripwire.metadata?.crisisReply ?? "Let's talk about something else.");
+```
+
+## LangChain
+
+A local drop-in for `openAIModerationMiddleware` in LangChain v1 agents.
+
+```js
+import { createAgent } from "langchain";
+import { paxmodGuardMiddleware } from "@paxmod/guard/langchain";
+
+const agent = createAgent({ model, tools, middleware: [paxmodGuardMiddleware()] });
+```
+
+A blocked user message ends the run with the crisis reply or a fallback, without a model call. A blocked model reply is replaced in place, so it never enters the conversation history.
+
+## What it checks
+
+48 labels, each with its own score from 0 to 1. Default labels count towards `flagged`; signal labels are always scored
+but only flag when you enable them (`enable: [...]`).
+
+| Area | Labels |
+|---|---|
+| Self-harm | `self_harm_intent` (triggers the crisis reply), `self_harm_instructions`, `eating_disorder`; signal: `distress` |
+| Sexual | `sexual`, `sexual_suggestive`, `sexual_minor`; signal: `romantic` |
+| Child safety | `minor_signal`, `grooming` (an older person plus grooming tactics), `grooming_suspected`, `image_request`, `sextortion`, `predator_report`, `abuse_disclosure`; signals: `age_inquiry`, `risk_check` (alone or supervised?), `secrecy`, `isolation`, `special_bond` |
+| Personal info | `pii_shared`, `pii_request`, `pii_other` (someone else's details), `off_platform`, `meetup` |
+| Abuse | `harassment`, `threat`, `hate`; signal: `profanity` |
+| Violence and danger | `violence`, `extremism`, `dangerous_challenge`, `weapons`, `drugs`, `crime` |
+| Fraud | `scam`, `spam` |
+| Advice | `medical_advice`, `financial_advice`, `legal_advice` |
+| AI behaviour | `jailbreak`, `prompt_injection`; from the bot: `ai_claims_human`, `ai_claims_professional`, `dependency`, `manipulation`, `ai_harmful_compliance`, `ai_hostility` |
+| General | signals: `unsafe` (any core harm), `unsafe_strict` (the broader definition public benchmarks use) |
+
+Game banter, roleplay and hyperbole are not harm by default ("gg I'm gonna kill you next round" is clean): PaxmodGuard is
+built to keep false alarms low in kids' games.
+
+Every result includes the score for each label:
+
+```js
+{
+  flagged: true,
+  labels: ["self_harm_intent"],
+  scores: { self_harm_intent: 0.97, minor_signal: 0.01, ... },
+  direction: "input",
+  latencyMs: 7.9,
+  crisisReply: "It sounds like you're going through something really painful..."
+}
+```
+
+## Options
+
+```js
+const guard = await createGuard({
+  modelDir: "./models/guard",       // use files you ship yourself, no download
+  threads: 2,                       // CPU threads per check
+  thresholds: { pii_request: 0.8 }, // per-label score needed to flag (each label ships with a tuned default)
+  enable: ["secrecy", "risk_check"],// signal labels to count towards flagged
+  includeUnsafe: true,              // also flag on the general "unsafe" score
+  crisisReply: "Your own wording, with your local crisis line.",
+});
+```
+
+Environment variables: `PAXMOD_GUARD_CACHE` (download location) and `PAXMOD_GUARD_MODEL_URL` (mirror).
+
+## Companion-chatbot laws
+
+Laws such as California SB 243 and New York's AI companion law ask operators to detect self-harm risk and point users to crisis services, to stop the bot claiming to be human, and to remind users they are talking to an AI. Guard helps with the per-message parts:
+
+```js
+import { createGuard, disclosureReminder } from "@paxmod/guard";
+
+const guard = await createGuard({
+  onCrisis: (result) => auditLog.write({ type: "crisis_referral", at: Date.now() }), // keep your own referral record
+});
+const reminder = disclosureReminder(); // at the start of a conversation, then every 3 hours
+
+const note = reminder.due(conversationId);
+if (note) reply = `${note}\n\n${reply}`;
+
+guard.stats(); // { checks, flagged, crisisReferrals, since }
+```
+
+This is engineering help, not legal advice: check your obligations with your lawyers. Age assurance, conversation-level escalation and annual reporting need more than a per-message check; [Paxmod cloud](https://www.paxmod.com) covers those.
+
+## Command line
+
+```bash
+npx @paxmod/guard check "i don't want to be here anymore"
+npx @paxmod/guard check "Let's keep this between us" --output
+npx @paxmod/guard download     # pre-fetch the model (about 220 MB), e.g. in a Docker build
+```
+
+## Paxmod cloud
+
+The local model checks messages and conversations you pass it. [Paxmod](https://www.paxmod.com) adds risk that builds across days and many conversations, a console for your safety team, a stronger model trained with production data, model updates, and compliance reporting for California SB 243 and similar laws. Get a free key without signing up:
+
+```bash
+npx @paxmod/guard key
+```

package/bin/cli.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+// paxmod-guard check "text" [--output] | download | key [--name "My bot"]
+import { createGuard, downloadModel } from "../src/index.js";
+
+const [cmd, ...rest] = process.argv.slice(2);
+const flag = (name) => { const i = rest.indexOf(name); return i >= 0 ? rest.splice(i, 2)[1] ?? true : undefined; };
+const log = (m) => console.error(m);
+
+if (cmd === "download") {
+  console.log(await downloadModel({ onProgress: log }));
+} else if (cmd === "check") {
+  const output = rest.includes("--output"); const text = rest.filter((a) => a !== "--output").join(" ");
+  if (!text) { log('Usage: paxmod-guard check "message" [--output]'); process.exit(2); }
+  const guard = await createGuard({ modelDir: process.env.PAXMOD_GUARD_MODEL_DIR, onProgress: log });
+  const r = await (output ? guard.checkOutput(text) : guard.checkInput(text));
+  console.log(JSON.stringify(r, (k, v) => (typeof v === "number" ? Math.round(v * 1000) / 1000 : v), 2));
+} else if (cmd === "key") {
+  // A capped Paxmod cloud key in one call, no signup. The developer claims it from claim_url.
+  const res = await fetch("https://www.paxmod.com/api/v1/agent-key", {
+    method: "POST", headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ name: flag("--name") ?? "Guard project", source: "paxmod-guard-cli" }),
+  });
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) { log(body?.error?.message ?? `HTTP ${res.status}`); process.exit(1); }
+  console.log(`PAXMOD_API_KEY=${body.api_key}\n\nKeep this project: ${body.claim_url}\nMessages included: ${body.messages_remaining}, expires ${body.expires_at}`);
+} else {
+  log(`paxmod-guard: local safety checks for AI companions
+
+  paxmod-guard check "message"            check a user message
+  paxmod-guard check "reply" --output     check your bot's reply
+  paxmod-guard download                   fetch the model now (about 220 MB)
+  paxmod-guard key                        get a free Paxmod cloud key, no signup`);
+  process.exit(cmd ? 2 : 0);
+}

package/package.json

@@ -1,6 +1,74 @@
 {
   "name": "@paxmod/guard",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Local safety classifier for AI companions and chatbots: self-harm, minors, sexual content, jailbreaks and more, on your own CPU in milliseconds.",
+  "main": "src/index.js",
+  "keywords": [
+    "guardrails",
+    "ai-safety",
+    "moderation",
+    "companion",
+    "chatbot",
+    "llm",
+    "onnx",
+    "sb-243"
+  ],
+  "author": "Paxmod",
+  "license": "Apache-2.0",
+  "type": "module",
+  "dependencies": {
+    "@huggingface/tokenizers": "^0.2.0",
+    "onnxruntime-node": "^1.30.0"
+  },
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./ai-sdk": {
+      "types": "./src/ai-sdk.d.ts",
+      "default": "./src/ai-sdk.js"
+    },
+    "./openai-agents": {
+      "types": "./src/openai-agents.d.ts",
+      "default": "./src/openai-agents.js"
+    },
+    "./mastra": {
+      "types": "./src/mastra.d.ts",
+      "default": "./src/mastra.js"
+    },
+    "./langchain": {
+      "types": "./src/langchain.d.ts",
+      "default": "./src/langchain.js"
+    }
+  },
+  "bin": {
+    "paxmod-guard": "bin/cli.js"
+  },
+  "files": [
+    "src",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "homepage": "https://www.paxmod.com",
+  "scripts": {
+    "demo": "node demo/server.js"
+  },
+  "peerDependencies": {
+    "langchain": ">=1.0.0",
+    "@langchain/core": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "langchain": {
+      "optional": true
+    },
+    "@langchain/core": {
+      "optional": true
+    }
+  }
+}

package/src/ai-sdk.d.ts

@@ -0,0 +1,15 @@
+import type { Guard, GuardOptions, GuardResult, GuardLabel } from "./index";
+
+export interface GuardMiddlewareOptions extends GuardOptions {
+  /** Reuse an existing guard instead of creating one. */
+  guard?: Guard | Promise<Guard>;
+  /** Labels that stop a message. Defaults: input self_harm, sexual_minor, jailbreak; output every label except minor_signal and jailbreak. */
+  block?: { input?: GuardLabel[]; output?: GuardLabel[] };
+  /** Reply used when a model output, or a non-crisis input, is blocked. */
+  fallback?: string;
+  /** Called for every flagged message, blocked or not. */
+  onFlag?: (result: GuardResult) => void;
+}
+
+/** Vercel AI SDK language model middleware (specificationVersion "v4"). */
+export function guardMiddleware(options?: GuardMiddlewareOptions): any;

package/src/ai-sdk.js

@@ -0,0 +1,114 @@
+// Vercel AI SDK middleware: checks the user's latest message before the model runs and the model's text after.
+//   import { wrapLanguageModel } from "ai";
+//   import { guardMiddleware } from "@paxmod/guard/ai-sdk";
+//   const model = wrapLanguageModel({ model: yourModel, middleware: guardMiddleware() });
+import { createGuard } from "./index.js";
+
+const DEFAULT_BLOCK = {
+  input: ["self_harm_intent", "self_harm_instructions", "sexual_minor", "grooming", "sextortion", "jailbreak", "prompt_injection"], // self_harm_intent is answered with the crisis reply
+  output: ["self_harm_instructions", "sexual_minor", "sexual", "ai_claims_human", "ai_claims_professional", "pii_other", "off_platform", "dependency", "harassment", "manipulation", "ai_hostility", "ai_harmful_compliance", "hate", "weapons", "drugs", "crime", "violence", "extremism", "dangerous_challenge"],
+};
+const DEFAULT_FALLBACK = "Sorry, I can't continue with that. Let's talk about something else.";
+const ZERO_USAGE = {
+  inputTokens: { total: 0, noCache: 0, cacheRead: 0, cacheWrite: 0 },
+  outputTokens: { total: 0, text: 0, reasoning: 0 },
+};
+
+// The text of the user's latest turn, or null when the prompt ends with a tool result or assistant turn
+// (a later step of an agent loop: that user message was already checked).
+function latestUserText(prompt) {
+  const last = prompt[prompt.length - 1];
+  if (!last || last.role !== "user") return null;
+  return last.content.filter((p) => p.type === "text").map((p) => p.text).join("\n");
+}
+
+/**
+ * @param {object} [options]
+ * @param {import("./index").Guard | Promise<import("./index").Guard>} [options.guard] reuse a guard; default creates one
+ * @param {{ input?: string[], output?: string[] }} [options.block] labels that stop a message (defaults above)
+ * @param {string} [options.fallback] reply used when the model's output is blocked or a non-crisis input is blocked
+ * @param {(result: import("./index").GuardResult) => void} [options.onFlag] called for every flagged message, blocked or not
+ */
+export function guardMiddleware(options = {}) {
+  const guard = Promise.resolve(options.guard ?? createGuard(options));
+  const block = { input: options.block?.input ?? DEFAULT_BLOCK.input, output: options.block?.output ?? DEFAULT_BLOCK.output };
+  const fallback = options.fallback ?? DEFAULT_FALLBACK;
+  const blocks = (r, list) => r.labels.some((l) => list.includes(l));
+  const meta = (r) => ({ paxmodGuard: { direction: r.direction, labels: r.labels, blocked: true } });
+
+  async function checkInput(params) {
+    const text = latestUserText(params.prompt);
+    if (!text) return null;
+    const r = await (await guard).checkInput(text);
+    if (r.flagged) options.onFlag?.(r);
+    if (!blocks(r, block.input)) return null;
+    return { text: r.crisisReply ?? fallback, result: r };
+  }
+
+  async function checkOutput(text) {
+    const r = await (await guard).checkOutput(text);
+    if (r.flagged) options.onFlag?.(r);
+    return blocks(r, block.output) ? r : null;
+  }
+
+  return {
+    specificationVersion: "v4",
+
+    async wrapGenerate({ doGenerate, params }) {
+      const stop = await checkInput(params);
+      if (stop) {
+        return { content: [{ type: "text", text: stop.text }], finishReason: { unified: "content-filter", raw: "paxmod-guard" },
+                 usage: ZERO_USAGE, warnings: [], providerMetadata: meta(stop.result) };
+      }
+      const result = await doGenerate();
+      const text = result.content.filter((p) => p.type === "text").map((p) => p.text).join("");
+      const bad = text && (await checkOutput(text));
+      if (!bad) return result;
+      return { ...result, content: [{ type: "text", text: fallback }, ...result.content.filter((p) => p.type !== "text")],
+               finishReason: { unified: "content-filter", raw: "paxmod-guard" }, providerMetadata: { ...result.providerMetadata, ...meta(bad) } };
+    },
+
+    async wrapStream({ doStream, params }) {
+      const stop = await checkInput(params);
+      if (stop) {
+        const parts = [
+          { type: "stream-start", warnings: [] },
+          { type: "text-start", id: "paxmod-guard" },
+          { type: "text-delta", id: "paxmod-guard", delta: stop.text },
+          { type: "text-end", id: "paxmod-guard" },
+          { type: "finish", usage: ZERO_USAGE, finishReason: { unified: "content-filter", raw: "paxmod-guard" }, providerMetadata: meta(stop.result) },
+        ];
+        return { stream: new ReadableStream({ start(c) { parts.forEach((p) => c.enqueue(p)); c.close(); } }) };
+      }
+      const { stream, ...rest } = await doStream();
+      // Each text block is held until it ends, then checked as a whole and released or replaced: a partial
+      // harmful reply never reaches the user. The check adds a few milliseconds after the block finishes.
+      const buffers = new Map();
+      let blocked = false;
+      const transform = new TransformStream({
+        async transform(chunk, controller) {
+          if (chunk.type === "text-start") { buffers.set(chunk.id, ""); controller.enqueue(chunk); return; }
+          if (chunk.type === "text-delta" && buffers.has(chunk.id)) { buffers.set(chunk.id, buffers.get(chunk.id) + chunk.delta); return; }
+          if (chunk.type === "text-end" && buffers.has(chunk.id)) {
+            const text = buffers.get(chunk.id); buffers.delete(chunk.id);
+            const bad = text && (await checkOutput(text));
+            if (bad) blocked = true;
+            if (text) controller.enqueue({ type: "text-delta", id: chunk.id, delta: bad ? fallback : text });
+          }
+          if (chunk.type === "finish" && blocked) {
+            controller.enqueue({ ...chunk, finishReason: { unified: "content-filter", raw: "paxmod-guard" } });
+            return;
+          }
+          controller.enqueue(chunk);
+        },
+        async flush(controller) {
+          for (const [id, text] of buffers) {
+            const bad = text && (await checkOutput(text));
+            if (text) controller.enqueue({ type: "text-delta", id, delta: bad ? fallback : text });
+          }
+        },
+      });
+      return { stream: stream.pipeThrough(transform), ...rest };
+    },
+  };
+}

package/src/index.d.ts

@@ -0,0 +1,98 @@
+export type GuardLabel =
+  | "self_harm_intent" | "self_harm_instructions" | "eating_disorder" | "distress"
+  | "sexual" | "sexual_suggestive" | "romantic" | "sexual_minor"
+  | "minor_signal" | "age_inquiry" | "grooming" | "grooming_suspected"
+  | "risk_check" | "secrecy" | "isolation" | "special_bond"
+  | "image_request" | "sextortion" | "predator_report" | "abuse_disclosure"
+  | "pii_shared" | "pii_request" | "pii_other" | "off_platform" | "meetup"
+  | "harassment" | "threat" | "hate" | "profanity"
+  | "violence" | "extremism" | "dangerous_challenge" | "weapons" | "drugs" | "crime" | "scam" | "spam"
+  | "medical_advice" | "financial_advice" | "legal_advice"
+  | "jailbreak" | "prompt_injection" | "ai_claims_human" | "ai_claims_professional"
+  | "dependency" | "manipulation" | "ai_harmful_compliance" | "ai_hostility" | "unsafe";
+
+/** Labels that are scored on every check but only flag when listed in `enable`. */
+export type SignalLabel = "unsafe" | "unsafe_strict" | "distress" | "risk_check" | "secrecy" | "isolation" | "special_bond" | "profanity" | "age_inquiry" | "romantic";
+
+export interface GuardOptions {
+  /** Use model files already on disk instead of downloading. */
+  modelDir?: string;
+  /** Where downloaded models are kept. Default ~/.cache/paxmod-guard (or PAXMOD_GUARD_CACHE). */
+  cacheDir?: string;
+  /** Base URL to download model files from (or PAXMOD_GUARD_MODEL_URL). */
+  modelUrl?: string;
+  /** CPU threads per check. Default 2. */
+  threads?: number;
+  /** Per-label score needed to flag, 0 to 1. Defaults come with the model. */
+  thresholds?: Partial<Record<GuardLabel, number>>;
+  /** Signal labels to count towards flagged/labels (off by default), e.g. ["risk_check", "secrecy", "profanity"]. */
+  enable?: SignalLabel[];
+  /** Same as enable: ["unsafe"]. Kept for older code. */
+  includeUnsafe?: boolean;
+  /** Reply suggested when a user message shows self-harm risk. */
+  crisisReply?: string;
+  /** Called when a user message is flagged self_harm_intent and a crisis reply is suggested (e.g. to log the referral). */
+  onCrisis?: (result: GuardResult) => void;
+  /** Overlapping-window size for long messages, in tokens. Default 128. */
+  windowTokens?: number;
+  onProgress?: (message: string) => void;
+}
+
+export interface GuardResult {
+  flagged: boolean;
+  labels: GuardLabel[];
+  scores: Record<GuardLabel, number>;
+  direction: "input" | "output" | "chat";
+  latencyMs: number;
+  /** Present when a user message is flagged self_harm_intent: a safe reply that points to crisis support. */
+  crisisReply?: string;
+}
+
+export interface Turn {
+  /** user = a person writing to an AI, ai = the AI, player = a person writing to other people. */
+  role?: "user" | "ai" | "player";
+  /** Who wrote it, for player turns: any short stable id per conversation, e.g. "A". */
+  speaker?: string;
+  text: string;
+}
+
+export interface CheckOptions {
+  /** Earlier messages, oldest first (v9 and later models). The oldest are dropped if they do not fit. */
+  context?: Turn[];
+}
+
+export interface ConversationResult {
+  flagged: boolean;
+  labels: GuardLabel[];
+  scores: Record<GuardLabel, number>;
+  turns: number;
+  latencyMs: number;
+}
+
+export interface Guard {
+  model: string;
+  labels: GuardLabel[];
+  /** input = a person writing to an AI, output = the AI's reply, chat = a person writing to other people. */
+  check(text: string, direction?: "input" | "output" | "chat", options?: CheckOptions): Promise<GuardResult>;
+  checkInput(text: string, options?: CheckOptions): Promise<GuardResult>;
+  checkOutput(text: string, options?: CheckOptions): Promise<GuardResult>;
+  /** A message one person wrote to others, e.g. game chat. */
+  checkChat(text: string, options?: CheckOptions): Promise<GuardResult>;
+  /** Judge a whole stretch of conversation (v9 and later models), e.g. a DM with both sides. */
+  checkConversation(turns: Turn[]): Promise<ConversationResult>;
+  /** True for models that read context and whole conversations (v9 and later). */
+  contextual: boolean;
+  stats(): { checks: number; flagged: number; crisisReferrals: number; since: string };
+  close(): Promise<void>;
+}
+
+export const DEFAULT_DISCLOSURE: string;
+export function disclosureReminder(options?: { everyMs?: number; text?: string; now?: () => number }): {
+  due(conversationId: string): string | null;
+  forget(conversationId: string): boolean;
+};
+
+export const MODEL_VERSION: string;
+export const DEFAULT_CRISIS_REPLY: string;
+export function createGuard(options?: GuardOptions): Promise<Guard>;
+export function downloadModel(options?: Pick<GuardOptions, "cacheDir" | "modelUrl" | "onProgress">): Promise<string>;

package/src/index.js

@@ -0,0 +1,214 @@
+// @paxmod/guard: a local safety classifier for AI companions and chatbots.
+// Runs Paxmod's Guard model on your own CPU with ONNX Runtime. No API calls, no data leaves the machine.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import * as ort from "onnxruntime-node";
+import { Tokenizer } from "@huggingface/tokenizers";
+
+export const MODEL_VERSION = "paxmodguard-v1";
+const MODEL_FILES = ["model.int8.onnx", "tokenizer.json", "tokenizer_config.json", "guard.json"];
+// One folder per model version in the repo (paxmodguard-v1: about 220 MB).
+const DEFAULT_MODEL_URL = "https://huggingface.co/paxmod/guard/resolve/main";
+const modelName = () => MODEL_VERSION;
+
+export const DEFAULT_CRISIS_REPLY =
+  "It sounds like you're going through something really painful, and I'm glad you told me. " +
+  "I'm an AI, so please reach out to someone who can help right now. In the US you can call or text 988 " +
+  "(Suicide & Crisis Lifeline). Elsewhere, findahelpline.com lists free, confidential lines in your country.";
+
+function defaultCacheDir() {
+  if (process.env.PAXMOD_GUARD_CACHE) return process.env.PAXMOD_GUARD_CACHE;
+  const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache");
+  return path.join(base, "paxmod-guard");
+}
+
+/** Download the model files into `dir` if they are not there yet. Returns the directory. */
+export async function downloadModel({ cacheDir = defaultCacheDir(), modelUrl = process.env.PAXMOD_GUARD_MODEL_URL || DEFAULT_MODEL_URL, onProgress } = {}) {
+  const name = modelName();
+  const dir = path.join(cacheDir, name);
+  fs.mkdirSync(dir, { recursive: true });
+  for (const file of MODEL_FILES) {
+    const dest = path.join(dir, file);
+    if (fs.existsSync(dest)) continue;
+    onProgress?.(`Downloading ${file}`);
+    const res = await fetch(`${modelUrl}/${name}/${file}`);
+    if (!res.ok) throw new Error(`@paxmod/guard: could not download ${file} (HTTP ${res.status}) from ${modelUrl}`);
+    const part = `${dest}.${process.pid}.part`;
+    fs.writeFileSync(part, Buffer.from(await res.arrayBuffer()));
+    fs.renameSync(part, dest); // atomic: a half-written file is never mistaken for a finished one
+  }
+  return dir;
+}
+
+/**
+ * Load the Guard model. Downloads it on first use (about 220 MB) unless `modelDir` points at local files.
+ * @param {import("./index").GuardOptions} [options]
+ */
+export async function createGuard(options = {}) {
+  const dir = options.modelDir ?? (await downloadModel(options));
+  const read = (f) => JSON.parse(fs.readFileSync(path.join(dir, f), "utf8"));
+  const meta = read("guard.json");
+  const labels = meta.labels;
+  const thresholds = { ...meta.thresholds, ...(options.thresholds ?? {}) };
+  const maxLength = meta.max_length ?? 256;
+  const tokenizer = new Tokenizer(read("tokenizer.json"), read("tokenizer_config.json"));
+  const session = await ort.InferenceSession.create(path.join(dir, "model.int8.onnx"), {
+    intraOpNumThreads: options.threads ?? 2,
+    executionProviders: ["cpu"],
+  });
+  const crisisReply = options.crisisReply ?? DEFAULT_CRISIS_REPLY;
+  // Signal labels (grooming tactics, distress, swearing, age questions, romance, the general "unsafe" score) are
+  // scored on every check but only count towards flagged/labels when enabled. Older models list none.
+  const enabled = new Set(options.enable ?? []);
+  if (options.includeUnsafe) enabled.add("unsafe");
+  const off = new Set((meta.default_off ?? ["unsafe"]).filter((l) => !enabled.has(l)));
+  const counts = (l, scores) => !off.has(l) && scores[l] >= (thresholds[l] ?? 0.5);
+  // v10 renamed self_harm to self_harm_intent; either triggers the crisis reply.
+  const CRISIS = ["self_harm_intent", "self_harm"];
+  // Crisis referrals made, for the counts companion-chatbot laws ask operators to report (e.g. California SB 243).
+  const stats = { checks: 0, flagged: 0, crisisReferrals: 0, since: new Date().toISOString() };
+
+  // Long messages are split into overlapping windows at two sizes, full-length for context and short so one
+  // bad sentence in a long message is not drowned out. A label's score is its highest across all windows.
+  // Context and conversation inputs only use full-length windows: they are already structured and cut as in training.
+  // Runs of spaces are collapsed to one: the JS tokenizer splits them differently from the Python one the model
+  // was trained with, and a single space means the same thing.
+  function windows(text, short = true) {
+    const ids = tokenizer.encode(text.replace(/ {2,}/g, " ")).ids;
+    const cls = ids[0], sep = ids[ids.length - 1], body = ids.slice(1, -1);
+    const sizes = [maxLength - 2, Math.min(maxLength, options.windowTokens ?? 128) - 2].filter((n, i, a) => i === 0 || (short && n < a[0] && body.length > n));
+    const out = [];
+    for (const size of sizes) {
+      const stride = Math.floor(size * 0.75);
+      for (let i = 0; ; i += stride) {
+        out.push([cls, ...body.slice(i, i + size), sep]);
+        if (i + size >= body.length) break;
+      }
+    }
+    return out;
+  }
+
+  // texts: one or more inputs; a label's score is its highest over every window of every input.
+  async function score(texts, short = true) {
+    const all = [].concat(texts).flatMap((t) => windows(t, short)).sort((a, b) => a.length - b.length);
+    const best = new Float64Array(labels.length).fill(-Infinity);
+    for (let k = 0; k < all.length; k += 8) { // small batches of similar length: little padding
+      const batch = all.slice(k, k + 8), len = batch[batch.length - 1].length;
+      const ids = new BigInt64Array(batch.length * len), mask = new BigInt64Array(batch.length * len);
+      batch.forEach((w, b) => w.forEach((id, i) => { ids[b * len + i] = BigInt(id); mask[b * len + i] = 1n; }));
+      const out = await session.run({
+        input_ids: new ort.Tensor("int64", ids, [batch.length, len]),
+        attention_mask: new ort.Tensor("int64", mask, [batch.length, len]),
+      });
+      const logits = out.logits.data;
+      for (let b = 0; b < batch.length; b++) for (let j = 0; j < labels.length; j++) best[j] = Math.max(best[j], logits[b * labels.length + j]);
+    }
+    return Object.fromEntries(labels.map((l, j) => [l, 1 / (1 + Math.exp(-best[j]))]));
+  }
+
+  // v9 models (guard-v9 and later) read the messages before the one being checked, and whole conversations.
+  // Their input tags each turn by who wrote it: [USER] to an AI, [AI], or [CHAT:<speaker>] between people.
+  const contextual = labels.includes("grooming");
+  const cut = (t, n = 300) => (t.length <= n ? t : t.slice(0, n) + "…"); // as in training: 300 for earlier turns
+  const tag = (turn) => {
+    const role = turn.role ?? (turn.direction === "output" ? "ai" : turn.direction === "chat" ? "player" : "user");
+    if (role === "ai") return "[AI]";
+    if (role === "player") return turn.speaker ? `[CHAT:${turn.speaker}]` : "[CHAT]";
+    return "[USER]";
+  };
+  const tokens = (t) => tokenizer.encode(t).ids.length;
+
+  /** Render the target with as many earlier turns as fit (the oldest are dropped first). */
+  function withContext(text, direction, context) {
+    const target = `[TARGET] ${tag({ direction })} ${cut(text, 1000)}`; // the judged turn: 1000, as in training
+    const earlier = context.map((t) => `${tag(t)} ${cut(t.text ?? "")}`);
+    for (let k = 0; k <= earlier.length; k++) {
+      const s = [...earlier.slice(k), target].join(" ");
+      if (k === earlier.length || tokens(s) <= maxLength) return s;
+    }
+  }
+
+  /**
+   * @param {string} text
+   * @param {"input"|"output"|"chat"} direction input = a person writing to an AI, output = the AI, chat = a person writing to other people
+   * @param {{context?: {role?: "user"|"ai"|"player", direction?: string, speaker?: string, text: string}[]}} [opts]
+   */
+  async function check(text, direction = "input", opts = {}) {
+    if (typeof text !== "string") throw new TypeError("@paxmod/guard: text must be a string");
+    const t0 = performance.now();
+    const input = !contextual ? `${direction === "output" ? "[AI]" : "[USER]"} ${text}`
+      : opts.context?.length ? withContext(text, direction, opts.context)
+      : `${direction === "chat" ? "[CHAT]" : tag({ direction })} ${text}`; // a single message is read whole, in windows
+    const scores = text.trim() ? await score(input, !(contextual && opts.context?.length)) : Object.fromEntries(labels.map((l) => [l, 0]));
+    const flagged = labels.filter((l) => counts(l, scores));
+    const result = { flagged: flagged.length > 0, labels: flagged, scores, direction, latencyMs: Math.round((performance.now() - t0) * 10) / 10 };
+    stats.checks++;
+    if (result.flagged) stats.flagged++;
+    if (direction !== "output" && CRISIS.some((l) => flagged.includes(l))) {
+      result.crisisReply = crisisReply;
+      stats.crisisReferrals++;
+      options.onCrisis?.(result);
+    }
+    return result;
+  }
+
+  /**
+   * Judge a whole stretch of conversation (v9 and later), e.g. a DM with both sides. Labels describe anything in it,
+   * including patterns no single message shows (grooming). Long conversations are read in overlapping windows.
+   * @param {{role?: "user"|"ai"|"player", direction?: string, speaker?: string, text: string}[]} turns
+   */
+  async function checkConversation(turns) {
+    if (!contextual) throw new Error("@paxmod/guard: checkConversation needs a v9 or later model");
+    const t0 = performance.now();
+    // As in training: windows of up to 40 turns, overlapping by half, so long chats are read piece by piece.
+    const parts = [];
+    for (let i = 0; ; i += 20) {
+      parts.push("[CONVERSATION] " + turns.slice(i, i + 40).map((t) => `${tag(t)} ${cut(t.text ?? "")}`).join(" "));
+      if (i + 40 >= turns.length) break;
+    }
+    const scores = await score(parts, false);
+    const flagged = labels.filter((l) => counts(l, scores));
+    stats.checks++;
+    if (flagged.length) stats.flagged++;
+    return { flagged: flagged.length > 0, labels: flagged, scores, turns: turns.length, latencyMs: Math.round((performance.now() - t0) * 10) / 10 };
+  }
+
+  return {
+    model: meta.version ?? modelName(),
+    labels,
+    check,
+    /** Check a message from the user before your bot sees it. */
+    checkInput: (text, opts) => check(text, "input", opts),
+    /** Check your bot's reply before the user sees it. */
+    checkOutput: (text, opts) => check(text, "output", opts),
+    /** Check a message one person wrote to others (game or community chat). */
+    checkChat: (text, opts) => check(text, "chat", opts),
+    checkConversation,
+    /** True for models that read context and whole conversations (v9 and later). */
+    contextual,
+    /** Counts since this guard was created: checks, flagged messages, crisis referrals. */
+    stats: () => ({ ...stats }),
+    close: () => session.release(),
+  };
+}
+
+export const DEFAULT_DISCLOSURE = "Just a reminder: I'm an AI, not a person. It might be a good moment to take a break.";
+
+/**
+ * Periodic "I'm an AI" reminders, per conversation. Some companion-chatbot laws require one at least every
+ * 3 hours (for example New York, and California for users known to be minors).
+ * Call due(conversationId) on each bot turn; it returns the reminder text when one is owed, otherwise null.
+ */
+export function disclosureReminder({ everyMs = 3 * 60 * 60 * 1000, text = DEFAULT_DISCLOSURE, now = () => Date.now() } = {}) {
+  const last = new Map();
+  return {
+    due(conversationId) {
+      const t = now(), prev = last.get(conversationId);
+      if (prev === undefined) { last.set(conversationId, t); return text; } // disclose at the start
+      if (t - prev >= everyMs) { last.set(conversationId, t); return text; }
+      return null;
+    },
+    forget: (conversationId) => last.delete(conversationId),
+  };
+}

package/src/langchain.d.ts

@@ -0,0 +1,4 @@
+import type { GuardMiddlewareOptions } from "./ai-sdk";
+
+/** LangChain v1 agent middleware (createAgent). Requires the langchain and @langchain/core packages. */
+export function paxmodGuardMiddleware(options?: GuardMiddlewareOptions): any;

package/src/langchain.js

@@ -0,0 +1,50 @@
+// LangChain (v1 createAgent) middleware, a local drop-in for openAIModerationMiddleware.
+//   import { createAgent } from "langchain";
+//   import { paxmodGuardMiddleware } from "@paxmod/guard/langchain";
+//   const agent = createAgent({ model, tools, middleware: [paxmodGuardMiddleware()] });
+// A blocked user message ends the run with the crisis reply (self-harm) or the fallback, without calling the model.
+// A blocked model reply is replaced in place (same message id), so it never enters the history, and the run ends.
+import { createMiddleware } from "langchain";
+import { AIMessage, HumanMessage } from "@langchain/core/messages";
+import { createGuard } from "./index.js";
+
+const DEFAULT_BLOCK = {
+  input: ["self_harm_intent", "self_harm_instructions", "sexual_minor", "grooming", "sextortion", "jailbreak", "prompt_injection"], // self_harm_intent is answered with the crisis reply
+  output: ["self_harm_instructions", "sexual_minor", "sexual", "ai_claims_human", "ai_claims_professional", "pii_other", "off_platform", "dependency", "harassment", "manipulation", "ai_hostility", "ai_harmful_compliance", "hate", "weapons", "drugs", "crime", "violence", "extremism", "dangerous_challenge"],
+};
+const DEFAULT_FALLBACK = "Sorry, I can't continue with that. Let's talk about something else.";
+
+/** @param {import("./ai-sdk").GuardMiddlewareOptions} [options] */
+export function paxmodGuardMiddleware(options = {}) {
+  const guard = Promise.resolve(options.guard ?? createGuard(options));
+  const block = { input: options.block?.input ?? DEFAULT_BLOCK.input, output: options.block?.output ?? DEFAULT_BLOCK.output };
+  const fallback = options.fallback ?? DEFAULT_FALLBACK;
+  const blocks = (r, list) => r.labels.some((l) => list.includes(l));
+
+  return createMiddleware({
+    name: "PaxmodGuardMiddleware",
+    beforeModel: {
+      canJumpTo: ["end"],
+      hook: async (state) => {
+        const last = state.messages?.[state.messages.length - 1];
+        // Only on a fresh user turn: later steps of a tool loop would re-check the same message.
+        if (!last || !HumanMessage.isInstance(last) || !last.text) return;
+        const r = await (await guard).checkInput(last.text);
+        if (r.flagged) options.onFlag?.(r);
+        if (!blocks(r, block.input)) return;
+        return { jumpTo: "end", messages: [new AIMessage({ content: r.crisisReply ?? fallback, response_metadata: { paxmodGuard: r } })] };
+      },
+    },
+    afterModel: {
+      canJumpTo: ["end"],
+      hook: async (state) => {
+        const last = state.messages?.[state.messages.length - 1];
+        if (!last || !AIMessage.isInstance(last) || !last.text) return;
+        const r = await (await guard).checkOutput(last.text);
+        if (r.flagged) options.onFlag?.(r);
+        if (!blocks(r, block.output)) return;
+        return { jumpTo: "end", messages: [new AIMessage({ id: last.id, content: fallback, response_metadata: { paxmodGuard: r } })] };
+      },
+    },
+  });
+}

package/src/mastra.d.ts

@@ -0,0 +1,4 @@
+import type { GuardMiddlewareOptions } from "./ai-sdk";
+
+/** Mastra input and output processor. On a block, the run's tripwire metadata is the GuardResult (with crisisReply on self-harm). */
+export function paxmodGuard(options?: Omit<GuardMiddlewareOptions, "fallback">): any;

package/src/mastra.js

@@ -0,0 +1,53 @@
+// Mastra processor: a local, millisecond replacement for an LLM-based moderation processor.
+//   import { paxmodGuard } from "@paxmod/guard/mastra";
+//   const guard = paxmodGuard();
+//   const agent = new Agent({ ..., inputProcessors: [guard], outputProcessors: [guard] });
+//   const result = await agent.generate(message);
+//   if (result.tripwire) reply(result.tripwire.metadata?.crisisReply ?? "Let's talk about something else.");
+import { createGuard } from "./index.js";
+
+const DEFAULT_BLOCK = {
+  input: ["self_harm_intent", "self_harm_instructions", "sexual_minor", "grooming", "sextortion", "jailbreak", "prompt_injection"], // self_harm_intent is answered with the crisis reply
+  output: ["self_harm_instructions", "sexual_minor", "sexual", "ai_claims_human", "ai_claims_professional", "pii_other", "off_platform", "dependency", "harassment", "manipulation", "ai_hostility", "ai_harmful_compliance", "hate", "weapons", "drugs", "crime", "violence", "extremism", "dangerous_challenge"],
+};
+
+function text(message) {
+  const parts = message?.content?.parts;
+  const t = Array.isArray(parts) ? parts.filter((p) => p.type === "text").map((p) => p.text).join("\n") : "";
+  return t || (typeof message?.content?.content === "string" ? message.content.content : "");
+}
+
+const latest = (messages, role) => [...messages].reverse().find((m) => m.role === role);
+
+/**
+ * @param {import("./ai-sdk").GuardMiddlewareOptions} [options] same options as the other adapters (guard, block, onFlag, model options)
+ */
+export function paxmodGuard(options = {}) {
+  const guard = Promise.resolve(options.guard ?? createGuard(options));
+  const block = { input: options.block?.input ?? DEFAULT_BLOCK.input, output: options.block?.output ?? DEFAULT_BLOCK.output };
+
+  async function check(message, direction, abort) {
+    const t = text(message);
+    if (!t.trim()) return;
+    const g = await guard;
+    const r = await (direction === "input" ? g.checkInput(t) : g.checkOutput(t));
+    if (r.flagged) options.onFlag?.(r);
+    if (r.labels.some((l) => block[direction].includes(l))) {
+      abort(`PaxmodGuard: ${r.labels.join(", ")}`, { metadata: r });
+    }
+  }
+
+  return {
+    id: "paxmod-guard",
+    name: "PaxmodGuard",
+    description: "Local safety classifier for companion chatbots (self-harm, minors, sexual content, jailbreaks and more).",
+    async processInput({ messages, abort }) {
+      await check(latest(messages, "user"), "input", abort);
+      return messages;
+    },
+    async processOutputResult({ messages, abort }) {
+      await check(latest(messages, "assistant"), "output", abort);
+      return messages;
+    },
+  };
+}

package/src/openai-agents.d.ts

@@ -0,0 +1,14 @@
+import type { Guard, GuardOptions, GuardResult, GuardLabel } from "./index";
+
+export interface GuardrailOptions extends GuardOptions {
+  /** Reuse an existing guard instead of creating one. Pass the same options object to guardInput and guardOutput to share one model. */
+  guard?: Guard;
+  /** Labels that trip the guardrail. */
+  block?: { input?: GuardLabel[]; output?: GuardLabel[] };
+  onFlag?: (result: GuardResult) => void;
+}
+
+/** InputGuardrail for @openai/agents. outputInfo is the GuardResult (with crisisReply on self-harm). */
+export function guardInput(options?: GuardrailOptions): any;
+/** OutputGuardrail for @openai/agents. */
+export function guardOutput(options?: GuardrailOptions): any;

package/src/openai-agents.js

@@ -0,0 +1,64 @@
+// OpenAI Agents SDK guardrails. A flagged message trips the run; catch the error and use the crisis reply.
+//   import { Agent, run, InputGuardrailTripwireTriggered } from "@openai/agents";
+//   import { guardInput, guardOutput } from "@paxmod/guard/openai-agents";
+//   const agent = new Agent({ name: "Companion", instructions, inputGuardrails: [guardInput()], outputGuardrails: [guardOutput()] });
+//   try { await run(agent, message) } catch (e) {
+//     if (e instanceof InputGuardrailTripwireTriggered) reply(e.result.output.outputInfo.crisisReply ?? "Let's talk about something else.");
+//   }
+import { createGuard } from "./index.js";
+
+const DEFAULT_BLOCK = {
+  input: ["self_harm_intent", "self_harm_instructions", "sexual_minor", "grooming", "sextortion", "jailbreak", "prompt_injection"], // self_harm_intent is answered with the crisis reply
+  output: ["self_harm_instructions", "sexual_minor", "sexual", "ai_claims_human", "ai_claims_professional", "pii_other", "off_platform", "dependency", "harassment", "manipulation", "ai_hostility", "ai_harmful_compliance", "hate", "weapons", "drugs", "crime", "violence", "extremism", "dangerous_challenge"],
+};
+
+// The latest user message: input is a string, or a list of items where user messages carry a string or text parts.
+function latestUserText(input) {
+  if (typeof input === "string") return input;
+  for (let i = input.length - 1; i >= 0; i--) {
+    const item = input[i];
+    if (item?.role !== "user") continue;
+    if (typeof item.content === "string") return item.content;
+    return (item.content ?? []).filter((p) => typeof p?.text === "string").map((p) => p.text).join("\n");
+  }
+  return "";
+}
+
+const shared = new WeakMap();
+function guardFor(options) {
+  if (options.guard) return Promise.resolve(options.guard);
+  // One model per options object, so guardInput(opts) and guardOutput(opts) share it.
+  if (!shared.has(options)) shared.set(options, createGuard(options));
+  return shared.get(options);
+}
+
+/** Input guardrail. Runs before the agent (not in parallel), so a tripped run never calls the model. */
+export function guardInput(options = {}) {
+  const block = options.block?.input ?? DEFAULT_BLOCK.input;
+  return {
+    name: "paxmod-guard-input",
+    runInParallel: false,
+    async execute({ input }) {
+      const text = latestUserText(input);
+      if (!text.trim()) return { tripwireTriggered: false, outputInfo: null };
+      const r = await (await guardFor(options)).checkInput(text);
+      if (r.flagged) options.onFlag?.(r);
+      return { tripwireTriggered: r.labels.some((l) => block.includes(l)), outputInfo: r };
+    },
+  };
+}
+
+/** Output guardrail: checks the agent's final text output. */
+export function guardOutput(options = {}) {
+  const block = options.block?.output ?? DEFAULT_BLOCK.output;
+  return {
+    name: "paxmod-guard-output",
+    async execute({ agentOutput }) {
+      const text = typeof agentOutput === "string" ? agentOutput : JSON.stringify(agentOutput ?? "");
+      if (!text.trim()) return { tripwireTriggered: false, outputInfo: null };
+      const r = await (await guardFor(options)).checkOutput(text);
+      if (r.flagged) options.onFlag?.(r);
+      return { tripwireTriggered: r.labels.some((l) => block.includes(l)), outputInfo: r };
+    },
+  };
+}