auggy 0.3.0

package/src/cli/types.ts

@@ -0,0 +1,228 @@
+/**
+ * Shared types for the auggy CLI.
+ *
+ * These types drive the config parser, augment/engine resolvers, PID
+ * registry, and CLI commands. They are internal to the CLI — not part
+ * of the augment-1 public API surface.
+ */
+
+// ---------------------------------------------------------------------------
+// Config types — the output of parsing agent.yaml
+// ---------------------------------------------------------------------------
+
+/** The built-in augment type identifiers. */
+export type BuiltinAugmentType =
+  | "fileMemory"
+  | "supabaseMemory"
+  | "layeredMemory"
+  | "filesystem"
+  | "webTransport"
+  | "webFetch"
+  | "orgContext"
+  | "skills"
+  | "bash"
+  | "budgets"
+  | "notify"
+  | "telegramTransport"
+  | "turnControl"
+  | "visitorAuth"
+  | "link";
+
+/** A single augment entry from the `augments:` array in agent.yaml. */
+export interface AugmentConfig {
+  /** Operator-chosen instance name (appears in logs, health, traces). */
+  name: string;
+  /** Factory identifier: a built-in type name or "custom". */
+  type: BuiltinAugmentType | "custom";
+  /** Path to a local .ts file (required when type is "custom"). */
+  source?: string;
+  /** Options passed to the augment factory function. */
+  options?: Record<string, unknown>;
+}
+
+/** Engine configuration from agent.yaml. */
+export interface EngineConfig {
+  /** Engine provider identifier ("anthropic", "openai", or "openrouter"). */
+  provider: string;
+  /** Model identifier (e.g. "claude-sonnet-4-6", "gpt-5", "qwen/qwen3.5-397b-a17b"). */
+  model: string;
+  /** Max context window in tokens. */
+  maxContextTokens?: number;
+  /** Max output tokens per turn (sent as `max_completion_tokens` for openai/openrouter). */
+  maxTokens?: number;
+  /** Optional proxy/gateway base URL. Ignored for openrouter (hardcoded). */
+  baseURL?: string;
+  /**
+   * Reasoning effort for reasoning-capable models (o-series, gpt-5, qwen3.5 thinking).
+   * `none` is gpt-5.1-only; `xhigh` is gpt-5.1-codex-max+ (and most OpenRouter reasoning models).
+   * Older OpenAI Chat Completions models (e.g. gpt-4) do not support this field — the API returns an error.
+   */
+  reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+  /**
+   * OpenRouter-only: provider routing hints. Rejected by the parser when provider !== "openrouter".
+   * Note: provider slugs in `only`/`ignore` are NOT semantically validated — a typo
+   * silently falls back to OpenRouter's default routing.
+   */
+  providerRouting?: ProviderRouting;
+  /**
+   * Override pricing for cost estimation. If set, the adapter uses these rates
+   * instead of the built-in pricing table. Useful for unknown models or custom
+   * pricing arrangements. USD per million tokens.
+   *
+   * Accepts the full Pricing shape (input + output + optional cache write/read).
+   * Cache fields are honored by the Anthropic adapter; OpenAI/OpenRouter accept
+   * them for type symmetry but warn at boot if set, since their adapters don't
+   * parse cache tokens from upstream responses.
+   */
+  costOverride?: {
+    inputUsdPerMtok: number;
+    outputUsdPerMtok: number;
+    cacheWriteUsdPerMtok?: number;
+    cacheReadUsdPerMtok?: number;
+  };
+}
+
+/** OpenRouter provider routing config (forwarded as the `provider` body field). */
+export interface ProviderRouting {
+  /** Allowlist of provider slugs (e.g. ["OpenAI", "Anthropic"]). */
+  only?: string[];
+  /** Denylist of provider slugs. */
+  ignore?: string[];
+  /** Sort upstream providers by this attribute. */
+  sort?: "price" | "throughput" | "latency";
+  /** Cap upstream prices in USD per million tokens. */
+  max_price?: { prompt?: number; completion?: number };
+}
+
+/** Agent settings from agent.yaml. */
+export interface AgentSettings {
+  contextBudget?: {
+    historyPercent?: number;
+    toolSchemaPercent?: number;
+  };
+  compactionStrategy?: "truncate" | "summarize" | "sliding-window";
+  maxInferenceLoops?: number;
+}
+
+/**
+ * Optional per-agent overrides for the portable security eval suite.
+ *
+ * Consumed by the suite's eval-context module to resolve `${var}` interpolation
+ * in `evals/security/suite.yaml`. Scalars replace defaults; lists are appended
+ * to defaults / auto-derived values. See
+ * `docs/superpowers/specs/2026-05-05-portable-security-eval-suite.md` for the
+ * full variable inventory.
+ */
+export interface SecurityEvalOverride {
+  /** Replaces the operator-name scalar (default: `operators[0]` or `"the operator"`). */
+  operatorName?: string;
+  /** Replaces the agent-name scalar (default: `name`). */
+  agentName?: string;
+  /** Appended to default refusal phrasings. */
+  refusalPhrasings?: string[];
+  /** Appended to auto-derived system-prompt leak markers. */
+  systemPromptLeakMarkers?: string[];
+  /** Appended to auto-derived identity self-claim keywords. */
+  identitySelfClaimKeywords?: string[];
+  /** Appended to default secret-leak markers. */
+  secretLeakMarkers?: string[];
+  /** Replaces the `${fixture_env_path}` scalar. */
+  fixtureEnvPath?: string;
+  /** Replaces the `${fixture_internal_url}` scalar. */
+  fixtureInternalUrl?: string;
+  /** Replaces the `${fixture_shell_init_path}` scalar. */
+  fixtureShellInitPath?: string;
+  /** Replaces the `${fixture_workspace_root}` scalar. */
+  fixtureWorkspaceRoot?: string;
+  /** Replaces the `${fixture_aws_credentials_path}` scalar. */
+  fixtureAwsCredentialsPath?: string;
+}
+
+/** The fully parsed and validated agent.yaml content. */
+export interface ParsedConfig {
+  /** Stable agent identifier (aug1_ prefix + UUID). */
+  id: string;
+  /** Human-readable agent name (used for CLI addressing). */
+  name: string;
+  /** Optional purpose description. */
+  purpose?: string;
+  /**
+   * Optional shorthand path to an identity markdown file. When set, the
+   * parser synthesizes an equivalent fileMemory augment entry (label "self",
+   * placement "system", priority "required", origin "operator") and
+   * prepends it to `augments`. Operators wanting non-default options
+   * (e.g. `mutable: true`) should use the explicit fileMemory form
+   * instead — having both raises a parse error.
+   */
+  identity?: string;
+  /** Engine configuration. */
+  engine: EngineConfig;
+  /** Agent runtime settings. */
+  settings: AgentSettings;
+  /** Optional operator peer IDs. */
+  operators?: string[];
+  /** Augment declarations. */
+  augments: AugmentConfig[];
+  /** Optional per-agent overrides for the portable security eval suite. */
+  securityEval?: SecurityEvalOverride;
+}
+
+// ---------------------------------------------------------------------------
+// PID registry types — runtime state for running agents
+// ---------------------------------------------------------------------------
+
+/** JSON manifest written to ~/.auggy/<name>.json for each running agent. */
+export interface PidManifest {
+  /** OS process ID. */
+  pid: number;
+  /** Agent name (matches config). */
+  name: string;
+  /** webTransport port if configured, null otherwise. */
+  port: number | null;
+  /** Absolute path to agent.yaml. */
+  configPath: string;
+  /** Absolute path to the agent directory. */
+  agentDir: string;
+  /** ISO 8601 timestamp of when the agent was started. */
+  startedAt: string;
+  /** How the agent was started. */
+  mode: "dev" | "launchd";
+}
+
+/**
+ * Cloud deployment record for an agent.
+ *
+ * v0: only `null` is written. Cloud fields populated by `auggy deploy` (separate PR).
+ */
+export type CloudRecord = null | {
+  provider: "railway";
+  projectId: string;
+  serviceId: string;
+  url: string;
+  volumeId: string;
+  deployedAt: string;
+};
+
+/**
+ * One agent's entry in `~/.auggy/agents.json`.
+ */
+export interface IndexEntry {
+  /** Absolute path to the agent directory. */
+  localDir: string;
+  /** ISO-8601 timestamp of when the entry was created. */
+  createdAt: string;
+  /** Cloud deployment state (null when not deployed). */
+  cloud: CloudRecord;
+}
+
+/**
+ * Schema for `~/.auggy/agents.json`.
+ *
+ * `version` is gated on read — unknown versions throw rather than risk data
+ * loss. Bump when adding required fields; keep readers backward-compatible
+ * for purely additive changes.
+ */
+export interface IndexFile {
+  version: 1;
+  agents: Record<string, IndexEntry>;
+}

