Download the PHP package forgeomni/superagent without Composer

SuperAgent

🌍 Language: Français 📖 Docs: API docs

An AI agent SDK for PHP — run the full agentic loop (LLM turn → tool call → tool result → next turn) in-process, with fourteen providers, real-time streaming, multi-agent orchestration, and a machine-readable wire protocol. Usable as a standalone CLI or as a Laravel library.

Table of Contents

• Quick Start
• Providers & Authentication
• OpenAI Responses API
• Cross-provider handoff
• Fable 5
• Opus 5
• GPT-5.6 (Sol / Terra / Luna)
• Grok 4.6
• DeepSeek V4
• MiniMax M3
• GLM-5.2 / 5.3
• Goal mode (codex /goal parity)
• Operational guardrails
• Companion tools (jcode-inspired)
• Agent Loop
• Tools & Multi-Agent
• Agent Definitions
• Skills
• MCP Integration
• Wire Protocol
• Retry, Errors & Observability
• Guardrails & Checkpoints
• Standalone CLI
• Laravel Integration
• Configuration reference

Every feature section ends with a Since line pointing at the release that introduced it. Full release notes live in CHANGELOG.md.

Quick Start

Install:

See INSTALL.md for the full matrix (system requirements, auth setup, IDE bridges, CI integration).

Smallest possible agent run:

Smallest agent run with tools:

One-shot via CLI:

Providers & Authentication

Fourteen registry-backed providers, with region-aware base URLs and multiple auth modes per provider. All implement the same LLMProvider contract, so swapping one for another is one line.

Auth options, by priority:

1. API key from environment — ANTHROPIC_API_KEY, OPENAI_API_KEY, KIMI_API_KEY, QWEN_API_KEY, GLM_API_KEY, MINIMAX_API_KEY, DEEPSEEK_API_KEY, XAI_API_KEY, OPENROUTER_API_KEY, GEMINI_API_KEY.
2. Stored OAuth credentials at ~/.superagent/credentials/<name>.json. Device-code flow — run superagent auth login <name>:
   • claude-code — reuses an existing Claude Code login
   • codex — reuses a Codex CLI login
   • gemini — reuses a Gemini CLI login
   • kimi-code — RFC 8628 device flow against auth.kimi.com (since v0.9.0)
   • qwen-code — device flow with PKCE S256 + per-account resource_url (since v0.9.0)
3. Explicit config — api_key / access_token / account_id on the agent options.

OAuth refresh is serialised across processes via CredentialStore::withLock() — parallel queue workers sharing one credential file don't race on refresh (since v0.9.0).

Declarative headers

Since v0.9.1

Model catalog

Every provider ships with model-id + pricing metadata bundled in resources/models.json. Refresh to the vendor's live /models endpoint at any time:

The bundled catalog is also synced against locally installed AI CLIs (Claude Code, Codex CLI, Copilot CLI, kimi-cli, cursor-agent, grok CLI). Entries attested only through a subscription CLI ship without per-token pricing — CostCalculator falls back to family-prefix rates — and the cursor block (composer-2.5, cursor-grok-4.5-high) is catalog-only reference data: Cursor has no public API and is deliberately not a callable provider. (v1.1.8–1.1.9)

Since v0.9.0

OpenAI Responses API

Dedicated provider at provider: 'openai-responses'. Hits /v1/responses with the full modern OpenAI shape.

Why use it over openai:

ChatGPT subscription routing

Pass access_token (or set auth_mode: 'oauth') to auto-route through chatgpt.com/backend-api/codex — so Plus / Pro / Business subscribers bill against their subscription instead of getting rejected at api.openai.com.

Azure OpenAI

Six base-URL markers auto-flip the provider into Azure mode. api-version query string is added (default 2025-04-01-preview, overridable); api-key header is set alongside Authorization.

Trace-context passthrough

Inject W3C traceparent into client_metadata so OpenAI-side logs correlate with your distributed trace:

Since v0.9.1

Cross-provider handoff

Agent::switchProvider($name, $config, $policy) swaps the active provider mid-conversation. The message history is preserved and re-encoded into the new provider's wire format on the next request — so a tool history that ran against Claude can continue under Kimi without losing parallel tool calls or tool_use_id correlation.

Handoff policy

Provider-only artifacts the new wire shape can't carry (Anthropic signed thinking, Kimi prompt_cache_key, Responses-API encrypted reasoning, Gemini cachedContent refs) get parked under AssistantMessage::$metadata['provider_artifacts'][$providerKey] — HandoffPolicy::preserveAll() keeps them around so a later swap back to the originating family can re-stitch them; default() keeps them stashed but invisible to the new provider.

Atomic swap

switchProvider() constructs the new provider before mutating any state. If construction fails (missing api_key, unknown region, network probe rejection) the agent stays on the old provider with its history untouched.

Six wire-format families share one Transcoder

