From eb4179f9958deeae408a0a06b1f8ae6437e089db Mon Sep 17 00:00:00 2001
From: t <t@tjp.lol>
Date: Sun, 7 Jun 2026 15:19:57 -0600
Subject: Sync Agent/Stream internals to public names; alias Stream

Push the API-shaping we'd done in the public facade down into the internal
types, collapsing the wrappers:

- Stream: rename phase->state, Phase->State; underscore-prefix the internal
  fields (_agent/_queue/_response/_start/_persisted/_pending_error). state
  is the one intended-public field. public.zig now aliases Stream; run
  returns *Stream.
- Agent compaction: pure transform compact()->private _compactInPlace;
  compactAndPersist()->compact() (the public name, persists).
- Agent system prompt: addSystemMessage(text,mode) split into
  addSystemMessage(text) + setSystemPrompt(text) over a private
  _persistSystemMessage.
- UserMessage moved off Agent to module scope.
- Underscore-prefix pure-internal Agent fields: _open_stream_fn,
  _auto_compacted, _retry_prng.

The Agent facade is now pure 1:1 forwarders; it stays a wrapper only because
init heap-pins the inner (copyable, move-safe handle) and conversation()/
sessionId() are accessors. Conversation and Stream are plain aliases.
---
 docs/libpanto-cleanup.md | 33 +++++++++++++++++++++++++++++++--
 1 file changed, 31 insertions(+), 2 deletions(-)

(limited to 'docs/libpanto-cleanup.md')

diff --git a/docs/libpanto-cleanup.md b/docs/libpanto-cleanup.md
index bc1e1aa..7c53e02 100644
--- a/docs/libpanto-cleanup.md
+++ b/docs/libpanto-cleanup.md
@@ -86,10 +86,39 @@ touching `agent.zig`.
 > `addAssistantMessage(blocks, ?usage)` on the real type (the separate
 > method deleted), so the alias already has the intended one-method shape.
 
+> **Updated during implementation (impl cleanups synced the internals to the
+> public names):** the public-API shaping we'd done in the façade was pushed
+> *into* the internal types, so the wrappers collapsed to trivial forwarders
+> (and two of the three behavioral types became plain aliases):
+> - **`Stream` is now aliased** (`pub const Stream = agent_mod.Stream`).
+>   `Stream.phase`→`state` and `Phase`→`State` renamed in the impl; `state`
+>   is the one intended-public field (the transparent state machine), and
+>   the rest (`_agent`/`_queue`/`_response`/`_start`/`_persisted`/
+>   `_pending_error`) are underscore-prefixed internal state. `Agent.run`
+>   returns `*Stream`.
+> - **Compaction renamed in the impl:** the pure no-persist transform is now
+>   the private `_compactInPlace`; `compactAndPersist`→`compact` (the public
+>   name, persists by default).
+> - **System-prompt split in the impl:** `addSystemMessage(text, mode)`
+>   became `addSystemMessage(text)` + `setSystemPrompt(text)` (mode is an
+>   internal `_persistSystemMessage` detail).
+> - **`UserMessage` moved to module scope** (off `Agent`); `public.UserMessage`
+>   aliases it.
+> - **Pure-internal `Agent` fields underscore-prefixed:** `_open_stream_fn`
+>   (the test seam), `_auto_compacted`, `_retry_prng`. The method-gated
+>   state (`config`/`registry`/`session`/`conversation`) stays unprefixed
+>   — it backs `setConfig`/`registerTool*`/`conversation()`/`sessionId()`
+>   and is heavily referenced; the door is the method.
+>
+> Result: the `Agent` façade is now **pure 1:1 forwarders** (no renames or
+> merges left). It remains a wrapper only because `init` heap-pins the inner
+> (making the handle copyable / move-safe) and `conversation()`/`sessionId()`
+> are accessors. `Conversation` and `Stream` are aliases.
+
 | bucket | rule | types |
 | --- | --- | --- |
-| **behavioral** | wrap a **pointer** to a heap-pinned internal | `Agent`, `Stream` |
-| **behavioral (pared + aliased)** | trim the real type to the public surface, then alias | `Conversation` |
+| **behavioral (thin wrapper)** | heap-pin the inner; every method a 1:1 forwarder | `Agent` |
+| **behavioral (pared + aliased)** | trim the real type to the public surface, then alias | `Conversation`, `Stream` |
 | **data (read/output)** | **alias** straight through; inspected field-by-field | `Event` (+ nested), `Usage`, `Pricing`, `SessionInfo` |
 | **data (constructed)** | **alias** straight through; Zig users build them with `ArrayList` directly | `ContentBlock`, `Message`, the block types, `Config` family, `ResultPart` |
 
-- 
cgit v1.3