CIAACC TokenGuard Agent 0.20.4

CIAACC TokenGuard is a drop-in AI Agent for self-hosted n8n that reduces unnecessary LLM context while preserving task behavior. In the Gemini LIVE qualification corpus, Automatic reduced actual provider input tokens by 35.63% while preserving the same model-call and tool-call counts as the native Agent.

Savings vary by workflow. Small workflows may save little or nothing. Correctness and safe fallback take priority over token reduction.

Stable public source release. npm package: n8n-nodes-ciaacc-token-guard.

Requirements

• Node.js 22.22 or newer, below Node.js 25.
• Self-hosted n8n 2.34.5, the current stable release target qualified on 2026-08-13.
• n8n 2.33.7 remains the historical root-Agent/Gemini qualification boundary.
• n8n 2.32.6 is a conservative canary target.
• A connected Main Model. Gemini is the current LIVE-qualified provider-sensitive boundary.

Install

In self-hosted n8n, open Settings > Community nodes, choose Install, and enter:

n8n-nodes-ciaacc-token-guard

If your instance disables unverified community packages, set
N8N_UNVERIFIED_PACKAGES_ENABLED=true and restart n8n before installation.

For manual npm installation, stop n8n, install the package in the custom-nodes directory, then restart n8n:

Set-Location "$env:USERPROFILE\.n8n\nodes"
npm install n8n-nodes-ciaacc-token-guard@0.20.4
n8n start

Use

1. Add CIAACC TokenGuard Agent to a workflow.
2. Connect the required Main Model and any optional Memory, Tool, or Output Parser nodes.
3. New version-2 nodes default to Optimization = Automatic. Version-1 legacy nodes with no serialized setting remain Off.
4. Run normally. Automatic applies only the Stable Core after maturity, opportunity, graph break-even, Recovery Budget, and fail-closed gates.
5. Read ciaaccOptimizationSummary in execution data. The main item.json is unchanged.

The summary distinguishes ACTUAL, ESTIMATED, and NOT_AVAILABLE; includes provider usage, estimated baseline/net reduction, calls, recoveries, selective recoveries, applied features, bypasses, and fallbacks; and reports Opportunity = LOW without inventing savings on small workloads.

Automatic and Off

Automatic may use Artifact Vault, Lossless Compaction, Context Lifecycle, Artifact Expansion, Full-Fidelity Pins, Prompt Contract, Progressive Tool Disclosure, Opportunity Gate, Graph Break-Even, Recovery Budget, Global Token Ledger, Optimization Summary, deterministic Selective Artifact Recovery, Smart Memory, Result Delta, Result Folding, and the minimal Context Fabric safety infrastructure where the maturity gate qualifies them.

Off takes the direct baseline Agent path and remains the diagnostic, comparison, and compatibility mode. For an immediate behavioral rollback, serialize Optimization = Off. To roll back completely, replace CIAACC with the native n8n AI Agent and reconnect the same model, memory, tools, and parser. Before downgrading the package, stop n8n, back up the workflow/database, install the previously qualified tarball in .n8n/nodes, and restart n8n. No automatic workflow conversion is performed.

Economy Planner is experimental and hidden/internal in this Stable release. Provider cache optimization, Neutral Handoff, Child Return Compaction, Agent-aware Disclosure, Delegation Loop Guard, and Multi-Agent Mesh remain disabled. Context Fabric is limited to Artifact lineage/ACL/recovery safety; it is not a Mesh or orchestration layer. The separately visible CIAACC Agent Tool is labeled Experimental.

Selective Artifact Recovery

The internal ciaacc_context tool accepts deterministic selectors for an exact JSON object path or exact array row identities with optional fields. Selection uses the immutable raw Artifact and its index, verifies integrity and ACL, performs no LLM call, and never guesses. Ambiguous or unsupported selection broadens to verified full raw only when safe; otherwise it fails closed.

Demo workflows

Exactly four importable Stable demos ship in the package: Small Agent, Many Tools, Large Tool Result, and Multi-Turn Artifact Reuse. Connect the model credential after import. The files contain no credential IDs or secrets. Savings vary by workload.

Support matrix

No external telemetry is emitted. Optimization metrics remain local to execution data. Raw prompts, tool results, and credentials must not be written to summary or release logs.

Known limitations

• Support is limited to the self-hosted n8n versions in the matrix above; future n8n releases require a new compatibility check.
• Gemini is the only LIVE-qualified provider-sensitive boundary. OpenAI and Anthropic remain fail-closed until validated with credentials.
• The Agent Tool remains Experimental, and savings depend on workload shape and provider behavior.

Development

npm install
npm run build:demos
npm run check
npm run validate:package
npm run check:adapter-drift
npm pack

For a newly detected n8n Stable release, set N8N_STABLE_VERSION before npm run check:adapter-drift. An unqualified version fails the gate and requires manual comparison of the native Agent adapter/API surface.

The release gate covers n8n 2.32.6 compatibility, n8n 2.33.7 historical qualification, n8n 2.34.5 current-stable release qualification, provider request parity, fail-closed resume state, selective recovery, package installation, Task Runners, and local editor smoke.

Security and support

Report vulnerabilities using SECURITY.md. Do not include credentials, raw prompts, or private tool results in reports. This Stable package has no n8n Cloud or Verified Marketplace claim and no broad provider certification.