vaerion 0.1.15__py3-none-any.whl

vaerion/__init__.py

@@ -0,0 +1,8 @@
+"""Vaerion — the AI-native development engine (PyPI delivery channel).
+
+Python is the delivery channel, not the substrate: the engine is
+TypeScript executed by the Bun runtime (ADR-0018). This package installs
+the `vae` console launcher and the packaged engine source.
+"""
+
+__version__ = "0.1.15"

vaerion/cli.py

@@ -0,0 +1,50 @@
+"""`vae` console launcher — resolves Bun, then hands argv to the engine.
+
+Design laws:
+  - One entrypoint: the packaged engine's own main() (same exit codes as
+    every other distribution channel).
+  - Educated errors: a missing Bun runtime is a taught error (exit 2),
+    never a traceback.
+  - exec, not wrap: os.exec* replaces this process, so streaming, signals,
+    and exit codes pass through unchanged.
+"""
+
+import os
+import shutil
+import sys
+from pathlib import Path
+
+_BUN_INSTALL = {
+    "darwin": "brew install oven-sh/bun/bun   (or: curl -fsSL https://bun.sh/install | sh)",
+    "linux": "curl -fsSL https://bun.sh/install | sh",
+    "default": "see https://bun.sh  (docs/INSTALL.md lists every method)",
+}
+
+
+def _bun_hint() -> str:
+    if sys.platform == "darwin":
+        return _BUN_INSTALL["darwin"]
+    if sys.platform.startswith("linux"):
+        return _BUN_INSTALL["linux"]
+    return _BUN_INSTALL["default"]
+
+
+def main() -> int:
+    bun = shutil.which("bun")
+    if bun is None:
+        print("E1600 vae requires the Bun runtime (>= 1.2) to execute the engine.", file=sys.stderr)
+        print(f"Fix: install Bun -> {_bun_hint()}", file=sys.stderr)
+        print("Docs: docs/INSTALL.md (all installation methods)", file=sys.stderr)
+        return 2
+
+    cli = Path(__file__).resolve().parent / "engine" / "cli" / "vae.ts"
+    if not cli.exists():
+        print("E1900 packaged engine source is missing — the vaerion install is incomplete.", file=sys.stderr)
+        print("Fix: reinstall -> pip install --force-reinstall vaerion", file=sys.stderr)
+        return 1
+
+    os.execvp(bun, [bun, "run", str(cli), *sys.argv[1:]])
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

vaerion/engine/agents/executor.ts

