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/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. 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?