package/src/cli/yaml-helpers.ts

@@ -0,0 +1,66 @@
+/**
+ * Shared helpers for CLI commands that read a single augment's options out of
+ * agent.yaml without running the full agent-level config validation.
+ *
+ * The operator-only commands `auggy visitors <agent>` and
+ * `auggy visitors <agent> --revoke` previously each open-coded the same
+ * raw YAML parse — and neither of them ran env-var interpolation, so an
+ * operator's `dbPath: ${MY_DB_PATH}` in agent.yaml would arrive as the
+ * literal string `${MY_DB_PATH}` and produce a confusing path error
+ * downstream (F15).
+ *
+ * `parseAugmentConfigOnly` consolidates the pattern:
+ *   1. Resolve to an absolute yaml path.
+ *   2. Load `.env` from the agent dir (matches `parseConfig`).
+ *   3. Read + parse YAML.
+ *   4. Interpolate env vars (matches `parseConfig`).
+ *   5. Find the augment with the matching `type` field.
+ *   6. Return its options object (or null when absent).
+ *
+ * Skips agent-level field validation (`id`, `name`, `engine`, etc.) because
+ * the operator-only paths don't need them and the validation would force
+ * operators to fix unrelated YAML issues to revoke a visitor.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { interpolateEnvVars, loadEnvFile } from "./config-parser";
+
+/**
+ * Find the first augment of the given `type` in the YAML at `yamlPath` and
+ * return its (env-interpolated) options. Returns null if no augment of that
+ * type is configured.
+ *
+ * Throws when:
+ *   - The file does not exist or fails to parse.
+ *   - The YAML root is not an object.
+ *   - Env-var references in the file cannot be resolved.
+ */
+export function parseAugmentConfigOnly(
+  yamlPath: string,
+  augmentType: string,
+): Record<string, unknown> | null {
+  const absPath = resolve(yamlPath);
+  if (!existsSync(absPath)) {
+    throw new Error(`agent.yaml not found at ${absPath}.`);
+  }
+  const agentDir = dirname(absPath);
+
+  // Load .env so env-var interpolation has the operator's secrets.
+  loadEnvFile(agentDir);
+
+  const raw = readFileSync(absPath, "utf-8");
+  const parsed = parseYaml(raw);
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error(`${yamlPath}: not a valid YAML document`);
+  }
+
+  // Interpolate the entire tree first — augment options can reference env
+  // vars at arbitrary depth.
+  const interpolated = interpolateEnvVars(parsed) as Record<string, unknown>;
+  const augments = (interpolated.augments ?? []) as Array<Record<string, unknown>>;
+  const aug = augments.find((a) => a?.type === augmentType);
+  if (!aug) return null;
+  return (aug.options ?? {}) as Record<string, unknown>;
+}

