@a5c-ai/krate 5.0.1-staging.f672fe79b

package/docs/agents/resource-relationship-map.md

@@ -0,0 +1,190 @@
+# Agent resource relationship map
+
+## Purpose
+
+This document shows how the agent resources relate to Krate's existing repository, CI, webhook, identity, and UI resources. It is a navigation aid for implementers and reviewers.
+
+## Existing Krate anchors
+
+| Existing kind/surface | Agent relationship |
+| --- | --- |
+| `Repository` | root scope for stacks, triggers, workspaces, runs, permissions, and artifacts. |
+| `PullRequest` | source for diagnosis/review/repair dispatches and write-back targets. |
+| `Issue` | work item source for agent sessions, workspace links, and board flow. |
+| `Pipeline` / `Job` | CI source and sibling display model for `AgentDispatchRun`. |
+| `RunnerPool` | execution placement and trust tier for dispatch attempts. |
+| `WebhookSubscription` / `WebhookDelivery` | incoming event source for `AgentTriggerRule`. |
+| `User` / `Team` / `RepositoryPermission` | human identity and authorization inputs. |
+| Native `ServiceAccount` / RBAC | authoritative agent, runner, and user permission enforcement. |
+| Native `Secret` / `ConfigMap` | runtime secret/config sources admitted through grants. |
+
+## Configuration relationship graph
+
+```text
+Repository
+  -> AgentStack
+    -> AgentToolProfile
+      -> AgentCapabilityRequirement
+      -> AgentSecretGrant / AgentConfigGrant
+    -> AgentMcpServer
+      -> AgentCapabilityRequirement
+      -> AgentSecretGrant / AgentConfigGrant
+    -> AgentSkill
+      -> AgentCapabilityRequirement
+      -> AgentSecretGrant / AgentConfigGrant
+    -> AgentSubagent
+      -> AgentToolProfile subset
+      -> AgentSkill subset
+      -> AgentMcpServer subset
+    -> AgentWorkspacePolicy
+    -> AgentServiceAccount
+      -> AgentRoleBinding
+    -> AgentContextLabel
+  -> AgentTriggerRule
+    -> AgentStack
+    -> AgentContextLabel
+    -> RunnerPool
+```
+
+## Execution relationship graph
+
+```text
+WebhookDelivery / Pipeline / Job / Issue / PullRequest / manual UI action
+  -> AgentTriggerExecution
+  -> AgentContextBundle
+  -> permission review snapshot
+  -> AgentDispatchRun
+    -> AgentDispatchAttempt
+      -> AgentMuxRunId / AgentMuxSessionId
+      -> AgentSession
+      -> AgentWorkspace
+      -> AgentArtifact / AgentReviewArtifact
+      -> AgentApproval
+    -> WorkItemSessionLink
+    -> WorkItemWorkspaceLink
+```
+
+## Source-to-run relationships
+
+| Source | Creates/links | Notes |
+| --- | --- | --- |
+| failed `Job` | `AgentTriggerExecution`, `AgentDispatchRun` | shows beside pipeline/job row. |
+| PR comment/mention | `AgentTriggerExecution`, `AgentContextBundle` | actor and comment are source refs. |
+| issue label | `AgentTriggerExecution`, work-item links | label cannot grant permissions. |
+| manual Code dispatch | `AgentContextBundle`, `AgentDispatchRun` | selected path/ref included. |
+| webhook replay | new `AgentTriggerExecution` | dedupe may coalesce with existing run. |
+| approval decision | write-back action and audit event | references artifact digest. |
+
+## Permission relationship graph
+
+```text
+User / Team / AgentStack / RunnerPool
+  -> AgentServiceAccount
+  -> AgentRoleBinding
+    -> native Role / ClusterRole
+    -> native RoleBinding / ClusterRoleBinding
+  -> AgentSecretGrant
+    -> native Secret metadata + selected keys
+  -> AgentConfigGrant
+    -> native ConfigMap metadata + selected keys
+  -> AgentCapabilityRequirement
+    -> stack readiness and dispatch permission review
+```
+
+## UI relationship map
+
+| UI page | Primary resources | Secondary resources |
+| --- | --- | --- |
+| `/agents` | dispatches, approvals, stack readiness | trigger health, workspace attention |
+| `/agents/stacks` | `AgentStack` | tools, MCP, skills, subagents, grants |
+| `/agents/runs` | `AgentDispatchRun` | attempts, sessions, artifacts, approvals |
+| `/agents/rules` | `AgentTriggerRule` | executions, deliveries, dry-runs |
+| `/agents/workspaces` | `AgentWorkspace` | sessions, runs, issues, PRs |
+| `/agents/approvals` | `AgentApproval` | artifacts, write-back targets |
+| `/agents/secrets` | `AgentSecretGrant`, `AgentConfigGrant` | consumers, rotations, missing grants |
+| `/orgs/[org]/repositories/[repo]/code` | repository path/ref | context bundle, dispatch composer |
+| `/orgs/[org]/repositories/[repo]/pull-requests` | PR, checks | run/artifact/approval/write-back links |
+| `/orgs/[org]/repositories/[repo]/runs` | pipelines/jobs | agent dispatch rows and artifacts |
+| `/orgs/[org]/repositories/[repo]/settings/agents` | stack/rule/grant policy | generated YAML and permission review |
+
+## Label and index strategy
+
+All agent resources should use common labels so generic list/watch APIs can power repository pages:
+
+- `krate.a5c.ai/repository`;
+- `krate.a5c.ai/source-kind`;
+- `krate.a5c.ai/source-name`;
+- `krate.a5c.ai/agent-stack`;
+- `krate.a5c.ai/dispatch-run`;
+- `krate.a5c.ai/trigger-rule`;
+- `krate.a5c.ai/workspace`;
+- `krate.a5c.ai/service-account`;
+- `krate.a5c.ai/runner-pool`.
+
+## Deletion impact rules
+
+Deleting or disabling a resource should show dependent resources first:
+
+| Delete/disable target | Must warn about |
+| --- | --- |
+| `AgentStack` | trigger rules, active runs, sessions, workspace links. |
+| `AgentToolProfile` | stacks and subagents that require it. |
+| `AgentMcpServer` | skills/stacks/subagents and missing capability requirements. |
+| `AgentSkill` | stacks/subagents using prompt fragments or output contracts. |
+| `AgentSecretGrant` | tools/MCP/skills/model providers that become blocked. |
+| `AgentConfigGrant` | skills/tools/MCP servers that become blocked. |
+| `AgentServiceAccount` | stacks, runner pools, active attempts. |
+| `AgentWorkspace` | sessions, runs, artifacts, work item links. |
+| `AgentArtifact` | approvals/write-back records that reference its digest. |
+
+## Acceptance criteria
+
+- Implementers can trace every UI affordance to resources and controllers.
+- Repository pages can query by labels rather than bespoke UI state.
+- Deletion warnings identify dependent stacks/rules/runs/grants/artifacts.
+- Permission review can explain a missing capability through the relationship graph.
+
+## Memory relationship graph
+
+```text
+Organization
+  -> AgentMemoryRepository
+    -> AgentMemoryOntology
+    -> AgentMemorySource
+      -> Repository / Team / AgentStack / AgentTriggerRule
+    -> AgentMemoryAssociation
+      -> Repository / Service / AgentStack / Tool / Skill / Subagent / Issue / PullRequest
+
+AgentTriggerExecution / manual dispatch
+  -> AgentContextBundle
+    -> AgentMemorySnapshot
+      -> AgentMemoryQuery
+      -> selected graph records
+      -> selected Markdown records
+      -> selected grep excerpts
+  -> AgentDispatchRun
+    -> AgentMemoryUpdate
+      -> AgentApproval
+      -> memory repository PR / merge commit
+```
+
+Deleting a memory source must warn about stacks, trigger rules, and dispatch composers that rely on it. Deleting or disabling a memory repository must block new required-memory dispatches while preserving historical `AgentMemorySnapshot` records.
+
+## Org-scoped relationship root
+
+```text
+Organization
+  -> Kubernetes Namespace
+  -> Repository
+  -> Deployment / Environment
+  -> AgentStack / AgentTriggerRule / RunnerPool
+  -> AgentMemoryRepository
+    -> MEMORY.md
+    -> BabysitterSession
+    -> BabysitterRun
+      -> RunJournalEvent
+      -> RunTaskResult
+      -> ArtifactManifest
+```
+
+All relationship queries should include org. A resource without org scope is either installation/platform state or invalid for product data.

