diff --git a/docs/superpowers/plans/2026-09-17-mecatl-research-note.md b/docs/superpowers/plans/2026-09-17-mecatl-research-note.md new file mode 100644 index 0000000..917b6e2 --- /dev/null +++ b/docs/superpowers/plans/2026-09-17-mecatl-research-note.md @@ -0,0 +1,27 @@ +# Mecatl Research Note Implementation Plan + +> **For agentic workers:** Execute this plan inline with validation checkpoints. + +**Goal:** Add and publish a sourced research note on Mecatl as a cloud-native production agent harness. + +**Architecture:** Describe the provider-agnostic agent loop, tools/permissions/delegation, durable sessions and event logs, and the Kubernetes `mecak8s` reference runtime. Map the generic engine and Kubernetes deployment separately to CF lifecycle, identity, bindings, draining, and observability. + +**Tech Stack:** Markdown, YAML frontmatter, Devbox, Git, GitHub CLI. + +--- + +### Task 1: Write `research/mecatl.md` + +- [ ] Add frontmatter with title `Mecatl: Cloud-Native Agent Harness with Durable State and Permissions`, author `Ruben Koster (@rkoster)`, date `2026-09-17`, tags `[orchestration, durable-execution, authorization, observability-governance]`, `cf_areas: [uaa, capi, diego, loggregator]`, `status: draft`, ratings, and Mecatl repository/README/docs sources. +- [ ] Explain the streaming provider-agnostic loop, tools, skills, hooks, subagents, teams, compaction, and service boundaries. +- [ ] Cover deny-dominant permissions, approval flows, secret-scrubbed environments, attribution, audit, and narrowing delegated capabilities. +- [ ] Cover durable sessions and append-only event logs, gRPC/HTTP-SSE/TypeScript clients, and the distinction between embedded engine and `mecak8s` runtime. +- [ ] Describe Redis-backed state, Kubernetes session leases, one-writer coordination, drain handling, and disposable replicas. +- [ ] Assess CF relevance for CAPI/Diego replacement, UAA identity, service bindings, external Redis/state stores, draining, and Loggregator. +- [ ] Add open questions about durable session ownership, permissions, delegation, failover, provider credentials, audit, and running without Kubernetes leases. + +### Task 2: Validate and publish + +- [ ] Run `devbox run validate`, `devbox run test`, and `git diff --check`. +- [ ] Stage only the note and approved spec/plan, commit `docs: add Mecatl research note`, push `research/mecatl`, and open a checklist-complete PR targeting `main`. +- [ ] Verify PR metadata and CI with `gh pr view`. diff --git a/docs/superpowers/specs/2026-09-17-mecatl-research-note-design.md b/docs/superpowers/specs/2026-09-17-mecatl-research-note-design.md new file mode 100644 index 0000000..f34c61c --- /dev/null +++ b/docs/superpowers/specs/2026-09-17-mecatl-research-note-design.md @@ -0,0 +1,30 @@ +# Mecatl Research Note Design + +## Goal + +Address issue #53 with a sourced research note on Mecatl as a cloud-native agent harness for +production workloads on infrastructure operators control. + +## Scope + +The note will cover Mecatl's streaming agent loop, provider-agnostic model integration, tools +and skills, permissions, hooks, delegation, durable sessions, append-only event logs, client +APIs, and the Kubernetes-native `mecak8s` runtime. It will discuss deny-dominant authorization, +derived delegated capabilities, attribution, audit, Redis-backed state, session leases, drain +handling, and disposable replicas. + +The Cloud Foundry analysis will map Mecatl to CAPI-managed applications, Diego process +replacement and draining, UAA identity, service bindings for model/state stores, and +Loggregator audit/event streams. It will not claim existing Mecatl/CF integration. + +## Structure and evidence + +Create `research/mecatl.md` with the required four sections and frontmatter. Use the Mecatl +repository, README, official documentation, and deployment/runtime guides. Distinguish the +generic embedded engine from the Kubernetes reference runtime and label CF conclusions as +analysis or open questions. + +## Validation + +Run Devbox validation and tests, inspect whitespace/staged files, commit the note and plan on +`research/mecatl`, push, and open a PR targeting `main` without unrelated artifacts. diff --git a/research/mecatl.md b/research/mecatl.md new file mode 100644 index 0000000..dc94c13 --- /dev/null +++ b/research/mecatl.md @@ -0,0 +1,110 @@ +--- +title: "Mecatl: Cloud-Native Agent Harness with Durable State and Permissions" +author: Ruben Koster (@rkoster) +date: 2026-09-17 +tags: [orchestration, durable-execution, authorization, observability-governance] +cf_areas: [uaa, capi, diego, loggregator] +status: draft +ratings: + platform-impact: + value: 82 + note: "Mecatl packages agent execution, permissions, durable state, and service boundaries in a form relevant to platform-hosted workloads." + maturity: + value: 70 + note: "The project has a substantial open-source implementation and Kubernetes reference runtime, while cross-platform operations still require evaluation." + novelty: + value: 70 + note: "Its emphasis on deny-dominant permissions, delegated capabilities, durable attribution, and replaceable execution environments distinguishes it from a simple agent SDK." + actionability: + value: 81 + note: "The engine and service APIs provide concrete integration points for CF process lifecycle, bindings, identity, draining, and event observability." +sources: + - https://github.com/stacklok/mecatl + - https://raw.githubusercontent.com/stacklok/mecatl/main/README.md + - https://mecatl.dev/docs/intro + - https://mecatl.dev/docs/building/cloud-native-harness + - https://mecatl.dev/docs/building/deployment/mecak8s + - https://mecatl.dev/docs/building/deployment/grpc-http +--- + +## Summary + +Mecatl is an open-source, provider-agnostic cloud-native agent harness for running production +agent workloads on infrastructure an operator controls. It combines a streaming agent loop +with tools, permissions, hooks, delegation, durable sessions, append-only event logs, and +gRPC/HTTP-SSE clients. Its `mecak8s` reference runtime adds Redis-backed state, Kubernetes +session leases, drain handling, and disposable replicas, making it a useful comparison point +for Cloud Foundry's process lifecycle and platform service boundaries. + +## Key findings + +- **The loop is independent of the client and execution environment.** Mecatl can run locally, + remotely with durable external state and event history, or across Kubernetes replicas without + replacing the core agent loop. Model providers and deployment infrastructure connect through + explicit interfaces. +- **The runtime includes more than model calls.** Its streaming loop provides tool dispatch, + compaction, hooks, subagents, and teams, while tools and skills are composed through service + boundaries that can be embedded or exposed through client APIs. +- **Permissions are first-class runtime state.** Mecatl documents deny-dominant permissions, + approval flows, secret-scrubbed command environments, durable attribution, and an audit trail. + This treats the agent's authority as part of execution rather than as an afterthought around + a model API. +- **Delegation narrows authority.** Delegated runs receive derived capabilities that can only + narrow at each in-process hop. This is a useful pattern for subagents and teams: a child run + should not automatically inherit or expand the authority of its parent. +- **Sessions and event history are durable.** Pluggable stores hold durable sessions and + append-only event logs so work can recover after process replacement. The event record also + provides a basis for attribution and audit across streaming turns and tool calls. +- **The service boundary is explicit.** Mecatl supports gRPC and HTTP/SSE integration, a + TypeScript SDK, and `mecatui` for local or remote use. The `engine` can be embedded with + application-selected model providers, state stores, filesystems, and UI. +- **`mecak8s` is a Kubernetes reference runtime, not the whole engine.** The supplied runtime + uses Redis for session state and event logs, Kubernetes leases to ensure one writer per + session, and a drain path for replacing Pods. This separates generic runtime guarantees from + Kubernetes-specific coordination. +- **Disposable replicas require ownership and draining semantics.** A replica can be replaced + while durable state and session ownership survive elsewhere. Leases prevent concurrent writers + from corrupting a session, while draining provides a controlled handoff during deployment or + failure. +- **Provider credentials and execution infrastructure remain replaceable.** Mecatl does not + require one model provider or one hosting substrate. Operators select adapters, state stores, + filesystem behavior, and client surfaces for their deployment. +- **Mecatl is a harness, not a complete platform.** It supplies execution and policy mechanisms, + but operators still need identity, secret distribution, state-store operations, network + policy, resource isolation, and observability around the harness. + +## CF relevance + +Mecatl's generic engine could run as a CF application supervised by Diego, with CAPI managing +application lifecycle and service bindings supplying model providers, Redis, databases, or +other external services. UAA or a workload identity mechanism could establish the authority +under which an agent acts, while Mecatl's deny-dominant permissions and derived capabilities +could constrain tool and subagent operations inside that application. + +The Kubernetes-specific `mecak8s` design maps to existing CF concerns around process replacement +and draining. CF would need an equivalent durable session ownership mechanism if multiple app +instances can handle the same session. Diego's desired-state and evacuation behavior could +provide lifecycle signals, but an external durable store and a lease or fencing mechanism would +still be needed to avoid concurrent writers during restage, scaling, crash recovery, or +deployment. + +Loggregator could carry correlated session, tool, permission, approval, delegation, and drain +events, while the append-only event log remains the authoritative runtime history selected by +the application. Service bindings should not expose broad provider credentials to every agent; +platform-managed credentials, scoped bindings, secret scrubbing, and explicit audit policy are +needed to preserve Mecatl's authority model in a multi-tenant CF environment. + +## Open questions + +- Can Mecatl's embedded engine run cleanly as a CF application while preserving durable session + recovery across Diego process replacement? +- What CF service should provide Redis-like session state, append-only events, leases, and + fencing, and how should it be provisioned through CAPI or service brokers? +- How should UAA identities, CF instance identities, user delegation, and Mecatl capabilities + combine without allowing subagents to expand authority? +- Which tool permissions, approval events, credentials, and delegated actions should be + visible in Loggregator, and which belong only in a protected audit store? +- How should a Mecatl session drain between instances during deploy, scale, crash recovery, or + provider outage, and what guarantees can CF provide to clients using streaming APIs? +- Should CF provide a Mecatl buildpack/service offering, or only the state, identity, network, + and lifecycle primitives needed to run the harness?