@@ -0,0 +1,227 @@
+/**
+ * Vaerion — the agent step executor (MS-4).
+ *
+ * One responsibility: run a single PlanStep through its constitutional path
+ * and return an honest outcome.
+ *
+ *   model step   → GatewayService (the single gate: decide → journal → act →
+ *                  meter); citation enforcement applies when the step asks
+ *                  for it and the run has prepared research context.
+ *   tool step    → ToolInvocationService (broker → journal → execute →
+ *                  receipts → replay).
+ *   note step    → ReasoningSession (persistent scratchpad, journaled).
+ *   context step → the ResearchPort (One Context Path: declared capability →
+ *                  deterministic retrieval → evidence → citations → pack).
+ *
+ * The executor is stateless with respect to authority: gate prompts
+ * (GatewayGatePrompt / ToolGatePrompt) propagate — the supervisor owns the
+ * pause-and-resume law. Failures are RETURNED as outcomes (never swallowed),
+ * so the supervisor can retry or replan with the failure in the history.
+ */
+
+import { VaerionError } from "../kernel/errors.ts";
+import type { Clock } from "../kernel/clock.ts";
+import type { Actor } from "../spine/envelope.ts";
+import type { Principal } from "../broker/contracts/principal.ts";
+import type { PolicyContract } from "../broker/contracts/decision.ts";
+import type { InvocationResult } from "../gateway/types.ts";
+import { GatewayGatePrompt } from "../gateway/service.ts";
+import type { GatewayService, BudgetGuard, GatewayHost } from "../gateway/service.ts";
+import { ToolGatePrompt } from "./tools.ts";
+import type { ToolInvocationService, ToolHost } from "./tools.ts";
+import type { ReasoningSession } from "./reasoning.ts";
+import type { PlanStep, PlannerHistoryItem } from "./planner.ts";
+import type { Citation } from "../research/citation.ts";
+
+/** The research port: the One Context Path behind `context` steps. */
+export interface ResearchPort {
+  prepare(query: string, capability: string): Promise<{ pack_fingerprint: string; citation_ids: string[]; evidence_count: number; blocks: number; dropped: number; tokens_estimated: number }>;
+}
+
+export type StepOutcome =
+  | {
+      ok: true;
+      kind: PlanStep["kind"];
+      summary: string;
+      /** Model-backed step accounting (present for kind === "model"). */
+      model?: { model: string; inputTokens: number; outputTokens: number; costMicroUsd: number; latencyMs: number; attempts: number; textHash: string | null; text: string };
+      /** Tool-backed step accounting (present for kind === "tool"). */
+      tool?: { tool: string; resultHash: string; blobRef: string | null };
+      /** Citations referenced by the step's output when citation-checked. */
+      citations?: string[];
+    }
+  | { ok: false; kind: PlanStep["kind"]; error_code: string; message: string };
+
+export interface StepExecutorOptions {
+  clock: Clock;
+  actor: Actor;
+  gateway: GatewayService | null;
+  /** The run host for gateway invocations (RunHarness satisfies it). */
+  gatewayHost: GatewayHost | null;
+  tools: ToolInvocationService | null;
+  /** The run host for tool pipelines (RunHarness satisfies it). */
+  toolHost: ToolHost | null;
+  reasoning: ReasoningSession;
+  research: ResearchPort | null;
+}
+
+const CITATION_RE = /cit_\d{4}/g;
+
+/** Gate prompts are NOT failures: they propagate for the supervisor's pause law. */
+function isGatePrompt(err: unknown): err is GatewayGatePrompt | ToolGatePrompt {
+  return err instanceof GatewayGatePrompt || err instanceof ToolGatePrompt;
+}
+
+export class StepExecutor {
+  private readonly opts: StepExecutorOptions;
+  private readonly gatewayHostField: GatewayHost | null;
+  private readonly toolHostField: ToolHost | null;
+  /** Citation ids minted by context steps in THIS run (citation enforcement). */
+  private readonly availableCitations: string[] = [];
+
+  constructor(opts: StepExecutorOptions) {
+    this.opts = opts;
+    this.gatewayHostField = opts.gatewayHost;
+    this.toolHostField = opts.toolHost;
+  }
+
+  /** Citation enforcement input: the run's prepared citation ids. */
+  availableCitationIds(): readonly string[] {
+    return this.availableCitations;
+  }
+
+  async execute(
+    step: PlanStep,
+    ctx: { principal: Principal; policy: PolicyContract; goal: string; requestId: () => string; budget: () => BudgetGuard },
+  ): Promise<StepOutcome> {
+    switch (step.kind) {
+      case "model":
+        return this.executeModel(step, ctx);
+      case "tool":
+        return this.executeTool(step, ctx);
+      case "note":
+        return this.executeNote(step);
+      case "context":
+        return this.executeContext(step, ctx);
+    }
+  }
+
+  private async executeModel(
+    step: Extract<PlanStep, { kind: "model" }>,
+    ctx: { principal: Principal; policy: PolicyContract; goal: string; requestId: () => string; budget: () => BudgetGuard },
+  ): Promise<StepOutcome> {
+    if (this.opts.gateway === null) {
+      return { ok: false, kind: "model", error_code: "E1600", message: "no gateway bound in this process — model steps are unavailable" };
+    }
+    let result: InvocationResult;
+    try {
+      result = await this.opts.gateway.invoke(this.gatewayHostField as GatewayHost, {
+        request: { op: "chat", model: step.model, messages: step.messages, seed: step.seed, maxOutputTokens: step.maxOutputTokens },
+        principal: ctx.principal,
+        policy: ctx.policy,
+        requestId: ctx.requestId(),
+        intent: `agent model step for goal: ${ctx.goal}`,
+        budget: ctx.budget(),
+      });
+    } catch (err) {
+      if (isGatePrompt(err)) throw err; // human authority is not a failure
+      return { ok: false, kind: "model", error_code: err instanceof VaerionError ? err.code : "E1900", message: (err as Error).message };
+    }
+    // Citation enforcement (E1806): an answer step over prepared research
+    // content must reference at least one prepared citation id.
+    let citations: string[] | undefined;
+    if (step.requiresCitations === true) {
+      if (this.availableCitations.length === 0) {
+        return { ok: false, kind: "model", error_code: "E1806", message: "answer step requires citations but the run prepared no research context" };
+      }
+      const cited = new Set(result.text.match(CITATION_RE) ?? []);
+      const used = this.availableCitations.filter((c) => cited.has(c));
+      if (used.length === 0) {
+        return {
+          ok: false,
+          kind: "model",
+          error_code: "E1806",
+          message: `answer does not reference any prepared citation (${this.availableCitations.slice(0, 4).join(", ")}${this.availableCitations.length > 4 ? "…" : ""})`,
+        };
+      }
+      citations = used;
+    }
+    return {
+      ok: true,
+      kind: "model",
+      summary: result.text.slice(0, 120),
+      model: {
+        model: result.model,
+        inputTokens: result.usage?.inputTokens ?? 0,
+        outputTokens: result.usage?.outputTokens ?? 0,
+        costMicroUsd: result.cost?.totalMicroUsd ?? 0,
+        latencyMs: result.latencyMs,
+        attempts: result.attempts,
+        textHash: result.textHash,
+        text: result.text,
+      },
+      ...(citations !== undefined ? { citations } : {}),
+    };
+  }
+
+  private async executeTool(
+    step: Extract<PlanStep, { kind: "tool" }>,
+    ctx: { principal: Principal; policy: PolicyContract; goal: string; requestId: () => string; budget: () => BudgetGuard },
+  ): Promise<StepOutcome> {
+    if (this.opts.tools === null) {
+      return { ok: false, kind: "tool", error_code: "E1600", message: "no tool pipeline bound in this process — tool steps are unavailable" };
+    }
+    try {
+      const result = await this.opts.tools.invoke(this.toolHostField as ToolHost, {
+        tool: step.tool,
+        args: step.args,
+        principal: ctx.principal,
+        policy: ctx.policy,
+        requestId: ctx.requestId(),
+        intent: `agent tool step for goal: ${ctx.goal}`,
+      });
+      return {
+        ok: true,
+        kind: "tool",
+        summary: `tool ${result.tool} completed (${result.resultHash.slice(0, 12)}…)`,
+        tool: { tool: result.tool, resultHash: result.resultHash, blobRef: result.blobRef?.hash ?? null },
+      };
+    } catch (err) {
+      if (isGatePrompt(err)) throw err; // human authority is not a failure
+      return { ok: false, kind: "tool", error_code: err instanceof VaerionError ? err.code : "E1900", message: (err as Error).message };
+    }
+  }
+
+  private async executeNote(step: Extract<PlanStep, { kind: "note" }>): Promise<StepOutcome> {
+    const note = await this.opts.reasoning.note(step.text);
+    return { ok: true, kind: "note", summary: `note #${note.index}: ${note.text.slice(0, 80)}` };
+  }
+
+  private async executeContext(
+    step: Extract<PlanStep, { kind: "context" }>,
+    ctx: { principal: Principal; policy: PolicyContract; goal: string; requestId: () => string; budget: () => BudgetGuard },
+  ): Promise<StepOutcome> {
+    if (this.opts.research === null) {
+      return { ok: false, kind: "context", error_code: "E1600", message: "no research port bound in this process — context steps are unavailable" };
+    }
+    try {
+      const prepared = await this.opts.research.prepare(step.query, step.capability);
+      this.availableCitations.push(...prepared.citation_ids);
+      return {
+        ok: true,
+        kind: "context",
+        summary: `context ${prepared.pack_fingerprint.slice(0, 12)}… (${prepared.blocks} blocks, ${prepared.evidence_count} evidence, ${prepared.citation_ids.length} citations)`,
+      };
+    } catch (err) {
+      if (isGatePrompt(err)) throw err; // human authority is not a failure
+      return { ok: false, kind: "context", error_code: err instanceof VaerionError ? err.code : "E1900", message: (err as Error).message };
+    }
+  }
+}
+
+/** Convert an outcome into a planner history item (newest-last fold input). */
+export function historyItemOf(round: number, index: number, outcome: StepOutcome): PlannerHistoryItem {
+  return outcome.ok
+    ? { round, index, kind: outcome.kind, ok: true, summary: outcome.summary }
+    : { round, index, kind: outcome.kind, ok: false, summary: outcome.message.slice(0, 160), error_code: outcome.error_code };
+}

