CodexFlow QueryRuntime (QRE)

English | 简体中文

CodexFlow QueryRuntime (QRE) is a cross-platform .NET agent runtime and lightweight command-line harness engineered for production-grade agentic systems. It packages model iteration loops, policy-gated tool execution, audit and replay, fault recovery (H1 Crash Recovery), sandboxing, and client-side outbound diagnostics into a cohesive, deterministic, and self-contained infrastructure.

QRE can be embedded directly into .NET host applications via official NuGet packages or published as a standalone, zero-dependency qre Native AOT binary, operating independently of the CodexFlow web platform.

This repository is on the 0.24.0 stable, v2-only line. All active development and integrations target CodexFlow.QueryRuntime.Protocol, CodexFlow.QueryRuntime.Engine.V2, and CodexFlow.QueryRuntime.Models. The legacy v1 API has been severed from active execution and remains strictly for historical trace inspection and migration compatibility.

• Why QueryRuntime (QRE)
• Architecture & Layering
• Quickstart
• CLI Command Reference
  • 1. Workspace Initialization & Diagnostics (init, doctor)
  • 2. Running Agent Tasks (run)
  • 3. Tool Catalog & Invocation (tool)
  • 4. Policy & Security Pre-flight (policy check)
  • 5. Auditing, Replay & Rerun (trace, replay, rerun)
  • 6. Fault Recovery (resume)
  • 7. Workspace Diff (diff)
  • 8. Controlled Sandbox Execution (sandbox exec)
  • 9. SDK Outbound Diagnostics Suite (diagnose)
• Tool System & Ecosystem Extension
  • Built-in Tools & Policy Profiles
  • External Tool Manifests (Stdio & MCP)
  • Dynamic Tool Retrieval (Tool Search)
• Skill System & Workflows
  • 1. Conceptual Positioning: Atomic Tools vs. Domain Skills
  • 2. Standard Skill Specification & Directory Structure
  • 3. Two-Phase Progressive Loading & Discovery
  • 4. Configuration & Usage in QRE
  • 5. Ecosystem Skills & Typical Scenarios
• Sandboxing & Security Model
• Fault Recovery & Deterministic Replay
• Troubleshooting & Logs
• Model Providers & Thinking Policies
  • Thinking Policy Control (--thinking)
  • Structured Outputs via JSON Schema
• Embedding in .NET Applications
• Runnable Examples Showcase
• Building, Testing & Native AOT Publish
• Technical Documentation Index
• License

Prototype agents are easy to build, but hardening them into reliable software is notoriously difficult. Developers constantly battle inconsistent LLM API behaviors, Chain-of-Thought (CoT) colliding with tool calls, uncontained execution side effects, unreproducible runtime crashes, and SDKs silently dropping structured arguments.

QRE fills the gap between "a 50-line script" and "a heavyweight SaaS platform":

1. Typed Agent Loop: Formal abstraction over Session, Turn, Step, and Invocation, with strict Token/Step budget enforcement and deterministic context compaction.
2. Fail-Closed Policy Pipeline: Four-tier security profiles with mandatory explicit approval gates (--approve-risk) for write operations.
3. Zero-Token Strict Replay: Offline, zero-cost, deterministic replay that validates historical execution trajectories without contacting models or executing tools, yielding a byte-identical replay_digest.
4. H1 Local Crash Recovery: Robust process self-healing with attempt leases, atomic checkpoints, and drift prevention against workspace, policy, or tool changes.
5. SDK Outbound Diagnostics: End-to-end client-side request inspection capturing QRE intent, MEAI options, and HTTP handler payloads to pinpoint argument dropping or serialization bugs.
6. Dual Sandbox Execution: High-speed trusted execution (LocalProcess) and isolated container execution (Docker) with selective write-back and network restrictions.
7. Native AOT Ready: Built on .NET 10, publishing into self-contained native binaries with sub-second startup times and zero JIT overhead.

┌────────────────────────────────────────────────────────┐
│               Host Applications / qre CLI              │
└───────────────────────────┬────────────────────────────┘
                            │
