@a5c-ai/krate 5.0.1-staging.f672fe79b

package/docs/agents/mvp-vertical-slice-spec.md

@@ -0,0 +1,146 @@
+# Agent MVP vertical slice spec
+
+## Purpose
+
+This document defines the smallest coherent implementation that proves Krate agent orchestration without attempting every spec at once. It should be the first code implementation target after the docs-only phase.
+
+## MVP goal
+
+A repository admin can define one read-only/diagnostic agent stack, review its Kubernetes-native permissions, manually dispatch it from a repository Code or Runs page, and see a CI-like `AgentDispatchRun` with context preview, permission snapshot, Agent Mux session binding when configured, and no write-back unless explicitly approved in a later slice.
+
+## Included user flow
+
+1. Admin creates minimal agent resources:
+   - `AgentServiceAccount`;
+   - `AgentRoleBinding` using read-only role template;
+   - `AgentToolProfile` with read-only filesystem and no broad network;
+   - optional `AgentMcpServer` if Agent Mux capability lookup requires it;
+   - `AgentStack` for diagnostic/readonly work.
+2. Admin runs permission review and sees `Ready=True` or exact blockers.
+3. User opens `/orgs/[org]/repositories/[repo]/code` or `/orgs/[org]/repositories/[repo]/runs`.
+4. User opens dispatch composer.
+5. Krate assembles `AgentContextBundle` preview and permission review.
+6. User confirms dispatch.
+7. Krate creates `AgentDispatchRun` and `AgentDispatchAttempt` before Agent Mux launch.
+8. Run appears in `/agents/runs` and repository Runs page.
+9. If Agent Mux is configured, Krate launches and binds session/run IDs.
+10. Run detail shows queued/running/completed/failed state, context digest, permission snapshot, event timeline, and linked session placeholder or chat panel.
+
+## Included resources
+
+Configuration:
+
+- `AgentStack`;
+- `AgentToolProfile`;
+- `AgentServiceAccount`;
+- `AgentRoleBinding`;
+- `AgentSecretGrant` only for model provider token if required by deployment mode;
+- `AgentConfigGrant` only if the selected tool/adapter needs non-secret config.
+
+Execution:
+
+- `AgentContextBundle`;
+- `AgentDispatchRun`;
+- `AgentDispatchAttempt`;
+- `AgentCapabilityRequirement`;
+- optional `AgentSession` projection if Agent Mux binds successfully;
+- optional `AgentArtifact` for diagnosis summary.
+
+## Included routes
+
+Global:
+
+- `/agents` overview;
+- `/agents/stacks` minimal stack list/builder;
+- `/agents/runs` dispatch list;
+- `/agents/runs/[run]` run detail;
+- `/agents/permissions` permission review panel.
+
+Repository:
+
+- `/orgs/[org]/repositories/[repo]/code` dispatch entry point;
+- `/orgs/[org]/repositories/[repo]/runs` agent run rows beside pipeline/job rows;
+- `/orgs/[org]/repositories/[repo]/settings/agents` minimal settings panel if sub-routes are available, otherwise embed in existing settings page.
+
+API:
+
+- generic resource API remains supported;
+- `POST /api/agents/permissions/review`;
+- `POST /api/agents/runs`;
+- `GET /api/agents/runs`;
+- `GET /api/agents/runs/:run`;
+- `GET /api/agents/runs/:run/events` or watch equivalent.
+
+## Explicitly deferred
+
+- automatic trigger rules;
+- issue/PR mention dispatch;
+- write-back approvals and branch pushes;
+- full Secret/ConfigMap grant wizard;
+- subagent execution;
+- workspace provisioning/rebase lifecycle;
+- artifact write-back;
+- retention jobs;
+- full observability dashboards;
+- broad chart feature gates beyond safe defaults;
+- production MCP server management.
+
+## MVP acceptance criteria
+
+### Resource model
+
+- Agent MVP kinds are in `src/resource-model.js` and `src/kubernetes-controller.js`.
+- Generic `/api/controller/resources?kind=AgentStack` can list stacks.
+- Agent resources render in advanced resource tables without custom UI hacks.
+
+### Permission review
+
+- Missing ServiceAccount blocks stack readiness.
+- Missing role binding blocks stack readiness.
+- Missing required Secret grant blocks stack readiness.
+- Permission review response includes no Secret values.
+
+### Manual dispatch
+
+- Dispatch creates run and attempt before Agent Mux launch.
+- Context bundle digest is attached to the attempt.
+- Permission snapshot digest is attached to the attempt.
+- Denied dispatch returns actionable policy/RBAC/grant reason.
+
+### UI
+
+- Code page shows dispatch entry point and disabled/missing-permission states.
+- Runs page shows agent dispatch rows beside pipeline rows.
+- Run detail shows source breadcrumbs, status, context, permission, and Agent Mux binding state.
+- Empty states are server-projected through controller UI model.
+
+### Agent Mux
+
+- If gateway is unavailable, run remains failed/degraded with clear condition and Krate stays usable.
+- If gateway is configured, run/session IDs are stored exactly once.
+- Unsupported actions are disabled based on capability snapshot.
+
+## MVP tests
+
+Required minimum tests:
+
+- resource schema test for `AgentStack` and `AgentDispatchRun`;
+- permission review missing grant test;
+- manual dispatch creates run/attempt/context test;
+- Agent Mux unavailable fallback test;
+- UI validation for Code dispatch entry and run detail empty/pending states;
+- package validation for CRDs/examples.
+
+## MVP non-negotiables
+
+- No Secret values in browser, status, logs, prompt preview, or audit.
+- No automatic writes to PRs, branches, checks, issues, or releases.
+- No untrusted fork privileged ServiceAccount or Secret access.
+- No UI-only permission checks for enabled actions.
+- No Agent Mux state as source of truth for Krate repository resources.
+
+## Org memory MVP slice
+
+The org memory MVP is described in [Org memory vertical slice spec](./org-memory-vertical-slice-spec.md). It should be treated as the first coherent agent-memory build target: one org, one repository, one company brain repo, one manual dispatch with memory snapshot, and one summary-only run-memory import.
+
+This slice is intentionally narrower than full agent orchestration. It excludes raw `.a5c` artifact retention, broad automation triggers, vector search, cross-org sharing, and advanced subagent orchestration.