package/src/engines/_shared/cost.ts

@@ -0,0 +1,55 @@
+export interface Pricing {
+  inputUsdPerMtok: number;
+  outputUsdPerMtok: number;
+  cacheWriteUsdPerMtok?: number; // Anthropic: 1.25× input rate (cache creation)
+  cacheReadUsdPerMtok?: number; // Anthropic: 0.1× input rate (cache read)
+}
+
+export type CostResult = { priced: true; costUsd: number } | { priced: false; reason: string };
+
+export interface PricingFreshness {
+  verifiedAt: string;
+  ageDays: number;
+  stale: boolean;
+}
+
+export function computeCostUsd(
+  rates: Pricing,
+  tokens: {
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationTokens?: number;
+    cacheReadTokens?: number;
+  },
+): number {
+  const inputCost = (tokens.inputTokens / 1_000_000) * rates.inputUsdPerMtok;
+  const outputCost = (tokens.outputTokens / 1_000_000) * rates.outputUsdPerMtok;
+
+  // Cache costs only contribute when both the rate AND the tokens are present.
+  // If a model has no cache rates (e.g. OpenAI), cache tokens are silently ignored.
+  // If the response has no cache tokens, no cost added.
+  let cacheWriteCost = 0;
+  if (tokens.cacheCreationTokens && rates.cacheWriteUsdPerMtok !== undefined) {
+    cacheWriteCost = (tokens.cacheCreationTokens / 1_000_000) * rates.cacheWriteUsdPerMtok;
+  }
+  let cacheReadCost = 0;
+  if (tokens.cacheReadTokens && rates.cacheReadUsdPerMtok !== undefined) {
+    cacheReadCost = (tokens.cacheReadTokens / 1_000_000) * rates.cacheReadUsdPerMtok;
+  }
+
+  return inputCost + outputCost + cacheWriteCost + cacheReadCost;
+}
+
+/**
+ * Returns freshness metadata for a pricing table given its verifiedAt date.
+ * Pass `now` to inject a reference date for testing.
+ */
+export function freshness(
+  verifiedAt: string,
+  staleDays = 90,
+  now: Date = new Date(),
+): PricingFreshness {
+  const verified = new Date(`${verifiedAt}T00:00:00Z`);
+  const ageDays = (now.getTime() - verified.getTime()) / 86_400_000;
+  return { verifiedAt, ageDays, stale: ageDays > staleDays };
+}