┌───────────────────────────▼────────────────────────────┐
│             CodexFlow.QueryRuntime.Engine (V2)         │
│  ┌──────────────────┐  ┌──────────────────┐  ┌───────┐ │
│  │  IAgentRuntime   │  │  Tool Pipeline   │  │ Audit │ │
│  │ State Reducer    │  │  Fail-Closed Gate│  │ & H1  │ │
│  └────────┬─────────┘  └────────┬─────────┘  └───────┘ │
└───────────┼─────────────────────┼──────────────────────┘
            │                     │
┌───────────▼──────────┐ ┌────────▼──────────┐ ┌─────────▼───────────┐
│     Models (MEAI)    │ │   Experimental    │ │   Sandbox Runners   │
│ OpenAI / vLLM / Claude│ │ Built-in Tools   │ │ LocalProcess        │
│ Outbound Diagnostics │ │ Tool Search / Stdio│ Docker Container    │
└──────────────────────┘ └───────────────────┘ └─────────────────────┘
            │                     │                      │
┌───────────┴─────────────────────┴──────────────────────┴───────────┐
│                 CodexFlow.QueryRuntime.Protocol                    │
│      Immutable Turn / Step / Tool / Event / Checkpoint Types       │
└────────────────────────────────────────────────────────────────────┘

• Required: .NET 10 SDK
• Optional: Docker (for container sandbox), Python 3.9+ / Node.js (for external tools or regression scripts)

# Build the entire solution
dotnet build CodexFlow.QueryRuntime.slnx

# Run deterministic unit tests
dotnet test CodexFlow.QueryRuntime.UnitTests/CodexFlow.QueryRuntime.UnitTests.csproj

Commands can be executed via dotnet run or from a published qre binary:

# Optional alias in PowerShell:
# function qre { dotnet run --project D:/codeup/codexflow.queryruntime.engine/CodexFlow.QueryRuntime.Cli -- $args }

# Check CLI version
qre --version

# 1. Deterministic offline smoke test (no credentials or network required)
qre run --workspace . --response "Offline smoke: QRE is operational" --json "hello world"

# 2. Inspect codebase using the read-only tool profile
qre run --workspace . --profile readonly --response "read files" "summarize the repository layout"

# 3. Deterministic strict replay of the latest run (zero token cost, zero side-effects)
qre replay latest --workspace . --strict --json

qre run --workspace . \
  --api-url "https://api.openai.com/v1" \
  --api-key "sk-..." \
  --model "gpt-4o" \
  --api-mode chat-completions \
  --profile readonly \
  --stream \
  "inspect this codebase and report architectural risks"

Standard environment variables are also supported:

• QRE_API_URL: Provider endpoint (e.g. http://localhost:8000/v1)
• QRE_API_KEY: API authentication key
• QRE_MODEL: Target model (e.g. qwen2.5-coder or gpt-4o)
• QRE_API_MODE: Protocol mode (chat-completions, responses, or anthropic-messages)

The qre CLI provides a complete suite of commands covering the full agent lifecycle:

qre <command> [options]
  init       Initialize workspace and .qre metadata
  doctor     Run environment and dependency diagnostics
  run        Execute the agent runtime loop
  tool       List, register, or invoke tools directly
  policy     Pre-flight check tool execution policies and risks
  trace      Inspect event logs, tokens, and execution traces
  logs       Find runs by time and preview or execute date-based cleanup
  replay     Summarize traces or execute strict offline replay
  rerun      Re-execute the latest task with existing configuration
  resume     Recover an interrupted run from a checkpoint (H1)
  diff       Inspect workspace file changes from a run
  sandbox    Execute commands inside policy-controlled sandboxes
  diagnose   Inspect, compare, and rebuild SDK outbound HTTP requests

• qre init: Sets up .qre/ layout and .qre/tools/ for external manifests.

  qre init --workspace . [--force] [--json]

• qre doctor: Verifies .NET version, Git state, Docker availability, Python/Node.js runtimes, and provider environment configurations.

  qre doctor --workspace . [--json]

qre run --workspace <path> [options] "<prompt>"

Test, debug, and manage tools independently of the agent loop:

# List tools available in a profile with parameter schemas
qre tool list --workspace . --profile readonly --json

# List both built-in and external tools
qre tool list --workspace . --profile verify --external

# Register an external tool manifest
qre tool register --workspace . --manifest my_tool.json [--force]

# Invoke a tool in isolation for testing and debugging
qre tool invoke --workspace . --name qre_read_file --arguments '{"path":"README.md"}' --json

Verify whether a specific command or tool call complies with runtime policies before execution:

# Check if dotnet test is allowed under the verify profile
qre policy check --workspace . --profile verify --tool qre_dotnet_test -- dotnet test --no-restore

# Verify high-risk command with explicit approval
qre policy check --workspace . --profile repair --tool qre_patch --approve-risk "Refactor" -- git apply

• Trace Inspection:

  # View latest run summary and events
  qre trace latest --workspace . --json
  qre trace latest --workspace . --jsonl

• Deterministic Replay:

  # Read-only summary (no execution)
  qre replay latest --workspace . --summary
  
  # Strict deterministic replay (validates trajectory, emits replay_digest)
  qre replay latest --workspace . --strict --json

• Rerun:

  # Re-execute the latest task with existing prompt and parameters
  qre rerun latest --workspace . --trace-data sanitized

If a run is terminated prematurely by process crash or timeout, QRE seamlessly resumes execution using its atomic checkpoint and attempt lease model:

# Resume latest interrupted run (validates workspace, tools, policy drift)
qre resume latest --workspace . --json

# View workspace modifications from the latest run (reads run-scoped diff.patch)
qre diff latest --workspace .

# Output patch statistics
qre diff latest --workspace . --stat --json

Execute individual commands inside the policy and sandbox pipeline with timeouts and buffer protection:

# Run locally under verify profile
qre sandbox exec --workspace . --profile verify -- dotnet build

# Run inside a Docker container
qre sandbox exec --workspace . --runner docker --docker-image mcr.microsoft.com/dotnet/sdk:10.0 -- dotnet test

Diagnose why a provider dropped parameters, failed schemas, or choked on reasoning tokens:

# 1. Run task with structural SDK outbound tracing
qre run --workspace . --sdk-diagnostics structure "audit dependencies"

# 2. Inspect outbound diagnostic evidence for the latest run
qre diagnose latest --workspace . --json

# 3. Compare two runs to locate where an option was dropped
qre diagnose compare <left_run_id> <right_run_id> --workspace .

# 4. Export sanitized diagnostic bundle (safe to share; no keys or code)
qre diagnose export latest --output issue_bundle.zip --workspace .

# 5. Extract request skeleton and rebuild offline
qre diagnose skeleton latest --output request_fixture.json
qre diagnose rebuild request_fixture.json --json

QRE enforces a strict principle of least privilege through four profiles:

       [ none ]        Pure reasoning; no tools permitted
          │
      [ readonly ]     File exploration & search (qre_list_files, qre_read_file, qre_search_files)
          │
       [ verify ]      Read-only verification (+ git_status, git_diff, dotnet_build, dotnet_test)
          │
       [ repair ]      Modifications & patches (+ qre_apply_patch, external writers) ──► Requires --approve-risk

Extend QRE with Python, Node.js, or compiled binaries by placing a JSON manifest in .qre/tools/<name>.json:

{
  "name": "calc_coverage",
  "description": "Calculates code test coverage report for the repository",
  "executable": "python",
  "arguments": ["scripts/calc_coverage.py"],
  "parameters": {
    "type": "object",
    "properties": {
      "format": {
        "type": "string",
        "enum": ["summary", "detailed"],
        "description": "Report format"
      }
    },
    "required": ["format"]
  },
  "timeoutSeconds": 30
}

Enable external tools via qre run --external .... Minimal MCP stdio tools are also supported. See examples/ExternalTools, examples/PythonFunctionTools, and examples/NodeFunctionTools.

Providing dozens of tool schemas upfront bloats prompt tokens and increases model hallucinations.

With --tool-search (and --tool-search-top-k 5):

1. QRE exposes only a single tool_search meta-tool on startup.
2. The agent queries tool_search(query="coverage") when it identifies a need.
3. QRE dynamically activates the most relevant Top-K tools into the next step's context.
4. Token overhead is reduced by up to 80% on large catalogs.

In production engineering, relying solely on atomic tools (e.g., reading files or running shell commands) can cause LLMs to lose strategic direction in multi-phase tasks. Conversely, cramming enterprise coding guidelines and domain workflows into system prompts quickly exhausts the context window. QRE natively supports the Skill system to provide agents with modular, on-demand Procedural Knowledge.

Each skill is organized as a self-contained directory rooted by a standard SKILL.md file:

my-custom-skill/
├── SKILL.md                 # [Required] YAML Frontmatter metadata + markdown instructions
├── scripts/                 # [Optional] Deterministic execution scripts (Python/Bash/Node.js)
├── references/              # [Optional] Domain schemas, API specs, or reference documents
└── assets/                  # [Optional] Boilerplates, code templates, or icons

---
name: code-reviewer
description: Enforces architectural boundaries, zero-warning compilation, immutable protocols, and security standards. Use when reviewing PRs or new code additions.
---

# Code Reviewer Skill

## Review Principles & Workflow
1. Verify architectural layering (Protocol contracts must never depend on Engine/UI);
2. Ensure deterministic resource lifecycle management (all `IDisposable` managed cleanly);
3. Enforce compiler zero-warning standards under `<Nullable>enable</Nullable>`.

To minimize context window consumption, QRE and VllmChatClient employ a Two-Phase Progressive Loading mechanism:

┌────────────────────────────────────────────────────────┐
│  Phase 1: Lightweight Metadata Discovery (Low Tokens)  │
│  Client scans skills directory, extracts frontmatter,   │
│  and injects a concise `# Skills` catalog into prompt  │
└───────────────────────────┬────────────────────────────┘
                            │
┌───────────────────────────▼────────────────────────────┐
│  Phase 2: On-Demand Workflow Activation                │
│  Agent matches task intent -> calls `ReadSkillFile`     │
│  Loads full skill markdown only when actively needed   │
└────────────────────────────────────────────────────────┘

QRE automatically discovers skills across multiple priority tiers:

1. Explicitly configured SkillDirectoryPath;
2. Environment variable CODEX_SKILLS_DIR;
3. Application root ./skills;
4. Current workspace ./skills or .qre/skills;
5. Recursive parent directory scan.

Configure VllmChatOptions with EnableSkills = true and the directory path. The underlying client automatically handles metadata discovery and built-in tool registration:

using CodexFlow.QueryRuntime.Models;
using Microsoft.Extensions.AI;

var chatOptions = new VllmChatOptions
{
    EnableSkills = true,
    SkillDirectoryPath = Path.Combine(AppContext.BaseDirectory, "skills"),
    ThinkingEnabled = true
};

// VllmChatClient automatically advertises available skills in the system prompt
// and registers two built-in discovery tools:
// 1. ListSkillFiles: Lists available skills with descriptions and file paths
// 2. ReadSkillFile: Reads the full markdown instructions of a targeted skill

Direct the agent to follow a specific skill from the command line:

qre run --workspace . --profile verify "Follow code-reviewer skill to audit recent architectural changes"

For a complete runnable example, see examples/SkillsWorkflow.

QRE follows a Fail-Closed security architecture, treating model output, tool arguments, external manifests, and workspace files as untrusted:

1. LocalProcessSandboxRunner:
   • Designed for trusted developer workflows.
   • Enforces timeouts, buffer truncation, and process group lifecycle management.
   • Note: Local process execution is not an isolated security boundary.
2. DockerSandboxRunner:
   • Hard isolation for untrusted commands and CI runners.
   • Read-only workspace volume mounts by default.
   • Selective write-back for approved artifact persistence.
   • Network allowlisting support.
   • Configurable image via --docker-image <image_name>.
3. Trace Storage Classes:
   • public: Redacted, shareable, no secrets, no checkpoints (not resumable).
   • sanitized: Preserved payloads for reviewed synthetic test fixtures.
   • private: Full diagnostic and recovery data with checkpoints.

For long-running tasks, QRE's V2 engine guarantees seamless fault recovery:

• Atomic Checkpoints: Checkpoints written to .qre/v2/checkpoints/ after every state step.
• Attempt Leases: Prevents concurrent execution or double-recovery conflicts.
• Drift Prevention: Validates workspace identity, tool registry hashes, policy snapshots, and model configurations before resuming.
• See the H1 Crash-Resume Implementation Report.

• Evaluates complete recorded trajectories completely offline.
• Injects deterministic clocks and query IDs.
• Emits a stable replay_digest for verifiable regressions and benchmarks.

Start with the failure time in your application logs, list QRE runs overlapping that interval, then select the corresponding audit for replay. Set --workspace to the production workspace that actually stores .qre; replace /app/data below with that path.

# List all matching runs in ascending start-time order (14:00–14:30 at UTC+08:00)
qre logs list --workspace /app/data --from 2026-09-27T14:00:00+08:00 --to 2026-09-27T14:30:00+08:00

# Return the same interval as JSON for scripted analysis
qre logs list --workspace /app/data --from 2026-09-27T14:00:00+08:00 --to 2026-09-27T14:30:00+08:00 --json

# Page through audits in descending start-time order
qre logs list --workspace /app/data --kind audit --descending --skip 0 --take 100

# Filter by UTC creation date
qre logs list --workspace /app/data --date 2026-09-27

The range includes its start and excludes its end. Timestamps require seconds and a timezone; output uses UTC. Matching uses overlapping run intervals, so a task that started before the failure window can still appear. Each row represents a whole run, not an individual event. Active records are treated as unfinished, including stale active records left by a crashed process. Either --from or --to may be used alone; neither can be combined with --date or --before.

Rows include start time, last update time, kind, run ID, status, directory size and absolute path. --kind accepts all (default), audit, private or diagnostics, covering v2 audits, private audits and SDK diagnostics. Host application logs, v1 traces and externally exported bundles are outside this scope. Pagination limits output only; queries still scan directory metadata.

Append audit.v1.jsonl to an audit directory returned by the list command and substitute that path below:

# Inspect the selected historical audit summary
qre replay latest --workspace /app/data --audit-file /app/data/.qre/v2/runs/RUN_ID/audit.v1.jsonl --summary --json

# Strictly validate an audit that supports recorded replay
qre replay latest --workspace /app/data --audit-file /app/data/.qre/v2/runs/RUN_ID/audit.v1.jsonl --strict --json

--audit-file overrides automatic latest selection. The file must remain inside the specified workspace and cannot use linked paths. Public redacted audits support summaries only; strict replay requires recorded replay data. Recorded replay does not contact a model or execute real tools. Inspect the selected JSONL for individual failure events. SDK diagnostic directories must be analyzed using the commands in qre diagnose --help, rather than passed to audit replay.

# Preview cleanup for one UTC creation date
qre logs delete --workspace /app/data --date 2026-09-20

# Preview runs created strictly before midnight UTC on this date
qre logs delete --workspace /app/data --before 2026-09-20

# Apply cleanup after checking the preview
qre logs delete --workspace /app/data --before 2026-09-20 --execute --json

Deletion requires --date or --before and only previews matches unless --execute is supplied. It removes entire run directories, including checkpoints, replay blobs, artifacts and patches; those records can no longer be replayed or resumed. Active, unknown, corrupt or linked records and incomplete SDK diagnostics are preserved. Open writers cause deletion to fail.

Unreadable records appear in JSON warnings; deletion failures are reported per run. Invalid arguments, unreadable records or deletion failures return exit code 1. Filesystem deletion is not transactional: permission changes or concurrent external modifications can cause partial deletion. See the log management guide (Chinese) for details and qre logs --help for all options.

QRE builds upon Microsoft.Extensions.AI and official CodexFlow.QueryRuntime.Models package, providing first-party adapters for:

• OpenAI-compatible APIs (OpenAI, Azure OpenAI, DeepSeek, Moonshot, Zhipu, etc.)
• vLLM inference clusters
• Anthropic Messages endpoints

Modern models with Chain-of-Thought (Reasoning) can fail or corrupt schemas when tools or JSON formats are activated. QRE manages this automatically:

• auto (Recommended): Automatically turns thinking off when tools or --json-output are active to prevent protocol conflicts; preserves thinking for pure text prompts.
• off: Forcibly disables reasoning parameters.
• on: Forcibly enables reasoning (only when the provider supports concurrent tools and CoT).
• preserve: Retains whatever defaults the model client options specify.

For production tasks requiring deterministic output shapes (such as architectural reports, security vulnerability manifests, or work item breakdowns), QRE natively supports structured outputs via strict JSON Schema.

• ChatResponseFormat.Json (json_object): The model is prompted to emit valid JSON, but without schema enforcement; missing fields or mismatched data types can occur.
• ChatResponseFormat.ForJsonSchema(...) (json_schema): Requests schema-constrained output. Backend support varies; clients must validate responses. HTTP 200 does not prove schema enforcement. See the live validation results.

Alibaba Cloud Model Studio configuration and live validation

Use a model explicitly listed as supporting JSON Schema, rather than only JSON Object. As checked on 2026-09-27, the official support list includes Qwen3.7-Plus, Qwen3.8-Flash, Qwen3.7-Flash, Qwen3.7-Max, and Qwen3.8-Max. qwen3.8-27b is not listed for JSON Schema; disabling thinking alone does not add schema support.

The verified combination is endpoint https://dashscope.aliyuncs.com/compatible-mode/v1, model ID qwen3.8-flash, and ThinkingEnabled = false (serialized as top-level enable_thinking: false). On 2026-09-27, 5 consecutive real API calls passed: HTTP 200, complete schema with strict=true in the outbound body, valid response fields/types/enums, and successful POCO deserialization. Raw SSE text matched the final QRE output without repair or mock fallback. This validates these five calls, not every possible input.

$env:QRE_API_URL = 'https://dashscope.aliyuncs.com/compatible-mode/v1'
$env:QRE_MODEL = 'qwen3.8-flash'
$env:QRE_API_KEY = $env:VLLM_ALIYUN_API_KEY # Or use your own Model Studio API key.
dotnet run --project examples/StructuredOutputsJsonSchema -- --live --evidence-dir artifacts/live-examples/schema

Running without --live or --endpoint performs an offline self-test only. See the validation record for request/response evidence and earlier unsupported-model results.

using System.Text.Json;
using CodexFlow.QueryRuntime.Models;
using Microsoft.Extensions.AI;

// 1. Define Strict JSON Schema
var schemaJson = """
{
  "type": "object",
  "properties": {
    "summary": { "type": "string" },
    "severity": { "type": "string", "enum": ["Low", "Medium", "High", "Critical"] },
    "approved": { "type": "boolean" },
    "violations": { "type": "array", "items": { "type": "string" } }
  },
  "required": ["summary", "severity", "approved", "violations"],
  "additionalProperties": false
}
""";

using var doc = JsonDocument.Parse(schemaJson);
var jsonSchemaFormat = ChatResponseFormat.ForJsonSchema(
    doc.RootElement,
    schemaName: "code_review_report",
    schemaDescription: "Enforces structural compliance for automated code review results.");

// 2. Configure Model Options
var options = new VllmChatOptions
{
    ResponseFormat = jsonSchemaFormat,
    Temperature = 0.1f,
    ThinkingEnabled = false // Verified Model Studio configuration: enable_thinking=false.
};

Model Studio recommends omitting max_tokens for structured output to avoid truncating JSON. The live comparison above retained the example's 1024-token limit; all five responses finished with stop.

• Thinking Policy Coordination (QreThinkingPolicy): Intelligently balances Reasoning (CoT) and schema constraints, preventing premature syntax failures during internal reasoning.
• Full-Link Outbound Diagnostics (qre diagnose): Three-tier probes track response_format from C# intent through to the HTTP Request Body, catching silent response_format_dropped degradations by intermediate proxies.

For a complete runnable example with strong-typed C# POCO deserialization, see examples/StructuredOutputsJsonSchema.

Embed the QRE V2 engine and model providers directly into any C# / .NET 10 host application:

Add the official NuGet packages (0.24.0):

<ItemGroup>
  <PackageReference Include="CodexFlow.QueryRuntime.Engine" Version="0.24.0" />
  <PackageReference Include="CodexFlow.QueryRuntime.Models" Version="0.24.0" />
</ItemGroup>

(Note: CodexFlow.QueryRuntime.Protocol is packaged internally as a dependency of the Engine package).

using CodexFlow.QueryRuntime.Engine.V2;
using CodexFlow.QueryRuntime.Models;
using CodexFlow.QueryRuntime.Protocol;

// 1. Configure model client (offline static or online MEAI client)
var modelClient = new StaticRuntimeModelClient("Hello! I am an embedded QRE agent.");

// 2. Initialize V2 Agent Runtime
IAgentRuntime runtime = new AgentRuntime(modelClient);

// 3. Assemble loop request
var sessionId = new RuntimeSessionId(Guid.NewGuid().ToString("N"));
var turnId = new RuntimeTurnId(Guid.NewGuid().ToString("N"));
string objective = "Analyze repository structure";

var request = new RuntimeAgentLoopRequest(
    sessionId,
    turnId,
    objective,
    [new RuntimeMessage(RuntimeMessageRole.User, [new RuntimeTextItem(objective)])],
    [],
    ModelParameters: new RuntimeModelParameters(),
    Policy: new RuntimePolicySnapshot("prod-policy", "readonly"),
    Environment: new RuntimeEnvironmentSnapshot("local", Path.GetFullPath("."), "my-host-app"),
    Budget: new RuntimeBudgetSnapshot(maxSteps: 5, maxToolCalls: 10)
);

// 4. Implement presentation event listener for streaming UI updates
var eventSink = new DelegateEventSink(runtimeEvent =>
{
    if (runtimeEvent.Type == RuntimePresentationEventType.TextDelta)
    {
        Console.Write(runtimeEvent.Text);
    }
    else if (runtimeEvent.Type == RuntimePresentationEventType.ToolCallRequested)
    {
        Console.WriteLine($"\n[Tool]: {runtimeEvent.ToolName}");
    }
    return ValueTask.CompletedTask;
});

// 5. Execute turn
using var cts = new CancellationTokenSource(TimeSpan.FromMinutes(2));
var result = await runtime.RunAsync(new RuntimeRunRequest(request), eventSink, cts.Token);

Console.WriteLine($"\nStatus: {result.Status}, Steps: {result.Turn.Steps.Count}");

See examples/EmbeddedV2 for a complete working host.

(Available from 0.24.0; see CHANGELOG.)

For "read-only tools + one structured answer" conversations (for example, extracting and scoring one review rule), the Runtime provides opt-in building blocks; leaving them unset keeps the default behavior unchanged:

using CodexFlow.QueryRuntime.Models.Tools;

// Host AIFunctions become V2 tools (read-only, idempotent, parallel-safe by default).
var pipeline = new RuntimeToolExecutionPipeline(
    new RuntimeToolRegistry(RuntimeAIFunctionTool.FromFunctions(hostFunctions)),
    new RuntimeAllowToolPolicy());

var request = new RuntimeAgentLoopRequest(/* ... */ pipeline.Descriptors,
    new RuntimeModelParameters(Model: model)
    {
        // JSON Schema output, applied only to Steps that expose no tools.
        ResponseFormat = RuntimeResponseFormat.ForJsonSchema(
            schema, "rule_result", scope: RuntimeResponseFormatScope.ToolFreeStepsOnly)
    }, /* policy, environment, budget */)
{
    ToolPipeline = pipeline,
    // After 12 tool calls or 85% of the deadline, run one tool-free final-answer Step.
    ToolFinalization = new RuntimeToolFinalizationPolicy
    {
        AfterToolCalls = 12,
        Deadline = TimeSpan.FromMinutes(3),
        Instruction = "Stop calling tools and return the final JSON now."
    },
    // A termination policy can return RuntimeTerminationDecision.ContinueWithoutTools(feedback)
    // to ask for a tool-free, format-constrained repair of invalid JSON.
    TerminationPolicy = jsonRepairPolicy,
    ModelRetryPolicy = new RuntimeRetryPolicy(), // exponential backoff with jitter
    ContextManager = new RuntimeContextManager(RuntimeContextOptions.ForModelWindow(128_000))
};

var modelClient = new MeaiRuntimeModelClient(chatClient, optionsFactory, new MeaiRuntimeModelClientOptions
{
    ClassifyProviderErrors = true, // 429/5xx/timeouts retryable, 401/403 terminal
    StreamingMode = MeaiStreamingMode.StreamingWithNonStreamingFallbackOnEmpty
});
// Add QreModelHttpErrorCaptureHandler to the provider HttpClient so SDKs that drop
// HTTP status codes (VllmChatClient) are still classified precisely.

Every decision (effective response format, finalization trigger, continue_without_tools, retries) is recorded in the audit and validated by data-only replay. See examples/EmbeddedStructuredExtraction for the complete, offline-runnable host.

The examples/ directory contains 11 fully working integration examples:

python scripts/test-examples.py

dotnet build CodexFlow.QueryRuntime.slnx
dotnet test CodexFlow.QueryRuntime.UnitTests/CodexFlow.QueryRuntime.UnitTests.csproj
dotnet test CodexFlow.QueryRuntime.IntegrationTests/CodexFlow.QueryRuntime.IntegrationTests.csproj

# Windows (x64)
dotnet publish CodexFlow.QueryRuntime.Cli/CodexFlow.QueryRuntime.Cli.csproj \
  -c Release -r win-x64 -p:PublishAot=true -p:SelfContained=true

# Linux (x64)
dotnet publish CodexFlow.QueryRuntime.Cli/CodexFlow.QueryRuntime.Cli.csproj \
  -c Release -r linux-x64 -p:PublishAot=true -p:SelfContained=true

# macOS Apple Silicon (ARM64)
dotnet publish CodexFlow.QueryRuntime.Cli/CodexFlow.QueryRuntime.Cli.csproj \
  -c Release -r osx-arm64 -p:PublishAot=true -p:SelfContained=true

• Production Log Management (Chinese)
• 📘 Technical Guide (中文)
• 🧭 0.2 Preview Migration Guide (中文)
• 🛡️ Security Policy (SECURITY.md)
• 🔒 Threat Model
• 🧰 Tool Capabilities
• 🔍 Tool Search Architecture & Partition Matrix
• 🔄 H1 Crash-Resume Implementation Report & Threat Model
• 🩺 SDK Outbound Diagnostics Guide (中文) & Acceptance Report
• 📦 Package Source & Provenance
• 🏛️ Architectural Decision Records (ADR):
  • ADR-001: Local Single-Process Runtime
  • ADR-002: Session-Turn-Step Lifecycle
  • ADR-003: Runtime IR and Model Adapters
  • ADR-004: State Events and Data Layers
  • ADR-005: Tool Execution Pipeline
  • ADR-007: V2-Only Cutover
  • ADR-008: Local Crash Resume
  • ADR-009: SDK Outbound Diagnostics

This project is licensed under the MIT License.