diff options
Diffstat (limited to 'docs/libpanto-bindings.md')
| -rw-r--r-- | docs/libpanto-bindings.md | 20 |
1 files changed, 20 insertions, 0 deletions
diff --git a/docs/libpanto-bindings.md b/docs/libpanto-bindings.md index 8d803d1..2872fde 100644 --- a/docs/libpanto-bindings.md +++ b/docs/libpanto-bindings.md @@ -170,6 +170,26 @@ Consequences, and why this exact shape: `error`. (`error.StreamExhausted` is *not* used — exhaustion is `null`, not an error; we reserve errors for failures.) +### `Stream.reopen()` — retry a failed turn after a config swap + +When `next()` surfaces a **terminal** error at the provider-open boundary +(e.g. an HTTP 400 because the chosen reasoning/thinking mode is unsupported by +the model), the conversation is left untouched — the user prompt that `run()` +appended is intact and no assistant message was committed. `reopen()` resets +that failed stream back to its turn-open state so the embedder can: + +1. catch the error from `next()`, +2. change the agent config (`set_config`), and +3. call `reopen()` and resume `next()` — re-running the SAME turn against the + new config **without re-appending the user message**. + +This is the binding-portable alternative to calling `run()` again (which would +append a duplicate prompt and persist it). It errors if the stream has not +failed. Exposed at every layer: Zig `Stream.reopen() !void`, C +`panto_stream_reopen(PantoStream*) -> PantoStatus`, Go `(*Stream).Reopen() +error`, Lua `stream:reopen()`. No embedder is privileged: the panto CLI's +adaptive-thinking fallback is built entirely on this public method. + ### `Event` spans the whole turn, not one HTTP response Verified from the code: `Agent.runStep` wraps **multiple** `streamStep` calls |