@framers/agentos-ext-code-safety

Static-analysis guardrail for @framers/agentos. Scans code that agents emit (in chat, in forged tools, in generated artifacts) for dangerous patterns before the code is shown to the user or executed in any sandbox.

What it does

Extracts code fences from agent output, parses them, and runs each block through a configurable rule set. Default rules cover:

• Filesystem destruction (rm -rf /, recursive deletes)
• Process control (fork bombs, unrestricted exec)
• Network exfiltration to non-allowlisted hosts
• Hard-coded secrets (API keys, tokens, private keys)
• Eval-style dynamic code execution
• Known-bad patterns from the OWASP LLM Top 10

Rules are pluggable; bring your own and the engine merges them with defaults.

Install

npm install @framers/agentos-ext-code-safety

Peer dependency: @framers/agentos.

Quickstart

import { AgentOS } from '@framers/agentos';
import { createCodeSafetyGuardrail } from '@framers/agentos-ext-code-safety';

const agentos = new AgentOS();
await agentos.initialize({
  extensionManifest: {
    packs: [
      {
        factory: () =>
          createCodeSafetyGuardrail({
            languages: ['typescript', 'javascript', 'python', 'shell'],
            extraRules: [],
          }),
        enabled: true,
      },
    ],
  },
});

Public API

• CodeFenceExtractor — pulls fenced code blocks from prose
• CodeSafetyScanner — runs fence content through rules
• CodeSafetyGuardrail — guardrail wiring the scanner for the AgentOS contract
• DefaultRules — the built-in rule pack
• createCodeSafetyGuardrail(options?) — factory returning an ExtensionPack
• createExtensionPack(context) — auto-discoverable factory used by AgentOS extension auto-pickup

See src/types.ts for CodeSafetyPackOptions.

Examples

• test/ — fixtures across the supported languages plus rule-authoring patterns

Lazy loading and optional install

This package is an optional dependency of @framers/agentos-extensions-registry. The registry ships catalog metadata; createCuratedManifest() calls import.meta.resolve() per entry and silently skips anything not installed. npm install @framers/agentos-ext-code-safety is the gate.

Unlike the other guardrail packs, code-safety is regex-only. There is no model to lazy-load. The default rule set ships in-process and adds zero cold-start cost. Custom rules merge in at activation through extraRules.

The guardrail registers with config.evaluateStreamingChunks = true and runs in Phase 2 of the two-phase dispatcher (parallel classifiers). Dangerous fence patterns (filesystem destruction, secrets, eval) return BLOCK; lower-severity matches return FLAG. Worst-action aggregation across all Phase 2 classifiers picks the strictest decision.

Tool calls

The guardrail also sets config.evaluateToolCalls, so the AgentOS output dispatcher (@framers/agentos 0.13.67 and later) hands it each tool-call chunk of a guarded stream. It scans the code argument of the tools it watches: command of shell_execute (as Bash), query of run_sql (as SQL), and content of write_file, create_file and edit_file. The codeExecutingTools and codeArgumentMapping options change that list. A critical or high finding blocks the call: the stream ends with the guardrail's verdict in place of the chunk, so the stream never hands the host the call to run. A call the runtime runs itself (executionMode: 'internal') does not wait for the output guardrails, so a block ends the stream without stopping it. An earlier AgentOS does not read the flag and passes tool calls unscanned.

For the full DI model and the end-to-end walkthrough that places this pack in the dispatcher, see How extensions stay optional and lazy and the auto-loading guide.

License

Apache 2.0 — see the repo root LICENSE.