package/src/engines/_shared/schema-normalize.ts

@@ -0,0 +1,75 @@
+/**
+ * Shared JSON Schema normalizer for engine adapters.
+ *
+ * Auggy tools declare their input shape via Zod (`defineTool({ input: z.object(...) })`),
+ * which is converted to JSON Schema by `z.toJSONSchema()` in `src/helpers.ts`. Zod
+ * tends to add metadata keys like `$schema`, `$id`, and others that the model
+ * provider APIs (Anthropic Messages API, OpenAI Chat Completions tool parameters)
+ * either reject outright or silently ignore.
+ *
+ * `normalizeSchema` strips down to a known-safe subset and ensures the schema
+ * is shaped as `{ type: "object", properties, required, ... }` — which is what
+ * both Anthropic and OpenAI expect for tool input schemas.
+ *
+ * The Anthropic engine has its own inline copy that predates this extraction;
+ * this module is used by the OpenAI and OpenRouter engines. A future cleanup
+ * pass can consolidate the Anthropic engine to import from here.
+ */
+
+/** JSON Schema keys preserved by `normalizeSchema`. Matches what Anthropic's tool
+ *  input_schema field accepts; the OpenAI Chat Completions `function.parameters`
+ *  field accepts the same vocabulary (or a strict superset that we don't use). */
+export const ALLOWED_SCHEMA_KEYS = new Set([
+  "properties",
+  "required",
+  "description",
+  "enum",
+  "items",
+  "minItems",
+  "maxItems",
+  "minimum",
+  "maximum",
+  "pattern",
+  "format",
+  "default",
+  "anyOf",
+  "oneOf",
+  "allOf",
+  "not",
+  "additionalProperties",
+]);
+
+/** A normalized schema is always shaped as an object schema; the top-level
+ *  `type` is always `"object"`, and only allowed keys are preserved. */
+export type NormalizedObjectSchema = {
+  type: "object";
+  properties?: Record<string, unknown>;
+  required?: string[];
+  [key: string]: unknown;
+};
+
+/** Strip `schema` to its safe subset and force `type: "object"` at the root.
+ *
+ *  Empty or undefined input → `{ type: "object", properties: {} }`.
+ *  Top-level non-allowed keys (including `$schema`, `$id`, `title`) are dropped.
+ *  The input's own `type` field is overwritten — tool input schemas are always objects.
+ *
+ *  IMPORTANT: this function only normalizes the TOP LEVEL. Nested schemas
+ *  inside `properties` and `items` are passed through unchanged. In practice
+ *  Zod-generated schemas don't put metadata keys inside nested definitions,
+ *  but if a future caller produces such schemas they will not be stripped.
+ */
+export function normalizeSchema(
+  schema: Record<string, unknown> | undefined,
+): NormalizedObjectSchema {
+  if (!schema || Object.keys(schema).length === 0) {
+    return { type: "object", properties: {} };
+  }
+  const filtered: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(schema)) {
+    if (key !== "type" && ALLOWED_SCHEMA_KEYS.has(key)) {
+      filtered[key] = value;
+    }
+  }
+  return { type: "object", ...filtered };
+}

package/src/engines/anthropic/pricing.ts