package/docs/agents/security-threat-model.md

@@ -0,0 +1,188 @@
+# Agent security threat model
+
+## Purpose
+
+Agent orchestration expands Krate from CI and repository management into autonomous tool execution. This document identifies threats and required mitigations for the docs-defined agent system.
+
+## Security boundaries
+
+| Boundary | Risk |
+| --- | --- |
+| User/browser to Krate API | forged UI actions, stale permissions, hidden local state |
+| Krate API to Kubernetes API | RBAC bypass, privilege escalation, admission gaps |
+| Krate controllers to Agent Mux | overbroad launch options, secret leakage, session confusion |
+| Agent Mux to tool/runtime | tool abuse, command injection, MCP abuse |
+| Runner/workspace to repository | untrusted code exfiltration, cross-run contamination |
+| Trigger source to dispatch | label/comment prompt injection, webhook replay, dedupe bypass |
+| Secret/ConfigMap grant to dispatch | credential overexposure, stale grants, rotation mismatch |
+| Agent output to write-back | unauthorized PR comments, branch pushes, release actions |
+
+## Threats and mitigations
+
+### Prompt injection through labels/comments/context
+
+Threat:
+
+- Issue labels, PR comments, webhook payloads, or context labels inject hidden instructions or secret requests.
+
+Mitigations:
+
+- Context labels are reviewed resources, not raw hidden prompt text.
+- Prompt preview shows all injected fragments and provenance.
+- Secret/config access is controlled by grants, never by prompt content.
+- Trigger dry-run shows rendered prompt and source payload summary.
+
+### Privilege escalation through roles
+
+Threat:
+
+- A user grants an agent or runner a stronger Role/ClusterRole than they can bind.
+
+Mitigations:
+
+- `AgentRoleBinding` apply requires bind/escalate checks.
+- Role templates show generated YAML before apply.
+- Escalation attempts set conditions and audit events.
+- Native Kubernetes RBAC remains authoritative.
+
+### Secret exfiltration by tools or MCP servers
+
+Threat:
+
+- Tool, skill, MCP server, or agent code reads secrets not required for the task.
+
+Mitigations:
+
+- Secrets require explicit `AgentSecretGrant` by subject, purpose, repo/ref, trigger source, and mount policy.
+- Agent launch passes only admitted references/mounts.
+- Untrusted refs receive no privileged secrets.
+- UI never shows Secret values; audit records only metadata and key names.
+
+### ConfigMap misuse
+
+Threat:
+
+- Non-secret config changes execution behavior or contains sensitive values.
+
+Mitigations:
+
+- `AgentConfigGrant` gates ConfigMap usage.
+- Sensitive keys are metadata-only in UI.
+- ConfigMap consumers and breakage warnings are visible before deletion/change.
+
+### Untrusted fork execution
+
+Threat:
+
+- Forked PR code runs on trusted runner or accesses privileged ServiceAccount/secrets.
+
+Mitigations:
+
+- Trust tier is part of trigger and runner admission.
+- Fork refs force untrusted runner pools and unprivileged ServiceAccounts.
+- Secret grants must explicitly allow untrusted refs; default deny.
+
+### MCP/tool abuse
+
+Threat:
+
+- MCP server or native tool performs network, filesystem, or API actions beyond user intent.
+
+Mitigations:
+
+- `AgentToolProfile` defines filesystem/network/native tool policy.
+- MCP servers declare required roles, Secret refs, ConfigMap refs, and allowed stacks.
+- Tool approval policies gate privileged invocations.
+- Runtime events stream tool calls into audit/observability.
+
+### Agent Mux session confusion
+
+Threat:
+
+- A chat/session is linked to the wrong repository, workspace, dispatch attempt, or actor.
+
+Mitigations:
+
+- `AgentDispatchAttempt.status.agentMuxRunId` and `agentMuxSessionId` are bound once and audited.
+- Run detail always shows source breadcrumbs.
+- Continuation requests include dispatch/run/session IDs and permission review context.
+
+### Write-back abuse
+
+Threat:
+
+- Agent posts comments, pushes branches, approves reviews, reruns checks, or publishes release artifacts without sufficient authorization.
+
+Mitigations:
+
+- Write-back is an explicit action with `AgentApproval` unless narrowly allowed by repository policy.
+- Approval records include actor, approver, artifact digest, target, and source event.
+- Write-back idempotency keys prevent duplicate comments/pushes/reruns.
+
+### Replay and dedupe bypass
+
+Threat:
+
+- Webhook replay, repeated labels, or schedule storms create duplicate costly runs.
+
+Mitigations:
+
+- `WebhookDelivery` is durable before trigger evaluation.
+- `AgentTriggerExecution` records dedupe/coalescing decisions.
+- Dedupe keys include source object, commit SHA, failure signature, rule, and context digest.
+
+### Workspace contamination
+
+Threat:
+
+- One agent attempt sees or mutates another run's workspace state.
+
+Mitigations:
+
+- Workspace policy selects isolated worktrees for untrusted or write-capable tasks.
+- Workspace links record ownership and active sessions/runs.
+- Missing/dirty/rebase states block unsafe write-back until resolved.
+
+## Required audits
+
+Every dispatch should preserve:
+
+- actor and Kubernetes identity;
+- source event and trigger rule;
+- stack generation and permission snapshot digest;
+- runtime and runner ServiceAccounts;
+- Secret/ConfigMap grant names and key names only;
+- tool/MCP/skill/subagent availability;
+- Agent Mux run/session IDs;
+- approvals and write-back decisions;
+- artifacts and digests.
+
+## Security acceptance criteria
+
+- A fork PR cannot access privileged Secret grants or trusted ServiceAccounts.
+- A label/comment cannot grant roles, secrets, configs, or write-back permission by itself.
+- A stack with missing tool/skill/MCP Secret access cannot dispatch.
+- Secret values are never visible in UI responses, status, logs, prompt previews, or audit events.
+- Role binding escalation is denied by server-side review.
+- Write-back to PRs, branches, checks, releases, or deployment surfaces is approval-gated and audited.
+
+## Company brain memory threats
+
+| Threat | Mitigation |
+| --- | --- |
+| prompt injection stored in memory | treat memory as untrusted input, scan risky instructions, render provenance, and separate memory from system/developer prompt layers. |
+| stale memory drives bad action | show pinned commit and stale warning; allow diff against current; require explicit refresh. |
+| unauthorized knowledge exposure | enforce `AgentMemorySource` path/kind grants and redact denied content before preview, prompt, transcript, or audit. |
+| malicious memory update | require validation, source-run link, owners, review, PR diff, and merge permission. |
+| secret leakage into memory | secret scan on reads and writes; block merge and redact selected context. |
+| historical run escapes pinned memory | memory tools default to `AgentMemorySnapshot`; current-memory access requires refresh/approval. |
+
+## Org boundary threats
+
+| Threat | Mitigation |
+| --- | --- |
+| repository slug collision leaks data | non-org repository routes are not served; users must choose an organization explicitly. |
+| cross-org Secret/ConfigMap mount | namespace and `organizationRef` admission checks before dispatch. |
+| cross-org memory query | `AgentMemorySource` and memory APIs require org match and path/kind grant. |
+| run journal imports leak another org | `AgentRunMemoryImport` resolves source repo/run/session ownership before reading `.a5c` material. |
+| shared controller writes to wrong namespace | side effects use resolved org namespace and audit namespace. |