norma/

Norma

A general-purpose Agent Harness SDK in Go. Norma is the engine that turns a language model into an autonomous agent: a streaming tool-use loop that lets a model read, run, and reason its way through a task while you keep control of the prompt, the tools, and the safety boundary.

You point it at any model (via the Anthropic or OpenAI wire format), drive it with a host-controlled system prompt, and extend it with your own tools, permission policy, hooks, and subagents. It ships as a focused, near-dependency-free library — the loop, scheduler, and safety boundary are provider- and scenario-agnostic: they don't know whether they're driving a coding agent, a security auditor, or a customer-support bot.

What you get out of the box: dual-format streaming, a fail-closed tool system with the standard file/shell toolset, a four-stage permission pipeline, automatic context-window management, lifecycle hooks, subagents, MCP, plan mode, long-term memory, a skill system, background tasks, and multi-agent coordination — all behind one stateful Session.

Module path: github.com/Bluestar-coder/ARTEX-RedTeam/norma（原上游 github.com/Autumn-27/norma）· Go 1.23+ (uses iter).

Packages

Quick start

prov, _ := llm.NewProvider(llm.Config{Format: llm.FormatAnthropic, Model: "your-model-name"})
// or:  llm.Config{Format: llm.FormatOpenAI, BaseURL: "https://api.deepseek.com/v1", Model: "deepseek-chat"}

sess := agentcore.NewSession(agentcore.Options{
    Provider:       prov,
    SystemPrompt:   []string{"You are a helpful coding agent."}, // the SDK injects NO preset prompt
    PermissionMode: permission.ModeDefault,
    CanUseTool:     myApprovalCallback, // gates mutating tools
})

for ev, err := range sess.Prompt(ctx, "Add a /health endpoint and run the tests.") {
    if err != nil { /* ... */ }
    if ev.Kind == harness.KindText { fmt.Print(ev.Text) }
}

CLI demo

go build -o agentcore ./cmd/agentcore

ANTHROPIC_API_KEY=... ./agentcore -provider anthropic -model your-model-name
OPENAI_API_KEY=...    ./agentcore -provider openai    -model gpt-4o
./agentcore -provider openai -model gpt-4o -yes -p "summarize the go files here"

Mutating tools (Write/Edit/Bash) prompt for approval unless -yes is set. Supply your own system prompt with -system FILE.

Design highlights

• Dual wire formats, one model. Both adapters translate to/from a single Anthropic-style content-block model, so the loop and tools never change when you switch providers. Reasoning models' reasoning_content surfaces as thinking events.
• Host owns the prompt. The SDK ships no preset system prompt — Options.SystemPrompt is yours. Coding / security-audit prompts live in examples/, not the core.
• Fail-closed tools. New tools default to not-read-only, not-concurrency-safe, approval-required. Read-only tools opt in and become eligible for parallel execution.
• iter.Seq2 streaming. Prompt and Query are range-over-func iterators; cancellation is via context.Context.

Examples

• examples/custom-llm — three provider configs + a custom non-coding prompt + a custom tool.
• examples/coding-agent — full coding agent with interactive permissions, a PreToolUse hook, and compaction.
• examples/security-audit — read-only auditor that delegates to a subagent.
• examples/planner-memory — plan mode (explore → approve → implement) plus persistent memory.

Tests

go test ./...

Coverage: both provider adapters over httptest SSE; the loop end-to-end with a scripted provider (tool execution, message threading, permission denial, max-turns, parallel reads); real tool execution in a temp dir; the permission pipeline matrix; compaction (auto-summary, circuit breaker, micro-compact); hooks (block/rewrite/Stop-gating); subagent dispatch + depth guard; and the MCP client over in-memory pipes.

Scope

Implements the core loop, dual providers, tools, the full permission pipeline, compaction, hooks, subagents, and MCP — plus plan mode, long-term memory, the skill system, background tasks, deferred tools, transcript persistence with resume, and coordinator multi-agent orchestration.