@a5c-ai/krate 5.0.1-staging.f672fe79b

package/docs/agents/api-contract-spec.md

@@ -0,0 +1,309 @@
+# Agent API contract spec
+
+## Purpose
+
+This document defines future HTTP contracts for agent orchestration while preserving the current Krate API shape:
+
+- `GET /api/controller` returns the `createControllerUiModel()` snapshot.
+- `GET/POST /api/controller/resources` lists and applies arbitrary Krate resources.
+- `GET/DELETE /api/controller/resources/[kind]/[name]` reads and deletes resources.
+- `GET /api/watch/orgs/[org]/[[...resource]]` streams Krate live events as SSE.
+
+Typed agent APIs should delegate to the same controller/resource gateway and never bypass resource admission.
+
+## Response conventions
+
+Successful resource response:
+
+```json
+{
+  "kind": "AgentStack",
+  "metadata": { "name": "claude-code-ci-repair" },
+  "spec": {},
+  "status": { "phase": "Ready", "conditions": [] }
+}
+```
+
+Error response:
+
+```json
+{
+  "error": {
+    "code": "POLICY_DENIED",
+    "message": "Secret grant is missing for github-commenter.",
+    "correlationId": "krate-...",
+    "resource": "AgentStack/krate-system/claude-code-ci-repair",
+    "reasons": [
+      {
+        "code": "MissingSecretGrant",
+        "field": "spec.permissionRefs.secretGrants",
+        "message": "Secret krate-secrets/github-writeback:token is required."
+      }
+    ]
+  }
+}
+```
+
+Recommended status codes:
+
+| Code | Use |
+| --- | --- |
+| `200` | read/action completed |
+| `201` | resource created |
+| `202` | async action accepted |
+| `400` | invalid request body or field |
+| `401` | unauthenticated |
+| `403` | RBAC/policy/admission denied |
+| `404` | resource not found |
+| `409` | generation conflict, dedupe conflict, active run conflict |
+| `422` | valid JSON but invalid resource spec |
+| `429` | concurrency/rate limit |
+| `503` | controller/gateway unavailable |
+
+## Resource CRUD
+
+These can initially use the existing generic API:
+
+- `GET /api/controller/resources?kind=AgentStack`
+- `POST /api/controller/resources`
+- `GET /api/controller/resources/AgentStack/claude-code-ci-repair`
+- `DELETE /api/controller/resources/AgentStack/claude-code-ci-repair`
+
+Typed routes can wrap the generic API for better UX and validation:
+
+- `GET /api/agents/stacks`
+- `POST /api/agents/stacks`
+- `GET /api/agents/stacks/:name`
+- `PATCH /api/agents/stacks/:name`
+- `DELETE /api/agents/stacks/:name`
+
+## Permission review
+
+`POST /api/agents/permissions/review`
+
+Request:
+
+```json
+{
+  "repository": "krate",
+  "ref": "refs/pull/42/head",
+  "actor": "tmusk",
+  "agentStack": "claude-code-ci-repair",
+  "triggerSource": "pull-request-comment",
+  "taskKind": "ci-repair",
+  "runnerPool": "untrusted-linux"
+}
+```
+
+Response:
+
+```json
+{
+  "decision": "denied",
+  "runtimeIdentity": { "serviceAccountRef": "agent-claude-code-ci-repair", "ready": true },
+  "runnerIdentity": { "runnerPool": "untrusted-linux", "serviceAccountRef": "runner-untrusted-linux", "ready": true },
+  "requiredRoles": [],
+  "requiredSecrets": [],
+  "requiredConfigs": [],
+  "missingGrants": [],
+  "approvalRequirements": [],
+  "yamlPreview": [],
+  "reasons": []
+}
+```
+
+The UI should call this endpoint for stack save, trigger dry-run, manual dispatch, and grant wizards.
+
+## Manual dispatch
+
+`POST /api/agents/runs`
+
+Request:
+
+```json
+{
+  "repository": "krate",
+  "ref": "refs/heads/staging",
+  "agentStack": "claude-code-ci-repair",
+  "taskKind": "manual-repair",
+  "prompt": "Investigate the failing docs validation.",
+  "contextLabels": ["ci-failure-summary"],
+  "runtimeIdentity": { "serviceAccountRef": "agent-claude-code-ci-repair" },
+  "sourceRefs": { "path": "docs/agents", "actor": "tmusk" },
+  "workspacePolicy": { "mode": "isolated-worktree" },
+  "writeBackPolicy": { "requireApproval": true }
+}
+```
+
+Response:
+
+```json
+{
+  "run": { "kind": "AgentDispatchRun", "metadata": { "name": "adr-01hx" }, "status": { "phase": "queued" } },
+  "attempt": { "kind": "AgentDispatchAttempt", "metadata": { "name": "ada-01hx-1" } },
+  "links": { "detail": "/agents/runs/adr-01hx" }
+}
+```
+
+## Dispatch actions
+
+- `POST /api/agents/runs/:run/cancel`
+- `POST /api/agents/runs/:run/retry`
+- `POST /api/agents/runs/:run/resume`
+- `POST /api/agents/runs/:run/fork`
+- `POST /api/agents/runs/:run/continue`
+
+Action request:
+
+```json
+{
+  "reason": "user-requested",
+  "message": "Continue with the focused test failure only.",
+  "expectedGeneration": 12
+}
+```
+
+Action response:
+
+```json
+{
+  "accepted": true,
+  "run": "adr-01hx",
+  "attempt": "ada-01hx-2",
+  "phase": "queued"
+}
+```
+
+## Approvals
+
+- `GET /api/agents/approvals`
+- `POST /api/agents/approvals/:approval/decision`
+
+Decision request:
+
+```json
+{
+  "decision": "approved",
+  "comment": "Post the diagnosis only; do not push the patch.",
+  "approvedActionSubset": ["pull-request-comment"],
+  "expectedArtifactDigest": "sha256:..."
+}
+```
+
+Decision response:
+
+```json
+{
+  "approval": "approval-01hx",
+  "phase": "approved",
+  "writeBack": { "accepted": true, "idempotencyKey": "approval-01hx:sha256:..." }
+}
+```
+
+## Trigger rules
+
+- `GET /api/agents/rules`
+- `POST /api/agents/rules`
+- `POST /api/agents/rules/:rule/dry-run`
+- `POST /api/agents/rules/:rule/lifecycle`
+- `POST /api/agents/rules/:rule/replay-delivery`
+
+Dry-run response must include matcher result, rendered prompt preview, context bundle plan, permission review, dedupe key, and expected actions.
+
+## Secret/config grants
+
+- `GET /api/agents/secrets`
+- `GET /api/agents/configmaps`
+- `POST /api/agents/secrets/grants`
+- `POST /api/agents/config/grants`
+- `GET /api/agents/capability-requirements`
+
+Grant APIs should only expose Secret metadata and key names, never values.
+
+## Watch/SSE contracts
+
+Current route:
+
+- `GET /api/watch/orgs/[org]/agentdispatchruns`
+- `GET /api/watch/orgs/[org]/agentapprovals`
+- `GET /api/watch/orgs/[org]/agentworkspaces`
+- `GET /api/watch/orgs/[org]/agenttriggerrules`
+
+SSE events should preserve the current `event: krate` style and include resource path and event payload. Typed agent pages may wrap this with a client helper, but the server path should remain Kubernetes-watch aligned.
+
+## UI model additions
+
+`GET /api/controller` should eventually include:
+
+```json
+{
+  "views": {
+    "agents": {
+      "activeRuns": [],
+      "pendingApprovals": [],
+      "stackReadiness": [],
+      "missingPermissions": [],
+      "repositoryAffordances": {}
+    }
+  }
+}
+```
+
+This lets existing server components continue using `fetchControllerUiModel()` while typed agent routes are added incrementally.
+
+## Memory API contracts
+
+Typed routes should preserve the generic controller API while adding focused memory actions:
+
+| Endpoint | Method | Purpose |
+| --- | --- | --- |
+| `/api/agents/memory/orgs/[org]/repositories` | `GET` | list visible `AgentMemoryRepository` resources and health. |
+| `/api/agents/memory/query` | `POST` | run admitted graph/frontmatter/grep query and create `AgentMemoryQuery`. |
+| `/api/agents/memory/resolve-ref` | `POST` | resolve branch, tag, SHA, snapshot tag, or `refAt` timestamp to commit. |
+| `/api/agents/memory/snapshots` | `POST` | create `AgentMemorySnapshot` for a dispatch context. |
+| `/api/agents/memory/diff` | `POST` | diff two memory refs or snapshots. |
+| `/api/agents/memory/updates` | `POST` | create proposed `AgentMemoryUpdate` from agent artifact or UI edit. |
+| `/api/agents/memory/updates/[id]/approve` | `POST` | approve an update. |
+| `/api/agents/memory/updates/[id]/merge` | `POST` | merge an approved update after validation. |
+| `/api/agents/memory/ontology/validate` | `POST` | validate ontology, graph YAML, frontmatter, and generated indexes. |
+
+All responses must include permission-review status, selected commit, digests, and redaction/truncation summaries when content is returned.
+
+## Org-scoped memory API requirements
+
+Memory APIs must be org-addressed or receive an explicit org in the request body. Preferred routes:
+
+| Endpoint | Method | Purpose |
+| --- | --- | --- |
+| `/api/orgs/[org]/agents/memory/import-babysitter-run` | `POST` | import curated `MEMORY.md`, session, journal, task, and artifact metadata into org memory. |
+| `/api/orgs/[org]/agents/memory/query` | `POST` | query memory within org scope. |
+| `/api/orgs/[org]/agents/memory/resolve-ref` | `POST` | resolve current, explicit, snapshot, or timestamp refs for org memory. |
+
+The server must reject requests where repository, deployment, memory repository, ServiceAccount, Secret, ConfigMap, session, or run belongs to a different org namespace.
+
+## Org route compatibility rules
+
+- New API surfaces should be org-addressed first.
+- Compatibility endpoints must resolve org before permission review and must fail if a repository, run, session, deployment, or memory source is ambiguous.
+- Watch endpoints should accept org filters and must not stream cross-org records without explicit admin scope.
+- Error bodies for org mismatch should identify the denied reference type, not leak private resource names from another org.
+
+## Org-scoped error contract
+
+Org-aware APIs should use stable errors:
+
+| Code | Meaning |
+| --- | --- |
+| `ORG_REQUIRED` | request did not include resolvable org context. |
+| `ORG_NOT_FOUND` | actor cannot see the requested org or it does not exist. |
+| `ORG_REQUIRED` | org-scoped route was missing an organization. |
+| `ORG_NAMESPACE_MISMATCH` | resource namespace does not match org binding. |
+| `CROSS_ORG_REF_DENIED` | referenced resource belongs to another org and no sharing policy applies. |
+| `MEMORY_IMPORT_REDACTION_BLOCKED` | import redaction was too broad or unsafe. |
+| `MEMORY_IMPORT_VALIDATION_FAILED` | normalized memory failed ontology/frontmatter/path validation. |
+
+Error responses must avoid leaking private names from other orgs. They can include the denied reference kind and policy reason.
+
+## Payload example reference
+
+Concrete JSON payloads for the org memory vertical slice are defined in [Org memory API payload examples](./org-memory-api-payload-examples.md). API implementation and tests should treat those examples as canonical fixtures for field names, digest fields, links, and stable error shapes.

