From 51bfe1542aed16d075d28aed94e23becf8f0f1fc Mon Sep 17 00:00:00 2001 From: rkoster Date: Fri, 18 Sep 2026 12:49:54 +0200 Subject: [PATCH 1/3] docs: define HumanLayer research note --- ...6-09-18-humanlayer-research-note-design.md | 31 +++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 docs/superpowers/specs/2026-09-18-humanlayer-research-note-design.md diff --git a/docs/superpowers/specs/2026-09-18-humanlayer-research-note-design.md b/docs/superpowers/specs/2026-09-18-humanlayer-research-note-design.md new file mode 100644 index 0000000..2229e0c --- /dev/null +++ b/docs/superpowers/specs/2026-09-18-humanlayer-research-note-design.md @@ -0,0 +1,31 @@ +# HumanLayer Research Note Design + +## Goal + +Add a sourced research note on HumanLayer's multiplayer agent workspace and its support for +stateless-at-the-process-layer agent execution. + +## Scope + +The note will describe HumanLayer's API/control-plane and local or remote daemon model, task +grouping, sessions, artifacts, plans, diffs, worktrees, event streaming, and multi-user access. +It will assess the thesis that durable collaboration/session state can be externalized while +agent processes and hosts remain replaceable. + +The note will explicitly distinguish documented daemon reconnection and externalized events from +unproven live process migration between containers. It will discuss host-bound capabilities such +as code, credentials, tools, private network access, worktrees, and persistent daemon storage. +Cloud Foundry analysis will cover CAPI/Diego, durable state stores, disposable processes, identity, +workspaces, and Loggregator. + +## Structure and evidence + +Create `research/humanlayer.md` with the required four sections and frontmatter. Use the +HumanLayer repository, current website, remote daemon guide, remote daemon architecture docs, +and related public documentation. Clearly distinguish current product claims from architectural +inference. + +## Validation + +Run Devbox validation and tests, inspect whitespace/staged files, commit the note and plan on +`research/humanlayer`, push, and open a PR targeting `main` without unrelated artifacts. From 40f75f59d5de62380fdb9ebbf765ecb7d1824cf7 Mon Sep 17 00:00:00 2001 From: rkoster Date: Fri, 18 Sep 2026 12:50:35 +0200 Subject: [PATCH 2/3] docs: add HumanLayer research note --- .../2026-09-18-humanlayer-research-note.md | 27 +++++ research/humanlayer.md | 111 ++++++++++++++++++ 2 files changed, 138 insertions(+) create mode 100644 docs/superpowers/plans/2026-09-18-humanlayer-research-note.md create mode 100644 research/humanlayer.md diff --git a/docs/superpowers/plans/2026-09-18-humanlayer-research-note.md b/docs/superpowers/plans/2026-09-18-humanlayer-research-note.md new file mode 100644 index 0000000..8ee80b5 --- /dev/null +++ b/docs/superpowers/plans/2026-09-18-humanlayer-research-note.md @@ -0,0 +1,27 @@ +# HumanLayer Research Note Implementation Plan + +> **For agentic workers:** Execute this plan inline with validation checkpoints. + +**Goal:** Add and publish a sourced research note on HumanLayer's externalized agent sessions and disposable execution model. + +**Architecture:** Describe the HumanLayer API/control plane, local/remote daemons, tasks, sessions, artifacts, diffs, worktrees, and streamed events. Separate durable collaboration state from host-bound execution context, then map the thesis to CF's durable state, disposable Diego processes, identity, and event streams. + +**Tech Stack:** Markdown, YAML frontmatter, Devbox, Git, GitHub CLI. + +--- + +### Task 1: Write `research/humanlayer.md` + +- [ ] Add frontmatter with title `HumanLayer: Externalized Agent Sessions and Disposable Execution`, author `Ruben Koster (@rkoster)`, date `2026-09-18`, tags `[durable-execution, orchestration, observability-governance, ecosystem-survey]`, `cf_areas: [capi, diego, loggregator]`, `status: draft`, ratings, and HumanLayer repository/website/remote-daemon sources. +- [ ] Describe HumanLayer as a multiplayer coding-agent workspace with API, web/desktop/mobile interfaces, local/remote daemons, tasks, sessions, artifacts, plans, diffs, and worktrees. +- [ ] Explain the stateless-at-the-process-layer thesis: collaboration/session state and events are externalized, while daemons and agent processes can be restarted or replaced. +- [ ] Distinguish documented API event streaming and daemon reconnection from unproven live in-memory process migration between containers. +- [ ] Cover host-bound capabilities: code, tools, credentials, private services, worktrees, filesystem, and persistent daemon authentication storage. +- [ ] Assess CF relevance for CAPI/Diego, durable state stores, disposable processes, session ownership, identity, workspace persistence, and Loggregator. +- [ ] Add open questions about process migration, state completeness, worktree portability, credential rehydration, event ordering, and failure recovery. + +### 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 HumanLayer research note`, push `research/humanlayer`, and open a checklist-complete PR targeting `main`. +- [ ] Verify PR metadata and CI with `gh pr view`. diff --git a/research/humanlayer.md b/research/humanlayer.md new file mode 100644 index 0000000..69d7890 --- /dev/null +++ b/research/humanlayer.md @@ -0,0 +1,111 @@ +--- +title: "HumanLayer: Externalized Agent Sessions and Disposable Execution" +author: Ruben Koster (@rkoster) +date: 2026-09-18 +tags: [durable-execution, orchestration, observability-governance, ecosystem-survey] +cf_areas: [capi, diego, loggregator] +status: draft +ratings: + platform-impact: + value: 84 + note: "HumanLayer illustrates a control plane where agent collaboration state is externalized while execution hosts remain replaceable." + maturity: + value: 62 + note: "The current product has local and remote daemons, multi-client collaboration, and documented persistence behavior, while the public architecture does not establish live process migration." + novelty: + value: 78 + note: "The combination of multiplayer task/artifact collaboration, full session visibility, remote daemons, and host-independent control is a distinctive platform pattern." + actionability: + value: 80 + note: "The architecture gives CF concrete questions about durable sessions, disposable processes, worktrees, identity, event streams, and host-bound capabilities." +sources: + - https://github.com/humanlayer/humanlayer + - https://humanlayer.com + - https://docs.humanlayer.com/guide/remote-daemons + - https://docs.humanlayer.com/explanation/remote-daemons +--- + +## Summary + +HumanLayer is a multiplayer coding-agent workspace and cloud control plane that brings agent +sessions, plans, artifacts, worktrees, and code diffs together for teams. Its API coordinates +local or remote daemons, while daemons launch the actual coding-agent sessions on hosts with +the required code, tools, credentials, and private-network access. This supports a thesis of +agents becoming stateless at the process layer: collaboration and session events live outside +the process, while the daemon or process can be restarted or replaced, although public docs do +not establish migration of a live in-memory process between arbitrary containers. + +## Key findings + +- **HumanLayer separates control plane from execution host.** Web, desktop, and mobile clients + request work through an API. A connected local or remote daemon receives the work, launches + Claude or Codex sessions, and sends session events back through the API to each interface. +- **Tasks group the durable collaboration surface.** Tasks group sessions, artifacts, plans, + designs, diffs, and worktrees so multiple humans and agents can collaborate on one unit of + work. This external object model is more durable and shareable than the memory of a single + agent process. +- **The product exposes full session visibility.** The website describes visibility into + thinking messages, subagent tool calls, code changes, and real-time topology across daemons + and clients. The event stream gives clients a way to reconnect to ongoing work without being + attached to the agent process's terminal. +- **Remote daemons move execution, not necessarily process memory.** A remote daemon can run on + a cloud VM, workstation, or private-network machine while the user controls sessions through + the browser. The host provides access to code, tools, credentials, and private services. The + public architecture supports dispatch and event streaming through the API, but does not prove + that a live Claude/Codex process can be serialized and resumed in a different container. +- **Execution context remains host-bound.** Worktrees, filesystem state, installed tools, + private network routes, credentials, and agent processes belong to the daemon host. Moving or + replacing a process therefore requires either preserving that host context or reconstructing + it from external state and repository history. +- **Authentication persistence is explicit.** Interactive login stores a session under + `~/.humanlayer/riptide/`, and the daemon can reuse it after restart or host reboot if the same + user and directory remain intact. Containers require persistent storage for those credentials; + removing and recreating the container loses them unless the storage is mounted. +- **The statelessness thesis is layered.** HumanLayer externalizes task metadata, artifacts, + plans, diffs, session events, and control-plane access. It does not imply that prompts, + in-memory model context, shell state, process trees, or credentials are automatically portable + across hosts. The practical model is stateless or replaceable orchestration around a potentially + stateful execution environment. +- **Git is the change-transfer boundary.** The public product centers code diffs and worktrees, + while the open repository documents that the older public code is largely deprecated and points + to the current product. Git history and artifacts can make work portable even when the original + runtime host cannot be reproduced exactly. +- **HumanLayer is multi-user by design.** Teammates can observe and interact with sessions from + different interfaces, comment on artifacts, and send work to agents. That requires identity, + access control, event fan-out, and protection for sensitive session content. + +## CF relevance + +HumanLayer provides a useful reference architecture for Cloud Foundry agents that should not +depend on one long-lived Diego process. CAPI could own tasks and session metadata, while Diego +hosts disposable agent processes whose durable state is stored externally. A replacement process +could rehydrate a task from conversation/event history, repository/worktree state, plans, and +artifacts rather than requiring the original process memory to survive. + +The difficult boundary is completeness of rehydration. CF would need durable session and event +stores, stable workspace or worktree storage, identity and credential reissuance, session +ownership/fencing, and a way to reconstruct tool and private-network access. Loggregator could +stream process, tool, session, and collaboration events, but a durable control-plane history +would still be needed for reconnecting clients and recovering work after process replacement. + +This model could reduce the need for stateful, permanently running agent containers while +preserving a rich interactive experience. It does not eliminate state; it moves state into +platform-managed records, repositories, artifacts, durable stores, and host capability +descriptions. The platform must decide which state is authoritative and how much execution +context is reproducible before claiming an agent is portable across Diego instances. + +## Open questions + +- Which parts of an agent session must be externalized for safe rehydration: conversation, + model context, tool state, shell state, worktree, environment, artifacts, or all of them? +- Can a CF agent process be replaced during a turn, or only between explicit event boundaries? +- How should CAPI and Diego coordinate session ownership, fencing, draining, and recovery to avoid + two processes acting on one task simultaneously? +- How should worktrees, uncommitted files, installed dependencies, credentials, and private + network access be reconstructed on a replacement instance? +- Which user, agent, task, and daemon identities should authorize session access and tool calls? +- What event ordering, replay, retention, and privacy guarantees should Loggregator and the + durable control plane provide? +- When does externalized state become sufficiently complete that process migration is practical, + and when is it more honest to treat a new process as a continuation with a reconstructed + context? From 5f59abaf022739abfc7b31bf31c88123811bd219 Mon Sep 17 00:00:00 2001 From: rkoster Date: Sat, 19 Sep 2026 16:27:52 +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..8ac1311 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.
 -