Merge remote-tracking branch 'upstream/main' into feat/otel-genai-semconv

Author: tdabasinskas

.gitignore

@@ -23,3 +23,8 @@ vendor
 /cagent-*
 /docker-mcp-*
 docker-agent
+
+# Generated wasm artifacts (built locally; see cmd/wasm/README.md)
+/wasm
+cmd/wasm/web/docker-agent.wasm
+cmd/wasm/web/wasm_exec.js

cmd/wasm/README.md

@@ -0,0 +1,215 @@
+# docker-agent in the browser (js/wasm)
+
+`cmd/wasm` is a `GOOS=js GOARCH=wasm` entry point that exposes a thin slice
+of docker-agent — config parsing and a single-round streaming chat — to a
+JavaScript host (a browser tab or Node).
+
+It is **not** a port of the full agent. It is a proof-of-concept for the
+"realistic plan" outlined when we surveyed which parts of docker-agent could
+even be cross-compiled to wasm. See the *Limits* section below.
+
+## Build
+
+```sh
+# Compile.
+GOOS=js GOARCH=wasm go build -o cmd/wasm/web/docker-agent.wasm ./cmd/wasm
+
+# Copy the matching wasm_exec.js shim from the Go toolchain (its API is
+# tied to the compiler version and must match the binary).
+cp "$(go env GOROOT)/lib/wasm/wasm_exec.js" cmd/wasm/web/wasm_exec.js
+```
+
+The output is a ~75 MB `.wasm`. It includes the entire YAML parser, three LLM
+provider clients (OpenAI, Anthropic, Google) and their dependencies. With
+`tinygo` or `-ldflags="-s -w"` plus `wasm-opt` you can roughly halve it; we
+have not optimised the size.
+
+## Run (Node smoke test)
+
+```sh
+node cmd/wasm/smoke_test.js
+```
+
+Prints the parsed config of a small two-agent YAML and exits 0. This proves
+that the Go runtime starts under wasm, that `globalThis.dockerAgent` gets
+registered, and that `parseConfig` returns the expected shape.
+
+## Run (browser, with OpenRouter sign-in)
+
+The demo page implements OpenRouter's [PKCE OAuth flow](https://openrouter.ai/docs/use-cases/oauth-pkce):
+
+1. Serve `cmd/wasm/web/` over HTTP (`WebAssembly.instantiateStreaming`
+   needs the `application/wasm` MIME type, so `file://` won't work):
+
+   ```sh
+   cd cmd/wasm/web && python3 -m http.server 8765
+   ```
+
+2. Open <http://localhost:8765/>.
+
+3. Click **Sign in with OpenRouter** — you'll be redirected to
+   `openrouter.ai`, log in, approve the app, and bounced back. The page
+   exchanges the `?code=` for a user-controlled API key (PKCE / S256) and
+   stores it in `localStorage`.
+
+4. Pick a free model from the dropdown (the YAML textarea updates
+   automatically) and click **Run**. Streaming completion deltas appear in
+   the output box.
+
+5. To revoke the key: click **Sign out** in the page (clears local copy)
+   and/or visit
+   <https://openrouter.ai/settings/keys> to revoke server-side.
+
+### Why this works in a browser
+
+Most LLM providers block direct browser fetches because anyone could read
+the API key out of the Network tab. OpenRouter solves this by issuing
+*per-app, per-user* keys via PKCE — the user owns the key, can revoke it,
+and the app never sees a master credential.
+
+We verified the relevant CORS posture before shipping:
+
+```
+$ curl -is -X OPTIONS https://openrouter.ai/api/v1/auth/keys \
+    -H "Origin: http://localhost:8765" \
+    -H "Access-Control-Request-Method: POST"
+HTTP/2 204
+access-control-allow-origin: *
+access-control-allow-headers: Authorization,...,Content-Type,...
+```
+
+Both `/api/v1/auth/keys` (token exchange) and `/api/v1/chat/completions`
+(inference) return `access-control-allow-origin: *` with `Authorization`
+in the allowed headers. No proxy needed.
+
+### What the YAML looks like
+
+OpenRouter exposes an OpenAI-compatible API, so it slots in as a custom
+provider:
+
+```yaml
+providers:
+  openrouter:
+    provider: openai
+    base_url: https://openrouter.ai/api/v1
+    token_key: OPENROUTER_API_KEY
+agents:
+  root:
+    model: openrouter/meta-llama/llama-3.3-70b-instruct:free
+    instruction: |
+      You are a helpful assistant ...
+```
+
+When the user clicks **Run**, the page passes the stored key as
+`env.OPENROUTER_API_KEY` to `dockerAgent.chat(...)`, the existing
+`pkg/model/provider/openai` reads it via `env.Get(ctx, cfg.TokenKey)`, and
+the Go HTTP transport (mapped to `fetch` under js/wasm) sends the
+request. **Same code path the CLI uses** — no special browser-only branch.
+
+### Bring-your-own-key fallback
+
+The `<details>` block on the page lets advanced users paste OpenAI /
+Anthropic / Gemini keys directly. Anthropic recently added
+`anthropic-dangerous-direct-browser-access` so it actually works from a
+tab; OpenAI and Gemini still block CORS for browser origins, so those
+fields are mostly there for use against a self-hosted proxy.
+
+## JavaScript API
+
+Once the wasm boots, two functions are exported on `globalThis.dockerAgent`:
+
+### `parseConfig(yamlString) -> object`
+
+Synchronous. Loads the YAML through `pkg/config.Load` (so all the version
+upgraders run) and returns a small JS-shaped projection:
+
+```js
+dockerAgent.parseConfig(`
+version: "2"
+agents:
+  root:
+    model: openai/gpt-4o-mini
+    instruction: hi
+`);
+// =>
+// {
+//   version: "2",
+//   agents: [{ name: "root", model: "openai/gpt-4o-mini", instruction: "hi", ... }],
+//   models: { "openai/gpt-4o-mini": { provider: "openai", model: "gpt-4o-mini" } }
+// }
+```
+
+Throws a JS `Error` on invalid YAML / unsupported version / failed validation.
+
+### `chat({yaml, agentName?, env?, messages}, onEvent) -> Promise`
+
+Asynchronous. Loads the config, picks the agent (or the only one), builds
+its model provider, and opens one streaming chat completion.
+
+- `yaml` — the YAML document, same as for `parseConfig`.
+- `agentName` — required if the config defines more than one agent.
+- `env` — `{ OPENAI_API_KEY: "...", ANTHROPIC_API_KEY: "...", GEMINI_API_KEY: "..." }`.
+  Whatever your model needs.
+- `messages` — array of `{role, content}` objects, OpenAI-style. The agent's
+  `instruction` is automatically prepended as a `system` message if you
+  haven't already supplied one.
+- `onEvent(ev)` — called from Go for every stream event:
+  - `{type: "delta",  content?: string, reasoning?: string}`
+  - `{type: "finish", reason: string}`
+
+Resolves to `{message: {role, content, reasoning, finish}}` once the stream
+ends. Rejects with an `Error` on any failure.
+
+## Limits
+
+These are not bugs to fix; they are direct consequences of `GOOS=js`:
+
+- **No tools, no MCP, no hooks, no sub-agent handoffs.** Anything that needs
+  `os/exec` or local file I/O is excluded from the build.
+- **No sessions.** `pkg/session` and `pkg/memory/database/sqlite` pull in
+  `modernc.org/libc` which does not have a js port. The browser caller is
+  responsible for keeping the message history.
+- **No fallbacks, no rule-based routing.** The rule-based router uses bleve,
+  which depends on `mmap` / file-locking primitives that don't exist on
+  js/wasm. A js-only `factory_js.go` swaps the full provider factory for a
+  slim variant with only openai / anthropic / google.
+- **No Docker Model Runner, no Bedrock, no Vertex AI.** Same reason —
+  `dmr` shells out, `bedrock` and `vertexai` pull in cloud SDKs that don't
+  cross-compile to wasm.
+- **No Docker Desktop integration.** `pkg/desktop` has stubs for js that
+  return empty paths and refuse to dial.
+- **CORS.** Mentioned above. Real deployment needs a proxy.
+
+## Where the cross-compilation work lives
+
+The shims that make the existing tree compile under `GOOS=js GOARCH=wasm`
+are intentionally tiny:
+
+| File | Purpose |
+| --- | --- |
+| `pkg/cache/lock_js.go` | No-op file-lock stubs (single-threaded js). |
+| `pkg/desktop/sockets_js.go` | Returns empty Docker Desktop paths. |
+| `pkg/desktop/connection_js.go` | Refuses Unix-socket / named-pipe dials. |
+| `pkg/desktop/connection_other.go` | Build tag updated to `!windows && !js`. |
+| `pkg/model/provider/factory.go` | Build tag added: `!js`. |
+| `pkg/model/provider/factory_js.go` | js-only provider dispatch (openai / anthropic / google). |
+
+Everything else compiles unchanged because docker-agent already had the
+`os/exec`, sandbox, sound, audio, server, browser, keyring code well-isolated
+behind their own packages — the wasm entry just doesn't import them.
+
+## Sanity check
+
+```sh
+# Native build still happy.
+go build ./...
+
+# Wasm build still happy.
+GOOS=js GOARCH=wasm go build -o /tmp/cagent.wasm ./cmd/wasm
+
+# Existing tests of the touched packages still pass.
+go test ./pkg/cache/... ./pkg/desktop/... ./pkg/model/provider/...
+
+# End-to-end runtime smoke test.
+node cmd/wasm/smoke_test.js
+```

cmd/wasm/bridge.go

@@ -0,0 +1,147 @@
+//go:build js && wasm
+
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"syscall/js"
+
+	"github.com/docker/docker-agent/pkg/chat"
+	"github.com/docker/docker-agent/pkg/config/latest"
+)
+
+// ---------------------------------------------------------------------------
+// JS <-> Go conversion helpers
+// ---------------------------------------------------------------------------
+
+// throwingError builds a JS object the JS-side wrapper recognises as an
+// error to re-throw. We use a sentinel field so plain return values can never
+// collide with it (real config output never includes a `__error` key).
+func throwingError(msg string) any {
+	return js.ValueOf(map[string]any{"__error": msg})
+}
+
+// jsError wraps a Go error in a JS Error so it can be passed to Promise.reject.
+func jsError(err error) js.Value {
+	return js.Global().Get("Error").New(err.Error())
+}
+
+// rejectedPromise returns a Promise that rejects immediately with msg.
+// Used when we can detect a bad call before launching a goroutine.
+func rejectedPromise(msg string) js.Value {
+	return newPromise(func(_, reject func(any)) {
+		reject(jsError(fmt.Errorf("%s", msg)))
+	})
+}
+
+// newPromise builds a JavaScript Promise whose executor is a Go function.
+// The returned js.Value is the Promise itself; resolve/reject are passed
+// to executor and may be called from any goroutine.
+func newPromise(executor func(resolve, reject func(any))) js.Value {
+	promiseCtor := js.Global().Get("Promise")
+	handler := js.FuncOf(func(_ js.Value, args []js.Value) any {
+		resolve := args[0]
+		reject := args[1]
+		executor(
+			func(v any) { resolve.Invoke(v) },
+			func(v any) { reject.Invoke(v) },
+		)
+		return nil
+	})
+	// Note: handler is a one-shot Func. The Promise executor is invoked
+	// synchronously from the constructor, so it is safe to Release the
+	// handler immediately afterwards. We don't, because the executor
+	// captures goroutines that may continue to call resolve/reject — which
+	// only invoke the captured `resolve`/`reject` js.Values, not the handler
+	// itself, so leaking the handler is OK and avoids a subtle race.
+	return promiseCtor.New(handler)
+}
+
+// emit invokes onEvent(payload) on the JS side, swallowing any error if the
+// caller passed something other than a function (or nothing at all).
+func emit(onEvent js.Value, payload any) {
+	if onEvent.Type() != js.TypeFunction {
+		return
+	}
+	onEvent.Invoke(js.ValueOf(payload))
+}
+
+// jsObjectToStringMap converts a flat JS object {k: "v", ...} into a Go
+// map[string]string. Non-string values are stringified via Object.toString.
+// A null/undefined input yields a nil map.
+func jsObjectToStringMap(v js.Value) map[string]string {
+	if v.Type() != js.TypeObject {
+		return nil
+	}
+	keys := js.Global().Get("Object").Call("keys", v)
+	out := make(map[string]string, keys.Length())
+	for i := 0; i < keys.Length(); i++ {
+		k := keys.Index(i).String()
+		val := v.Get(k)
+		if val.Type() == js.TypeString {
+			out[k] = val.String()
+		} else {
+			out[k] = val.Call("toString").String()
+		}
+	}
+	return out
+}
+
+// jsToMessages decodes a JS array of {role, content} objects into a slice of
+// chat.Message. We round-trip through JSON so any extra fields the JS side
+// supplies (e.g. tool_calls in a future iteration) flow through naturally.
+func jsToMessages(v js.Value) ([]chat.Message, error) {
+	if v.Type() != js.TypeObject {
+		return nil, fmt.Errorf("messages must be an array")
+	}
+	jsonStr := js.Global().Get("JSON").Call("stringify", v).String()
+	var msgs []chat.Message
+	if err := json.Unmarshal([]byte(jsonStr), &msgs); err != nil {
+		return nil, fmt.Errorf("decoding messages: %w", err)
+	}
+	return msgs, nil
+}
+
+// configToMap reduces a fully-parsed *latest.Config to the small JS-friendly
+// shape returned by parseConfig. We deliberately omit fields that wouldn't
+// mean anything in the browser (toolsets, hooks, sandbox).
+func configToMap(cfg *latest.Config) map[string]any {
+	agents := make([]any, 0, len(cfg.Agents))
+	for _, a := range cfg.Agents {
+		agents = append(agents, map[string]any{
+			"name":         a.Name,
+			"description":  a.Description,
+			"model":        a.Model,
+			"instruction":  a.Instruction,
+			"sub_agents":   stringsToAny(a.SubAgents),
+			"handoffs":     stringsToAny(a.Handoffs),
+			"add_date":     a.AddDate,
+			"add_env_info": a.AddEnvironmentInfo,
+		})
+	}
+
+	models := map[string]any{}
+	for k, m := range cfg.Models {
+		models[k] = map[string]any{
+			"provider": m.Provider,
+			"model":    m.Model,
+			"base_url": m.BaseURL,
+		}
+	}
+
+	return map[string]any{
+		"version": cfg.Version,
+		"agents":  agents,
+		"models":  models,
+	}
+}
+
+// stringsToAny widens a []string to []any so syscall/js.ValueOf accepts it.
+func stringsToAny(in []string) []any {
+	out := make([]any, len(in))
+	for i, s := range in {
+		out[i] = s
+	}
+	return out
+}