forgeos 0.1.0-alpha.1 → 0.1.0-alpha.10

package/AGENTS.md

@@ -1,4 +1,4 @@
-// @forge-generated generator=0.1.0-alpha.1 input=d50515ea2f22c012d06e8794c2031206c9478d732b15ce6592aa8bf74bdaa665 content=e0bf36433d915daf5ad06ac6265b3ac6f2cd1706269c69618bbbc1cb1f44e465
+// @forge-generated generator=0.1.0-alpha.10 input=9b218d51e45bbb3220f861cec8dcd08f63224475d6356fc73d26c330ddf108e7 content=1611635edf59c122b013ba76c85bd333ab3b30b289aaea04a9074f9438782a50
 # AGENTS.md
 
 <!-- forge-generated:start -->
@@ -69,6 +69,7 @@ forge inspect app --json
 forge inspect all --json
 forge inspect frontend --json
 forge inspect capabilities --json
+forge inspect agent-tools --json
 forge deps inspect <package> --json
 forge deps api <package> <symbol> --json
 forge deps trace <package> --json
@@ -82,6 +83,9 @@ forge doctor
 forge doctor windows --json
 forge setup windows --json
 forge agent print-context --json
+forge ai tools --json
+forge ai agents --json
+forge ai trace <traceId> --json
 forge verify --smoke
 forge verify --standard
 forge verify --strict
@@ -103,6 +107,21 @@ Tenant-scoped tables:
 - ANTHROPIC_API_KEY (required)
 - OPENAI_API_KEY (required)
 
+## AI Tools And Agents
+
+- AI SDK engine: Vercel AI SDK v6.
+- Forge layer: generated registry, runtime rules, telemetry, secrets, tenant/auth context, and agent contract.
+- Use `ctx.agent.run` or `ctx.ai.runAgent` only in actions, workflows, endpoints, and server code.
+- Do not create custom tool loops; use Forge tools and AI SDK `ToolLoopAgent` through the Forge runtime.
+
+Tools:
+
+- none
+
+Agents:
+
+- none
+
 ## Auth
 
 - Modes: dev-headers, jwt, oidc, disabled
@@ -158,6 +177,7 @@ Use:
 forge make resource <name> --fields title:text,status:enum(open,closed) --dry-run --json
 forge make resource <name> --fields title:text,status:enum(open,closed) --with-ui --yes
 forge make ui --framework vite --dry-run --json
+forge make ai-chat support --dry-run --json
 ```
 
 Review the plan before applying when the resource touches schema or policies.
@@ -194,11 +214,13 @@ Use:
 ```bash
 forge refactor rename field tickets.priority tickets.urgency --dry-run --json
 forge refactor rename field tickets.priority tickets.urgency --yes