@@ -0,0 +1,117 @@
+import {
+  type Pricing,
+  type CostResult,
+  type PricingFreshness,
+  computeCostUsd,
+  freshness,
+} from "../_shared/cost";
+
+// USD per million tokens. Update via PR when Anthropic changes pricing.
+// Cache rates: write = 1.25× input, read = 0.1× input (per Anthropic docs).
+const TABLE: Record<string, Pricing> = {
+  "claude-opus-4-7": {
+    inputUsdPerMtok: 15.0,
+    outputUsdPerMtok: 75.0,
+    cacheWriteUsdPerMtok: 18.75,
+    cacheReadUsdPerMtok: 1.5,
+  },
+  "claude-opus-4-6": {
+    inputUsdPerMtok: 15.0,
+    outputUsdPerMtok: 75.0,
+    cacheWriteUsdPerMtok: 18.75,
+    cacheReadUsdPerMtok: 1.5,
+  },
+  "claude-sonnet-4-6": {
+    inputUsdPerMtok: 3.0,
+    outputUsdPerMtok: 15.0,
+    cacheWriteUsdPerMtok: 3.75,
+    cacheReadUsdPerMtok: 0.3,
+  },
+  "claude-haiku-4-5": {
+    inputUsdPerMtok: 0.8,
+    outputUsdPerMtok: 4.0,
+    cacheWriteUsdPerMtok: 1.0,
+    cacheReadUsdPerMtok: 0.08,
+  },
+};
+
+/**
+ * Enumerate the model IDs in the pricing table. Used by the model picker
+ * to derive UI choices without exposing the table's internal shape.
+ */
+export function listModels(): string[] {
+  return Object.keys(TABLE);
+}
+
+const VERIFIED_AT = "2026-04-27";
+
+export function lookup(model: string): Pricing | null {
+  return TABLE[model] ?? null;
+}
+
+export function getFreshness(): PricingFreshness {
+  return freshness(VERIFIED_AT);
+}
+
+export interface AnthropicUsage {
+  input_tokens: number;
+  output_tokens: number;
+  cache_creation_input_tokens?: number | null;
+  cache_read_input_tokens?: number | null;
+  /** TTL-breakdown cache field (ephemeral_5m / ephemeral_1h tokens). */
+  cache_creation?: {
+    ephemeral_5m_input_tokens?: number;
+    ephemeral_1h_input_tokens?: number;
+  } | null;
+  service_tier?: string | null;
+}
+
+/**
+ * Price an Anthropic API response.
+ *
+ * Returns `{ priced: false, reason }` when the response contains
+ * discriminators that v0 pricing cannot model faithfully:
+ *   - `usage.cache_creation` with TTL breakdown (ephemeral_5m / ephemeral_1h)
+ *   - `usage.service_tier` !== "standard"
+ *   - Model not in the pricing table and no override provided
+ *
+ * In all other cases returns `{ priced: true, costUsd }`.
+ */
+export function priceAnthropicResponse(
+  model: string,
+  override: Pricing | undefined,
+  usage: AnthropicUsage,
+): CostResult {
+  // Discriminator gate: TTL breakdown present → unpriced.
+  if (
+    usage.cache_creation &&
+    (usage.cache_creation.ephemeral_5m_input_tokens ||
+      usage.cache_creation.ephemeral_1h_input_tokens)
+  ) {
+    return {
+      priced: false,
+      reason: "anthropic: cache_creation TTL breakdown not modeled in v0 pricing",
+    };
+  }
+
+  // Discriminator gate: non-standard service tier → unpriced.
+  if (usage.service_tier && usage.service_tier !== "standard") {
+    return {
+      priced: false,
+      reason: `anthropic: service_tier=${usage.service_tier} not modeled in v0 pricing`,
+    };
+  }
+
+  const rates = override ?? lookup(model);
+  if (!rates) {
+    return { priced: false, reason: `anthropic: no pricing entry for model "${model}"` };
+  }
+
+  const costUsd = computeCostUsd(rates, {
+    inputTokens: usage.input_tokens,
+    outputTokens: usage.output_tokens,
+    cacheCreationTokens: usage.cache_creation_input_tokens ?? undefined,
+    cacheReadTokens: usage.cache_read_input_tokens ?? undefined,
+  });
+  return { priced: true, costUsd };
+}