All conversion goes through Conversation\Transcoder, which dispatches by WireFamily enum: Anthropic (also bedrock's anthropic.* invocations), OpenAIChat (OpenAI/Kimi/GLM/MiniMax/Qwen/OpenRouter/LMStudio), OpenAIResponses, Gemini (the only family that correlates tool calls by name+order, no ids), DashScope, Ollama. Useful directly for offline transcoding:

Since v0.9.5

Fable 5

Fable 5 (claude-fable-5) is Anthropic's most capable model — for the most demanding reasoning and long-horizon agentic work. It runs on the standard anthropic provider (API key or Claude Code OAuth), with a 1M-token context (128K max output) and high-res vision. PAYG pricing is $10 in / $50 out per million tokens — above the Opus tier (Opus 5 is $5/$25). It is the Squad EXPERT-tier model; the zero-config anthropic default is Claude Opus 5. Refusals fall back to Opus 4.8.

Its request surface differs from the Opus tier — the SDK handles this automatically:

• Thinking is always on and adaptive. The provider emits thinking: {type: "adaptive"}; an explicit budget_tokens is never sent (Fable 5 / Opus 4.7 / 4.8 400 on it). Depth is steered by the effort dial, not a token budget.
• No sampling params, no prefill. temperature / top_p / top_k and a trailing assistant prefill are dropped for Fable 5 (they 400 there); steer via prompting + effort instead.
• Effort dial. AnthropicProvider implements SupportsReasoningEffort → Anthropic's GA output_config.effort (low … high … xhigh … max), also available on Opus 4.5+/Sonnet 4.6.

⚠️ 30-day data retention required. Fable 5 is not available under zero data retention — an org configured below 30-day retention gets a 400 on every request. Safety classifiers may also return stop_reason: "refusal".

Sonnet 5 (claude-sonnet-5, released 2026-06-30) ships alongside as the new sonnet flagship — Anthropic's most agentic Sonnet, close to Opus 4.8 at a lower price. Same Claude-5-generation adaptive surface (adaptive-only thinking, effort dial, no sampling params / prefill), 1M context (128K max output), $3 in / $15 out (intro $2/$10 through 2026-08-31). The sonnet / claude-sonnet / sonnet-5 aliases now resolve to it.

Since v1.1.5

Opus 5

Opus 5 (claude-opus-5) is the current flagship Opus and the zero-config anthropic default — a drop-in upgrade over Opus 4.8 at the same $5 in / $25 out per million tokens, with a 1M context (128K max output) and fast mode. The opus / claude-opus / opus-5 aliases resolve to it.

It shares the Claude-5-generation request surface, which the SDK applies for you:

• Thinking is ON by default and adaptive — thinking: {type: "adaptive"}; an explicit budget_tokens 400s, so a fixed budget is silently upgraded to adaptive. ThinkingConfig::disabled() emits no thinking key at all, so it can never collide with Opus 5's rule that type: "disabled" is rejected above high effort.
• No sampling params, no prefill — temperature / top_p / top_k and a trailing assistant prefill are dropped (they 400).
• Full effort dial — output_config.effort accepts low … high … xhigh … max. Start at xhigh for coding/agentic work, then sweep down: low/medium are unusually strong on this model.
• 512-token prompt-cache minimum (down from 1024 on Opus 4.8), so shorter prefixes now cache.

Pinned ids are never rewritten: a config on claude-opus-4-8 (or any other explicit id) keeps running that exact model — only the bare family aliases track the newest release.

Since v1.1.10

GPT-5.6 (Sol / Terra / Luna)

GPT-5.6 (GA 2026-07-09) replaces GPT-5.5 as OpenAI's flagship line and retires the mini/nano suffixes — the family is three tiers sharing a 1.05M-token context (128K max output) and vision:

Inputs beyond 272K tokens bill at 2× in / 1.5× out. openai-responses now defaults to gpt-5.6-sol; the Chat Completions openai provider keeps its gpt-4o default but resolves all three ids.

• Effort dial, normalized per generation. GPT-5.6 retired minimal and added none + max (default medium). The provider normalizes whatever you pass to the target model's legal set — minimal → low on 5.6, max → xhigh on pre-5.6 — so cross-provider reasoning_effort calls keep working. OpenAIResponsesProvider now implements SupportsReasoningEffort.
• reasoning.mode: pro is the API form of ChatGPT's Sol Pro (Sol only); reasoning.context controls reasoning persistence across turns. Both also pass through verbatim inside options['reasoning'].
• Explicit prompt caching. prompt_cache_options: {mode: explicit} — cache writes bill at 1.25× uncached input, reads keep the 90% discount.
• Programmatic tool calling / multi-agent beta stay reachable via extra_body until first-class knobs land.

Since v1.1.6

Grok 4.6

Grok 4.6 (grok-4.6, released 2026-08-12) is xAI's frontier flagship for long-running agents, coding and visual work, and the grok provider default — 500K context, text+image input, vision, server-side tools (web/X search, code execution) and remote MCP. Pricing is $2 in / $0.50 cached / $6 out per million (the whole request bills 2× — $4/$1/$12 — once the prompt reaches 200K). grok-4.5 (2026-07-08) stays active as the previous flagship (cached input now $0.30/M) and grok-4.3 (1M ctx, $1.25/$2.50, batch-eligible) remains the value tier.

• Reasoning-effort dial. Grok 4.6 reasons unconditionally (no off switch) and takes reasoning_effort: low | medium | high | xhigh (server default high) — max maps to the new xhigh top tier. Grok 4.5 keeps the three-level dial (max/xhigh clamp to high); off sends nothing on either. grok-4.3 / grok-4 still reject the param, so the fragment stays gated per model id.

• Prompt-cache pinning. xAI recommends pinning a conversation to a server for reliable cache hits ($0.50/M vs $2/M). Pass conversation_id (or prompt_cache_key) in the provider config and the Chat Completions surface sends it as the x-grok-conv-id header on every request:

Since v1.1.6

DeepSeek V4

DeepSeek V4 ships two MoE models — deepseek-v4-pro (1.6T total / 49B active; GA since 2026-08-13 as model version DeepSeek-V4-Pro-0813, same id) and deepseek-v4-flash (284B / 13B active; re-post-trained 0731 public beta) — with 1M context as the default and a single-model thinking / non-thinking toggle plus a low | high | max reasoning-effort dial (the low tier is new with GA). Pricing moves to a peak/off-peak model on 2026-08-16 (peak 01-04 + 06-10 UTC bills 2× the off-peak base of $0.66/$1.98 Pro, $0.22/$0.66 Flash per M). The same backend exposes both an OpenAI-wire and an Anthropic-wire endpoint, so the SDK supports two routes:

Reasoning channel. V4-thinking, R1, Kimi-thinking, Qwen-reasoning and any future OpenAI-compat reasoner stream their internal monologue on delta.reasoning_content. The shared ChatCompletionsProvider SSE parser now surfaces it as a separate ContentBlock::thinking() block prepended to the assistant turn — callers render or hide it deliberately rather than mixing it into the user-facing answer.

Deprecation lane. deepseek-chat and deepseek-reasoner retire 2026-07-24. The catalog flags both with deprecated_until and replaced_by fields; ModelResolver emits a one-shot warning per process recommending deepseek-v4-flash / deepseek-v4-pro respectively. Set SUPERAGENT_SUPPRESS_DEPRECATION=1 to silence.

Cache-aware billing. OpenAI-compat backends report prompt_tokens as gross (cache hits + misses). The parser now subtracts the cached portion before populating Usage::inputTokens, so the cache discount lands correctly — CostCalculator charges 10% of input price for read hits instead of effectively 110%. Affects every OpenAI-compat backend with caching (DeepSeek, Kimi, OpenAI itself).

Beta endpoint. Set region: 'beta' to route to https://api.deepseek.com/beta for FIM / prefix completion access on the same auth — see completeFim() for the dedicated helper.

Since v0.9.6

Reasoning-effort dial (v0.9.8)

Three-tier dial across DeepSeek native + every relay:

Each upstream gets the body shape it expects: top-level reasoning_effort + thinking: {type: enabled} for DeepSeek native / OpenRouter / Novita / Fireworks / SGLang; nested chat_template_kwargs.{thinking, reasoning_effort} for NVIDIA NIM. Unknown values silently no-op rather than poisoning the request.

Multi-upstream routing (v0.9.8)

Same V4 weights, six relay paths. One upstream config key picks the host:

region is preserved as an alias of upstream for backward compatibility — existing region: 'default' | 'cn' | 'beta' callers are byte-compatible.

V4 Interleaved-Thinking replay (v0.9.8)

V4 thinking mode rejects assistant messages that carry tool_calls without reasoning_content. The provider now:

1. Re-emits each AssistantMessage's thinking blocks as wire reasoning_content automatically (no caller change).
2. Runs a final-pass sanitizer that forces a (reasoning omitted) placeholder on any assistant+tool_calls that slipped through — bullet-proofs sessions restored from disk pre-0.9.8 and sub-agents that hand-build messages.

Disable with reasoning_effort: 'off' (sanitizer skips when thinking is explicitly disabled).

FIM (prefix completion) (v0.9.8)

Hits https://api.deepseek.com/beta/v1/completions. Throws when the provider isn't on the beta region rather than silently routing elsewhere.

/model auto heuristic (v0.9.8)

Pro escalation when: prompt ≥ 32K tokens, ≥ 3 trailing tool turns, explicit reasoning_effort=max, or system-prompt keywords (review / audit / design / architect / plan / debug a complex / analyze the codebase / find the root cause). Flash otherwise.

Cache-aware compaction (v0.9.8)

Wraps any CompressionStrategy. Result shape: [head_pinned, summary_boundary, summary, tail_preserved] with the cached prefix at byte 0. Idempotent across rounds — feeding a compacted result back through the wrapper preserves the same prefix bytes, so DeepSeek's auto prefix cache keeps hitting on every /compact.

MiniMax M3

MiniMax M3 (released 2026-06-01, the minimax default) is the MSA-architecture flagship: a 1M-token context (512K max output), native multimodality (image and video input trained from step 0), and a single-model interleaved-thinking toggle. Standard pay-as-you-go pricing is $0.60 in / $2.40 out per million tokens (a 7-day launch promo currently halves it to $0.30/$1.20; image/video input billed at $1.00/M) — thinking and non-thinking share one price. MiniMax-M2.7 stays available by id or the m2 alias.

Interleaved thinking. A single-model on/off/adaptive toggle, wired through the same thinking: {type: ...} field GLM and DeepSeek V4 use. Drive it three ways:

adaptive (the model picks depth per turn) is MiniMax's recommended default; disabled is the low-latency path for chat / code completion. Reasoning streams back as a separate ContentBlock::thinking() block — the same channel DeepSeek V4 uses, so the rendering code is shared.

Native multimodality. Image and video ride the standard OpenAI-style content parts — image_url and video_url — in your message content; no special flags.

Group routing. Set MINIMAX_GROUP_ID (or group_id in config) to emit the optional X-GroupId header; it's omitted when unset.

Since v1.1.1

GLM-5.2 / 5.3

GLM-5.2 (the glm default as of v1.1.2) is Z.ai's coding-first agentic flagship: a 1M-token context (128K max output), text-only I/O, and — new for the 5.2 line — a reasoning-effort dial on top of the binary thinking toggle. Official pay-as-you-go pricing is $1.40 in / $4.40 out per million tokens, with $0.26 cache-hit input (cache storage currently free, limited-time). glm-5.1 (200K context, same pricing) ships alongside, and every prior glm-5 / glm-4.x id stays reachable.

GLM-5.3 (released 2026-08-14, "Built to Code. Ready for Cyber Defense") is a coding + cyber-defense post-train of the same 5.2 base, reachable as glm-5.3 (alias glm5.3; 1M-context route glm-5.3[1m]). It widens the effort dial to a genuine low | high | max (server default max) and makes thinking mandatory — thinking.type cannot be disabled, so reasoning_effort: off degrades to the low tier instead (matching Z.ai's own Coding Plan adapters). It is live in the GLM Coding Plan while the standalone API rolls out in stages; per-token pricing is not yet published (cost tracking provisionally uses the 5.2 rate), so glm-5.2 stays the provider default for now. Open weights are promised ~2 weeks post-launch.

Reasoning effort. GLM-5.2 adds a reasoning_effort dial on top of the binary thinking toggle; GlmProvider implements both SupportsThinking and SupportsReasoningEffort. Drive it three ways:

off sends thinking: {type: disabled}; high and max send reasoning_effort paired with thinking: {type: enabled} (reasoning_effort wins over a bare thinking toggle when both are set). Reasoning streams back as a separate ContentBlock::thinking() block via the shared delta.reasoning_content channel — the same one DeepSeek V4 uses.

Companion tools. GLM's server-side tools stay available: glm_web_search, glm_web_reader, glm_ocr, glm_asr.

Since v1.1.2

Goal mode (codex /goal parity) (v0.9.8)

Three model-callable tools, four-state lifecycle, two prompt templates. Goals are thread-scoped; each thread has at most one non-terminal goal at a time. The model can ONLY transition active → complete; pause / resume / budget changes flow from user / system.

Persistence. InMemoryGoalStore ships with the SDK; SuperAICore provides EloquentGoalStore (table ai_goals) so a goal survives process restarts.

Untrusted-input wrapping. Both prompt templates wrap the user objective in <untrusted_objective> via Security\UntrustedInput::tag() so a crafted goal can't smuggle higher-priority instructions into the system role:

Recommended at every site that injects user-supplied text into a system-role message — goals, skills, memory imports.

Operational guardrails (v0.9.8)

Sub-agent depth cap

Cap on recursive agent tool calls. Mirrors codex's agents.max_depth.

Depth tracked through the SUPERAGENT_AGENT_DEPTH env so it survives process spawning.

Token-bucket rate limiter

DeepSeek-TUI shape (8 RPS sustained, 16-burst):

In-process fidelity. Cross-process limits are a host concern (Redis- backed Guzzle middleware).

Ephemeral conversation fork (/side semantics)

Ad-hoc memory injection

Companion tools (jcode-inspired)

Five additive primitives borrowed from jcode. Each is opt-in and degrades to no-op when its host wiring is absent.

agent_grep — token-aware grep with enclosing-symbol injection

A sibling of the byte-for-byte ripgrep grep tool. Same flags, plus per-match enclosing-symbol metadata (PHP / JS / TS / Python / Go) and per-session seen-chunk truncation so the model doesn't re-read the same hunk three turns in a row.

Symbol extraction is pluggable via the Tools\Builtin\Symbols\SymbolExtractor SPI:

Tree-sitter is auto-discovered on $PATH (override via SUPERAGENT_TREE_SITTER_BIN or constructor arg). Missing binary / unsupported grammar / failed invocation degrades to "I don't support this" — never throws.

FileLedger — cross-agent edit notification for swarms

Agent A edits a file that agent B has read; B gets a FileShiftedEvent in its mailbox. Lazy-attached to WorktreeManager::fileLedger(), opt-in by tools that record reads/writes; default emitter is no-op so existing swarms are byte-compatible.

AmbientWorker — background memory hygiene with cost split

Long-lived low-priority worker that runs memory dedup + staleness scans on a tick. Tick budget enforced internally so a pass never blocks for more than a few seconds. Token cost is tagged usage_source: 'ambient' via the supplied callback so dashboards split user-facing vs background spend.

Native browser bridge (Firefox / Chromium)

WebExtension Native Messaging — 4-byte length-prefixed JSON framing — lets an agent drive a real browser without Selenium / Playwright. Single launcher per tool instance; tight capability surface (no tab management, cookies, or extension APIs).

Launcher path comes from SUPERAGENT_BROWSER_BRIDGE_PATH (or constructor launcherArgv). The companion Tools\Browser\FirefoxBridge::class docblock contains the full WebExtension + Native Messaging manifest walkthrough.

Pluggable embeddings — Memory\Embeddings\*

EmbeddingProvider interface (batch shape, dimensions(), fingerprint()). Three reference implementations:

Hooks straight into the upgraded SemanticSkillRouter:

superagent resume — cross-harness session pickup

Pick up a Claude Code or Codex CLI session in SuperAgent without losing the thread.

--from accepts claude / claude-code / cc / codex. Behind the scenes: Conversation\HarnessImporter interface + per-harness importers (ClaudeCodeImporter reads ~/.claude/projects/<hash>/<uuid>.jsonl; CodexImporter reads ~/.codex/sessions/**/*.jsonl), feeding internal Message[] into the existing Conversation\Transcoder so the transcript flips wire family transparently.

Since v0.9.7

Agent Loop

Agent::run($prompt, $options) drives the full turn loop until the model stops emitting tool_use blocks. Each turn's cost, usage, and messages flow into AgentResult.

Budget + turn caps

Streaming

For machine-readable event streams (JSON / NDJSON for IDE / CI consumers) see the Wire Protocol section.

Auto-mode (task detection)

Squad mode — Adaptive Cross-Model Squad (v0.9.9)

Auto-mode picks single vs. multi-agent. Squad mode goes further: when a prompt decomposes into 2+ subtasks spanning multiple difficulty bands, each subtask is dispatched to its own model — Haiku for trivial extraction, Sonnet for moderate refactors, DeepSeek-Pro / Opus for hard reasoning. There is no master agent — the workflow definition is the orchestrator and every step is a peer. Human-in-the-Loop gates sit inline as ApprovalSteps.

What it gives you that the master-slave path doesn't:

• Cross-model: each subtask picks its own (provider, model) via ModelTierMap. Defaults are intentionally cross-vendor (Anthropic + DeepSeek + …) so a HARD subtask doesn't pay Opus rates for an EASY peer.
• Stable per-role sessions: squad:{squadId}:role:{roleName} is reused across resumes — the provider's prompt-cache prefix survives, so re-running step N doesn't re-prime the model.
• Skip + restart: SquadResumeManager re-seeds completed step outputs and BFS-invalidates only what depends on a restarted step.
• Parallel groups: prompts with 同时 / in parallel are split on 和 / and, and peers in the same group execute through a single ParallelStep.
• Cost downshift: at 80% of maxCostUsd, remaining steps drop one tier (EXPERT → HARD → MODERATE → …).
• Provider fallback ladder: if a band's primary provider isn't registered, ModelTierMap::resolve() walks down then up to a registered alternative.
• Auto-trigger from auto mode: AutoModeAgent routes into squad when the decomposed prompt spans ≥ 2 difficulty bands. Force with superagent auto "<task>" --squad, opt out with --no-squad.
• Peer-to-peer messaging: agents talk directly via PeerMailbox (tell / broadcast / ask) — no master agent relaying summaries. PeerAsk routes through the peer's stable session so its prompt cache survives. Read-only PeerAsk / PeerSend / PeerInbox tools let an agent call peers from inside its own tool loop.

CLI:

Config (config/superagent.php):

YAML team library (v1.0.1)

A SquadPlan no longer requires PHP code. Drop a YAML file, register it, run it:

21 production-grade teams ship in resources/squad-teams/ — engineering (code-review-loop, code-bug-triage, code-test-driven, code-security-audit, code-perf-optimize, …), architecture (arch-from-scratch, arch-decision-record, arch-migration-plan), QA/SRE (qa-ship-gate, qa-multi-model-council, qa-incident-response), product (product-strategy-trio, product-discovery-pair), docs (docs-tech-pipeline, docs-api-spec-pipeline), data (data-research-trio, data-anomaly-detector), ops/growth (release-coordination, growth-hypothesis-test).

Three-tier override: hosts call addDirectory('/path/to/host-teams') to layer additional YAML files on top of the bundled library, or register($name, $plan) for programmatic overrides. Later directories override earlier ones; runtime registrations override directory entries. Same pattern ModelCatalog uses.

Reviewer-loop runner: Squad\ReviewerLoopRunner wraps any agentDispatcher callable. When the reviewer's first non-blank line doesn't start with APPROVED (case-insensitive), the runner prepends the reviewer's feedback to the writer's prompt and re-dispatches the writer. Loop exits on approval or max_retries.

Cross-mode orchestration (v1.0.1)

auto / smart / squad can now compose, recurse, and hand off through one shared ModeContext. A squad step can declare mode: smart and recurse into the orchestrator; a smart sub-task can land on a full squad; a reviewer that hits max_retries escalates to smart automatically. Across every layer, blackboard reads, cost-ledger writes, and prompt-cache session ids share one object — there are no isolated child islands.

The ModeContext flows through every recursion level:

Loose-coupling SPIs:

• Squad\SquadDispatcherRegistry::set($dispatcher) — hosts install a default squad dispatcher (e.g. a CLI-aware one)
• Modes\ModeRouterRegistry::set($router) — hosts install a default cross-mode router (e.g. one that knows cli:claude_cli leaf tags alongside the three mode names)

Both are class-level static slots. SDK code paths consult them before falling back to internal defaults. SDK itself never sets either — slots are reserved for hosts.

Gemini 3.5 + thinking / grounding (v1.0.5)

gemini-3.5-pro / gemini-3.5-flash / gemini-3.5-flash-lite are first-class catalog entries (alias gemini → 3.5 Pro). The 3.x preview SKUs from gemini-cli (gemini-3-pro-preview, gemini-3.1-pro-preview, gemini-3-flash-preview, gemini-3.1-flash-lite-preview) ship too. Provider default upgraded from gemini-2.0-flash → gemini-3.5-flash.

AssistantMessage::$metadata['grounding_sources'] carries [{uri, title}, ...] for any Google-Search citation; parts[].thought (Gemini 3.x thinking parts) is surfaced as ContentBlock::thinking(), and usageMetadata.thoughtsTokenCount folds into Usage::$outputTokens.

Semantic loop detection (v1.0.5)

Guardrails\LoopDetector already catches hash-identical repetition (5 tool-call dupes, 10-char content chants, 8 file-reads in a 15-call window, …). New Guardrails\LlmLoopChecker complements it with a Flash-model probe after the 30th turn — catches semantic loops the hashes miss (model paraphrases the same plan ten times without acting). Prompt is the verbatim gemini-cli LOOP_DETECTION_SYSTEM_PROMPT; check interval adjusts dynamically (5–15 turns).

Six opencode patterns ported (v1.0.5)

Each fills a gap relative to a production coding agent; every piece is opt-in and tested.

Chrome Trace Event timeline (v1.0.6)

Every long-running orchestration (debate, red-team, error-recovery, cost-autopilot, parallel agents) now writes a lock-free ring buffer of TraceEvent records. Trigger sites (errors, snapshot tool calls, completed protocols) flush to a .json file you open in chrome://tracing or ui.perfetto.dev.

Wired-up emitters: Debate\DebateOrchestrator (debate.start / debate.rounds / debate.round_N / debate.judge / debate.total plus redteam.* / ensemble.*), ErrorRecovery\ErrorRecoveryManager (auto-dumps the last N events on unrecoverable / retries-exhausted), CostAutopilot\CostAutopilot (budget.spend counter + budget.tier_change instants), Console\Output\ParallelAgentDisplay::exportPerfettoJson() (whole-team snapshot). Env: SUPERAGENT_TRACE_ENABLED=false to disable, SUPERAGENT_TRACE_PATH=… to override.

The agent itself can call snapshot('about to git reset', tag: 'pre_destructive') (new SnapshotTool) when something feels off — pure observability, isReadOnly === true.

Pi-aligned JSON Event Stream (v1.0.6)

A canonical 18-type session-event taxonomy borrowed from pi's JSON Event Stream Mode so SuperAgent sessions can be replayed by any pi-compatible viewer.

Event types: session / agent_start / agent_end / turn_start / turn_end / message_start / message_update / message_end / tool_execution_start / tool_execution_update / tool_execution_end / queue_update / compaction_start / compaction_end / auto_retry_start / auto_retry_end / model_change / thinking_level_change. Legacy SuperAgent event names round-trip via PiEventStream::translateLegacy().

Mid-turn steering + follow-up queue (v1.0.6)

Pi-borrowed mid-turn correction without aborting + post-turn follow-up queueing. An operator (or host RPC handler) can nudge a running agent without losing tool state.

Same surface on ACP: editors that speak the protocol send session/steer / session/follow_up JSON-RPC methods (constants Protocol::METHOD_SESSION_STEER / METHOD_SESSION_FOLLOW_UP). Handler contract gains steer($params) / followUp($params); DefaultHandler ships drain helpers (drainSteer($sessionId) / drainFollowUp($sessionId)) for the host's promptFn to consume at safe checkpoints.

RTK structured-output compression (v1.0.6)

git diff / grep -rn / find / ls -R / tree outputs dominate token usage in coding sessions — typically 30-50 % of input budget per turn, much of it cosmetic. Tools\Compression\RtkPipeline (borrowed from 9Router + claude-octopus) auto-compresses these in a lossy-safe way: paths, line numbers, diff hunks are preserved verbatim; cosmetic noise is dropped. Wired into QueryEngine — every non-error tool result goes through it.

Opt out per-call via options: ['disable_rtk_compression' => true]. Stats available via $pipeline->stats() (bytes_in / bytes_out / saved_bytes / ratio).

Cross-provider tool-schema portability (v1.0.6)

Anthropic, OpenAI, Gemini all accept slightly different subsets of JSON Schema (Gemini rejects $ref / $defs / top-level oneOf; OpenAI strict mode is stricter than non-strict; etc.). Tools\Schema\Schema lets you declare a schema once carrying intent markers; ProviderNormalizer rewrites it per provider.

Cross-provider compliance is verified by tests/Tools/Schema/CrossProviderComplianceTest.php — round-trips every tagged shape through all three normalisers and asserts each output passes the target provider's acceptance rules.

Kimi (Moonshot) compatibility hardening (v1.0.10)

Validated by diffing SuperAgent's Kimi path against MoonshotAI's official kimi-code client (packages/kosong, packages/oauth). Unlike the opt-in ProviderNormalizer above (which you invoke when authoring a schema), these run automatically on the wire:

• Tool schemas are normalized for Moonshot's validator on every request. Format\JsonSchemaNormalizer inlines local $ref / $defs and fills a type onto typeless property schemas — the common enum-only MCP shape Moonshot rejects — so MCP / Skill / Agent tools reach Kimi intact. The $ref-inlining pass is also exposed as an overridable normalizeToolSchema() hook on ChatCompletionsProvider, so any strict backend can opt in.
• Streaming requests opt into usage. stream_options: {include_usage: true} is now sent on every streaming chat-completions request. Without it the OpenAI-spec servers (Kimi included) return no usage block — silently zeroing token / cost / cached-token accounting. Benefits every OpenAI-compatible provider.
• max_completion_tokens. Kimi reasoning models share the completion budget with the hidden reasoning_content channel; the cap now rides on max_completion_tokens so a small value can't starve the answer into an empty 200.
• reasoning_content round-trip. Kimi replays its prior reasoning across multi-turn history (shared with the DeepSeek path), keeping a think → tool-call → think sequence coherent.
• Per-model capability discovery. ModelCatalogRefresher maps Moonshot's supports_reasoning / image_in / video_in / tool_use (and OpenRouter's supported_parameters) from /models into the CapabilityRouter capability map.
• Agent Swarm is opt-in. kimi_swarm returns an actionable error unless SUPERAGENT_KIMI_SWARM_ENABLED is set — kimi-code ships no swarm REST endpoint (its parallelism is local coder / explore / plan subagents). The REST plumbing and its wire-contract tests are retained for when Moonshot publishes the spec.

Tests: tests/Unit/Format/JsonSchemaNormalizerTest.php, tests/Unit/Providers/KimiProviderTest.php, tests/Unit/Providers/ChatCompletionsSseParserTest.php.

Session branching — pi /tree fork (v1.0.6)

Pi models a session as an append-only tree, not a line. SuperAgent now mirrors /tree:

Conversation\BranchManager provides the pure tree algebra (no I/O, no LLM) — leaves(), ancestry($id), findCommonAncestor($a, $b), collectBranch($leaf, $ancestor), makeBranchSummaryEntry(). Conversation\Importers\PiImporter replays existing pi sessions (~/.pi/agent/sessions/) into SuperAgent's wire format.

Squad consensus gates — N-of-M parallel voting (v1.0.6)

The existing reviewer_loop is a serial, single-veto gate (one reviewer agrees → pass). Squad\ConsensusGate (borrowed from claude-octopus) is a parallel N-of-M gate: M peers vote in parallel, ≥N must approve.

Tally returns {verdict, passed, counts, per_voter}; downstream steps branch on passed.

Qwen 3.7 Max + Anthropic-protocol drop-in (v1.0.6)

Qwen 3.7 Max (released 2026-05-21) ships native Anthropic API protocol support — the /v1/messages wire is byte-compatible with Anthropic's canonical shape, so Claude-Code-shaped clients can point at DashScope and use Qwen as a drop-in.

TODO: DashScope's exact Anthropic-protocol endpoint URL is not yet documented in English; the default dashscope.aliyuncs.com/anthropic-mode/v1 is best-guess. Verify and override via base_url until Alibaba publishes it.

Recipe cookbook (v1.0.6)

Focused, copy-pasteable recipes for the higher-level subsystems live under docs/cookbook/:

• 01-debate-protocol.md — proposer / critic / judge structured debate
• 02-redteam-attack.md — builder / attacker / reviewer adversarial pattern
• 03-cost-autopilot.md — budget-driven model tiering (Opus → Sonnet → Haiku cascade)
• 04-cost-prediction.md — KNN-based proactive spend prediction
• 05-adaptive-feedback.md — corrections promote into auto-applied patterns

Idempotency

Since v0.9.1

Tools & Multi-Agent

Tools are subclasses of SuperAgent\Tools\Tool. Built-in tools — read / write / edit / bash / glob / grep / search / fetch — auto-load unless the caller opts out. Custom tools register via $agent->registerTool(new MyTool()).

Multi-agent orchestration (AgentTool)

Dispatch sub-agents in parallel by emitting multiple agent tool_use blocks in one assistant message:

Each sub-agent runs in its own PHP process (via ProcessBackend); blocking I/O in one child doesn't block siblings. When proc_open is disabled, fibers take over.

Productivity evidence

Every AgentTool result carries hard evidence of what the child actually did — not just success: true:

completed_empty — zero tool calls observed. Re-dispatch or pick a stronger model. completed + non-empty productivityWarning — the child invoked tools but wrote no files (often fine for advisory consults; check the text).

Productivity instrumentation since v0.8.9. CJK localisation + filesystem audit since v0.9.1.

Output-directory audit + guard injection

Pass output_subdir to opt into both (a) a CJK-aware guard-block prepended to the child's prompt and (b) a post-exit filesystem scan:

Since v0.9.1

Provider-native tools

Any main brain can call these as regular tools — no provider switch needed.

Moonshot server-hosted builtins (execute server-side; results inlined in the assistant reply):

Other provider-native tool families:

• Kimi — KimiFileExtractTool, KimiBatchTool, KimiSwarmTool, KimiMediaUploadTool
• Qwen — QwenLongFileTool + dashscope_cache_control feature
• GLM — glm_web_search, glm_web_reader, glm_ocr, glm_asr
• MiniMax — minimax_tts, minimax_music, minimax_video, minimax_image

Agent Definitions (YAML / Markdown)

Auto-loaded from ~/.superagent/agents/ (user scope) and <project>/.superagent/agents/ (project scope). Three formats: .yaml, .yml, .md. Cross-format extend: inheritance.

Tool-list fields (allowed_tools, disallowed_tools, exclude_tools) accumulate through extend: chains. Cycle depth-limited.

Since v0.9.0

Skills

Markdown-based capabilities you can register globally and pull into any agent run:

Skill markdown supports frontmatter with name, description, allowed_tools, system_prompt. Skill runs inherit the caller's provider.

MCP Integration

Server registration

Config persists atomically at ~/.superagent/mcp.json.

OAuth-gated MCP servers

Servers declaring an oauth: {client_id, device_endpoint, token_endpoint} block in their config use this flow. Since v0.9.0.

Declarative catalog + non-destructive sync

Drop a catalog at .mcp-servers/catalog.json (or .mcp-catalog.json) in your project root:

Sync to a project .mcp.json:

Non-destructive contract — byte-equal disk hash → unchanged; a user-edited file is kept as user-edited; first-time writes or our-last-hash matches become written. A manifest at <project>/.superagent/mcp-manifest.json tracks sha256 of every file we've written so stale entries clean up automatically.

Since v0.9.1

Wire Protocol

v1 — line-delimited JSON (NDJSON), one event per line, self-describing via wire_version + type top-level fields. Foundation for IDE bridges, CI integrations, structured logs.

Transport (since v0.9.1)

Choose where the stream goes via a DSN:

Programmatic use:

Non-blocking peer socket means a dropped IDE doesn't stall the agent loop.

Wire Protocol v1 since v0.9.0. Socket / TCP / file transport since v0.9.1.

Retry, Errors & Observability

Layered retry

Jittered exponential backoff (0.9–1.1× multiplier) prevents thundering-herd retries from parallel workers. Retry-After header honoured exactly (no jitter — the server knows best).

Since v0.9.1

Classified errors

Six subclasses of ProviderException emitted by OpenAIErrorClassifier against the response body's error.code / error.type / HTTP status:

All subclasses extend ProviderException, so pre-existing catch (ProviderException) sites keep working unchanged.

Since v0.9.1

Health dashboard

Wraps ProviderRegistry::healthCheck() — distinguishes auth rejection (401/403) from network timeout from "no API key" so an operator can fix the right thing without guessing.

Since v0.9.1

SSE parser hardening (since v0.9.0)

• Per-index tool-call assembly — one streamed call split across N chunks now produces one tool-use block, not N fragments.
• finish_reason: error_finish detection — DashScope-compat throttles raise StreamContentError (retryable, HTTP 429) instead of silently polluting the message body.
• Truncated tool-call JSON repair — one-shot attempt to close unbalanced braces before falling back to an empty arg dict.
• Dual-shape cached-token reads — usage.prompt_tokens_details.cached_tokens (current OpenAI shape) AND usage.cached_tokens (legacy) both populate Usage::cacheReadInputTokens.

Guardrails & Checkpoints

Loop detection (since v0.9.0)

Five detectors observe the streaming event bus; first trigger is sticky:

Violations fan out as loop_detected wire events — the agent keeps running, the host decides whether to intervene.

Checkpoints + shadow-git (since v0.9.0)

Every turn snapshots the agent state (messages, cost, usage). Attach a GitShadowStore and file-level snapshots land alongside in a separate bare git repo at ~/.superagent/history/<project-hash>/shadow.git — never touches the user's own .git.

Restore reverts tracked files and leaves untracked files in place for safety. The project's own .gitignore is respected (the shadow's worktree IS the project dir).