vaerion/engine/agents/grants.ts

@@ -0,0 +1,73 @@
+/**
+ * Vaerion — agent permission grants (MS-4 wiring).
+ *
+ * The agent principal acts inside the permission-graph ceiling like every
+ * other principal. Its grants are DERIVED from human declarations only:
+ *
+ *   - tool.call: one grant over every DECLARED tool scope (config.tools) —
+ *     declaring a tool in vaerion.yaml is the human's statement that this
+ *     tool exists; the broker policy still decides allow/deny/prompt.
+ *   - model.invoke: the DECLARED model scopes (enabled gateway providers'
+ *     concrete `provider/model` ceilings) that a declared policy rule admits
+ *     for agents — the human typed both the models and the rules; nothing
+ *     is invented here.
+ *
+ * Fail-closed: declare nothing, grant nothing. Derived grants are concrete
+ * scope strings that sit INSIDE the standing ceilings (graphFromConfig
+ * enforces coverage), so grants only ever narrow.
+ */
+
+import type { VaerionConfig } from "../config/config.ts";
+import type { PolicyContract } from "../broker/contracts/decision.ts";
+import type { ConfigGrantInput } from "../broker/engine.ts";
+import type { Principal } from "../broker/contracts/principal.ts";
+import { scopeMatches } from "../broker/contracts/capability.ts";
+
+/** Does any declared rule admit `agentKind` for `domain` over `scope`? */
+function policyAdmits(policy: PolicyContract, domain: string, scope: string, agentKind: Principal["kind"]): boolean {
+  return policy.rules.some((rule) => {
+    if (rule.domain !== domain && rule.domain !== "*") return false;
+    if (rule.effect === "deny") return false;
+    if (rule.principalKinds !== "all" && !rule.principalKinds.some((k) => k === agentKind)) return false;
+    return scopeMatches(rule.scope, scope);
+  });
+}
+
+/** Derive the agent's ceiling-internal grants from config + policy. */
+export function agentGrants(config: VaerionConfig, policy: PolicyContract, agent: Principal): ConfigGrantInput[] {
+  const grants: ConfigGrantInput[] = [];
+  // Tool ceilings: declared tools + declared extensions only (declared-before-used
+  // law; an extension is reachable as a tool, so its name is its scope).
+  const toolScopes = [
+    ...(config.tools ?? []).map((t) => t.scope ?? t.name),
+    ...(config.extensions ?? []).map((e) => e.name),
+  ];
+  if (toolScopes.length > 0) grants.push({ principalId: agent.id, domain: "tool.call", scopes: toolScopes });
+  // Model ceilings: concrete declared models admitted by declared policy.
+  const modelScopes: string[] = [];
+  for (const [provider, p] of Object.entries(config.gateway?.providers ?? {})) {
+    if (!p.enabled) continue;
+    for (const model of p.models ?? []) {
+      const scope = `${provider}/${model}`;
+      if (policyAdmits(policy, "model.invoke", scope, agent.kind)) modelScopes.push(scope);
+    }
+  }
+  if (modelScopes.length > 0) grants.push({ principalId: agent.id, domain: "model.invoke", scopes: modelScopes });
+  return grants;
+}
+
+/** The builtin scopes the R-2 host bridge exposes to extensions. */
+export const BRIDGEABLE_BUILTIN_SCOPES: ReadonlyArray<string> = ["echo", "clock.read"];
+
+/**
+ * Derive the EXTENSION principal's ceiling-internal grants (MS-5, ADR-0009):
+ * an extension may bridge only to the declared builtins, and only where a
+ * declared policy rule admits `extension` for that scope. Declaring an
+ * extension grants nothing by itself — this mirrors agentGrants.
+ */
+export function extensionGrants(config: VaerionConfig, policy: PolicyContract): ConfigGrantInput[] {
+  if ((config.extensions ?? []).length === 0) return [];
+  const scopes = BRIDGEABLE_BUILTIN_SCOPES.filter((scope) => policyAdmits(policy, "tool.call", scope, "extension"));
+  if (scopes.length === 0) return [];
+  return (config.extensions ?? []).map((ext) => ({ principalId: `extension:${ext.name}`, domain: "tool.call", scopes: [...scopes] }));
+}

