{
  "schemaVersion": "auggy.api-reference.v1",
  "package": {
    "name": "auggy",
    "sourcePackageVersion": "0.5.0",
    "publishedBaselineFromDocs": "0.5.0",
    "module": "auggy",
    "homepage": "https://auggy.dev",
    "summary": "Small Bun and TypeScript runtime for self-hosted agents, extended through augments that provide tools, memory, context, transports, skills, policy, and integrations.",
    "runtime": [
      "Bun",
      "TypeScript"
    ],
    "node": ">=20",
    "bun": ">=1.2.0"
  },
  "releaseStates": {
    "Published": "Available in the latest npm release described by the docs corpus.",
    "Preview": "Usable current behavior whose API or operational posture may change before 1.0."
  },
  "sources": [
    "../augment-1/src/index.ts",
    "../augment-1/src/helpers.ts",
    "../augment-1/src/types.ts",
    "../augment-1/src/agent.ts",
    "../augment-1/src/http.ts",
    "../augment-1/src/auth/external-auth.ts",
    "../augment-1/src/authz/delegated-authorization.ts",
    "../augment-1/src/kernel/route-manifest.ts",
    "../augment-1/src/cli/routes-client.ts",
    "../augment-1/src/transports/web-transport.ts",
    "src/lib/docs-content.ts"
  ],
  "imports": {
    "primary": "import { defineAugment, defineTool } from \"auggy\";",
    "advancedPreview": "import { defineRoute, json } from \"auggy\";",
    "auth": "import { createExternalAuthAssertion, verifyExternalAuthAssertion } from \"auggy\";",
    "http": "import { createHttpClient } from \"auggy\";",
    "providerAdapters": [
      "import { createAnthropicEngine } from \"@auggy/anthropic\";",
      "import { createOpenAIEngine } from \"@auggy/openai\";",
      "import { createOpenRouterEngine } from \"@auggy/openrouter\";"
    ]
  },
  "symbols": [
    {
      "name": "defineAugment",
      "kind": "function",
      "status": "Published",
      "import": "auggy",
      "signature": "defineAugment(opts: Augment): Augment",
      "summary": "Declare a composable runtime capability that can add tools, context, transport, memory, lifecycle hooks, policy, operator surfaces, and optional preview HTTP routes.",
      "parameters": [
        {
          "name": "opts",
          "type": "Augment",
          "required": true,
          "description": "The augment declaration. Runtime surfaces are inferred from concrete fields such as tools, HTTP routes, context, transport, memory, and lifecycle hooks."
        }
      ],
      "returns": {
        "type": "Augment",
        "description": "The same augment object, typed for composition by the runtime."
      },
      "example": "defineAugment({ name: \"support\", type: \"custom\", tools: [] })",
      "relatedDocs": [
        "/docs/define-augment",
        "/docs/build-augment"
      ]
    },
    {
      "name": "defineRoute.get",
      "kind": "function",
      "status": "Preview",
      "import": "auggy",
      "signature": "defineRoute.get(path: string, opts: DefineGetRouteOptions): AugmentHttpRoute",
      "summary": "Declare a deterministic GET route owned by an augment.",
      "parameters": [
        {
          "name": "path",
          "type": "string",
          "required": true,
          "description": "Route path. Must start with /. Full-segment params use :name, such as /orders/:id."
        },
        {
          "name": "opts.auth",
          "type": "AugmentHttpRouteAuth",
          "required": true,
          "description": "Required auth mode. There is no implicit default."
        },
        {
          "name": "opts.query",
          "type": "z.ZodType | undefined",
          "required": false,
          "description": "Schema for parsed query parameters."
        },
        {
          "name": "opts.params",
          "type": "z.ZodType | undefined",
          "required": false,
          "description": "Schema for path params."
        },
        {
          "name": "opts.response",
          "type": "z.ZodType | undefined",
          "required": false,
          "description": "Successful JSON response schema for route manifests, OpenAPI export, and generated clients."
        },
        {
          "name": "opts.handler",
          "type": "(ctx: RouteContext) => Promise<Response> | Response",
          "required": true,
          "description": "Handler receives request, signal, auth, params, route, query, and body."
        }
      ],
      "returns": {
        "type": "AugmentHttpRoute",
        "description": "Route declaration collected at agent.start()."
      },
      "example": "defineRoute.get(\"/services/search\", { auth: \"none\", query: SearchQuery, response: SearchResponse, handler: ({ query }) => json({ services: search(query.q) }) })",
      "relatedDocs": [
        "/docs/define-route",
        "/docs/add-http-routes"
      ]
    },
    {
      "name": "defineRoute.post",
      "kind": "function",
      "status": "Preview",
      "import": "auggy",
      "signature": "defineRoute.post(path: string, opts: DefinePostRouteOptions): AugmentHttpRoute",
      "summary": "Declare a deterministic POST route owned by an augment.",
      "parameters": [
        {
          "name": "path",
          "type": "string",
          "required": true,
          "description": "Route path. Must start with /. Full-segment params use :name, such as /orders/:id/refund."
        },
        {
          "name": "opts.auth",
          "type": "AugmentHttpRouteAuth",
          "required": true,
          "description": "Required auth mode."
        },
        {
          "name": "opts.body",
          "type": "z.ZodType | undefined",
          "required": false,
          "description": "Schema for JSON request body. Invalid JSON or schema mismatch returns 400."
        },
        {
          "name": "opts.query",
          "type": "z.ZodType | undefined",
          "required": false,
          "description": "Schema for parsed query parameters."
        },
        {
          "name": "opts.params",
          "type": "z.ZodType | undefined",
          "required": false,
          "description": "Schema for path params."
        },
        {
          "name": "opts.timeoutMs",
          "type": "number | undefined",
          "required": false,
          "default": 30000,
          "description": "Per-route handler timeout in milliseconds."
        },
        {
          "name": "opts.maxBodyBytes",
          "type": "number | undefined",
          "required": false,
          "default": 1048576,
          "description": "Maximum accepted request body bytes."
        },
        {
          "name": "opts.rateLimit",
          "type": "{ maxPerMinute: number } | undefined",
          "required": false,
          "description": "Sliding-window per-route rate limit."
        },
        {
          "name": "opts.requires",
          "type": "AuthorizationRequirement | readonly AuthorizationRequirement[] | undefined",
          "required": false,
          "description": "Delegated app authorization requirements satisfied by verified external auth claims."
        },
        {
          "name": "opts.policy",
          "type": "AugmentHttpRoutePolicy | undefined",
          "required": false,
          "description": "Policy metadata, currently webhook signature policy."
        },
        {
          "name": "opts.response",
          "type": "z.ZodType | undefined",
          "required": false,
          "description": "Successful JSON response schema for route manifests, OpenAPI export, and generated clients."
        },
        {
          "name": "opts.handler",
          "type": "(ctx: RouteContext) => Promise<Response> | Response",
          "required": true,
          "description": "Handler receives request, signal, auth, params, route, query, and body."
        }
      ],
      "returns": {
        "type": "AugmentHttpRoute",
        "description": "Route declaration collected at agent.start()."
      },
      "example": "defineRoute.post(\"/leads/create\", { auth: \"visitor.optional\", body: CreateLeadSchema, maxBodyBytes: 8192, rateLimit: { maxPerMinute: 10 }, response: LeadResponse, handler: ({ body }) => json({ lead: saveLead(body) }, 201) })",
      "relatedDocs": [
        "/docs/define-route",
        "/docs/add-http-routes",
        "/docs/build-augment"
      ]
    },
    {
      "name": "defineRoute.group",
      "kind": "function",
      "status": "Preview",
      "import": "auggy",
      "signature": "defineRoute.group(prefix: string, routes: readonly AugmentHttpRoute[]): AugmentHttpRoute[]",
      "summary": "Prefix a group of routes while preserving effective route context.",
      "parameters": [
        {
          "name": "prefix",
          "type": "string",
          "required": true,
          "description": "Path prefix."
        },
        {
          "name": "routes",
          "type": "readonly AugmentHttpRoute[]",
          "required": true,
          "description": "Routes to prefix."
        }
      ],
      "returns": {
        "type": "AugmentHttpRoute[]",
        "description": "A new route array with prefixed paths."
      }
    },
    {
      "name": "defineTool",
      "kind": "function",
      "status": "Published",
      "import": "auggy",
      "signature": "defineTool<T extends z.ZodType>(opts: { name: string; description: string; category: ToolCategory; input: T; requires?: AuthorizationRequirement | readonly AuthorizationRequirement[]; execute: (input: z.infer<T>, context?: ToolExecuteContext) => Promise<string | ToolResult> }): Tool<z.infer<T>>",
      "summary": "Declare a model-callable capability with typed input, optional delegated authorization, and a structured or string result.",
      "parameters": [
        {
          "name": "opts.name",
          "type": "string",
          "required": true,
          "description": "Stable tool name exposed to the model."
        },
        {
          "name": "opts.description",
          "type": "string",
          "required": true,
          "description": "Model-facing description. Keep it action-oriented and specific."
        },
        {
          "name": "opts.category",
          "type": "ToolCategory",
          "required": true,
          "description": "Tool category used by selection and docs."
        },
        {
          "name": "opts.input",
          "type": "z.ZodType",
          "required": true,
          "description": "Input schema. Converted to JSON Schema for model/tool metadata."
        },
        {
          "name": "opts.requires",
          "type": "AuthorizationRequirement | readonly AuthorizationRequirement[] | undefined",
          "required": false,
          "description": "Delegated app authorization requirements."
        },
        {
          "name": "opts.execute",
          "type": "(input, context?) => Promise<string | ToolResult>",
          "required": true,
          "description": "Tool implementation."
        }
      ],
      "returns": {
        "type": "Tool",
        "description": "A typed tool declaration for the augment."
      },
      "example": "defineTool({ name: \"save_lead\", description: \"Save a lead for creator follow-up.\", category: \"business\", input: CreateLeadSchema, execute: async (input) => JSON.stringify({ lead: saveLead(input) }) })",
      "relatedDocs": [
        "/docs/define-tool",
        "/docs/add-tools",
        "/docs/build-augment"
      ]
    },
    {
      "name": "json",
      "kind": "function",
      "status": "Preview",
      "import": "auggy",
      "signature": "json(data: unknown, status?: number, headers?: Headers | Record<string, string>): Response",
      "summary": "Create a JSON Response with content-type application/json unless already supplied.",
      "parameters": [
        {
          "name": "data",
          "type": "unknown",
          "required": true,
          "description": "JSON-serializable response body."
        },
        {
          "name": "status",
          "type": "number",
          "required": false,
          "default": 200,
          "description": "HTTP status code."
        },
        {
          "name": "headers",
          "type": "Headers | Record<string, string>",
          "required": false,
          "description": "Additional headers."
        }
      ],
      "returns": {
        "type": "Response",
        "description": "Native Response object."
      }
    },
    {
      "name": "webhook.signature",
      "kind": "function",
      "status": "Preview",
      "import": "auggy",
      "signature": "webhook.signature(provider: AugmentHttpRouteWebhookProvider, opts?: { secretEnv?: string; timestampToleranceSeconds?: number }): AugmentHttpRouteWebhookSignaturePolicy",
      "summary": "Build webhook signature policy metadata for route manifests and transports that implement provider verification.",
      "parameters": [
        {
          "name": "provider",
          "type": "\"stripe\" | \"github\" | \"svix\" | string",
          "required": true,
          "description": "Webhook provider identifier."
        },
        {
          "name": "opts.secretEnv",
          "type": "string | undefined",
          "required": false,
          "description": "Environment variable containing the signing secret. Manifest exposes the name, never the value."
        },
        {
          "name": "opts.timestampToleranceSeconds",
          "type": "number | undefined",
          "required": false,
          "description": "Maximum accepted provider timestamp age. Stripe and Svix default to 300 seconds when omitted."
        }
      ],
      "returns": {
        "type": "AugmentHttpRouteWebhookSignaturePolicy",
        "description": "Route policy metadata."
      }
    },
    {
      "name": "defineAgent",
      "kind": "function",
      "status": "Published",
      "import": "auggy",
      "signature": "defineAgent(config: AgentConfig, model: ModelClient): AgentHandle",
      "summary": "Construct an agent runtime handle from config, augments, and a model client.",
      "parameters": [
        {
          "name": "config",
          "type": "AgentConfig",
          "required": true,
          "description": "Runtime config with name, model id, augments, context budget, compaction, and inference/tool-choice settings."
        },
        {
          "name": "model",
          "type": "ModelClient",
          "required": true,
          "description": "Provider adapter implementing complete(), countTokens(), and maxContextTokens."
        }
      ],
      "returns": {
        "type": "AgentHandle",
        "description": "start, stop, ready, health, card, and inject methods."
      }
    },
    {
      "name": "createExternalAuthAssertion",
      "kind": "function",
      "status": "Preview",
      "import": "auggy",
      "signature": "createExternalAuthAssertion(opts: CreateExternalAuthAssertionOptions): string",
      "summary": "Create a short-lived app-signed assertion that lets Auggy treat external app auth as public recognized context with scopes and grants.",
      "parameters": [
        {
          "name": "opts.secret",
          "type": "string",
          "required": true,
          "description": "Signing secret."
        },
        {
          "name": "opts.audience",
          "type": "string",
          "required": true,
          "description": "Target Auggy agent id/audience."
        },
        {
          "name": "opts.provider",
          "type": "string",
          "required": true,
          "description": "External auth provider name."
        },
        {
          "name": "opts.subject",
          "type": "string",
          "required": true,
          "description": "External subject/user id."
        },
        {
          "name": "opts.ttlSeconds",
          "type": "number | undefined",
          "required": false,
          "default": 300,
          "description": "Assertion TTL in seconds."
        },
        {
          "name": "opts.scopes",
          "type": "readonly string[] | undefined",
          "required": false,
          "description": "Delegated scopes."
        },
        {
          "name": "opts.grants",
          "type": "readonly AuthorizationGrant[] | undefined",
          "required": false,
          "description": "Delegated action/resource grants."
        }
      ],
      "returns": {
        "type": "string",
        "description": "Compact assertion string formatted as base64urlPayload.signature."
      },
      "relatedDocs": [
        "/docs/delegated-authorization"
      ]
    },
    {
      "name": "verifyExternalAuthAssertion",
      "kind": "function",
      "status": "Preview",
      "import": "auggy",
      "signature": "verifyExternalAuthAssertion(assertion: string, opts: VerifyExternalAuthAssertionOptions): ExternalAuthAssertionVerification",
      "summary": "Verify a compact external auth assertion.",
      "parameters": [
        {
          "name": "assertion",
          "type": "string",
          "required": true,
          "description": "Assertion created by createExternalAuthAssertion."
        },
        {
          "name": "opts",
          "type": "VerifyExternalAuthAssertionOptions",
          "required": true,
          "description": "Secret(s), expected audience, allowed providers, TTL limit, and clock override."
        }
      ],
      "returns": {
        "type": "{ ok: true; claims: ExternalAuthClaims } | { ok: false; reason: ExternalAuthAssertionFailureReason }",
        "description": "Verification result."
      }
    },
    {
      "name": "externalAuthClaimsToRouteContext",
      "kind": "function",
      "status": "Preview",
      "import": "auggy",
      "signature": "externalAuthClaimsToRouteContext(claims: ExternalAuthClaims, opts?: ExternalAuthPrincipalOptions): RouteVisitorAuthContext",
      "summary": "Convert verified external auth claims into Auggy visitor route context."
    },
    {
      "name": "externalAuthClaimsToRoutePrincipal",
      "kind": "function",
      "status": "Preview",
      "import": "auggy",
      "signature": "externalAuthClaimsToRoutePrincipal(claims: ExternalAuthClaims, opts?: ExternalAuthPrincipalOptions): Extract<RouteAuthPrincipal, { kind: \"visitor\" }>",
      "summary": "Convert verified external auth claims into the typed visitor principal payload for public recognized context."
    },
    {
      "name": "externalSubjectVisitorId",
      "kind": "function",
      "status": "Preview",
      "import": "auggy",
      "signature": "externalSubjectVisitorId(claims: Pick<ExternalAuthClaims, \"provider\" | \"subject\">): string",
      "summary": "Create a stable Auggy visitor id from an external provider and subject."
    },
    {
      "name": "createInMemoryExternalAuthReplayStore",
      "kind": "function",
      "status": "Preview",
      "import": "auggy",
      "signature": "createInMemoryExternalAuthReplayStore(): ExternalAuthReplayStore",
      "summary": "Create an in-memory JTI replay store for verified external auth assertions."
    },
    {
      "name": "createHttpClient",
      "kind": "function",
      "status": "Published",
      "import": "auggy",
      "signature": "createHttpClient(opts?: HttpClientOptions): HttpClient",
      "summary": "Create a fetch-backed HTTP client with timeout, redirect limit, user-agent, body cap, default headers, and optional structural SSRF guard.",
      "parameters": [
        {
          "name": "opts.timeoutMs",
          "type": "number | undefined",
          "required": false,
          "default": 20000,
          "description": "Total timeout across the request and redirects."
        },
        {
          "name": "opts.maxRedirects",
          "type": "number | undefined",
          "required": false,
          "default": 10,
          "description": "Maximum 3xx redirects to follow."
        },
        {
          "name": "opts.userAgent",
          "type": "string | undefined",
          "required": false,
          "default": "auggy-http/0.1",
          "description": "User-Agent header."
        },
        {
          "name": "opts.defaultHeaders",
          "type": "Record<string, string> | undefined",
          "required": false,
          "description": "Headers added to every request."
        },
        {
          "name": "opts.maxBodyBytes",
          "type": "number | undefined",
          "required": false,
          "default": 5242880,
          "description": "Maximum response body size; larger responses are truncated."
        },
        {
          "name": "opts.rejectUnsafeUrls",
          "type": "boolean | undefined",
          "required": false,
          "default": false,
          "description": "Reject non-http(s), loopback, RFC1918, link-local, cloud metadata, and related unsafe literal hosts before fetch."
        }
      ],
      "returns": {
        "type": "HttpClient",
        "description": "request, get, post, put, delete, and head methods."
      }
    }
  ],
  "types": [
    {
      "name": "Augment",
      "status": "Published",
      "summary": "Composable runtime capability registered into an agent.",
      "fields": [
        {
          "name": "name",
          "type": "string",
          "required": true
        },
        {
          "name": "type",
          "type": "string | undefined",
          "required": false
        },
        {
          "name": "version",
          "type": "string | undefined",
          "required": false
        },
        {
          "name": "category",
          "type": "\"transports\" | \"capabilities\" | \"memory\" | \"guardrails\" | undefined",
          "required": false
        },
        {
          "name": "context",
          "type": "(turn: TurnState, priorContext?: ContextBlock[]) => Promise<ContextBlock[] | string> | undefined",
          "required": false
        },
        {
          "name": "tools",
          "type": "Tool[] | undefined",
          "required": false
        },
        {
          "name": "httpRoutes",
          "type": "AugmentHttpRoute[] | undefined",
          "required": false,
          "status": "Preview"
        },
        {
          "name": "transport",
          "type": "TransportSpec | undefined",
          "required": false
        },
        {
          "name": "memory",
          "type": "MemoryProviderSpec | undefined",
          "required": false
        },
        {
          "name": "constraints",
          "type": "AugmentConstraints | undefined",
          "required": false
        },
        {
          "name": "adminInfo",
          "type": "() => Promise<AdminInfoBlock> | undefined",
          "required": false
        },
        {
          "name": "onBoot",
          "type": "() => Promise<void> | undefined",
          "required": false
        },
        {
          "name": "onShutdown",
          "type": "() => Promise<void> | undefined",
          "required": false
        },
        {
          "name": "onTurnStart",
          "type": "(turn: TurnState) => Promise<void> | undefined",
          "required": false
        },
        {
          "name": "onTurnEnd",
          "type": "(turn: TurnResult) => Promise<void> | undefined",
          "required": false
        },
        {
          "name": "onIdle",
          "type": "() => Promise<void> | undefined",
          "required": false
        }
      ]
    },
    {
      "name": "AugmentCapability",
      "status": "Published",
      "type": "\"transport\" | \"context\" | \"tools\" | \"lifecycle\""
    },
    {
      "name": "ToolResult",
      "status": "Published",
      "summary": "Structured tool result. Tools may still return a plain string.",
      "fields": [
        {
          "name": "content",
          "type": "string",
          "required": true
        },
        {
          "name": "terminate",
          "type": "{ status: \"input-required\" | \"completed\"; message?: string } | undefined",
          "required": false
        }
      ]
    },
    {
      "name": "RouteContext",
      "status": "Preview",
      "summary": "Typed context passed to defineRoute handlers.",
      "fields": [
        {
          "name": "request",
          "type": "Request",
          "required": true
        },
        {
          "name": "signal",
          "type": "AbortSignal",
          "required": true
        },
        {
          "name": "auth",
          "type": "RouteAuthContext",
          "required": true
        },
        {
          "name": "webhook",
          "type": "RouteWebhookContext | undefined",
          "required": false
        },
        {
          "name": "params",
          "type": "TParams",
          "required": true
        },
        {
          "name": "query",
          "type": "TQuery",
          "required": true
        },
        {
          "name": "body",
          "type": "TBody",
          "required": true
        },
        {
          "name": "route",
          "type": "{ method: \"GET\" | \"POST\"; path: string; params: TParams }",
          "required": true
        }
      ]
    },
    {
      "name": "AugmentHttpRouteAuth",
      "status": "Preview",
      "type": "\"bearer\" | \"creator\" | \"none\" | \"visitor.optional\" | \"visitor.required\" | \"agent.required\""
    },
    {
      "name": "AuthorizationRequirement",
      "status": "Preview",
      "summary": "Delegated authorization rule satisfied by verified external auth claims.",
      "variants": [
        {
          "type": "{ scope: string }",
          "description": "Requires a delegated scope."
        },
        {
          "type": "{ action: string; resource?: string | { param: string } | { input: string }; constraints?: Readonly<Record<string, AuthorizationConstraintValue>> }",
          "description": "Requires a delegated action grant, optionally bound to a route param or tool input."
        }
      ]
    },
    {
      "name": "AgentConfig",
      "status": "Published",
      "fields": [
        {
          "name": "name",
          "type": "string",
          "required": true
        },
        {
          "name": "displayName",
          "type": "string | undefined",
          "required": false
        },
        {
          "name": "creator",
          "type": "CreatorConfig | undefined",
          "required": false
        },
        {
          "name": "purpose",
          "type": "string | undefined",
          "required": false
        },
        {
          "name": "model",
          "type": "string",
          "required": true
        },
        {
          "name": "augments",
          "type": "Augment[]",
          "required": true
        },
        {
          "name": "contextBudget",
          "type": "{ historyPercent?: number; toolSchemaPercent?: number } | undefined",
          "required": false
        },
        {
          "name": "compactionStrategy",
          "type": "\"summarize\" | \"truncate\" | \"sliding-window\" | undefined",
          "required": false
        },
        {
          "name": "maxInferenceLoops",
          "type": "number | undefined",
          "required": false,
          "default": 10
        },
        {
          "name": "toolChoice",
          "type": "\"auto\" | \"any\" | { name: string } | undefined",
          "required": false,
          "default": "auto"
        }
      ]
    },
    {
      "name": "AgentHandle",
      "status": "Published",
      "methods": [
        {
          "name": "start",
          "signature": "start(): Promise<void>"
        },
        {
          "name": "stop",
          "signature": "stop(): Promise<void>"
        },
        {
          "name": "ready",
          "signature": "ready(): Promise<void>"
        },
        {
          "name": "health",
          "signature": "health(): AgentHealth"
        },
        {
          "name": "card",
          "signature": "card(): AgentCard"
        },
        {
          "name": "inject",
          "signature": "inject(trigger: TurnTrigger): Promise<TurnResult>"
        }
      ]
    },
    {
      "name": "ModelClient",
      "status": "Published",
      "fields": [
        {
          "name": "complete",
          "type": "(prompt: AssembledPrompt, opts?: { onDelta?: (delta: ModelDelta) => void }) => Promise<ModelResponse>",
          "required": true
        },
        {
          "name": "countTokens",
          "type": "(text: string) => number",
          "required": true
        },
        {
          "name": "maxContextTokens",
          "type": "number",
          "required": true
        }
      ]
    },
    {
      "name": "HttpClient",
      "status": "Published",
      "methods": [
        {
          "name": "request",
          "signature": "request(url: string, init?: HttpRequestInit): Promise<HttpResponse>"
        },
        {
          "name": "get",
          "signature": "get(url: string, init?: Omit<HttpRequestInit, \"method\" | \"body\">): Promise<HttpResponse>"
        },
        {
          "name": "post",
          "signature": "post(url: string, init?: Omit<HttpRequestInit, \"method\">): Promise<HttpResponse>"
        },
        {
          "name": "put",
          "signature": "put(url: string, init?: Omit<HttpRequestInit, \"method\">): Promise<HttpResponse>"
        },
        {
          "name": "delete",
          "signature": "delete(url: string, init?: Omit<HttpRequestInit, \"method\">): Promise<HttpResponse>"
        },
        {
          "name": "head",
          "signature": "head(url: string, init?: Omit<HttpRequestInit, \"method\" | \"body\">): Promise<HttpResponse>"
        }
      ]
    }
  ],
  "routeReference": {
    "status": "Preview",
    "methods": [
      "GET",
      "POST"
    ],
    "pathRules": {
      "mustStartWithSlash": true,
      "params": "Full-segment path params use :name.",
      "reservedPaths": [
        "/",
        "/agent/run",
        "/health",
        "/.well-known/agent-card.json"
      ],
      "reservedPrefixes": [
        "/console",
        "/admin"
      ],
      "collisionBehavior": "Exact or overlapping method/path collisions throw at agent.start()."
    },
    "authModes": [
      {
        "mode": "none",
        "public": true,
        "headers": [],
        "handlerAuthMode": "none",
        "description": "Accepts any caller. Use deliberately for public callbacks and intentionally public routes."
      },
      {
        "mode": "visitor.optional",
        "public": true,
        "headers": [
          "x-visitor-token",
          "x-auggy-auth-assertion"
        ],
        "handlerAuthMode": "visitor",
        "description": "Accepts anonymous callers and upgrades to public recognized context when a visitor token or external auth assertion is valid."
      },
      {
        "mode": "visitor.required",
        "public": false,
        "headers": [
          "x-visitor-token",
          "x-auggy-auth-assertion"
        ],
        "handlerAuthMode": "visitor",
        "description": "Requires public recognized context."
      },
      {
        "mode": "bearer",
        "public": false,
        "headers": [
          "authorization"
        ],
        "handlerAuthMode": "bearer",
        "description": "Creator/operator route guarded by the web transport bearer token."
      },
      {
        "mode": "creator",
        "public": false,
        "headers": [
          "authorization"
        ],
        "handlerAuthMode": "creator",
        "description": "Semantic creator-only alias for bearer auth."
      },
      {
        "mode": "agent.required",
        "public": false,
        "headers": [
          "x-agent-id",
          "x-agent-secret"
        ],
        "handlerAuthMode": "agent",
        "description": "Requires admitted machine/agent credentials from access.agents."
      }
    ],
    "manifestEntry": {
      "type": "RouteManifestEntry",
      "fields": [
        "method",
        "path",
        "augmentName",
        "auth",
        "params",
        "public",
        "security",
        "timeoutMs",
        "maxBodyBytes",
        "rateLimit",
        "policy",
        "requires",
        "requestJsonSchema",
        "responseJsonSchema"
      ]
    },
    "responseShapes": {
      "jsonHelper": {
        "contentType": "application/json",
        "body": "JSON.stringify(data)",
        "statusDefault": 200
      },
      "generatedClientResult": {
        "type": "AuggyClientResult<TData>",
        "success": "{ ok: true; status: number; data: TData; response: Response; visitorToken?: string }",
        "failure": "{ ok: false; status: number; data: unknown; response: Response; visitorToken?: string }"
      },
      "dispatcherErrors": [
        {
          "status": 400,
          "body": {
            "error": "bad-request",
            "message": "Invalid request"
          },
          "when": "defineRoute helper cannot parse JSON, params, query, or body schema"
        },
        {
          "status": 400,
          "body": {
            "error": "bad-body"
          },
          "when": "dispatcher cannot read request body"
        },
        {
          "status": 401,
          "body": {
            "error": "unauthorized"
          },
          "when": "bearer or creator auth is missing or invalid"
        },
        {
          "status": 401,
          "body": {
            "error": "visitor-auth-required"
          },
          "when": "visitor.required route has no public recognized context"
        },
        {
          "status": 401,
          "body": {
            "error": "agent-auth-required"
          },
          "when": "agent.required route has no valid agent credentials"
        },
        {
          "status": 403,
          "body": {
            "error": "forbidden",
            "reason": "authorization-claims-required|authorization-scope-missing|authorization-grant-missing|authorization-resource-unresolved"
          },
          "when": "delegated authorization requirements fail"
        },
        {
          "status": 413,
          "body": {
            "error": "payload-too-large"
          },
          "when": "request body exceeds maxBodyBytes"
        },
        {
          "status": 429,
          "headers": {
            "retry-after": "seconds"
          },
          "body": {
            "error": "rate-limited"
          },
          "when": "per-route rate limit is exceeded"
        },
        {
          "status": 500,
          "body": {
            "error": "route-auth-misconfigured"
          },
          "when": "route auth mode is invalid at dispatch"
        },
        {
          "status": 500,
          "body": {
            "error": "internal"
          },
          "when": "route handler throws"
        },
        {
          "status": 504,
          "body": {
            "error": "timeout"
          },
          "when": "route handler exceeds timeoutMs"
        }
      ]
    },
    "cli": [
      {
        "command": "auggy routes [name]",
        "description": "Inspect deterministic augment routes."
      },
      {
        "command": "auggy routes [name] --json",
        "description": "Emit route manifest JSON."
      },
      {
        "command": "auggy routes [name] --openapi",
        "description": "Emit an OpenAPI 3.1 JSON document."
      },
      {
        "command": "auggy routes [name] --client ts --target browser --out src/auggy-client.ts",
        "description": "Generate a browser-safe TypeScript route client. Browser target omits bearer, creator, agent, and webhook-policy routes."
      },
      {
        "command": "auggy routes [name] --client ts --target server --out src/auggy-client.server.ts",
        "description": "Generate a server TypeScript route client including privileged routes."
      }
    ]
  },
  "configFiles": [
    {
      "path": "agent.yaml",
      "status": "Published",
      "summary": "Runtime source of truth for an agent project.",
      "fields": [
        {
          "name": "name",
          "type": "string",
          "required": true
        },
        {
          "name": "displayName",
          "type": "string",
          "required": false
        },
        {
          "name": "purpose",
          "type": "string",
          "required": false
        },
        {
          "name": "engine.provider",
          "type": "\"anthropic\" | \"openai\" | \"openrouter\" | \"ollama\"",
          "required": true
        },
        {
          "name": "engine.model",
          "type": "string",
          "required": true
        },
        {
          "name": "engine.baseURL",
          "type": "string",
          "required": false
        },
        {
          "name": "engine.reasoningEffort",
          "type": "\"none\" | \"minimal\" | \"low\" | \"medium\" | \"high\" | \"xhigh\"",
          "required": false
        },
        {
          "name": "engine.routing.sort",
          "type": "\"price\" | \"throughput\" | \"latency\"",
          "required": false
        },
        {
          "name": "augments",
          "type": "string[] | Array<{ name?: string; type: string; options?: object }>",
          "required": true
        },
        {
          "name": "settings",
          "type": "object",
          "required": false
        },
        {
          "name": "access.agents",
          "type": "Array<{ id: string; secretEnv?: string; secret?: string; displayName?: string; orgId?: string }>",
          "required": false
        }
      ],
      "notes": [
        "Keep secrets in .env or provider-owned secret stores, not in agent.yaml.",
        "agent.yaml selects provider/model and enabled augment order."
      ]
    },
    {
      "path": "augments/<id>/augment.yaml",
      "status": "Published",
      "summary": "Per-augment config file.",
      "fields": [
        {
          "name": "type",
          "type": "string",
          "required": true
        },
        {
          "name": "config",
          "type": "object",
          "required": false
        }
      ],
      "notes": [
        "Reference secrets through environment variables instead of storing secret values.",
        "Custom augments usually pair augment.yaml with index.ts."
      ]
    },
    {
      "path": "skills/<name>/SKILL.md",
      "status": "Published",
      "summary": "Model-readable skill instructions loaded on demand.",
      "notes": [
        "Skills are not code and are not augments.",
        "Use skills to teach judgment about when and how to use tools and workflows without loading every instruction every turn."
      ]
    }
  ],
  "cli": [
    {
      "command": "auggy create <name>",
      "status": "Published",
      "description": "Scaffold a standalone agent project."
    },
    {
      "command": "auggy init [name]",
      "status": "Published",
      "description": "Initialize the current directory as an Auggy agent project."
    },
    {
      "command": "auggy run [name]",
      "status": "Published",
      "description": "Run an agent locally and open /console/chat."
    },
    {
      "command": "auggy dev [name]",
      "status": "Published",
      "description": "Run an agent in the foreground."
    },
    {
      "command": "auggy start [name]",
      "status": "Published",
      "description": "Install agent as a launchd service."
    },
    {
      "command": "auggy stop <name>",
      "status": "Published",
      "description": "Stop a running agent."
    },
    {
      "command": "auggy restart <name>",
      "status": "Published",
      "description": "Stop and restart a running agent."
    },
    {
      "command": "auggy status [name]",
      "status": "Published",
      "description": "Show running agents or detail a specific one."
    },
    {
      "command": "auggy list",
      "status": "Published",
      "description": "List agent projects in the current directory."
    },
    {
      "command": "auggy chat [name]",
      "status": "Published",
      "description": "Open a running agent console chat."
    },
    {
      "command": "auggy deploy [name] --to railway",
      "status": "Published",
      "description": "Deploy an agent to Railway."
    },
    {
      "command": "auggy doctor [name]",
      "status": "Published",
      "description": "Check whether an agent is ready to run."
    },
    {
      "command": "auggy models list [provider]",
      "status": "Published",
      "description": "List models Auggy can select or recognize."
    },
    {
      "command": "auggy models doctor [name]",
      "status": "Published",
      "description": "Check configured model and pricing status."
    },
    {
      "command": "auggy augment add [augments...]",
      "status": "Published",
      "description": "Add built-in or local augments to an agent."
    },
    {
      "command": "auggy augment create <slug>",
      "status": "Published",
      "description": "Scaffold a local custom augment."
    },
    {
      "command": "auggy augment install <agent> <path>",
      "status": "Published",
      "description": "Install a local custom augment into an agent."
    },
    {
      "command": "auggy augment list",
      "status": "Published",
      "description": "List installed augments."
    },
    {
      "command": "auggy augment remove <augment>",
      "status": "Published",
      "description": "Remove an augment from an agent."
    },
    {
      "command": "auggy augment test <path>",
      "status": "Published",
      "description": "Validate a local custom augment module."
    },
    {
      "command": "auggy skill add <skill>",
      "status": "Published",
      "description": "Install or restore a bundled skill for an installed augment."
    },
    {
      "command": "auggy skill create <name>",
      "status": "Published",
      "description": "Create a user-authored skill."
    },
    {
      "command": "auggy skill list",
      "status": "Published",
      "description": "List installed skills."
    },
    {
      "command": "auggy skill remove <name>",
      "status": "Published",
      "description": "Remove a skill folder."
    },
    {
      "command": "auggy mcp init",
      "status": "Published",
      "description": "Create .mcp.json in the agent root."
    },
    {
      "command": "auggy mcp list",
      "status": "Published",
      "description": "List configured MCP servers."
    },
    {
      "command": "auggy mcp add-json <name> <json>",
      "status": "Published",
      "description": "Add or replace an MCP server from JSON."
    },
    {
      "command": "auggy routes [name]",
      "status": "Preview",
      "description": "Show HTTP routes registered by an agent."
    }
  ],
  "builtInAugments": [
    {
      "name": "fileMemory",
      "status": "Published",
      "summary": "Loads identity.md and learned-behaviors.md into context."
    },
    {
      "name": "filesystem",
      "status": "Published",
      "summary": "Scoped file access."
    },
    {
      "name": "webTransport",
      "status": "Published",
      "summary": "HTTP transport for chat, console, health, home, and AG-UI runtime routes."
    },
    {
      "name": "webFetch",
      "status": "Published",
      "summary": "Fetch URLs and HTTP APIs."
    },
    {
      "name": "knowledge",
      "status": "Published",
      "summary": "Local markdown docs and API-backed knowledge sources."
    },
    {
      "name": "skills",
      "status": "Published",
      "summary": "Mounts model-readable skill files."
    },
    {
      "name": "layeredMemory",
      "status": "Published",
      "summary": "Peer-scoped episodic memory backed by SQLite by default."
    },
    {
      "name": "visitorAuth",
      "status": "Published",
      "summary": "Email magic-link verification and public recognized visitor tokens."
    },
    {
      "name": "notify",
      "status": "Published",
      "summary": "Outbound notifications to an operator or service."
    },
    {
      "name": "agentMail",
      "status": "Published",
      "summary": "Policy-gated send, reply, and forward tools plus polling/WebSocket/Svix inbound, durable catch-up, human review, and reconciliation."
    },
    {
      "name": "telegramTransport",
      "status": "Published",
      "summary": "Bidirectional Telegram chat."
    },
    {
      "name": "mcp",
      "status": "Published",
      "summary": "Bridge local or remote MCP servers into Auggy tools."
    },
    {
      "name": "bash",
      "status": "Preview",
      "summary": "Shell capability with explicit setup and risk controls."
    },
    {
      "name": "budgets",
      "status": "Preview",
      "summary": "Turn and spend caps through a first-party turn gate."
    },
    {
      "name": "link",
      "status": "Preview",
      "summary": "Peer/link integration surface."
    }
  ],
  "generatedRouteClient": {
    "status": "Preview",
    "factory": "createAuggyClient(config)",
    "targets": {
      "browser": {
        "includes": [
          "none",
          "visitor.optional",
          "visitor.required"
        ],
        "omits": [
          "bearer",
          "creator",
          "agent.required",
          "webhook.signature routes"
        ],
        "config": [
          "baseUrl",
          "fetch",
          "visitorToken",
          "authAssertion",
          "onVisitorToken",
          "headers"
        ]
      },
      "server": {
        "includes": [
          "none",
          "visitor.optional",
          "visitor.required",
          "bearer",
          "creator",
          "agent.required",
          "webhook.signature routes"
        ],
        "config": [
          "baseUrl",
          "fetch",
          "bearerToken",
          "agentCredentials",
          "headers"
        ]
      }
    },
    "resultType": "AuggyClientResult<TData>",
    "commands": [
      "auggy routes [name] --client ts --target browser --out src/auggy-client.ts",
      "auggy routes [name] --client ts --target server --out src/auggy-client.server.ts"
    ]
  }
}