Hybrid Mode

Hybrid Mode

Hybrid mode allows agents to mix natural language prose with CTX statements in a single input. The parser separates them automatically — CTX statements become typed AST nodes, everything else becomes prose.

Why Hybrid Mode?

Agents don’t always think in pure CTX. Sometimes they need to reason in natural language while interspersing structured operations:

I need to check if the auth module exists in the codebase.
?k "auth" #code ^3
If it doesn't exist, I'll create a new one based on the JWT pattern.
+m:task "create auth module" #todo #architecture

Hybrid mode parses this into:

• 2 CTX statements — the ?k search and the +m:task store
• 2 prose segments — the surrounding English text

Usage

Pass mode: "hybrid" to the parser:

import { CTXParser } from '@agentctx/core';

const parser = new CTXParser();
const result = parser.parse(
  `I think we should check the auth module first.
   ?k "auth" #code ^3
   Then store a note about what we find.
   +m auth-review #task "review auth patterns"`,
  { mode: "hybrid" }
);

// Result: CTXHybridResult
// {
//   statements: [
//     { operator: "?", plane: "k", target: "auth", filters: [...] },
//     { operator: "+", plane: "m", target: "auth-review", ... }
//   ],
//   prose: [
//     "I think we should check the auth module first.",
//     "Then store a note about what we find."
//   ],
//   raw: "..."
// }

How Detection Works

The parser scans each line for CTX patterns — an operator-plane pair (?k, +m, >t, etc.) at a word boundary. When found:

1. The text before the pattern becomes prose
2. The CTX-like segment is strict-parsed
3. If parsing succeeds → it’s a statement
4. If parsing fails → it’s treated as prose (R2: errors are data, not exceptions)

This means invalid CTX never crashes hybrid parsing. It gracefully degrades to prose.

Return Type

interface CTXHybridResult {
  statements: CTXStatement[];  // Successfully parsed CTX
  prose: string[];             // Natural language segments
  raw: string;                 // Original input
}

When to Use Each Mode

Mode	Use Case
strict (default)	Clean CTX input from agents, CLI, or programmatic use
hybrid	Agent reasoning traces, mixed-format tool output, human-agent chat

Strict vs Hybrid Behavior

Input	Strict Mode	Hybrid Mode
?k "auth" ^3	✅ Returns CTXStatement	✅ Returns { statements: [stmt], prose: [] }
Check the auth module	❌ Throws INVALID_OPERATOR	✅ Returns { statements: [], prose: ["Check..."] }
Mixed input	❌ Throws on first non-CTX line	✅ Separates into statements + prose

Next

• Examples → — real-world CTX workflows
• Formal Specification → — EBNF grammar and parsing rules