feat(examples): add TanStack AI chat() guardrails example

[davidmytton]

Adds examples/tanstack-agent: a small Node chat({ middleware }) support agent protected by @arcjet/guard/tanstack-ai/v0 (arcjet-js#6260).

Inbound guard() runs before chat(). guardMiddleware is first in the middleware list so onBeforeToolCall rate-limits lookups and scans free-text note args for PII. Default DENY is { type: "skip", result: ArcjetDenialResult }. Correlation is a caller-owned sessionId — never ctx.threadId.

The adapter is on main but not on npm yet, so @arcjet/guard and @arcjet/transport (./http2) are vendored from d730d57. Repin once @arcjet/guard/tanstack-ai/v0 publishes.

import { guardMiddleware, tanstackAiContext } from "@arcjet/guard/tanstack-ai/v0";
import { chat } from "@tanstack/ai";

const appContext = { sessionId: conversationId };
const ctx = tanstackAiContext({ context: appContext });

const inbound = await arcjet.guard({
  label: "message.received",
  rules: [detectInjection(text)],
  ...ctx,
});
if (inbound.conclusion === "DENY" || inbound.hasFailedOpen()) {
  return; // do not call chat()
}

const stream = chat({
  adapter,
  messages,
  tools: [lookupOrder],
  context: appContext,
  middleware: [
    guardMiddleware(arcjet, {
      action: ({ toolName }) => `${toolName}.invoked`,
      sessionId: conversationId,
      rules: ({ input }) => [
        lookupLimit({ key: `order:${input.orderId}`, requested: 1 }),
        ...(input.note ? [detectPii(input.note)] : []),
      ],
    }),
  ],
});

Docs: /guards/tanstack-ai/. Run examples/tanstack-agent with ARCJET_KEY and AI_GATEWAY_API_KEY.

  

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​@​tanstack/​ai-openai@​0.22.3
	npm/​@​tanstack/​ai@​0.52.0

View full report

[socket-security]

Warning

Review the following alerts detected in dependencies.

According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.

Action	Severity	Alert  (click "▶" to expand/collapse)
Warn		Network access: npm @tanstack/ai-openai in module globalThis["fetch"] Module: globalThis["fetch"] Location: Package overview From: examples/tanstack-agent/package-lock.json → npm/@tanstack/ai-openai@0.22.3 ℹ Read more on: This package | This alert | What is network access? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should remove all network access that is functionally unnecessary. Consumers should audit network access to ensure legitimate use. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/@tanstack/ai-openai@0.22.3. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Environment variable access: npm @tanstack/ai-utils Location: Package overview From: examples/tanstack-agent/package-lock.json → npm/@tanstack/ai@0.52.0 → npm/@tanstack/ai-openai@0.22.3 → npm/@tanstack/ai-utils@0.4.0 ℹ Read more on: This package | This alert | What is environment variable access? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should be clear about which environment variables they access, and care should be taken to ensure they only access environment variables they claim to. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/@tanstack/ai-utils@0.4.0. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report

[arcjet-review]

Arcjet Review — 🟡 Medium Risk

Decision: Approved

Rationale: Self-contained example addition. New Node HTTP server has input validation (zod), body size cap (32 KiB), message length cap (2000), and clear README warnings that this is a local demo without auth. No hardcoded secrets. The vendored @arcjet/guard and @arcjet/transport packages are pinned to a documented arcjet-js commit (d730d57) with SOURCE.txt attribution and are only used inside the example. Escalation triggers fire (Dockerfile, compose.yaml, package.json) but each is scoped to the new example directory and doesn't touch shared infra. Approving despite Medium risk because the changes are isolated to an example, security caveats are clearly documented, and the guardrails logic itself (inbound guard() + hasFailedOpen check, guardMiddleware first, default-skip DENY) matches the documented @arcjet/guard/tanstack-ai/v0 patterns.

Summary of Changes

Adds examples/tanstack-agent: a Node HTTP server + minimal HTML page demonstrating TanStack AI chat() protected by Arcjet Guard's tanstack-ai/v0 adapter. Inbound prompt-injection screening runs before chat(); guardMiddleware runs first for tool-call rate limiting and PII detection on free-text args. Because @arcjet/guard/tanstack-ai/v0 is not yet on npm, @arcjet/guard and @arcjet/transport are vendored from arcjet-js@d730d57. Also registers the example in the top-level compose.yaml, README, and prepare-to-publish.ts.

Escalation Triggers

• Dependency Changes: New examples/tanstack-agent/package.json declares dependencies including file:./vendor/... refs and an overrides block for @arcjet/transport.
• CI/CD Pipeline: New Dockerfile for the example (scoped to examples/tanstack-agent, not shared CI).
• Infrastructure: New examples/tanstack-agent/compose.yaml and an include entry in the top-level compose.yaml.

Notes

PR exceeds the 1000-line threshold, but ~2500+ of the added lines are vendored README/LICENSE/SKILL.md content from arcjet-js@d730d57 (documented in vendor/SOURCE.txt), not novel logic. The reviewable new code (index.ts, lib/agent.ts, lib/arcjet.ts, index.html, tsconfig/Dockerfile/compose) is small and self-contained.

Path filtering: 95 files excluded by ignore paths. 27 of 122 files included in review.

_{Review: 762d75cd | Model: anthropic/claude-opus-4-7 | Powered by Arcjet Review}

[arcjet-review]

Nit: this env-var check runs on every POST but the value only changes at process start. Consider moving the AI_GATEWAY_API_KEY/OPENAI_API_KEY check next to server.listen(...) so the process fails fast at startup instead of after the first request. Not blocking for an example.

[arcjet-review]

When the body exceeds MAX_JSON_BODY_BYTES you throw out of the for await, but the underlying request stream is left in a half-consumed state — the client may see a truncated response before the 413 lands. Consider request.destroy() (or request.resume() to drain) before throwing so the socket is cleaned up promptly.

[arcjet-review]

screenInbound maps every thrown error to GUARD_UNAVAILABLE / reason: "ERROR". That's the right fail-closed posture for this demo, but it also swallows programming errors (bad rule config, etc.) into a generic "unavailable" message. Consider at least console.error-logging the caught exception so it's not silently hidden during development.

[arcjet-review]

asPrintableId silently drops a conversation id that fails the printable-ASCII / length check, and the run then goes uncorrelated. For a demo that's fine, but it may confuse a user who supplies an id and sees (uncorrelated) in the UI with no explanation. Consider returning a 400 for a supplied-but-invalid id instead of silently coercing to undefined.

[arcjet-review]

The vendored @arcjet/guard package.json declares version: "1.11.0" — the same version as the currently published npm release, even though this build is from an unreleased main commit that contains the tanstack-ai/v0 subpath the npm release lacks. If a consumer ever hoists this into a workspace that also depends on @arcjet/guard@1.11.0 from the registry, npm may treat them as satisfying the same version and de-dup unpredictably. Consider bumping to a distinguishable pre-release version (e.g. 1.11.1-vendor.<sha>) — matches the intent of the SOURCE.txt/README note that this is a temporary vendor drop.