package/docs/agents/artifacts-writeback-spec.md

@@ -0,0 +1,145 @@
+# Agent artifacts and write-back spec
+
+## Purpose
+
+Agents produce diagnoses, patches, review comments, reports, test results, and release recommendations. Krate must treat these as durable artifacts with explicit approval and write-back paths, not opaque chat text.
+
+## Artifact resources
+
+| Artifact kind | Resource | Typical source | Write-back target |
+| --- | --- | --- | --- |
+| diagnosis | `AgentArtifact` | CI/run analysis | PR/issue comment |
+| patch | `AgentArtifact` | repair agent | branch push or PR update |
+| review | `AgentReviewArtifact` | reviewer agent | PR review/comments |
+| test report | `AgentArtifact` | validation subagent | pipeline/job summary |
+| release report | `AgentArtifact` | release-check agent | release approval item |
+| subagent output | `AgentArtifact` | child agent | parent run summary |
+| workspace diff | `AgentArtifact` | workspace controller | review/apply flow |
+
+## Artifact metadata
+
+Required fields:
+
+- dispatch run and attempt;
+- producing agent/subagent;
+- kind;
+- digest;
+- object storage ref or inline safe summary;
+- source context digest;
+- permission snapshot digest;
+- target object refs;
+- validation status;
+- retention policy;
+- redaction status.
+
+## Patch artifacts
+
+Patch artifacts should include:
+
+- base ref/SHA;
+- target branch/workspace;
+- file list;
+- diff digest;
+- generated patch object ref;
+- test evidence;
+- conflicts/rebase status;
+- unsafe file warnings;
+- apply strategy: comment-only, branch update, PR update, local workspace only.
+
+Patch artifacts never push themselves. They create write-back requests.
+
+## Review artifacts
+
+`AgentReviewArtifact` should support:
+
+- review decision: pending, approved, changes-requested, comment-only;
+- inline comments with file/line anchors;
+- summary comment;
+- risk checklist;
+- confidence score;
+- target PR/check refs;
+- provider integration status;
+- approval state before submission.
+
+## Write-back actions
+
+Supported actions:
+
+- issue comment;
+- PR comment;
+- PR review submission;
+- branch push;
+- create branch;
+- open PR;
+- check rerun;
+- workflow rerun;
+- release note/report;
+- deployment/release approval request.
+
+Every write-back action must have:
+
+- explicit target;
+- artifact digest;
+- actor/approver;
+- idempotency key;
+- policy decision;
+- audit event;
+- rollback/repair note where possible.
+
+## Approval model
+
+Write-back may be:
+
+- denied by policy;
+- allowed automatically by narrow repository policy;
+- require approval always;
+- require approval only for untrusted refs;
+- require approval based on action class.
+
+Approval UI must show:
+
+- artifact preview;
+- target object;
+- exact mutation;
+- actor and agent;
+- context/permission digests;
+- risk warnings;
+- allow subset controls where applicable.
+
+## Idempotency
+
+Idempotency key format:
+
+```text
+<approval-uid>:<action-type>:<target-kind>:<target-name>:<artifact-digest>
+```
+
+Repeated apply with same key must not duplicate comments, pushes, reviews, or reruns.
+
+## UI surfaces
+
+- Run detail: artifacts tab/list with approval/write-back controls.
+- PR page: review artifacts, patch proposals, comments, check reruns.
+- Issue page: diagnosis/report artifacts and linked dispatches.
+- Runs page: diagnosis/test report artifacts beside failed jobs.
+- Inbox: pending write-back approvals.
+- Workspace page: workspace diff and patch artifacts.
+
+## Failure modes
+
+| Failure | Behavior |
+| --- | --- |
+| artifact digest mismatch | reject approval/write-back |
+| target PR changed | require rebase/refresh before write-back |
+| branch push rejected | keep artifact, mark write-back failed, suggest rebase |
+| review comment anchor stale | show stale anchor and allow comment-only fallback |
+| check rerun denied | mark approval applied=false with RBAC reason |
+| artifact contains suspected secret | block write-back until redaction/remediation |
+
+## Acceptance criteria
+
+- Agent output becomes durable artifacts, not just transcript text.
+- Privileged write-back is gated by approval/policy.
+- Artifact digest is checked before write-back.
+- Duplicate approvals do not duplicate side effects.
+- PR/issue/pipeline pages show related artifacts in context.

