From f8af1e04a64caa21acdb0317b548c94604bd2a69 Mon Sep 17 00:00:00 2001 From: rkoster Date: Thu, 17 Sep 2026 16:39:49 +0200 Subject: [PATCH 1/3] docs: define Mecatl research note --- .../2026-09-17-mecatl-research-note-design.md | 30 +++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 docs/superpowers/specs/2026-09-17-mecatl-research-note-design.md 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. From 4ff869e3ce5e3980dea96382d0753c89d2ff02ea Mon Sep 17 00:00:00 2001 From: rkoster Date: Thu, 17 Sep 2026 16:40:33 +0200 Subject: [PATCH 2/3] docs: add Mecatl research note --- .../plans/2026-09-17-mecatl-research-note.md | 27 +++++ research/mecatl.md | 110 ++++++++++++++++++ 2 files changed, 137 insertions(+) create mode 100644 docs/superpowers/plans/2026-09-17-mecatl-research-note.md create mode 100644 research/mecatl.md 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/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? From f4a4c9974719357b8dd294339e08537dffab8ba0 Mon Sep 17 00:00:00 2001 From: rkoster Date: Sat, 19 Sep 2026 16:28:26 +0200 Subject: [PATCH 3/3] docs: update generated research map --- generated/research-map.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/generated/research-map.html b/generated/research-map.html index bbe5f21..51827ec 100644 --- a/generated/research-map.html +++ b/generated/research-map.html @@ -23,9 +23,9 @@

Focus use cases

Attested Workload Authority and Mediated Tool AccessExchange platform-attested workload identity for scoped authority while credentials and outbound tool access remain mediated by the platform.Strategic decision: Decide whether CF should become the portable trust and policy layer between agent workloads and the tools they invoke.
Gap, experiments, and evidence
Current CF gap
CF issues workload identity certificates but does not exchange them for scoped tool authority, keep third-party credentials out of workloads, mediate off-platform access, or record delegation-aware audit events.
Candidate POC
Exchange a Diego instance identity certificate for a short-lived scoped token, invoke one allowed tool through a credential proxy and egress mediator, deny another, and emit attributable audit events.
Candidate RFC scope
Define workload token exchange, authority and delegation claims, credential brokering, outbound mediation and policy enforcement, audit events, revocation, and integration boundaries for UAA, routing, and service brokers.

Core

Supporting

-
Gap, experiments, and evidence
Current CF gap
CF can stage apps and run ephemeral tasks but cannot cheaply compose a reusable environment with per-session workspace state, select stronger isolation, constrain session networking, or resume the session lifecycle.
Candidate POC
Start two isolated sessions from one content-addressed staged environment, attach separate mutable workspaces, apply per-session egress policy, stop one session, and resume it on fresh compute.
Candidate RFC scope
Define environment and workspace references, session identity and lifecycle, isolation classes, network policy, workspace persistence and cleanup, scheduling, quotas, and compatibility with existing CF staging and task APIs.

Core

Supporting

ResearchIdea

Platform Impact x Maturity

Emerging < Maturity > EstablishedLocal concern < Platform Impact > Platform-wide concern
Unplaced notes (0)
  • All notes are placed.
+
Gap, experiments, and evidence
Current CF gap
CF can stage apps and run ephemeral tasks but cannot cheaply compose a reusable environment with per-session workspace state, select stronger isolation, constrain session networking, or resume the session lifecycle.
Candidate POC
Start two isolated sessions from one content-addressed staged environment, attach separate mutable workspaces, apply per-session egress policy, stop one session, and resume it on fresh compute.
Candidate RFC scope
Define environment and workspace references, session identity and lifecycle, isolation classes, network policy, workspace persistence and cleanup, scheduling, quotas, and compatibility with existing CF staging and task APIs.

Core

Supporting

ResearchIdea

Platform Impact x Maturity

Emerging < Maturity > EstablishedLocal concern < Platform Impact > Platform-wide concern
Unplaced notes (0)
  • All notes are placed.
 -