agent-lifecycle 0.2.2__tar.gz → 0.2.3__tar.gz

agent_lifecycle-0.2.3/.devague/plans/agent-lifecycle-v0-3-ships-the-two-pluggable-seam.json

@@ -0,0 +1,252 @@
+{
+  "slug": "agent-lifecycle-v0-3-ships-the-two-pluggable-seam",
+  "title": "agent-lifecycle v0.3 ships the two pluggable seam interfaces \u2014 Transport (message-first, presence optional) and Harness \u2014 plus a minimal in-process supervisor core and a reference echo transport+harness that prove the seam end-to-end, depending on nothing culture/agentirc/Slack-specific.",
+  "frame_slug": "agent-lifecycle-v0-3-ships-the-two-pluggable-seam",
+  "schema_version": 1,
+  "status": "exported",
+  "created": "2026-06-09T23:23:48Z",
+  "updated": "2026-06-09T23:36:22Z",
+  "targets": [
+    {
+      "id": "c1",
+      "kind": "announcement",
+      "text": "agent-lifecycle v0.3 ships the two pluggable seam interfaces \u2014 Transport (message-first, presence optional) and Harness \u2014 plus a minimal in-process supervisor core and a reference echo transport+harness that prove the seam end-to-end, depending on nothing culture/agentirc/Slack-specific."
+    },
+    {
+      "id": "h1",
+      "kind": "honesty",
+      "text": "The reference harness+transport demo runs in CI with no network and no optional culture/agentirc/Slack packages installed."
+    },
+    {
+      "id": "c2",
+      "kind": "audience",
+      "text": "The cultureagent and colleague maintainers (the two proving harnesses) plus the charter reviewers (guildmaster#61) who need concrete code \u2014 not prose \u2014 to ratify the Transport/Harness seam."
+    },
+    {
+      "id": "h7",
+      "kind": "honesty",
+      "text": "The exported spec is directly consumable by the cultureagent + colleague maintainers as the ratification target: it names both proving harnesses and links guildmaster#61."
+    },
+    {
+      "id": "c3",
+      "kind": "after_state",
+      "text": "The Transport and Harness contracts are importable from agent_lifecycle and demonstrated end-to-end: a reference harness wired to a reference transport through the supervisor round-trips a message in-process, with zero culture/agentirc/Slack imports."
+    },
+    {
+      "id": "h2",
+      "kind": "honesty",
+      "text": "round-trip is observable: an inbound message handed to the Harness produces an outbound message delivered back through the Transport, asserted by a test \u2014 not just an interface that type-checks."
+    },
+    {
+      "id": "c4",
+      "kind": "before_state",
+      "text": "The agent runtime is entangled inside cultureagent: the four backend daemons and the supervisor mechanics live together, and IRC is hardcoded as the transport (IRCTransport / agentirc VirtualClient lineage). No transport-free, harness-free core exists."
+    },
+    {
+      "id": "h8",
+      "kind": "honesty",
+      "text": "The entanglement is citable in cultureagent today: the backend daemons and the supervisor mechanics live in the same package, and IRCTransport is the only transport."
+    },
+    {
+      "id": "c5",
+      "kind": "why_it_matters",
+      "text": "A transport-free, harness-free core lets cultureagent slim to a harness pack and lets colleague/Slack build on the same runtime without inheriting IRC or the Claude-family backends \u2014 the coupling that blocks both cases today."
+    },
+    {
+      "id": "h9",
+      "kind": "honesty",
+      "text": "With the core extracted, a colleague-on-Slack deployment can be composed with no agentirc/IRC/culture package anywhere in its dependency tree."
+    },
+    {
+      "id": "c6",
+      "kind": "boundary",
+      "text": "First increment only: NOT extracting cultureagent's four backends, NOT shipping the IRC/Slack/agtag transport plugs, and NOT refitting cultureagent to consume the package yet. Those follow once the seam is ratified."
+    },
+    {
+      "id": "h10",
+      "kind": "honesty",
+      "text": "This increment is shippable and reviewable with NO cultureagent source present in this repo \u2014 it adds only new in-repo modules + tests."
+    },
+    {
+      "id": "c7",
+      "kind": "success_signal",
+      "text": "A pytest test composes the reference Harness + reference Transport through the supervisor and round-trips a message in-process; an import-guard test asserts agent_lifecycle has no culture/agentirc/Slack import in its dependency tree."
+    },
+    {
+      "id": "h3",
+      "kind": "honesty",
+      "text": "the import-guard test fails loudly if a future commit adds a culture/agentirc/Slack import to the core (e.g. it walks the import graph, not just a grep)."
+    },
+    {
+      "id": "c9",
+      "kind": "requirement",
+      "text": "agent_lifecycle's runtime dependency tree imports nothing culture-, agentirc-, or Slack-specific; the seam is defined as abstract interfaces (Protocol/ABC) so concrete transports/harnesses live in downstream packs/plugs."
+    },
+    {
+      "id": "h5",
+      "kind": "honesty",
+      "text": "a downstream pack can implement Transport/Harness against only agent_lifecycle's public exports, with no import from a sibling pack."
+    }
+  ],
+  "tasks": [
+    {
+      "id": "t1",
+      "summary": "Message-first core type: add agent_lifecycle/runtime/message.py (+ minimal runtime/__init__.py package marker) defining a Message value object \u2014 sender identity, target/channel, body, optional kind/metadata \u2014 with NO transport/harness coupling.",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "A Message value object is importable from agent_lifecycle.runtime.message with sender-identity, target/channel and body fields; constructing one requires no Transport or Harness, and runtime/__init__.py is a bare package marker (no re-exports of not-yet-built submodules)."
+      ],
+      "deps": [],
+      "covers": [
+        "c3"
+      ]
+    },
+    {
+      "id": "t2",
+      "summary": "Transport interface: add agent_lifecycle/runtime/transport.py defining Transport as an abstract message-first interface (Protocol/ABC) over Message \u2014 send, receive/subscribe, identity \u2014 with presence (join/part/who) as a SEPARATE optional Presence protocol a transport may omit.",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "Transport is an abstract interface exposing send / receive(subscribe) / identity over Message; presence is a distinct optional Presence protocol \u2014 importing or implementing Transport imposes no presence requirement (an async/no-presence transport is expressible without changing the Transport signature).",
+        "Concurrency model is asyncio: send/receive are async, subscribe yields an async iterator of Messages; this is the single seam-wide concurrency model."
+      ],
+      "deps": [
+        "t1"
+      ],
+      "covers": [
+        "c3"
+      ]
+    },
+    {
+      "id": "t3",
+      "summary": "Harness interface: add agent_lifecycle/runtime/harness.py defining Harness as an abstract long-lived streaming brain \u2014 start / feed_message / stream-of-reply-Messages / stop \u2014 modeling a live process-backed agent like Claude Code or Codex.",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "Harness is an abstract interface for a long-lived streaming brain (start -> feed_message -> async/iterable stream of reply Messages -> stop); no Harness method takes a transport or a presence argument.",
+        "Concurrency model is asyncio: start/feed_message/stop are async and the reply stream is an async iterator of Messages."
+      ],
+      "deps": [
+        "t1"
+      ],
+      "covers": [
+        "c3"
+      ]
+    },
+    {
+      "id": "t4",
+      "summary": "Minimal in-process supervisor: add agent_lifecycle/runtime/supervisor.py wiring any Transport to any Harness \u2014 pump inbound Messages from the transport into the harness, publish the harness reply stream back out via the transport \u2014 with a start/stop/status surface (in-process only, not OS-process).",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "The supervisor accepts any Transport + Harness, delivers each inbound Message to the harness and publishes its reply stream back through the transport; stop() halts the pump cleanly; it imports only agent_lifecycle.runtime public types, never a concrete transport/harness.",
+        "Supervisor drives the pump with asyncio \u2014 awaits inbound from the transport, awaits the harness reply stream, awaits transport send \u2014 no blocking calls."
+      ],
+      "deps": [
+        "t2",
+        "t3"
+      ],
+      "covers": [
+        "c3"
+      ]
+    },
+    {
+      "id": "t5",
+      "summary": "Reference doubles: add agent_lifecycle/reference/ (__init__.py, echo_transport.py, echo_harness.py) \u2014 an in-memory no-network Transport and an EchoHarness that emits one reply Message per inbound \u2014 implemented against only agent_lifecycle public exports.",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "An in-memory reference Transport (no sockets/network) and an EchoHarness (one reply Message per inbound) are importable from agent_lifecycle.reference and implement Transport/Harness using only agent_lifecycle public exports \u2014 proving a downstream pack needs no sibling-pack import.",
+        "Reference doubles implement the asyncio Transport/Harness (async methods, async-iterator streams), no threads/sockets."
+      ],
+      "deps": [
+        "t2",
+        "t3"
+      ],
+      "covers": [
+        "h5"
+      ]
+    },
+    {
+      "id": "t6",
+      "summary": "Round-trip demo test: add tests/test_runtime_roundtrip.py composing EchoHarness + the in-memory reference Transport through the supervisor, sending one inbound Message and asserting the matching outbound reply is observed at the transport.",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "A pytest wires EchoHarness + in-memory Transport via the supervisor, sends one inbound Message, and asserts the corresponding outbound reply is delivered back through the transport \u2014 running with no network and with no culture/agentirc/Slack package installed."
+      ],
+      "deps": [
+        "t4",
+        "t5"
+      ],
+      "covers": [
+        "c1",
+        "h1",
+        "h2",
+        "c7"
+      ]
+    },
+    {
+      "id": "t7",
+      "summary": "Import-guard test: add tests/test_import_guard.py that imports every agent_lifecycle submodule, resolves the loaded module set, and asserts none belong to a culture/agentirc/slack package \u2014 walking the import graph, not grepping source.",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "A pytest imports every agent_lifecycle submodule and asserts the resolved sys.modules set contains no culture/agentirc/slack package; adding such an import to any core module makes the test fail loudly (verified by a temporary/monkeypatched offender or an allowlist-diff)."
+      ],
+      "deps": [
+        "t4",
+        "t5"
+      ],
+      "covers": [
+        "c7",
+        "h3",
+        "c9"
+      ]
+    },
+    {
+      "id": "t8",
+      "summary": "Seam documentation: add docs/runtime-seam.md (linked from README) for the cultureagent + colleague maintainers and charter reviewers \u2014 states the before (runtime entangled in cultureagent, IRC hardcoded) -> after (extracted transport-free/harness-free core), why it matters (cultureagent slims; colleague/Slack build without IRC/Claude backends), and this increment's explicit boundary/non-goals.",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "docs/runtime-seam.md (linked from README) names the cultureagent + colleague audience and links guildmaster#61 / issue #1; states before->after and why; and explicitly lists the increment boundary (no backend extraction, no real IRC/Slack/agtag, no cultureagent refit) \u2014 and the repo builds/ships with NO cultureagent source present."
+      ],
+      "deps": [
+        "t2",
+        "t3"
+      ],
+      "covers": [
+        "c2",
+        "h7",
+        "c4",
+        "h8",
+        "c5",
+        "h9",
+        "c6",
+        "h10"
+      ]
+    }
+  ],
+  "risks": [
+    {
+      "id": "r1",
+      "text": "cultureagent backend extraction + refit, and real IRC/Slack/agtag transport plugs, are explicitly later increments \u2014 this plan only defines + proves the seam greenfield.",
+      "kind": "out_of_scope",
+      "task_id": null
+    },
+    {
+      "id": "r2",
+      "text": "Before the first REAL PyPI publish, a Trusted Publisher must be registered for agent-lifecycle on PyPI AND TestPyPI (per issue #1 packaging facts); not needed for this increment since it ships no new publishable runtime contract decision beyond the package itself.",
+      "kind": "follow_up",
+      "task_id": null
+    },
+    {
+      "id": "r3",
+      "text": "Concurrency model must be consistent across Transport/Harness/Supervisor (t2/t3/t4) and the reference doubles (t5): pick ONE \u2014 recommend asyncio to match cultureagent's async daemons \u2014 so the stream/pump types compose. A split model would break the round-trip demo.",
+      "kind": "unknown_nonblocking",
+      "task_id": "t4"
+    }
+  ]
+}