+forge refactor rename command createTicket openTicket --dry-run --json
+forge refactor rename command createTicket openTicket --yes
 ```
 
-These codemods are AST-aware for `extract-action`, `rename field`, and `rename table`. Field renames are scoped to the target table, so `tickets.priority` only rewrites references linked to `tickets`.
+These codemods are AST-aware for `extract-action`, `rename command`, `rename field`, and `rename table`. Command renames update runtime registries, generated client references, frontend hooks, tests, and string references where safe. Field renames are scoped to the target table, so `tickets.priority` only rewrites references linked to `tickets`.
 
-Never edit `src/forge/_generated/**` directly. Review migration hints before applying field or table renames.
+Never edit `src/forge/_generated/**` directly. Review migration hints before applying command, field, or table renames.
 
 ### Plan impact-based tests
 
@@ -224,6 +246,19 @@ forge repair plan --from-last-test-run --write
 
 Apply only high-confidence deterministic repairs automatically. Review medium or low confidence repairs before changing code.
 
+### Add AI tools or agents
+
+Use:
+
+```bash
+forge generate
+forge inspect all --json
+forge ai check --json
+forge ai trace <traceId> --json
+```
+
+Define tools with `aiTool({ inputSchema, outputSchema, risk, needsApproval, handler })` and agents with `agent({ provider, model, instructions, tools, stopWhen })`. Execute agents with `ctx.agent.run` or `ctx.ai.runAgent` only from actions, workflows, endpoints, or server code. In dev, POST `/ai/agents/run` returns JSON for automation and POST `/ai/agents/chat` returns an AI SDK UIMessage stream for React `useChat`; both accept `agent: "<exportedAgentName>"` and use generated auto-tools from `agentTools.json`.
+
 ### Export agent adapters
 
 Use:

package/CHANGELOG.md

@@ -1,5 +1,99 @@
 # forgeos
 
+## 0.1.0-alpha.10
+
+Launch polish:
+
+- Fixed `forge run <external-command> --args ...` so CLI arguments reach the external runtime bridge.
+- Added direct external query CLI support through `forge query <service.query> --args ...`.
+- Emit generated `.json` artifacts as pure JSON while keeping deterministic headers on code/text artifacts.
+- Relaxed the `minimal-web` template verify script to `forge verify --smoke` and added the missing `check` script to `b2b-support-web`.
+- Updated public protocol/changelog docs for the external runtime and Go adapter alpha line.
+- Bumped the create-app wrapper package line to `create-forgeos-app@0.1.0-alpha.4`.
+
+## 0.1.0-alpha.9
+
+### Patch Changes
+
+- Added the Forge external runtime protocol bridge for manifest-backed commands and queries.
+- Added the Go adapter MVP with a real `go-billing` conformance example.
+- Emitted external service metadata into inspect/API/agent artifacts, including `needsApproval` for agent tools.
+- Reuse compiler classifier package signals across export classification, dropping repeated package signal scans.
+- Reuse serialized graph JSON when rendering the largest generated TypeScript graph artifacts.
+- Keep generated Forge artifacts aligned with the `0.1.0-alpha.9` compiler/runtime version.
+
+## 0.1.0-alpha.8
+
+### Patch Changes
+
+- [`7568756`](https://github.com/Stahldavid/forge/commit/756875688873dd60d3d6cf700a7bb7c211968c69) Thanks [@Stahldavid](https://github.com/Stahldavid)! - Publish prerelease packages through the ForgeOS alpha publisher so npm dist-tags stay aligned.
+
+## 0.1.0-alpha.7
+
+### Patch Changes
+
+- [`4ace311`](https://github.com/Stahldavid/forge/commit/4ace3113e3298b5c306000870922fcfbae9c1861) Thanks [@Stahldavid](https://github.com/Stahldavid)! - Keep npm prerelease publishing on the public alpha dist-tag.
+
+## 0.1.0-alpha.6
+
+### Patch Changes
+
+- [`c30f906`](https://github.com/Stahldavid/forge/commit/c30f9069c99ac747ce143ab5fbcbf13912ed8760) Thanks [@Stahldavid](https://github.com/Stahldavid)! - Add CLI version output, align create-app help with package metadata, and add release dependency audit evidence.
+
+## 0.1.0-alpha.5
+
+Release alignment for the public alpha channel:
+
+- Added `forge ai redteam --model-level --json` with deterministic prompt-injection, secret-exfiltration, approval-bypass, cross-tenant, and indirect tool-injection probes.
+- Added `forge security prove --full --json` support for source checkouts, with graceful structural-proof fallback when packaged apps do not include ForgeOS test fixtures.
+- Strengthened npm publish workflows to run `security prove --db postgres --full --json`.
+- Added public registry smoke coverage for `forgeos@alpha` and `create-forgeos-app@alpha`.
+- Bumped the create-app wrapper package line to `create-forgeos-app@0.1.0-alpha.1`.
+
+## 0.1.0-alpha.4
+
+Security assurance and release evidence hardening:
+
+- Added value-aware telemetry redaction for known secret values in safe-looking fields, messages, details, outputs, and stack traces.
+- Added webhook signature, timestamp, and replay protection helpers with Stripe/GitHub/generic HMAC coverage.
+- Added HTTP tenant-isolation tests that exercise the dev server/API boundary, not only the internal runtime executor.
+- Added `forge rls mutate-test --json` to kill dangerous generated RLS mutations such as missing FORCE RLS, missing policies, unconditional predicates, and `BYPASSRLS`.
+- Extended `forge security prove --json` with RLS mutation proof and invariant-level evidence metadata.
+- Added scripts to split security evidence by invariant and emit basic release supply-chain evidence plus CycloneDX SBOM.
+- Strengthened publish/security workflows so release gates use Postgres-backed security proof, RLS mutation proof, release evidence, and SBOM generation.
+
+## 0.1.0-alpha.3
+
+Native Forge AI agents on top of Vercel AI SDK v6:
+
+- Added `aiTool` and `agent` primitives with generated `agentTools.json` / `agentTools.md`.
+- Added `ctx.agent.run` and `ctx.ai.runAgent` using AI SDK `ToolLoopAgent`.
+- Added auto-tools for commands, queries, and liveQueries with read-only vs approval-required writes.
+- Added dev agent endpoints: `POST /ai/agents/run` and `POST /ai/agents/chat`.
+- Extended `forge ai` CLI with `tools`, `agents`, and `trace` subcommands.
+- Added `forge inspect agent-tools` and agent tool metadata in `agentContract.json`.
+- Upgraded runtime dependency to AI SDK v6 for tool calling, streaming UI, and MCP compatibility.
+
+Documentation:
+
+- Added public [AI](https://forgeos.readthedocs.io/en/latest/ai/) page and AST-aware `rename command` codemod docs.
+- Expanded ReadTheDocs to full agent-native coverage: agent workflow (`forge do`), frontend/liveQuery, security/data, authoring, testing/repair, self-host, templates, Material theme, and changelog page.
+
+## 0.1.0-alpha.2
+
+Windows and generated-app hardening:
+
+- Fixed Node ESM handler loading on Windows by importing generated app modules
+  through `file://` URLs across commands, queries, liveQueries, outbox actions,
+  workflow steps, mocks, and telemetry adapters.
+- Fixed `forge dev` SSE streaming on the Node HTTP fallback so liveQuery
+  snapshots are flushed immediately instead of buffering forever.
+- Hardened generated app scaffolding and web dev spawning on Windows.
+- Updated the B2B support template to route frontend imports through
+  `web/lib/forge.ts` and use safer handler input validation.
+- Added focused tests for Node compatibility, template scaffolding, runtime
+  imports, and streaming responses.
+
 ## 0.1.0-alpha.1
 
 Republish alpha with the dependency/API oracle improvements:

package/README.md

@@ -2,9 +2,11 @@
 
 Agent-native application framework and compiler for building Forge apps without a mandatory dashboard. ForgeOS turns application source into deterministic runtime contracts, generated clients, safety checks, and machine-readable context that humans and AI coding agents can use safely.
 
-**Status:** private/public alpha MVP, implemented through H42. The core compiler, local runtime, frontend SDK, production auth, RLS compiler, repair/review loops, UI test bridge, guided intent router, full-stack capability map, clean templates, faster generated checks, showcase app, Windows-safe Bun resolution, native Windows diagnostics/setup, Node-compatible CLI/runtime paths, observable verify timeouts, multi-OS Node CI smoke, release packaging smoke, npm alpha publishing, Trusted Publisher/OIDC release wiring, ReadTheDocs-ready public docs, package/version-aligned generator metadata, AST-aware codemods for `extract-action`, `rename field`, and `rename table`, broader field-test automation, and quieter template workspaces are present. Public release hardening is still focused on deeper semantic codemods and more real-project field reports.
+**Status:** private/public alpha MVP, implemented through H43. ForgeOS already includes the compiler, local runtime, frontend SDK, production auth, RLS compiler, liveQuery, self-host artifacts, generated agent contract, guided dev loop, repair/review/test tooling, AST-aware codemods, package intelligence, native AI tools/agents, npm alpha publishing, and Read the Docs public docs. Public release hardening is still focused on deeper semantic codemods, broader field reports, and more production mileage.
 
-Public docs are configured for ReadTheDocs with `.readthedocs.yaml` and `mkdocs.yml`. The local docs entrypoint is `docs/index.md`.
+Public docs live at [forgeos.readthedocs.io](https://forgeos.readthedocs.io/). The repo builds them with `.readthedocs.yaml`, `mkdocs.yml`, and `docs/index.md`.
+
+Start with [Why ForgeOS](https://forgeos.readthedocs.io/en/latest/why-forgeos/) to understand the agent-native design.
 
 ## Agent-First Quickstart
 
@@ -44,6 +46,22 @@ These files describe the app surface, runtime rules, generated files, policies,
 
 ## Create a Test App
 
+Public one-command app creation:
+
+```bash
+npm create forgeos-app@alpha notes-app -- --template minimal-web
+cd notes-app
+npm run dev
+```
+
+Equivalent lower-level command without installing ForgeOS globally:
+
+```bash
+npm exec --package forgeos@alpha -- forge new notes-app --template minimal-web --package-manager npm
+```
+
+If ForgeOS is already installed or you are inside this repository:
+
 ```bash
 forge new notes-app --template minimal-web --package-manager npm
 cd notes-app
@@ -58,11 +76,11 @@ Templates also include workspace editor excludes for generated/runtime directori
 For release or external smoke testing, choose the Forge package source explicitly:
 
 ```bash
-forge new smoke-app --template minimal-web --package-manager npm --forge-spec "npm:forgeos@^0.1.0-alpha.0"
+forge new smoke-app --template minimal-web --package-manager npm --forge-spec "npm:forgeos@alpha"
 forge new local-app --template minimal-web --package-manager npm --local-forge
 ```
 
-`--forge-spec` writes that dependency spec into the generated app, while `--local-forge` keeps the monorepo/local package workflow. The npm package is published as `forgeos`, but generated apps keep the dependency key, CLI binary, and import surface as `forge` (`forge`, `forge/server`, `forge/react`) by using npm alias specs such as `"forge": "npm:forgeos@^0.1.0-alpha.0"`. CI uses both `--forge-spec "file:$GITHUB_WORKSPACE"` and a packed tarball smoke to prove freshly created apps can install ForgeOS and run outside the framework workspace.
+`--forge-spec` writes that dependency spec into the generated app, while `--local-forge` keeps the monorepo/local package workflow. The npm package is published as `forgeos`, but generated apps keep the dependency key, CLI binary, and import surface as `forge` (`forge`, `forge/server`, `forge/react`) by using npm alias specs such as `"forge": "npm:forgeos@alpha"`. CI uses both `--forge-spec "file:$GITHUB_WORKSPACE"` and a packed tarball smoke to prove freshly created apps can install ForgeOS and run outside the framework workspace.
 
 For broader field testing:
 
@@ -73,6 +91,35 @@ npm run field:test -- --package-managers npm --templates minimal-web --forge-spe
 
 The scheduled/manual `Field Tests` workflow expands that coverage across Linux, macOS, Windows, Node 22, Node 24, and npm/pnpm/yarn/bun.
 
+## External Runtimes And Go Adapter
+
+ForgeOS can import services written outside TypeScript through the Forge Protocol.
+External runtimes publish a `forge.manifest.json` that describes commands, queries,
+transport, policies, risk metadata, tenant scope, and schemas. Forge then emits
+the same machine-readable app/API/agent artifacts and exposes runtime bridge
+endpoints for those entries.
+
+The first adapter MVP is Go:
+
+```bash
+cd examples/go-billing
+go run . --manifest --base-url http://127.0.0.1:8787 > forge.manifest.json
+go run . --addr 127.0.0.1:8787 --base-url http://127.0.0.1:8787
+```
+
+In a Forge app:
+
+```bash
+forge manifest validate ./forge.manifest.json --json
+forge manifest import ./forge.manifest.json --json
+forge generate
+forge run billing.createInvoice --args '{"title":"Invoice"}' --user-id u1 --tenant-id tenant-a --role admin
+forge query billing.listInvoices --args '{}' --user-id u1 --tenant-id tenant-a --role admin
+```
+
+See [`docs/forge-protocol.md`](docs/forge-protocol.md), [`schemas/forge-manifest.schema.json`](schemas/forge-manifest.schema.json),
+and [`adapters/go`](adapters/go/README.md).
+
 ## What ForgeOS Generates
 
 ```txt
@@ -122,7 +169,7 @@ forge.lock
 | Auth | dev headers, JWT, OIDC discovery/JWKS verification via `jose`, production-mode guardrails |
 | RLS | Postgres RLS SQL compiler/checks for DB-enforced tenant isolation |
 | Secrets/env | secret registry, env schema, redaction, strict `process.env` checks |
-| AI | provider registry, `ctx.ai`, mock mode, telemetry without prompt/output retention by default |
+| AI | Vercel AI SDK v6 engine, provider registry, `ctx.ai`, `ctx.agent.run`, `aiTool`, `agent`, `/ai/agents/run` JSON automation, `/ai/agents/chat` UIMessage streaming, `forge ai trace`, structural and model-level redteam probes, mock mode, telemetry without prompt/output retention by default |
 | Frontend | generated client SDK, React/Next hooks, template app, liveQuery client support |
 | LiveQuery | durable invalidation log, reconnect/resume semantics, production hardening checks |
 | Self-host | compose/deploy artifacts and self-host checks |
@@ -198,6 +245,7 @@ Common command groups:
 Refactor codemods are AST-aware where safety matters most:
 
 - `forge refactor extract-action` is binding-aware and preserves unrelated imports, type-only imports, and shadowed locals.
+- `forge refactor rename command <oldName> <newName>` rewrites command declarations, generated client references, React hook usage, tests, and safe string references while preserving unrelated symbols.
 - `forge refactor rename field <table.field> <table.field>` rewrites structured TS/JS/JSX/TSX and JSON references, preserves locals, and scopes the field change to files/objects linked to the target table. For example, `tickets.priority -> tickets.urgency` does not rewrite a generic `priority` prop in a component with no `tickets` binding.
 - `forge refactor rename table <from> <to>` rewrites table definitions, `ctx.db.<table>` access, policy strings, JSON/blueprints, and import/export specifiers while preserving unrelated locals with the same name.
 
@@ -226,12 +274,23 @@ See [`examples/showcase-forge-app`](examples/showcase-forge-app/README.md).
 
 ```bash
 cd examples/showcase-forge-app
-bun install
-bun run generate
-bun run dev
+npm install
+npm run generate
+npm run dev
 ```
 
-Examples are source-only where practical: generated artifacts, `forge.lock`, package lockfiles, and operational `.forge/**` state are recreated locally. The showcase demonstrates tenant-scoped data, policies, commands, queries, liveQueries, outbox actions, workflows, mock AI, telemetry trace IDs, generated React hooks, `agentContract`, `frontendGraph`, and `capabilityMap`.
+For the reproducible public proof path:
+
+```bash
+npm run proof:inspect
+npm run proof:dev
+npm run proof:capabilities
+npm run proof:verify
+```
+
+Read [`examples/showcase-forge-app/PUBLIC_PROOF.md`](examples/showcase-forge-app/PUBLIC_PROOF.md) for the full walkthrough.
+
+Examples are source-only where practical: generated artifacts, `forge.lock`, package lockfiles, and operational `.forge/**` state are recreated locally. The showcase demonstrates tenant-scoped data, policies, commands, queries, liveQueries, outbox actions, workflows, mock AI, telemetry trace IDs, generated React hooks, `agentContract`, `frontendGraph`, `capabilityMap`, and the standard agent handoff loop.
 
 ## Platform Support
 
@@ -307,7 +366,7 @@ For the first prerelease publish, use the alpha dist-tag explicitly:
 
 ```bash
 npm run release:publish-local-alpha -- --dry-run
-npm run release:publish-local-alpha -- --yes
+npm run release:publish-alpha
 ```
 
 The normal path is:
@@ -330,7 +389,7 @@ Configure npm Trusted Publisher for package `forgeos`:
 | Environment | blank |
 | Allowed action | `npm publish` |
 
-Do not add `NPM_TOKEN` for normal releases. Alpha releases publish with the `alpha` dist-tag so prerelease builds do not become `latest` accidentally. The first manual package creation uses `release:publish-local-alpha`, which publishes from a temporary hardlink-free staging copy and disables provenance because local shells do not have a GitHub OIDC provider. The workflow uses `id-token: write`, Node 24/npm 11+, and provenance for subsequent releases. `npm run release:smoke` runs `npm pack`, creates a fresh app with the packed tarball, installs dependencies, runs `forge dev --once --json`, and verifies the app smoke path.
+Do not add `NPM_TOKEN` for normal releases. Alpha releases publish with the `alpha` dist-tag so prerelease builds do not become `latest` accidentally. Use `release:publish-local-alpha -- --dry-run` only to validate the staged tarball locally; real npm publishing should go through `release:publish-alpha`, which dispatches `publish.yml` and uses npm OIDC Trusted Publisher. The workflow checks whether the package version already exists before installing dependencies or running tests, then uses `id-token: write`, Node 24/npm 11+, and provenance for the actual publish. `npm run release:smoke` runs `npm pack`, creates a fresh app with the packed tarball, installs dependencies, runs `forge dev --once --json`, and verifies the app smoke path.
 
 ## Milestone History
 
@@ -377,11 +436,12 @@ H39  Showcase app
 H40  Windows/runtime hardening
 H41  Node-compatible CLI/runtime
 H42  Verify observability and quieter app workspaces
+H43  Native AI tools and agent loop
 ```
 
 ## Remaining Hardening Before Public Release
 
-- Keep expanding semantic codemods beyond the current AST-aware `extract-action`, `rename field`, and `rename table` paths.
+- Keep expanding semantic codemods beyond the current AST-aware `extract-action`, `rename command`, `rename field`, and `rename table` paths.
 - Reduce command-selection risk with more task routers and richer inline diagnostics.
 - Keep hardening native Windows setup beyond diagnostics and safe automatic environment fixes.
 - Keep broadening package manager CI from template smoke toward install/build smoke for pnpm and yarn apps.

package/adapters/go/README.md

@@ -0,0 +1,23 @@
+# Forge Go Adapter
+
+`adapters/go` is the minimal Go SDK for external Forge runtimes. It registers
+commands and queries, emits `forge.manifest.json`, and exposes a Forge-compatible
+HTTP handler.
+
+```go
+app := forge.New("billing", forge.BaseURL("http://127.0.0.1:8787"))
+
+app.Command("createInvoice", forge.Handle(createInvoice),
+    forge.Policy("billing.manage"),
+    forge.TenantScoped(true),
+    forge.NeedsApproval(true),
+)
+
+app.Query("listInvoices", forge.Handle(listInvoices),
+    forge.Policy("billing.manage"),
+    forge.TenantScoped(true),
+)
+```
+
+The HTTP handler accepts Forge runtime envelopes on `/commands/:name` and
+`/queries/:name`, then returns `{ "ok": true, "result": ... }` envelopes.

package/adapters/go/go.mod

@@ -0,0 +1,3 @@
+module github.com/Stahldavid/forge/adapters/go
+
+go 1.22

package/adapters/go/http.go

@@ -0,0 +1,149 @@
+package forge
+
+import (
+	"encoding/json"
+	"errors"
+	"net/http"
+	"strings"
+)
+
+func (registry *Registry) HTTPHandler() http.Handler {
+	mux := http.NewServeMux()
+	mux.HandleFunc(registry.service.Health, registry.handleHealth)
+	mux.HandleFunc("/manifest", registry.handleManifest)
+	mux.HandleFunc("/commands/", registry.handleRuntime(KindCommand, "/commands/"))
+	mux.HandleFunc("/queries/", registry.handleRuntime(KindQuery, "/queries/"))
+	return mux
+}
+
+func (registry *Registry) handleHealth(response http.ResponseWriter, request *http.Request) {
+	writeJSON(response, http.StatusOK, map[string]any{
+		"ok":      true,
+		"service": registry.service.Name,
+	})
+}
+
+func (registry *Registry) handleManifest(response http.ResponseWriter, request *http.Request) {
+	baseURL := request.URL.Query().Get("baseUrl")
+	if baseURL == "" {
+		baseURL = registry.service.BaseURL
+	}
+	writeJSON(response, http.StatusOK, registry.Manifest(baseURL))
+}
+
+func (registry *Registry) handleRuntime(kind EntryKind, prefix string) http.HandlerFunc {
+	return func(response http.ResponseWriter, request *http.Request) {
+		name := strings.TrimPrefix(request.URL.Path, prefix)
+		registered, ok := registry.lookup[lookupKey(kind, name)]
+		if !ok {
+			writeError(response, http.StatusNotFound, "", "FORGE_GO_ENTRY_NOT_FOUND", "external entry not found")
+			return
+		}
+		if request.Method != http.MethodPost && request.Method != http.MethodGet {
+			writeError(response, http.StatusMethodNotAllowed, "", "FORGE_GO_METHOD_NOT_ALLOWED", "external entry only accepts GET or POST")
+			return
+		}
+
+		envelope, err := readRequestEnvelope(request)
+		traceID := traceIDFrom(request, envelope)
+		if err != nil {
+			writeError(response, http.StatusBadRequest, traceID, "FORGE_GO_BAD_REQUEST", err.Error())
+			return
+		}
+		if envelope.Forge.Service == "" {
+			envelope.Forge.Service = registry.service.Name
+		}
+		if envelope.Forge.Entry == "" {
+			envelope.Forge.Entry = name
+		}
+		if envelope.Forge.Kind == "" {
+			envelope.Forge.Kind = string(kind)
+		}
+		if envelope.Forge.TraceID == "" {
+			envelope.Forge.TraceID = traceID
+		}
+		if envelope.Auth.Kind == "" {
+			envelope.Auth = authFromHeaders(request.Header)
+		}
+
+		call := &Context{
+			Auth:    envelope.Auth,
+			Forge:   envelope.Forge,
+			Headers: request.Header,
+		}
+		result, err := registered.handler(request.Context(), call, envelope.Args)
+		if err != nil {
+			writeError(response, http.StatusInternalServerError, envelope.Forge.TraceID, "FORGE_GO_HANDLER_FAILED", err.Error())
+			return
+		}
+		writeJSON(response, http.StatusOK, ResponseEnvelope{
+			OK:      true,
+			Result:  result,
+			TraceID: envelope.Forge.TraceID,
+		})
+	}
+}
+
+func readRequestEnvelope(request *http.Request) (RequestEnvelope, error) {
+	if request.Method == http.MethodGet {
+		args := request.URL.Query().Get("args")
+		if args == "" {
+			args = "{}"
+		}
+		return RequestEnvelope{Args: json.RawMessage(args)}, nil
+	}
+	defer request.Body.Close()
+	var envelope RequestEnvelope
+	decoder := json.NewDecoder(request.Body)
+	if err := decoder.Decode(&envelope); err != nil {
+		return envelope, err
+	}
+	if len(envelope.Args) == 0 {
+		envelope.Args = json.RawMessage("{}")
+	}
+	if !json.Valid(envelope.Args) {
+		return envelope, errors.New("request args must be valid JSON")
+	}
+	return envelope, nil
+}
+
+func authFromHeaders(headers http.Header) Auth {
+	auth := Auth{Kind: headers.Get("x-forge-auth-kind")}
+	if auth.Kind == "" {
+		auth.Kind = "anonymous"
+	}
+	auth.UserID = headers.Get("x-forge-user-id")
+	auth.TenantID = headers.Get("x-forge-tenant-id")
+	auth.Role = headers.Get("x-forge-role")
+	return auth
+}
+
+func traceIDFrom(request *http.Request, envelope RequestEnvelope) string {
+	if envelope.Forge.TraceID != "" {
+		return envelope.Forge.TraceID
+	}
+	return request.Header.Get("x-forge-trace-id")
+}
+
+func writeError(response http.ResponseWriter, status int, traceID string, code string, message string) {
+	writeJSON(response, status, ResponseEnvelope{
+		OK: false,
+		Diagnostics: []Diagnostic{{
+			Severity: "error",
+			Code:     code,
+			Message:  message,
+			Docs:     []string{"docs/forge-protocol.md"},
+		}},
+		Error: &ErrorInfo{
+			Code:    code,
+			Message: message,
+		},
+		TraceID: traceID,
+	})
+}
+
+func writeJSON(response http.ResponseWriter, status int, body any) {
+	response.Header().Set("content-type", "application/json")
+	response.WriteHeader(status)
+	_ = json.NewEncoder(response).Encode(body)
+}