@gnldev/processors 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 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:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) 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
+
+      (d) 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
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Karaca Yılmaz (https://gnl.dev)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,121 @@
+# @gnldev/processors
+
+**Input/output processors** for `@gnldev/durable` agents: PII masking, moderation, tool filtering, safety.
+Built-ins inherit durability — input processors run before `persistInput` (masking is journaled → doesn't
+run again on resume).
+
+> Install: `pnpm add @gnldev/processors` — or use it from a [repo clone](https://github.com/Karaca7/gnldev): `pnpm install && pnpm -r build`.
+
+```bash
+npm i @gnldev/processors   # peer: @gnldev/durable
+```
+
+```ts
+import { runDurable } from '@gnldev/durable';
+import { piiRedactor, moderationProcessor, toolFilter } from '@gnldev/processors';
+
+await runDurable({
+  runId: 'r1', journal, model, prompt: '...',
+  processors: [
+    piiRedactor(),                                    // mask email/phone/card
+    moderationProcessor({ blocklist: ['...'] }),      // tripwire on blocked content
+    toolFilter({ allow: ['searchPolicy', 'lookupOrder'] }), // restrict the tool set the model sees
+  ],
+});
+```
+
+## API
+- `piiRedactor(opts?)` · `moderationProcessor(opts?)` · `toolFilter(opts?)`
+- `tokenLimit(...)` · `promptInjectionDetector(...)` · `outputLimit(...)`
+- `piiTextRedactor(opts?) → (text: string) => string` — the same masking as `piiRedactor`, as a plain
+  string function, for text that never passes through a processor at all. A `Processor` only sees
+  `processInput`/`processOutput`/`processToolResult`; a run's failure message is written by
+  `recordRunOutcome` in `@gnldev/durable` and no processor is consulted about it, yet it can carry user
+  data (providers echo the offending input back when refusing). Wire it wherever that message is
+  shipped onward — `@gnldev/otel`'s `redact` option is the case it was added for. Takes `types`/`mask`
+  and shares `piiRedactor`'s defaults, on purpose: two copies of the defaults is how the redacted path
+  and the un-redacted one drift apart.
+- Lower-level: `redactString`, `redactMessages`, `PII_PATTERNS`, `PII_VALIDATORS`, `PiiPattern`, `luhn`, `ibanMod97`
+
+### Checksums: why any sixteen digits is not a card
+
+Some identifiers carry their own check digit, so whether a match is real is arithmetic rather than a
+guess. `creditCard` is validated with Luhn and `iban` with mod-97, and a match that fails its own
+check is left alone:
+
+| Text | Masked |
+|---|---|
+| `kart 4111 1111 1111 1111` | yes — Luhn holds |
+| `siparis 1234567812345678` | **no** — same shape, not a card |
+| `TR330006100519786457841326` | yes — mod-97 holds |
+| one digit changed | **no** |
+
+The trade is real: a card typed with a wrong digit fails Luhn and is then not masked. Pass
+`validate: false` to mask on shape alone — blunter, corrupts more text, but cannot be talked out of
+masking anything.
+
+`phone` has no checksum to appeal to, so it is bounded by shape instead: 7–15 digits, and short
+groups once a number is split. That replaced a pattern which counted *characters*, and so masked
+`2024-01-15 10` out of a timestamp, the whole of `1.2.3 - 4.5.6`, and a run id — text corruption in
+exactly the payload it most often runs over. It is checked against 24 written forms across a dozen
+countries, and against non-PII text that has to survive — both directions, because a first attempt
+verified against a set chosen *after* the rule was written passed while `+49 30 12345678`,
+`+90 5321112233` and `0212 5551234` were going through unmasked.
+
+A match that fails its checksum is **skipped, not consumed**. That matters: with a plain
+`String.replace`, a candidate spanning `1234567890 555-123-4567` failed the digit count and took the
+real number out of reach of every later pattern — a leak caused by the validator meant to prevent one.
+
+### Masking an identifier the built-ins cannot name
+
+National ids are a per-country long tail, so they are not shipped here — `extraPatterns` is how you
+add your own, with the same checksum power the built-ins have:
+
+```ts
+import { piiRedactor } from '@gnldev/processors';
+
+piiRedactor({
+  extraPatterns: [
+    { name: 'mrn', pattern: /\bMRN-\d{6}\b/g },
+    // `test` is where the identifier's own checksum goes, so a custom pattern is as precise as a built-in.
+    { name: 'tckn', pattern: /\b\d{11}\b/g, mask: '[TCKN]', test: (v) => v[10] === String(
+      ([...v.slice(0, 10)].reduce((n, d) => n + Number(d), 0)) % 10) },
+  ],
+});
+```
+
+They run **before** the built-ins, and that ordering is load-bearing: `phone` would otherwise reach an
+11-digit national id first and mask it under the wrong name — which would also make the audit report
+say the wrong type. Custom names appear in `recordProcessorReport` alongside the built-in ones, and
+the counts come off the same call that performs the redaction, so the report cannot describe a masking
+that did not run. A pattern without the `g` flag gets it added, rather than quietly masking only the
+first occurrence.
+
+A name in `types` with no pattern behind it is **refused at construction** instead of masking nothing
+in silence; `piiTextRedactor` takes the same options.
+- Re-exported: the `Processor` type + `ProcessorTripwire` (importable from a single package)
+
+## How it works
+The processor pipeline is passed to `runDurable`/`createGnl` config. Pure transforms (masking) are
+deterministic; non-deterministic ones are journaled via `ctx.step` → same result on replay. When a
+tripwire fires, the run stops safely.
+
+## Limitations — an honest warning
+
+`moderationProcessor`, `promptInjectionDetector`, `piiRedactor`, and `untrustedToolContent` use **naive
+substring/regex matching**. This means they:
+
+- **Are easily bypassed** — by adding whitespace/punctuation, typos, unicode homoglyphs, paraphrasing,
+  encoding (base64, etc.), or another language.
+- **Are NOT a real security/compliance boundary** — prompt-injection defense is still an unsolved problem
+  in LLM safety; PII regexes don't guarantee GDPR/HIPAA/PCI-DSS-level detection.
+- **Are designed as a first line of defense / noise-reduction layer.** For a critical flow (payment, data
+  deletion, external authorization), don't use these as the ONLY protection mechanism — combine them with
+  additional layers like a model-based judge, human approval, or least-privilege design.
+
+For details, see the JSDoc on the relevant functions (`src/moderation.ts`, `src/safety.ts`, `src/pii.ts`,
+`src/redact.ts`).
+
+## License
+
+Apache-2.0 — see [LICENSE](./LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { piiRedactor, piiTextRedactor } from './pii.js';
+export type { PiiRedactorOptions } from './pii.js';
+export { moderationProcessor } from './moderation.js';
+export type { ModerationOptions } from './moderation.js';
+export { toolFilter } from './tool-filter.js';
+export type { ToolFilterOptions } from './tool-filter.js';
+export { tokenLimit, promptInjectionDetector, outputLimit, untrustedToolContent } from './safety.js';
+export { tokenLimiter } from './token-limiter.js';
+export type { TokenLimiterOptions } from './token-limiter.js';
+export { PII_PATTERNS, PII_VALIDATORS, redactString, redactMessages, luhn, ibanMod97 } from './redact.js';
+export type { PiiType, PiiPattern } from './redact.js';
+export { ProcessorTripwire } from '@gnldev/durable';
+export type { Processor, ProcessorToolResult } from '@gnldev/durable';
+export { toolSearch } from './tool-search.js';
+export type { ToolSearchOptions } from './tool-search.js';

package/dist/index.js

@@ -0,0 +1,13 @@
+// @gnldev/processors — input/output processors for @gnldev/durable agents.
+// Built-ins inherit durability: input processors run before persistInput
+// (masking is journaled), non-deterministic processors journal via ctx.step.
+export { piiRedactor, piiTextRedactor } from './pii.js';
+export { moderationProcessor } from './moderation.js';
+export { toolFilter } from './tool-filter.js';
+export { tokenLimit, promptInjectionDetector, outputLimit, untrustedToolContent } from './safety.js';
+export { tokenLimiter } from './token-limiter.js';
+export { PII_PATTERNS, PII_VALIDATORS, redactString, redactMessages, luhn, ibanMod97 } from './redact.js';
+// Re-export: lets consumers get the Processor type/Tripwire from a single package.
+export { ProcessorTripwire } from '@gnldev/durable';
+export { toolSearch } from './tool-search.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,yEAAyE;AACzE,6EAA6E;AAC7E,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAExD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEtD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EAAE,UAAU,EAAE,uBAAuB,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACrG,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,cAAc,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE1G,mFAAmF;AACnF,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEpD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC","sourcesContent":["// @gnldev/processors — input/output processors for @gnldev/durable agents.\n// Built-ins inherit durability: input processors run before persistInput\n// (masking is journaled), non-deterministic processors journal via ctx.step.\nexport { piiRedactor, piiTextRedactor } from './pii.js';\nexport type { PiiRedactorOptions } from './pii.js';\nexport { moderationProcessor } from './moderation.js';\nexport type { ModerationOptions } from './moderation.js';\nexport { toolFilter } from './tool-filter.js';\nexport type { ToolFilterOptions } from './tool-filter.js';\nexport { tokenLimit, promptInjectionDetector, outputLimit, untrustedToolContent } from './safety.js';\nexport { tokenLimiter } from './token-limiter.js';\nexport type { TokenLimiterOptions } from './token-limiter.js';\nexport { PII_PATTERNS, PII_VALIDATORS, redactString, redactMessages, luhn, ibanMod97 } from './redact.js';\nexport type { PiiType, PiiPattern } from './redact.js';\n// Re-export: lets consumers get the Processor type/Tripwire from a single package.\nexport { ProcessorTripwire } from '@gnldev/durable';\nexport type { Processor, ProcessorToolResult } from '@gnldev/durable';\nexport { toolSearch } from './tool-search.js';\nexport type { ToolSearchOptions } from './tool-search.js';\n"]}

package/dist/moderation.d.ts

@@ -0,0 +1,30 @@
+import type { Processor } from '@gnldev/durable';
+export interface ModerationOptions {
+    /**
+     * Blocked terms (normalized to lowercase before matching) — pure substring matching, bypassable
+     * (see `moderationProcessor` JSDoc). Not a real security boundary.
+     */
+    blocklist: string[];
+    /** input/output/both (default: 'both'). */
+    on?: 'input' | 'output' | 'both';
+}
+/**
+ * Rule-based moderation processor — throws `ProcessorTripwire` when a blocked term is found (run stops).
+ * Deterministic (blocklist is fixed) → no journaling needed.
+ *
+ * HONEST WARNING (naive matching): Matching is a plain, case-insensitive **substring** search
+ * (`String.includes`). This is NOT a real security/moderation boundary — it's easily bypassed:
+ * inserting spaces/punctuation ("s e c r e t"), unicode homoglyphs, typos, synonyms, another
+ * language, etc. — none of these are caught. Treat it as a first-line-of-defense / noise-reduction
+ * layer only — do not use it as the SOLE protection mechanism in a critical flow; for real
+ * moderation, layer in a model-based judge (see below) or a dedicated moderation service.
+ *
+ * For a model-based variant: inside `processInput`/`processOutput`, JOURNAL the LLM-judge call with
+ * `ctx.step('moderation', () => judge(...))` → same decision on resume, no duplicate judge call. Example:
+ *   processOutput: async (out, ctx) => {
+ *     const verdict = await ctx.step('moderation', () => callJudgeModel(out.text));
+ *     if (verdict.blocked) throw new ProcessorTripwire('blocked', 'moderation', verdict);
+ *     return out;
+ *   }
+ */
+export declare function moderationProcessor(opts: ModerationOptions): Processor;

package/dist/moderation.js

@@ -0,0 +1,72 @@
+import { ProcessorTripwire, recordProcessorReport } from '@gnldev/durable';
+function collectText(input) {
+    const parts = [];
+    if (typeof input.system === 'string')
+        parts.push(input.system);
+    if (typeof input.prompt === 'string')
+        parts.push(input.prompt);
+    for (const m of input.messages ?? []) {
+        if (typeof m?.content === 'string')
+            parts.push(m.content);
+        else if (Array.isArray(m?.content)) {
+            for (const p of m.content)
+                if (typeof p?.text === 'string')
+                    parts.push(p.text);
+        }
+    }
+    return parts.join('\n').toLowerCase();
+}
+function firstHit(text, blocklist) {
+    const lower = text.toLowerCase();
+    for (const term of blocklist)
+        if (lower.includes(term.toLowerCase()))
+            return term;
+    return null;
+}
+/**
+ * Rule-based moderation processor — throws `ProcessorTripwire` when a blocked term is found (run stops).
+ * Deterministic (blocklist is fixed) → no journaling needed.
+ *
+ * HONEST WARNING (naive matching): Matching is a plain, case-insensitive **substring** search
+ * (`String.includes`). This is NOT a real security/moderation boundary — it's easily bypassed:
+ * inserting spaces/punctuation ("s e c r e t"), unicode homoglyphs, typos, synonyms, another
+ * language, etc. — none of these are caught. Treat it as a first-line-of-defense / noise-reduction
+ * layer only — do not use it as the SOLE protection mechanism in a critical flow; for real
+ * moderation, layer in a model-based judge (see below) or a dedicated moderation service.
+ *
+ * For a model-based variant: inside `processInput`/`processOutput`, JOURNAL the LLM-judge call with
+ * `ctx.step('moderation', () => judge(...))` → same decision on resume, no duplicate judge call. Example:
+ *   processOutput: async (out, ctx) => {
+ *     const verdict = await ctx.step('moderation', () => callJudgeModel(out.text));
+ *     if (verdict.blocked) throw new ProcessorTripwire('blocked', 'moderation', verdict);
+ *     return out;
+ *   }
+ */
+export function moderationProcessor(opts) {
+    const on = opts.on ?? 'both';
+    const proc = { name: 'moderation' };
+    if (on === 'input' || on === 'both') {
+        // Synchronous throw is PRESERVED (see safety.ts promptInjectionDetector, same rationale) — recordProcessorReport
+        // is called fire-and-forget (best-effort, swallows errors), doesn't break the tripwire's synchronous behavior.
+        proc.processInput = (input, ctx) => {
+            const hit = firstHit(collectText(input), opts.blocklist);
+            if (hit) {
+                void recordProcessorReport(ctx, 'moderation', 'input', { hit });
+                throw new ProcessorTripwire(`Input blocked by moderation: "${hit}"`, 'moderation', { hit });
+            }
+            return input;
+        };
+    }
+    if (on === 'output' || on === 'both') {
+        proc.processOutput = (output, ctx) => {
+            const hit = firstHit(output.text ?? '', opts.blocklist);
+            if (hit) {
+                void recordProcessorReport(ctx, 'moderation', 'output', { hit });
+                throw new ProcessorTripwire(`Output blocked by moderation: "${hit}"`, 'moderation', { hit });
+            }
+            return output;
+        };
+    }
+    return proc;
+}
+//# sourceMappingURL=moderation.js.map

package/dist/moderation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"moderation.js","sourceRoot":"","sources":["../src/moderation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAa3E,SAAS,WAAW,CAAC,KAAqB;IACxC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ;QAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/D,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ;QAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/D,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,QAAQ,IAAI,EAAE,EAAE,CAAC;QACrC,IAAI,OAAO,CAAC,EAAE,OAAO,KAAK,QAAQ;YAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;aACrD,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,CAAC;YACnC,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,OAAO;gBAAE,IAAI,OAAO,CAAC,EAAE,IAAI,KAAK,QAAQ;oBAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACjF,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;AACxC,CAAC;AAED,SAAS,QAAQ,CAAC,IAAY,EAAE,SAAmB;IACjD,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IACjC,KAAK,MAAM,IAAI,IAAI,SAAS;QAAE,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YAAE,OAAO,IAAI,CAAC;IAClF,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAuB;IACzD,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE,IAAI,MAAM,CAAC;IAC7B,MAAM,IAAI,GAAc,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC;IAE/C,IAAI,EAAE,KAAK,OAAO,IAAI,EAAE,KAAK,MAAM,EAAE,CAAC;QACpC,iHAAiH;QACjH,+GAA+G;QAC/G,IAAI,CAAC,YAAY,GAAG,CAAC,KAAqB,EAAE,GAAiB,EAAE,EAAE;YAC/D,MAAM,GAAG,GAAG,QAAQ,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;YACzD,IAAI,GAAG,EAAE,CAAC;gBACR,KAAK,qBAAqB,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;gBAChE,MAAM,IAAI,iBAAiB,CAAC,iCAAiC,GAAG,GAAG,EAAE,YAAY,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;YAC9F,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC,CAAC;IACJ,CAAC;IAED,IAAI,EAAE,KAAK,QAAQ,IAAI,EAAE,KAAK,MAAM,EAAE,CAAC;QACrC,IAAI,CAAC,aAAa,GAAG,CAAC,MAAuB,EAAE,GAAiB,EAAE,EAAE;YAClE,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAC,IAAI,IAAI,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;YACxD,IAAI,GAAG,EAAE,CAAC;gBACR,KAAK,qBAAqB,CAAC,GAAG,EAAE,YAAY,EAAE,QAAQ,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;gBACjE,MAAM,IAAI,iBAAiB,CAAC,kCAAkC,GAAG,GAAG,EAAE,YAAY,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;YAC/F,CAAC;YACD,OAAO,MAAM,CAAC;QAChB,CAAC,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC","sourcesContent":["import { ProcessorTripwire, recordProcessorReport } from '@gnldev/durable';\nimport type { Processor, ProcessorInput, ProcessorOutput, ProcessorCtx } from '@gnldev/durable';\n\nexport interface ModerationOptions {\n  /**\n   * Blocked terms (normalized to lowercase before matching) — pure substring matching, bypassable\n   * (see `moderationProcessor` JSDoc). Not a real security boundary.\n   */\n  blocklist: string[];\n  /** input/output/both (default: 'both'). */\n  on?: 'input' | 'output' | 'both';\n}\n\nfunction collectText(input: ProcessorInput): string {\n  const parts: string[] = [];\n  if (typeof input.system === 'string') parts.push(input.system);\n  if (typeof input.prompt === 'string') parts.push(input.prompt);\n  for (const m of input.messages ?? []) {\n    if (typeof m?.content === 'string') parts.push(m.content);\n    else if (Array.isArray(m?.content)) {\n      for (const p of m.content) if (typeof p?.text === 'string') parts.push(p.text);\n    }\n  }\n  return parts.join('\\n').toLowerCase();\n}\n\nfunction firstHit(text: string, blocklist: string[]): string | null {\n  const lower = text.toLowerCase();\n  for (const term of blocklist) if (lower.includes(term.toLowerCase())) return term;\n  return null;\n}\n\n/**\n * Rule-based moderation processor — throws `ProcessorTripwire` when a blocked term is found (run stops).\n * Deterministic (blocklist is fixed) → no journaling needed.\n *\n * HONEST WARNING (naive matching): Matching is a plain, case-insensitive **substring** search\n * (`String.includes`). This is NOT a real security/moderation boundary — it's easily bypassed:\n * inserting spaces/punctuation (\"s e c r e t\"), unicode homoglyphs, typos, synonyms, another\n * language, etc. — none of these are caught. Treat it as a first-line-of-defense / noise-reduction\n * layer only — do not use it as the SOLE protection mechanism in a critical flow; for real\n * moderation, layer in a model-based judge (see below) or a dedicated moderation service.\n *\n * For a model-based variant: inside `processInput`/`processOutput`, JOURNAL the LLM-judge call with\n * `ctx.step('moderation', () => judge(...))` → same decision on resume, no duplicate judge call. Example:\n *   processOutput: async (out, ctx) => {\n *     const verdict = await ctx.step('moderation', () => callJudgeModel(out.text));\n *     if (verdict.blocked) throw new ProcessorTripwire('blocked', 'moderation', verdict);\n *     return out;\n *   }\n */\nexport function moderationProcessor(opts: ModerationOptions): Processor {\n  const on = opts.on ?? 'both';\n  const proc: Processor = { name: 'moderation' };\n\n  if (on === 'input' || on === 'both') {\n    // Synchronous throw is PRESERVED (see safety.ts promptInjectionDetector, same rationale) — recordProcessorReport\n    // is called fire-and-forget (best-effort, swallows errors), doesn't break the tripwire's synchronous behavior.\n    proc.processInput = (input: ProcessorInput, ctx: ProcessorCtx) => {\n      const hit = firstHit(collectText(input), opts.blocklist);\n      if (hit) {\n        void recordProcessorReport(ctx, 'moderation', 'input', { hit });\n        throw new ProcessorTripwire(`Input blocked by moderation: \"${hit}\"`, 'moderation', { hit });\n      }\n      return input;\n    };\n  }\n\n  if (on === 'output' || on === 'both') {\n    proc.processOutput = (output: ProcessorOutput, ctx: ProcessorCtx) => {\n      const hit = firstHit(output.text ?? '', opts.blocklist);\n      if (hit) {\n        void recordProcessorReport(ctx, 'moderation', 'output', { hit });\n        throw new ProcessorTripwire(`Output blocked by moderation: \"${hit}\"`, 'moderation', { hit });\n      }\n      return output;\n    };\n  }\n\n  return proc;\n}\n"]}

package/dist/pii.d.ts

@@ -0,0 +1,86 @@
+import type { Processor } from '@gnldev/durable';
+import { type PiiType, type PiiPattern } from './redact.js';
+export interface PiiRedactorOptions {
+    /** Which PII types to mask (default: all). */
+    types?: PiiType[];
+    /** Mask generator (default: `[REDACTED_<TYPE>]`). */
+    mask?: (type: PiiType) => string;
+    /** input/output/both (default: 'both'). */
+    on?: 'input' | 'output' | 'both';
+    /**
+     * Also redact the tool execute result (processToolResult hook) — default: false.
+     * known limitation: tool output (external API/DB/file result) was being written to the journal as
+     * PLAIN TEXT; it may contain PII. Left as opt-in so existing piiRedactor users' behavior does NOT
+     * CHANGE — this option only masks tool output when explicitly set to `true`.
+     */
+    redactToolResults?: boolean;
+    /**
+     * Extra patterns, for the identifiers the five built-in types cannot name.
+     *
+     * The built-in list is US-shaped (`ssn` exists nowhere else), so a national id, an IBAN, a patient
+     * record number or an internal customer id has no type that matches it. Dropping a built-in from
+     * `types` removes coverage rather than adding any, and mutating the exported `PII_PATTERNS` changes
+     * behavior for every redactor in the process — neither is a way to add your own.
+     *
+     * These run BEFORE the built-ins, deliberately: the built-in `phone` pattern is greedy enough to
+     * swallow a national id (measured — `12345678901` comes back `[REDACTED_PHONE]`), so a pattern that
+     * ran afterwards would find its text already masked under the wrong name.
+     *
+     *   piiRedactor({ extraPatterns: [{ name: 'iban', pattern: /TR\d{24}/g }] })
+     */
+    extraPatterns?: PiiPattern[];
+    /**
+     * Run each identifier's own checksum before masking — Luhn for `creditCard`, mod-97 for `iban`,
+     * and any `test` on a custom pattern. Default: true.
+     *
+     * It is what separates a card number from any sixteen digits: measured, the pattern alone masked
+     * `order 1234567812345678` as a card, which loses the order number without protecting anything.
+     * The trade is real and worth stating — a card typed with a wrong digit fails Luhn and is then left
+     * alone. Set to `false` to mask on shape only, which is the older, blunter behavior: it corrupts
+     * more text but cannot be talked out of masking anything.
+     */
+    validate?: boolean;
+}
+/**
+ * The same masking as `piiRedactor`, as a plain string function, for the text that never passes
+ * through a processor at all.
+ *
+ * A `Processor` only sees `processInput`/`processOutput`/`processToolResult`. A run's failure
+ * message is written from `recordRunOutcome` in @gnldev/durable, which no processor is consulted
+ * about, and it is not always the host's own text: a provider that refuses a request commonly
+ * echoes the offending input back inside the message. Anything that ships that message onward —
+ * `@gnldev/otel`'s span attributes are the case this was added for — needs the same mask, and had
+ * no way to reuse it because `DEFAULT_TYPES` is private to this module.
+ *
+ * Shares that constant and the default mask with `piiRedactor` deliberately: two copies of the
+ * defaults is exactly how the redacted path and the un-redacted one drift apart.
+ *
+ *   import { piiTextRedactor } from '@gnldev/processors';
+ *   await exportRun(journal, runId, { endpoint, redact: piiTextRedactor() });
+ */
+export declare function piiTextRedactor(opts?: Pick<PiiRedactorOptions, 'types' | 'mask' | 'extraPatterns' | 'validate'>): (text: string) => string;
+/**
+ * PII redaction processor — pure regex (email/phone/credit-card/ssn/ip). Deterministic, so no
+ * journaling is needed: produces the same masking on resume. The input side runs BEFORE persistInput
+ * → masked content is written to the journal, the model NEVER sees raw PII.
+ *
+ * HONEST WARNING (naive regex matching): These regexes are best-effort, they do NOT provide an
+ * AUDIT/COMPLIANCE-grade (GDPR/HIPAA/PCI-DSS etc.) PII DETECTION GUARANTEE. Known limits: only
+ * matches specific formats (e.g. US/generic-format phone numbers, plain 16-digit card numbers) —
+ * international/local formats, unstructured PII like name/address, or unusual formatting (line
+ * breaks, different separators) can slip through; it can also produce false positives (e.g. a
+ * random 16-digit number). Use it as a noise-reduction / first-line-of-defense layer, not as a real
+ * compliance/security boundary.
+ *
+ * SCOPE, measured — WHAT THE OUTPUT SIDE DOES NOT COVER: `processOutput` transforms the
+ * `{text, messages}` view, so `result.text` and `result.response.messages` come back masked on both
+ * `runDurable` and `streamDurable`, and so does persisted thread memory. `result.steps` and
+ * `result.content` DO NOT — they still hold the model's raw output, and a caller reading either one
+ * sees unredacted PII. This is not fixable inside the hook: a processor's output arity is
+ * unconstrained (a summariser legally returns one message for a turn that produced three), so no
+ * mapping back onto per-step records exists, and `content` is a parts array rather than messages.
+ * Read `text`/`response.messages`; treat `steps`/`content` as raw. On the STREAM path the
+ * `textStream`/`fullStream` deltas are raw as well — they reach the client before the turn ends, so
+ * use `on: 'input'` (or `runDurable`) if the wire itself must never carry it.
+ */
+export declare function piiRedactor(opts?: PiiRedactorOptions): Processor;