{agent_lifecycle-0.2.2 → agent_lifecycle-0.2.3}/.gitignore

@@ -231,6 +231,8 @@ skills.local.yaml
 
 # devague working state (not committed by default)
 .devague/reviews/
-# Mutable "current frame" pointer — local working state, churns per branch.
-# The durable artifacts are .devague/frames/<slug>.json + docs/specs/<slug>.md.
+# Mutable "current frame" / "current plan" pointers — local working state that
+# churns per branch. The durable artifacts are .devague/frames/<slug>.json,
+# .devague/plans/<slug>.json, and the exported docs/specs|plans/<slug>.md.
 .devague/current
+.devague/current_plan

{agent_lifecycle-0.2.2 → agent_lifecycle-0.2.3}/.markdownlint-cli2.yaml

@@ -21,3 +21,9 @@ ignores:
   - ".teken/**"
   # Vendored skills are cited verbatim from guildmaster — do not reformat them.
   - ".claude/skills/**"
+  # devague-generated specs/plans — task summaries become sentence headings
+  # (trailing period → MD026). These are tool output, not hand-authored prose.
+  - "docs/specs/**"
+  - "docs/plans/**"
+  # devague local working state (frames/plans JSON + ungitignored review md).
+  - ".devague/**"

{agent_lifecycle-0.2.2 → agent_lifecycle-0.2.3}/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/). This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.3] - 2026-06-10
+
+### Added
+
+- **Converged devague build plan for the first increment** (`docs/plans/2026-06-09-agent-lifecycle-v0-3-ships-the-two-pluggable-seam.md`),
+  the forward leg from the spec landed in 0.2.2. Eight tasks covering all 16 spec
+  targets across four file-disjoint dependency waves: `runtime/message.py` →
+  `transport.py` + `harness.py` → `supervisor.py` + reference doubles + seam docs
+  → round-trip + import-guard tests. Decision baked into the task acceptance
+  criteria: the seam uses **asyncio** as its single concurrency model (matches
+  cultureagent's async daemons). Risks recorded: cultureagent extraction / real
+  transports are out-of-scope later increments; a PyPI Trusted Publisher must be
+  registered before the first real publish.
+
+### Changed
+
+### Fixed
+
 ## [0.2.2] - 2026-06-10
 
 ### Added

{agent_lifecycle-0.2.2 → agent_lifecycle-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-lifecycle
-Version: 0.2.2
+Version: 0.2.3
 Summary: Harness- and transport-agnostic agent runtime: supervises an agent's process lifecycle independent of its harness (brain) and transport (IRC/Slack/agtag).
 Project-URL: Homepage, https://github.com/agentculture/agent-lifecycle
 Project-URL: Issues, https://github.com/agentculture/agent-lifecycle/issues

agent_lifecycle-0.2.3/docs/plans/2026-06-09-agent-lifecycle-v0-3-ships-the-two-pluggable-seam.md

@@ -0,0 +1,72 @@
+# Build Plan — agent-lifecycle v0.3: the two pluggable seam interfaces (Transport + Harness)
+
+slug: `agent-lifecycle-v0-3-ships-the-two-pluggable-seam` · status: `exported` · from frame: `agent-lifecycle-v0-3-ships-the-two-pluggable-seam`
+
+> agent-lifecycle v0.3 ships the two pluggable seam interfaces — Transport (message-first, presence optional) and Harness — plus a minimal in-process supervisor core and a reference echo transport+harness that prove the seam end-to-end, depending on nothing culture/agentirc/Slack-specific.
+
+## Tasks
+
+### t1 — Message-first core type: add agent_lifecycle/runtime/message.py (+ minimal runtime/__init__.py package marker) defining a Message value object — sender identity, target/channel, body, optional kind/metadata — with NO transport/harness coupling.
+
+- covers: c3
+- acceptance:
+  - A Message value object is importable from agent_lifecycle.runtime.message with sender-identity, target/channel and body fields; constructing one requires no Transport or Harness, and runtime/__init__.py is a bare package marker (no re-exports of not-yet-built submodules).
+
+### t2 — Transport interface: add agent_lifecycle/runtime/transport.py defining Transport as an abstract message-first interface (Protocol/ABC) over Message — send, receive/subscribe, identity — with presence (join/part/who) as a SEPARATE optional Presence protocol a transport may omit.
+
+- depends on: t1
+- covers: c3
+- acceptance:
+  - Transport is an abstract interface exposing send / receive(subscribe) / identity over Message; presence is a distinct optional Presence protocol — importing or implementing Transport imposes no presence requirement (an async/no-presence transport is expressible without changing the Transport signature).
+  - Concurrency model is asyncio: send/receive are async, subscribe yields an async iterator of Messages; this is the single seam-wide concurrency model.
+
+### t3 — Harness interface: add agent_lifecycle/runtime/harness.py defining Harness as an abstract long-lived streaming brain — start / feed_message / stream-of-reply-Messages / stop — modeling a live process-backed agent like Claude Code or Codex.
+
+- depends on: t1
+- covers: c3
+- acceptance:
+  - Harness is an abstract interface for a long-lived streaming brain (start -> feed_message -> async/iterable stream of reply Messages -> stop); no Harness method takes a transport or a presence argument.
+  - Concurrency model is asyncio: start/feed_message/stop are async and the reply stream is an async iterator of Messages.
+
+### t4 — Minimal in-process supervisor: add agent_lifecycle/runtime/supervisor.py wiring any Transport to any Harness — pump inbound Messages from the transport into the harness, publish the harness reply stream back out via the transport — with a start/stop/status surface (in-process only, not OS-process).
+
+- depends on: t2, t3
+- covers: c3
+- acceptance:
+  - The supervisor accepts any Transport + Harness, delivers each inbound Message to the harness and publishes its reply stream back through the transport; stop() halts the pump cleanly; it imports only agent_lifecycle.runtime public types, never a concrete transport/harness.
+  - Supervisor drives the pump with asyncio — awaits inbound from the transport, awaits the harness reply stream, awaits transport send — no blocking calls.
+
+### t5 — Reference doubles: add agent_lifecycle/reference/ (__init__.py, echo_transport.py, echo_harness.py) — an in-memory no-network Transport and an EchoHarness that emits one reply Message per inbound — implemented against only agent_lifecycle public exports
+
+- depends on: t2, t3
+- covers: h5
+- acceptance:
+  - An in-memory reference Transport (no sockets/network) and an EchoHarness (one reply Message per inbound) are importable from agent_lifecycle.reference and implement Transport/Harness using only agent_lifecycle public exports — proving a downstream pack needs no sibling-pack import.
+  - Reference doubles implement the asyncio Transport/Harness (async methods, async-iterator streams), no threads/sockets.
+
+### t6 — Round-trip demo test: add tests/test_runtime_roundtrip.py composing EchoHarness + the in-memory reference Transport through the supervisor, sending one inbound Message and asserting the matching outbound reply is observed at the transport
+
+- depends on: t4, t5
+- covers: c1, h1, h2, c7
+- acceptance:
+  - A pytest wires EchoHarness + in-memory Transport via the supervisor, sends one inbound Message, and asserts the corresponding outbound reply is delivered back through the transport — running with no network and with no culture/agentirc/Slack package installed.
+
+### t7 — Import-guard test: add tests/test_import_guard.py that imports every agent_lifecycle submodule, resolves the loaded module set, and asserts none belong to a culture/agentirc/slack package — walking the import graph, not grepping source
+
+- depends on: t4, t5
+- covers: c7, h3, c9
+- acceptance:
+  - A pytest imports every agent_lifecycle submodule and asserts the resolved sys.modules set contains no culture/agentirc/slack package; adding such an import to any core module makes the test fail loudly (verified by a temporary/monkeypatched offender or an allowlist-diff).
+
+### t8 — Seam documentation: add docs/runtime-seam.md (linked from README) for the cultureagent + colleague maintainers and charter reviewers — states the before (runtime entangled in cultureagent, IRC hardcoded) -> after (extracted transport-free/harness-free core), why it matters (cultureagent slims; colleague/Slack build without IRC/Claude backends), and this increment's explicit boundary/non-goals
+
+- depends on: t2, t3
+- covers: c2, h7, c4, h8, c5, h9, c6, h10
+- acceptance:
+  - docs/runtime-seam.md (linked from README) names the cultureagent + colleague audience and links guildmaster#61 / issue #1; states before->after and why; and explicitly lists the increment boundary (no backend extraction, no real IRC/Slack/agtag, no cultureagent refit) — and the repo builds/ships with NO cultureagent source present.
+
+## Risks
+
+- [out_of_scope] cultureagent backend extraction + refit, and real IRC/Slack/agtag transport plugs, are explicitly later increments — this plan only defines + proves the seam greenfield.
+- [follow_up] Before the first REAL PyPI publish, a Trusted Publisher must be registered for agent-lifecycle on PyPI AND TestPyPI (per issue #1 packaging facts); not needed for this increment since it ships no new publishable runtime contract decision beyond the package itself.
+- [unknown_nonblocking] Concurrency model must be consistent across Transport/Harness/Supervisor (t2/t3/t4) and the reference doubles (t5): pick ONE — recommend asyncio to match cultureagent's async daemons — so the stream/pump types compose. A split model would break the round-trip demo. (task t4)

{agent_lifecycle-0.2.2 → agent_lifecycle-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-lifecycle"
-version = "0.2.2"
+version = "0.2.3"
 description = "Harness- and transport-agnostic agent runtime: supervises an agent's process lifecycle independent of its harness (brain) and transport (IRC/Slack/agtag)."
 readme = "README.md"
 license = "MIT"

{agent_lifecycle-0.2.2 → agent_lifecycle-0.2.3}/uv.lock

@@ -4,7 +4,7 @@ requires-python = ">=3.12"
 
 [[package]]
 name = "agent-lifecycle"
-version = "0.2.2"
+version = "0.2.3"
 source = { editable = "." }
 
 [package.dev-dependencies]