package/docs/agents/chart-packaging-spec.md

@@ -0,0 +1,128 @@
+# Agent chart and packaging spec
+
+## Purpose
+
+This document defines how the agent orchestration docs should map into the Helm chart and package surfaces. It is grounded in the current chart:
+
+- CRDs live under `charts/krate/crds/`.
+- Deployments, services, RBAC, ServiceAccount, NetworkPolicy, and auth Secret templates live under `charts/krate/templates/`.
+- `charts/krate/values.yaml` already contains `externalDependencies`, `auth`, `apiService`, `rbac`, `serviceAccount`, `networkPolicy`, `arc`, `kyverno`, and `gatekeeper` blocks.
+- `scripts/validate-package.mjs` checks required files, CRDs, values terms, and npm package contents.
+
+## Chart values to add
+
+```yaml
+agents:
+  enabled: false
+  agentMux:
+    enabled: false
+    gatewayUrl: ""
+    existingSecret: ""
+    streamTimeoutSeconds: 300
+  defaults:
+    runnerPool: untrusted-linux
+    runtimeServiceAccount: ""
+    workspacePolicy: isolated-worktree-default
+    approvalMode: prompt
+  retention:
+    dispatchRunsDays: 90
+    transcriptsDays: 30
+    contextBundlesDays: 30
+    artifactsDays: 180
+    auditDays: 365
+  permissions:
+    manageNativeRbac: true
+    allowClusterRoleBindings: false
+    requireBindEscalateReview: true
+  secrets:
+    enableGrantManagement: true
+    allowUiSecretCreation: true
+    showConfigMapValues: false
+  featureGates:
+    triggerRules: false
+    manualDispatch: false
+    workspaceLifecycle: false
+    writeBackApprovals: false
+    subagentTelemetry: false
+```
+
+These should be off by default until controllers exist.
+
+## CRD packaging
+
+Add CRDs in a dedicated file such as `charts/krate/crds/agent-resources.yaml` or split by domain:
+
+- `agent-config-resources.yaml`
+- `agent-execution-resources.yaml`
+- `agent-rbac-grant-resources.yaml`
+
+Required CRD groups:
+
+- stack/tool/MCP/skill/subagent/context/workspace policy;
+- trigger rules;
+- ServiceAccount/RoleBinding/SecretGrant/ConfigGrant;
+- dispatch/run/attempt/session/workspace/approval/artifact projections if CRD-backed for MVP.
+
+If execution resources are served by the aggregated API only, the chart must still install APIService/openapi surfaces and examples; do not create etcd-backed high-cardinality CRDs by accident.
+
+## Template changes
+
+### ServiceAccount and RBAC
+
+Current chart has `templates/serviceaccount.yaml` and `templates/rbac.yaml`. Agent implementation should extend them to include:
+
+- controller permissions for agent config resources;
+- read/watch permissions for native ServiceAccounts/Roles/RoleBindings where enabled;
+- Secret/ConfigMap metadata access only where grants are enabled;
+- no blanket Secret read for the web pod;
+- separate controller role from web role if agents need broader reconciliation permissions.
+
+### Deployments
+
+Current deployments already set auth-related env vars. Agent additions should include:
+
+- `KRATE_AGENTS_ENABLED`;
+- `KRATE_AGENT_MUX_GATEWAY_URL`;
+- `KRATE_AGENT_DEFAULT_RUNNER_POOL`;
+- `KRATE_AGENT_DEFAULT_SERVICE_ACCOUNT`;
+- retention env vars;
+- feature gate env vars;
+- secret/config grant management flags.
+
+### NetworkPolicy
+
+Agent Mux gateway and MCP traffic should be explicit egress rules, not broad outbound allow. The UI should surface when network policy blocks an MCP server or Agent Mux gateway.
+
+### Secrets
+
+Agent Mux gateway credentials should use `existingSecret` by default. The chart must not render provider secrets from plaintext values except for local-dev/demo modes.
+
+## Examples
+
+Add examples later under `examples/agents/`:
+
+- `agent-stack-claude-code.yaml`;
+- `agent-rbac-grants.yaml`;
+- `agent-trigger-ci-repair.yaml`;
+- `agent-manual-dispatch.yaml`;
+- `agent-permission-review-denied.yaml`.
+
+Package validation should eventually require at least one agent stack example and one SecretGrant/ConfigGrant example.
+
+## Validation updates
+
+When implementation starts, update `scripts/validate-package.mjs` to check:
+
+- agent CRD file exists;
+- required agent CRD kinds are included;
+- values include `agents`, `agentMux`, `retention`, `permissions`, `secrets`, `featureGates`;
+- npm pack includes new docs and examples;
+- chart templates do not give web pods broad Secret read;
+- chart templates consume new values.
+
+## Release safety
+
+- Agent features should be disabled by default until a vertical slice is implemented.
+- Installing the chart with `agents.enabled=false` should behave exactly as today.
+- Enabling agents without Agent Mux gateway configured should show degraded readiness, not crash the whole app.
+- Missing RBAC permissions should disable agent actions but keep repository browsing available.