package/docs/agents/observability-audit-spec.md

@@ -0,0 +1,265 @@
+# Agent observability and audit spec
+
+## Purpose
+
+Agent runs should be observable like CI runs and auditable like privileged control-plane actions. This document defines metrics, events, logs, traces, audit records, and UI projections for agent orchestration.
+
+It is grounded in current Krate behavior: `src/controller-ui.js` already exposes metrics, events, validation checks, and empty `auditLog`, while `/api/watch/orgs/[org]/*` streams live Kubernetes watch events into UI panels.
+
+## Observability principles
+
+- Every run is traceable from source event to trigger execution to dispatch run to Agent Mux session to artifacts/write-back.
+- Every privileged decision has an audit event.
+- User-facing run pages should explain queueing, execution, approvals, and failures without requiring raw logs first.
+- Metrics should be repository-, stack-, runner-, and trigger-scoped.
+- Secret values are never logged; Secret/ConfigMap metadata can be logged only by name/key/purpose/digest.
+
+## Correlation IDs
+
+Every agent operation should carry:
+
+- `correlationId`: request/session-wide trace.
+- `sourceEventUid`: webhook/CI/comment/label/manual source.
+- `triggerExecutionUid`.
+- `dispatchRunUid`.
+- `attemptUid`.
+- `agentMuxRunId`.
+- `agentMuxSessionId`.
+- `contextBundleDigest`.
+- `permissionSnapshotDigest`.
+- `artifactDigest` where applicable.
+
+These IDs should appear in events, logs, audit records, and UI details.
+
+## Event taxonomy
+
+| Event | Producer | UI surface |
+| --- | --- | --- |
+| `AgentTriggerMatched` | trigger controller | rules, source page, run detail |
+| `AgentTriggerCoalesced` | trigger controller | rules, source page |
+| `AgentTriggerRejected` | trigger controller | rules, denied dispatch panel |
+| `AgentContextAssembled` | context bundle controller | dispatch composer, run detail |
+| `AgentPermissionReviewCompleted` | permission review | stack builder, run detail, audit |
+| `AgentDispatchQueued` | dispatch controller | run list, pipeline page |
+| `AgentRunnerAssigned` | dispatch controller | run detail |
+| `AgentMuxLaunchRequested` | dispatch controller | run detail |
+| `AgentMuxSessionBound` | Agent Mux client | run/session page |
+| `AgentToolCallStarted` | Agent Mux event projection | observability timeline |
+| `AgentToolCallApprovalRequested` | Agent Mux/client | approval inbox, run detail |
+| `AgentSubagentStarted` | Agent Mux event projection | subagent tree |
+| `AgentArtifactProduced` | dispatch controller | run detail, PR/issue page |
+| `AgentWriteBackRequested` | approval/write-back controller | approval inbox |
+| `AgentWriteBackApplied` | approval/write-back controller | run detail, source page |
+| `AgentDispatchCompleted` | dispatch controller | run list, source page |
+| `AgentDispatchFailed` | dispatch controller | run detail, source page |
+
+## Metrics
+
+### Global metrics
+
+- active dispatches;
+- queued dispatches;
+- pending approvals;
+- running Agent Mux sessions;
+- failed dispatches by reason;
+- average queue wait;
+- average run duration;
+- approval wait duration;
+- token/cost estimates by stack/provider;
+- trigger coalescing/rejection rates;
+- missing permission warning counts.
+
+### Repository metrics
+
+- dispatches per repository/ref/PR/issue;
+- failed CI repair attempts;
+- write-back approvals/applied actions;
+- workspace recoveries/rebase conflicts;
+- top failing trigger rules;
+- secrets/config grants used by active stacks.
+
+### Runner metrics
+
+- queue depth by runner pool;
+- wait latency p50/p95;
+- active attempts;
+- trusted vs untrusted usage;
+- runner ServiceAccount denials;
+- cost by pool/repository.
+
+### Agent Mux metrics
+
+- launch latency;
+- session bind latency;
+- stream reconnect count;
+- tool call count/duration;
+- subagent count/duration;
+- adapter rejection count;
+- transcript/event bytes.
+
+## Audit records
+
+Audit records should be append-only and queryable by repository, user, stack, trigger, dispatch, and target object.
+
+Required audit event classes:
+
+- permission/grant changes;
+- role/service-account changes;
+- stack save and readiness changes;
+- trigger lifecycle changes;
+- dispatch creation and cancellation;
+- context refresh;
+- approval decisions;
+- write-back actions;
+- secret/config rotation impact;
+- native RBAC drift;
+- policy bypass or denial.
+
+Audit record required fields:
+
+```yaml
+type: AgentApprovalDecision
+actor:
+  kind: User
+  name: tmusk
+  kubernetesUser: tmusk@example.com
+source:
+  repository: krate
+  dispatchRun: adr-01hx
+  attempt: ada-01hx-1
+target:
+  kind: PullRequest
+  name: krate/42
+decision:
+  allowed: true
+  reason: ApprovedByMaintainer
+digests:
+  contextBundle: sha256:...
+  permissionSnapshot: sha256:...
+  artifact: sha256:...
+metadata:
+  correlationId: krate-...
+  agentMuxRunId: run_01hx
+  agentMuxSessionId: ses_01hx
+```
+
+## Logs
+
+Controller logs should be structured and include:
+
+- controller name;
+- reconciliation key;
+- correlation ID;
+- resource kind/name;
+- phase/condition changes;
+- external call target without secrets;
+- duration and result.
+
+Do not log:
+
+- Secret values;
+- raw authorization headers;
+- full prompt when it may contain sensitive context;
+- full transcript unless explicitly configured for a safe environment.
+
+## Traces
+
+Trace spans should cover:
+
+- API request;
+- permission review;
+- context assembly;
+- trigger evaluation;
+- dispatch creation;
+- runner placement;
+- Agent Mux launch;
+- event stream reconciliation;
+- artifact persistence;
+- approval/write-back.
+
+## UI projections
+
+`src/controller-ui.js` should eventually expose:
+
+```json
+{
+  "metrics": {
+    "agentDispatches": 12,
+    "agentApprovals": 3,
+    "agentMissingPermissions": 2
+  },
+  "auditLog": [],
+  "views": {
+    "agents": {
+      "activeRuns": [],
+      "pendingApprovals": [],
+      "recentFailures": [],
+      "missingPermissions": []
+    }
+  }
+}
+```
+
+Run detail must show:
+
+- event timeline;
+- transcript/session state;
+- queue and runner timings;
+- permission snapshot;
+- context digest;
+- artifacts and approvals;
+- audit trail for write-back.
+
+## Alerts
+
+Recommended alert conditions:
+
+- Agent Mux gateway unavailable;
+- dispatch queue wait p95 over threshold;
+- approval backlog over threshold;
+- repeated adapter launch rejection;
+- native RBAC drift on owned role;
+- missing Secret/ConfigMap grant blocks active stack;
+- untrusted ref attempted privileged secret access;
+- write-back failure after approval;
+- retention job failure.
+
+## Acceptance criteria
+
+- A user can follow a failed CI-triggered agent run from source event through dispatch, session, artifacts, approval, and write-back.
+- Every privileged grant/approval/write-back has an audit record.
+- Missing permission warnings appear in metrics and UI.
+- Agent Mux stream disconnects produce visible stale/reconnect state.
+- No log/audit/UI surface contains Secret values.
+
+## Memory observability
+
+Memory events must be auditable because memory can change agent behavior.
+
+Required events:
+
+- `agent.memory.ref.resolved` with requested ref, resolved commit, mode, and requester.
+- `agent.memory.query.executed` with snapshot, query modes, counts, truncation, and denied scopes.
+- `agent.memory.snapshot.created` with ontology/index/query digests.
+- `agent.memory.update.proposed` with source run, paths, diff digest, and validation result.
+- `agent.memory.update.approved`, `agent.memory.update.merged`, and `agent.memory.update.rejected`.
+- `agent.memory.ontology.invalid` with parse/error counts and blocking status.
+
+Metrics should include query latency, index age, validation failures, denied memory reads, update merge latency, and historical-memory dispatch count.
+
+## Org and memory audit fields
+
+Every agent, memory, deployment, and repository audit event should include:
+
+- `organizationRef`;
+- `namespace`;
+- actor user/group/service account;
+- repository/deployment refs when applicable;
+- memory repository and resolved commit when memory is used;
+- session ID and run ID when Agent Mux or Babysitter participates;
+- journal digest when `.a5c` run memory is imported;
+- cross-org sharing policy ID when a cross-org ref is admitted.
+
+## Org memory sequence audit coverage
+
+Each sequence in `org-memory-controller-sequence-spec.md` should emit audit records for preflight, admission decision, Git ref resolution, memory query, context snapshot, Agent Mux launch, memory import collection, redaction, validation, review, merge, and cross-org denial. Audit records must include org, namespace, source refs, resolved commit, and digest fields where applicable.