vaerion/engine/agents/index.ts

@@ -0,0 +1,61 @@
+/**
+ * Vaerion — agents subsystem barrel (MS-4).
+ *
+ * Agent runtime (supervisor over journaled decisions), tool invocation
+ * pipeline, planners, reasoning sessions, metrics, and the local research
+ * port. Everything here is L2: it may import L0/L1/L2, never L4.
+ */
+
+export type {
+  ToolHost,
+  ToolDeclaration,
+  ToolArgsSchema,
+  ToolExecutor,
+  ToolContext,
+  ToolInvokeInput,
+  ToolInvokeResult,
+  SearchHit,
+  SearchableIndex,
+} from "./tools.ts";
+export {
+  ToolRegistry,
+  ToolInvocationService,
+  ToolGatePrompt,
+  echoTool,
+  clockReadTool,
+  researchSearchTool,
+} from "./tools.ts";
+
+export type { PlanStep, Plan, Planner, PlannerInput, PlannerHistoryItem } from "./planner.ts";
+export {
+  InlinePlanner,
+  ModelPlanner,
+  parsePlanText,
+  assertPlan,
+  type GatewayHostLike,
+  type ModelPlannerOptions,
+  type InlinePlannerOptions,
+} from "./planner.ts";
+
+export type { ReasoningNote, ReasoningFold, ReasoningState, ReasoningHost } from "./reasoning.ts";
+export {
+  ReasoningSession,
+  initialReasoningState,
+  reasoningStateReducer,
+  unfoldedNotes,
+  foldSummary,
+} from "./reasoning.ts";
+
+export type { StepOutcome, ResearchPort } from "./executor.ts";
+export { StepExecutor, historyItemOf } from "./executor.ts";
+
+export type { AgentOutcome, AgentRunState, AgentRuntimeOptions, AgentRunInput, AgentRunResult } from "./runtime.ts";
+export { AgentRuntime, initialAgentRunState, agentRunStateReducer, agentStateFromRecords } from "./runtime.ts";
+
+export type { AgentMetrics } from "./metrics.ts";
+export { agentMetricsFromRecords } from "./metrics.ts";
+
+export type { LocalResearchPortOptions } from "./research-port.ts";
+export { LocalResearchPort } from "./research-port.ts";
+
+export { agentGrants } from "./grants.ts";

