phase2-migrate-from-kagent: ship azureclaw migrate from-kagent (S9.3)

[Pal Lakatos-Toth (pallakatos)]

Slice S9.3 — phase2-migrate-from-kagent

Closes §15.2 #8 of the implementation plan ("kagent migration tool").

One-shot YAML translator from a kagent.dev/v1alpha2 Agent CR
(verified directly against kagent-dev/kagent @ 90212ab go/api/v1alpha2/agent_types.go via GitHub MCP) into an AzureClaw resource bundle.

Emits

• ClawSandbox (always) — name + namespace + labels (with the deterministic azureclaw.azure.com/sandbox marker that the emitted ToolPolicies match against), BYO image direct or --image override for Declarative agents (kagent ADK runtime is not bundled), spec.sandbox.network.allowedDomains → spec.networkPolicy.allowedEndpoints, deployment-level env → spec.openclaw.extraEnv (last-literal-wins, valueFrom dropped + warned).
• InferencePolicy (only when spec.declarative.modelConfig is set) — provenance-only mapping; carries the kagent ModelConfig name as azureclaw.azure.com/kagent-model-config annotation. Inference enforcement is not migrated.
• ToolPolicy (one per (McpServer, toolName) pair) — requireApproval list maps to spec.approval.mode='always'; empty toolNames emits one wildcard ToolPolicy with a warning; type: Agent tools dropped with warning. Original TypedReference preserved as azureclaw.azure.com/kagent-tool-ref annotation; user is warned that an equivalent AzureClaw McpServer must already exist.

Hard-fail on lossy by default

Same exit-code grammar as S9.2 convert: 0 ok, 2 invalid input / wrong kind / multi-doc / collision, 4 lossy refused. --allow-lossy waives. --dry-run still applies the lossy gate.

Aspirational mappings explicitly REJECTED

Per pre-implementation rubber-duck critique (14 findings adopted, 0 deferred):

• ClawAgentIdentity — Phase 4 CRD per docs/internal/internal-boundaries.md:28; the plan line 210 mentioning it is overridden by repo reality per slice rule §0.2 security: inference requests bypass policy evaluation entirely (CRITICAL) #7.
• McpServer auto-emission — we cannot reconstruct upstream MCP endpoints from a kagent TypedReference.
• InferencePolicy enforcement from ModelConfig — separate CRD; we keep provenance only.

Output formats

• --format yaml (default) — multi-doc YAML stream, deterministic order: ClawSandbox, InferencePolicy, ToolPolicys sorted by name.
• --format json — single Kubernetes v1.List (pipes cleanly to kubectl apply -f -).
• --out-dir <dir> — splits into <kind>-<name>.yaml files; refuses to overwrite unless --force.

Tests

• 53 new vitest cases in cli/src/migrate/from_kagent.test.ts covering DNS sanitization edges, hash determinism + collision distinguishability, env projection (last-wins, valueFrom, prior-literal-purge), description truncation, every input gate, label conflict rejection, namespace mismatch warn, Declarative non-runnability + escape hatch, conditional InferencePolicy emit, ToolPolicy fan-out + approval mapping + wildcard emission + dedupe + agent-as-tool drop + headersFrom + allowedHeaders warns, all Declarative + deployment-level lossy fields, networking projection + wildcard warn, bundle ordering, BYO clean happy-path.
• CLI workspace: 382 → 435 tests (+53).
• Manual end-to-end smoke: a Declarative agent with one McpServer tool (2 toolNames, 1 requireApproval) + a network allowlist round-trips to a 4-resource bundle that exits 0 with --allow-lossy --image … and exits 4 without --allow-lossy.

CI

tsc --noEmit ✓ · oxlint ✓ (clean) · vitest 435 ✓ · ci/no-stubs.sh ✓ · ci/no-custom-crypto.sh ✓ · ci/check-loc.sh ✓.

Audit doc

docs/security-audits/2026-04-28-phase2-migrate-from-kagent.md — full 12-section template. STRIDE table (13 threats), reuse map (7 existing seams enumerated, 0 parallel-implementations), aspirational-rejection table, failure-mode matrix, CRD round-trip validation, test coverage map.

Day-1 use case

azureclaw migrate from-kagent agent.yaml --image my/runtime:v1 --allow-lossy | kubectl apply -f -

Operator running kagent declarative agents adopts AzureClaw governance by piping the bundle into kubectl apply, then hand-edits the emitted ClawSandbox to set spec.inference.{provider,endpoint,model} per their ModelConfig and creates an AzureClaw McpServer for each kagent McpServer reference.

Phase 2 progress

S1 #51 ✓ · S2 #52 ✓ · S3 #53 ✓ · S4 #54 ✓ · S5 #55 ✓ · S6 #56 ✓ · S8 #57 ✓ · S11 #59 ✓ · S11.1 #61 ✓ · S9.1 #62 ✓ · S9.2 #63 ✓ · S9.3 (this PR)

12 of ~14 slices.

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com