package/docs/agents/operator-runbook.md

@@ -0,0 +1,174 @@
+# Agent operator runbook
+
+## Purpose
+
+This runbook describes how an operator should install, enable, validate, troubleshoot, and safely disable Krate agent orchestration once implemented. It is docs-only and aligns with the current chart/API validation surfaces.
+
+## Current baseline
+
+Before agent implementation, these commands should remain green:
+
+```powershell
+npm run validate:docs
+npm run package:check
+npm run ui:validate
+npm run check
+```
+
+Current install surfaces:
+
+- chart: `charts/krate`;
+- values: `charts/krate/values.yaml`;
+- CRDs: `charts/krate/crds/`;
+- controller API: `/api/controller`;
+- resource API: `/api/controller/resources`;
+- watch API: `/api/watch/orgs/[org]/*`.
+
+## Enablement checklist
+
+When agents are implemented, enable in this order:
+
+1. Install/upgrade CRDs for agent config resources.
+2. Enable `agents.enabled=true` in Helm values.
+3. Configure Agent Mux gateway URL and credentials through `existingSecret`.
+4. Configure default untrusted runner pool.
+5. Configure default agent runtime ServiceAccount.
+6. Enable permission review without auto-dispatch.
+7. Create a read-only agent stack.
+8. Validate stack readiness and permission review.
+9. Enable manual dispatch for a test repository.
+10. Enable trigger rules only after manual dispatch is stable.
+11. Enable write-back approvals last.
+
+## Preflight checks
+
+Operator should verify:
+
+- Kubernetes API reachable from controller pod;
+- Krate CRDs installed;
+- native RBAC allows controller to manage intended resources;
+- Agent Mux gateway reachable from controller namespace;
+- runner pools exist and trust tiers are correct;
+- Secret/ConfigMap grant management feature gate configured;
+- NetworkPolicy allows only required Agent Mux/MCP egress;
+- `/api/controller` reports healthy controller model;
+- `/api/watch/orgs/[org]/repositories` streams events.
+
+## Safe default policy
+
+Default install should be safe:
+
+- agents disabled;
+- trigger rules disabled;
+- manual dispatch disabled;
+- write-back approval required;
+- no privileged secrets on forks;
+- untrusted runner pool default;
+- no broad Secret read for web pod;
+- Agent Mux gateway optional/degraded if absent.
+
+## Common operations
+
+### Create first read-only stack
+
+1. Create `AgentServiceAccount` with read-only role template.
+2. Create `AgentToolProfile` with filesystem read-only and network deny.
+3. Create `AgentStack` using read-only tool profile.
+4. Run permission review.
+5. Confirm stack `Ready=True`.
+
+### Grant a tool Secret
+
+1. Open Secret grant wizard or apply `AgentSecretGrant`.
+2. Scope to stack/tool, repository, refs, trigger sources, and purpose.
+3. Confirm Secret key metadata exists.
+4. Confirm stack readiness updates.
+5. Run dry-run before dispatch.
+
+### Enable CI diagnosis
+
+1. Create CI diagnosis stack.
+2. Create `AgentTriggerRule` in draft.
+3. Dry-run against failed `Pipeline`/`Job` payload.
+4. Validate context bundle preview and permission review.
+5. Set lifecycle to active.
+6. Watch `AgentTriggerExecution` and `AgentDispatchRun` resources.
+
+### Rotate Secret
+
+1. Update native Secret using approved process.
+2. Confirm `AgentSecretGrant` status updates metadata version.
+3. Check affected stacks/rules/runs.
+4. Retry/resume only after fresh permission review.
+
+## Troubleshooting
+
+| Symptom | Check | Likely fix |
+| --- | --- | --- |
+| stack not ready | stack conditions | fix adapter, ServiceAccount, grant, MCP, or skill dependency. |
+| dispatch denied | permission review response | add least-privilege role/grant or change runner/source. |
+| Agent Mux launch fails | attempt status and adapter rejection | update launch options or adapter configuration. |
+| session stuck pending | Agent Mux gateway and session binding | retry binding or inspect gateway logs. |
+| no watch updates | `/api/watch/orgs/<org>/<resource>` | check Kubernetes watch/RBAC/network. |
+| Secret grant missing | capability requirements | create scoped `AgentSecretGrant`. |
+| fork run gets privileged pool | trigger/runner trust policy | force untrusted pool and audit policy violation. |
+| write-back duplicated | idempotency key/audit | fix write-back controller idempotency before retrying. |
+
+## Rollback and disablement
+
+To disable safely:
+
+1. Pause trigger rules.
+2. Disable manual dispatch.
+3. Wait for active dispatches or cancel them.
+4. Disable write-back actions.
+5. Keep read-only run/artifact/audit views available.
+6. Disable Agent Mux gateway integration.
+7. Leave CRDs installed until retained records are exported or pruned.
+
+Emergency disable:
+
+- set `agents.enabled=false` or feature gates false;
+- revoke Agent Mux gateway secret;
+- revoke privileged `AgentSecretGrant` and `AgentRoleBinding` resources;
+- scale agent controllers down if necessary;
+- preserve audit and run records.
+
+## Operational metrics to watch
+
+- active dispatches;
+- queued dispatches;
+- failed dispatches;
+- pending approvals;
+- Agent Mux launch failures;
+- permission review denials;
+- RBAC drift;
+- missing grants;
+- write-back failures;
+- retention job failures.
+
+## Support bundle
+
+A safe support bundle should include:
+
+- controller model from `/api/controller` with secrets redacted;
+- stack/rule/run resource YAML;
+- permission review response;
+- conditions from ServiceAccount/RoleBinding/SecretGrant/ConfigGrant resources;
+- event timeline;
+- Agent Mux run/session IDs;
+- audit records;
+- chart values with Secret values redacted.
+
+It must not include Secret values, raw tokens, kubeconfigs, private keys, or full transcripts unless explicitly approved.
+
+## Company brain operations
+
+Operators should treat the memory repository like production configuration:
+
+- verify `AgentMemoryRepository` health before enabling required-memory stacks;
+- keep ontology validation green before allowing memory update merges;
+- monitor index age and query failures;
+- use historical memory refs for reproducible incident replay;
+- disable affected `AgentMemorySource` scopes before reverting a bad memory commit;
+- preserve `AgentMemorySnapshot` records even when source policies change.