API Reference

API Reference

This page documents the primary TypeScript APIs available in @agentctx/core.

CTXParser

The core parser that converts CTX strings into typed ASTs.

Constructor

const parser = new CTXParser();

parse()

Parse a single CTX statement:

// Strict mode (default)
const stmt: CTXStatement = parser.parse('?k "auth" #code ^3');

// Hybrid mode
const result: CTXHybridResult = parser.parse(
  'Search for ?k "auth" #code ^3',
  { mode: 'hybrid' }
);

Parameters:

Name	Type	Description
input	string	Raw CTX string
options	CTXParseOptions	Optional: { mode, depth }

Returns: CTXStatement (strict) or CTXHybridResult (hybrid)

Throws: CTXParseError with typed data.code

parseMulti()

Parse multiple newline-separated statements:

const stmts: CTXStatement[] = parser.parseMulti(`
  ?t github
  >t github.issues.list state="open"
`);

Gateway

The central request router and middleware pipeline.

Constructor

const gateway = new Gateway(config, knowledge, memory);

process()

Process a raw CTX string through the full middleware pipeline:

const result: GatewayResult = await gateway.process('?k "auth" ^3');
// { ok: true, op: "?k", ms: 4, data: { results: [...] } }

close()

Shutdown the gateway and all backend connections:

await gateway.close();

Sidecar

Deterministic translation engine with Ed25519 signing.

Constructor

const sidecar = new Sidecar();          // Default emitters
const sidecar = new Sidecar(registry);  // Custom emitter registry

translate()

Translate a CTX AST to a target language:

const translation: Translation = sidecar.translate(ast, 'human');
// { source: "?k ...", target: "human", output: "Searched for...", timestamp: "..." }

translateBatch()

Translate multiple statements:

const translation: Translation = sidecar.translateBatch(asts, 'surrealql');

signAndWrite()

Translate, sign with Ed25519, and write to .context/translations/:

const signed: SignedTranslation = await sidecar.signAndWrite(ast, crypto, contextDir);
// { ctx, human, signature, digest, timestamp }

CryptoManager

Ed25519 keypair management and signing.

init()

Initialize or load existing keypair:

const crypto = new CryptoManager(contextDir);
await crypto.init();

signTranslation()

Sign a CTX↔human translation pair:

const signed = await crypto.signTranslation(ctxRaw, humanOutput);

Types

CTXStatement

interface CTXStatement {
  operator: CTXOperator;      // "?" | "!" | ">" | "+" | "~" | "-" | "^"
  plane: CTXPlane;            // "k" | "t" | "s" | "m" | "a" | "i" | "l"
  verb?: CTXVerb;             // Pipeline verb
  decorator?: CTXDecorator;   // @similar, @traverse, etc.
  target: string;             // Target identifier or query
  filters: CTXFilter[];       // Tag, time, limit, etc.
  payload?: CTXPayload;       // Key-value pairs or quoted string
  raw: string;                // Original normalized input
}

GatewayResult

interface GatewayResult {
  ok: boolean;
  op: string;
  ms: number;
  data: unknown;
  error?: string;
  code?: string;
}

Translation

interface Translation {
  source: string;
  target: TranslationTarget;
  output: string;
  timestamp: string;
}

See Also

• Formal Specification — full type definitions
• Architecture Guide — module structure