diff options
Diffstat (limited to 'docs/libpanto-cleanup.md')
| -rw-r--r-- | docs/libpanto-cleanup.md | 50 |
1 files changed, 34 insertions, 16 deletions
diff --git a/docs/libpanto-cleanup.md b/docs/libpanto-cleanup.md index 5fb8db3..a495ff5 100644 --- a/docs/libpanto-cleanup.md +++ b/docs/libpanto-cleanup.md @@ -116,18 +116,26 @@ natural there as well.) > (`ResultParts.fromText`/`fromTextOwned`/`deinit`, replacing the freestanding > `textResult`/`ownedTextResult`/`freeResultParts`). > -> **FLAGGED:** the CLI still reaches two internal namespaces — `panto.agent` -> and `panto.conversation` — because it is a *deep* embedder that drives the -> loop below the curated `Agent`/`Conversation` façades: it needs -> system-prompt seeding *through* the agent (`agent.addSystemMessage`), -> `compaction_system_prompt`, the injectable `open_stream_fn` test seam, -> direct `agent.conversation` field access, raw standalone `Conversation` -> values (the façade `Conversation` only wraps a pointer to an agent-owned -> one), and `compactAndPersist`. These two namespaces remain re-exported from -> `public.zig` as a documented deep-embedder escape hatch (not part of the -> stable surface a C-ABI/binding should use). Closing this gap — growing the -> façade with standalone `Conversation` construction and agent -> system-prompt/compaction plumbing — is the natural follow-up. +> **Holes plugged (escape hatch removed).** The deep-embedder gap is closed; +> the CLI now uses **only** the curated `public.zig` surface (zero +> `panto.agent`/`panto.conversation` reaches), and the transitional +> internal-namespace re-exports are deleted. The additions that closed it: +> - **`Agent.init` / `Agent.deinit`** on the public façade (heap-pin the +> inner; the handle is a cheap copyable value passed by-value everywhere). +> - **`Agent.addSystemMessage(text)`** (`.append`) and +> **`Agent.setSystemPrompt(text)`** (`.replace`) — the two `SystemMode`s. +> - **`CompactionConfig.compaction_prompt`** owns the compaction system +> prompt (auto-compaction reads it; the old `Agent.compaction_system_prompt` +> field is deleted). **`Agent.compact(override_system_prompt: ?[]const u8, +> extra)`** falls back to it when the override is null. +> - **`ConversationData`** = the owned conversation value type (what +> `Session.load` returns and `Agent.init` adopts), distinct from the +> borrowed `Conversation` handle returned by `Agent.conversation()`. +> - **`Agent.sessionId()`** accessor. +> +> `compactAndPersist` was an internal detail — the public `Agent.compact()` +> *is* it (renamed, persists by default); the CLI `/compact` command now +> calls `agent.compact(...)`. ## The two jobs the API must serve @@ -165,7 +173,7 @@ pub const OpenAIChatConfig = config.OpenAIChatConfig; pub const AnthropicMessagesConfig = config.AnthropicMessagesConfig; pub const APIStyle = config.APIStyle; pub const ReasoningEffort = config.ReasoningEffort; -pub const CompactionConfig = config.CompactionConfig; +pub const CompactionConfig = config.CompactionConfig; // now owns `compaction_prompt` pub const RetryConfig = config.RetryConfig; ``` @@ -185,9 +193,14 @@ pub const Agent = struct { pub fn setConfig(self: Agent, config: *const Config) void; // swap provider/model between turns pub fn run(self: Agent, message: UserMessage) !Stream; - pub fn compact(self: Agent, system_prompt: []const u8, extra: ?[]const u8) !CompactionResult; // persists + // override_system_prompt falls back to config.compaction.compaction_prompt: + pub fn compact(self: Agent, override_system_prompt: ?[]const u8, extra: ?[]const u8) !CompactionResult; // persists + + pub fn addSystemMessage(self: Agent, text: []const u8) !void; // .append, persists + pub fn setSystemPrompt(self: Agent, text: []const u8) !void; // .replace, persists pub fn conversation(self: Agent) Conversation; // borrowed handle + pub fn sessionId(self: Agent) []const u8; }; pub const UserMessage = struct { text: []const u8 }; // top-level, NOT nested in Agent @@ -201,8 +214,13 @@ Changes from today: longer means rebuilding the whole tool list. - **`UserMessage` is top-level**, defined in `public.zig` (translated to the internal `agent.Agent.UserMessage` inside `run`). -- **`Agent.addSystemMessage` is dropped** — system messages are a - `Conversation` concern (see below). +- **`Agent.addSystemMessage` / `setSystemPrompt` are kept on `Agent`** (they + persist through the turn-path, which a bare `Conversation` mutation does + not). *Updated during implementation:* the plan originally proposed + dropping `Agent.addSystemMessage` in favor of `Conversation`-only system + messages, but the CLI's system-prompt seeding/reconciliation needs the + agent to *persist* the system entry with its `SystemMode`, so the two + agent methods stay (façade `addSystemMessage`/`setSystemPrompt`). - **`compactAndPersist` → `compact`** (persists by default). The pure no-persist transform stays a private internal helper. - **`registry()` / `httpClient`-style accessors not exposed.** |