Permission modes

ask prompts the caller's PermissionCallbackInterface before any write-class tool. Wrap it in WireProjectingPermissionCallback to surface the request as a wire event for IDE prompts.

Standalone CLI

Options:

Interactive commands (inside the REPL):

Standalone CLI since v0.8.6.

Laravel Integration

The service provider auto-registers when you composer require forgeomni/superagent:

Artisan commands mirror the CLI:

See docs/LARAVEL.md for queue integration, job dispatching, and the ai_usage_logs schema.

SmartFlow — cross-model dynamic flows (v1.1.0)

A PHP port of the Claude Code Workflow engine, made cross-model / cross-API: the same primitives — agent(), parallel(), pipeline(), gate(), budget, schema/SKIP — drive any of the 15 providers. One set of primitives, many brains.

Beyond the built-in engine it adds a 3-layer structured-output safety net (native → submitted → extracted, falling back to a SKIP sentinel), reusable roles/personas, gates with fallback/relay, a call-ledger + signature for token-free checkpoint resume, true process-pool parallelism, and a MULTI_AI_FAKE_PROVIDER=1 zero-cost rehearsal mode (every shipped flow is guaranteed to rehearse green).

Static flows are also authored declaratively in resources/flows/*.yaml (strategies: solo / parallel / pipeline / gate, with {{args.x}} / {{steps.name.output}} templating). Full guide: docs/smartflow.md.

Host Integrations

Frameworks that embed SuperAgent — typically multi-tenant platforms that store encrypted provider credentials in a database row and spin up an agent per request — use ProviderRegistry::createForHost() instead of create(). The host passes a normalised shape and the SDK dispatches to the right constructor via per-provider adapters.

Every ChatCompletions-style provider (Anthropic, OpenAI, OpenAI-Responses, OpenRouter, Ollama, LM Studio, Gemini, Kimi, Qwen, Qwen-native, GLM, MiniMax) uses the default pass-through adapter. Bedrock ships a built-in adapter that splits credentials.aws_access_key_id / aws_secret_access_key / aws_region into the AWS SDK's shape.

Plugins or hosts that need to customise an adapter register their own:

New SDK provider keys in future releases register their own adapter (or ride the default one), so the host-side factory code never needs to grow a new match arm per release.

Since v0.9.2

Configuration reference

Every option accepted by the Agent constructor, grouped. Defaults in parentheses.

Provider selection

Agent loop

Per-call options ($agent->run($prompt, $options))

Retry + transport (provider-level)

Links

• CHANGELOG — full per-release notes
• INSTALL — install + first-run setup
• Advanced usage — patterns, sample agents, debugging
• Native providers — region maps + capability matrix
• Wire protocol — v1 spec
• Features matrix — which provider supports which feature

License

MIT — see LICENSE.