vaerion/engine/agents/metrics.ts

@@ -0,0 +1,125 @@
+/**
+ * Vaerion — agent metrics (MS-4).
+ *
+ * A pure fold over journal records — the ONLY accounting there is. Latency,
+ * cost, tokens, success, failures, retries, and tool activity all come from
+ * the spine events the runtime already journaled (R-RT2: state is a fold of
+ * the journal; no counters live anywhere else). Integer micro-USD throughout.
+ */
+
+import type { JournalRecord } from "../journal/records.ts";
+
+export interface AgentMetrics {
+  run: {
+    started: boolean;
+    outcome: "goal" | "step_limit" | "failed" | "awaiting_gate" | null;
+    steps: number;
+    failures: number;
+    retries: number;
+  };
+  model: {
+    invocations: number;
+    inputTokens: number;
+    outputTokens: number;
+    costMicroUsd: number;
+    latencyMs: number;
+    attempts: number;
+  };
+  tools: {
+    requested: number;
+    completed: number;
+    denied: number;
+    failed: number;
+  };
+  context: {
+    packs: number;
+    notes: number;
+    folds: number;
+  };
+  gates: {
+    opened: number;
+    resolved: number;
+  };
+}
+
+/** Fold agent metrics from journal records (order-free, deterministic). */
+export function agentMetricsFromRecords(records: ReadonlyArray<JournalRecord>): AgentMetrics {
+  const m: AgentMetrics = {
+    run: { started: false, outcome: null, steps: 0, failures: 0, retries: 0 },
+    model: { invocations: 0, inputTokens: 0, outputTokens: 0, costMicroUsd: 0, latencyMs: 0, attempts: 0 },
+    tools: { requested: 0, completed: 0, denied: 0, failed: 0 },
+    context: { packs: 0, notes: 0, folds: 0 },
+    gates: { opened: 0, resolved: 0 },
+  };
+  for (const rec of records) {
+    if (rec.k !== "evt") {
+      if (rec.k === "gate") {
+        if (rec.gate.state === "open") m.gates.opened++;
+        else if (rec.gate.state === "resolved") m.gates.resolved++;
+      }
+      continue;
+    }
+    const p = rec.env.payload as Record<string, unknown>;
+    const int = (v: unknown): number => (typeof v === "number" && Number.isFinite(v) ? Math.max(0, Math.round(v)) : 0);
+    switch (rec.env.type) {
+      case "agent.run.started":
+        m.run.started = true;
+        break;
+      case "agent.run.completed":
+        m.run.outcome = (typeof p.outcome === "string" ? p.outcome : null) as AgentMetrics["run"]["outcome"];
+        break;
+      case "agent.step.recorded": {
+        m.run.steps++;
+        if (typeof p.attempt === "number" && p.attempt > 1) m.run.retries += p.attempt - 1;
+        break;
+      }
+      case "agent.step.failed": {
+        m.run.failures++;
+        const attempts = int(p.attempts);
+        if (attempts > 1) m.run.retries += attempts - 1;
+        break;
+      }
+      case "gateway.invoke.recorded": {
+        // THE metering truth: every model invocation crosses the single gate,
+        // so tokens/cost/latency fold from ITS records only (never from step
+        // events — that would double-count planner + step spend).
+        const usage = p.usage as { inputTokens?: unknown; outputTokens?: unknown } | null | undefined;
+        const cost = p.cost as { totalMicroUsd?: unknown } | null | undefined;
+        m.model.invocations++;
+        m.model.inputTokens += int(usage?.inputTokens);
+        m.model.outputTokens += int(usage?.outputTokens);
+        m.model.costMicroUsd += int(cost?.totalMicroUsd);
+        m.model.latencyMs += int(p.latency_ms);
+        m.model.attempts += int(p.attempts);
+        break;
+      }
+      case "gateway.invoke.failed":
+        m.model.invocations++;
+        m.model.attempts += int(p.attempts);
+        break;
+      case "tool.call.requested":
+        m.tools.requested++;
+        break;
+      case "tool.call.completed": {
+        m.tools.completed++;
+        if (p.ok === false) m.tools.failed++;
+        break;
+      }
+      case "tool.call.denied":
+        m.tools.denied++;
+        break;
+      case "research.context.prepared":
+        m.context.packs++;
+        break;
+      case "reasoning.note.recorded":
+        m.context.notes++;
+        break;
+      case "reasoning.folded":
+        m.context.folds++;
+        break;
+      default:
+        break;
+    }
+  }
+  return m;
+}