The remainder of the package-wide sweep's genuine survivors.
view-model.ts `truncate(firstLine(output), …)` -> `truncate(output, …)`
The tool preview keeps its newlines, so a one-line row renders as
several. Every `ls`, every stack trace, every file read breaks the
transcript's layout.
decode.ts drop `|| type === ""`
Survived my OWN earlier test, which asserted only that the frame was
refused. It still is -- but as `unknown_event` with an empty detail
instead of `missing_type` with the key list. The dropped-events row then
blames the engine for sending something unrecognised when what arrived
had no type at all, and a reason that names the wrong failure sends
whoever reads it to the wrong place.
bundle.ts `isMarked` `&&` -> `||`
"half and "half both report as marked-missing, so a translator's literal
bracket reads as a missing key and the report names strings that are
present.
segment.ts `end === 0` -> `end === 1`
A chunk whose only character is a terminator reports incomplete, so
`completedLength` returns 0 and the screen-reader announcement stalls.
CJK writes short sentences; a lone "。" is a whole one.
format.ts `seconds < 45` -> `< 44`, and session.ts `<= 60` -> `< 60`
Threshold and boundary, each the entire contract of its function, and
neither had a value placed on it. format-intl.ts has the same 45s
boundary and is pinned separately -- the two must not drift.
AND THE FIFTH FAKE
`testing/src/fake-http.ts` had no test file. Two of its behaviours are
load-bearing for every engine test written against it:
The route table picks the LONGEST matching suffix, so `/chats` does not shadow
`/chat`. Inverting it silently mis-routes a test to the wrong handler and the
test still passes -- against the wrong thing. I have already been bitten by
this file's suffix matching once this session, when a handler registered for
`/approve` never matched `/approve/{id}` and a test went green without
exercising what it was written for.
And `streamOf` chunks its body deliberately, "because a frame split across
chunks is the normal case on a real network". Emitting an extra zero-length
chunk changes what the SSE reader is exercised with -- and that reader's
pending-CR logic is precisely sensitive to where boundaries fall. A fake that
stops splitting properly can mask the CRLF defect this package shipped once
already.
That is the fifth fake here to get its own tests after being caught
misrepresenting what it stands in for, after setTimer's delay, every's period,
advance's amount, and the fake DOM that appended instead of ordering.
1121 tests on node 22.23 and 24.12. Eight mutations confirmed to fail.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
`engines/` measured 46.7% genuine mutation survival -- more than double the
package average and 4.5x core -- with six of seven survivors on transport
failure or early exit. The last three.
praisonai-ts/engine.ts `if (signal.aborted) controller.abort()` deleted
The `else` branch attaches an abort LISTENER, which never fires for a
signal that went down before it was attached. So a run handed an
already-aborted signal streams to completion and PERSISTS an answer
nobody is waiting for. Reachable through dispose-then-new-run, and
through Stop followed immediately by Send.
praisonai-ts/classify.ts `status >= 500` -> `> 500`
A plain 500 -- the most common provider failure there is -- classifies
as `internal`, whose recovery is `none`. The user is told something went
wrong and offered no way to try again. 502 and 503 are unaffected, so
the boundary lands exactly on the case that matters most.
remote-http/readiness.ts `probe.status !== 200` -> `> 200`
A sub-200 status (100, 101, 199) falls through and is classified from its
BODY, so a websocket upgrade or a "continue" reports ready. The engine is
then offered as usable and every request to it fails.
Each is paired: a live signal must still stream, a 4xx must NOT be transport
(offering Retry for a revoked key can never succeed), and a 200 must still be
classified from its body.
A NEW BREAK MODE FOR THE ENGINE CONTRACT
`start_only` -- a run that opens and then simply stops, with no terminal event
at all. It is now asserted to redden "a run emits start first and exactly one
terminal event last" by name.
Writing it also settled a survivor I had listed as a gap: weakening that case's
`events.length >= 2` to `>= 1` does NOT let a start-only engine through. Nor
does weakening the terminal COUNT as well. The case catches it either way, so
the length assertion is redundant rather than unguarded -- worth knowing, and
worth not chasing.
1107 tests on node 22.23 and 24.12. Three mutations confirmed to fail; the
fourth proved redundant rather than surviving.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The remaining tier-1 survivors from the package-wide sweep.
main.ts `? actionStop : actionSend` transposed
The button READS "Send" while the turn is streaming, and tapping it stops
the run. The line below sets `dataset.action` and is untouched, so label
and behaviour disagree -- and nothing in 1091 tests read the label.
transcript.ts `blocks.slice(0, -1)` -> `slice(0, -2)`
Appending to the trailing text block dropped the block BEFORE it too. Any
answer that keeps talking after a tool call loses the tool row and its
output: the user sees two paragraphs and no evidence a tool ever ran.
a11y/names.ts `row.title === ""` -> `!== ""`
Both directions at once: a real title announced as "Untitled", and an
untitled row announced as an EMPTY accessible name. A nameless row reads
as just "button" and cannot be told apart from the one above it, which
the comment two lines above says is the whole point of the function.
tauri/shell.ts `sameInsets` without `right`
A landscape notch appearing on the right is deduped away as "no change",
so content sits under it after a rotation.
tauri/shell.ts `coerceInsets` requiring ALL four edges
A native side that sends only what moved has every event discarded, and
the insets stay at whatever the first CSS read gave them -- the composer
under the home indicator for the life of the app. Its pair: an EMPTY
payload must mean "re-read the CSS", not "every inset is zero".
WHERE EACH TEST HAD TO GO, AND WHY THAT MATTERS
Two of these could not live in the shared shell contract, and finding out why
was the useful part.
`emitInsets` takes a full `SafeAreaInsets`, so the harness cannot express a
PARTIAL native payload -- which is exactly the input `coerceInsets`'s guard is
about. And the inset dedupe is a Tauri-only optimisation: the fake and web
shells republish an identical payload, so asserting otherwise in the shared
contract failed two of three implementations. I wrote it there first and had to
move it.
A contract can only assert what every implementation owes. Behaviour that is
one adapter's alone needs its own test, and mistaking the two is how a case
either fails for the wrong shells or never reaches the branch at all.
1100 tests on node 22.23 and 24.12. Seven mutations confirmed to fail.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
A package-wide sweep of 154 mutations on current main put genuine survival at
23.8%, against 26.3% originally -- an improvement inside the sampling error,
so flat package-wide. The layer split is the actionable result:
engines 46.7% <-- weakest, 4.5x core
adapters 29.2%
ui 20.5%
app 15.4%
core 10.3% <-- strongest
Six of the seven engine survivors were on TRANSPORT-FAILURE or EARLY-EXIT
paths. The conformance harness covers the happy path thoroughly; nothing
covered these, and a phone spends a disproportionate amount of its life there.
postOk: `if (response.status !== 200) return false` deleted
Every non-200 -- 202, 401, 500, 502 -- reports SUCCESS. The UI announces
a stop that never happened and marks an approval sent that the engine
never received. Both callers were written to trust this boolean.
the reader's `cancel()` in the finally, deleted
On New chat or Stop the consumer breaks out of the loop; without the
cancel the engine keeps generating into a socket nobody drains, and keeps
billing. Proved with a stream that records its own cancellation.
`{ ...parsed.value, type: frame.event }` transposed
A frame whose data object carries its own `type` is then decoded as THAT
type. A delta arriving as an ill-formed `error` is dropped silently, so
text vanishes from the answer with no diagnostic at all.
AND THE CHECKER STOPPED CHECKING ITSELF
`tools/check-boundaries.mjs` walked `.ts` and `.mjs`. Dropping the `.mjs` half
survived: it silently stops walking every .mjs in the package -- and `tools/`
is entirely .mjs -- while still printing "136 files checked, no violations".
That is verbatim the failure boundaries.json's own comment warns about: "a rule
that stops covering new code while still reporting a clean pass is worse than
no rule." The walk is now `sourceFilesUnder(base, roots)` in depgraph.mjs so a
test can call it, following the same move already made for `ungovernedRootsIn`.
ONE TEST OF MINE PASSED FOR THE WRONG REASON
The refusal test registered `http.on("/approve", ...)`, and the fake matches by
URL SUFFIX -- the engine posts to `/approve/{approvalId}`, so nothing matched
and every request 404'd. A 404 is not 200, so the test went green while never
exercising the status check it was written for. Its paired "a 200 with an ok
body IS accepted" case failed, which is the only reason I noticed.
1091 tests on node 22.23 and 24.12. Four mutations confirmed to fail.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The padded-URL case only asserted resolve/reject, so the fake and web shells
forwarded the raw padded string to the OS and still passed — the exact
validate-one-form/forward-another seam the Tauri-specific test was written for.
Surface the forwarded URLs through ShellHarness.forwarded() and assert the
trimmed value, then trim in the web and fake shells to match the port contract.
Co-authored-by: Mervin Praison <[email protected]>
The production-side findings from the same re-measure, verified live against
merged main before any were touched.
main.ts `setChat(mintChatId())` -> `setChat("unassigned")`
"unassigned" is what controller.ts uses to mean "nobody has said which
conversation this is". Shipping it to an engine keying history by chat_id
merges conversations. The existing test only asserted two ids DIFFER --
and the launch id is real now, so a placeholder on turn two passed it.
main.ts delete `input.value = ""`
The sent text stays in the composer, so the next Send tap re-submits the
SAME question. The user double-sends and pays twice, with nothing on
screen to say so.
platform.ts `view.localStorage` -> `view.sessionStorage`
Every chat dies with the tab -- on a phone, every time the OS reclaims
the webview. The file's own comment is about localStorage EVICTION being
the risk; nothing asserted which store it reached for.
web/http.ts `status: response.status` -> `status: 200`
Every 401, 403, 429 and 502 reported as success. The engine reads the
status to choose `auth` vs `transport`, so the whole recovery
distinction -- go to settings, or retry -- was fed a constant. The tests
that DO cover that distinction drive the fake http, so the one place the
real status is read had nothing on it.
tauri/shell.ts `url.trim()` -> `url`
The interesting one. It survived EVERY contract case, including the new
padded-URL case I wrote for it, because a contract can only observe
REJECTION and the allowlist tolerates padding either way. What changes is
what reaches the OS.
A URL validated in one form and forwarded in another is the shape of a
scheme-confusion bypass, and nothing in the suite read what the bridge was
handed. The probe bridge now records it, and the assertion is on the forwarded
string rather than on whether the promise settled. Mutating the forward to pass
the raw `url` instead of `target` also fails now -- so the test observes the
seam, not just the trim.
That is the general lesson of this one: `doesNotReject` proves a call did not
throw. It does not prove the call did the right thing, and for a security
boundary that gap is the whole question.
1085 tests on node 22.23 and 24.12. Six mutations confirmed to fail.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
A re-measure of the regions a previous sweep named. The production rates DID
fall -- main.ts 74.4% -> 28.6%, adapters 44.3% -> 24.1%, i18n 43.8% -> 34.8%,
boot.ts 30.8% -> 22.2%. Those fixes were structural.
The survival moved into the machinery I added to guard them.
THE SHELL CONTRACT WAS COMPLETELY UNDEFENDED
`contract-fixture.ts` registered secrets, storage and time. Not shell -- the
largest of the four, 33 cases, including seven `openExternal` refusals. No
break mode, no floor. Measured: every assertion in it deletable, the whole
security section removable, the entire contract replaceable with
`assert.ok(shell)`, green each time. 57 of 61 assertions across all four
contracts were free; exactly four were load-bearing.
A `javascript:` URL reaching `openExternal` inside a webview is script
execution in the app's own origin with the user's session, from a URL that
routinely arrives from a model, a tool result, or pasted text. The RULE is in
core/src/ports/shell.ts and both adapters call it. What was undefended is the
contract proving they do -- and the next shell, React Native, would be written
against a contract that cannot fail.
Registered now, with three break modes: a shell that opens anything, a back
stack in registration order, and a listener count that cannot see a leak.
Built by wrapping a real web shell rather than hand-rolling a ShellPort, so
the fixture cannot drift from the interface it exercises.
TWO HOLES THE FLOOR HAD
`# SKIP` is reported as `ok` in TAP, so changing `test(` to `test.skip(` on a
security case kept the run green -- a case could be disabled rather than
deleted and the count never moved. The floor now excludes skips and todos.
And the meta-test filtered for `not ok` lines and matched separately, so
neutering the filter let a PASSING line satisfy the assertion: it went green
precisely when the contract stopped catching anything. The prefix is part of
the pattern now.
A CONTRACT CASE TOO WEAK TO CATCH ITS OWN MUTATION
"the most recently registered back handler gets first refusal" registers two
DIFFERENT closures, so `indexOf` and `lastIndexOf` behave identically and the
mutation between them survived in BOTH shells. React StrictMode double-invokes
effects, so the same reference registered twice is ordinary. The new case
registers A, B, A and drops the second A; removing the first instead inverts
the stack and the back press goes to the wrong screen.
WHERE THIS STOPS
Lowering a floor, or rewriting the meta-test's assertion back to its weaker
form, is not caught by anything -- and cannot be without another guard above
it. The regress has to end somewhere. It ends at code review, and this commit
moves the line up: the contracts, the cases, the break table and the skip
counting are all defended mechanically now. Only edits to the guard itself are
not, and those read as what they are in a diff.
1077 tests on node 22.23 and 24.12. boundaries: 136 files, no violations.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The `every no-Intl fallback differs from its formatted twin` control only
compared number/count/date. Elapsed and relative-time render byte-identical in
English through both Intl and the fallback ("1h 02m", "10 minutes ago"), so an
"en" twin can't distinguish the fallback branch from a successful memo(). Added
de-DE twins (comma decimal, native relative phrasing) that genuinely differ from
the ASCII/English en_US fallback, so the control now guards all seven paths.
Co-authored-by: Mervin Praison <[email protected]>
The last of the regions a mutation sweep named. `format-intl.ts` measured 67%
survival for one reason: every `fmt === null` branch is unreachable on a host
with full ICU, which is every host a test runs on. `memo(...)` always returns a
formatter, so seven fallbacks never executed.
They are not exotic old-WebView paths. Every Intl constructor throws
RangeError on an underscore tag, and locale.ts says in its own header that a
stored preference reaches us as "en_US" as often as "en-US". These are one bad
settings value away, in production, today.
Six mutations that survived, and what each shipped:
String(value) -> "" a number renders as nothing
String(whole) -> whole + 1 every count off by one
padStart(2, "0") dropped "1h 2m" instead of "1h 02m", which scans
and sorts wrongly in a list of durations
toFixed(1) dropped sub-10s durations lose their decimal, and
that decimal is the whole reason the branch
exists -- "3s" hides 2.5 from 3.4
slice(0, 10) -> slice(0, 7) every date in the chat list loses its day
and reads as a month
formatRelativeFromStrings "10 minutes ago" becomes "10"
replaced by the raw value
No export was needed, unlike `segment.ts` and `locale.ts` -- these functions
are already public and the fallback is reachable through the ordinary API. The
gap was never structural; nothing had passed a locale that fails.
Each assertion is paired with a check that the FORMATTED output differs from
the fallback, so the block cannot start passing for the wrong reason if
`memo()` ever succeeds for "en_US" or the formatted path degrades.
One of my expectations was wrong rather than the code: I asserted 5.25 seconds
renders "5.2s"; `toFixed(1)` rounds it to "5.3s".
1071 tests on node 22.23 and 24.12. Tests only; no product source changed.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
`app/src/main.ts` measured 74% mutation survival -- the highest of any file.
The tests it had each pinned one previously-reported defect and nothing around
it, which is what happens when tests are written from a bug list rather than
from what the code does.
Eight mutations that survived, and what each shipped:
phase === "streaming" ? "stop" : "send" -> "send"
THE STOP BUTTON NEVER APPEARS. A run cannot be cancelled from the UI at
all; it keeps generating and keeps billing.
keyboardHeightPx -> 0
The composer never lifts above the keyboard. You type behind it.
insets.top -> insets.bottom
The top safe-area is read from the bottom, so content sits under the
notch. Both custom properties were written and neither was checked.
render = diff.next removed
The render state never advances, so every publish re-inserts every row.
A three-delta answer paints as three separate paragraphs of the same
growing text.
transcript.textContent = "" removed
New chat leaves the previous conversation on screen.
input.value.trim() -> input.value
Whitespace-only sends start real turns against the engine.
root.textContent = "" removed (fatal screen)
The crash screen appends UNDER the corpse of the dead UI rather than
replacing it, so the app looks alive and is not.
AND ONE FOUND WHILE WRITING THEM
New chat cleared the transcript and not the live regions. `announcer =
initialAnnouncer` resets the state that decides what to SAY next; it does not
empty the regions themselves. So the previous conversation's answer stayed in
the accessibility tree of what the user believes is an empty chat -- not
announced again, but still there for anyone navigating the page.
I found it because my own test asserted on the whole document text and failed
while the transcript was correctly empty. The test now asserts on the
transcript AND on the regions, which is what it should have done from the
start.
1063 tests on node 22.23 and 24.12. Eight mutations confirmed to fail.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The corpus test's `assert.ok(compared > 20)` hard-failed on a small-ICU
build where `Intl.Locale.textInfo` is absent for most tags -- the exact
host the test's own header promised to skip. Replaced the assertion with
`t.skip()` below the threshold, so a full-ICU host still enforces parity
across ~50 tags while a degraded host reports nothing rather than failing
for the wrong reason.
Co-authored-by: Mervin Praison <[email protected]>
Two findings from a targeted re-measure, both about code that only runs where
no test can see it.
THIRTEEN LANGUAGES RENDERED LEFT TO RIGHT
`direction()` prefers `Intl.Locale.textInfo` and falls back to a table. The
fallback is consulted only when textInfo is ABSENT -- which is never, on any
host a test runs on. So the table could disagree with Intl indefinitely and
nothing would notice.
Asking both and comparing across a corpus: thirteen disagreed, every one of
them RTL by Intl and LTR by the table.
aeb acm ajp apc ary arz five spoken Arabic varieties -- which is what a
phone in those regions actually reports, rather
than plain "ar"
bal glk haz lrc mzn skr Baluchi, Gilaki, Hazaragi, Northern Luri,
Mazanderani, Saraiki
rhg Rohingya, whose Hanifi script is RTL
On an older Android or iOS WebView without textInfo, every one of those got
the entire UI laid out the wrong way round. A prior sweep reported eight; a
wider corpus found five more, which is the argument for the test rather than
the fix: it now asserts the table agrees with Intl across ~50 tags, so the
NEXT drift fails rather than the next audit finding it. Tags this Node cannot
answer for are skipped, so a small-ICU build reports nothing rather than
failing for the wrong reason.
THE FAKE DOM HAD TWELVE UNGUARDED BEHAVIOURS
Every composition-root test rests on `testing/src/fake-dom.ts`, and a sweep
broke it in twelve places with the whole suite staying green: `insertBefore`
appending unconditionally, `insertBefore` not detaching (so a move becomes a
duplicate), `remove()` not removing, buttons no longer satisfying `instanceof
HTMLButtonElement`, `preventDefault()` doing nothing, `style.setProperty`
being a no-op.
Each of those makes a `mount()` test pass for the wrong reason. The
`instanceof` one is the sharpest: `main.ts` reads `disabled` only off
something that passes that check, so a fixture answering false makes every
disabled control look enabled -- and the guard that stops a double-send is
never exercised while its test still passes.
This package has now found FOUR fakes lying about the port they stood in for
-- `setTimer`'s delay, `every`'s period, `advance`'s amount, and a fake DOM
that appended instead of ordering. A fixture with twelve unguarded behaviours
is the fifth waiting to happen, so it gets its own tests rather than being
trusted because the tests using it pass.
Thirteen self-tests. Seven representative mutations confirmed to fail.
`FakeDom` also exposes `make(tag)` now, so a test builds an element directly
rather than reaching through `ownerDocument` -- which is typed `unknown`,
because the app only ever hands it back to the fake.
1057 tests on node 22.23 and 24.12. boundaries: 136 files, no violations.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
A targeted re-measure asked whether the contracts I added last round actually
defend anything. They do not, and neither did the two that came before them.
I deleted `assert.ok(fired >= 2)` from the time contract -- the one assertion
that catches `setInterval` becoming `setTimeout`, which stops every polling
loop in the app after a single tick -- and the suite reported 1035 pass, 0
fail. Fourteen assertions across all four contracts could be deleted for free.
Removing an entire SECTION of the time contract simply reported one test fewer
and zero failures.
The cause is the meta-tests. `contracts.test.ts` has a set named "the contract
catches an adapter that ...", and each one builds a broken adapter and then
RE-IMPLEMENTS the contract's assertion inline. That proves an assertion of that
shape would catch the defect. It proves nothing about whether the contract
still contains it. They are decorative.
This is not a regression in the new contracts. The old storage and shell
contracts have the identical hole, and the whole pattern in that file is the
same shape as the defect this package keeps finding: a mechanism that exists,
is documented, is tested, and is connected to nothing.
The fix already existed one directory over. `engines/src/contract-fixture.ts`
spawns the REAL contract against an engine broken in one named way and asserts
the matching case goes red BY NAME -- written for exactly this reason, with a
comment saying so. The adapter contracts never got it.
`adapters/src/conformance/contract-fixture.ts` is that, for adapters. Six break
modes, each asserted to redden its own named case, plus a `none` control so a
fixture that failed for an unrelated reason -- a syntax error, a bad import --
could not masquerade as proof. It builds its broken adapters INLINE rather than
importing the fakes, because `adapters` may not import `testing` and the layer
rule is right to say so. The boundary checker caught my first attempt.
The break modes are chosen from real defects: two keychain accounts sharing one
credential; an empty string read back as absent; a missing key reading
`undefined`; namespaces colliding; `every()` firing once; a clear that does not
clear.
And a count floor, because the break modes prove a case still WORKS while a
case with no break mode could simply be deleted. It is counted from a real run
of the fixture rather than from source text -- a regex over `test(` would be
satisfied by a case that asserts nothing.
Verified: gutting a case, deleting a case, and deleting the load-bearing
assertion of a case all now fail. Deleting ONE of two redundant assertions
still passes, correctly -- the case retains its power through the other.
1043 tests on node 22.23 and 24.12. boundaries: 135 files, no violations.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Round five, driving realistic SEQUENCES through the real mount() rather than
one action at a time. Two critical defects, one root cause.
`turn` was a controller-lifetime variable. `runTurn` reset `approvals` -- added
last round for exactly this reason -- and never reset `turn`. The only thing
that reset it was a `start` event.
So a turn producing NO start met a state left `ended` by its predecessor:
`apply()` dropped the error as `wrong_msg_id` or `after_terminal`, and
`finish()` returned the PREVIOUS turn untouched because its outcome was
already set. And a turn produces no start for every pre-first-token failure --
401, 403, 500, offline, a refused connection, a wrong baseUrl.
Measured, turn 1 answers and turn 2 gets a 401:
turn 2 text : "first answer" <- the PREVIOUS answer
turn 2 outcome: {"type":"end", ...} <- the PREVIOUS outcome
turn 2 dropped: 1
The user types a second question, taps Send, the composer clears, and NOTHING
HAPPENS. The old answer stays on screen. No error, no retry, no auth prompt,
not even a hint that a run was attempted. Silent, repeatable, permanent. The
default baseUrl is 127.0.0.1:8765 -- the phone itself -- so "engine
unreachable" is the common case here, not an exotic one.
Two amplifiers: the dropped error landed in `carry`, so the next SUCCESSFUL
turn inherited a "1 event could not be read" row blaming itself for its
predecessor; and `send()` publishes before `runTurn` starts, so a stale turn
was painted into what the user believed was a new conversation.
THE SECOND ONE IS THE SAME BUG WITH A WORSE PAYLOAD
New chat clears the screen. It could not clear the controller's `turn`, so the
wipe held only until the next Send -- at which point the PREVIOUS chat's
pending approval reappeared, with live buttons. `setChat` had already cleared
the approvals table, so the row found no entry, rendered `actionable: true`,
and Allow posted the decision to the engine.
The scenario is a user abandoning a conversation BECAUSE it asked to run
`rm -rf /`, starting a fresh chat, typing something unrelated, and being asked
again underneath it.
ALSO FIXED
A turn the user STOPPED rendered as a red "Connection lost" with a Retry
button, and announced "Connection lost" to a screen reader. The catch mapped
every thrown iterator to `transport` without asking whether the abort was
ours: Stop cancels the engine, aborts the reader, and a real fetch then errors
the body stream. The `cancelled` outcome and its "Stopped" notice were
reachable only if the engine's goodbye frame won a race against our own abort,
which it usually loses. Both directions are pinned -- a stream that dies on its
own is still a transport error, because hiding a real network failure behind a
calm "Stopped" removes the retry the user needs.
Every launch's FIRST conversation went to the engine as the literal
"unassigned". `chatId` defaults to it and `setChat` was only ever called by the
New chat handler. Against an engine keying server-side history by chat_id,
every user's first chat on every device was one shared thread. The existing
test asserted only that two chat ids DIFFER, and "unassigned" !== "chat-2"
passes that.
The suite passed 1029/1029 before any of this changed, which is the measure of
how little of it was observed: no test in the package ran a FAILING turn after
a SUCCEEDING one.
1035 tests on node 22.23 and 24.12. Five mutations confirmed to fail.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The last of the sweep's three structural recommendations. Its own words: "items
2, 4 and 41 all hide behind the same blind spot -- the tests read the event
stream and never read back the file."
The blind spot was one line. `engine.test.ts`'s fake persistence is
async record(req) { recorded.push(req); return indices; }
It records the request and THROWS THE ANSWER AWAY, so nothing in that file
could see what actually reaches the repository.
answer = event.text -> +=
survived. `finish` carries the full text and the engine trusts it over the
streamed accumulation, because upstream may normalise and a non-streaming
provider finishes with content having emitted no deltas at all. Appending
instead writes the answer TWICE to disk -- while the screen, built from the
deltas, looks perfectly correct. The user sees a normal answer, and finds it
doubled when they reopen the chat.
Four tests now assert the persisted side, covering both directions: a
normalising finish must win over what was streamed, and a stream with no finish
must still persist what it streamed. Deleting the finish handling entirely
fails four of them.
Same blind spot, second instance:
updated: at -> updated: base.updated
survived, because no test read a chat back across TWO turns. The chat keeps the
timestamp of its first message forever, so a list ordered by `updated` sinks
the conversation you are actively using to the bottom while one you have not
touched in a month sits at the top.
1029 tests. Tests only; no product source changed.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The worst-scoring module in a 226-mutation sweep, and the last of that sweep's
three structural recommendations. `adapters/src/web/time.ts` had no test file
and no contract; every mutation aimed at it survived. What each one shipped:
setInterval -> setTimeout EVERY polling loop in the app fires once and
stops. Readiness polling, the coalescer's flush
tick, elapsed-time updates -- all of it, and the
app reads as merely slow rather than broken.
clearTimer does nothing A cancelled timer still fires, so the publish
gate reopens after it was deliberately shut.
performance.now -> Date.now Elapsed measurements jump backwards when the
clock is NTP-corrected mid-turn, which is
exactly why the port separates the two.
unsubscribe does nothing The interval leaks for the app's lifetime.
Written as a contract because the fake and the real adapter must agree, and
because this port has form: `every`'s period and `setTimer`'s delay were BOTH
found discarded in the fake, in two separate rounds. A test that only ever
drives the fake cannot see it a third time.
Two things the contract had to be honest about rather than paper over:
The fake deliberately uses ONE clock for nowMs and epochMs -- its own header
says so, "safe in a fake and wrong in an adapter". Asserting they differ would
be asserting the fake is broken, so that case is guarded and runs only against
a real-time adapter, where it is the case that matters.
The web adapter targets a browser, and `requestFrame` throws ReferenceError in
Node. The contract supplies requestAnimationFrame rather than skipping the
case. Not having that shim is part of why this adapter had never been
contract-tested at all.
All four mutations now fail by ASSERTION, not merely by timing out -- checked,
because the unsubscribe one also hangs the run (the leaked interval keeps the
event loop alive, which is the resource leak it ships), and a hang is not the
same as a test that says what is wrong.
1024 tests on node 22.23 and 24.12. Tests only; no product source changed.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The sweep's structural finding, and the reason its survivor count did not fall:
almost every genuine survivor lives on a FALLBACK path -- the branch that runs
when the platform is missing something. The suite runs on a Node with full ICU
and no DOM, so the primary path is exercised hard and the degraded path is
never entered at all.
That is one gap, not many independent ones.
`direction()` is `directionFromIntl(tag) ?? directionFromTables(tag)`. On the
test host the first half always answers, so the second half -- the branch that
runs on an older Android WebView without `Intl.Locale.textInfo` -- had FIVE
indistinguishable mutations in it. What each shipped:
RTL_LANGUAGES never matches Arabic, Hebrew, Farsi and Urdu render LTR
script not title-cased az-Arab and ku-Arab render LTR
length test 4 -> 3 ar-Latn and ks-Deva render RTL
The whole UI mirrored the wrong way, or not at all, on exactly the devices most
likely to reach this code.
`sentences()` uses `Intl.Segmenter` whenever it exists, and it always does
here, so `fallbackSentences` never ran. Three mutations survived in it -- one
per failure the file's own header names: splitting on a decimal point,
splitting mid-CJK, and failing to split after a quoted full stop. A fourth
dropped the unterminated tail, which on a host without Segmenter means a blind
user never hears the in-progress end of an answer, and breaks the documented
seam guarantee that slice(0,n) + slice(n) recombine.
Both are now exported and called directly, which is this repo's stated rule --
extract the expression so the test calls it rather than asserting it appears in
the source. Stubbing globals would have worked too; exporting is honest about
what is being tested and does not leave a fixture that can itself drift.
1009 tests on node 22.23 and 24.12. Four representative mutations confirmed to
fail. Product source changed only by two `export` keywords and their comments.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
A 226-mutation sweep against an isolated worktree. 59 genuine survivors, 10
equivalent mutants each proved by differential test rather than asserted. These
are the seven with the sharpest user consequence; the sweep's own structural
recommendation is the next commit.
TWO ACCOUNTS IN ONE SLOT SHARED ONE CREDENTIAL
`adapters/src/web/secrets.ts` had no test file. Collapsing its key from
`${slot}:${account}` to `${slot}` survived everything: adding a second
profile's API key silently overwrites the first, reading either returns
whichever was written last, `has()` answers true for an account never set, and
deleting one deletes both.
Written as a CONTRACT rather than a test of one adapter, matching shell and
storage. The fake and the web adapter must agree on key semantics or a test
that passes against the fake ships a device-only defect. That is not a guess:
in the same sweep the two ports WITH a contract scored best and the two
without scored worst. The mutation now fails three times, once per adapter.
A DISABLED CONTROL STILL FIRED AN ACTION
`if (el.disabled === true) return null` -> `continue`. The walk skips the
disabled element and keeps climbing, so a tap on a greyed-out approval button
reaches the enclosing row and fires THAT row's intent. It is the only thing
between a double tap and a second send, and between a tap on a decision already
in flight and a second decision.
ONE CORRUPT CHAT FILE HID EVERY CHAT AFTER IT
`if (!result.ok) continue` -> `break`. Half the library vanishes with no error
anywhere, and `listUnreadable` still reports only the one bad file -- so the
app is confidently wrong about how much is missing.
A CHAT WITH NO id LOADED SUCCESSFULLY
Dropping `typeof chat.id !== "string"` gives `ok: true` with `id: undefined`: a
row addressed at nothing, absent from `listUnreadable`, and saved back to the
storage key "chats/undefined". The header's rule -- "a chat that fails to parse
is reported, not skipped" -- broken in the one direction nothing checked.
A REFUSED DECISION COULD BE MARKED SENT
`acknowledge` accepting a `failed` entry flips `isActionable` to false and
drops `outstanding` to zero: the buttons die and the run stays blocked on a
prompt the engine never received, until its 300-second timeout. Verbatim the
desktop failure approvals.ts says it exists to prevent.
AN UNMOUNTED SCREEN WAS NEVER FORGOTTEN
Dropping `nodes.delete(id)` makes `live()` lie. screens.ts asks `live.has(next)`
to decide whether to mount, gets a stale yes, and never rebuilds -- a blank
screen with no way back. Its sibling, dropping the `nodes.has` guard, appends a
second copy and orphans the first.
Also covered: a chat id that vanishes between `listIds` and `read` is absent,
not corrupt -- reporting it unreadable shows a permanent corruption warning for
a file that was simply deleted.
999 tests on node 22.23 and 24.12. Tests only; no product source changed.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Mutating the refused-stop fix back was `fail=0`: I had verified it with a
throwaway script and never added a test. Worth recording, because the fix
itself was a regression of my own from two commits earlier -- so the defect had
now escaped twice, once into the code and once past my own verification.
The first pair I wrote was also wrong. `SCRIPTS.happy` finishes on its own, so
whether a run was still live when Stop was pressed depended on microtask
ordering: the refusal test passed because `stop()` returned false for the
BORING reason -- nothing was running -- rather than because the engine refused.
Its sibling then failed and exposed it.
Both now use an engine whose turn stays open until the test releases it, so a
run is genuinely live when Stop is pressed. Three mutations die:
refused stop aborts anyway fail=1
refused stop keeps `cancelling` fail=1
bootOrFail rethrows fail=1
971 tests on node 22.23 and 24.12.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
A round-four audit drove the real `mount()` through a fake DOM for the first
time. Every defect it found is the same shape: a pure function that is correct,
and a composition root that calls it wrongly or not at all. main.test.ts was
30 lines and said so out loud -- "`mount` needs a whole fake SSE transport to
drive end to end, so the parts of it that can be wrong are extracted and called
directly instead". Every one of these lived in the part that was not extracted.
1. EVERY PRE-FIRST-TOKEN FAILURE SAID "the engine produced no output"
`apply()` drops any event arriving before `start`, and both the controller's
synthesised transport error and the engine's synthesised auth error ARE the
first event. So the real reason was thrown away, `finish()` substituted
kind: "empty", and 401, 403, 500, 502, offline, DNS and TLS all rendered
identically -- plus a dropped row accusing the engine of sending an event
before the turn began.
The default baseUrl is 127.0.0.1:8765, which on a phone is the phone itself, so
this was the FIRST thing every new user saw. It also made the auth ->
"go to settings" recovery unreachable: the one distinction between "retry this"
and "fix your credentials" never survived to the view model.
An error is a terminal event; if nothing has started, it IS the turn's outcome.
2. A SCREEN-READER USER NEVER HEARD THE ANSWER
`for (const item of announcements) region.textContent = item.text` overwrites
the earlier items in the same task. A short answer completing inside one
interval produced [polite "<the answer>", polite "Response complete"], so the
user heard only "Response complete." That is verbatim what announce.ts rule 4
exists to prevent -- "the user would never hear the end of the response" --
reintroduced at the single point where the pure function meets the DOM.
3. NEW CHAT DID NOT STOP THE RUN
It cleared the screen and left the turn streaming, so the next token
reconciled against an empty render and re-inserted the previous conversation's
rows into what the user believed was a fresh chat, where it finished.
4. EVERY REQUEST FROM EVERY CHAT CARRIED chat_id "unassigned"
`setChat` was never called anywhere in the app. controller.ts says in as many
words that "an engine cannot tell two conversations apart if every turn claims
the same id"; against an engine keying server-side history by chat_id, every
conversation the user ever had was one thread.
5. A STORAGE FAILURE AT BOOT LEFT A RENDERED, DEAD APP
`createApp` returns a typed BootResult for anticipated failures and THROWS for
a StoragePort failure -- reachable via SecurityError with site data blocked or
QuotaExceededError. The chrome is appended before that await, so the rejection
skipped both the fatal screen and the listener registrations: top bar,
composer, green Send button, and nothing ever happened again. No spinner, no
error, no crash screen.
6. THE CRASH HANDLER WAS INSTALLED AFTER THE THING THAT THROWS
`detectPlatform()` ran first, directly contradicting the comment above the
crash handler. It reads window.localStorage, which raises SecurityError with
site data blocked, and a throw there left the root completely empty.
AND ONE REGRESSION OF MY OWN
`stop()`'s idempotence guard, added two commits ago, aborted the reader even
when the engine ANSWERED FALSE. So a refused stop set `aborted`, and the next
tap returned true without asking the engine again. The user is told the stop
was refused, taps the only affordance offered, and is told nothing at all --
which stopNotice defines as success -- while the run keeps generating. The
defect that notice exists for, inverted, one layer down. A refusal now leaves
the run retryable and the reader attached.
THE HARNESS
testing/src/fake-dom.ts models the DOM behaviours the app actually depends on:
ordering under insertBefore (which DETACHES first, the detail that hid two
ordering defects here), textContent replacing children, delegated event
dispatch, and the three constructors main.ts walks with `instanceof` -- without
which the click listener throws `Element is not defined` and every intent is
lost. That is why nobody had driven the composition root before: the first
attempt fails before reaching an assertion.
Eight tests now drive mount() end to end. Each fix was confirmed by mutating it
back and watching a named test fail.
969 tests. boundaries: 132 files, no violations.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
`publish-gate.ts` is a verbatim port of the desktop's stream-pacing with two
constants tightened deliberately for mobile. It IS called -- controller.ts has
`if (frames.length > 0 && gate(streamed)) publish()` -- but in the shipped
pipeline that condition is almost never true, so neither constant affects
anything.
The cause is the coalescer's flush tick, added three PRs ago to fix answers
arriving in one lump. The tick drains the coalescer every maxDelayMs, so by the
time a delta arrives `push()` usually returns [] and the gate is never
consulted. The tick's own publish is deliberately ungated, which is right --
that frame exists precisely because nothing has painted recently.
Measured by driving the real controller with a virtual clock and counting
whether the gate was consulted even once. The count is exact rather than
inferred: the gate calls requestFrame on its FIRST invocation, so zero frame
requests proves zero calls.
20 tok/s 2004 publishes for 2000 tokens gate consulted: no
60 tok/s 2004 no
150 tok/s 670 no
400 tok/s 289 no
1600 tok/s 80 no
3200 tok/s 42 YES
8000 tok/s 42 YES
The threshold is where 256 bytes land inside one 16ms window. Real model
streaming is 20-150 tok/s, so it is unreachable in practice.
Not currently a defect: paints stay bounded by time, which is the property that
matters, and per-publish view work is under 9% of a frame in the worst measured
case. Recorded because two things follow. There is no backpressure path at all
-- the gate is the mechanism that notices the renderer cannot keep up, and it
never runs. And a module with its own tuned constants that never executes reads
as load-bearing to whoever next touches pacing.
The fix is to wire the tick's publish through the gate or delete the module.
Deciding that is a design call, not a bug fix, so it is written down rather
than done quietly. What is not acceptable is leaving it LOOKING wired, which is
the defect class this package keeps producing.
Docs only.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The documented tail of round three's 49 survivors. I confirmed all seven were
still live by mutating them and, through a mistake in my restore paths, ended
up applying every one simultaneously -- 957 tests still passed with all seven
defects in the tree at the same time. That is a better demonstration than the
one I intended, so it is worth recording rather than tidying away.
count: turn.dropped.length -> count: 1
The dropped row always said "1". `reasons: []` was caught; the count was
not. The reason the row carries a number at all is to distinguish one
malformed frame from a stream that is mostly unparseable.
copy: turn.text !== "" -> copy: true
A Copy button on an empty answer copies an empty string and reports
success -- an action that says it did something and did not.
signatureOf drops ${row.recovery}
The comment two lines above it says exactly why it is there: "the same
message can offer a different action once the engine reports a different
kind". Nothing checked. The row would keep a Retry button after the
engine reclassified the failure as one retrying cannot fix.
signatureOf drops ${row.reasons.join(",")}
Two refusals for different reasons look identical to a count, so the row
keeps naming the wrong failure.
pending.length >= maxBytes -> >
Off by one on the constant the coalescer's whole contract is written
around. No test ever landed exactly on the cap.
formatElapsed `seconds < 10` -> `<= 10`, `minutes < 60` -> `<= 60`
The entire point of a threshold is which side of it a value falls on,
and no test placed a value exactly on one. 60 seconds rendered "60s"
instead of "1m 00s"; 3600 rendered "60m 00s" instead of "1h 00m".
Each is now pinned in both directions -- an unchanged row still produces no
ops, so a signature that changed every time cannot pass by repainting always.
964 tests on node 22.23 and 24.12. Tests only; no product source changed.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The reconciler fix landed, but the harness the PR body describes as proving
it -- a fake DOM with real insertBefore reference-node semantics, and a
reconcile->applyOps ordering sweep -- was never committed. dom.test.ts's fake
still appended unconditionally (a fake that cannot represent order cannot fail
an ordering test), and reconcile.test.ts asserts op shapes without applying
them.
Give the fake real insertBefore/remove semantics and add the exhaustive
prev/target sweep in app/ (the only layer allowed to import both halves),
applying the real ops through the real applyOps and asserting DOM order equals
the target. Verified both ways: reverting the reconciler to the surviving-index
model, or the fake back to append-only, makes the sweep fail. Also asserts the
minimal-op guarantees at the DOM (append is one insert; a settled list is zero
ops).
957 tests pass; boundaries clean; no new typecheck errors.
Co-authored-by: Mervin Praison <[email protected]>
`reconcile` tracked `surviving` -- the previous ids minus removals -- and
spliced each move into it at the TARGET index. Those are two different
coordinate systems: the target index counts rows inserted on this pass, and
`surviving` contains none of them. Inserted rows were never added to it either,
so the model drifted from the DOM as soon as one insert preceded a reorder, and
the emitted ops then described a list nobody had.
Measured by applying the REAL ops through the REAL applyOps to a DOM:
exhaustive, 5 ids, every prev/target pair 120 of 960 rendered wrong
fuzz, 8 ids, 200k pairs 1546 wrong
smallest case [a,b,c] -> [d,e,b,c,a] rendered [d,e,b,a,c]
It now models the list it is actually producing: `current` starts as the
survivors, every insert and move is applied to it, and a row already in place
emits nothing. Both sweeps are 0 wrong. The minimal-op guarantees are intact --
appending to 200 rows is still one insert, an unchanged list still zero ops --
and those are now asserted here too, so a correct-but-rebuilding reconciler
cannot pass by brute force.
WHY NOTHING CAUGHT IT
Two reasons, and both are worse than the bug.
`reconcile.test.ts` asserts the SHAPE of the ops and never applies them. It can
say "a move was emitted for c at index 0"; it cannot say whether running the
ops produces the intended order. The pair is tested here in app/, the only
layer allowed to import both halves.
And the fake DOM's `insertBefore` ignored its reference node and appended
unconditionally. A fake that cannot represent ORDER cannot fail an ordering
test. It now has real semantics, including detaching the node first -- and
mutating it back to appending makes the new sweep fail, so the fake is itself
under test.
That is the fourth fake in this package found lying about the port it stands
in for, after `setTimer`'s delay, `every`'s period and `advance`'s amount.
WHAT I DID NOT KEEP
I first "fixed" this in applyOps by detaching the node before placing it. With
the reconciler corrected, that mutation is `fail=0` -- no test can tell the
difference, because reading `children[op.index]` before `insertBefore` detaches
already names a real sibling. So it went back out. Unverified code that claims
to fix something is the thing this session keeps finding; adding more of it
while removing a bug is not a trade worth making. dom.ts keeps only a comment
saying why the existing line is correct.
Reachability today is low: transcript rows are append-only, so the wrong-order
path needs an insert before a reorder, which the current view model does not
produce. This is a latent defect in a core renderer, fixed before the screens
that would reach it are built.
952 tests on node 22.23 and 24.12.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
A mutation sweep over the whole package found this file the weakest in it:
16 tests, and 15 of 16 mutations survived. The existing tests cover the SHAPE
of every event thoroughly -- and never once pass `versions` other than 1,
`active` other than 0, an absent `assistant_index`, or an empty-string id.
Those are the fields that decide which message the UI selects and which turn
Fork and Delete act on.
Nine mutations now fail. Each was applied and measured first:
`: userIndex + 1` -> `: userIndex` the assistant index points at the
USER'S OWN message, so anything
selecting by it renders the prompt
back as the answer
versions clamp removed `versions: 0` reaches the UI -- a
message existing in zero versions
active floor / ceiling / off-by-one events.ts says an out-of-range index
"selects nothing and the message
renders blank"; this clamp is the
only thing between a buggy engine and
an empty answer bubble
`active ?? 0` -> `?? 1` silently selects the SECOND version
of every message the engine gave no
cursor for. Invisible with one
version, which is why it survived
finite check removed NaN / Infinity accepted for versions,
active, chars and seconds
`!(key in o)` -> `=== undefined` collapses absent vs present-undefined,
the exact distinction this file's own
comment says it exists to prevent
array accepted as tool args every consumer gets an object keyed
"0","1",... -- and args are shown to
the user as the command being approved
`|| raw === "always"` "always allow" decodes to null, so the
button exists, is pressed, and nothing
happens
Two of my first attempts asserted my guess rather than the contract and failed:
present-but-undefined resolves to `null` (not on disk), not to a derived index;
and `approval_response` is not an event -- the choice decoder is a standalone
export. Both tests now assert what the code actually guarantees, which is the
better behaviour in each case.
`versions ?? 1` -> `?? 0` is genuinely EQUIVALENT: the Math.max(1, ...) below
it maps both to the same output. Recorded in the test file so nobody hunts it
as a live survivor.
952 tests. Tests only; no product source changed.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Two defects the final review found in PR #4561's own changes:
- sse.ts recomputed the swallow-CR flag from every chunk, including an
EMPTY one. `"".endsWith("\r")` read false, cleared the flag, and a `\n`
in a later chunk survived as a false frame boundary -- splitting one
CRLF frame into two malformed ones. A chunk with no decoded characters
now leaves the pending-CR state untouched (and clears it only when the
swallow consumed the LF). Regression test added.
- controller.stop()'s `aborted` guard is sequential: two OVERLAPPING
stops (dispose + the Stop button) both pass it before either
engine.cancel resolves, each issues its own cancel, and an honest
engine refuses the duplicate -- reporting a real stop as rejected. The
in-flight cancel is now memoised per run so overlapping stops share one
result. Regression test forces the overlap.
Both new tests were mutation-verified (each fails against the un-fixed
line). npm run check: typecheck clean, boundaries 131 files no
violations, 939 tests pass on node 22.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Round three of multi-agent validation, run against an isolated worktree so
nothing could interfere. It found what the previous two did not, including two
defects that lose or corrupt user-visible work.
1. AN SSE STREAM WITH CRLF LINE ENDINGS SILENTLY LOST CONTENT
`sse.ts` normalised line endings PER CHUNK. A chunk ending in `\r` became
`\n`, and the next chunk's leading `\n` then completed a `\n\n` that was never
a frame boundary -- one frame became two malformed ones.
Measured end to end through the real engine over a CRLF stream:
chunk size 1024 -> "The answer is 42." correct
chunk size 7 -> "The answer " half the answer gone
chunk size 1-3 -> "" + error "the engine produced no output"
Seven bytes is the repo's own test chunk default. CRLF is not exotic: the spec
permits it and any proxy may rewrite to it. A transport bug was rendering as
the model having said nothing.
The first fix held a trailing `\r` back until the next chunk could say whether
it was half of a `\r\n`. That regressed the OTHER legal ending -- a lone-CR
stream ends on `\r` with no chunk after it, so its last frame never completed,
taking CR-only streams from working to silent. Caught by testing all three
terminators rather than only the broken one. The `\r` is now emitted
immediately and a matching `\n` swallowed if one follows.
Verified exhaustively: every one-cut AND two-cut split of a two-frame stream,
for CRLF, LF and CR -- 0 wrong of 5253, 4656 and 4656 -- plus byte-by-byte
delivery for each. The file had a CRLF test and chunk-split tests; it never
had both at once, and the defect lived at exactly one offset out of 103.
2. STOP COULD CRASH THE APP OR CANCEL THE WRONG RUN
`stop()` captured `runId` but `live.abort.abort()` re-read the closure variable
AFTER awaiting the engine -- and cancel is a real network call, so the turn can
settle inside that window:
queue empty `live` is null, TypeError. Both callers reach stop() through
a floating `void`, so the crash handler replaced the whole
app with the crash screen. Tapping Stop at the wrong instant
blanked the page.
queue non-empty `live` is the QUEUED FOLLOW-UP. The engine was asked to
cancel the finished run while the abort killed the new one,
which rendered "the engine produced no output" with Retry --
and stop() returned true, so the UI announced success.
Cancelling "whatever is live" is what runId exists to stop.
The run is captured, not just its id. stop() is also idempotent now: a second
tap re-issued cancel for an already-cancelled run, every honest engine answers
false for that, and stopNotice then announced "the engine did not accept the
stop" for a stop that DID happen -- inverting the defect that notice was added
for two commits ago. The background -> dispose path calls stop() twice by
design.
My first test for this did not reproduce the race at all: the turn had already
settled before stop() ran, so `live?.abort.abort()` survived it. The test now
forces the ordering -- cancel() releases the first turn and waits until the
follow-up has genuinely started -- and the mutation dies.
ALSO CLOSED, each mutation-verified:
- `drainDrops` accumulated into `next`; restarting from `state` each iteration
kept only the LAST refusal of a batch. Every existing test drained exactly
one at a time. The channel exists to make "40% of this stream is
unparseable" visible; keeping one of every N divides that by N.
- `decide()`'s catch could `acknowledge` instead of `reject` and survive: an
approval whose engine call THREW rendered as sent and accepted. The
`ok === false` path was tested; the throw path was not.
- `set()` did not mark a key chosen -- only `load()` did -- so a setting the
user changes IN THE APP was ignored by `chosenStringOr` and the caller's
default won. That is precisely the defect `isSet` was added to prevent,
reachable through the commoner of its two paths.
- An empty-string `engineId`, trivially persisted by a settings field, outrank-
ed the composition root's default and boot died with `unknown_engine ''`.
- HTTP 403 was classified `transport`, not `auth`, so the UI offered Retry
forever instead of sending the user to credentials.
- `createCoalescer(maxBytes, maxDelayMs)` takes two numbers, so transposing
them typechecked and survived: frames would flush at 16 BYTES with a 256ms
delay bound. Same-typed adjacent arguments, the shape that has already
produced one defect here.
- `FakeTime.advance(ms)` could ignore `ms` entirely and leave all 915 tests
green, making every pacing constant reached through it untested. Its tick
period was not enforced either, contradicting the fake's own comment. This
is the THIRD time a fake in this package has been found discarding an
argument its port declares, so the fake now has its own tests rather than
being trusted because the tests using it pass.
937 tests on node 22.23 and 24.12. boundaries: 131 files, no violations.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The triage bot fixed the same leak independently and pushed to this branch
while I was fixing it. Both stop the leak; they disagree about one case, and
the disagreement is real.
bot: dropped: state.phase === "ended" ? [] : state.dropped
mine: dropped: state.carry (drops recorded while nothing was streaming)
The bot's discards the previous turn's list wholesale once it has ended, so a
frame the DECODER refused in the gap between two turns goes with it. Such a
refusal often has no msgId -- that is frequently why it was refused -- so it
cannot be attributed backwards to the turn that just finished. It belongs to
the turn about to open, and losing it quietly is the exact failure this whole
channel exists to undo.
Its test found the case mine had wrong, though: a LATE FRAME FROM THE OLD RUN
(`after_terminal`) is evidence against the old run, and carrying it forward
blames the next answer for its predecessor's mess. `carry` now takes
everything recorded while not streaming EXCEPT `after_terminal`, which is the
one out-of-band drop that is genuinely about the turn just finished.
My own between-turns test did not distinguish the two implementations: it
started from `initialTurn`, so the phase was `idle` rather than `ended`, and
the bot's version passed it. Mutating this file to the phase-only form was
`fail=0` until a test was added that ends a turn FIRST and then refuses a
frame. Another instance of a test observing an adjacent property rather than
the one that matters -- caught only by running the alternative implementation
against the suite.
Both tests are kept, and both implementations now fail:
carry ignores the after_terminal split fail=1
the phase-only fix instead fail=1
carry everything, even mid-turn fail=4
915 tests on node 22.23 and 24.12.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
A second validation pass over the refusal channel this PR adds. The channel
works -- three previously-invisible refusals now reach the transcript -- but
making them reachable exposed two defects that were harmless while nothing
could produce one.
1. EVERY DROP LEAKED ONTO EVERY SUBSEQUENT TURN, PERMANENTLY
`apply`'s `start` case carried `state.dropped`, which at that moment is the
PREVIOUS TURN'S ENTIRE LIST. Its comment justifies carrying pre-start drops --
correct intent, wrong list. Nothing resets the controller's `turn`, so one
refusal on turn 1 made every later turn report itself damaged for the lifetime
of the app. Measured: turn 1 has one genuine refusal; turn 2 is a perfectly
clean stream and still renders it. `new-chat` does not help -- it resets the
renderer, not the controller.
That also made the count meaningless for the thing it exists to express, "this
stream is 40% unparseable", and removed the per-turn bound on an already
quadratic append (`[...state.dropped, x]`): a bad connection refusing 500
frames/s for a minute is ~2s of main-thread work on a phone, and every later
turn then pays for the inherited list on every publish.
`TurnState.carry` now holds only drops recorded while nothing was streaming,
and `start` takes exactly those. Four tests, both directions: a clean turn
after a damaged one shows nothing; a drop BETWEEN turns still reaches the next
one; it is carried once rather than forever; and a drop during a live turn
never enters the carry.
2. FIVE DISTINCT WIRE FAILURES ALL REPORTED THE SAME WRONG REASON
`safeParse` returned `{}` for anything it could not read, and the caller
spreads it and adds `type` -- so an HTML error page from a proxy, a body
truncated by a cut connection, a JSON array, a bare string and `null` all
arrived at the decoder as an object with only a type, and all came back as
`missing_msg_id`. The payload was discarded too, so `detail` could not recover
it. `decodeEvent` gets every one of these right when handed the raw string.
Survivable while rejections were discarded. They are user-visible prose now:
a 502 page from a proxy told the user "an event arrived with no message it
belongs to", pointing whoever they reported it to at an engine msg_id bug that
does not exist. Two shipped strings -- "not valid JSON" and "a value where an
event was expected" -- were unreachable for the same reason.
`parseFrame` returns a discriminated result, so the reason survives and the
detail carries enough of the frame to identify it. One test covers all five.
ALSO, from the same pass:
- `engineId.choices` offered `praisonai-ts`, which `enginesFor` only builds
when `createInProcess` is supplied and main.ts never supplies. Selecting it
persisted an id `selectEngine` then rejects, so the NEXT launch died at
renderFatal with no way back except editing storage by hand. The list is now
what the shipping composition can build, and its test compares against
`enginesFor` rather than against the same two constants the def names --
which is why it could not fail before.
- `adapters/src/web/secrets.ts` claimed "the composition root refuses to hand a
hardware-backed secret to an engine when the transport is not native, and
this flag is half of that check". There is no such check: the flag is read
only by the settings view's warning row, and boot.ts has never consulted it.
Nor is one needed yet -- no secret reaches an engine at all, because
registry.ts never passes the `token` the engine accepts. The comment now says
that, and says where the refusal belongs when the key is wired. Describing a
guard that does not exist is worse than having none: it stops the next reader
looking for one.
- Four settings are declared and consumed by nothing (`model`, `temperature`,
`showReasoning`, `showDiagnostics`). Expected -- their screens do not exist --
and now recorded in gaps.md so nobody concludes they work. `showDiagnostics`
is called out in place because unlike the others it contradicts behaviour
that already exists: the dropped row is rendered unconditionally.
912 tests on node 22.23 and 24.12. Every fix mutation-verified in both
directions.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
apply(start) carried `dropped` across every new start, including one that
followed a FINISHED turn -- so a refusal on turn 1 painted turn 2's clean
answer as damaged. A turn that already ended owns its drops; only a
before_start drop (recorded while idle) belongs to the turn now opening.
Clear `dropped` on a start that replaces an ended turn. Pinned at both hops:
reverting fails one reducer test and one controller test.
Co-authored-by: Mervin Praison <[email protected]>
gaps.md recorded it as knowingly open because closing it needed a channel from
the engine to the transcript that did not exist. It exists now, and the entry
says so rather than leaving a reader to discover the file is stale.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The last defect from the validation pass, and the one left open when #4558
merged because closing it needed a channel that did not exist.
remote-http is the ONLY production caller of decodeEvent, and it did:
const outcome = decodeEvent(...);
if (isDecoded(outcome)) yield outcome.event;
Every rejection went on the floor. So a `tool_result` frame missing its `ok`
-- and `ok` is the only signal of tool success, never inferred from output --
made its tool disappear entirely and the turn rendered as a clean answer with
a shorter reply. Meanwhile `Dropped.reason` already admitted every
IgnoredReason, the view model already rendered a dropped row, there was
already a `showDiagnostics` setting labelled "Show dropped events", and
ui/src/i18n/strings.ts already had a sentence for all seven reasons. None of
it was reachable, because nothing upstream ever produced one.
THE CHANNEL. The engine is built at composition and the controller per app, so
neither can call the other. `core/src/run/drop-sink.ts` sits between them:
the engine notes a refusal, the controller drains onto the transcript. It is
drained per event and again in `finally`, so a refusal arriving beside the
last frame -- or while the stream was dying -- is still shown. Deliberately
not an EventTarget: draining on the controller's own schedule means a refusal
paints with the frame it arrived beside rather than forcing its own publish.
`noteDropped` is the public form of the reducer's private `drop`, because
`apply` can only record events it was handed and a frame that failed to decode
never became one.
Found while writing this: my first drain sat at the end of the `catch` block,
so it only ran when the turn had already failed. The paired test for a refusal
on the last frame caught it. It is in `finally` now, before the turn settles.
WIRED, and proved wired. Eight mutations, one per hop, each now failing:
engine discards refusals again fail=2
engine reports a refusal for every frame fail=2
controller drains but discards fail=3
controller skips the final drain fail=1
sink drains without clearing fail=1
boot does not give the sink to the ctrl fail=1
boot hands engines a dead callback fail=1
registry declines to forward onIgnored fail=1
The last two mattered most. Removing `dropSink` from createRunController, and
dropping the registry's forward, BOTH left the suite green on the first pass:
every hop worked in isolation and the ends were not joined. That is the exact
mechanism-connected-to-nothing this commit exists to undo, reproduced by me
while undoing it. Both are now pinned by composition tests -- one through
createApp, one through the real enginesFor rather than a test double.
Every case is paired, so wiring that invented a dropped row would fail too.
907 tests, 0 failed. boundaries: 130 files, no violations.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
`check (node 24)` failed while `check (node 22.18)` passed on the identical
commit. The prover greps the spawned fixture's output for `not ok`, which
assumes TAP. Node's default reporter differs by version: 22 emits TAP when
stdout is a pipe, 24 emits the spec reporter, so the same failing case prints
not ok 3 - FIXTURE no_start: a run emits start first and ... (node 22)
✖ FIXTURE no_start: a run emits start first and ... (node 24)
The child's exit status was correct on both; only the line the test read for
the case NAME was missing, so the prover reported that the contract failed for
the wrong reason.
The reporter is now forced with `--test-reporter=tap`, so the format is a
decision this test makes rather than a default it inherits.
Reproduced and verified against a real node 24.12.0 rather than assumed: the
default reporter there prints `✖`, forcing tap restores `not ok`, and the full
suite is 895/895 on both 22.23 and 24.12.
This is the same mistake as the ones this branch has been fixing, made by me
while fixing them: a test that observes an incidental property rather than the
thing it means to check. CI caught it because it runs two node versions, which
is the only reason it was visible at all.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
This file exists to record claims that outran the code. It had two of its own.
1. Gap 3 ended "Removing the join removes the opportunity." The join was never
removed -- only the TYPE duplication was. view-model.ts still calls
findApproval(table, pending.approvalId), and replacing that with
`table.entries[0]` passed the entire suite, because every test had exactly
one approval in flight. With two outstanding, the second row rendered the
first's decision: an `rm -rf /` prompt shown as already-allowed against a
decision nobody made. The join is correct and is now pinned in both
directions; the opportunity still exists, and taking it now fails.
2. The closing line said what remained was "the Tauri Rust crate". The crate
exists -- src-tauri/src/{lib,commands,main}.rs, the shell module and two
test files -- with a CI job compiling it on ubuntu-22.04 and macos-15. The
same line silently dropped route->view dispatch, which the body of the file
lists as open and which is still open: main.ts imports neither screens.ts
nor mount.ts and never subscribes to the router, so tapping "Settings"
pushes onto a stack nothing reads.
"Every gap in this file is now closed" is narrowed to "every gap ORIGINALLY
RECORDED in this file", because a later validation pass found fourteen
mutation survivors and three product defects that were never gaps in the sense
this file records. A list of closed gaps is not evidence that nothing is wrong,
and the old phrasing invited exactly that reading.
The remaining-work list is now specific and each item was checked against the
tree before being written -- including that the in-process engine's stated
blocker (bare `crypto` and `events` on the Agent import graph) is already fixed
upstream, so the rationale for omitting that engine no longer holds.
One defect is recorded as knowingly open: remote-http discards decode
rejections, so a malformed frame makes a tool vanish and the turn renders as a
clean answer.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The tool's own header says "a check that silently stops covering anything is
worse than no check". It then did exactly that.
`drift` keeps only output lines mentioning `parity.ts`. When the compiler
could not start at all, the caught error's message is `spawn npx ENOENT` --
which mentions no such thing. Zero drift lines, so:
upstream-parity: the real Agent still satisfies PraisonAgent
exit 0
over nothing whatsoever. Reproduced by running it with npx off PATH.
A tsc that genuinely ran and failed prints diagnostics; a spawn failure, a
missing binary or a killed process prints none. The run is now required to
have either exited 0 or produced `error TS`-shaped output, and anything else
exits 1 saying the check did not run rather than reporting a pass.
Two tests, driven as subprocesses because this is a property of how the tool
is invoked rather than of anything it exports: one empties PATH and requires a
failure whose reason says so and which does NOT also print the success line;
its pair runs with the real PATH and requires the success, so a checker that
failed unconditionally cannot satisfy the first while breaking every build.
Same class as the ungoverned-roots hole fixed earlier on this branch, and the
third instance this session of a checker reporting green over work it did not
do.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
conformance.ts says the suite can fail. conformance.test.ts said each broken
engine "is asserted to fail a NAMED case". Two validators found independently
that neither was true, and I confirmed it: gutting a contract case so it
asserts nothing left all 890 tests green.
`describeEngineContract` was only ever called with CONFORMING engines -- the
scripted fake, praisonai-ts, remote-http. The five can-fail tests build a
broken engine and then hand-run assertions about the REDUCER instead. That is
a real check of the reducer and no check at all of the contract, so the
contract could silently stop checking anything while reporting a clean pass.
This is the exact failure mode tools/check-boundaries.mjs guards against one
directory over, in the file that claims to be the seam's guarantee.
Worse, one of those fixtures cannot fail the suite even in principle: the case
it purports to break is manufactured by `finish()` in the reducer, so it
passes regardless of the engine.
contract-fixture.ts registers the REAL contract against an engine broken in
one named way, selected by argv, and conformance.test.ts spawns it once per
mode -- asserting the process fails AND that the failing line names the case
that mode breaks, not merely that something failed.
no_start -> a run emits start first and exactly one terminal...
tool_failure_as_ok -> a failed tool is reported failed and never inferred...
empty_is_fine -> an empty stream is an error, not an empty answer
decide_always_true -> deciding an unknown approval returns false rather...
A `none` mode is spawned too and must PASS. Without it a runner that reported
failure for everything -- a bad path, a syntax error, a process that never
started -- would satisfy all four assertions while proving nothing.
Verified by gutting each of the four cases in turn: every one is now caught,
where every one previously passed.
NODE_TEST_CONTEXT is stripped from the child. Left in place, the spawned
fixture believes it is a worker of the parent run and reports through it
rather than printing its own verdict, so the output the test reads carries no
result -- which is how the first version of this passed while measuring
nothing, and is the same class of bug it exists to catch.
HONEST LIMIT: four of the contract's twenty-one cases have a prover. The
remaining seventeen can still be gutted silently. Adding a mode per case is
mechanical; the mechanism is here and the four highest-value rules are the
ones covered -- start-first, ok-is-the-only-signal, empty-is-an-error, and no
false success on an unknown approval.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Two product defects. Not test gaps -- the app did these wrong on a device, and
no test could reach either.
1. THE ENGINE WAS BUILT WITH A STUB THAT ANSWERED undefined
main.ts built the engine list with `facadeStub()`, whose `get` returned
undefined for everything, and the engine closed over it at boot. The stub's
own comment said it was "replaced by the real one immediately after". It was
not: nothing rebuilt the engine.
So settings were loaded from disk at boot purely to be discarded. A user's
engine address fell back to the hardcoded http://127.0.0.1:8765, and
`engineId` -- a declared setting, with a `choices` list a picker renders --
was ignored outright, because main.ts passed the literal "remote-http".
createApp now builds the real facade before selecting the engine, which it
could always have done: settings load first precisely so the engine choice and
its credentials come from them. The factory takes `(persistence, settings)`,
facadeStub is deleted, and the persisted engineId is preferred over the
caller's default.
An existing test caught the first attempt, and was right to. Reading the value
with `get()` alone let a def's DEFAULT outrank the caller's explicit argument
-- `get` returns the default for a key nobody ever touched, which is
indistinguishable from a deliberate choice. That is the same class of bug in
the opposite direction: a setting nobody set silently overriding the thing
that asked. The store now tracks which keys came from storage or an accepted
`set`, and `chosenStringOr` consults `isSet` before preferring one.
2. STOP CONFIRMED A CANCELLATION THE ENGINE REFUSED
The controller returns the engine's own answer, and both the scripted engine
and the conformance contract go out of their way to keep that boolean honest
-- "a Stop button that confirms a cancellation which never happened is worse
than one that reports it could not."
The one caller discarded it. The button label flips off `turn.phase`, which
settles either way, so a refused Stop looked exactly like an accepted one
while the run kept generating and kept billing. It is now announced in the
assertive live region. The decision is extracted as `stopNotice` so a test
calls it -- driving `mount` end to end needs a whole fake SSE transport, and
this is the part that can be wrong.
Every mutation pinned in both directions.
STILL OPEN, deliberately not fixed here: the remote-http engine discards
decode rejections (`if (isDecoded(outcome)) yield`), so a malformed frame
makes a tool vanish and the turn renders as a clean answer. The reducer's
Dropped type, the view model's dropped row and seven user-facing strings are
all unreachable because of it. Fixing it needs a channel from the engine to
the transcript that does not exist yet; half-wiring it would be the same
mechanism-connected-to-nothing this commit is undoing.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Three more survivors, found by a validation pass and confirmed by mutation
here before anything was written.
view-model.ts approvalRow -- `findApproval(table, pending.approvalId)`
replaced by `table.entries[0]`. Its own comment says "Looked up by approvalId
in both -- never zipped by index", and the whole approvalId design exists to
stop position-pairing. It survived the entire suite because every existing
test has exactly ONE approval in flight, where the first entry and the right
entry are the same object.
With two outstanding, the second row renders the first row's decision: an
`rm -rf /` prompt shows as already-allowed, with dead buttons, against a
decision the user never made. The defect the design prevents, reintroduced at
the last hop before the DOM. Both directions are pinned -- an approval with no
entry of its own must render pending rather than borrow a stranger's.
dom.ts -- `el.dataset["status"] = row.status` hardcoded to "ok", and
`durationKnown ? durationLabel : UNKNOWN` collapsed to the label. Both
survived. The ok-is-the-only-signal chain is airtight through decode, the
reducer and the view model -- every mutation aimed at those dies -- and then
the attribute the CSS keys off was written by nothing that checked it. A
failed tool rendered with the success styling. `seconds: null` means the
engine never observed the call begin, which is not zero; rendering the label
regardless states a duration that was never measured, and that invariant was
written in a comment two lines above code nothing tested.
Each pinned in both directions, so a test that catches one mutation is not
satisfied by code broken the opposite way.
Tests only; no product source changed.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The earlier fix here moved the length check BEFORE segmentation, which made
short input 42x faster. It does nothing for the case that actually hurts: at
the real call site `max` is PREVIEW_CHARS = 120, so any long output always
overflows the check and always paid full segmentation anyway.
`buildTranscript` re-derives every tool preview on EVERY publish, roughly
thirty times a second during a streaming answer. One tool returning 40kB of
single-line JSON -- an API response, fetched HTML, a minified file, base64 --
therefore cost ~10ms per publish on a laptop, and a phone is 3-5x slower, so
that one tool blows the frame budget on its own. `firstLine()` rescues the
multi-line case; single-line output gets no such reprieve.
Only `max + 1` clusters are ever needed: `max` to keep, and one more to learn
whether anything was cut. `Intl.Segmenter.segment()` returns a LAZILY iterable
Segments -- `Array.from` is what forces the whole string.
10kB one line 9.7ms -> 0.04ms 61x
40kB one line 9.7ms -> 0.05ms 197x
200kB one line 47.9ms -> 0.12ms 407x
Byte-identical to the old implementation over 50,010 differential cases: 21
hand-picked (ZWJ family emoji, skin-tone modifiers, regional-indicator flags,
Devanagari conjuncts, max of 0/1/NaN/Infinity) plus 50,000 randomised.
The regression test is timed rather than counted, because the segmenter is not
injectable. The threshold has ~170x headroom over the fixed implementation and
still fails the revert by more than 2x. Both reverts were confirmed to fail it.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
A second audit pass, this time asking what the FAKES excuse rather than what
the tests assert. Five more mutations survived the suite; all five now fail.
The root cause for three of them: TimePort declares `setTimer(cb, ms)` and
`every(ms, cb)`, and both fakes accepted the callback and threw the delay
away. A fake that takes fewer arguments than its port silently excuses every
caller from getting them right.
publish-gate setTimer(reopen, UNPAINTED_REOPEN_MS) -> setTimer(reopen, 0)
The gate reopens on the next macrotask: publish per token,
which is the entire thing the module exists to prevent. It
survived even the file's own positive control, because that
control never involves a timer.
controller every(maxDelayMs, ...) -> every(60_000, ...)
The coalescer's flush tick runs once a minute. This restores
verbatim the defect fixed three commits ago -- a short answer
arriving in one lump with zero intermediate paints -- and the
test written for that fix did not notice, because the fake
fired every callback on every tick regardless of period.
`FakeTime.tick()` now fires only the intervals whose period has actually
elapsed on the fake clock, so the period is load-bearing in every existing
test rather than in one bespoke assertion. `FakeScheduler` records the delay
it was armed with, and the gate's is asserted against the constant AND
against zero -- pinning it to the constant alone still passes if the constant
itself is set to 0, which is the same shipped behaviour.
coalescer `if (pending === "") openedAt = nowMs` -> unconditional
Every arriving token restarts the delay budget, so on a device
-- where tokens arrive continuously -- `waited` never reaches
maxDelayMs and text paints only at the byte cap. The existing
trickle test pushes ONE token, which makes the two versions
identical. It needs more than one drop to be a trickle.
boot.ts delete the lifecycle subscription, or background -> active
`assert.equal(stopped || true, true)` is true for every value
of `stopped` -- and `stopped` was in fact false: the test never
started a run, so `controller.stop()` returned early and
`cancel` was never reached. The comment beside it shows the
assertion was neutralised rather than the setup fixed.
The turn is now genuinely in flight before backgrounding, and
a paired test proves only `background` stops it -- otherwise
every resume notification would kill the turn on screen.
Tests and fakes only; no product source changed.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
boundaries.json has said this since the day it was written:
"governedRoots exists so a NEW top-level directory is reported as ungoverned
rather than silently exempt. A rule that stops covering new code while still
reporting a clean pass is worse than no rule."
Nothing implemented it. governedRoots was only a list of directories to WALK,
so a directory absent from that list was never visited. Adding features/ and
importing both '@tauri-apps/api' and 'praisonai' from it -- the two seams the
whole layer arrangement exists to defend -- still printed "126 files checked,
no violations" and exited 0.
That is the failure the fixtures in depgraph.test.mjs exist to prevent, one
level up: not a rule that gets an answer wrong, a rule that reports success
over code it never looked at.
The scan is now ungovernedRootsIn(root, config) in depgraph.mjs, following the
note at the top of check-boundaries.mjs -- the rule's logic stays a library
tests can call. It takes root as an argument so the tests point it at fixture
trees rather than mutating the real one. check-boundaries.mjs runs it before
the walk and exits 1 with the two ways to resolve it.
ungovernedRoots is the other half: tools, src-tauri and docs are now
deliberately declared exempt. Listing a directory is a decision someone made;
not listing one is caught.
Seven tests, including a shallow-scan case (features/a/b/c/x.ts), a no-source
case so docs/ cannot cry wolf, and one asserting the real boundaries.json still
accounts for every directory on disk -- which is the test that will fail on
somebody's future branch. Verified against three broken implementations:
always-[], report-everything, and shallow-only.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Two more mutation survivors, both silent.
controller.ts: `ok ? acknowledge : reject` collapsing to always-acknowledge.
The engine reports that it did not accept a decision -- it restarted, or the
approval expired -- and the row still renders resolved. The user sees their
Deny confirmed against a command the engine never denied, which is the one
failure the approval table exists to make visible. Both directions are now
pinned: an always-reject controller trips three tests.
settings/store.ts: the secret guard inside persist(). Deleting it survived
because nothing can reach it -- `set` refuses a secret-flagged key and `load`
drops one, so through the public API no secret ever enters the map. That is
precisely why it needed a test: an unreachable guard is one nobody notices the
deletion of, and it is the last line between an API key and a plaintext
settings file the day a new write path forgets the rule.
The guard is now `plainOnly(values, byKey)`, following the rule this file
already states -- extract the expression so a test can call it rather than
asserting it appears in the source. Behaviour is unchanged; persist() calls
the extracted function. A falsy-value test pins the other half, since a
truthiness filter here would reset every disabled toggle on the next load.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
FakeTime.advance mutated its own offset with no monotonic guard, while the
createFakeClock it composes throws on a negative advance. A mistaken negative
advance silently rewound nowMs -- a state a monotonic TimePort never produces --
letting a pacing test pass or fail for the wrong reason. Guard it the same way.
Co-authored-by: Mervin Praison <[email protected]>
A mutation run over the package found five files that no test executes at
all -- they are wiring, so nothing imports them, and the suite was green
with them arbitrarily broken. Four survivors, each silent on a device:
app/src/platform.ts -- always returning the web shell. An on-device build
falls back to the browser shell: no safe-area insets, no OS back gesture,
no lifecycle. It looks like it works.
adapters/src/web/http.ts -- deleting `signal: request.signal`. Stop reaches
the engine and never reaches fetch, so the request keeps streaming and
keeps billing after the user cancelled.
adapters/src/web/http.ts -- flipping sendsFromNative to true. That flag is
the claim that an API key does not enter the webview heap; nothing checked
the claim against the adapter making it.
core/src/chat/session.ts -- transposing the two same-typed arguments of
persistenceFor's record(). Every stored conversation gets the user's
message and the model's reply the wrong way round, and a transposed
transcript still renders and still round-trips.
Each test was confirmed to fail against its mutation before being kept.
Tests only; no source file changed.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The coalescer has two bounds: flush at maxBytes, or flush after
maxDelayMs. Only the first was ever connected. `coalescer.tick()` was
never called, and `TimePort.every` -- whose own doc comment calls it
"the coalescer's flush tick" -- had zero call sites outside tests.
So the time bound never fired. Measured before this: a 130-character
answer produced ZERO intermediate paints and arrived in one lump when
the run ended, making time-to-first-visible-token the whole answer's
latency. A long answer advanced in 256-character jumps roughly every
420ms. The publish gate's MAX_HELD_CHARS = 96, tightened deliberately
for mobile with a comment explaining why 256 was too coarse, never bound
either -- the coalescer upstream was already withholding more.
In an app whose stated first priority is streaming performance, the
streaming was not connected.
The tick is stopped in `finally`, before anything else: one firing after
the turn settled would paint into a finished transcript and keep a timer
alive for the app's lifetime.
Its frame is deliberately NOT gated. The gate skips intermediate paints
when the renderer cannot keep up; this frame exists precisely because
nothing has painted for maxDelayMs, so gating it reintroduces the stall
it was added to prevent.
WHY NO TEST NOTICED: testing/src/fake-time.ts implemented `every` as
`() => () => {}`. A fake that cannot observe the thing it stands in for
makes every test using it pass for the wrong reason. It drives real
interval callbacks now, and can advance the clock.
And my first attempt at the test was itself vacuous -- it asserted "more
than one paint carried text", which the `end` flush satisfies with the
tick removed. The assertion is on PARTIAL text now: without a tick the
text goes straight from "" to the whole answer. Verified by removing the
tick again: it fails.
838 tests, boundaries clean.
Two findings from an adversarial audit. The first is the most serious
thing found in this package.
app/src/dom.ts HAD NO TEST AT ALL. Changing `el.textContent = row.text`
to `el.innerHTML = row.text` left all 830 tests passing. Model output,
tool results and summarised web pages all flow through that line, so the
file's own header -- "makes that structurally impossible rather than
depending on an escaping function nobody re-reads" -- was guaranteed by
nothing.
The only thing in the suite that mentioned applyOps asserted the BUNDLE
CONTAINED THE SYMBOL. Rename it and that breaks; gut its body and it
passes. That is the shape of a test that looks like coverage and is not.
Six tests now, and they kill what survived: the innerHTML swap fails 2,
and `b.disabled = false` -- the guard that stops a double tap sending
two decisions for one approval -- fails 1. Both verified by re-applying
the mutation.
TRUNCATE SEGMENTED BEFORE CHECKING. `graphemes(text)` ran over the whole
string, then the length check discovered it had not been needed. A code
unit count is an upper bound on graphemes, so the check can come first.
Measured: a 20-character preview went from 8.83us to 0.21us, 42x. It
matters because buildTranscript re-derives every tool preview on EVERY
publish -- with eight 40kB tool results that was 44ms per publish and
~361MB of transient allocation across one turn, to regenerate previews
that had not changed since the tool returned.
839 tests, boundaries clean.
test_the_recorded_pid_owns_the_trainer_signalable_by_group failed in CI with
AssertionError: recorded pid 2568 does not own the trainer
(trainer's parent is )
assert '' == '2568'
and it blocks unrelated pull requests when it does.
The stand-in trainer records its parent with
ps -o ppid= -p $$ | tr -d ' ' > trainer_ppid
and the wait loop broke as soon as all three files EXISTED. Shell redirection
creates its target before the command on the left produces a byte, so
trainer_ppid exists and is empty for as long as `ps` takes to run. The loop
saw it, stopped waiting, and compared '' against the recorded pid.
It is not a slow machine and not a short timeout -- the window is the runtime
of `ps`, so a longer wait does not help. Waiting for CONTENT does.
Measured on the same shell shape, 300 trials each:
existence-only (before) read an empty value 296/300
content (after) read an empty value 0/300
The real loop polls at 100ms, which usually outlasts `ps` -- which is why this
passes most of the time and fails under CI load rather than every run.
The emptiness check is also asserted separately from the ownership comparison,
so a genuine timeout reads as "the trainer never recorded its parent" instead
of masquerading as the ownership bug this test exists to catch.
Separately, and NOT fixed here: this test is unsafe to run on a host without
`setsid` (macOS). The launch script cannot make the wrapper a group leader,
so the wrapper stays in pytest's process group and the test's
`os.killpg(os.getpgid(recorded), SIGTERM)` terminates the test runner itself
-- pytest exits -15 before reporting. On Linux CI `setsid` exists and the
group is isolated, so this does not affect the pipeline. Flagged for whoever
owns this suite; fixing it is a design choice about how the test spawns.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The rust shell job ran cargo test/clippy directly, but tauri::generate_context!
expands frontendDist (../dist) at compile time and dist/ is gitignored -- absent
on a fresh checkout. Both matrix jobs failed to compile before any test ran.
Add setup-node + npm ci + npm run build to create ../dist first.
Co-authored-by: Mervin Praison <[email protected]>
Found by an adversarial validation pass. Two problems, and the second is
why the first survived.
THE BUILD IS BROKEN. capabilities/default.json names a permission
`allow-back-gesture-result` that does not exist, so tauri-build fails
before anything compiles:
Permission allow-back-gesture-result not found
An app command registered through invoke_handler is always reachable and
has no ACL entry to grant -- only plugin commands do. Removed, with the
reason recorded in the file's own description so it is not re-added.
NOTHING WOULD HAVE CAUGHT IT. mobile.yml's path filter already triggers
on src-tauri changes and it has no cargo job at all -- so a crate with
14 tests had none of them run, and a crate that does not compile merged
green. That is precisely the failure this workflow's header says it was
created to prevent, one language over.
The new `shell` job runs cargo test and clippy -D warnings on
ubuntu-22.04 AND macos-15. Both, because the crate is cfg-heavy: the
back-gesture fallback is #[cfg(target_os = "android")] / ios /
not(mobile), and a cfg mistake compiles perfectly on whichever host you
happened to try.
Clippy then caught something real in my own test: asserting on a const
inside a test is compile-time-known, so it proved nothing at runtime.
The floor is a const assertion in the source now -- lowering
ANSWER_TIMEOUT_MS stops the crate compiling rather than failing a test.
Verified by lowering it to 50: E0080, build refused.
14 Rust tests, cargo check clean, clippy clean with -D warnings.
- add src-tauri/capabilities/default.json so the main webview can
subscribe to the four shell events (core:event) and invoke
back_gesture_result; without a capability Tauri v2 silently rejects
these, disabling the entire shell contract (Greptile P1).
- shell-seam.test.mjs: use fileURLToPath(import.meta.url) instead of
URL.pathname so the test resolves on Windows checkouts, matching the
sibling check-boundaries.mjs (Greptile P2).
Co-authored-by: Mervin Praison <[email protected]>
The Rust side of the two seams. Everything the app does lives in the
webview; this crate exists to tell it four things a browser cannot know
and to act on the one answer it sends back.
THE EVENT NAMES ARE A CONTRACT, and a rename is silent: the webview
simply stops receiving that event and lays out as though the phone had
no notch, no keyboard and no lifecycle. Nothing throws. So there are two
guards -- a Rust test pinning each constant to a literal, and a Node
test that READS both sources and compares them, catching a rename in
either language. Verified by renaming one on the Rust side: both fail.
BACK-GESTURE ARBITRATION is the piece with real failure modes, and it is
pure with the platform injected, so all of them are tested on a laptop:
- The answer may never come. bridge.invoke swallows every rejection on
the TypeScript side, so silence is indistinguishable from success --
a bundle that failed to load would leave a back button that does
nothing FOREVER, which is worse than one that exits. Hence a
watchdog.
- There is no correlation id. The webview sends { handled } and
nothing else, so two presses close together produce two answers Rust
cannot tell apart, and the second could pop an activity the first
decided to keep. Dropping while pending is the only correct option
on this side of the frozen contract.
- A late answer after a timeout must not fall back twice. That is the
bug this design is most likely to ship, and it has its own test.
LIFECYCLE maps Suspended to "background" rather than "inactive", and the
comment says why rather than leaving it to be rediscovered: boot.ts only
flushes on background, and on iOS the app can be killed while suspended
with no further callback. Mapping to inactive would lose the transcript
on every backgrounding. The cost -- a control-centre pull-down stopping
the run loop -- is the cheaper mistake.
panic = "abort" is deliberately NOT set, unlike the desktop crate:
mobile_entry_point wraps the app in catch_unwind, and abort turns a
readable message into a bare SIGABRT on a device with no console.
Icons are generated placeholders in the product's own accent colour,
written by hand as RGBA because Tauri rejects RGB.
14 Rust tests, 830 TypeScript tests, boundaries clean.
- view-model: an approval kept from an ended turn (resolved) now renders
non-actionable even though its decision-table entry stays pending, closing
the P1 where a finished run could still submit/retry a decision it can no
longer deliver.
- strings: route droppedEvents through a module-level enDroppedReason instead
of the sibling en.droppedReason, since bundle.ts lifts each string function
off the table and there is no reliable `this` (Greptile P2).
- test: cover an ended-turn approval rendering as history, not a live prompt.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
None of them blocked shipping, which is exactly why they sat. Two were
one bad day away from mattering.
GAP 2 -- settle() deleted the approvals, so a finished transcript could
never say "you were asked to allow rm -rf / and the turn ended first",
which is the thing a reader most wants to see afterwards. They are kept
now and marked resolved: NOT ACTIONABLE rather than NOT RECORDED. The
pair test is the one that matters -- marking everything resolved would
satisfy the audit-trail case while making every live prompt
unanswerable.
`resolved` is optional rather than required, and the reason is in the
type: absent IS the answer for every approval that has not been settled,
which is all of them until a turn ends. Writing `resolved: false` at a
dozen construction sites would be noise carrying no information, and
noise is where a real value gets mistyped unnoticed.
GAP 3 -- ApprovalEntry is now literally PendingApproval & { state }. The
duplication forced the view model to join the two by approvalId at
render time, and that join is where index-pairing gets reintroduced --
pairing an approval by position is the defect the whole approvalId
design exists to prevent. Removing the join removes the opportunity.
GAP 7 -- a dropped event said `wrong_msg_id` to a user, which tells them
nothing. It reads as a sentence now AND keeps the tag: translating the
tag away would make the one searchable string in the message
unsearchable for whoever they report it to. An unknown tag passes
through rather than becoming "unknown reason", because a newer engine
can invent one and the tag is then the only information present.
Verified by reverting each: emptying the approvals again fails 2 tests,
returning bare tags fails 3.
An existing test also caught me adding a string key with no sample call,
which is the guard working exactly as intended.
826 tests, boundaries clean. Every gap in docs/gaps.md is now closed.
The wrapper now backgrounds the trainer and records the trainer's own pid
($!) instead of the wrapper shell's, so stop() sends SIGTERM to the process
actually doing the work rather than a sh -c wrapper that never forwards it
(which orphaned the run). The wrapper program is quoted once with shlex.quote
for the outer shell, so a stray apostrophe or metacharacter in the workdir or
dataset name can no longer close the sh -c string and rewrite the command.
Updated the regression test to assert the recorded pid IS the trainer and that
a TERM to it actually stops the trainer, and to kill all descendants on exit.
Addresses Greptile P1 (stop non-forwarding), P1 (nested quoting), P2 (test leak).
Co-authored-by: Mervin Praison <[email protected]>
_launch_script recorded $! from the outer shell -- the transient subshell
that backgrounded the whole `&&` list -- not the process that owns the
trainer. status() then read `unknown` for a live run and stop() signalled
the wrong pid. The wrapper now records its own pid from inside (echo $$),
and a brace group with </dev/null releases ssh's stdin/stdout so the launch
returns immediately.
Co-authored-by: MervinPraison <[email protected]>
Addresses Greptile P1: after SIGTERM to the group, stop() checked only the
recorded wrapper pid. A wrapper can exit while a child (dataloader worker,
torchrun rank) survives SIGTERM, so stop() reported "stopped" while paid GPU
work continued. Re-probe now scans the whole process group; "stopped" means
no member of the group remains. Adds a test where the wrapper exits and a
SIGTERM-trapping child survives — stop() must raise, not lie.
Co-authored-by: Mervin Praison <[email protected]>
Pinch-zoom shrinks visualViewport.height below innerHeight exactly as a
software keyboard does, so readKeyboardHeight reported a phantom keyboard
the moment a page was zoomed -- most visibly at construction, where a page
opened already zoomed seeded a positive height and pushed the composer up
on the first frame. A software keyboard never changes scale, so scale > 1
is zoom, not a keyboard; guard on it and report 0.
The live publishKeyboard path now reads through the same readKeyboardHeight
function, so the clamp and the zoom guard live in one place and cannot drift
between the first frame and every frame after it.
Positive control: fake-window gains setZoom(scale); reverting the guard fails
the two new tests. Documents the remote-http persistence scope in gaps.md so a
reviewer's finding is not later read as an oversight.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
The view models existed and nothing mounted them: the app rendered one
hard-coded transcript and the router drove nothing.
The decision layer is pure, and it is pure for a specific reason -- the
cases that matter are about what should be KEPT, and a test that can
only inspect a DOM cannot tell "rebuilt identically" from "left alone".
The chat screen is retained; the others are not. Rebuilding the
transcript on every return from settings throws away every row node and
the scroll position with it, so a reader who scrolls up, checks a
setting and comes back is dumped at the bottom of the conversation. That
is the most annoying bug a chat app can have and it is invisible to a
test that only asserts the right rows are present afterwards.
Retention is a cost, not a default: a retained screen holds its DOM for
the app's lifetime. Worth it for a live transcript with scroll state,
not for a settings form that should re-read its values on entry.
Mount happens BEFORE hide, so no navigation shows an empty frame.
A mutation run caught a vacuous test of my own here, and it is worth
recording. The fake DOM logged append and remove but not visibility --
so reordering hide before mount changed nothing it could see, and the
test named "mounting happens BEFORE hiding" asserted nothing at all. The
fake records show/hide now and the mutation fails it.
Other mutations caught: destroying a retained screen instead of hiding
it fails 2, unmounting a retained screen fails 1, and treating
same-route as always-noop fails 1.
816 tests, boundaries clean across 123 files.
A workdir like `-rf` passed the character-class check but would be parsed
as an option by the remote mkdir/cd. Add `--` to end option parsing so it
is always treated as a path; tilde expansion is unaffected since the shell
expands `~` before either command sees the argument. Adds a regression test.
Co-authored-by: Mervin Praison <[email protected]>
A reviewer amended gaps 4 and 5 back to open after I marked them closed,
and was right on both. The same mistake twice: a mechanism existing is
not a mechanism working.
GAP 4 -- "mechanism landed, not wired". createSession was called.
RunPersistence.record was called. Nothing connected them, and the two
signatures did not even line up -- record(prompt, answer) against
record(request, answer) -- which is why it went unnoticed. So record()
never ran in a real turn and no conversation was ever saved, while the
gap read as closed from either end.
persistenceFor() is now the named adapter where the two vocabularies
meet. Naming it rather than inlining a lambda at the call site is
deliberate: this is the one place they touch, and a lambda buried in
composition is a seam nobody finds later.
AppDeps.engines is now a FACTORY taking the persistence, so there is no
way to obtain the engine list without being handed the thing engines
write through. A pre-built array was the original bug; the type refuses
it now. That change surfaced every unwired call site immediately, which
is the argument for making it a type rather than a convention.
The session is also built BEFORE engine selection, because the engine
writes through it.
GAP 5 -- "property added, snapshot not seeded". keyboardHeightPx was
declared = 0 and only ever updated by an event, so a component mounting
while the keyboard was already up laid out at 0 for one frame and then
jumped: precisely the bug the synchronous property was added to prevent.
Seeded from visualViewport at construction now.
Both verified by positive control -- reverting either fails a named
test. 798 tests, boundaries clean.
RemoteRunner.stop() killed only the recorded pid -- the wrapper shell -- so
the trainer's children (dataloader workers, torchrun ranks) survived on the
GPU, reparented to init. Resolve the process group on the host, signal -$pgid,
then re-probe: return True only when the process is actually gone, raise when
it survives SIGTERM, and refuse to signal the ssh session's own group. Launch
under setsid where available (portable fallback for macOS).
Co-authored-by: MervinPraison <[email protected]>
resolve_workdir quoted the workdir before the remote shell saw it, so ~
never expanded and a directory literally named '~' was created. Validate
the workdir (same rule as settings.validate) and pass it unquoted so the
remote shell expands it; use mkdir -m 700 so a shared box's umask does
not decide who can read the shipped config and dataset.
Co-authored-by: MervinPraison <[email protected]>
Gap 4 (session/live-turn identity) and Gap 5 (keyboard snapshot) were marked
CLOSED but are only half-closed in code:
- Gap 4: core/src/chat/session.ts implements RunPersistence, but no engine is
wired to it in production — createPraisonTsEngine gets a RunPersistence only
in tests, boot.ts never passes session to an engine, and remote-http has no
persistence. Turns are not recorded end-to-end.
- Gap 5: ShellPort.keyboardHeightPx exists but both adapters init it to 0 and
only correct on a later event; unlike insets it is not seeded synchronously,
so a warm resume still paints at 0 then jumps.
Gap 6 is genuinely closed (defs/subscribe/setSecret/clearSecret on the facade)
and stays closed. Reclassifies 4 & 5 as still-open and updates the audit
preamble to match its own rule: a gap is closed only when wired end-to-end.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Found while auditing what is outstanding. Gaps 4, 5 and 6 were fixed and
left recorded as open:
4 no user-message side closed by core/src/chat/session.ts
5 keyboard not synchronous closed by ShellPort.keyboardHeightPx
6 settings cannot enumerate closed by defs/subscribe/setSecret
That is not a filing problem. It is the same failure this package is
built against, one level up: a document asserting a state nobody
re-checked. And it has a measurable cost -- a stale P0 list for
praisonai-ts sent two agents to verify nine "blockers" that were every
one of them already fixed. Useful work, since it turned up three real
bugs nobody had listed, but not the work it was supposed to be.
So the file now carries the rule as well as the state: close a gap here
in the same commit that closes it in code, and verify before believing
what it says. Every claim in it is checkable in under a minute.
Genuinely still open, and recorded as such: gaps 2, 3 and 7, none of
which blocks shipping. Plus route-to-view dispatch and the Tauri crate,
which are unbuilt work rather than defects and are named separately so
they are not mistaken for gaps.
794 tests, boundaries clean.
Blanket digit deletion in normalise_error collapsed distinct failures
(HTTP 404 vs 500, exit code 12 vs 34) onto one signature, suppressing the
promised re-alert on a changed error (Greptile P1). Now strip only volatile
numbers — hex/uuid blobs, long digit runs (timestamps/pids/request ids) and
numbers fused into identifier words — while preserving short standalone codes
so genuinely different failures re-alert and changing request ids still group.
Co-authored-by: Mervin Praison <[email protected]>
Address reviewer findings on the shared durable idempotency store:
- DeliveryRouter: a send suppressed for a dead target, or cancelled while
waiting on the rate limiter or during the adapter send, now releases the
durable reservation claimed up-front by _is_duplicate(). Previously the key
stayed 'inflight' for up to the 15-min lease, wrongly suppressing legitimate
retries. CancelledError is a BaseException so it is handled explicitly.
- SchedulerDelivery: the durable store path now honours $PRAISONAI_HOME
(falling back to ~/.praisonai) so two isolated deployments under one OS
account keep separate dedup ledgers instead of cross-suppressing.
- Tests: add dead-target and cancellation release regressions.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Promote the existing durable SqliteIdempotencyStore to an injectable dedup
substrate the DeliveryRouter uses on every path, so restart-safe
effectively-once delivery is no longer gateway-only. The lightweight
SchedulerDelivery now injects the same store the gateway uses, and a failed
send releases the durable reservation so it stays retryable.
Co-authored-by: MervinPraison <[email protected]>
Add a pure, dependency-free incident brain beside RunRecord: error_signature()
groups failures by a stable sha256 of the normalised error, and IncidentTracker
folds the run stream into de-duplicated operator alerts — alert once per
incident, re-alert only on a changed signature, resolve on recovery, and an
optional N-consecutive-failure threshold. Core-only decision logic so every
engine (gateway, wrapper, standalone) shares one policy; delivery reuses the
existing DeliveryTarget plumbing.
Co-authored-by: MervinPraison <[email protected]>
Address Greptile P1 findings: by_model, total_interactions and
recent_interactions in the token reports were still copied from the
process-global TokenCollector summary, leaking other concurrent
PraisonAIAgents instances' usage. Re-derive by_model and
total_interactions from this instance's own interaction records and
filter recent_interactions to owned agent names.
Co-authored-by: Mervin Praison <[email protected]>
Route the backward-compatible thinking_budget setter through the unified
reasoning_effort path so the CLI's post-construction override actually
reaches the provider request (previously dormant: it only set
_thinking_budget, never emitted the native parameter). Also sync a
post-construction change into an already-built LLM instance.
Wire session persistence + resume for reasoning effort in the CLI:
persist the graded effort alongside the model in apply_cli_session_continuity,
add find_session_reasoning_effort, and restore it on --continue/--session
next to the existing model restore, mirroring the model precedent (#3685).
Add unit coverage for the thinking_budget setter reaching the request and
for the wrapper effort-restore helper.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <[email protected]>
Co-authored-by: Mervin Praison <[email protected]>
Store-backed jobs added via `praisonai schedule add` previously never fired
unless the gateway/BotOS/UI host was running, because only those hosts wired
the store poller. `praisonai schedule start` runs the unrelated agents.yaml
engine, so a plain CLI user's jobs silently never executed.
- Core: add `ScheduleLoop.run_forever(poll_seconds, owner_id)` — a foreground,
blocking counterpart to `start()` that reuses the same lease-safe `fire_due`
tick body (at-most-once `claim_due_jobs`, no double-fire alongside a gateway).
- Wrapper: add `praisonai schedule run` CLI command that reuses the existing
`schedules_runner` bridge executor (delivery fallback included) and blocks
until Ctrl-C.
No new engine, params, or exports beyond one core convenience method and one
CLI command.
Co-authored-by: MervinPraison <[email protected]>
- agent.py: last_stop_reason returns a specific agent-owned block/refusal/
truncation before backend fallbacks so a stale backend "max_steps" no longer
masks the OpenAI-native classification.
- chat_mixin.py: reset _last_stop_reason at the start of the async native turn
(mirrors the sync _chat_completion reset) to prevent cross-run leakage.
- execution_mixin.py: narrow the stop-reason lookup to AttributeError so a
lookup failure is not silently converted into a successful "completed".
- tests: add regressions for agent-owned-vs-backend precedence.
Co-authored-by: Mervin Praison <[email protected]>
Addresses reviewer feedback (Greptile) on the SqliteEventLog sink:
- Cursor no longer rewinds after a full prune: per-session seq is allocated
from a persistent event_seq high-water-mark table instead of MAX(seq) over
live rows, so deleting every row for a session never resets its counter.
- Seq allocation is atomic across connections/processes sharing one DB file:
read+bump+insert run inside a BEGIN IMMEDIATE transaction, eliminating the
read-then-insert race that previously dropped colliding events.
- Caller-provided event.metadata now persists (metadata_json column) and is
restored on query, with the durable seq/session_id overlaid on top.
- Additive migration for pre-existing databases: adds metadata_json and seeds
event_seq from MAX(seq) so the next append continues above existing rows
instead of colliding on the primary key.
Adds regression tests: post-full-prune monotonicity, metadata round-trip,
cross-connection no-collision, and legacy-schema migration.
Co-authored-by: Mervin Praison <[email protected]>
Add an opt-in SQLite sink for the existing EventBus so lifecycle events
survive a restart and can be read back per session with a cursor.
- New core module bus/event_log.py: EventLogProtocol + SqliteEventLog
(stdlib sqlite3, WAL, best-effort append, monotonic per-session seq,
cursor query(session_id, after_seq), age/count prune).
- EventBus.attach_sink()/detach_sink()/has_sinks: sinks receive every
published event (including the no-subscriber fast path) and their
failures are swallowed so a full/slow log never breaks a turn.
- Export EventLogProtocol/SqliteEventLog from bus/__init__ (lazy).
- Backward compatible: a bare Agent() attaches no sink, preserving the
zero-overhead in-memory path; the in-memory ring buffer is unchanged.
Co-authored-by: MervinPraison <[email protected]>
When check_same_thread=True, a worker-created connection cannot be closed
from close()'s caller thread — sqlite3 raises ProgrammingError. The prior
code swallowed it then cleared _conns, silently dropping (leaking) those
connections untracked. Now such connections are retained in _conns so they
stay reachable for a later close() from their owning thread; cleanly-closed
connections are still removed. Default check_same_thread=False path unchanged.
Co-authored-by: Mervin Praison <[email protected]>
- async_agent_scheduler: retry backoff now waits on _stop_event via
_sleep_or_stop(), so stop()/shutdown is no longer held for the full cap
- _base_scheduler: daemon state written atomically (tempfile + os.replace)
and JSON/OS errors logged at warning instead of being silently swallowed
- sqlite conversation store: track every thread-local connection and drain
them all in close() so a thread pool no longer leaks N-1 connections
Co-authored-by: MervinPraison <[email protected]>
Address two Greptile P1s on PR #4533:
1. Async tool exceptions now count toward the circuit breaker. The
post-invoke record block was skipped when the tool *raised* (control
jumped to the except handler), so raised failures never opened the
breaker. Record a breaker failure in the exception handler too, matching
the sync path's breaker.call.
2. The in-context is_already_approved/mark_approved cache is now keyed by
the per-instance scope_id (falling back to agent_name), so two same-named
agents sharing an execution context can't pre-authorize each other via the
name-keyed fast-path checked before the session lookup. Threaded scope_id
through approve_sync/approve_async, the two _check_tool_approval mark sites,
and the module-level wrappers.
Adds regression tests: async breaker opens after 5 raised failures and is
per-instance; context cache is isolated by scope_id with name-keyed fallback.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <[email protected]>
Extract countSubstantiveMergeGateRuns helper and add direct regression
tests so a reload of workflow_run probes into the pending cap is caught
by the self-test (addresses Greptile coverage gap on PR #4534).
Co-authored-by: Mervin Praison <[email protected]>
Auto-dispatch probe runs were counted toward the max-pending cap, blocking
repository_dispatch for merge-ready PRs even when no assess job was queued.
Co-authored-by: Cursor <[email protected]>
Three sibling code paths silently diverged from the "safe by default,
multi-agent safe, async-safe" guarantee. Each mirrors an existing correct
pattern that the sibling path never received:
1. Async tool execution now engages the per-agent circuit breaker. Added
shared helpers (_circuit_breaker_precheck / _circuit_breaker_record) in
tool_execution.py using the same instance-scoped breaker key as the sync
path, and wired them into _execute_tool_async_impl so a persistently
failing tool short-circuits with the circuit_open signal the async retry
loop already checks for, instead of being hammered indefinitely.
2. ApprovalCallback.__call__ now routes async approve_fn through the shared
run_coroutine_from_any_context bridge instead of hand-rolling a new event
loop with no running-loop guard, replacing an uncaught loop-crash inside a
running loop (e.g. FastAPI async route) with the codebase's standard clean
error.
3. Session-scoped ("this session") tool approvals are now keyed by the
per-Agent-instance _approval_scope_id via a new scope_id parameter on
approve_sync/approve_async (threaded into _is_session_scoped /
_persist_scoped_decision), so same-named agents no longer inherit each
other's human-granted shell-execution approvals. agent_name is retained
for name-keyed lookups (per-agent backend, risk level, ask rules, durable
"always" persistence). Same fix applied to the doom-loop approval path.
Co-authored-by: MervinPraison <[email protected]>
FINAL architecture reviewer prompt now mandates the Phase 1 table with an
explicit SDK value row and TS AGENTS.md routing. Merge-gate helpers treat
src/praisonai-ts/ as SDK scope for test enforcement and CI check patterns.
Co-authored-by: Cursor <[email protected]>
The user data directory was only created inside provision_engine, which
runs solely after the user clicks "Get started" on the first-run setup
screen. A clean machine that merely opened the app -- or one whose data
folder was deleted to repair a corrupt state -- therefore left no Roaming
directory at all, indistinguishable in a clean-start QA check from a shell
that never started. Create it eagerly in setup() (the primary-only path;
a secondary never reaches it) so the directory exists the moment the app
is running, whether or not provisioning has begun. Best effort, so a shell
never fails to start because it could not create its data directory.
Co-authored-by: Dhivya-Bharathy <[email protected]>
Strengthen the fetch_url redirect regression test per reviewer
feedback (Greptile). The test previously only checked the secret
body was absent from the result -- an implementation that contacts
the unapproved loopback target and discards its response would still
pass. Record requests to server B and assert it receives none, since
the request itself is a side effect (actions, logging, rate limits).
Mutation-verified: reverting the one-line server.py fix makes the
strengthened test fail on both the leaked body and the recorded hit.
Co-authored-by: Mervin Praison <[email protected]>
The approval card authorises one URL, but urllib.request.urlopen follows
3xx by default, so a 302 could send the fetch to any host or port --
including this engine on loopback -- and return its body to the model
under an approval that never named it. Fetch through an opener that
refuses redirects and reports the unapproved target instead.
Part of the #4504 desktop audit tracking issue (finding #1 of 16, high).
Co-authored-by: MervinPraison <[email protected]>
The bulk "Delete all conversations" path returned early on any failure
without checking whether the active conversation was among the deletes
that succeeded, leaving its transcript on screen while gone on disk.
Track the active id and blank the transcript when it was deleted, even
if a different conversation's delete failed. Adds a regression test.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
The engine answered {"ok": true} whether or not the chat was removed,
and both UI delete paths blanked the transcript regardless. A read-only
or synced data dir left the conversation closed on screen and back in
the sidebar on the next refresh.
- engine/server.py: do_DELETE returns 400 on an invalid id and 500 on
an OSError instead of swallowing both.
- ui/index.html: the sidebar delete and runAction('clear') now check the
response before blanking the transcript, matching the per-message
delete already in place.
- tests: engine DeleteChats route tests and two buttons.test.mjs cases.
Co-authored-by: MervinPraison <[email protected]>
After rebasing onto main, saveCfg reconciles the server's echoed settings back
into CFG. The stub returned the original settings for both GET and POST, so the
persisted step was overwritten and rapid text-size steps collapsed. Echo the
written patch like the real engine does.
Co-authored-by: Mervin Praison <[email protected]>
Moving the CFG mutation to after the await made rapid text-size steps read
stale state, collapsing bursts and letting overlapping writes land out of
order. Queue writes FIFO and step from the pending target so bursts
accumulate (fixes Greptile P1).
Co-authored-by: Mervin Praison <[email protected]>
saveCfg mutated CFG/cfg and applied prefs before POSTing /settings, with no
r.ok check and no catch. A rejected write (e.g. across the engine restart the
base_url/api_key rows warn about) left the theme button dead, toggles diverged
from stored state, and setTextSize toasted success while every write failed.
saveCfg now persists first, mutates only on r.ok, toasts on failure, and
returns a boolean. apply() and setTextSize gate their visible effects on it.
Co-authored-by: MervinPraison <[email protected]>
Route the persistence doctor's URL->backend detection through the tested
PraisonAIDB._detect_backend instead of hand-rolled substring sniffing.
Doctor-specific lenient fallbacks (sqlite/qdrant/memory and the chroma
special-case) are retained via a CLI-local wrapper.
Co-authored-by: MervinPraison <[email protected]>
The trainer is spawned with start_new_session=True, so on macOS/Linux a
signal aimed at the engine's process group never reaches it. The engine's
exit handler was `lambda *_: sys.exit(0)`, which let the fine-tune reparent
to init and keep the GPU with nothing left able to find or stop it.
The exit handler now calls Trainer.stop() first, which terminates the
trainer's own process group before the engine exits. Well within the 2s
Engine::shutdown allows before SIGKILL.
Co-authored-by: MervinPraison <[email protected]>
The toast intentionally paints below the settings scrim (see layout.test
'the settings scrim covers the toast'), so blank-name and backend-error
feedback shown while the MCP overlay is open was dimmed and unreadable --
the same invisible-feedback bug this PR set out to fix. Route both MCP
error paths through askConfirm, whose .confirm-back (z-index 90) paints
above the overlay (z-index 80).
Co-authored-by: Mervin Praison <[email protected]>
The PR fixed list_chats() but /projects and /search call load_chat() on the
same files, where a valid-but-non-object JSON (the app's own array export)
returned the raw list and crashed on .get(...) with AttributeError -- dropping
the connection on exactly the file the PR set out to handle.
Co-authored-by: Mervin Praison <[email protected]>
close() flushes, so a full disk or revoked directory can raise from the
reader's finally block just as a per-line write can. If it escapes, it
skips proc.wait()/run.finish() and wedges the run in "running" forever --
the same permanent wedge this reader exists to prevent, moved to the last
line. Guard the close and add a regression test that reproduces the wedge
on the unfixed code.
Co-authored-by: Mervin Praison <[email protected]>
std::env::vars() panics on any non-Unicode env key/value, and the release
profile sets panic = "abort", so a single non-Unicode inherited variable would
abort the desktop app before the engine started. Switch to vars_os() and drop
undecodable entries; spawn_env only handles String, so nothing usable is lost.
Co-authored-by: Mervin Praison <[email protected]>
The settings client optimistically set launch_at_login=true and ignored
the POST response, so when the OS declined to register a login item the
toggle stayed on for the session even though the server persisted false.
saveCfg now reads the response and reconciles any keys the server wrote
back, and the launch_at_login handler surfaces the explanation.
Co-authored-by: Mervin Praison <[email protected]>
Two fixes to the restorable-conversation feature:
- Preserve the tool `name` through getHistory/setHistory. toAISDKPrompt sets
the tool-result part's toolName from msg.name; without it a restored tool
history sent to a non-OpenAI (AI SDK) backend emits an empty toolName and is
rejected. Added optional name to AgentMessage, copied it in copyMessage, and
carried it in the start() replay.
- Clear responseCache in setHistory so a repeat prompt is re-evaluated against
the restored history instead of returning the pre-restore prompt-keyed answer.
Added regression tests for both; full suite: 1141 passed, 0 failed.
Co-authored-by: Mervin Praison <[email protected]>
Two valid restart-recovery bugs from PR review:
- _persist now writes a temp file, fsyncs and os.replaces it, so an engine
killed mid write can never leave partial JSON that _reload silently skips
(which would lose the live run from history, stop() and the single-GPU guard).
- start() persists the run (pending) before the supervisor thread exists, and
the spawn-failure branch persists its FAILED state, so a child spawned before
the first post-spawn _persist is never left with no run.json.
Adds two tests. PID reuse is left as the documented minimal tradeoff.
Co-authored-by: Mervin Praison <[email protected]>
Return the client captured in a local before the awaited Logger.debug so a
concurrent credential change or resetOpenAIClient() during that yield cannot
hand a caller the wrong client or null. Adds two race regression tests.
Co-authored-by: Mervin Praison <[email protected]>
The tool_call/tool_result mapping landed but the seam documentation still
described the pre-tool three-variant union, contradicting the new support.
Aligns engine.ts, agent-api.ts and conformance.test.ts headers and gaps.md
so the capability status reads consistently: tools supported, approvals the
one remaining gap. Docs/comments only; no behaviour change.
Co-authored-by: Mervin Praison <[email protected]>
WKWebView under Tauri has no JS dialog panel, so prompt() returns null
and alert() shows nothing. This made "Move to project" inert and hid MCP
add errors. Add an askText() helper mirroring askConfirm(), and route
the three sites through askText/toast. Update the button test stubs to
model the real platform (prompt->null, alert throws) and add a
contextmenu test asserting a POST /project request is issued.
Co-authored-by: MervinPraison <[email protected]>
venv_resolve::spawn_env strips PYTHONPATH/PYTHONHOME/PYTHONSTARTUP and sets
VIRTUAL_ENV/PATH, but had no production caller -- supervisor::start inherited
the shell's environment and only added PYTHONUTF8/PYTHONIOENCODING. A user with
PYTHONHOME or PYTHONPATH exported got the engine pointed at a foreign stdlib or
site-packages, and the module written to prevent exactly that never ran.
start now takes the resolved env and applies it with env_clear + envs; main.rs
builds it from the already-resolved VenvLayout. Adds a regression test proving a
poisoned PYTHONHOME/PYTHONPATH never reaches the spawned child.
Co-authored-by: MervinPraison <[email protected]>
Wrap the settings runAction body in runActionInner and catch failures with
a toast, so Export/Check for updates/MCP no longer resolve into silence when
the engine is unreachable. Export additionally throws on non-ok responses so a
500 cannot slip past, and the clipboard is only written on success -- a failed
export can no longer masquerade as a backup via a stale paste.
Co-authored-by: MervinPraison <[email protected]>
The desktop settings registry described MCP servers as launched over stdio and offered an enable switch, but engine/server.py load_mcp() has no client consumer: _get_agent builds Agent(tools=_builtin_tools()) and never spawns a server. The text claimed a live capability that does not exist.
Apply the honest-text fix to all three synced registry copies and the Manage panel, and add a registry-drift guard asserting the hint no longer claims a launch the engine never performs.
Co-authored-by: MervinPraison <[email protected]>
On Windows venv_python_rel() returned "Scripts/python.exe" (forward slash),
which Path::join appends verbatim, so the expected interpreter string never
matched the backslashed sys.executable the engine records in its lockfile.
adopt::decide byte-compared them, always returned DifferentInterpreter, and
every relaunch taskkill'd a healthy engine (and its trainer via /T).
- platform.rs: use "Scripts\\python.exe" so the produced path is canonical.
- adopt.rs: compare interpreter and venv_root through same_path(), which folds
'/' to '\\' and lower-cases on Windows (case-insensitive FS) and compares
as-is elsewhere.
- tests: adopt across mixed separator/case spellings; same_path semantics.
Co-authored-by: MervinPraison <[email protected]>
esc() covered only & < > , so a model-authored URL containing a double
quote closed the double-quoted href built in inline() and injected its
own attributes -- id=f made getElementById('f') return the injected <a>
instead of the composer <form>, breaking Enter-to-send. Adding the two
quote characters to the escape class is the whole fix, since inline()
escapes before the link rule runs.
Co-authored-by: MervinPraison <[email protected]>
getHistory() now returns the exported AgentMessage type carrying tool_calls and
tool_call_id, so persisting it is lossless. Adds a validating setHistory() that
rejects unknown roles, orphaned tool_call_ids and non-arrays, strips a leading
system message, and copies on write. The non-stream/no-tools start() path now
sends the full restored history via generateChat instead of dropping it.
Co-authored-by: MervinPraison <[email protected]>
A file that is valid JSON but not an object (the app's own Export emits a
list) reached c.get(...) in list_chats() and raised AttributeError, which
escaped the (OSError, ValueError) handler and closed the connection with no
status -- so /chats, /projects and /search appeared as an engine outage.
Raise ValueError for a non-dict so it surfaces as a corrupt row instead.
Co-authored-by: MervinPraison <[email protected]>
praisonai-ts gained tool_call and tool_result, so the engine's
capabilities.tools goes true and three conformance scenarios move from
"cannot be produced" to produced and passing.
The flag was false for a real reason rather than caution: upstream
EXECUTED tools and never announced them, so a UI rendering rows from a
true flag would have rendered nothing and looked broken. The flag and
the behaviour agree again, which is the only thing the flag ever
claimed.
This also fixes a break the widening would otherwise have caused. The
mapping loop ended in an `else` that treated any unrecognised variant as
a terminal error -- so the first tool_call to arrive would have ended
the turn as a failure. Widening a union is source-breaking for exactly
this shape, and this is the consumer I predicted it would break.
Two things passed through rather than re-derived:
- `ok` comes straight from upstream. Inferring it from a non-empty
output is the defect the protocol comment was written against, and
the tool_failed scenario deliberately carries a non-empty output on
a failed call so a suite that inferred would fail it.
- `seconds: null`, because upstream reports no duration. Null means
unknown, which the view renders differently from zero.
Skipped conformance scenarios: 5 -> 2. The two that remain are the
approval prompts, which ApprovalManager gates upstream but cannot
surface on the event channel.
794 tests, boundaries clean, bundle unchanged at 42.4kB.
The training subsystem kept the live run and history in memory only, so any
engine restart lost the run: /train/runs returned empty, /train/stop had
nothing to stop, and start() launched a second trainer beside a live one --
the OOM that "one GPU runs one job" exists to refuse.
Each run now writes a run.json (state + pid) at spawn, on the RUNNING/STOPPING
transition, and on finish. Trainer.__init__ reloads from disk: a run whose pid
is still alive is adopted (current is set, so start still refuses and stop can
reach it via its pid's process group); an interrupted run is marked failed. The
engine stays stdlib-only.
Adds SurvivingARestart tests: a live run reappears, a second fine-tune is
refused, stop kills the adopted pid, an interrupted run reports failed, and a
finished run is not re-adopted.
Co-authored-by: MervinPraison <[email protected]>
A single OSError on the log write abandoned the reader while the child
was still writing to a PIPE nobody drained. The child blocked on the full
pipe, proc.wait() blocked on the child, run.finish() never ran, and the
run read "running" forever -- refusing every subsequent run for the life
of the engine.
The reader now drains the pipe whatever happens to the log: a log-open or
log-write failure drops the log and keeps consuming stdout, so the run
still ends. Each line is also flushed, so train.log is the live record it
is documented to be rather than 0 bytes until exit.
Co-authored-by: MervinPraison <[email protected]>
The /settings handler wrote the requested launch_at_login value first and
only attached set_launch_at_login's result to the response -- which nothing
reads. Off macOS (and in a macOS checkout) registration always returns
{"enabled": false}, so the toggle rendered on, persisted, and survived
restarts while no login item existed. Now the platform action runs first and
the persisted value is coerced to what actually happened.
Co-authored-by: MervinPraison <[email protected]>
The desktop engine's fetch_url gated on the approved URL, then let urllib
follow any 3xx to any host -- including the engine on loopback -- under
that same approval, so an author-controlled redirect could pull another
chat's transcript, /settings or /logs into the model's context.
Fetch now uses a no-redirect opener that raises on any 3xx, so the honest
error reaches the model and the user can approve the new URL via a second
card. Adds a test standing up a 302 -> secret-body pair and asserting the
secret is not returned.
Co-authored-by: MervinPraison <[email protected]>
When one agent declares tool_timeout and another omits it,
_resolve_uniform_tool_timeout classified the single value as uniform and
wrapped the shared tool dict, silently forcing the undeclared agent's
valid long-running calls to fail with ToolTimeoutError. Now a value is
uniform only when every agent/role declares it with the same value;
otherwise the per-agent resolver is the sole guard, leaving undeclared
agents unwrapped.
Co-authored-by: Mervin Praison <[email protected]>
Key the env-only getOpenAIClient() cache on API key + base URL instead of
mere existence, so a rotated/updated key or a changed base URL is picked up
without restarting the process. Add resetOpenAIClient() for tests and
settings-driven rebuilds. The identity string is never logged.
Co-authored-by: MervinPraison <[email protected]>
The remote dispatch fallback only recognised a dataset given as a bare
string, but the trainer's canonical shape is a list of mappings and it
loads any name/data_files that exists on disk. A config using
`dataset: [{name: ./local.json}]` therefore had its file left behind, and
the remote run failed on a path that existed only on the launching machine.
_local_dataset_in now inspects both forms, mirroring how the trainer
resolves a local file, and returns the first local dataset to ship.
Co-authored-by: Mervin Praison <[email protected]>
The triage bot fixed a real bug of mine: the dispatch compared
`state == "failed"` while status() returns `"failed (exit N)"`, so a remote run
that failed was reported as a success.
My test did not catch it because my fake returned exactly `"failed"` -- and
`"done"` for success, which the runner never returns either. The fake agreed
with the bug, so the test passed and the code was wrong. That is the same
defect as the code it was meant to check, one level up.
The fake now speaks the runner's actual vocabulary -- completed, running,
unknown, `failed (exit N)` -- and a test reads runner.py from disk and asserts
those spellings still exist, so the fake cannot quietly drift from the thing it
stands in for. Deleting `failed (exit` from the runner now fails the dispatch
tests.
Two test-harness repairs alongside it. `monkeypatch.setattr(train_cmd,
"import_code_module", ...)` never intercepted anything: train_llm imports that
name inside the function body, so the patch has to be on
praisonai_train._code_bridge, where the lookup happens. And the vocabulary test
read RemoteRunner through the module -- which the autouse fixture has already
replaced with the fake, so it would have asserted that the fake agrees with
itself.
Three mutations, three caught, including restoring the equality comparison.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
- Detect failed status by prefix: runner.status() returns 'failed (exit N)',
so the equality check reported failed remote runs as success.
- Ship a dataset named only in --config when it is a local file, so the
remote process is not handed a path that exists only locally.
- Resolve and validate the remote block in --dry-run so the preview matches
the real dispatch and bad settings are caught before renting a GPU.
- Reject falsey non-mapping remote values ([], '', false) instead of quietly
treating them as train-locally.
- Assert typer.Exit in the no-remote dispatch test rather than swallowing
every exception; skip the POSIX-only keyring tests on Windows.
Co-authored-by: Mervin Praison <[email protected]>
Track DeliveryOutcome.DELIVERED via a dedicated _delivered_count instead of
inferring delivered_deliveries from success - undelivered. NOT_CONFIGURED and
SUPPRESSED runs are recorded successes but not deliveries, so the derived metric
over-reported them. Applied to sync + async schedulers and _build_stats /
get_stats_sync, with sync + async tests asserting zero delivered for
NOT_CONFIGURED and SUPPRESSED runs.
Co-authored-by: Mervin Praison <[email protected]>
Standalone AgentScheduler recorded a run as success even when delivery of
its result to the chat channel failed: _deliver_result discarded the
delivery bool, on_success fired, and a failed send was only a swallowed
logger.error.
Now _deliver_result returns a typed DeliveryOutcome
(NOT_CONFIGURED/SUPPRESSED/DELIVERED/UNDELIVERED). Both the sync and async
schedulers observe it: an undelivered result is counted, surfaced via the
existing core HookEvent.MESSAGE_UNDELIVERED hook, and routed to on_failure
instead of on_success. get_stats() now exposes delivered/undelivered
counts. Intentional silence stays a recorded non-outcome.
Reuses the existing MESSAGE_UNDELIVERED protocol seam - no new user-facing
knobs or infrastructure.
Co-authored-by: Mervin Praison <[email protected]>
Serialize workflow_run auto-dispatch, skip dispatch when a gate is already active or the queue is saturated, and reuse the guard in pipeline label sync.
Co-authored-by: Cursor <[email protected]>
The AI-SDK tool loop called generateText unconditionally, so on any
non-OpenAI provider `stream: true` silently had no effect once tools
were configured -- and the round's assistant text was DROPPED.
A model that says "Let me check." before calling a tool had that
sentence recorded into `messages` for its own context and never
delivered to the caller. The user watched a tool run with no explanation
of why. Losing no streaming is a downgrade; losing a sentence the model
actually produced is a wrong transcript.
StreamChunk already carries text AND toolCalls, and StreamTextOptions
extends GenerateTextOptions, so one shape covers both and the loop now
streams when streaming is on.
This makes non-OpenAI consistent with OpenAI rather than inventing
behaviour: the OpenAI path has always streamed pre-tool text through
streamChatWithTools. Every real provider implements streamText --
anthropic, google and the ai-sdk backend all do -- so no provider loses
a transport it had.
tools-cross-provider.test.ts needed updating, and the reason matters.
Its guarantee is in its name -- "tools survive on every non-OpenAI
provider" -- but it asserted on generateText specifically, and `stream`
defaults to true. It now asserts on whichever transport carried the
call, which keeps the guarantee without pinning the mechanism. Its two
multi-round cases are pinned to stream:false, because they are about the
LOOP across rounds and that keeps a real generateText case in the suite.
Their mock also had `streamText: jest.fn()`, which returns undefined and
throws on `for await` before reaching any assertion.
1120 tests pass, tsc clean.
The routing fix now sends a bare claude-*/gemini- name to the AI-SDK
backend, but getBackend() never forwarded the constructor's apiKey and the
backend's key gate read only the provider env var. A caller who passed
apiKey (no env var) authenticated on the OpenAI path but was rejected on
the path their model actually takes.
- Agent stores apiKey/baseURL and forwards them via resolveBackend config
- resolveBackend maps the flat apiKey/baseUrl onto providers[providerId]
- validateProviderApiKey accepts an explicit key, gated after reading it
- 2 tests pin the forwarding and the key-gate behaviour
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Adds a protocol-only SkillAutomation descriptor (schedule/deliver/prompt)
parsed from SKILL.md metadata.praisonai.automation, so an installed skill
can declare when to run and where to deliver. Preserves nested metadata
mappings during parsing and exports SkillAutomation. Materialisation via
the wrapper scheduler's consent-first SuggestionEngine/DeliveryRouter is
left to consumers.
Co-authored-by: Mervin Praison <[email protected]>
- chat_mixin: run input guardrail BEFORE begin_durable_run in _start_stream so a
guardrail-blocked stream never opens/finalizes a durable run as "succeeded"
(parity with chat()/achat()); remove the now-redundant check from
_start_stream_impl.
- tool_execution: a tool that *raised* (flattened error dict tagged
_praison_retryable) again surfaces as ToolExecutionError so the run fails,
while a plain tool-*returned* {"error": ...} still falls through to the LLM.
Restores test_tool_failure_not_relabelled without losing the PR's self-correct
path for shell_tools/tavily_tools-style returned errors.
- agents: scope every token-report field to the team's agents — rebuild
total_interactions and by_model from the per-interaction log, and add
_scoped_recent_interactions so get_detailed_token_report no longer leaks
another concurrent team's activity.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Mervin Praison <[email protected]>
Found by an agent auditing a stale P0 list. It is the most serious thing
in this session, and it is a hole in the gate I added two PRs ago.
`src/mobile.ts` passed the gate. `dist/esm/mobile.js` -- what
package.json actually resolves `praisonai/mobile` to -- failed to bundle
for a browser with TEN unresolved builtins:
Could not resolve "module" @ dist/esm/llm/backend-resolver.js:1
Could not resolve "url" @ dist/esm/llm/backend-resolver.js:2
Could not resolve "path" @ dist/esm/llm/backend-resolver.js:3
... and 7 more
ROOT CAUSE. scripts/esm-shim.js prepended a CJS banner -- static imports
of module, url and path -- to any emitted file whose source uses a bare
`require()`. Three first-party files on the mobile graph do, all of them
LAZY provider loads. The banner turned three lazy requires into three
STATIC Node imports: precisely the failure the gate exists to prevent.
WHY THE GATE MISSED IT. It checked TypeScript sources only, and the
banner does not exist until build:esm has run. So it passed, confidently
and repeatedly, on an input that is not what ships. A gate that reports
OK about the wrong artifact is worse than no gate, because it is
believed.
Two fixes, because either alone leaves something wrong:
- The banner is browser-safe now. A guarded top-level await keeps Node
behaviour identical and lets a bundler defer the import instead of
failing on it; in a browser the catch installs a `require` that
throws only if a lazy provider path is actually taken, which on a
phone it is not.
- The gate checks dist/esm too, and CI builds before gating. Only when
dist/ exists, so the gate still runs on a fresh clone.
One test needed updating and it is worth saying why rather than burying
it: esm-shim-banner.test.ts pinned BANNER_MARKER to
`__praisonCreateRequire(import.meta.url)` -- an internal identifier, not
a behaviour -- so renaming it failed four tests that were not about
naming. The marker is now `const require =`: a banner that stopped
defining require would still fail them.
Verified in Node after the change: dist/esm/mobile.js loads and exports
Agent/getEnv/randomUUID, backend-resolver parses claude-3-5-sonnet-latest
to anthropic, and the lazy require path still resolves --
createProvider('openai') returns an OpenAIProvider.
1136 tests pass. All four entries -- both sources, both built -- report
loadable in a webview.
- Add "local" to the three gateway tokenless gates (config validation,
start_channels, _start_single_channel) so a token-free terminal channel
starts instead of being skipped and marked degraded (Greptile P1 #1).
- Run the blocking stdin readline on a dedicated daemon thread so a pending
TTY read at shutdown can never join-block interpreter exit; cancellation
resolves the awaiting coroutine promptly (Greptile P1 #2).
- Add regression tests: cancelled-read clean exit, daemon reader guard.
Co-authored-by: Mervin Praison <[email protected]>
Found while verifying a stale P0 list -- not on it, and worse than
anything that was.
The Agent constructor carried its own copy of the model-parsing rule,
and it defaulted EVERY slash-less name to OpenAI:
const providerId = this.llm.includes('/') ? ... : 'openai';
So `new Agent({ llm: 'claude-3-5-sonnet-latest', tools: [...] })` made
one OpenAI call and zero Anthropic ones, sending OpenAI-format tools to
the OpenAI endpoint. The tools were not dropped -- the entire request
went to the wrong vendor, which surfaces as model-not-found, or as a
bill nobody can explain.
backend-resolver.parseModelString had always inferred anthropic from a
`claude-` prefix and google from `gemini-`. There were simply two rules
that disagreed and the constructor used the wrong one. Now there is one.
A custom baseURL is a deliberate exception: pointing at an
OpenAI-compatible proxy that serves claude-* is a real deployment, and
prefix inference would route it away from the endpoint the caller
explicitly asked for. An EXPLICIT anthropic/... prefix still wins over a
baseURL, because that is unambiguous.
Verified as a positive control: restoring the old parser fails the two
routing cases and nothing else.
1144 tests pass, tsc clean.
Drop unused mer.vin blog draft files from the monorepo root; they are not referenced by CI, docs, or package code.
Co-authored-by: Cursor <[email protected]>
The LeafStoreDeletion suite fakes `security`/`secret-tool` with #!/bin/sh
scripts, which Windows cannot execute, so set() returned False and three
asserts failed on the windows-latest engine leg. Those stores are the macOS
keychain and Linux libsecret and do not exist on Windows; skip the class
there using the file's existing os.name=='nt' pattern.
Co-authored-by: Mervin Praison <[email protected]>
_build_tools_dict set either _tool_timeout_wrap (uniform) or
_agent_tool_wrap_resolver (heterogeneous) but never cleared the
mutually-exclusive key. Reusing the same generator with a different
timeout layout leaked a prior run's closure into the adapters, applying
an earlier budget to current tools. Now both keys are written every call
(inactive one set to None). Adds a reuse regression test.
Co-authored-by: Mervin Praison <[email protected]>
Address the two P1 gaps raised in review:
- Cached LLM stayed stale: the reasoning_effort setter now updates the
already-materialized LLM instance (which _build_completion_params reads),
not just _llm_init_params, so post-construction changes take effect.
- Session effort was serialized but never written/restored in production:
apply_cli_session_continuity now persists reasoning_effort alongside the
model, and `run` restores it on --continue/--session (mirroring #3685).
Also: thinking_budget setter now routes through the effort setter, and the
effort value is normalised to a canonical graded level so the persisted/
queried value is always provider-portable.
Co-authored-by: Mervin Praison <[email protected]>
The desktop restores the last-used view from localStorage synchronously at
startup. When that is Train, body.training is set and the stylesheet hides
async; when it resolves to setup-needed/failed, firstRun()/failWithSetup()
render the setup wizard or failure banner into #thread -- which is now hidden
behind the Train view. The title bar shows "setup needed" with nothing on
screen to act on: the reported Windows dead end.
Force the Chat view (showEngineGate) when the engine is not ready so the
deliberate Train choice returns once the engine is up. Engine and Rust
supervisor untouched.
Co-authored-by: Mervin Praison <[email protected]>
The async reasoning_steps post-tool branch captured the completion but
never called _record_finish_reason, so a content-filter/refusal/length
cutoff returned after an async reasoning-enabled tool call was silently
collapsed into "completed" instead of surfacing the explicit provider
terminal reason. Mirrors the sync path which already records it.
Co-authored-by: Mervin Praison <[email protected]>
Wrap the two new guardrail run_in_executor offloads with
copy_context_to_callable so a custom guardrail sees the same
contextual state (trace emission, session context) as the sync path,
matching every other run_in_executor call site in the SDK.
Co-authored-by: Mervin Praison <[email protected]>
- Run the blocking stdin readline() in a dedicated single-thread executor and
tear it down with wait=False/cancel_futures on stop(), so cancelling start()
during a pending read never blocks asyncio.run's event-loop teardown.
- Propagate stdout write failures from send_message() instead of swallowing
them, so the shared DeliveryRouter records a real failure (returns False)
rather than a phantom success.
- Correct the startup log: Ctrl-D exits; /stop cancels the current run.
- Add regression tests: write-failure propagation, router failure on broken
stdout, and prompt shutdown while a stdin read is in flight.
Addresses CodeRabbit/Greptile review findings on PR #4463 (fixes#4455).
Co-authored-by: Mervin Praison <[email protected]>
Use the GitHub App token for post-issue CodeRabbit/Qodo kicks, treat kick failures as non-fatal, and recognise triage-bot kick comments for idempotency.
Co-authored-by: Cursor <[email protected]>
- AutoGen: local code execution is now opt-in via config.autogen.code_execution
(default off; Docker on when enabled), warns on use_docker=False, and
human_input_mode defaults to TERMINATE instead of forced NEVER.
- PraisonAIAdapter: injected ACP/LSP centric tools carry the same per-run
tool_timeout guard via a wrap threaded through cli_config.
- agents_generator: heterogeneous per-agent tool_timeout budgets are honoured
per-agent (no silent tightest-wins downgrade); uniform values still wrap once.
- _config_builder / crewai / autogen adapters: thread the per-agent wrap
resolver so every framework honours per-agent budgets (tools stay shared).
Co-authored-by: Mervin Praison <[email protected]>
A standalone scheduled run no longer reports success when channel delivery
of its result fails. `_deliver_result` now returns a typed `DeliveryOutcome`
(NOT_CONFIGURED / SUPPRESSED / DELIVERED / UNDELIVERED) instead of discarding
the delivery bool; the sync and async schedulers fold that outcome into their
accounting so an undelivered result fires `on_failure` (not `on_success`),
bumps an undelivered counter surfaced in `get_stats()`, and best-effort emits
the existing `HookEvent.MESSAGE_UNDELIVERED` seam. Intentional silence stays a
recorded non-outcome.
Co-authored-by: Mervin Praison <[email protected]>
Bridge installed skills to the scheduler by parsing an optional
metadata.praisonai.automation block (schedule/deliver/prompt) into a new
protocol-only SkillAutomation dataclass exposed via SkillProperties.automation.
Preserve nested metadata mappings during parsing so the namespaced block
survives; older parsers ignore it and skills without it get automation=None.
Materialisation stays in the wrapper's existing SuggestionEngine + DeliveryRouter.
Co-authored-by: Mervin Praison <[email protected]>
Malformed JSON or non-object arguments throw before the normal tool_call
emission, so the catch previously emitted an orphan tool_result with no
matching tool_call to pair by callId. Track emission and announce the call
in the catch when the parse/validation path rejected it early.
Co-authored-by: Mervin Praison <[email protected]>
Make the graded reasoning-effort knob live and provider-portable:
- core: add thinking/effort.py resolving off|minimal|low|medium|high to each
provider's native param (OpenAI/xAI reasoning_effort, Anthropic/Gemini
extended-thinking budget; no-op for non-reasoning models).
- llm/llm.py: emit the translated param in _build_completion_params from a new
reasoning_effort setting (with thinking_budget as a backward-compatible alias).
- agent/agent.py: accept reasoning_effort= and revive the previously-dead
thinking_budget alias, threading both into the LLM request pipeline.
- session/store.py: persist reasoning_effort on the session record and restore it
on resume via get_session_reasoning_effort, mirroring model-persist (#3685).
Co-authored-by: Mervin Praison <[email protected]>
Core now inspects the provider finish_reason/refusal signal and records a
distinct, additive terminal reason (content_filtered | refused |
length_truncated) instead of collapsing provider-side blocks into a silent
empty "completed" or a generic "failed".
- run_outcome.py: extend TerminalReason + precedence additively; add a shared
classify_finish_reason() helper and PROVIDER_BLOCK_REASONS.
- llm.py: add _record_finish_reason() and call it at the non-streaming response
capture points on both the sync and async LiteLLM paths (only overrides a
"completed" reason so max_steps stays sticky).
- chat_mixin.py: record the classification on the OpenAI-native path where the
empty-content finish_reason/refusal is already detected; reset the agent-level
reason per turn so a prior block never leaks.
- agent.py: last_stop_reason surfaces the agent-recorded provider block reason.
- execution_mixin.py: _outcome_for_result() threads the provider block reason
into RunOutcome for return_outcome=True callers.
- run.py (wrapper): map the new reasons to exit code 2 + a human-readable
message + a machine-readable reason in --output json, winning over a generic
empty-result failure.
Backward-compatible: unknown/absent finish reasons behave exactly as today.
Co-authored-by: Mervin Praison <[email protected]>
Every launch recorded itself as primary at main() start while the guard
callback -- which runs in the existing primary -- recorded that primary's
pid as secondary, reversing both role/pid pairs (greptile p1). Record
secondary at main() start (honest before the guard decides, own pid) and
upgrade to primary from setup(), which only the first instance reaches.
Co-authored-by: Mervin Praison <[email protected]>
Two async-safety parity gaps where an async code path silently failed to
match its sync sibling's behaviour:
1. Async guardrail validation ran a blocking, synchronous LLM call from
inside async methods, stalling the whole event loop (and every task
under asyncio.gather). _aapply_guardrail_with_retry and arun_task now
offload the sync guardrail chain via loop.run_in_executor, mirroring
async_memory_mixin's _run_memory_in_thread pattern.
2. The async tool-execution path had no circuit breaker (only loop-guard
parity was added by #4005), so a repeatedly-failing tool could be
hammered every turn via achat()/async workflows and the dead
circuit_open retry-skip never fired. _execute_tool_async_impl now
routes the invocation through the same per-agent/per-tool
CircuitBreaker.acall used by the sync path, counting error-dict results
as failures and surfacing circuit_open=True when the breaker opens.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Deployment infra now lives under src/praisonai-deploy/infra/ and src/praisonai-bot/infra/; the monorepo-root deploy/README.md stub is unused.
Co-authored-by: Cursor <[email protected]>
Add a built-in `local` channel that reads stdin / writes stdout, registered
exactly like the nine remote platforms. It is token-free and owner-trusted,
and joins the same BotSessionManager, identity resolver and DeliveryRouter as
every remote channel — so `BotOS(agent=agent, platforms=["local"])` lets you
converse with a gateway agent from your shell with zero setup, and
`deliver="local:local"` routes through the shared router for cross-channel
continuity.
Co-authored-by: Mervin Praison <[email protected]>
Move the tool_call emission to immediately after argument parsing and
before the function-existence and approval gates, so denied and
unregistered calls no longer produce an orphan tool_result with no
matching invocation to pair by callId. Also reject non-object JSON
arguments (null, array, scalar) so AgentEvent.args honours its declared
Record<string, unknown> contract. Adds a denied-call ordering regression.
Co-authored-by: Mervin Praison <[email protected]>
- _start_stream_impl now runs input-guardrail validation like chat()/achat(),
so start(stream=True)/iter_stream() no longer skip it
- a tool's own {"error": ...} return with no transient/denial marker flows back
as a normal tool result instead of raising a fatal ToolExecutionError, letting
the LLM self-correct
- PraisonAIAgents token summaries filter to the instance's own agent names,
preventing concurrent instances from leaking each other's usage/cost
Co-authored-by: Mervin Praison <[email protected]>
The Windows first-run report was "double-click, nothing happens, no
window, no folder, no logs", read as a missing-AppData crash. But the
shell's window is eager and visible and AppData is only touched after
the webview exists, so an absent data dir cannot cause a pre-webview
exit. The exit 0 is the single-instance guard telling a secondary
launch to hand off to the primary (which is hidden to the tray on
close) and quit -- indistinguishable from the outside from a shell
that died.
Write one line to %TEMP%\PraisonAI-startup.log before the guard runs
and before the window is built, tagging each launch primary/secondary
with its pid. That log exists whether or not %APPDATA%\PraisonAI does,
which is the "no logs to inspect" gap the report named, and it tells a
handed-off secondary apart from a real crash. Pure path/format helpers
live in the core crate with tests; the write is best effort so a shell
never fails to start over a log it could not write.
Co-authored-by: Mervin Praison <[email protected]>
Move the skill to local ~/.cursor/skills so TS routing guidance stays personal rather than tracked in the monorepo.
Co-authored-by: Cursor <[email protected]>
Fine-tuning needs CUDA. A Mac does not have it, and neither does most of the
hardware this desktop app runs on -- so "Start" in the Training tab offered
every one of those users a button that cannot finish. Remote training was not a
missing convenience; it is the only way the feature works for them.
The SSH runner already existed (`praisonai_train.remote`) and was reachable
only from `praisonai-train remote start`. The gap was that nothing else could
ask for it: there was no YAML key, no flag on the command people actually run,
and nothing in the desktop form.
## One fact, three ways of saying it
remote: --remote-host gpubox [Run on: A remote server]
host: gpubox --remote-python /opt/py [SSH host: gpubox]
python: /opt/py --remote-workdir ~/runs [Remote python: /opt/py]
workdir: ~/runs
All three are the same instruction and are declared once, in
`praisonai_train/remote/settings.py`. The flags are named from that table, the
YAML is validated against it, and a test asserts every key has a flag and the
CLI declares exactly those and no others -- because three surfaces over one set
of facts is precisely the arrangement that drifts apart.
Precedence is the one this CLI already uses everywhere: the file is the
baseline, a flag wins, and an absent flag does not erase a file value.
`llm` dispatches on the resolved config, before the heavy import. That ordering
matters: the reason to train elsewhere is that this machine has no torch and no
GPU, so requiring them locally would make the remote path unreachable from
exactly the machines that need it. The desktop needed no new execution path at
all -- it writes the config, and the config decides.
Four things the design had to get right, each with a test:
* The remote block is stripped from the shipped config. Left in, the far side
reads its own config, finds a host, and dispatches again.
* A remote run does not write ./config.yaml into the directory the user
happened to be standing in. That is the local dispatcher's contract, not a
side effect training elsewhere should have.
* SIGINT and SIGTERM stop the run on the other machine. Without that the signal
ends the tail and leaves a rented GPU training a job reported as cancelled --
which is exactly how the desktop Stop button would lie.
* Credentials are refused, and refused *as credentials*: they are also unknown
keys, and telling someone they misspelled `password` invites them to spell it
correctly into a file that gets copied to another machine and printed by
--dry-run.
Host, workdir and python are validated as plain names -- they reach a remote
shell, and `remote.host: "gpu; rm -rf /"` is not a typo.
## Also fixed
`train_llm`'s `dataset` parameter was never unwrapped, and `_v()` recognised
only `OptionInfo` while `dataset` is a `typer.Argument` and produces
`ArgumentInfo`. Called as a plain function -- which its own docstring says is
supported -- it arrived as an ArgumentInfo, which is truthy, and was written
into the resolved config. The YAML dump then raised RepresenterError.
## Tests
30 in praisonai-train (parity, precedence, refusals, dispatch), 24 in the
desktop training suite. Nothing contacts a remote machine: the runner is
replaced, and what is under test is the decision and what gets handed over.
Thirteen mutations, thirteen caught. Four survived the first pass and each was
a test that did not reach its case -- a credential test passing because the
unknown-key check fired first, a dispatch test that never went through the
command, and two default-value tests where the field's own markup already
supplied the default. One survivor was a genuinely equivalent mutation: `get()`
already trims, so the extra `.trim()` calls were removed rather than pinned.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Task 7. AgentEvent carried three variants -- text, finish, error -- so a
consumer of streamEvents could see prose and nothing else. praisonai-ts
executed tools perfectly well and never said so, which meant any UI
built on it had to infer tool activity from the model's own description
of it. Inference is exactly how a tool call that silently failed still
looks like a normal answer.
Two new variants, and `ok` is the point of both. A tool that FAILED with
a message is byte-identical to one that succeeded with a message, so
success can never be read off a non-empty output. All three paths emit
it: success, throw, and an approval-gate denial -- a denied tool did not
run, and rendering it as a success tells the user something happened
that did not.
callId pairs a result to its call. Matching by position holds only while
exactly one call is ever in flight and silently attributes the wrong
output the moment that stops being true.
Structured events share the SAME queue as the text, which is what keeps
a tool call in its true position. On a separate channel it could arrive
before the sentence that introduced it, and a reader cannot tell a
reordered transcript from a model that said things in that order.
ADDITIVE BY CONSTRUCTION. `start()` gained a fifth optional parameter,
so every existing caller passes four and behaves exactly as before.
`stream()` filters on type === 'text' and is unaffected -- asserted, not
assumed. A run with no tools emits no tool events, which is the pair
that stops a spurious emit from satisfying every other case.
Verified by mutation: reporting a failed tool as ok fails 1 case,
never emitting tool_call fails 3.
One test bug worth noting rather than hiding: two cases first failed
because I passed inline arrow functions as tools. An anonymous arrow
registers under the name "", so the mocked call never matched and was
rejected before any event -- which is correct behaviour, and a small
piece of evidence that these events fire only for tools that really run.
1110 tests pass, tsc clean, build emits 290 files, both entries still
report webview-loadable.
Task 5. `praisonai` resolves to src/index.ts, which re-exports the CLI,
the MCP server, the tool registry and the knowledge store -- modules
that read the filesystem, spawn processes and open sockets. A phone
loads none of them, and a bundler cannot tell: it follows every
re-export, pulls the whole graph in, and the build dies on a Node
builtin nothing was ever going to call.
src/mobile.ts is an allowlist rather than a convenience. Everything it
names is checked by scripts/webview-gate.mjs, which now gates both
entries and fails the build if either gains an import-time Node
dependency. The rule for adding to it is written in the file: if it
cannot run in a browser it does not belong there, even if it would be
useful -- a consumer reaching for something absent gets a resolution
error at build time, which beats a blank screen on a device at import
time.
praisonai/mobile, minified: 77.8kB (target was <400kB)
praisonai, root entry: 2.97MB
The export is placed BEFORE './*' in the map so it wins the match.
TASK 2 IS A CORRECTION RATHER THAN A CHANGE. The list called node-fetch
a phantom dependency to delete. It is not a dependency at all -- it sits
in `overrides`, pinning a TRANSITIVE dep's version, most likely for a
security or compatibility fix. Removing it would change resolution for
whatever pulls node-fetch in, which is the opposite of harmless. Left
alone, and recorded here so it is not "fixed" later by someone reading
the same list. dotenv is genuinely gone: absent from every dependency
section and referenced nowhere in src.
Nothing was removed from package.json; the diff is purely additive.
1103 tests pass, tsc clean, and the build emits dist/mobile.js,
dist/esm/mobile.js and dist/mobile.d.ts.
Task 1 of the mobile-consumable list. PR #4438 replaced the Node
`crypto` import in the two files on the Agent graph and left the
identical import in 32 others -- every one of which re-breaks a webview
bundle the moment anything reachable from it is touched. All 32 were
byte-identical: `import { randomUUID } from 'crypto'`.
They now import src/utils/uuid, and the two local copies #4438 left
behind are gone with them, so there is one implementation rather than
three drifting ones.
The tests force the fallback, which is otherwise unreachable:
globalThis.crypto.randomUUID exists in every environment the suite runs
in, so that path would stay green however broken it was -- and it is the
path that exists for older webviews, where nobody is watching a console.
Verified by mutation, four for four:
version nibble ORed without masking -> 3 fail (0xff reads as version f)
variant nibble ORed without masking -> 1 fail
hex byte not zero-padded -> 4 fail
never using the platform generator -> 1 fail
Worth recording: the first mutation run reported the two mask mutations
as SURVIVING. They had not -- jest was serving a cached transform. With
--no-cache both fail. A mutation run against a cached transform is a
mutation run that proves nothing, and it reports the reassuring answer.
Existing behaviour unchanged: 1096 tests pass, tsc clean, cjs+esm build
produces 289 files, and the webview gate still reports the Agent entry
loadable.
An audit went looking for the pattern this codebase keeps producing -- a check
that something was attempted rather than that it worked -- and found two of my
own recent fixes were exactly that.
## The "no output" fix only worked when the stream was completely empty
_drain_tools() empties the queue and returns how many events it emitted. It is
called in two places: inside the streaming loop, and again on the failure path.
The in-loop call discarded its return value, so by the time the tally ran the
queue was already empty and tools_shown was zero. The no_answer branch never
fired, and the user got "the engine produced no output" printed directly
beneath the tool cards it had just been shown.
One frame of anything is enough to take that path -- a reasoning frame, an
empty text chunk. The only case that worked was a generator that yielded
literally nothing, and that is the only case the tests covered:
chunks=() -> no_answer (tested)
chunks=[reasoning frame] -> empty (not tested)
chunks=[""] -> empty (not tested)
The fix is one `tools_shown +=`. The tests now drive the loop body.
## Deleting a key still reported success
FallbackSecretStore was hardened so a delete has to succeed in every store the
secret could be read from. That layer is right, and it was only ever tested
against a fake -- so nobody looked underneath, where both real stores returned
True whatever happened.
Both had the same shape: the write path passes check=True, the delete path did
not. A locked keychain leaves the item intact and `security` exits 51; a Linux
session with no D-Bus cannot reach the collection at all. In both cases the app
said the key was removed, unset it for the running process so it looked gone,
and read it back on the next launch.
Exit 44 from `security` means "no such item", which is a delete that has
already happened, so it stays a success. `secret-tool clear` exits 0 whether or
not it matched, so any non-zero status is a real failure.
The tests put a fake `security` / `secret-tool` on PATH and exercise the real
KeychainSecretStore and SecretToolSecretStore. No keychain is touched.
Six mutations, six caught. Both of these fixes were mutation-tested when I
first wrote them -- against mutations of the layer I had just edited, which is
how a fix passes its own tests while the thing underneath it stays broken.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
PR #4438 made praisonai-ts loadable in a webview by removing the static
`crypto` and `events` imports from the Agent graph. Nothing stops them
coming back.
That gap is structural, not an oversight. `npm test` runs in Node, where
every one of these imports works perfectly -- so no unit test can catch
the regression. A single `import { x } from "fs"` added to any file the
Agent happens to reach would silently un-ship the mobile app, and the
first signal would be a blank screen on a device with no console.
The gate bundles src/agent/simple.ts for a browser target and fails on
any Node builtin reachable at IMPORT time.
STATIC vs DYNAMIC is distinguished deliberately. A static import is
evaluated at module load and kills the bundle outright; a dynamic
`await import()` inside a function only fails if that function is called
-- readline is reached only from createCLIApprovalPrompt, which is
CLI-only by name and contract. Failing on it would force a shim for a
code path a phone cannot take, which is how a gate gets worked around
rather than fixed. Lazy builtins are still printed on every run.
Verified as a positive control: re-adding `import { randomUUID } from
'crypto'` to simple.ts fails the gate with the builtin named and #4437
cited. Without that check this would be a gate whose state on real code
nobody knows.
NOTHING RUNTIME CHANGED. The diff is one new script, one new workflow,
and two lines of package.json. src/ is untouched, and the existing suite
is unaffected: 1096 tests pass, tsc clean, and the cjs+esm build still
produces its 288 files.
The workflow is path-filtered to praisonai-ts so it cannot affect any
other job.
Two bugs the user hit, with one thing in common: the app knew the answer and
did not use it.
## "No output" on a turn whose tools all ran
The desktop engine does not run the praisonaiagents in this repo. It runs the
one installed in the app's venv -- published 1.7.1 -- and in that version a
tool-using turn ends the stream without ever asking the model for its answer:
_start_stream_impl in 1.7.1: 1 x chat.completions.create
the same function in HEAD: 2 x chat.completions.create
So the generator yields nothing, `streamed` stays False (engine/server.py:1797,
set only in the text-delta branch at :1829), and the engine reports "the engine
produced no output" for a turn whose tools every one succeeded.
The library fix already existed here -- commit 06dfc8e59, 25 Aug -- and could
never reach anyone: pyproject.toml still declared 1.7.1, the same version
already on PyPI, and the desktop installs an unpinned `praisonaiagents` exactly
once, on first run. So the version is now 1.7.2 and the desktop asks for
`praisonaiagents>=1.7.2`. **This needs publishing to PyPI to reach users.**
Why it looked intermittent: whether the model answers in text or calls a tool
is a per-turn decision, and only the first shape streams. Why "Try again"
worked: the failed turn still left the tool result in the cached agent's
history, so the retry answered from it in plain text -- the failure fetched the
thing that made the next attempt succeed.
Three defensive changes so this cannot be silent again:
* The engine now drains tool activity on the failure path too. A turn that ran
tools and then died showed neither the answer nor the tools -- the work
happened and left no trace on screen.
* A turn that ran tools but produced no answer now says so, instead of
reporting the same "no output" as a turn where nothing happened at all.
* The library raises instead of ending a tool turn in silence. Returning
quietly there is indistinguishable from a model with nothing to say, which is
precisely how this reached users.
And the dev escape hatch that was supposed to prevent exactly this class of
confusion did not work: engine/server.py computed the checkout path with a
fixed parents[2], which from the bundled copy under src-tauri/target/<profile>/
resolves to target/praisonai-agents -- a directory that does not exist. Its own
comment says it exists so that "a fix appear[ing] to have no effect" cannot
happen. It searches upward now, and honours PRAISONAI_AGENTS_SOURCE.
## A reopened chat had no history
`grep -c chat_history engine/server.py` returned 0. The conversation lived in
two places and only one of them was durable: the transcript on disk, which the
sidebar renders, and the agent's chat_history, which is what the model is shown.
Nothing ever copied the first into the second.
The agent cache is a plain dict in the engine process, so it is empty after any
restart; save_settings clears it outright; and the tools toggle keys a
*different* agent for the same session. After any of those, reopening a chat
showed the user their whole conversation while the model got a blank slate --
and said so: "I don't have access to your previous questions."
The transcript is now replayed into an agent that has none. Only when it has
none: an agent mid-session already holds those turns, including tool messages
the transcript never stored, and replaying over the top would duplicate them.
Blank turns are skipped -- an empty assistant message is what a failed turn
leaves behind, and feeding it back teaches the model that silence is an answer.
## Tests
engine/test_chat_stream.py is new: the chat path had no test at all, which is
why both of these shipped. Twelve tests, agent stubbed, no provider and no key
required. Eight mutations, eight caught -- including removing the replay,
reversing its order, replaying over an agent that already has history, and
restoring the original "no output" branch.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
96 tests for the a11y and i18n layers, plus the fixes for what building
them exposed in the entry point I had just written.
THE LIVE REGION WAS THE SERIOUS ONE. I had put role="log" and
aria-live="polite" on the whole transcript element -- the same element
reconcile/applyOps mutates on EVERY publish. So a screen reader restarts
on each token batch and no sentence is ever finished, which is worse
than announcing nothing: the app becomes unusable rather than merely
opaque. Clearing it for a new chat announced the wipe, too.
Announcements now go through ui/src/a11y/announce.ts, into two small
regions that change only when there is something worth saying. That
policy coalesces to completed sentences, rate-limits at 1200ms, keeps a
character cursor so nothing repeats, flushes the tail when the turn
ends, never reads reasoning or tool arguments, and lets an approval
bypass the limit -- an approval blocks the run, so waiting politely for
the queue to drain waits for something that will not happen until the
user answers.
The second bug: the message textarea was labelled with the SEND button's
name, so the composer announced as "Send, edit text" -- telling a blind
user what the control beside them does and nothing about the one they
are in. It has its own key now, and the comment says why the two are
distinct.
.sr-only uses the clip-rect idiom rather than display:none, because
display:none and visibility:hidden remove an element from the
accessibility tree entirely -- a live region styled either way is a live
region nothing ever reads.
Also consolidates the duplicate string table I introduced in main.ts
onto ui/src/i18n/strings.ts, and routes dom.ts through it -- including
its hand-rolled `event`/`events` plural, which is wrong in most
languages: Polish has three plural categories, Welsh six, Arabic a zero.
One process note worth recording: my `git add -A` on a shared tree swept
four of the a11y agent's in-progress files into the previous commit,
whose message does not describe them. Content was unaffected.
794 tests, 119 files, bundle 42.4kB of 400kB.
The audit's headline was "every layer is a library; nothing is an
application." This is the file that was missing.
tools/bundle.mjs has defaulted its entry to app/src/main.ts since it was
written, and that file did not exist -- so `npm run build` failed on a
missing file and the webview gate had NEVER run against the real import
graph. Every check was in a known state about fixtures and an unknown
state about the code that would actually ship.
It runs now, and it passes:
bundle: 35.1kB of a 400kB budget, 0 external, 0 problems
tools/app-bundle.test.mjs keeps it that way, and asserts more than "it
built": one real symbol per layer must be present in the unminified
output, because a bundle that tree-shook the app away would pass every
other check -- and no testing/ fake may appear, because a scripted
engine reaching a shipped bundle means the app answers with a fixture on
a real device.
Also landing:
app/index.html carries viewport-fit=cover, which is not optional --
without it env(safe-area-inset-*) is 0px in WKWebView and every inset
collapses to flush, silently, because 0 is the documented safe collapse.
app/app.css uses NO viewport units at all. 100vh includes an address bar
that does not exist here and is wrong through every keyboard transition;
the layout comes from measured pixel geometry instead. The composer's
keyboard offset is padding rather than a transform, so the transcript's
scroll height shrinks with it and the last message stays reachable. The
textarea is 16px because iOS zooms the page when focusing anything
smaller.
app/src/platform.ts is the only file naming both shells, and the probe
is synchronous: an async "is there a native shell" answer would make the
first frame guess, paint wrong, and jump.
app/src/crash.ts is the last line of defence -- there was no onerror and
no unhandledrejection handler anywhere, so a throw in a click handler
left a UI that just stopped responding. It reports rather than swallows,
and draws once however many faults follow, because a crash cascades and
repainting each time pins the CPU.
Strings are injected rather than inlined, so gaining a language does not
touch this file.
698 tests, boundaries clean across 108 files.
The settings screen and the text input, both as pure logic. 45 tests,
each load-bearing rule mutation-checked rather than trusted green.
Two design points worth keeping:
Secret rows are structurally value-less -- SecretRow has no value field
plus `readonly value?: never`, so writing one is a compile error, and a
@ts-expect-error test fails the typecheck if that protection is ever
removed. A runtime `"value" in row` check only proves one build behaved.
Presence has THREE states. hasSecret is async and buildSettings is not,
so an unresolved check renders as UNKNOWN rather than "Not set" --
telling someone their key is missing while it sits in the keychain makes
them paste it again.
Closes the gap that build raised: SettingDef could say "this is a
secret" without saying WHICH keychain slot, so a screen could render
presence and still not know where setSecret should write. The mapping
had to be carried in by whoever built the view, which put the one
identifier that addresses a stored credential outside the registry that
declares it.
secretRefOf refuses both mismatches instead of guessing: a secret def
with no ref has nowhere to write, and a non-secret def with a ref would
route an ordinary setting into the keychain where nothing reads it back.
Guessing a slot from the key name would store a real credential at an
address that is never read, and report success.
684 tests, boundaries clean across 98 files.
A live bug, found by the Tauri planning agent reading both adapters
side by side. The Tauri shell read --safe-area-inset-*; the web shell,
which I wrote, read --sai-*. On a real page one of them was always going
to find "", parse it to 0, and lay content flush against the notch.
It fails silently in the worst way: 0 is the documented safe collapse
for a missing inset, so there is no error, no warning, and nothing in
the console -- just content under the camera.
The conformance suite could not have caught it, and that is the more
interesting part. Both shells pass every shell-contract case because
each is driven through its own harness, so NEITHER ever reads real CSS.
A contract that exercises two implementations through fakes cannot see
them disagree about something only the real environment supplies.
So the names now live once, in the port, beside the type they describe.
There is also a test that gives each shell a stylesheet defining only
the shared names -- which is what a real page has -- and asserts both
read the same insets from it. Verified by mutation: changing one entry
fails two cases across two different shells.
Kept the env() spelling rather than the shorter one. A stylesheet line
that reads `--safe-area-inset-top: env(safe-area-inset-top, 0px)` is
self-evidently correct at a glance, which is worth more than four
characters.
dom.ts rendered approval buttons carrying data-approval-id and
data-choice, and nothing in the package listened for them. The prompt
was drawn, it blocked the run, and it could not be answered -- the run
then hangs until the engine's timeout with a correct-looking screen,
which is the worst class of bug here.
The mapping is a pure function over an attribute bag rather than logic
inside a listener, because the cases that matter cannot be tested well
any other way: a tap that lands on the label INSIDE a button (which is
what every real tap looks like -- the finger hits the text, not the
control), a tap on a control that went disabled mid-decision, an id that
went missing from a row.
It walks the ancestor chain outward, which is what every real toolkit
does and what an event.target check gets wrong on exactly the taps users
make most.
Three refusals are deliberate and each is tested with its pair:
- a disabled control does nothing, and a disabled ANCESTOR blocks a
tap on its child -- otherwise the walk finds something actionable
further out, which is worse than doing nothing.
- an unrecognised choice is refused rather than coerced. The run stays
blocked either way, but a refusal is visible.
- an unknown action stops the walk instead of resolving to the
enclosing row's action, which is how a tap on an unfamiliar control
would delete a chat.
Verified by mutation, three for three.
634 tests.
The audit's sharpest structural point: every port, conformance suite and
view model existed, and nothing declared what the app actually OFFERS.
SettingDef[] was an injected parameter only a test ever supplied, and no
code path constructed a real engine, so no live answer was possible.
Both registries live in app/ because they are the only place that names
a concrete engine or a concrete setting -- which is exactly what keeps
every layer below unable to tell one engine from another.
An engine whose prerequisites are absent is OMITTED rather than offered
and then failed: a picker listing a choice that cannot work is a support
ticket, and selectEngine already reports "no engine X; available: ..."
which is the honest message. So praisonai-ts appears only when a factory
is injected -- praisonai cannot be a dependency until it is bundleable
for a webview (#4437), and the remote engine needs nothing injected and
works today.
The tests assert against the REAL registry rather than a fixture, which
is the only way the "apiKey is secret" case means anything: a def that
forgot secret:true would put a live key in a plain settings file, and a
fixture cannot catch that.
Also: the base URL loses a trailing slash. `${baseUrl}/v1/run` against
"http://host/" produces a double slash, which some servers 404 and
others silently redirect -- losing the POST body.
618 tests.
The controller hardcoded chatId: "current", so every turn from every
conversation carried the same literal and an engine had no way to tell
them apart. Switching chats mid-stream is the case that matters: the
answer still in flight belongs to the chat it started in.
markIdle was flagged by the audit as violating its own documented
contract -- "a turn finished AND was persisted" -- because the
controller calls it unconditionally. Traced it rather than changing it,
and the code is right while the doc was imprecise:
- persistence happens BEFORE `end` is emitted, so a successful turn is
already on disk by the time the finally block runs.
- a cancelled or errored turn is deliberately not persisted, and
idling anyway is required, not a bug: the alternative is a queue
that stays busy forever after one failure and deadlocks every prompt
behind it.
- nothing is at risk, because indices come from stored messages only,
so the next turn numbers from what is really there --
session.test.ts asserts exactly that.
Documented the reasoning where the next reader will hit it.
An audit found the keychain port completely inert: SettingsFacade had
no way to enumerate keys, no change notification, and -- the part that
mattered -- no way to WRITE a secret at all. set() refuses any
secret-flagged def and setSecret was not on the facade, so there was no
reachable code path in the package that stored a key. A fresh install
had no way to become usable.
The facade now carries defs(), subscribe(), setSecret() and
clearSecret(). It still has no getter, and that asymmetry is the design:
a view can configure a key and prove one is present without ever being
able to fault the value into a render tree, a log, or a screenshot.
SettingDef gained label, help, section and choices, so a screen renders
a control from data instead of hard-coding the key list that already
exists as data -- the two drift the first time a setting is added.
subscribe fires only after an ACCEPTED write. Notifying on a refused one
makes a screen redraw a value the user did not manage to change, which
reads as the setting having been accepted. Secret writes notify too, or
a row keeps saying "not set" after a key is stored.
619 tests.
ChatRepository was fully tested and called by NOTHING. Every turn
streamed, rendered, and evaporated. The hole was structural rather than
an oversight: TurnState is assistant-only, StoredChat has both roles,
and no layer owned the join -- docs/gaps.md #4.
createSession owns it, and it is what engines call to record a turn.
That placement is the point: end.userIndex is authoritative and cannot
be computed by a client, because a cancelled or errored turn stays on
screen and is never written, so screen position and disk position
diverge immediately. The indices now come from whatever actually did
the write, and null means the write failed -- which is what withholds
Fork and Delete rather than offering them against a message that is not
there.
The user's message is written when the turn SUCCEEDS, not when send was
pressed, so an abandoned turn cannot leave a dangling prompt with no
reply beneath it in a stored transcript.
A failed write also does not advance the in-memory chat, or the next
turn's indices are computed against messages that were never stored and
every index after it is wrong.
Verified by mutation, three for three: an off-by-one index fails 2
cases, keeping a failed write fails 10, dropping the save fails 4.
596 tests.
Two pieces the package needed before it could have a UI at all.
ui/src/render/reconcile.ts is the diff, and it is pure. A streaming
answer publishes many times a second; rebuilding the transcript each
time throws away every node, loses selection, and forces layout on the
whole list to repaint one character. The tests assert OPERATIONS rather
than outcomes, because a suite that only checks "the right rows are
present" passes just as well against the rebuild-everything renderer
this exists to prevent -- and one case measures it: 200 publishes of a
growing paragraph cost exactly 200 ops.
Verified by mutation. Always-update fails 4 cases; comparing raw
previous indices instead of surviving order fails 3 -- that second one
is the bug where inserting a row reports a move for everything below it.
The exhaustiveness check in signatureOf immediately caught two row kinds
I had missed (error, dropped), which is the whole reason it is written
as a never-assignment rather than a default case.
adapters/src/web/shell.ts makes "runs end-to-end in a browser, no
Tauri" true. It is honest about the platform: no haptics, share falls
back to the clipboard, and the keyboard comes from visualViewport --
the only browser API that reports a software keyboard, clamped at 0
because overscroll can make it briefly negative.
It reports all THREE lifecycle phases, from three different signals.
visibilitychange alone cannot express "inactive", and collapsing that
into "background" would flush and stop the render loop every time the
user pulled down a notification. The contract caught that; I had
collapsed it at first.
Back is wired to popstate, which is a browser's Back, with the same
last-registered-first stack every other shell uses.
All three shells -- fake, Tauri, web -- now pass one contract.
580 tests, boundaries clean across 85 files.
docs/gaps.md #1. TurnState had text as one accumulated string and tools
as a parallel array, so a view could render all the prose and then all
the tools -- and nothing else. That is not how any chat UI shows a
multi-step turn, and it is not something a renderer can work around.
TurnState now carries blocks: the turn in the order it happened. A delta
extends the open text block or starts a new one; a tool_call appends a
tool block; a tool_result for a call never seen gets a position too, or
its row exists in tools and appears nowhere on screen -- the same silent
loss the reducer creates that row to avoid.
The invariant that stops two representations of one thing drifting is
asserted rather than hoped for: every text block concatenated reproduces
text exactly. Both directions verified by mutation -- every delta
opening its own block fails one case (and would be thousands of nodes
per answer), a tool_call adding no block fails three.
buildTranscript walks blocks now, and only the LAST text block streams:
an earlier one was closed by the tool call after it, and a caret on it
would claim two places are being written at once. Row ids are distinct
per block, because two rows sharing an id is how a keyed renderer paints
the second paragraph into the first one's node.
534 tests.
The upstream-parity job failed twice. First on npm ci -- praisonai-ts
gitignores its lockfile. Then on npm install, which fails there with an
ERESOLVE peer conflict (bedrock-agentcore -> @strands-agents/sdk). The
package's dependencies simply do not install cleanly.
That turned out to be the wrong problem to solve. Every member the check
looks at -- streamEvents, lastStopReason and their types -- is declared
locally in simple.ts, so unresolved third-party imports degrade only
unrelated members. The check needs typescript, which THIS package has,
and nothing else.
Asserted rather than assumed, across all four combinations:
deps=present api=correct -> passes
deps=present api=drifted -> FAILS
deps=absent api=correct -> passes
deps=absent api=drifted -> FAILS <- the one that matters
Without that last row this would have been a check that always passes
once the install is gone, which is worse than deleting it.
tsc now runs from praisonai-mobile and only errors AT the generated
parity file count as drift. An assignability failure always reports at
the assignment site, so nothing real is lost -- while TS2307 and TS7006
noise from praisonai-ts's own sources would otherwise fail every run.
The job is also now cheap: one cached npm ci instead of installing a
large dependency tree that could not install anyway.
The upstream-parity job failed on its first run in 10s. praisonai-ts
deliberately gitignores package-lock.json (src/praisonai-ts/.gitignore:6),
so 'npm ci' fails outright -- it exists precisely to install FROM a
lockfile. 'npm install' is what the repo already uses for that package
elsewhere (claude.yml:345).
Also hardens the check itself. tsc has to resolve praisonai-ts's own
imports to typecheck its Agent, so with no node_modules it cannot run at
all. It now SKIPS loudly and names the command to fix it, rather than
failing -- reporting a missing install as upstream drift would send
someone looking in agent-api.ts for a problem that is not there.
Both paths verified by moving node_modules aside: absent -> skip with
the fix printed, exit 0; present -> the real check runs.
The two check jobs passed on their first run, on both node 22.18 and 24
-- so the floor declared in package.json is real rather than a guess.
No workflow referenced praisonai-mobile, so its 523 tests would never
have run on a PR. That is not hypothetical here: praisonai-desktop's
suite existed and ran nowhere for months for exactly this reason, and
desktop.yml opens by saying so.
Four gates, catching different things:
typecheck erasableSyntaxOnly. node:test STRIPS types rather than
compiling, so an enum or a constructor parameter property
is a runtime parse error at import -- this turns that into
a typecheck failure at the file that caused it.
boundaries the two seams. Only engines/src/praisonai-ts may import
'praisonai', only adapters/src/tauri may import
@tauri-apps. A rule enforced only by review stops being
enforced.
test the suite.
test:bundle the gate's OWN fixtures, which prove each check can fail.
A build check that has only ever seen clean input is a
check nobody knows the state of.
The bundle gate is the one a normal test run cannot do: node:test runs
in Node, where a 'crypto' import and a top-level process.env both work
and both kill a webview bundle at import time.
Node matrix is 22.18 (the floor declared in package.json -- tested
because a declared floor nobody runs is a guess; 22.18.0 is where type
stripping became unflagged) and 24 (the forward check).
upstream-parity is its own job so drift from the real Agent is visible
in the checks list rather than buried in another job's log.
All five steps verified locally against the real package.
The fix is right, but it swaps two battle-tested Node implementations
for hand-written ones and adds no tests. Both replacements sit on paths
CI cannot reach on its own:
randomUUID's fallback is dead code in every environment these tests run
in, because globalThis.crypto.randomUUID always exists there -- so it
would stay green no matter how broken it was. It is also the path that
matters, since it exists for older webviews, where nobody is watching a
console. The version and variant nibbles are set by hand, and an
all-0xff and an all-0x00 source are the inputs that expose a bad mask.
SimpleEventEmitter's risky parts are not the obvious methods. They are
once-unwrapping inside off -- without it a caller's unsubscribe silently
never matches, and the listener keeps firing afterwards -- and mutation
during emit, where splicing a live array shifts every later index down
and skips the next listener while still reporting success.
Verified non-vacuous by mutation, four for four:
emit iterates the live array (no slice copy) -> 3 fail
off compares by identity only -> 1 fail
version nibble ORed without masking -> 2 fail
hex byte not zero-padded -> 3 fail
21 tests. Full suite 1082 passing, tsc clean.
.gitignore has `src/*/build/`, which is right for build OUTPUT and
wrong for build TOOLING. So the previous commit's message described a
bundle.mjs that existed only on my disk. Moved to tools/, next to the
boundary checker, which is tracked and is where it belonged anyway.
Also refines the gate itself, after verifying PR #4438 against it
exposed a limitation: it treated every Node builtin alike, so a lazy
import no mobile path can reach failed the build exactly like an
import-time one. That is the difference between a blank screen and a
feature that is merely unavailable -- readline is reached only from
createCLIApprovalPrompt, which is CLI-only by name and contract.
Failing on it would force a shim for a code path a phone cannot take,
which is how a gate gets worked around rather than fixed. Lazy builtins
are still printed every build. Static wins when both kinds appear.
Against the real praisonai-ts:
main builtins=[crypto, events, readline] problems=1
PR #4438 builtins=[readline] problems=0
523 tests, boundaries clean.
Step 19. createApp() takes its adapters INJECTED rather than building
them, so the whole boot sequence runs under node:test against fakes. A
composition root that constructs its own dependencies is the one part of
an app that can never be tested, and it is also where ordering bugs live
-- every case in boot.test.ts is an ordering or a teardown question.
Ordering that is asserted rather than assumed: settings load before the
engine is built (the engine choice and its credentials come from there);
dispose unsubscribes from the shell BEFORE disposing the engine, or a
lifecycle event arriving mid-teardown calls stop() on a disposed engine.
app/src/engines.ts is the only file that knows more than one engine
exists. It returns a result rather than throwing -- an unusable engine
should land the user on a settings screen naming which and why, not on a
crash handler -- and it disposes an engine it rejects, since one left
holding a socket only ever shows up as a second, unrelated failure.
Two of my own tests had the wrong premise and the suite corrected me:
checkProtocol deliberately ACCEPTS a newer engine, because decode.ts
degrades an unrecognised event rather than dropping it, so a v3 client
against a v4 engine loses an affordance and not the conversation. The
real failures are too_old and unreadable, and there is now a pair
asserting the newer case is accepted.
Also lifts fakeTime out of controller.test.ts into testing/src/fake-time
-- it was private there, so any other test needing a TimePort either
rewrote it or reached for real timers, which is how a pacing suite goes
flaky on a loaded CI box.
519 tests, boundaries clean across 80 files.
Step 21. Adds adapters/src/tauri (bridge + shell) and a shell contract
run against BOTH the fake and the Tauri adapter so the two cannot drift.
Three things were living in one implementation and are now part of the
contract, because an adapter author reading only the port would ship
without them:
- openExternal's scheme allowlist. In a webview a javascript: URL is
script execution in the app's OWN origin with the user's session,
and the URL routinely comes from a model, a tool result or a pasted
message. The rule was in the Tauri shell only, so the fake accepted
anything and the contract could not assert it. Now in core, obeyed
by both, with an allowlist rather than a blocklist -- the dangerous
set is open-ended and platform specific.
- back handlers are a STACK, last registered first. This was a comment
inside the fake; a second author using a Set has no defined order and
ships a modal that never consumes the gesture.
- insets and keyboard height must be updated BEFORE subscribers run,
since every re-render re-reads the snapshot inside the callback.
keyboardHeightPx is new, and both agents building against this port
asked for it independently: a component mounting while the keyboard is
already up laid out at 0 until the next transition -- one wrong frame,
then a jump. Exactly the reasoning already written for insets.
Verified by mutation rather than assumed. A permissive allowlist fails
9 cases; notifying before snapshotting fails 3. One of my own tests was
vacuous and the mutation run caught it: an uppercase JAVASCRIPT: URL is
refused whether or not the comparison is case-insensitive, so the case
that matters is an uppercase HTTPS: still being OPENED.
504 tests, boundaries clean.
Building the ui layer against core and protocol surfaced nine design
gaps. Two were cheap and are fixed here; the other seven are written
down in docs/gaps.md rather than fixed, because each needs a decision.
ttft sat next to a field called seconds with no unit in its name, so a
renderer had to guess between seconds and milliseconds -- 1000x in a
number the user reads. The TS field is ttftSeconds now; the wire key
stays ttft, translated in decode.ts, which is the one place that
translation is supposed to happen. The all-11-events round-trip test
covers it.
versions and active had no documented meaning, so the UI could not
render them and dropped them. Both documented, including why decode.ts
clamps active into [0, versions-1] instead of trusting it: an
out-of-range index selects nothing and the message renders blank.
484 tests.
Step 18. Framework-free on purpose: every decision is a named exported
function returning a description of what to render, so the React Native
port reimplements the renderer and reuses all of this.
The load-bearing one is approval routing. decisionIdOf() is the only
sanctioned way to get the id that goes back on the wire, and the
two-approval test delivers the prompts in the OPPOSITE order to their
tool rows, so any index-zip crosses rm with curl. Verified by mutation:
returning row.callId instead of row.approvalId fails two tests.
Tool success comes only from tool_result.ok, never inferred from a
non-empty output; a call with no result renders unresolved, never
successful; seconds: null renders as unknown rather than zero.
Fork/Delete are withheld when end.userIndex is null -- and offered at
index 0, which is the falsy-check trap that would hide them on the
first message of every chat.
At the root route the back handler returns false so Android can exit; a
handler that always returns true traps the user inside the app.
79 tests, every 'must not' paired with the case that makes an
always-refuse implementation fail.
Both were written and never read, silenced with void. streamed was
genuinely dead and is gone. disposed now fails a run fast: a disposed
engine that still accepted runs would start a provider request cancel()
can no longer reach, since dispose() has already cleared the live map it
looks in -- so Stop would report false forever.
engine.ts claimed 'a signature change upstream is a typecheck error here
rather than a runtime surprise on a device'. Nothing actually checked
that, so it was a comment. This makes it true.
The check is one assignment -- the real Agent to the structural
PraisonAgent -- and tsc names the diverged member when it fails.
Verified as a positive control: injecting a member the real Agent lacks
produces 'Property renamedUpstream is missing in type Agent'.
Kept out of npm test deliberately: it needs the sibling praisonai-ts
checkout, present in the monorepo and absent in a standalone clone. It
SKIPS loudly there rather than passing quietly, because a check that
silently stops covering anything is worse than no check.
Step 20. build/bundle.mjs fails the build on three things node:test
cannot catch, because node:test runs in Node where all three work:
- a Node builtin surviving into the bundle. Read off the esbuild
metafile rather than grepped from the output, because a grep cannot
tell an import from a string containing the same word -- there is a
test for exactly that innocent case.
- a TOP-LEVEL process.env read. Scoped to depth zero on purpose: a
guarded read inside a function is how the codebase is expected to
read env, and a check that failed on it would be unusable. Both
directions are tested.
- silent size growth, against a deliberately tight 400kB budget.
Pointed at the real praisonai-ts Agent it reports crypto, events and
readline -- two of them static and unconditional, so the failure is at
import time with no error boundary and a blank screen. Filed upstream as
issue #4437. Top-level process reads are now 0 there, which is #4425.
Also adds testing/src/fake-shell.ts: back-gesture handlers are an ARRAY
rather than a Set, because they are a stack and the most recently
registered gets first refusal -- a Set has no defined order, so a modal
would not reliably consume the gesture ahead of the route beneath it.
326 tests.
Steps 15-16. Implements AgentEnginePort on top of praisonai-ts and runs
it through the same conformance suite as remote-http and the scripted
fake: 21/21, with 5 scenarios declared unsupported and printed.
The coupling is declared structurally in agent-api.ts rather than
imported from 'praisonai'. Three consequences: the tests need no
provider, no network and no key; the file IS the list of what swapping
frameworks would cost (one class, three methods, a three-variant union);
and a signature change upstream fails the typecheck here rather than a
device at runtime.
Capabilities are stated against what the engine can REPORT, not what it
does internally -- so tools is false even though praisonai-ts executes
tools, because it never announces them and a UI rendering rows from a
true flag would render nothing. Recorded in docs/gaps.md.
end.userIndex comes from an injected RunPersistence and is null when the
write failed, never a fabricated zero. Deriving it is what shifted every
subsequent Fork onto the wrong message on desktop.
The classifier test caught a real bug: /\bauthentication\b/ does not
match Anthropic's 'authentication_error' because _ is a word character,
so a bad key was classified internal and sent the user to 'try again'
instead of to settings.
311 tests, boundaries clean.
Store the original listener on the once wrapper and match it in off()
so passing the original callback to off() removes the subscription,
mirroring Node EventEmitter semantics.
Co-authored-by: Mervin Praison <[email protected]>
Replace the static `crypto` import in agent/simple.ts and the static
`events` (EventEmitter) import in ai/tool-approval.ts with browser-safe
internal implementations, so `Agent` can be bundled for browser/webview
targets without pulling Node builtins at import time.
- simple.ts: local `randomUUID()` backed by WebCrypto with a Node<19 fallback
- tool-approval.ts: `SimpleEventEmitter` (~20 lines) backing ApprovalManager,
plus WebCrypto-safe `randomUUID()` in place of bare `crypto.randomUUID()`
Public API is unchanged; `readline` stays lazy (CLI-only).
Co-authored-by: MervinPraison <[email protected]>
The interpolation depth-scanner counted braces inside line/block comments
and regex character classes as structural, prematurely closing the ${...}
interpolation and hiding a genuine require()/__dirname that followed it,
so the emitted ESM omitted its createRequire banner (Greptile P1).
The scanner now skips line comments, block comments, and regex literals
(disambiguated from division via the previous significant char), so their
braces no longer affect depth. Adds regression tests for regex-with-brace,
comment-with-brace, and division-not-regex cases.
Co-authored-by: Mervin Praison <[email protected]>
needsCjsBanner() tested /\brequire\b/ against raw file text, matching the
word require (and __dirname/__filename) inside string literals and comments.
24 of 288 emitted ESM files got a createRequire banner they did not need,
each gaining hard imports of module, url and path — e.g. openai.js bannered
solely by the error string "Zod schemas require zod-to-json-schema".
- Add stripStringsAndComments() to blank strings/templates/comments (newlines
preserved) before detection.
- Match real require(...) call expressions and identifier-position
__dirname/__filename (not obj.require).
- Run main() only via require.main === module and export helpers so tests
assert on the actual emit transform.
- Add esm-shim-banner.test.ts (10 cases, both directions).
Bannered ESM files: 24 -> 9 (remaining all have genuine require/__filename).
Co-authored-by: Mervin Praison <[email protected]>
`start()` with no `onToken` defaulted to `process.stdout.write`, which
threw on the FIRST streamed token in a webview -- after the constructor
had already succeeded, so the constructor guard alone did not cover it.
Extracted as `writeTokenToStdout` rather than left inline, so the test
calls the real function instead of re-implementing the guard beside it.
Both directions are asserted: absent stdout must not throw, and a
present stdout must still be written to, so "never write" cannot pass.
Credit to #4435, which spotted this call site.
A Tauri/React-Native webview has no `process`. Fifteen unguarded
`process.env` dereferences — five of them in the `Agent` constructor
itself — threw `ReferenceError: process is not defined` on the first
`new Agent(...)`, so the bundle died at import time on a device while
every Node test passed.
`getEnv()` already existed in llm/openaiClientOptions and already does
the `typeof process !== 'undefined'` guard; these call sites simply were
not using it. Routed all fifteen through it across six files.
The new test deletes `globalThis.process` rather than mocking `getEnv`,
so a newly added raw deref fails it too. Verified as a positive control:
against the pre-fix constructor all four cases fail with the
ReferenceError at simple.ts:244.
Closes#4425
needsCjsBanner() tested /\brequire\b/ against raw file text, matching the word
inside string literals and comments. 24/288 emitted ESM files gained a
createRequire banner plus hard imports of module/url/path they never needed;
the clearest case, llm/providers/openai.js, was banner-ed solely because of the
error string "Zod schemas require zod-to-json-schema" despite having no
require() call. This made the built ESM strictly worse to bundle than source.
Strip strings/comments before detection and match real CJS usage: require(...)
call expressions and __dirname/__filename/module in identifier positions.
Bannered files drop from 24 to 9 (all with genuine __filename/require).
Adds esm-shim-banner.test.ts asserting on the emitted transform output in both
directions: a string/comment/template "require" must NOT get the banner, while a
real require()/__dirname/module.exports must.
Co-authored-by: MervinPraison <[email protected]>
Breaking out of a stream's for-await loop detached the token sink but
never aborted the request, so the provider kept generating and billing.
- Add signal?: AbortSignal to AgentStreamOptions and thread it into start()
- streamEvents owns an AbortController aborted in its finally, so break
(the iterator's return()) stops the upstream request by default
- Set lastStopReason = 'cancelled' on abort, distinct from 'error'
- Pass abortSignal into the post-tool-loop structured-output generateChat
Co-authored-by: MervinPraison <[email protected]>
v4.7.3 shipped with no macOS downloads. Both Mac legs failed, and the gate
added one commit earlier is why -- it looked for the .app, and by the time it
runs there is no .app:
Bundling PraisonAI.app (.../bundle/macos/PraisonAI.app)
Signing with identity "-"
Signing .../PraisonAI.app: replacing existing signature
Bundling PraisonAI_0.1.0_aarch64.dmg
Cleaning .../bundle/macos/PraisonAI.app <- deleted here
So the same run proves two things: the signing fix works exactly as intended,
and the check written to guard it could never have passed.
It now mounts the DMG and verifies the bundle inside. That is also the better
check -- the DMG is the artifact people download, and the one that was broken.
Both directions verified locally against real disk images rather than argued:
the published v4.7.2 DMG fails the gate ("code has no resources but signature
indicates they must be present", Sealed Resources=none), and a properly ad-hoc
signed DMG passes it ("valid on disk", "satisfies its Designated Requirement",
Sealed Resources version=2 rules=13 files=7). A gate that only ever rejects is
not a gate; it needed the positive control as much as the negative one.
While testing, my own harness reported the broken DMG as passing. It piped
codesign to head and read ${PIPESTATUS[0]}, which zsh spells differently, so
the exit status was silently discarded. The workflow does not pipe that command
and was never affected -- but the near miss is worth recording, because a test
harness that swallows the status under test is the same defect as the one being
fixed, one level up.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
- Stop the MCPToolRunner (best-effort join) before raising on init
timeout/error so a blocked handshake does not leak a daemon thread and
its stdio child process across construction retries.
- Only exempt the empty-tools fail-closed check when a filter actually
removed tools: if the server itself advertised zero tools, raise even
when allowed_tools/disabled_tools is set (a filter cannot be blamed for
an already-empty server).
- Add regression tests for filter-plus-empty-server and filter-removes-all.
Co-authored-by: Mervin Praison <[email protected]>
Reserved job verbs (submit/status/result/cancel/list/stream) now win over
os.path.exists() so a stray file named after a verb can't steal the jobs
API. Explicit paths like ./submit still route to the YAML runner. Adds a
regression test for the collision case.
Co-authored-by: Mervin Praison <[email protected]>
- Re-raise KeyboardInterrupt/SystemExit/GeneratorExit in the Chroma client
init and directory-walk BaseException handlers so Ctrl+C / interpreter
shutdown is no longer masked as a backend RuntimeError.
- Point Knowledge.config's default vector_store path at
.praisonai/knowledge/chroma so the primary Agent flow actually uses the
isolated per-project store (matches _default_chroma_path). User-supplied
path still overrides.
- Add regression test for KeyboardInterrupt propagation.
Addresses Greptile & CodeRabbit review feedback on #4376.
Co-authored-by: Mervin Praison <[email protected]>
- Agent.processToolCalls now receives the resolved AbortSignal and refuses
to invoke (side-effecting) tools once aborted; cancellation propagates out
of the loop instead of being buried as a tool error result.
- ai-sdk backend: caller cancellation is terminal (non-retryable CANCELLED)
instead of being misclassified as a retryable TIMEOUT and re-attempted.
- mergeSignals now returns cleanup that detaches fallback abort listeners in
every request finally block, preventing MaxListenersExceededWarning on
Node < 20 with a shared agent-level signal.
- OpenAIService.streamText forwards an optional AbortSignal to the client.
- Tests: Agent tool-loop cancellation (aborted vs. running).
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
The legacy dispatcher routed every `args.command == 'run'` to the async-jobs
API, whose argparse only accepts {submit,status,result,cancel,list,stream}. So
`praisonai run agents.yaml` (and the unified dispatcher's rewrite of
`praisonai agents.yaml` -> `run agents.yaml`) hit the jobs parser and failed
with `invalid choice` (exit 2) instead of running the team.
Detect a YAML/file first token and hand it to the modern Typer agent runner
(commands/run.py `run_main`), which already resolves YAML files via
`_is_yaml_file`. Genuine job verbs (`run submit`, etc.) still reach the jobs
API unchanged.
Co-authored-by: Mervin Praison <[email protected]>
Adds a cooperative cancellation path so a UI Stop button can actually stop
a run and stop token billing. AbortSignal is threaded end-to-end:
- signal?: AbortSignal on GenerateTextOptions/StreamTextOptions/GenerateObjectOptions
- OpenAI provider forwards it via create(..., { signal })
- Anthropic and Google providers forward it via fetch(..., { signal })
- AI-SDK backend MERGES the caller signal with its timeout controller
(was overwriting it) so aborting either stops the request
- Tools registry honours the previously-dead ToolExecutionContext.signal
- OpenAIService + Agent.chat()/start() + SimpleAgentConfig.signal, with an
explicit per-call signal taking precedence over the agent-level default
(mirrors Python cancel_token > interrupt_controller)
Behavioural tests call the code and fail before the fix.
Co-authored-by: Mervin Praison <[email protected]>
A stdio MCP server that times out on init, errors on init, or lists zero
tools previously only printed a warning and returned an empty _tools list.
Agent(tools=mcp) then ran as a tool-less chat and the model hallucinated
answers (n_tools=0). Now MCP raises TimeoutError/RuntimeError instead of
handing back a usable-but-empty object.
Co-authored-by: Mervin Praison <[email protected]>
Default ChromaKnowledgeAdapter persist path was the cwd-relative string
"knowledge_db", which two projects/harnesses can share and which lets
Chroma's rust bindings panic (pyo3 PanicException, a BaseException) and
kill the process on Windows. Now defaults to an absolute per-project
.praisonai/knowledge/chroma, wraps PersistentClient in try/except
BaseException -> RuntimeError, and adds a BaseException guard to the
directory-walk indexer so a native panic no longer unwinds the process.
Co-authored-by: Mervin Praison <[email protected]>
Document TypeScript SDK ownership in the monorepo, add PR review checklists,
and point issue triage at src/praisonai-ts/AGENTS.md so agents review TS changes correctly.
Co-authored-by: Cursor <[email protected]>
CONTRIBUTOR bug reports with # [BUG] in the body but plain titles (e.g. #4374)
were skipped because autoClaude required an actionable title prefix. Now any
bug label or [BUG] marker triggers Claude; enhancement still needs title prefix.
Co-authored-by: Cursor <[email protected]>
Two correctness fixes flagged by Greptile (P1) and CodeRabbit (Major) in the
unified streaming+tools loop:
1. Assistant/tool message pairing: when a response exceeded
maxToolCallsPerTurn, the assistant message stored every declared tool_call
but only the capped subset got tool result messages, causing the next
OpenAI request to 400 on unresolved tool_call_ids. Now the assistant
message lists only the executed subset.
2. response_format + tools mutual exclusivity: tool rounds no longer send the
json_schema response_format (OpenAI treats them as exclusive). The schema is
applied on a final tools-omitted request once the model stops calling tools.
Adds a behavioral test asserting the assistant tool_calls stay 1:1 with tool
results when the per-turn cap truncates.
Co-authored-by: Mervin Praison <[email protected]>
Streaming and tools are no longer mutually exclusive. A streaming agent
can now call tools: text deltas, tool calls and tool results interleave
on one request per round-trip via a new OpenAIService.streamChatWithTools.
- Remove the `this.stream && !this.tools` gates; the tool loop streams
when `stream` is set and blocks otherwise.
- Default maxIterations 5 -> 20 (Python ExecutionConfig.max_iter parity).
- Add maxToolCallsPerTurn (default 10, Python parity).
- Add Agent.lastStopReason ('completed' | 'max_steps' | 'cancelled' |
'error') so a truncated run is distinguishable from a completed one.
- Tests call the code path: a streaming run with tools yields text AND
executes a tool, plus exhaustion sets lastStopReason='max_steps'.
Co-authored-by: Mervin Praison <[email protected]>
Resolved rebase onto main: kept main's new AI SDK backend branches
(tools + outputSchema via generateObject) and applied this PR's
stream->streamEnabled rename + emitToken sink. Added the required `name`
field to the approval-denial tool result so processToolCalls's return
type is satisfied (tsc clean; agent + llm suites green).
Co-authored-by: Mervin Praison <[email protected]>
The version the macOS signing fix ships in. v4.7.2's two DMGs cannot be opened
on any Mac -- the bundle was never signed, so the only signature on it was the
linker's, which declares a resource seal an unsigned bundle does not have, and
macOS reports that as "damaged" rather than as untrusted.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Agent.stream() ignored the finish event, so agents running with
stream:false, tools, or an outputSchema (which emit only a finish event,
never token deltas) yielded no output. Now stream() surfaces finish.text
when no deltas were emitted. Adds a regression test and completes JSDoc
@param/@returns for the streaming APIs.
Co-authored-by: Mervin Praison <[email protected]>
Add Agent.stream() yielding AsyncIterable<string> (mirrors Python's
iter_stream, which yields plain str) plus Agent.streamEvents() for
structured AgentEvent deltas/finish/error. Remove both
process.stdout.write calls in start(); tokens now route through an
internal onToken sink that defaults to stdout only for CLI use, so
non-terminal hosts (browser, webview, React Native, server) can render
answers as they arrive. Cancellation is a single path: breaking the loop
detaches the sink.
Co-authored-by: Mervin Praison <[email protected]>
Regenerate the lockfile importer to match package.json so
`pnpm install --frozen-lockfile` (CI) no longer fails with an
outdated-lockfile error. Removes the dotenv/node-fetch direct-dependency
entries and the now-unused dotenv package/snapshot; node-fetch remains as
a transitive dependency. Addresses Greptile P1 review feedback.
Co-authored-by: Mervin Praison <[email protected]>
Importing the package no longer reads process.env or runs dotenv.config()
at module-initialisation time, so it does not throw in runtimes where
`process` is undefined (webviews/bundles).
- logger.ts: lazy, `typeof process`-guarded `level` getter
- openai.ts: drop module-scope `dotenv.config()` and the dotenv import
- package.json: remove unused `dotenv` and `node-fetch` dependencies
- add behavioral tests that call the code (guarded level read; import
without throwing / no dotenv)
Co-authored-by: Mervin Praison <[email protected]>
Address reviewer findings on the dual ESM+CJS build:
- package.json: the restrictive exports map (only "." + "./package.json")
broke documented deep imports (praisonai/ai, praisonai/tools,
praisonai/integrations/*, praisonai/db/*) with ERR_PACKAGE_PATH_NOT_EXPORTED.
Add "./*" file subpath, "./*/index" and explicit "./ai"/"./tools" dir
entries mapping to both esm and cjs outputs.
- esm-shim.js: tsc leaves explicit relative require('./x') calls in the ESM
output; under dist/esm (type:module) those throw ERR_REQUIRE_ESM on Node <22
(engines: node >=18). Repoint every internal relative require at its mirrored
CommonJS twin under dist/ (resolved from the twin dir so package.json and
directory-index targets also resolve), so createRequire loads real CJS/JSON.
- dual-build.test.ts: always rebuild (npm run build) so tests never validate
stale artifacts; add behavioural tests asserting no relative require resolves
inside dist/esm and that documented deep-import subpaths load under native ESM.
npm test: 1008 passed, 87 skipped, 0 failed. verify:dist: cjs + esm OK.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
- Add getEnv() helper reading process.env only when defined, and route all
OpenAI client apiKey lookups through it (openai.ts, providers/openai.ts) so
browser/webview/React-Native hosts no longer throw ReferenceError.
- Guard top-level dotenv.config() behind a process check.
- Honour an explicit dangerouslyAllowBrowser:false even when the base options
already carried the flag (strip it).
- Add JSDoc (@param/@returns/@example) to exported helpers.
- Add regression tests for getEnv and the explicit-false override.
Co-authored-by: Mervin Praison <[email protected]>
The `approval: true` shorthand built a bare ApprovalManager with no handler,
so requestApproval() fell through to a respond()-awaiting Promise that nobody
resolves — blocking every tool call for the full 5-minute timeout before
denying, compounding across calls and exhausting maxIterations.
Wire the existing createCLIApprovalPrompt() as the default handler so the
shorthand prompts interactively (safe by default, hard to misuse). No new
deps or exports. Adds tests asserting a handler is wired and that denial
resolves without hitting the timeout.
Co-authored-by: Mervin Praison <[email protected]>
- processToolCalls now sets `name` on tool-role results so the AI SDK
adapter emits a non-empty toolName; non-OpenAI providers previously
rejected the follow-up request.
- When both tools and outputSchema are configured, the resolved final
answer is produced via generateObject instead of dropping the schema,
matching the OpenAI native path.
- Extend cross-provider tests: assert tool name propagation and the
tools+outputSchema combination.
Co-authored-by: Mervin Praison <[email protected]>
Two regression gaps flagged in review, both places where the release-signing
tests would keep passing after a future change that reintroduces the exact
failure they exist to catch:
- The signingIdentity assertion accepted any truthy value; only "-" is the
ad-hoc identity that makes the shipped "damaged" bundle's signature valid.
Any other value is a Developer ID with no keychain to satisfy it (codesign
fails) or a typo. Pinned to "-".
- The verify-before-upload test checked command presence and ordering but not
that the step is scoped to macOS. Flipping its `if` to skip macOS -- or
dropping it so it runs on Linux where codesign is absent and the step is
silently skipped -- passed every assertion. Now pins `if: runner.os == 'macOS'`
on the codesign step.
Mutation-checked: a bogus identity and a Linux-scoped gate each fail exactly
one test; 15/15 green otherwise.
Co-authored-by: Mervin Praison <[email protected]>
The published package was CommonJS-only with no exports map or module field,
so tsc downleveled every `await import()` into a `require()` that browser/RN
bundlers cannot resolve statically. Add a parallel ESM build plus an exports
map so dynamic import() survives as a lazy chunk.
- package.json: add `module` + `exports` (types/import/require/default);
split build into build:cjs + build:esm; add verify:dist smoke check.
- tsconfig.esm.json: emit esnext modules + declarations to dist/esm.
- scripts/esm-shim.js: post-process dist/esm — rewrite extensionless relative
specifiers to .js / /index.js, prepend a createRequire(import.meta.url)
banner to files using CJS globals, write dist/esm/package.json {type:module}.
Source files and the CJS build are untouched (backward-compatible require()).
- scripts/verify-dist.mjs: assert both entries load Agent (require + import).
- tests/unit/packaging/dual-build.test.ts: behavioural tests — assert emitted
ESM preserves import() (not require()), specifiers are extensioned, and the
ESM entry loads in a native Node child process and constructs an Agent.
Deferred (matches the issue; avoids green-lying): sideEffects:false,
mobile/node subpath allowlists, and a browser-platform CI gate all require the
separately-filed root-barrel split first.
Co-authored-by: Mervin Praison <[email protected]>
The openai SDK throws in any browser-like runtime (webview, Electron
renderer, React Native, browser) unless dangerouslyAllowBrowser is
passed. praisonai-ts passed it at 0 of 7 construction sites.
Add a shared buildOpenAIClientOptions helper that auto-detects
browser-like runtimes (leaving Node behaviour unchanged) and supports
an injectable fetch so hosts can route egress through native code,
keeping the API key out of the JS heap. Wire all 7 sites through it.
Extend ProviderConfig with fetch/dangerouslyAllowBrowser and add
per-agent apiKey/baseURL to SimpleAgentConfig to mirror Python's
per-agent api_key/base_url. Includes a behavioral test that constructs
the real SDK.
Co-authored-by: Mervin Praison <[email protected]>
Adds an optional `approval?: boolean | ApprovalManager` to SimpleAgentConfig
and gates every tool call in Agent.processToolCalls before invocation. Denials
are fed back to the model as the tool result (course correction) instead of
aborting the run. Reuses the existing ai/tool-approval.ts machinery; binds the
decision to the tool_call id (correlation, never positional).
Co-authored-by: MervinPraison <[email protected]>
Non-OpenAI providers silently dropped tools/outputSchema and answered
without them. The AI SDK backend already supports generateText({ tools }),
streamText and generateObject; simple.ts just never passed them through.
Format tools once in a provider-agnostic shape and run the tool-call loop
through the backend, matching what litellm gives the Python SDK. Adds a
cross-provider regression test asserting tools survive on every provider.
Co-authored-by: MervinPraison <[email protected]>
The parity tracker decides a capability exists by matching an exported
symbol name, so an exported-but-unreachable symbol (e.g. ApprovalCallback)
was reported as "DONE" while unusable. Rather than build a heavy
reachability/conformance subsystem, make the reports honest about what
they measure:
- Add a "What this measures / does NOT" note to generated PARITY.md
(TypeScript and Rust): counts are exported names, include barrel
re-exports, and are not a behaviour or reachability check.
- Relabel the markdown status from "DONE"/"TODO" to "exported"/"missing"
so a symbol-presence check is not mistaken for "works".
- Document the same limitation in the TypeScript extractor docstring.
- Add a regression test asserting the disclaimer + relabel are present.
Co-authored-by: MervinPraison <[email protected]>
v4.7.2's DMG fails to open on every Mac with *"PraisonAI is damaged and can't
be opened"*. This is not the ordinary unsigned-app warning, and the
instructions shipped next to it could not have worked.
Nothing signs the bundle. The only signature present is the one rustc's linker
puts on the bare executable:
CodeDirectory flags=0x20002(adhoc,linker-signed)
Sealed Resources=none
Its CodeDirectory declares a resource seal, and an unsigned bundle has none, so
verification fails outright:
code has no resources but signature indicates they must be present
macOS reports an *invalid* signature as "damaged" and an *untrusted* one as
"unidentified developer". Only the second can be bypassed with right-click →
Open, which is what INSTALL.md told people to do.
`signingIdentity: "-"` makes Tauri codesign the bundle with an ad-hoc identity.
Verified against the shipped artifact: signing it turns
code has no resources but signature indicates they must be present
into
valid on disk
satisfies its Designated Requirement
An ad-hoc identity is still not a Developer ID and Gatekeeper still refuses the
app on a double-click -- but it refuses it as untrusted rather than broken,
which is a door with a handle on it.
The release build now runs `codesign --verify --deep --strict` on the .app
before the artifact is attached, so this cannot ship again silently. Tests pin
the identity and the gate, including that the gate runs before the upload
rather than after.
INSTALL.md now distinguishes the two messages instead of conflating them, and
says plainly that v4.7.2 is affected.
Two notes on the tests. One assertion matched the phrase "codesign --verify"
inside the comment that explains the gate, so deleting the command changed
nothing -- comments are stripped now. And a second check for unsealed resources
was dropped rather than pinned: `--verify` already fails on the exact bundle
that shipped, so it was only a second way of saying the same thing, which is
why removing it broke no test.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Make PraisonAIDB the single owner of the agent lifecycle store write hooks
and have PersistenceOrchestrator delegate its store dispatch to it, removing
the duplicated sync/async store plumbing.
- db/adapter.py: add PraisonAIDB._from_stores() to build an adapter over
already-constructed stores (no URL parsing); fix the stale docstring that
falsely claimed it bridged to the orchestrator.
- persistence/orchestrator.py: lazily build an internal PraisonAIDB and
delegate on_message/aon_message + aon_agent_end store dispatch to it, while
keeping the orchestrator-only surface (ConversationMessage return contract,
resume-aware on_agent_start, LRU session cache). Docstring updated.
Public exports, all backends, and the MemoryConfig(db=...) live path unchanged.
Co-authored-by: Mervin Praison <[email protected]>
The desktop engine's "stream protocol v2" comment listed 9 events but the
engine emits 11: approval_request (the human-in-the-loop gate) and
tool_drafting were live on the wire but absent from the spec. The start and
end payloads had also drifted.
- Rewrite the comment to list all 11 events with their real payloads.
- Add StreamProtocolVocabulary tests that parse the comment and every
emit()/_emit_now() call site and assert the sets match both ways, so the
vocabulary can no longer drift without failing CI.
Co-authored-by: Mervin Praison <[email protected]>
Extract the duplicated ChromaDB metadata sanitisation into a single
module-level helper `sanitize_chroma_metadata` in memory/adapters/factories.py.
Both `Memory._sanitize_metadata` and `ChromaMemoryAdapter._sanitize_metadata`
now delegate to it. Public method names/signatures unchanged, behaviour
byte-for-byte preserved. The distinct core.py JSON-based variant is untouched.
Co-authored-by: Mervin Praison <[email protected]>
Canonical TS path stays src/praisonai-ts/; mirror sync direction is
monorepo to praisonai-js, not the reverse.
Co-authored-by: Cursor <[email protected]>
Finding 3 offloads task/knowledge memory writes via asyncio.to_thread, so
parallel task callbacks can now hit the shared in-memory adapter on different
worker threads concurrently. The non-atomic _next_id increment + append +
eviction sequence could produce duplicate memory IDs or lost entries. Guard all
adapter mutations/reads with a re-entrant lock (negligible cost single-threaded).
Addresses Greptile P1 review on PR #4403.
Co-authored-by: Mervin Praison <[email protected]>
Remove praisonai-js from merge-gate FINAL prompt, Claude STEP 3-ALT, and
tsMirrorPathReasons block. Hub issues and fixes stay in the same repo.
Co-authored-by: Cursor <[email protected]>
The engine (windows-latest) CI job failed in test_training.py -- a file
outside this PR's stream-protocol scope -- because _alive() and one inline
assertion used os.kill(pid, 0). That POSIX liveness idiom is broken on
Windows: signal 0 maps to TerminateProcess (it kills rather than queries),
and a dead pid raises OSError(WinError 87) instead of ProcessLookupError.
Route the Windows check through OpenProcess + GetExitCodeProcess, which
only observes, and replace the os.kill-raises assertion with the same
portable _alive helper. POSIX behaviour is unchanged; no production code
touched.
Co-authored-by: Mervin Praison <[email protected]>
Reject --image up front on execution paths that cannot carry a per-invocation
attachment (--agent, --profile/--profile-deep, YAML file, --output actions)
instead of silently discarding it, and reject single --image values containing
a comma (which ImageHandler treats as the multi-image separator) so a valid
path/URL is never fragmented. Adds 5 CLI guard tests.
Co-authored-by: Mervin Praison <[email protected]>
- edit_file: honour replace_all (default False = first occurrence only) so
the previewed diff matches what edit_file actually applies
- acp_edit_file: use its real whole-file contract (filepath + new_content)
instead of requiring old_string/new_string, which never matched and fell
back to the truncated argument summary
- add regression tests for first-only vs replace_all and ACP whole-file diff
Co-authored-by: Mervin Praison <[email protected]>
Address two P1 reviewer findings on PR #4400:
- agent_invoke._swap_llm: also clear _panel_descriptor (not just
_llm_explicit) so Agent._apply_default_llm no longer early-returns for
panel-configured agents. Previously an accepted agent_config.llm override
silently kept running on the panel model. Mirrored in the manual fallback.
- call._validate_public_base: replace prefix-only check with urlparse-based
validation. Reject malformed values with no host and cleartext ws:// to
non-local hosts (which would expose live audio + the one-shot session token
over an unencrypted transport). Localhost ws:// still permitted for dev.
Co-authored-by: Mervin Praison <[email protected]>
_config_write_target() used _find_config_file() which only sees cwd +
global, so with a nearer ancestor config the CLI wrote a lower-precedence
global file that the ancestor overrode on reload. Use the highest-precedence
discovered file instead, and seed set_plugin_enabled() from the target file
only (not the merged view) to avoid persisting inherited global keys.
Co-authored-by: Mervin Praison <[email protected]>
Strengthen the stream-protocol drift guard to also read the event names
returned by _classify_stream_item, the source of the variable forwarded
through emit(event, frame). A new classifier return value now fails the
guard instead of drifting onto the wire unseen (Greptile finding).
Skip test_a_delete_the_fallback_could_not_perform_is_not_reported_as_success
on Windows: its precondition (an unwritable store via chmod(0o500)) is
unreachable there because Windows ignores POSIX mode bits for directory
writability, matching the existing os.name == "nt" skips in this file.
Co-authored-by: Mervin Praison <[email protected]>
- Finding 1: key skill auto-approval by a unique per-instance
_approval_scope_id instead of the display name (which defaults to
"Agent" for every unnamed agent), preventing one agent's skill grant
from leaking to unrelated agents in the same process.
- Finding 2: add a substring fallback in _detect_provider so routed
models (bedrock/anthropic.*, vertex_ai/claude-*, openrouter/anthropic/*,
vertex_ai/gemini-*) get the correct adapter and its streaming guard
instead of falling through to the OpenAI adapter and crashing async
streaming.
- Finding 3: offload the synchronous, network-bound knowledge.search and
store_in_memory calls via asyncio.to_thread so they no longer block the
shared event loop for concurrently running agents/tasks.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Mervin Praison <[email protected]>
Attach a unified diff to the ApprovalRequest context for edit_file,
write_file and apply_patch so the console approval prompt renders the
actual +/- change instead of a truncated argument dump. Non-edit tools
keep the existing argument summary. The diff also travels on the request
context so non-console backends can render or attach it.
Co-authored-by: Mervin Praison <[email protected]>
- call.py §3: build Twilio media-stream URL from PRAISONAI_CALL_PUBLIC_BASE
instead of the client-controlled request.url.hostname (Host header), closing
the SSRF/call-audio-exfiltration path when CALL_SERVER_TOKEN leaks.
- call.py §2: move module-global `tools` + `_pending_stream_sessions` into a
per-app, thread-locked CallAppState on app.state so co-hosted/multi-tenant
build_call_app() instances never share tool schemas or cross-consume tokens.
- agent_invoke.py §1: route agent_config {"llm": ...} overrides through the
SDK's Agent._apply_default_llm invalidator (with a manual-fallback) so the
cached _llm_instance/_unified_dispatcher/_llm_init_params are dropped and the
request actually runs on the requested model.
Co-authored-by: Mervin Praison <[email protected]>
Add a repeatable --image option to `praisonai run` and plumb it to the
existing vision path instead of the hardcoded args.image = None. The core
Agent and the wrapper's handle_direct_prompt/ImageHandler already support
image input (local paths, http(s):// URLs, MIME detection, base64, multi-
image and clear validation errors); this closes the missing CLI surface.
Image runs bypass the warm-runtime fast path and the bare-Agent "actions"
path (neither can carry an attachment) so the vision-capable path handles
them. Text-only runs are unchanged.
Co-authored-by: Mervin Praison <[email protected]>
The praisonai-ts tool-call loop had a hardcoded 5-iteration cap and, on
exhaustion, logged a warning and returned finalResponse — which is ''
when tool calls were still pending. That empty string is
indistinguishable from the model saying nothing.
- Add optional maxIterations config field (default 5).
- Throw on genuine exhaustion (loop still needed another round-trip)
so callers can observe it instead of receiving ''.
Unifying streaming with the tool loop (interleaving text deltas and
tool calls on one stream) depends on the streaming Agent API in #4385
and is intentionally deferred to that work.
Co-authored-by: MervinPraison <[email protected]>
Config resolution previously returned the first config file found, so any
project-local .praisonai/config.* silently shadowed the user-global config,
discarding every global default. Introduce _discover_config_files() (global
first, ancestor project dirs, nearest project last) and a recursive
_deep_merge() (dicts recurse, lists/scalars replace); _load_config() folds
them lowest->highest so a project config selectively overrides globals while
unset keys fall through. A single-file fast path preserves prior behaviour.
Co-authored-by: Mervin Praison <[email protected]>
Make PraisonAIDB the single owner of the agent-lifecycle store-write
hooks and have PersistenceOrchestrator delegate its message-write and
session-end store dispatch to an internal adapter built via the new
PraisonAIDB._from_stores(), removing the duplicated sync/async store
plumbing while preserving the orchestrator's own return contract and
LRU session cache. Fix the drifted cross-referencing docstrings in both
modules. Public exports (PersistenceOrchestrator, wrap_agent_with_
persistence, PersistentAgent, create_persistent_session) and the
MemoryConfig(db=...) live path are unchanged.
Co-authored-by: MervinPraison <[email protected]>
Extract the byte-identical ChromaDB metadata sanitisation logic into a
shared module-level helper `sanitize_chroma_metadata` in
memory/adapters/factories.py. Both Memory._sanitize_metadata and
ChromaMemoryAdapter._sanitize_metadata now delegate to it, preserving
their public method names and behaviour. The distinct core.py JSON-based
variant is left untouched.
Co-authored-by: MervinPraison <[email protected]>
The engine emitted eleven stream events but the comment block listed nine,
omitting approval_request (the human-in-the-loop tool gate) and tool_drafting.
Documented payloads had also drifted from what start/end actually carry.
- Update the comment to list all eleven events with their real payloads.
- Add StreamProtocolVocabulary tests that parse the comment and every emit()
call site, failing on drift in either direction -- so the spec is now a
checked artifact rather than a comment nothing verifies.
Co-authored-by: MervinPraison <[email protected]>
Accept TS/JS issues on PraisonAI, route fixes to praisonai-js via Claude
STEP 3-ALT, block direct src/praisonai-ts/ PRs unless sync from praisonai-js,
and document routing in CONTRIBUTING, bug template, and SECURITY.
Co-authored-by: Cursor <[email protected]>
The version the desktop release is cut from. v4.7.1 predates the whole
Windows and Linux effort, so attaching those builds to it would have claimed
that release shipped something it did not contain.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
A review of the fixes themselves, which is where new bugs get introduced.
**A stale tab really could cancel someone else's run.** The engine refuses to
stop a run other than the one asked for -- and the Stop button never sent the
id, so the guard could not fire and the three server tests covering it were
testing a request the product does not make. Reproduced end to end: tab A's
Stop cancelled the run tab B had started. The button names its run now.
**The CSP test caught none of seven CSP-breaking changes, including a straight
revert of the fix it exists to protect.** It matched a *variable* name against
an element id -- `stopBtn` against `id="stopBtn"`, which does not exist; the id
is `stop` -- so it silently compared nothing. It now resolves bindings to
elements before judging a line, and covers the four other ways the policy can
be broken: a style attribute in any casing or quoting, `setAttribute('style')`,
a `<style>` built at runtime, and `style=` concatenated into innerHTML. Ten
mutations, ten caught, including both directions of the original bug.
The rule it enforces is also broader than before. Hiding with an inline style
and revealing with a class leaves the element hidden from the second turn on,
just as the reverse leaves it hidden forever -- so for an element the markup
hides with a class, any `.style.display` assignment is a defect regardless of
the value.
**A whole test file ran nowhere.** `stream-pacing.test.ts` is TypeScript and
matched neither npm glob, so its eight tests -- including the positive control
for logic `ui/index.html` justifies by saying it was "ported verbatim from the
tested one" -- never executed. The skip-count assertion could not see it
either: nothing skips when nothing runs. That is the same failure the workflow
comment claims to prevent.
**Windows CI could not go green** on a clippy error in a `#[cfg(windows)]`
block, invisible from any other platform, and three tests errored in setUp on
`os.getpgid` -- which does not exist on Windows -- in the class that exists to
prove the Windows path works.
Secrets, three ways a report of success was untrue:
* A delete returned `or` of the two stores, so an unwritable fallback meant the
plaintext survived, `get` served it, and the user was told the key was gone.
* A key the primary could not accept went to the fallback while the primary
kept the old one -- and `get` reads the primary first, so the app went on
using the previous key after a successful save.
* `FileSecretStore._read` swallowed every error, so one unreadable read meant
"empty" and the next write destroyed the other secrets. The DPAPI store's
docstring names this exact hazard; this one had been left with it.
And: `macos-14` began deprecation on 2026-07-06 with brownouts that fail jobs
now, and it was the only Apple-silicon leg, so the arm64 DMG was on its way to
disappearing -- there is a test listing retired images now, because this is the
second runner to expire mid-branch. `x11_threads` declared dlsym's argument as
`*const i8`, which does not compile on ARM Linux where `c_char` is unsigned.
The two Tauri window configs must agree, and nothing checked. The log-tail
comment described dropping a seek-truncated first line that nothing dropped.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The CI matrix found this on its third run, and it is the same defect this
branch already fixed once on POSIX -- still fully present on Windows, reported
as a success. Every stop-related test failed there, and one of them says it
plainly:
'RAN-TO-COMPLETION' unexpectedly found in the log
: the run was reported cancelled but ran to the end anyway
_terminate_group sent CTRL_BREAK_EVENT. That event is delivered through a
console, and the trainer is spawned with CREATE_NO_WINDOW precisely so that it
has none -- so send_signal returned successfully, nothing died, and the
`except OSError: proc.terminate()` fallback never ran because there was no
error. The user pressed Stop, the UI said cancelled, and the fine-tune carried
on to completion holding the GPU.
It kills the process tree with `taskkill /T /F` now, which is what killpg
achieves on POSIX. /T is the part that matters: without it the trainer dies and
whatever it spawned keeps the card.
The test that was supposed to cover this asserted `proc.signals or
proc.terminated` -- "something was signalled". CTRL_BREAK_EVENT satisfied that
perfectly while the process ran on. This is the third time in this branch that
a test asserted an attempt rather than an effect, so it now asserts which pid
was killed, that the command carries /T and /F, that a failed taskkill still
escalates, and that a process which already exited is not killed again.
The tree kill is a module-level function so all of this runs from any platform.
The branch that only executes on the machine nobody tests on is exactly the
branch that was wrong.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
My own regression from two commits ago, found by looking rather than by a test.
Capping the run history meant making it a bounded deque, and the insertion was
left as `insert(0, run)`. On a *full* bounded deque that raises
IndexError("deque already at its maximum size") -- so the run after the cap
would not start, and every run after that would fail the same way, on an app
that is meant to stay open for days. `appendleft` evicts from the far end,
which is the oldest run, which is what the cap is for.
The tests now reach the cap rather than stopping short of it. Both things that
go wrong here only go wrong when the deque is full: the insertion raising, and
eviction taking the newest run instead of the oldest. Neither is observable
below the limit, which is why a test that stops at three runs proves nothing.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Second round from the same matrix. Linux went green; Windows did not.
**The whole training route suite failed on Windows for a quoting reason.**
The test helper built `PRAISONAI_TRAIN_CMD` with `shlex.quote`, which escapes
an inner `'` as the concatenation `'"'"'`. POSIX reassembles that into one
token; Windows rules split it into seven. Every script in the suite prints
something, so every one of them contains a quote, and the trainer was launched
with a shattered command line -- the run never reached "running" and nine tests
timed out waiting for it. The body goes through a file now: a path has no
newlines and no quotes, so both rule sets agree about it. (`split_command`
itself is right; a Windows user would quote the Windows way.)
**The lockfile was not the bytes it says it writes.** `write_text` translates
"\n" to "\r\n" on Windows, so the file differed by platform. The Rust parser
trims each line and coped, but a lockfile whose bytes depend on the host is a
difference waiting to matter -- and the encode is the only conversion that
should be happening in a function documented as "always as UTF-8". It writes
bytes now.
The rest were test-only, and all the same mistake: `str(Path("/a/b"))` is
`\a\b` on Windows, and comparing a `PurePosixPath` to a `WindowsPath` fails
even when both name the same location. They compare `.as_posix()` now.
Also made the generated script filename a content hash rather than `hash()`,
which is salted per process and could have had two bodies collide on one file.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The CI added in the previous commit did its job on its first run: the engine
suite failed on Linux and Windows, and the Rust suite failed on Windows, while
all three passed on macOS -- the only platform any of this had ever run on.
Every failure is in the tests, not the product, and every one is the same
mistake in a different costume: asserting something about the *host* rather
than about the behaviour under test.
* Two Rust tests compared a whole PATH string against a hardcoded expectation
containing forward slashes. `PathBuf::join` writes a backslash when the tests
themselves run on Windows, so `C:/data/venv\Scripts` did not match
`C:/data/venv/Scripts`. The subject is the separator *between* entries, so
they now split on it and check the parts -- which is what the comment above
them always claimed they were doing.
* Four Python tests compared `str(Path(...))` against a POSIX string, which is
backslash-separated on Windows. They compare paths to paths now.
* The C-locale harness passed its statement through `python -c`. Python decodes
that argument with the filesystem encoding -- ASCII with surrogateescape
under LC_ALL=C on Linux -- so a test whose whole point was a non-ASCII path
died on unpaired surrogates before reaching the code under test. It goes
through a file now: source files are read as UTF-8 regardless of locale.
* The same harness captured the child's output with a bare `text=True`, which
decodes using the *parent's* encoding. On a Windows runner a test about UTF-8
handling was reading its own result back through cp1252 and failing on the
round trip rather than on anything the engine did.
* One test asked FileSecretStore to write to "/nonexistent/nope" and expected
failure. A Windows runner can create that at the drive root, so the store
succeeded and the assertion was backwards. It now puts a file where a
directory is needed, which fails everywhere.
None of this was reachable from a Mac, which is the entire argument for the
matrix.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
An adversarial review pointed out that nothing in .github referenced
praisonai-desktop. Every suite in it -- engine, shell and UI -- existed and was
never executed by anything except a person running it by hand.
The UI suite could not even be installed. jsdom was undeclared, so it ran only
on machines that happened to have one somewhere further up the tree, at
whatever version that happened to be. Pinning it surfaced the consequence
immediately: 16 tests fail on jsdom 25 and pass on 30. They had been passing
against a version nobody chose.
The workflow runs the engine tests on all three platforms, which is the point
of the portability suite; the Rust tests and clippy on all three; and the UI
tests on Linux. Clippy is included because it was already failing -- a
redundant closure in supervisor.rs -- which is exactly the sort of thing a gate
catches and a person does not.
The lifecycle suite is excluded by name rather than left to skip. It drives
real conversations against a live engine and a real model, neither of which
exists on a runner, so it would have skipped all thirteen of its tests and
exited 0. The remaining 128 run with the skip count asserted to be zero,
because a suite that skips everything looks exactly like a suite that passed.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Three of these are in the "user cancels" and "user watches a long run" paths,
which are the two things this feature exists to do.
**Opening the Training tab on a run older than ~20 minutes showed nothing, and
pinned a core doing it.** The SSE handler answered a gap by resyncing at
cursor=-1 -- which makes the next since() compute a gap again, because every
ring that has ever evicted satisfies `0 < oldest`. The `continue` then skipped
both the sleep and the terminal check, so it spun at ~13,000 resync frames per
second, delivered zero log events, and went on spinning after the run had
finished. A tqdm refresh emits two events, so a real fine-tune passes the 4000
-event ring in about twenty minutes. It now resumes at the oldest event still
held and falls through to deliver it.
**Pressing Stop before the trainer process existed cancelled nothing.** start()
returns as soon as the supervisor thread is created, so between the HTTP reply
and Popen returning, run._proc is None and stop() had nothing to signal. It
recorded STOPPING and _supervise then overwrote it with RUNNING: the user got
{"ok": true} and a "stopping" pill, and the fine-tune ran to completion and
reported "done" -- holding the GPU it was told to release. The state is now
settled under the run's lock, and a stop that arrived first terminates the
process on arrival.
**One trailing slash let a stale tab kill the live run.** The route was matched
by string, and rsplit("/") on "/train/stop/<stale-id>/" yields "", which is
falsy -- so the guard that exists to stop exactly this was skipped. The same
matching treated "/train/stopXXXX" as the stop route and read "?force=1" as
part of the run id, refusing a legitimate stop. The path is parsed now.
Also:
* Two runs could share a directory, overwriting each other's config.yaml and
interleaving into one train.log. Ids differing only in case are one directory
on macOS and Windows; and the generated id had one-second resolution, so two
runs started in the same second collided -- which the new check caught
immediately. Ids are settled before anything is created, so a refused run no
longer clobbers the config of the run it collided with.
* A method that could never work failed after the model download rather than
before it. GRPO needs reward functions this form cannot supply, so it is now
refused in milliseconds with a message saying to use the CLI. Column
requirements depend on the dataset and are still the trainer's to check, so
every method hint now names the columns it needs instead of leaving the user
to discover them an hour in.
* _last_meaningful_line read the whole log to keep forty lines from the end --
at the exact moment a run fails, and a tqdm bar writes a line per refresh. It
reads the last 64KB now.
* An unwritable runs directory raised PermissionError past the handler, so the
connection dropped with no response and the UI reported "could not reach the
engine", sending the user after the wrong problem.
* A malformed ?cursor= was an unhandled ValueError that dropped the connection.
* run.metrics and Trainer.history grew without limit in a process meant to stay
open for days.
Converting those two to bounded deques broke /train/runs and /train/status,
because a deque cannot be sliced -- caught by the existing route tests, which
is what they are for.
Tests: 49 + 23 + 6 Python, 134 UI. New coverage for replaying a run that has
outlived its buffer, every stop-route shape, the pending-stop window, run-id
collisions, and the method preflight. All five fixes were mutation-tested.
Two notes on the tests themselves. The pending-stop case cannot be reached
through HTTP -- two round trips are slower than a spawn -- so it is tested
where it is deterministic, by delaying the spawn. And its first version asserted
only that the final state was "cancelled", which a version that never signals
the process also satisfies while the job runs to the end; it now asserts the
process died and the script's completion marker never reached the log.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Found while fixing the same class of defect on the cross-platform branch.
Configuring a CSP makes Tauri stamp a nonce on the page's <style> tag, and a
nonce in a source list voids 'unsafe-inline' for that directive -- so every
style="" attribute in the document stops applying. The heading above the run
history would have lost its spacing the moment the two branches met, silently.
A class instead. The other inline styles on this branch are pre-existing and
are handled in the cross-platform work, along with the test that would have
caught this one.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Three ship-blockers, one security bug, one claim of mine that was simply wrong.
**The CSP I added broke the app, and I said it would not.** Configuring any CSP
makes Tauri stamp a nonce on the page's <style> tag and a hash on its inline
<script> at build time -- and a nonce or hash in a source list *voids*
'unsafe-inline' for that directive. So the moment a CSP existed, every
style="" attribute in the document stopped applying: a permanently visible red
Stop button, a raw file-input widget, and every tool-output block expanded, on
first launch. Nothing errors; it just looks broken. Those five attributes are
now classes. Setting .style from JavaScript is CSSOM and was never affected --
but `el.style.display=''` to reveal an element now restores the class default,
which is `display:none`, so those three call sites toggle the class instead.
**The Linux tray took the whole app down.** `tray::build(...)?` in setup, and
on Linux the tray goes through libappindicator, which is dlopen'd at first use
and *panics* if neither library is present -- not catchable, since we build
with panic=abort. Because it is dlopen'd there is no DT_NEEDED entry, so
dpkg-shlibdeps could not generate the dependency either: the package installed
cleanly and then did nothing when clicked. The tray is now non-fatal and the
library is declared explicitly, along with curl, which the uv bootstrap runs
and minimal images omit.
**The macOS overlay silently deleted the window geometry.** Tauri merges
tauri.macos.conf.json with RFC 7386, whose rule for arrays is replacement, not
element-wise merge. An overlay carrying only the two macOS keys replaced the
whole `windows` array: title, width, height and both minimums vanished, so the
app became an 800x600 "Tauri App" that could be dragged down to nothing. The
overlay now repeats the full object.
**Deleting an API key reported success while the key kept working.** Once a
secret had been written to both stores -- keyring unavailable, then available
again -- a delete that short-circuited on the first success left the other copy
behind, and the read path served it. The plaintext stayed on disk. A delete now
reaches every store, and a successful write clears the fallback so a superseded
key is not left readable.
Everything else, briefly:
* macos-13 was retired on 2025-12-04, so the Intel leg would never have
scheduled -- and the completeness check would then have failed every release,
forever, correctly. Now macos-15-intel.
* `cargo install tauri-cli ... || true` swallowed a real failure and the next
step died complaining about an unrelated missing command. It also behaved
differently per leg, since Windows defaults to pwsh where `true` is not a
command.
* Two spawn sites had no console suppression -- including the engine itself, so
a black console window sat beside the app for the entire session on Windows.
There is now a lint over every spawn site, which is honest about being a lint:
a Windows creation flag has no observable effect here, but "did anyone forget
to call it" is exactly what regressed.
* One undecodable byte silently ended the engine's log reader for the rest of
the session. `lines().map_while(Result::ok)` *stops* on the first
Err(InvalidData) rather than skipping it, and Python encodes redirected
streams with the locale code page on Windows. If it arrived before the port
announcement, startup failed 30 seconds later blaming a timeout.
* The engine spawn had no process group on Unix, so SIGTERM reached the engine
and nothing it had started -- with the training tab, a fine-tune would have
kept a GPU after quit.
* `XInitThreads` is now called first in main(). GTK never calls it, several
threads drive X anyway, and the failure is `_exit(1)` with no message.
* Empty environment variables were treated as set on the Rust side only, so
`XDG_DATA_HOME=""` made the shell look for the lockfile in the working
directory while the engine wrote it under the home directory -- "no lock,
spawn" on every launch.
* The uv installer's exit code was taken as proof it installed something;
`powershell -Command "irm ... | iex"` can exit 0 having done nothing.
* Three write-then-rename sites -- transcripts, MCP config, settings -- did not
use the retry helper whose own docstring names their failure case.
* A leftover temp file kept its old permissions, so a secret could be written
world-readable before the chmod that follows the rename. O_EXCL now.
* A DPAPI blob that would not decrypt read as empty and was then overwritten,
destroying every other secret in it.
* The tray used macOS template rendering and Cmd accelerators everywhere:
a black-on-black icon, and a menu advertising Win+Q, which Windows takes.
* "Copy data folder path" reproduced the default instead of asking the engine,
so it handed the user a path the app was not using whenever it was
overridden. /health now reports it.
Tests: 35 engine, 123 Rust, 141 UI. New: a CSP guard (there was none -- no test
in the suite sets a CSP header, which is why this shipped), a lossy-reader
suite, spawn-site hygiene with a positive control, and secret-deletion tests
that failed before the fix.
Two of my own new tests were wrong in the usual way. One asserted a repair
button *existed* without clicking it, so replacing its handler with an empty
function changed nothing. The other's comment-stripper only checked line
prefixes, so a continuation line inside a block comment -- this file's own
explanation of the bug -- was reported as an instance of it.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The macOS release workflow shipped first. Adding the other two was not a matter
of adding runners: the bundle targets were macOS-only, so a Windows or Linux
build produced zero artifacts and still exited zero. That is fixed in the
config change; this wires the pipeline to it.
Four legs now: macOS on both architectures, Windows NSIS, Linux .deb. NSIS
rather than MSI because MSI can only be built on Windows, needs an optional
Windows feature, and installs to Program Files behind a UAC prompt; NSIS
installs per-user with no administrator password. .deb only -- no RPM, no
AppImage. AppImage needs libfuse2, which Ubuntu 24.04 removed, and renders a
blank window on some Wayland and Mesa combinations; a .deb that works beats an
AppImage that half does.
Two decisions that look arbitrary and are not:
* The Linux leg pins ubuntu-22.04. glibc is forward-compatible only, so the
build host sets the *oldest* distribution the package can start on. Building
on 24.04 would emit a .deb that refuses to launch on 22.04 or Debian 12 with
a GLIBC_2.38 error no runtime flag can fix. That image begins deprecation on
2026-09-17 and retires 2027-04-17; the comment says to move to a debian:12
container rather than bump the runner, so the floor stays our decision.
* libappindicator3-dev, not the ayatana package the Tauri docs suggest. The
.deb's generated Depends: follows whichever the binary linked against, so
mixing them between builds produces packages that disagree about their own
dependencies.
A `verify` job now fails the release if any platform is missing an asset. A
release that quietly ships three platforms instead of four is worse than one
that fails, because nobody notices -- which is how v4.7.1 went out with zero
assets in the first place.
The install doc covers all four downloads, and says plainly what each platform
does about an unsigned build: Gatekeeper's misleading "damaged" message and the
right-click-Open, SmartScreen's hidden Run anyway, and `apt install ./file.deb`
rather than dpkg so dependencies resolve.
Guarded by tests, because these three files must agree and none of them fails
loudly when they do not: the workflow matrix, the config's bundle targets, and
the filenames the install doc tells people to download. 9 tests, 11/11
mutations caught -- including dropping a platform, swapping the appindicator
package, bumping the Linux runner, and removing the Windows icon.
One of those tests was weak on the first attempt: it grepped the whole file for
`exit 1`, which appears in the verify job too, so it passed with the
artifact step's guard removed. It is now scoped to that step.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The bundle targets were `["app", "dmg"]`. Both are macOS-only bundle types, so
a Windows or Linux build produced *zero artifacts* and still exited zero --
the failure mode is a green build with nothing in it. Added nsis and deb.
`titleBarStyle: "Overlay"` and `hiddenTitle` are macOS-only keys, silently
ignored elsewhere, which left a native title bar sitting on top of the CSS one.
They now live in tauri.macos.conf.json, which Tauri merges per platform.
`csp: null` disabled the content security policy entirely. It is now explicit,
and allows exactly what this app needs: loopback to the engine, which is how
the webview talks to Python at all.
On the UI side the page now reads which platform it is on and adapts three
things that were macOS facts written as layout constants:
* 5.2rem of left padding for the traffic lights. Windows and Linux put their
window controls top-*right*, so this was dead space on the left and an
overlap with the toolbar on the right.
* `⌘N`, `⌘K`, `⌘,` labels. The keydown handler already accepted Ctrl, so the
shortcuts worked -- the hints just named a key those keyboards do not have.
They now come from one place, so a new shortcut cannot be added with a
hardcoded modifier that is wrong on two platforms out of three.
* "into your Library folder", and a Copy button that copied
`~/Library/Application Support/PraisonAI` on machines where no such path
exists. Windows gets %APPDATA%, which pastes straight into Explorer.
Detection is layered -- userAgentData, then navigator.platform, then the user
agent string -- because the last is the easiest to be wrong about: a webview
reporting only "(darwin)" matched none of the names and fell through to Linux
on a Mac. That was caught by a test, not by reasoning.
Two test defects fixed along the way, both of which had been passing while
proving nothing:
* `first-run.test.mjs` asserted the lede contains "Library". That passed only
because this suite has only ever run on macOS; on the Linux runner this
release needs, it would fail on correct behaviour -- and anyone fixing the
copy would have "broken CI" for doing the right thing. It now asserts the
copy names *a* place, whichever platform is reading it.
* The new platform tests originally passed jsdom's `userAgent` option, which
is silently ignored, so all three cases ran against jsdom's own agent and
were really testing one platform three times. The navigator properties are
now defined directly. A second version read `body.textContent` -- which
includes the inline script's source -- and "found" macOS copy on Windows
inside the source of the very branch that avoids it.
Also generated icons/icon.ico: without it tauri-build does not warn, it
refuses to compile for Windows at all.
Tests: 6 new platform tests, 7/7 mutations caught. Full suite 124 passing, and
verified still passing with the page forced to report Linux.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The crate always compiled for all three platforms -- there is exactly one
`#[cfg]` in it -- so nothing ever failed loudly. Every defect here is a runtime
one: the app starts and then cannot find its own engine.
Platform is now a value rather than a `cfg`. Every path and process decision
that differs goes through a function taking one, because `#[cfg(windows)]`
makes the Windows branches invisible to a suite that only ever runs on macOS,
and invisible branches are how the code nobody runs comes to be wrong.
What was broken:
* `HOME` was the only home lookup. It is normally unset on Windows -- that is
`USERPROFILE` -- so provisioning returned "no home directory" and the
orphan-reclaim path never ran at all.
* Every interpreter candidate ended in `bin/python3`. A Windows venv keeps its
interpreter in `Scripts\python.exe`, so all of them failed `is_file()` and
the app reported "no usable Python found" immediately after successfully
provisioning one.
* The uv bootstrap ran `/usr/bin/curl` piped into `/bin/sh`. Neither exists on
Windows, so first-run provisioning was simply dead; and pinning curl's
absolute path breaks Linux images where it lives elsewhere. There is now a
PowerShell installer for Windows, and curl is found by name.
* `/bin/kill` was spawned unconditionally to reap an orphan, and the call site
discards the result -- so on Windows, deciding to kill an orphan killed
nothing, which is the exact bug reclaim.rs exists to prevent.
* `/bin/ps -o lstart=` was the only start-time source, so every pid on Windows
read as "no such process", every live engine looked dead, and a second one
started beside it on every launch. Windows now reads the creation stamp from
kernel32.
* site-packages was derived as `lib/python3.X/site-packages`. Windows is
`Lib\site-packages` with no version segment -- and the caller's only check is
that the path sits under the venv root, so the wrong path passed the guard
while pointing at nothing, which is worse than failing.
* `spawn_env` joined PATH with `:` and used `bin`. Windows is `;` and
`Scripts`; one wrong separator makes the entire PATH a single unusable entry.
The shell and the engine must also agree on two things or they fail silently
and permanently: the data directory, and the hash that identifies a running
process. Both are now asserted from both sides -- reclaim.rs and
test_portability.py carry the identical fixture table, so if either hashing
implementation drifts, both suites fail rather than the two quietly disagreeing
and starting an engine per launch forever.
The PowerShell installer deliberately avoids `-WindowStyle Hidden` with
`-ExecutionPolicy Bypass`: that pair is a known malware detection signature and
gets installers flagged. The console is suppressed with a creation flag, which
is not a behavioural signal. `UV_NO_MODIFY_PATH` is set on every platform,
because an app should not rewrite the user's shell profiles to install its own
dependency.
Also generated the icon set. `icons/icon.ico` was missing, and tauri-build does
not warn about that -- it refuses to compile for Windows at all.
Verified rather than assumed: `cargo check --target x86_64-pc-windows-msvc
--all-targets` passes, so the FFI and the CommandExt code that macOS never
compiles is at least type-checked. Linux cannot be checked from here because
libdbus-sys needs system headers that only exist on Linux; CI covers it. 116
tests pass on the host.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Six independent macOS assumptions. Two of them kill the engine outright on
Windows; one makes settings unsavable on Windows *and* Linux.
The signal registration was the worst, because of where it failed rather than
how. `for sig in (SIGTERM, SIGINT, SIGHUP)` builds the tuple before the loop
body, so SIGHUP is dereferenced outside the try that was meant to tolerate a
missing signal -- and Windows has no SIGHUP. It raised AttributeError, which
that except clause would not have caught anyway. It happened *after* the port
was announced and the lockfile written, so the shell adopted an engine that
was already dead and every request looked like a network fault. Signals are
now looked up one name at a time.
Secrets went to the macOS keychain via the `security` binary, which does not
exist elsewhere: the write reported failure, POST /settings raised with no
handler, and load_settings reported the key as unset forever. The app was
permanently unauthenticated on both other platforms with no visible cause.
There is now a store per platform -- keychain, DPAPI, libsecret -- each backed
by a 0600 file, because a machine with no keyring daemon (headless, container,
locked login keyring) must still be able to save a key. A secret is never
written into settings.json, which is the file people paste into issues.
The data directory was `~/Library/Application Support` everywhere. On Windows
that is not merely unconventional: it is excluded from roaming profiles and
from most backup tooling, so a user's entire history silently fails to follow
them to a new machine. Now %APPDATA% and $XDG_DATA_HOME respectively.
Three quieter ones. The lockfile was written in the locale encoding while the
Rust side reads it as strict UTF-8 and maps invalid bytes to "absent" -- and
absent means spawn, so a non-ASCII home directory would have produced a second
engine beside the live one on every launch. `read_file` decoded user files in
the locale encoding with errors replaced, handing the model plausible mojibake
it would reason over confidently. And SO_REUSEADDR, correct on POSIX, means
"another process may bind this address while I am listening" on Windows --
on unauthenticated loopback carrying API keys.
Also: the recycled-pid fingerprint shelled out to `ps` and returned 0 on
Windows, and 0 is the "could not tell" value, so every recycled pid compared
equal and an unrelated process would be adopted as the engine.
GetProcessTimes gives a real creation stamp.
One incident worth recording. Verifying this live wrote a test key into my own
macOS keychain, because PRAISONAI_DESKTOP_HOME isolates the data directory but
not the system keyring, which is shared per user. KEYCHAIN_SERVICE is now
overridable so a test cannot reach the real one. Asking for isolation should
isolate everything.
Tests: 27, all mutation-checked -- 13/13 mutations of these guarantees are
caught. Four of those tests were rewritten after the first versions survived
their mutations: the XDG test compared a path to itself (its "custom" value
was the default), the two encoding tests could not fail on a UTF-8 Mac and now
run under LC_ALL=C in a child process, and the permission test asserted the
final mode, which passes even when the file is created 0644 and chmodded
afterwards -- leaving a window where any local process can read the key.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The desktop app could talk to a model but not make one, while praisonai-train
sat behind it doing exactly that. This wires the two together.
A training run is a subsystem rather than a route. The engine is a
ThreadingHTTPServer where every request is a turn that starts, streams and
ends -- right for chat, wrong for something that runs for hours, must survive
the window closing, and has to resume after a reconnect.
Three decisions, each taken because the alternative was worse:
* One run at a time. Two fine-tunes on one GPU do not co-exist; they OOM.
Starting a second returns 409 naming the run that is already going, rather
than queueing, which would imply a scheduler nobody asked for.
* Progress is a replayable ring buffer, not a stream. Reconnecting reads from
a cursor, so a closed lid loses nothing; if history was evicted the client
is told to resync rather than handed a log with a hole in it.
* The subprocess owns the truth. Status comes from the process and its log,
never from what the client last heard, so a client that missed the ending
still learns how it ended.
Three defects the tests found while being written, all of which would have
shipped:
* The event cursor was derived from len(events). Once eviction begins the
length stops growing, every later event is handed the same cursor, and
since() returns nothing forever -- a live run whose UI silently stops
updating. It is now a standalone counter.
* run_id came from the client and became a directory name. The engine listens
on loopback with no auth by design, so any local process could have posted
`../../../Library/LaunchAgents/x`. Now allowlisted.
* Stopping a run signalled the process group without checking whose group it
was. The mutation that removes start_new_session proves the hazard is real:
it makes the test runner kill itself. The engine now refuses to signal its
own group.
Portable from the start, since Windows and Linux builds are next: the pipe is
decoded as UTF-8 rather than the locale encoding (cp1252 turns unsloth's
banner into mojibake, and five of its bytes raise inside the reader loop,
freezing the log while the run continues); PRAISONAI_TRAIN_CMD is split with
Windows rules on Windows, where POSIX splitting eats every backslash in an
interpreter path; the child gets CREATE_NEW_PROCESS_GROUP there, because
CPython accepts start_new_session on Windows and then ignores it; and run ids
reject reserved device names, which an alphanumeric allowlist cannot see.
Tests: 42 engine unit tests, 10 end-to-end tests against a real spawned
engine, 16 UI tests driving the real page in a DOM. All 9 mutations of the
engine's guarantees are caught, and all 7 of the UI's. The existing desktop
suite stays green at 134.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Releases carried no assets at all. v4.7.1 shipped zero, so a Mac user had
nothing to download and no path to the app that exists in this repo.
On a published release (or by hand against an existing tag) this builds a .dmg
on macos-14 and macos-13 and uploads both:
PraisonAI-<version>-macos-apple-silicon.dmg
PraisonAI-<version>-macos-intel.dmg
Two per release rather than one universal binary, because Tauri does not
produce a universal build and a wrong-arch download fails at LAUNCH rather than
at install -- which is a worse place to discover it.
The build fails loudly when no .dmg is produced instead of uploading nothing.
An empty asset list is exactly the state this workflow exists to fix, and a
silent no-op would recreate it while looking green.
Unsigned, deliberately: signing needs a Developer ID in repository secrets, and
shipping an unsigned build people can right-click-open beats shipping none.
INSTALL-macOS.md says so plainly rather than letting Gatekeeper say it -- its
message for an unsigned app is "PraisonAI is damaged and can't be opened",
which is both alarming and untrue. The guide covers which architecture to pick,
the right-click-Open path, the xattr fallback, what the first-run provisioning
does and where it puts things, and how to remove it.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Rebuilt on current main after #4367, #4368 and #4370 merged.
An adversarial audit ran 16 mutations against this suite. EIGHT survived all
408 tests, and every survivor was covered only by
src = inspect.getsource(some_function)
assert "the_thing_i_want" in src
which passes whether or not the code does anything: the string is still in the
file when the branch around it is disabled.
The worst case was a test holding a COPY of the logic it tested.
test_response_masking.py defined _auto_use_mask() mirroring train_model's
`auto` expression, so reverting the real line to the pre-fix `supports_mask`
alone left the whole suite green -- the single defect that PR existed to fix
was undetectable by its own test file. The expression is now
resolve_mask_setting() and the test calls it; that mutation now fails.
The guard caps source-text assertions, bans reimplementing tested logic, and
asserts the extracted helpers stay importable -- each of resolve_mask_setting,
decide_masking, resolve_response_markers, is_out_of_memory, rewards.require and
rewards.resolve_all exists because a source-text test failed to catch a bug,
and inlining one silently returns its test to proving nothing.
The cap is a ratchet, not a ban: ordering constraints are genuinely structural.
It tripped twice on rebases while this PR waited, which is the point. Both
times the new assertion turned out to be convertible and was converted rather
than waved through: _launch_script RETURNS its command, and the PEFT forwarding
list is data, now the module constant PEFT_PASSTHROUGH.
Two things the guard got wrong first, both found by running the regression
rather than reading it: it matched the COMMENT explaining the removed copy, so
it now tokenises and drops comments and strings; and joining tokens with spaces
turned `inspect.getsource` into `inspect . getsource`, so the count missed
every occurrence.
483 tests passing.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Each of these is a keyword unsloth already accepts and this package never
passed. Nothing failed when they were missing -- the run just did something
narrower than the user asked for.
QUANTS: 12 of unsloth's 24 were refused by this validator before unsloth was
ever asked -- q3_k_l, q4_k_s, q5_k_s, f32 and the aliases are all legal
upstream. The IQ family (11 imatrix quants) was unreachable entirely, which is
how a 30B model fits on a laptop. Now 35 accepted, read out of unsloth's own
save.py rather than hand-picked, with a test that fails when the two drift.
MODEL ACCESS: hf_token, trust_remote_code and revision were unreachable, so a
gated repo (Llama, Gemma) worked only through an environment variable, a
custom-code model not at all, and a multi-day run could not pin a revision --
the tag moves and the run is no longer reproducible.
PEFT SELECTORS: the target-module list was hardcoded to seven names.
finetune_last_n_layers (the cheap-run recipe), target_parameters (required to
LoRA MoE experts), layers_to_transform, layers_pattern and init_lora_weights
are all forwarded now.
OFFLINE MERGE: save_pretrained_merged was never called, so the only way to get
merged weights was to PUSH them -- needing a Hub account, a token and a
network. `merged_save_dir` writes them to a directory.
vLLM: fast_inference was never passed, so GRPO always ran the slow HF-generate
rollout path.
28 tests. Five mutations, all killed.
One of them could not be expressed at first, because the test helper
REIMPLEMENTED the assembly it was checking -- in the very change that bans
reimplementing tested logic. It is now model_access_kwargs() and the test calls
it; deleting the token forwarding fails.
480 tests passing.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
A `git stash --include-untracked` during merge-conflict repair swallowed the
whole untracked praisonai-desktop tree and it was never restored. It surfaced
only because a UI audit described settings as inert that had been fixed days
earlier -- true of the tree on disk, not of the work. Recovered from
stash@{0}^3.
What it contains, all previously reported and none of it on main:
- The eleven dead settings wired to real behaviour, each proven by a test swept
across at least two values.
- Text size scales the whole interface rather than only the chat, with every
fixed-pixel dimension converted to rem and a test that fails on any
dimensional px over 3px.
- The transcript and the composer share one column. They were ~240px apart
because an auto margin on a flex item's cross axis overrides `stretch`.
- In-app confirmation dialogs. window.confirm returns false immediately in a
WKWebView without showing anything, so every guard written as
`if (!confirm(...)) return;` cancelled -- which had silently broken deleting
a conversation outright.
- data-tauri-drag-region plus core:window:allow-start-dragging, without which
the titlebar could not move the window: -webkit-app-region is a Chromium
feature WKWebView does not implement.
- Accessibility: landmarks, a live region for streamed answers, accessible
names on icon-only controls, a focus-trapping dialog, aria-current on rows.
- Real app and menubar icons from the PraisonAI mark. A macOS template image is
drawn from its alpha channel alone, so the previous one rendered as a solid
block.
- First-run provisioning with staged progress, message versions with a
`< 1/2 >` picker, and orphan reclamation through the lockfile the Rust side
had always specified and nothing wrote.
118 JS tests across 11 suites, 90 Rust tests, all passing.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Three agents audited the eleven PRs that just merged. Every defect below passed
the suite that shipped it.
FIVE IN THE CODE
1. --dry-run showed one config and a different one trained. Forwarding
--dataset/--model -- which I added as "belt and braces" -- puts the legacy
dispatcher on its regeneration branch (praison_ai.py:676), where
generate_config() runs with every tuning parameter None and rewrites
config.yaml from defaults: lora_r 64 -> 16, epochs 5 -> 1, method dpo -> sft,
and huggingface_save false -> TRUE with hf_model_name defaulted to a third
party's repository.
2. cpt silently lost embedding_learning_rate, the one value it exists to set.
__dataclass_fields__ is inherited, so on a plain __init__ subclass it resolves
to the parent's fields and the drop-unknown filter deleted the value 45 lines
after setting it -- along with max_seq_length and packing.
3. remote start could never train: it passed config.yaml as the dataset
positional. Two positionals meant exit 2 before the GPU was touched.
4. Remote command injection and path traversal. --run-id 'x;touch /tmp/pwned'
executed, because the far half of an scp target is expanded by a shell there.
fetch ../../../../etc/passwd passed the existence gate and copied the file
back. Both quoted and validated now.
5. hf_private failed open: 'private', 'y', 'enabled', 5 all published the
repository.
FIVE AT THE BOUNDARY
6. llm overwrote ./config.yaml with no backup, and had already destroyed a
hand-written one in this repo's working tree.
7. praisonai train exposed 6 of 15 commands and no remote group, because the
integrated CLI imports cli/commands/train.py while the siblings register via
cli/app.py.
8. tests/unit/data/ -- 96 tests -- was collected by no workflow at all.
9. The suite needed 3.11 while pyproject declares >=3.10.
10. pip install "praisonai-train[llm]" produced an llm command that died at
argument parsing; nothing declared the praisonai wrapper it imports.
44 tests. Ten mutations, all killed -- four only after fixing the test first: a
fake class with **kwargs returned early, two called a validator the code path
no longer had to use, and one matched the comment explaining the fix rather
than the configuration. That last shape has now appeared three times.
452 tests passing.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Rebuilt again on current main, which moved when four sibling PRs merged.
The last of unsloth's training methods. It rewrites every trl.trainer.*_trainer
module generically (rl.py:4235-4248), so all three work through it. GRPO was
the blocker for the rest, because it needs reward functions and a YAML config
can only carry a string.
DECISION, stated because it is the one thing I could not derive: reward
functions are named by dotted import path, `module:function`.
method: grpo
reward_funcs:
- myproject.rewards:length_penalty
num_generations: 8
A registry populated by decorator would mean the config can only name functions
from a module something else already imported. Inline Python in YAML is a
code-execution surface in a file people paste from the internet. An import path
is the only one of the three resolvable before anything runs -- which is why
rewards resolve before the model loads, so a typo costs five seconds rather
than a multi-gigabyte load. If you would rather have a registry, the change is
contained to rewards.py.
A missing module and a missing attribute are told apart, since one is a
PYTHONPATH problem and the other a typo; the attribute error lists the
callables that are there. Every broken path is reported at once. GRPO takes
prompts only, since it generates its own completions.
394 tests passing.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Rebuilt again on current main, which moved when #4361/#4362/#4364/#4365 merged.
praisonai-train checkpoints
praisonai-train infer -d lora_model "Summarise this release."
checkpoints: after an interrupted run there was no way to find what was saved
without `ls`. Matches checkpoint-<n> exactly, so a directory called
checkpoint-final is not reported as step 0, and sorts numerically.
infer: TrainModel.inference() existed with no caller anywhere in the package.
serve --benchmark measures tokens per second without showing a token.
Streamed, with usable defaults rather than the dead inference()'s
temperature=1.5 / max_new_tokens=64.
Named infer, not generate: generate is already dataset generation, and a second
command of that name silently replaces one with the other.
Also one line: dataset_num_proc defaults to None rather than 1, so unsloth's
memory-aware sizing is not overridden into a single process.
386 tests passing.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Rebuilt on current main; the previous branch carried eight unrelated commits.
The `models` command now lives in its own module rather than alongside the
post-training commands, so this change does not depend on them.
model_name was free text with no validation anywhere. A typo was caught by
Hugging Face -- after the CLI accepted it, after the environment was built,
sometimes after a partial download. And nothing told a new user which models
work: config.yaml offers exactly one example, from the Llama-3.1 era.
praisonai-train models
praisonai-train models gemma
praisonai-train models --json
The catalog is read from unsloth's mapper at runtime, not vendored: it carries
246 distinct 4-bit repos and is updated every release, so a copy here would be
stale the day it shipped. CURATED is the fallback for when unsloth is absent --
the CLI is importable without the training extra -- and the starting point for
someone who has not chosen yet.
An unknown model warns rather than refusing, because unsloth loads plenty it
does not map. Suggestions match the repo name, not the full id, so an upstream
id surfaces the unsloth mirror. The catalog includes mapper values as well as
keys, since a 16-bit mirror appears only as a value and naming one would
otherwise be reported as unknown.
335 tests passing.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Rebuilt on current main; the previous branch carried nine unrelated commits.
Two ways to end up with an environment that looks fine and cannot train.
Version floors were pip metadata only. pyproject declares torch>=2.6.0 and the
rest, but nothing checked at runtime -- and pip is routinely bypassed:
--no-deps, a hand-built conda env, setup_conda_env.sh pinning its own torch.
The failure then arrived as whatever traceback the mismatched package happened
to raise, several imports deep. A test asserts the floors match pyproject
exactly: lower lets a broken environment through, higher refuses one pip would
have built.
The CUDA pin ignored the hardware. Every Linux host got pytorch-cuda=12.4
regardless. On AMD or Blackwell that builds a working-LOOKING environment that
fails at the first kernel; on a CPU host it installs a CUDA build that can
never run. There is a probe now -- nvidia-smi, then /proc/driver/nvidia/gpus
for a host with the driver but not the tool, then rocminfo -- and the pin lives
in one place instead of four copies across two branches.
A CPU-only Linux host is told plainly that training will refuse, since
trainer.py raises on a missing GPU. A prerelease of the required version counts
as satisfying the floor, because refusing 2.6.0rc1 blocks people testing
upstream and unsloth's own checks are release-level.
338 tests passing.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Rebuilt on current main; the previous branch carried four unrelated commits.
A raw-text corpus could not load. A dataset with only a `text` column fell
through to the Alpaca branch, formatted every row to "", and died with "All
examples formatted to empty text" — an error blaming the dataset for a shape
the formatter did not handle. Domain and language adaptation could not run.
And the embeddings got the wrong learning rate. modules_to_save was exposed, so
a user could make embed_tokens/lm_head trainable, but the trainer was plain
SFTTrainer, which has no embedding_learning_rate. They trained at the adapters'
rate — the recipe unsloth ships UnslothTrainer to avoid.
method: cpt
modules_to_save: [embed_tokens, lm_head]
embedding_learning_rate: 2e-5 # defaults to learning_rate / 10
Raw text passes through with no tokenizer call; ShareGPT and Alpaca still win
over a stray `text` column; cpt is formatted like SFT rather than taking the
preference passthrough. The empty-dataset error now names the three shapes and
prints the columns the dataset actually had.
326 tests passing.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Rebuilt on current main; the previous branch was cut from its predecessor and
carried five unrelated commits.
`praisonai-train llm` took three flags to `unsloth train`'s thirty-eight, and
was the one command that would not accept --config though export and serve
both do. Eleven flags now, plus --config and --dry-run.
Two fixes on top of the original branch, both from problems main surfaced:
train_llm is called directly as a plain function, not only through Click --
main's own tests do it. Unfilled Typer parameters then arrive as OptionInfo
objects and Path(config) raises TypeError. They are unwrapped to their declared
defaults first.
The dataset and model reach argv as well as the resolved config.yaml. The
config path alone is the better mechanism, since the legacy dispatcher drops
every flag it does not declare -- but an earlier incident had the dataset
dropped entirely and the run trained on a public Alpaca mirror, discovered
after the GPU time. Passing both means neither path can lose it, and main's
regression test for that incident keeps passing.
330 tests passing.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Rebuilt on current main. The previous branch was cut from its predecessor
rather than from main, so it carried three unrelated commits and conflicted
once those merged. This is the change on its own.
praisonai_train/remote/runner.py was never in the repo. It was untracked —
present in a working tree, absent from git — so the CLI wired to a module that
did not exist and every command raised ModuleNotFoundError. That is what the 7
CI failures were, and the runner here is the one the triage agent wrote to fix
it: stdlib only, no new dependency for a feature most users never touch.
The tests did not catch it because every one of them replaces `_runner` with a
fake. A fake is the right tool for the CLI's behaviour and the wrong tool for
"does the thing I am faking exist" — so there are now three tests that import
the real module, check it has the six methods the CLI calls, and assert it
pulls in nothing outside the standard library. Removing the module fails ten
tests where it used to pass fourteen.
praisonai-train remote preflight gpubox
praisonai-train remote start gpubox -c config.yaml -d data/train.jsonl
praisonai-train remote tail gpubox run-1787...
praisonai-train remote fetch gpubox run-1787... lora_model -o ./out
praisonai-train remote stop gpubox run-1787...
start prints the run id and the stop command before it streams, so a Ctrl-C
during --follow does not leave a job running with no handle. A preflight
failure and a refused start both exit non-zero. stop reports when nothing was
running rather than claiming success.
319 tests passing.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Two runtime bugs flagged in review:
- load_datasets() called logger.warning but the module never defines a
logger, so any dataset with processing_func set raised NameError and
aborted the run. Switched to print(), matching every other warning in
this module.
- Response-only masking (train_on_responses_only) rewrites SFT label
tensors; it is meaningless for DPO/ORPO/KTO, whose trainers build labels
from chosen/rejected pairs. The decision ran before method was read and
applied unconditionally, so an enabled masking setting could corrupt a
preference run. Gated the whole masking block on method == "sft".
Co-authored-by: Mervin Praison <[email protected]>
Two things the tool told the user that were not true.
OOM. torch.cuda.OutOfMemoryError subclasses RuntimeError, so the CLI's
catch-all flattened it into one ERROR line carrying torch's raw allocator dump.
It is the most common fine-tuning failure and the one where a first-time user
has no idea which number to change. The handler now classifies it and prints an
ordered remedy — sequence length first, smaller model last — matching the
ordering unsloth validated in its own backend
(studio/backend/core/training/worker.py:4834-4845). A test asserts every knob
the remedy names is actually accepted by the config, so the advice cannot drift
from the schema.
README. Two quickstart commands did not exist as written:
praisonai-train data from-trials ... # there is no `data` sub-app
praisonai-train llm --dataset ... # dataset is positional
The second is the exact shape of an incident this code already carries a
comment about (cli/commands/train.py:65-68): a dataset passed the wrong way was
silently dropped and the run trained on the default corpus, discovered only
after the GPU time was spent. A reader who "fixes" --dataset by dropping the
flag walks straight into it.
A test now parses every `praisonai-train <sub>` in the README and asserts it is
a registered command, so the docs cannot drift from the CLI again.
While writing the tests I deleted a branch I had just added: a separate
type(exc).__name__ == "OutOfMemoryError" check was redundant with the
"outofmemoryerror" text marker, since the class name is folded into the
searched text. No mutation could distinguish it from its absence, which is the
definition of code a test cannot cover.
12 tests. Mutations killed: the remedy never printed, the marker dropped, and
each README command reverted. Full suite 265 passing.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
In `assistant_only_loss: auto` (the documented default), use_mask was keyed
off TRL's `_supports_assistant_mask()` alone. Every unsloth template lacks
`{% generation %}`, so that returned False, use_mask became False, and
decide_masking short-circuited to full-sequence loss before the turn-marker
route was ever considered -- the exact defect this PR set out to fix. Auto now
enables masking when EITHER route is usable and lets decide_masking pick.
Adds regression tests covering the auto-normalization coupled with route
selection, the gap that let the bug survive.
Co-authored-by: Mervin Praison <[email protected]>
Resolves three P1 issues from review on PR #4357:
- Vision pushes (train_vision.py, upload_vision.py) now wrap push_to_hub
in the shared hf_push_errors context manager, so a 401/403 becomes the
same actionable advice the LLM path gives instead of a raw traceback.
- hub_push_kwargs default coercion is now string-aware: vision callers
that omit `flag` read hf_private: "false"/"0"/"no" as public instead of
bool("false") == True keeping the repo private against the user's wish.
- Legacy single-element quantization_method lists are normalized back into
config in both validate_config and for_export, so the GGUF exporter
(which re-reads self.config) receives the method string, not a list.
- train_vision.save_model_merged now uses the guarded clean_local_repo_dir
instead of an unguarded rmtree that could delete a namespaced repo path.
Co-authored-by: Mervin Praison <[email protected]>
Every instruction-tuning run was training on the prompt as well as the answer.
`assistant_only_loss` is TRL's mask and it needs `{% generation %}` in the chat
template. None of unsloth's 43 templates contain it — grep -c "generation %}"
unsloth/chat_templates.py returns 0. So `assistant_only_loss: auto`, the
documented default, resolved to False for every template a user can actually
select. There was no error; the run summary printed "Loss mask: full sequence"
as though that were the intended outcome.
Unsloth's own answer is train_on_responses_only(trainer, instruction_part,
response_part) (chat_templates.py:58-87), which masks by locating literal turn
markers and works on any template. It is applied to the built trainer rather
than through the config, because it rewrites label tensors on the tokenised
dataset.
That needs the two markers, which vary by family, so this adds a table for
llama-3, chatml, gemma, mistral, phi and zephyr, and a resolver that falls back
to the model name when no chat_template is set. Unknown models resolve to None
rather than a guess: masking on the wrong markers finds no boundary and trains
on nothing, which is worse than not masking.
Two things worth review:
- Writing the resolver's tests found a real bug in it. Every unsloth model is
"unsloth/<name>", and "unsloth" is itself a template key, so scanning the
full repo id sent every one of them to the chatml markers — including Gemma
and Llama models whose markers are different. It now matches the repo name,
not the org.
- The summary line now names which route masked. "assistant replies only" hid
the distinction between two mechanisms with very different coverage, and the
unmasked case now says what it costs: "full sequence (training on prompts
too)".
decide_masking() is separate from train_model so the routing can be tested
directly. The first version of that test read train_model's source for the
string "train_on_responses_only" and passed with the calling branch disabled —
the same shape of weak test that let the original defect survive.
18 tests. Five mutations, four killed: removing the fallback route, matching
the org prefix again, making two markers identical, and forcing masking on.
The survivor is collapsing the two routes into one truthiness check, which is
covered by the label test rather than the router. Full suite 253 passing.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
process_dataset applied the SFT formatter unconditionally, collapsing every row
to a single "text" column before the preference column check ran -- so a
correctly shaped DPO/ORPO/KTO dataset lost the very columns its trainer needs and
was rejected before trainer construction, making all three new methods
unreachable. Skip SFT text-formatting for preference methods so prompt/chosen/
rejected (and prompt/completion/label) survive intact.
Also fixes an undefined `logger` in load_datasets that raised NameError whenever
dataset.processing_func was set; switched to print to match the module.
Adds regression tests covering both the preference bypass and the unchanged SFT
path.
Co-authored-by: Mervin Praison <[email protected]>
Every model this tool uploaded became a PUBLIC repository. `private` was never
passed to push_to_hub_merged or push_to_hub_gguf in any of the three places
that push — train/llm/trainer.py, train_vision.py and upload_vision.py. Unsloth
accepts the flag (save.py:2654, create_huggingface_repo(private=...)); nothing
here forwarded it. A model fine-tuned on private data was published the moment
training finished, silently.
The default is now private. Publishing is one click in the Hub UI; unpublishing
something that has already been crawled is not. Set hf_private: false to
publish.
The same duplication hid two more defects, both in upload_vision.py, both
already solved in its LLM twin:
- No error handling at all, so a rejected token surfaced as a raw
HfHubHTTPError traceback. The LLM copy has translated 401 and 403 into
actionable messages for a while.
- An unguarded rmtree: it deleted config["hf_model_name"] whenever a directory
of that name existed, with no check that the value was a local path rather
than a Hub repo id. A bare name like "mymodel" deleted ./mymodel.
All three now share praisonai_train/_hub.py, so the next fix lands in one place
instead of one of three. save_method, commit_message and tags are forwarded
too — previously save_method was hardcoded to merged_16bit at all three sites.
Found by an agent diffing unsloth's save.py against these files.
14 tests. The privacy default is asserted directly, the YAML "false" string is
covered (without the trainer's coercion it is truthy and would keep the repo
private against the user's wish), and a test asserts no push site still uses a
bare token as its only kwarg — the signature of the original defect.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The DPO/ORPO/KTO support in the previous commit could never have worked on a
real corpus, and the tests did not catch it because they exercised the column
check in isolation rather than through process_dataset.
process_dataset ends with
dataset.map(format_func, remove_columns=dataset.column_names)
which collapses every row to a single `text` column for SFT. Applied to a
preference dataset that destroys prompt/chosen/rejected before the trainer ever
sees them, so every DPO run would have died with
method 'dpo' needs the column(s) ['prompt', 'chosen', 'rejected']
and the dataset has ['text']
— an error message that blames the user's file for something this code did to
it moments earlier.
Non-SFT methods now return the dataset with its columns intact, after the
shuffle that the SFT path would also have applied. Found by an agent reading
unsloth's rl_replacements.py against this file; the preference trainers there
read those columns by name (rl_replacements.py:163-201, :850-931).
Two tests, both asserting order rather than outcome: the method guard must
appear before the flattening call and must return rather than warn, and the SFT
path must still flatten. Removing the guard fails the first.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Unsloth patches TRL's DPO, ORPO and KTO trainers alongside SFT — they are
named in the list of trainers it rewrites at unsloth/__init__.py:1438-1443.
praisonai-train could only ever construct an SFTTrainer, so a dataset of
chosen/rejected pairs had nowhere to go and the whole preference-tuning half
of the backing library was unreachable.
method: dpo # or orpo, kto; sft remains the default
beta: 0.1
max_prompt_length: 1024
TRAINING_METHODS is a registry: each entry names the TRL trainer and config
class, the columns the dataset must provide, and whether the method needs a
frozen reference model. Adding a method is one entry.
Three things worth calling out:
- ORPO declares needs_ref_model: False. It folds the reference into its loss,
so holding a second frozen model would double VRAM for nothing.
- DPO and KTO pass ref_model=None, which means "use the frozen base weights".
With a PEFT adapter that is exactly right and avoids a second full model.
- The dataset's columns are checked before the run starts. TRL's own failure
for a wrongly-shaped preference dataset surfaces inside the collator —
minutes in, after the model is loaded and quantised, and phrased in terms
of tensors rather than the file the user pointed at.
The TRL imports are individual and lazy, so a TRL too old to provide one
trainer can still run the others rather than failing at import; a method whose
classes are absent raises a message naming what to upgrade.
resolve_method() is separate from validate_config() so the method surface can
be tested without a CUDA import.
19 new tests. Five mutations, all killed: accepting an unknown method, dropping
case normalisation, disabling the column check, giving ORPO a reference model,
and having validate_config skip the check. Full suite 233 passing.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Extract byte-identical prep and finalize logic from the sync
_execute_single_step and async _aexecute_single_step into three private
helpers (_prepare_step_context, _build_step_action, _finalize_step_result),
so both variants share a single source of truth. Genuine async seams
(handler-coroutine await, achat executor branch, retry-loop await) remain
per-variant. Pure behaviour-preserving extraction; no public API change.
Co-authored-by: MervinPraison <[email protected]>
Delete unreferenced 680-line EnhancedTemplateGenerator module that is
never imported, wired into the CLI, or exported. The canonical, wired
generator remains standardise/templates.py::TemplateGenerator.
Co-authored-by: MervinPraison <[email protected]>
The regression test for #4229 eagerly constructed Agent(memory=preset) for
every advertised preset, which initialised live memory adapters (Mem0/MongoDB)
and failed CI without API keys or running services. Assert resolver correctness
instead, matching resolver-only test patterns elsewhere.
Co-authored-by: MervinPraison <[email protected]>
- ui/index.html: handle approval_request SSE events with an inline
Allow/Always/Deny card that POSTs /approve/{id}. Without this, the default
approval_mode:ask stalled every gated file/URL tool for the full 300s
timeout because the shipped UI never resolved the decision.
- engine/server.py: _apply_env now removes OPENAI_API_KEY / OPENAI_API_BASE
when a value is cleared, instead of skipping it — clearing a key or base_url
no longer leaves the deleted credential/endpoint active for later turns.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
A Tauri shell supervising a Python engine on loopback. The streaming path is
kept off the IPC bridge: the webview reads SSE from 127.0.0.1 directly, which
is what jan, unsloth studio, ollama and hermes all independently converged on.
src-tauri/ Rust core, pure and I/O-injected so every decision is testable
without a Mac, a certificate, a network or an installed Python:
venv_resolve one function owns both interpreter and
site-packages, catching the silent case where
3.13.2 and 3.13.7 share a path and nothing raises
verify half-installed is Stale, not Ready
health a server answering failures with HTTP 200 cannot
be trusted by status code alone
readiness log phrasing is upstream and versioned, so it is
a tested pure function
adopt five gates before reusing an orphan; a recycled
PID is never killed
lockfile absent and corrupt get different answers
port_announce an announced port is a claim until probed
engine/ stdlib-only HTTP + SSE: streaming, cancellation, sessions,
persistence, tool approval carrying call_id, attachments, search,
settings, MCP config, fork, projects, keychain-backed secrets
ui/ single-file frontend. Named ui/ rather than dist/ because it is
hand-authored source, not build output -- and the repo's .gitignore
excludes dist, which would have silently dropped the entire
interface from the commit.
Tests: 62 Rust, 8 pacing, 11 DOM click tests dispatching real MouseEvents.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The verbose-callers migration accidentally dropped the broad `except Exception`
branch (added in 2eacdcf79) that degrades an installed-but-uninitializable
memory backend to FileMemory. Without it, a registered backend that raises a
non-ImportError during init (mem0 missing credentials, MongoDB unreachable)
hard-crashes Agent construction. Restored to honour the fallback contract.
Co-authored-by: Mervin Praison <[email protected]>
yaml_loader.py documents verbose: true in its example agents.yaml, reads it,
and passes it to Agent() unconditionally with a default of False. Agent has no
verbose parameter, so every scheduled YAML agent raises TypeError on
construction -- whether or not the key appears in the YAML.
Verbosity now goes through output=, which is where it was consolidated.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Verbosity was consolidated into output=, but two shipped call sites inside
praisonaiagents were left behind and raise TypeError on construction:
compaction/memory_flush.py the pre-compaction agent could never be built
tools/delegation_tools.py every delegate_task call
Agent's rejection of unknown kwargs is deliberate and is left intact. What was
missing was guidance: verbose is accepted by six sibling classes, and Agent has
no verbosity parameter among its 41, so the answer is not discoverable from the
signature. The error now names output= as the destination.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The shared BotSessionManager._profile_namespace field was rewritten by every
routing handler, so overlapping turns for different tenants could recompute a
storage key from another tenant's profile after an await point — reading or
persisting one tenant's transcript into another's namespace (flagged by
CodeRabbit and Greptile).
Bind the resolved profile turn-locally in a per-task ContextVar inside chat()
(consumed from per-agent/instance staging and reset in finally), and propagate
that context into the load/save executor threads. Concurrent routed turns now
keep isolated namespaces and an unscoped route always fails closed.
Adds an overlapping-turns regression test.
Co-authored-by: Mervin Praison <[email protected]>
The gateway resolved RouteMatch.profile but never consumed it, so per-route
tenant isolation was inert and failed open — every route on a process shared
one memory store. Wire the resolved profile through the routing handlers onto
the session's storage key so memory/session state is namespaced per tenant,
and stays unscoped (fail-closed) when a route names no profile.
Co-authored-by: MervinPraison <[email protected]>
The lockstep extraction only recognised double-quoted literal msg_type
comparisons, so a dispatcher branch written enum-only (as ping/pong already
are, e.g. `msg_type == EventType.X.value`) would drift past it — the exact
silent registry/dispatcher divergence the test exists to catch.
Resolve every `EventType.<NAME>.value` operand through the enum to its wire
value, treat operands within one `in (...)` branch as aliases for a single
dispatch path (so the abort/MESSAGE_ABORT branch stays one method, not a
spurious `message_abort`), and add a positive control asserting the
enum-derived branch resolution still works.
Co-authored-by: Mervin Praison <[email protected]>
Providers send a tool-call id once and omit it on later argument chunks.
The DELTA_TOOL_CALL/TOOL_CALL_END branches minted a fresh UUID per chunk,
orphaning arguments from the invocation the client assembles. Track the
active tool call in EventBuffer and fall back to it. Also drop the
truthiness guard on these branches so a TOOL_CALL_END with an empty
tool_call payload closes the call instead of raising.
Co-authored-by: Mervin Praison <[email protected]>
Reuse the original request messages (system prompt, output constraints,
memory context) for the post-tool follow-up instead of chat_history alone,
which dropped the system turn. Bracket the follow-up answer with
REQUEST_START/LAST_TOKEN/STREAM_END so consumers see telemetry for the
answer, not just the tool-call round. Strengthen the regression test to
assert the sentinel flows through the streamed answer, proving the tool
branch ran.
Co-authored-by: Mervin Praison <[email protected]>
The streaming path collected tool calls, executed them, appended the results
to chat history -- and then ended. It never asked the model for the final
answer, so start(stream=True) yielded nothing while the identical
non-streaming call answered normally.
There was no error. The caller received an empty generator and could not
distinguish 'the model had nothing to say' from 'the answer was never
requested'.
The follow-up completion carries no tools, so the model answers from the
results it already has rather than calling another tool, which also bounds
the turn to a single round.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
resolve_required_scope() fails closed to ADMIN for anything it does not know,
which is the right default -- but four of the six message types the dispatcher
handles were unregistered, so switching the resolver on would have demanded
ADMIN for the connection handshake and locked out every client.
hello, join and leave are READ; abort is WRITE, since aborting a turn mutates
it exactly as sending one does.
Adds a lockstep test pinning the dispatcher's message types against the
registry, in the style that catches a runtime-only permission failure no
behavioural test can see.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The AG-UI adapter handled DELTA_TEXT, TOOL_CALL_START and TOOL_CALL_RESULT
and ended with a bare `return []`. StreamEventType has sixteen members, so
thirteen were discarded with no error and no log.
ERROR, RETRY, MODEL_FALLBACK and STREAM_UNAVAILABLE were among them: a
mid-stream provider failure produced a run that ended cleanly having never
told the client anything went wrong.
Every type now has an explicit disposition -- mapped, or listed in
NOT_WIRE_VISIBLE -- and an undeclared type raises rather than vanishing, so
adding a seventeenth member fails a test instead of dropping a frame in
production.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
CI test-core (subdirs) failed on test_every_advertised_preset_resolves with
"Mem0 API Key not provided" because the mem0 package is installed in that job
but no MEM0_API_KEY is set. Agent(memory="mem0") already promised a graceful
"Falling back to FileMemory" for missing optional dependencies (ImportError),
but an installed-yet-uninitialisable SaaS backend raised ValueError, which was
uncaught and crashed construction. Broaden the string-preset branch to honour
the same fallback contract for runtime init failures.
Pre-existing, unrelated to PR #4340 (gateway durability); no Agent params added.
Co-authored-by: Mervin Praison <[email protected]>
Address two valid review findings on the durability-degradation surface:
- Recovery clears degradation: a successful durable SqliteIdempotencyStore
build now clears any prior `durability:idempotency` degraded fact, so a
same-process rebuild (config hot-reload) that restores durability no longer
leaves health()/`gateway status` permanently reporting non-durable operation.
Mirrors the existing session-store recovery-clear path.
- Redacted operator-facing reasons: the idempotency and session fallback paths
no longer interpolate the raw store-init exception (which can embed backend
filesystem paths) into the degraded-owner `reason`. The raw exception stays in
the log only; the reported reason is an operator-safe, redacted string —
matching the documented contract on record_durability_degraded.
Tests: add recovery-clears-degradation test and a redaction assertion.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Gateway durable state was opt-in and lost silently. Now:
- build_idempotency_store is durable by default (SQLite when a state dir is
available); "memory" stays an explicit opt-in for tests/ephemeral runs.
- Gateway server default idempotency backend is durable when none configured.
- Session/idempotency store-init failures record a durability-degraded fact
(owner_kind="gateway", owner_id="durability:<component>") instead of a silent
logger.warning, reusing the existing DegradedCapabilityRegistry — no new core
protocol or Agent params.
- health() merges durability facts; `gateway status` prints a Degraded: section
with a redacted reason and a `fix:` hint so operators see non-durable runs.
Co-authored-by: MervinPraison <[email protected]>
- rules clear: constrain deletion to workspace-scoped CLI-created rules; no
longer unlinks discovered AGENTS.md/CLAUDE.md/PRAISON.md, global, git-root or
nested subdir rules (Greptile P1).
- context_files remote fetch: pin each connection to a validated public IP and
re-validate at connect time, closing the DNS-rebinding TOCTOU window while
preserving Host/SNI; _allow_local_urls opt-in bypasses pinning (Greptile P1).
- tests: add regressions for clear-scope preservation and rebind refusal.
Co-authored-by: Mervin Praison <[email protected]>
On a standalone `pip install praisonai-code` the subtree instruction hook,
`--instructions` resolution, and the `rules` command silently degraded because
their implementations were reachable only via the optional `praisonai_bot` /
`praisonai` wrapper packages.
- Add a resident, dependency-free `praisonai_code/integration/context_files.py`
(stdlib + `praisonaiagents.hooks` only) so subtree AGENTS.md loading and
`--instructions` glob/URL resolution work without the optional packages.
- Wire `run.py::_wire_subtree_context_hook` to fall back to the resident helper
after the optional bot/wrapper copies, removing the silent no-op.
- Give `rules list/add/clear` a native implementation backed by core
`praisonaiagents.memory.RulesManager`, delegating to the wrapper bridge only
when core is genuinely unavailable.
- Add standalone regression tests that block the optional packages.
Co-authored-by: MervinPraison <[email protected]>
Address two P1 races flagged by Greptile on PR #4336:
- executor.submit: reserve the admission slot synchronously (create+register
task before any await) so concurrent submits can no longer slip past the
max_queued ceiling. The QUEUED persist moves to the head of _execute_job
(before the concurrency semaphore), preserving the store-reflects-QUEUED
contract without a check-then-await race.
- router.submit_job: on JobQueueFull after save_if_absent persisted the job,
delete the stranded record so its idempotency key is freed and status/SSE
don't hang while /result returns 409. Cleanup is best-effort and never masks
the 503.
Co-authored-by: Mervin Praison <[email protected]>
Gap 1: JobExecutor now keeps a list of progress callbacks per job and
fans out to all of them, so concurrent SSE viewers of the same run each
receive updates; unregister removes only the given callback.
Gap 2: JobExecutor.submit rejects with JobQueueFull once max_queued
(default max_concurrent*10) is reached; the router maps this to a 503 +
Retry-After so floods get honest backpressure instead of unbounded task
growth.
Gap 3: AsyncAgentScheduler gains from_blueprint via a shared
build_from_blueprint helper in _base_scheduler; blueprint resolution now
lives in one place for both sync and async schedulers, and the async
variant dispatches via astart so it never blocks the event loop.
Co-authored-by: MervinPraison <[email protected]>
- chat_mixin: before_model/wrap_model_call mutations to temperature/tools now
flow into the retry core (were silently ignored)
- chat_mixin: after_model mutations on non-string responses are preserved via
_unwrap_model_response (previously raw object bypassed hook edits)
- chat_mixin: achat() now routes through the model middleware manager (was
bypassing before/after/wrap_model_call); sync chain bridged via executor
without nesting event loops, retry core extracted to
_achat_completion_with_retry_core
- knowledge: URL ingestion now captures bare string document ids (MongoDB)
Addresses CodeRabbit/Greptile review findings on PR #4334.
Co-authored-by: Mervin Praison <[email protected]>
- Task(skip_on_failure=True)/on_error="continue" now let a dependent task
run in degraded mode instead of being force-failed when an upstream
dependency fails, across every cascade path (agents async/sequential and
process sequential/asequential).
- Agent(hooks=[before_model/after_model/wrap_model_call]) now fire: model
calls route through MiddlewareManager.execute_model_call via a new
_get_model_middleware_manager, mirroring the existing tool-hook wiring.
- Knowledge.add() now ingests URL inputs (as its docstring documents) via
MarkItDown extraction instead of raising NotImplementedError.
Co-authored-by: Mervin Praison <[email protected]>
web_search and other tools declared in praisonaiagents' TOOL_MAPPINGS
resolve to None when their optional dependencies aren't installed. After
switching to ToolResolver.resolve(), these were incorrectly flagged as
'Unknown tool' errors, breaking test_agents_yaml_valid_fields_no_warnings.
Consult TOOL_MAPPINGS so such tools produce an install warning instead of
a hard error, while genuinely unknown tools still error.
Co-authored-by: Mervin Praison <[email protected]>
ConfigValidator._validate_tools called a non-existent resolve_tool()
method on the ToolResolver instance, raising AttributeError that was
swallowed by the broad except, downgrading every tool reference to a
generic warning. Unknown/misspelled tools were never reported as errors.
Use the actual instance method resolve(), which returns None on miss.
Co-authored-by: MervinPraison <[email protected]>
Address CodeRabbit review: _get_legacy_verbs() returned an empty set on
oracle import failure, which let implemented verbs (e.g. `thinking status`)
fall through to the bare-prompt rule and be forwarded to the modern `run`
engine as a paid LLM prompt — the exact #4327 regression the guard prevents.
Now fails closed via a static _LEGACY_VERBS_FALLBACK mirror, logs a warning,
and does not cache the fallback (so recovery is possible). Adds tests for the
fail-closed path, end-to-end routing under discovery failure, and a drift
assertion keeping the fallback in sync with the authoritative oracle.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Since 82f55c97b the unified dispatcher treated any first token that is not a
registered Typer command as free text and forwarded it to the modern `run`
engine, billing 29 implemented legacy verbs (thinking, install, persistence,
audio, …) to /v1/responses at ~2.5k tokens with exit 0.
Extract the legacy dispatcher's authoritative verb list into a reusable
LEGACY_SPECIAL_COMMANDS constant and have the unified dispatcher consult that
same oracle: an implemented legacy verb routes to legacy (its handler) before
the bare-prompt/LLM path. containers and vector-stores are withheld pending
#4322 so routing does not promote a fabricated success.
Co-authored-by: MervinPraison <[email protected]>
The `search` command was advertised in --help and registered as a real Typer
command, but was missing from get_command_names()'s routing oracle. This caused
`praisonai search "..."` to be misclassified as a bare prompt and billed as an
LLM call, contradicting its "no LLM generation" help text.
Adds `search` to the routed set and a parity regression test guaranteeing every
advertised command is also routed (guards the #2191 drift guarantee).
Co-authored-by: MervinPraison <[email protected]>
backends was added to _LAZY_COMMANDS but never mapped in COMMAND_CATEGORIES,
leaving test_every_registered_command_has_a_category failing and the command
without an explicit --help panel. Map it to Advanced.
Co-authored-by: Mervin Praison <[email protected]>
Vector store file ops now call the real litellm public API
(vector_store_file_create/list/delete) instead of the never-existent
create_vector_store_file names, and no longer swallow AttributeError into
fabricated success. Delete defaults to False, not True.
search() uses the shipped duckduckgo_tools.internet_search symbol (was the
nonexistent duckduckgo_search) and surfaces backend errors instead of a
permanent empty-but-successful result.
containers/container_files have no backend, so container_create and the
container file read/write/list functions now raise NotImplementedError
rather than inventing container IDs or returning empty results. CLI and MCP
adapters already wrap these in except Exception, so failures surface cleanly.
Co-authored-by: MervinPraison <[email protected]>
get_command set rich_help_panel but never command.name. typer_get_command
yields "" for a Typer(help=...) declared without name=, and collapses a
single-command app to that command's own name — so --help rendered 77/98
commands with a blank name and 3 with a wrong (untypeable) name. Pin
command.name to the registry key (the true typeable name) in get_command.
Co-authored-by: MervinPraison <[email protected]>
- _chunk.py: only re-wrap truly pure single-fence chunks in enforce_hard_cap;
mixed fence+prose or multi-fence chunks are hard-split as plain text so prose
is never rendered as code (Greptile P1).
- telegram.py: measure and chunk in the platform's declared UTF-16 unit so
emoji-heavy replies cannot exceed Telegram's 4096 UTF-16 cap (Greptile P1).
- tests: mixed-fence non-corruption + UTF-16 length coverage.
Co-authored-by: Mervin Praison <[email protected]>
Part 1: split_media_from_output stripped every blank line from every
Telegram/Slack reply, destroying load-bearing separators, paragraph
breaks and clean chunk boundaries. Now only excess blank runs left by
removed MEDIA lines are collapsed; single blank-line separators survive.
Part 2: chunk_message emits an over-cap code fence by design and no
caller re-checked the platform cap, so a pure/oversized fence raised
"message too long" and lost the whole reply. New enforce_hard_cap()
splits any over-cap chunk (re-balancing ``` on split fences) and is
applied in every _send_long_message (telegram/slack/discord).
Fixed together so restoring blank lines cannot regress fence delivery.
Co-authored-by: MervinPraison <[email protected]>
- Remove the dead /sethome registry entry: it was published to every
adapter's menu but implemented on none, so drop the false advertisement.
- Telegram: on a slash-command miss, dispatch the raw text to the agent
instead of ending silently, matching the Slack reference and the code's
own docstring.
- Discord: remove the bare terminal return in the on_message command block
so an unknown/unimplemented slash command falls through to agent dispatch
(like Slack) rather than a silent no-op.
- _session.reset()/reset_all(): clear _model_overrides so /new actually
remedies a bad or unavailable /model instead of every later turn failing
silently at the provider.
Co-authored-by: MervinPraison <[email protected]>
Address final-review findings on #4316:
- _export_qc_cfg no longer force-zeroes script thresholds when a caller sets
script_range/script_drop/script_flag, so a documented
qc_cfg={"script_range": [...]} re-enables the target-script check for other
languages instead of silently passing wrong-script rows. English default
(thresholds=0) is unchanged when no script key is given.
- Add test for the script_range-only re-enable path (kept for Latin, dropped
for Tamil).
- README: validate's atomic --out write is shared with generate/dedup, and
document that any script key re-enables the export QC check.
Co-authored-by: Mervin Praison <[email protected]>
Explicitly chain the translated typer.Exit from the caught SystemExit to
resolve Ruff B904 and preserve the original traceback.
Co-authored-by: Mervin Praison <[email protected]>
The legacy dispatcher's `if args.command:` chain had no `train` case, so
`praisonai-train llm <dataset>` fell through to the bare-prompt handler and
forwarded the literal word "train" to an LLM as a chat prompt — the real
training block was never reached and no trainer subprocess launched.
- Add a `train` guard in main()'s command chain so it reaches the dedicated
training block (which reads args.dataset/args.model and dispatches
praisonai_train.train.llm.trainer).
- Propagate a non-zero SystemExit from the router in train_llm so missing-dep
failures no longer exit 0 (CI gating on $? now sees them); clean exits still
return 0.
- Add a regression test that drives the real router (asserts the trainer is
dispatched and handle_direct_prompt is never called) plus exit-code tests.
Co-authored-by: MervinPraison <[email protected]>
- from-trials --qc: default export QC config disables the Tamil script-purity
check, since agent trajectories are English by construction (kept dedup,
boilerplate/refusal, length, diversity). qc_cfg still re-enables it.
- Surface the actual QC drop reasons: ExportSummary gains skipped_qc/qc_drops so
no row vanishes unaccounted, and from-trials names the reasons on the zero-row
error instead of guessing.
- validate: reuse the in-module tempfile+os.replace helpers (mirrors dedup/
generate) with a zero-kept guard, so an --out that aliases the input is never
truncated and a zero-kept run exits non-zero leaving any existing file intact.
- Document the Tamil script_range default in README and validate --help.
Co-authored-by: MervinPraison <[email protected]>
- server.py: extension-engine termination now uses the per-session agent's
max_steps (forwarded via start_session) instead of the server default, so
`browser run --max-steps` actually bounds the run (Greptile P1).
- browser.py: playwright/hybrid engines now warn when CDP-only options
(--vision/--screenshots/--record-video/--max-retries/--no-record) are set
rather than silently discarding them; corrected the run --help "Features"
block to state these require --engine cdp specifically (Greptile P1).
Co-authored-by: Mervin Praison <[email protected]>
- knowledge.query: forward `limit` to Knowledge.search (was dropped)
- a2a.send: forward `task_id` via kwargs (was discarded)
- realtime.send: map message to `data` with real event_type (was passed as event_type)
- add regression tests for the three semantic bindings
Co-authored-by: Mervin Praison <[email protected]>
- Send max_steps in start_session wire frames on the extension path
(server.py already reads it, so this was a pure missing-field fix)
- Pass record_video=record_video to run_cdp_only in _run_alternative_engine
so --record-video on cdp actually records instead of only billing gpt-4o
- Warn when engine-only options (--vision/--screenshots/--record-video/
--max-retries/--headless/--extension/--no-record) are set on the default
extension engine, instead of silently discarding them
- Clarify --url is context-only on the extension path and show max steps
- Fix run --help "Features" caveat and add --engine to screenshots example
Co-authored-by: MervinPraison <[email protected]>
A CDP click/type/clear_input on a selector matching nothing returned success
unconditionally, so run()'s retry loop broke on first success and --max-retries
plus all fallback-selector strategies never fired. The injected JS now returns
whether the element was found and a miss yields success=False with an error,
making the existing alternative-selector retry strategies reachable.
Co-authored-by: MervinPraison <[email protected]>
Coerce unknown deploy keys to str before sorted()/join() so a non-string
YAML key raises a clean ValueError instead of TypeError, and guard that
the deploy section is a mapping. Adds regression tests.
Co-authored-by: Mervin Praison <[email protected]>
status() and destroy() previously fell back to the ambient az
subscription when subscription_id was unset, risking wrong-subscription
inspection/deletion. Both now return their structured failure result
before issuing any az command, mirroring deploy()'s guard.
Also fixes test_azure_provider_deploy_failure to supply a
subscription_id so it reaches subprocess.run, and adds no-subscription
tests for status() and destroy().
Co-authored-by: Mervin Praison <[email protected]>
27 of 85 advertised praisonai-mcp tools could not succeed for any input:
their adapters called core/wrapper APIs that don't exist or have different
signatures, failing at attribute lookup or argument binding before any I/O.
24 returned isError:false and 9 reported an installed module as "not available".
Rebindings against real core:
- knowledge.*: query->search, list->get_all, stats->get_corpus_stats,
clear->reset, add(source) (dropped nonexistent source_type)
- hooks.*: get_default_registry().list_hooks() (was get_hook_manager)
- session.*: get_default_session_store() (was SessionManager)
- tools.*: list_tools/get_tool (was get_available_tools/get_tool_info/search_tools)
- eval.*: AccuracyEvaluator/PerformanceEvaluator (was AccuracyEval/PerformanceEval)
- workflow.run/run_file: AgentsGenerator(..., config_list=[])
- workflow.auto: AutoGenerator(topic, pattern).generate()
- audio.transcribe(audio=), audio.speech(text=), guardrails.check(content=),
ocr(document=), a2a.send(target_agent=), containers.file_read/write(path=),
skills.load(skill_name=), realtime.send(event_type=)
- resources: memory/sessions -> session store, knowledge/sources -> get_all
_handle_tools_call now sets isError:true when a handler returns an
"Error: ..." string, matching the convention already used for adapters
that raise.
Tests bind against real core (not hand-written fakes), so a future core
rename the adapter doesn't track fails here.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: MervinPraison <[email protected]>
Bring DockerSandbox policy validation to parity with SubprocessSandbox
where it is semantically meaningful for a container:
- Enforce allowed_paths (opt-in) alongside blocked_paths, so a path
outside configured roots is refused before dispatch.
- Route run_command through the shared build_argv helper so a shell=True
payload is split by policy_scan_parts and its paths are scanned,
instead of walking an opaque `sh -c "..."` argv.
Deliberately does NOT copy SubprocessSandbox's allow_subprocess shell
block: Docker always dispatches via `sh -c` inside the container, which
is the isolation boundary that clause approximates on the host. Applying
it would refuse every command and defeat the backend rather than harden
it.
Adds regression tests for allowed_paths (in/out) and shell-payload path
scanning. All host-side + Docker filesystem tests pass.
Co-authored-by: Mervin Praison <[email protected]>
A misspelled field/section key in agents.yaml was silently discarded by
pydantic's default extra='ignore', so `deploy validate` reported valid while
deploying with defaults (e.g. a typo in cluster_name deploying to a new ECS
cluster). Set extra='forbid' on the deploy input models, reject unknown
top-level deploy sections in schema validation, surface cluster_name in the
human-readable validate output, and make the docker `push: true` path reach the
existing "no registry" error instead of silently skipping the push.
Co-authored-by: MervinPraison <[email protected]>
Azure Container Apps deployments read subscription_id only to echo it in
plan(); it was never passed to az, so every resource was created/destroyed in
the ambient default subscription. Mirror the GCP provider:
- append `--subscription {subscription_id}` to all six az invocations across
deploy/status/destroy/doctor via a _subscription_args() helper
- fail fast in deploy() when subscription_id is unset (matches GCP's project_id
guard)
- check_azure_cli() now compares the ambient subscription against the configured
one and warns on mismatch
Co-authored-by: MervinPraison <[email protected]>
DockerSandbox accepted a SecurityPolicy and enforced none of it, so moving
to the tier documented as stronger silently dropped every command-level
control. Mirror the tested SubprocessSandbox enforcement:
- Validate commands against blocked_commands / allowed_commands / blocked_paths
in run_command before dispatch.
- Truncate host-side communicate() output to max_output_size in run_command
and execute, so a runaway print in the container cannot exhaust the host
process.
Co-authored-by: MervinPraison <[email protected]>
Extends the OpenAI-native /stop fix to every synchronous same-run
re-dispatch that previously dropped the token, closing the Greptile P1
"nested completions drop cancellation":
- reflection + regeneration _chat_completion calls (chat_mixin.py)
- internal recursive redispatches: context-compression retry,
model fallback, retryable-error backoff (chat_mixin.py)
- guardrail-retry regeneration via _apply_guardrail_with_retry
(agent.py + its sync call sites in chat_mixin.py)
All hops just forward the existing cancel_token param (defaults None),
so behaviour is unchanged when no token is set. No new Agent params,
modules, or exports.
Co-authored-by: MervinPraison <[email protected]>
The default (non-custom) LLM path dropped the cancel token: chat_mixin
threaded llm_kwargs['cancel_token'] only inside the custom-LLM branch,
while the OpenAI-native else branch called _chat_completion(...) which
had no cancel_token parameter. The token never reached OpenAIClient,
so the between-iteration cancel checks were never armed and /stop
reported success while remaining tool calls kept executing.
Thread cancel_token symmetrically through the four sync hops that
already existed: _chat_completion -> _chat_completion_with_retry ->
_execute_unified_chat_completion -> _unified_dispatcher.chat_completion,
matching the custom-LLM branch. Defaults to None so no caller behaviour
changes.
Co-authored-by: MervinPraison <[email protected]>
The async idempotency veto only scanned self.tools, so a task-scoped tool
supplied via tools_override (and never registered on the agent) missed its
restart_safe=False / idempotent=False declaration and was retried, duplicating
its side effect. _tool_declares_not_idempotent now accepts the effective
tools_override set (searched first, mirroring _execute_tool_async_impl
resolution) while defaulting to None for the unchanged sync call sites.
Also tightens the test helper to catch only the expected RuntimeError /
ToolExecutionError instead of a blanket Exception, and adds an override-only
regression test.
Co-authored-by: Mervin Praison <[email protected]>
Adapter-backed get_all_memories() returned records keyed by `memory_type`
(SQLite) or `type` (in-memory), diverging from the legacy path's `type`
field and breaking callers that read record["type"]. Normalize adapter
results to always populate `type` while retaining adapter-specific keys.
Strengthen regression tests: assert both colliding tiers are erased on
untyped deletion, and assert the public `type` field is present on
adapter-backed records.
Co-authored-by: Mervin Praison <[email protected]>
_execute_tool_async_with_retry never consulted the idempotency
declaration, so achat()/astart() re-ran an effectful tool marked
restart_safe=False up to max_attempts times. Add the same veto the
sync loops use (tool_execution.py:884 and :2115) plus an async test.
Co-authored-by: MervinPraison <[email protected]>
Address reviewer findings on PR #4296:
- Data-loss guard (CodeRabbit): derive WarmSession.flushed from a per-key
_flushed marker set only after a completed store write, not from
_store presence. A caught/partial persist now leaves the cache unflushed
so the pressure sweep never evicts the only current copy. Marker cleared
in _save_history (pre-write), _soft_evict, and reap_stale.
- Nested cgroup (CodeRabbit): resolve the process's own cgroup path from
/proc/self/cgroup and probe its v2/v1 memory limit first, falling back to
the filesystem root so a nested container's lower ceiling is honoured.
- Tests: add failed-persist skip and nested-cgroup coverage (15 total pass;
core planner 16 and gateway session suites still green).
Co-authored-by: Mervin Praison <[email protected]>
get_all_memories() selected from legacy short_mem/long_mem tables that no
adapter creates, so it swallowed OperationalError and returned [] for every
provider. Delegate to the active adapter, mirroring delete_short_term/
reset_short_term.
delete_memory(id) with no memory_type short-circuited on the first tier that
reported a hit. Since the SQLite adapter gives each tier its own AUTOINCREMENT
sequence, ids collide across tiers, so it erased an unrelated short-term row
and left the caller's target in place while reporting success. Delete from
both tiers instead of short-circuiting.
Co-authored-by: MervinPraison <[email protected]>
The core planner plan_pressure_evictions() plus the WarmSession /
MemoryPressureProtocol contracts had no runtime consumer, so an
always-on multi-session gateway had no way to reclaim warm-cache memory
under pressure and climbed to OOM.
This adds the missing wrapper-side enactor and a concrete reader:
- BotSessionManager.warm_sessions(): snapshots warm caches as core
WarmSession facts (LRU last_activity, in_flight, flushed).
- BotSessionManager.sweep_under_pressure(): reads the real cgroup budget/
RSS, calls the core planner, and soft-evicts the coldest rebuildable
caches LRU-first, re-sampling RSS to shed the minimum. No-op without a
cgroup limit, preserving today's behaviour.
- BotSessionManager._soft_evict(): drops only the in-memory history; the
durable store copy remains and is rebuilt on the next turn (lossless).
- Per-turn in-flight tracking so a live turn's cache is never evicted.
- gateway/memory_pressure.py CgroupMemoryPressure: stdlib-only concrete
MemoryPressureProtocol (cgroup v2 memory.high/max, v1 fallback,
/proc/self/status RssAnon), degrading to no-op when unreadable.
Flushed (store-backed) caches only are evicted; in-flight and unflushed
caches are always skipped. Backward-compatible: no eviction unless the
gateway calls sweep_under_pressure on its periodic tick.
Co-authored-by: MervinPraison <[email protected]>
Closes two P1 gaps in the ack scope gate (Greptile #4293):
- Gateway-hosted Telegram handler acked on `_ack.enabled` alone, bypassing
ack_scope so ambient group chatter still got a ⏳ reaction. Now routes
through should_ack_message like the standalone adapter.
- Slack classified a thread reply (no fresh @mention, mention_required off)
as ambient, silently dropping its ack. thread_ts now counts as engaging
the bot so the reply is acked under group-mentions.
Adds 3 TestAckScopeGating cases for the gateway wiring and Slack thread
classification.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Addresses Greptile P1 findings on PR #4292:
- GatewayApprovalBackend now threads authorized_reviewers into register(),
so per-request reviewer custody is actually bound on the production path
(previously silently dropped, leaving every request unbound).
- _resolve_operator_identity prefers a non-secret X-Operator-Id header before
the shared-token digest, so a proxy/SSO layer can distinguish individual
operators sharing a gateway token in the audit trail.
Adds a regression test asserting the backend binds custody end-to-end.
Co-authored-by: Mervin Praison <[email protected]>
Add a closed AckScope (off | direct | group-mentions | group-all | all)
to AckReactor with a should_ack()/should_ack_message() gate, and a
BotConfig.ack_scope key (default group-mentions). Adapter call sites
(telegram/discord/slack/whatsapp/signal/linear) now derive direct/mention/
ambient context from the existing BotMessage and only ack messages the
scope covers, instead of reacting to every non-command message.
Co-authored-by: Mervin Praison <[email protected]>
The gateway resolve boundary now captures the resolving principal on the
durable audit trail (ApprovalDecision.approver) and allow-always grant,
replacing the constant "gateway"/"gateway:human" attribution. Resolution
gains an optional resolver id, threaded from the authenticated HTTP request
context (derived as a non-secret hash handle of the operator token).
An approval may optionally be bound to a set of authorized reviewers;
resolve() rejects a resolver not in that set (re-inserting the request so an
authorised reviewer can still resolve it) while preserving first-answer-wins
via the atomic pop. The binding is durable across restarts. Core
ApprovalRequest gains an optional authorized_reviewers field (the only core
touch). All defaults keep today's behaviour.
Co-authored-by: Mervin Praison <[email protected]>
The Signal poll loop refreshed inbound-liveness on every successful poll
batch, including successfully-empty ones. A silently half-open transport
returns [] forever without raising, so this kept health.last_activity
fresh and defeated the existing evaluate_channel_health STALE_SOCKET seam,
leaving a "deaf" channel reported HEALTHY with no operator signal.
Only note inbound activity when the bridge actually delivered an envelope,
so a stalled poll loop becomes detectable through the existing health seam
(no new module, API surface, or config knob).
Co-authored-by: Mervin Praison <[email protected]>
Address Greptile P1s on AsyncMongoDBStateStore:
- async_hdel now returns only the count of fields actually present and
removed (StateStore contract "Returns count deleted"), matching the
Firestore/DynamoDB document-store backends instead of over-reporting.
- async_hset/async_hdel treat fields as opaque top-level keys via a
$mergeObjects pipeline / read-compute-write, so a dotted field like
"a.b" round-trips through hget/hgetall/hdel instead of being coerced
into a nested MongoDB path.
Co-authored-by: Mervin Praison <[email protected]>
- AsyncMongoDBStateStore: implement the 7 missing StateStore abstract
methods (keys, ttl, expire, hget, hset, hgetall, hdel) plus async twins
so the class is instantiable and every async_mongodb/motor/mongodb_async
factory alias boots instead of raising TypeError.
- db/adapter.py: rename the 6 async state-store call sites from the
non-existent aset/aget to async_set/async_get so async persistence hooks
take the native coroutine path instead of silently falling back to sync.
- agents_generator.safe_format: delegate to core
BaseFrameworkAdapter._format_template (single source of truth) so wrapper
and core cannot drift; fixes latent TypeError on non-string (None) input.
Co-authored-by: MervinPraison <[email protected]>
Closes the Greptile/CodeRabbit approval-clone coverage gap: the prior test
only inspected the original agent's private _approval_config and never
constructed a clone. Add a clone round-trip test asserting the served clone
reconstructs the same approval config and enforced _perm_deny set, plus a
negative test that a plain agent and its clone stay policy-free.
Co-authored-by: Mervin Praison <[email protected]>
clone_for_channel() rebuilds the agent from getattr(self, '_guardrails_config',
None) and getattr(self, '_approval_config', None), but neither attribute was
ever assigned to the instance -- both were locals inside __init__. The getattr
therefore always returned None and every served clone (one per gateway channel,
one per HTTP invocation) ran with no output guardrail and lost its approval
policy. Persist both resolved values on the instance so the clone can read them.
Co-authored-by: MervinPraison <[email protected]>
Regression from #4257: `_tool_declares_not_idempotent` fell back to the
shared `MUTATING_TOOLS` name registry, silently dropping the retry from
any *undeclared* tool that happened to share a name with an entry
(`write_file`, `store_memory`, `mkdir`...). Key on the explicit
declaration only, and consult the process-global registry the way
`_is_tool_idempotent` already does when `allow_global_tools` is set.
Co-authored-by: MervinPraison <[email protected]>
- Return False for non-dict verdicts (e.g. [], "allow", null) to avoid
AttributeError and preserve fail-closed behavior (CodeRabbit)
- Set ToolResponse.result to the denial message since the agent tool
executor returns result and discards error, so denials reach the model
instead of a null result (Greptile)
- Add non-object JSON regression test; update block test assertion
Co-authored-by: Mervin Praison <[email protected]>
- Re-add Python-style single-quoted list support via ast.literal_eval
(safe literal-only eval), fixing a regression where ['a','b'] collapsed
into a single loop item.
- Anchor JSONDecoder.raw_decode with the idx argument instead of slicing
text[start:] to avoid per-bracket copies.
- Cap decode attempts (and keep the 1M-char guard) so deeply nested
bracket input can no longer cause O(n^2) parsing time or a crash
(RecursionError now caught alongside JSONDecodeError).
- Add regression tests for single-quoted lists and adversarial input.
Co-authored-by: Mervin Praison <[email protected]>
Adds an optional, provider-neutral example that gates command-bearing
tools through HOL Guard at the existing wrap_tool_call boundary. The
policy is fail-closed: the wrapped tool only runs on an explicit allow
verdict; block/unknown/malformed/timeout/CLI-failure short-circuit with
zero downstream execution. Includes a regression test suite proving a
denied command never reaches the tool executor.
Co-authored-by: kantorcodes <[email protected]>
Delete the unused ServerRegistry class and _get_default_server_registry()
helper. These were never wired into the live launch path; server state
lives in module-level dicts in execution_mixin.py, torn down by
cleanup_launch_registration(). Also update the now-stale comment that
referenced the removed class.
Co-authored-by: MervinPraison <[email protected]>
- reject import payloads newer than PORTABLE_VERSION (reported, not applied)
- persist imported sessions verbatim via _save_imported_session (bypass
destination retention/active_window so a valid larger export is not truncated)
- copy metadata before clearing live fields so the caller payload is not mutated
- write CLI exports to a temp file + atomic os.replace (never corrupt an
existing backup on failure; nonzero exit on error)
- add tests for the above
Co-authored-by: Mervin Praison <[email protected]>
- Reject non-finite/non-increasing bucket bounds before storing (prevents
render_prometheus() failures)
- Raise ValueError on conflicting bucket layouts for an existing metric name
instead of silently ignoring later overrides
- Reject caller-supplied reserved 'le' label to avoid duplicate le samples
- Fix snapshot() to emit name_count{labels}/name_sum{labels} matching the
Prometheus renderer
- Rename _HistData sum param to avoid shadowing builtin (ruff A002)
- Add tests for bucket conflicts, le rejection, validation, and label ordering
Co-authored-by: Mervin Praison <[email protected]>
Extend the session-store contract with a store-agnostic portability surface so
a gateway operator can back up, move, or restore live conversation state:
- core: add PortableSessionStoreProtocol + ImportReport to session.protocols
- core: implement export_session / export_all / import_sessions on
DefaultSessionStore (SqliteSessionStore inherits it), reusing the existing
SessionData.to_dict/from_dict shape. Export is lineage-aware; import is
hardened (size cap, duplicate guard, malformed-record skip) and resets live
routing/activity fields so restored state is inert until re-bound.
- core: export the new symbols from session/__init__.py
- wrapper: add `praisonai gateway sessions export/import` CLI + preflight
helpers over the gateway's own default store.
Co-authored-by: MervinPraison <[email protected]>
Add a dependency-free histogram metric type to GatewayMetrics so the
gateway /metrics endpoint exposes latency distributions (buckets, _sum,
_count) for SLOs and slow-turn diagnosis, alongside the existing
counters and gauges.
- observe(name, seconds, buckets=..., labels=...) records durations
- timer(name, ...) context manager times its body and records it
- render_prometheus() emits _bucket/+Inf/_sum/_count histogram lines
- snapshot() includes a "histograms" section
- default buckets cover sub-second to multi-second turns
Co-authored-by: MervinPraison <[email protected]>
Address two P1 review findings on the gateway saturation telemetry:
- LoopWatchdog: anchor the lag clock to the oldest still-unacked probe so a
stall spanning several probe intervals is no longer understated (each fresh
probe was overwriting the send-time). The ack consumes the anchor so the
next probe re-anchors from a caught-up loop.
- OutboundQueue.try_depth_snapshot(): non-blocking (pending, dead_letter)
counts that yield None when the writer lock is contended, and wire
_compute_pressure() to reuse last-known depths instead of blocking. Health
and /metrics run on the event loop and must never wait on the outbox lock.
Adds regression tests for the anchoring invariant and the non-blocking snapshot.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Mervin Praison <[email protected]>
The always-on gateway enforces back-pressure (admission ceiling + fair
wait-queue, durable outbox/DLQ, event-loop wedge watchdog) but exposed no
saturation telemetry — health() reported liveness only, so the first signal
of overload was dropped work.
Core (praisonaiagents) owns the shape + a pure classifier, mirroring the
ReloadStatus precedent:
- HealthPressure frozen dataclass + deterministic evaluate_pressure() helper
- LoopWatchdog now reads back its continuously-measured scheduling lag
(last_lag_ms), the same signal the wedge check already uses
Wrapper (praisonai_bot) reads facts already in hand and fills the block:
- health() gains a "pressure" block; /metrics gains admission/backlog/lag gauges
- OutboundQueue.dead_letter_count() surfaces the permanent-failure tier
Additive observability only — no new config keys, no new endpoint.
Co-authored-by: MervinPraison <[email protected]>
Save the prior tool_call/llm_content callbacks and restore them on cleanup
under the core callbacks lock with an identity check, instead of blindly
overwriting and deleting the process-global slots. This mirrors
praisonaiagents' own register/restore pattern so another in-process
consumer that owns these slots keeps receiving events after a TUI turn.
Addresses Greptile P1 (global callback ownership lost).
Co-authored-by: Mervin Praison <[email protected]>
The default interactive TUI (async_tui.py) only registered the tool_call
display callback, so intermediate assistant text was rendered as a single
whole-response append after the worker thread joined. Register the core
llm_content callback (already emitted per LLM step) to push narrative into a
live assistant message as the turn progresses, and reuse that streamed
message as the finalised turn to avoid a duplicate append. Read-only review
turns keep their single-summary behaviour. No new core surface; wrapper-only.
Co-authored-by: Mervin Praison <[email protected]>
- api/call.py: the lazy-import refactor dropped the ``request: Request`` /
``websocket: WebSocket`` annotations, so FastAPI treated ``request`` as a
required query param and 422'd the ``/`` route. Stamp the real classes onto
the handlers in _register_routes (build time, where fastapi is already
imported) — import stays cheap, route injection restored.
- cli/_shim.py: skip ``None`` placeholders in the eager walk_packages loop so a
known-absent submodule can't poison the old dotted path before _AliasFinder
resolves it lazily (mirrors the existing guard in the first pass).
- test_wrapper_layer_regression.py: force PRAISONAI_ALLOW_LOOP_BLOCKING empty
around the strict assertion so an ambient opt-in can't mask the RuntimeError.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
The lazy-by-default shim in cli/_shim.py broke module identity across the
old/new dotted paths (guarantee #1 in its own docstring): importing the
old name first (e.g. `from praisonai.mcp_server.cli import ...`, as the
tests do) re-entered _AliasFinder and double-loaded the moved file,
yielding two distinct module objects. That made mock.patch("<old.path>")
target a different object than the running code (imported via the new
name), causing the test-core (cli/subdirs) and smoke CI failures.
Restore eager pre-registration as the DEFAULT (it was already lightweight:
optional heavy submodules that fail import are logged and left for lazy
resolution). Keep an explicit opt-out via PRAISONAI_SHIM_LAZY=1 for
callers that don't rely on cross-path module identity.
Also make api/call._load_local_tools() idempotent (clear before repopulate)
so repeated build_call_app(load_local_tools=True) builds no longer
accumulate duplicate tool definitions in the shared registry (greptile).
Co-authored-by: MervinPraison <[email protected]>
Three lightweight, backward-compatible wrapper fixes:
1. cli/_shim.py: gate the eager walk_packages pre-import behind
PRAISONAI_SHIM_EAGER (lazy by default via _AliasFinder) and log
previously-swallowed submodule ImportErrors instead of silently
skipping them.
2. api/call.py: make heavy deps (fastapi, twilio, uvicorn, pyngrok,
websockets, rich) lazy-imported; build the FastAPI app via a
build_call_app() factory plus a lazy module __getattr__ for `app`;
move the import-time tools.py filesystem scan + user-code execution
into a server-entry-point path so importing the module has no side
effects.
3. _async_bridge.run_sync_or_offload: refuse to block a running event
loop by default (opt-in via PRAISONAI_ALLOW_LOOP_BLOCKING), steering
async callers to arun_sync_or_offload; PraisonAIAdapter.run uses
run_sync on the plain-sync path and raises a clear error from a
running loop.
Updated the corresponding wrapper regression test to the new strict
contract.
Co-authored-by: MervinPraison <[email protected]>
The sync workflow() path (lines 1502/1504) is duplicated code, edited
independently from aworkflow(). The existing suite drove only aworkflow(),
so a whitespace regression in the sync branch would leave it green.
Adds _run_sync driver + parametrized sync retry/control tests. Verified
they fail without .strip() and pass with it.
Co-authored-by: Mervin Praison <[email protected]>
Decision task verdicts were routed via result.raw.lower() and pydantic.decision.lower() at eight sites without strip(). Raw model text routinely carries a trailing newline, so the condition lookup missed and a miss was treated as exit-condition-met: the workflow finished silently with the rejected output (no retry, no validation feedback, no error). This adds strip() at all eight sites so a padded verdict routes exactly like a clean one, matching validate_decision_string which already lowers and strips.
Co-authored-by: MervinPraison <[email protected]>
The retry veto only read the raw `idempotent` attribute, missing the public
`restart_safe=False` contract used by @tool (FunctionTool) and BaseTool. Such
effectful tools remained retryable in both loops, duplicating side effects.
Fall back to `restart_safe` when `idempotent` is unset; add regression tests
for @tool and BaseTool declarations.
Co-authored-by: Mervin Praison <[email protected]>
A tool declaring idempotent=False was still re-driven up to max_attempts
times by both retry loops, duplicating side effects (send a second email,
charge twice). Both loops now veto the retry when a tool *explicitly*
declares itself non-idempotent, via a new tri-state helper
_tool_declares_not_idempotent that keys on the explicit declaration only,
leaving undeclared/declared-safe tools' retry behaviour unchanged.
Co-authored-by: MervinPraison <[email protected]>
- _extract_llm_response_content now inspects message.refusal (carried
independently of finish_reason) and warns without logging refusal text
- async chat_history test now asserts result == "" and an empty assistant
message, closing gaps flagged in review
Co-authored-by: Mervin Praison <[email protected]>
The streaming auto-detect block in _chat_completion caught every
non-LLMError exception and fell back to a non-streaming retry. Tool
failures during the streaming attempt were therefore run again by the
fallback, executing the tool twice and potentially masking the original
typed failure. Re-raise ToolExecutionError before the generic fallback,
mirroring the guard in the main completion block.
Also tighten the regression tests to assert the failing tool actually
executed (the tool executor retries a failing tool, so every attempt is
verified to target the same recipient).
Co-authored-by: Mervin Praison <[email protected]>
_extract_llm_response_content ended in return str(response), reached whenever
a well-formed response carried no content and no tool_calls (content filter,
refusal, or finish_reason=length with zero output tokens). achat() used this,
so the user's answer became the raw ChatCompletion repr, persisted into
chat_history and replayed to the model.
Now a cleanly-parsed-but-empty message returns "" (matching the sync path),
logging a warning when finish_reason is unexpected. str(response) is reserved
for genuinely unparseable responses where the repr is a diagnostic.
Co-authored-by: MervinPraison <[email protected]>
Prefix the unused _agent() tuple element with an underscore to satisfy
Ruff RUF059, as flagged in review.
Co-authored-by: MervinPraison <[email protected]>
The sync reflection handler incremented the retry counter and continued
unconditionally on a parse error, so a persistently unparseable reflection
(e.g. an OpenAI structured-output refusal where message.parsed is None)
looped forever at two LLM calls a turn and chat() never returned. Mirror the
async bound at chat_mixin.py so the loop stops at max_reflect and returns the
un-reflected answer.
Co-authored-by: MervinPraison <[email protected]>
Add an explicit `except ToolExecutionError: raise` guard before the blanket
`except Exception` in `_chat_completion`, mirroring the existing
`BudgetExceededError` escape hatch. Previously a `ToolExecutionError` raised by
the sync tool executor was caught by position and re-labelled as `LLMError`,
causing chat() to return None, the tool's message to be fed to the LLM error
classifier (so a tool error resembling a rate limit re-drove the model with no
tool result), and confident answers generated with no tool result.
Co-authored-by: MervinPraison <[email protected]>
- Resolve RLIMIT_* via getattr so POSIX platforms missing a constant skip
that cap instead of raising AttributeError before subprocess launch
- Add RLIMIT_CPU (CPU-seconds from timeout) so CPU-bound sandbox code is
stopped by the kernel rather than only the wall-clock timeout
- Check cancel token before AND after rate-limiter acquire in both sync
chat() and async achat() backend branches, so pre-cancelled requests do
not block on the limiter or consume capacity
Co-authored-by: Mervin Praison <[email protected]>
The overflow pointer advertises read_file/grep on the spilled artifact, but
those tools reject out-of-workspace paths. When PRAISONAI_TOOL_OUTPUT_DIR is
unset, spill into a workspace-local .praisonai_tool_output dir so the omitted
output stays retrievable (fixes Greptile P1 on #4247).
Co-authored-by: Mervin Praison <[email protected]>
- Rewrite success path now surfaces the "Applied N changes" receipt that
sg writes to stderr, instead of reporting the failure value
"No changes made" after a real, destructive rewrite.
- Confine path/rule_file to the workspace via path_safety.resolve_within_root.
- Add a `--` argv terminator so a dash-leading path is never parsed as a flag.
- Bound search/rewrite/scan output via _output_overflow.bounded_with_pointer.
Co-authored-by: MervinPraison <[email protected]>
1. Sandbox ResourceLimits (memory/CPU/process/fd/disk caps) are now applied
via setrlimit in a POSIX preexec_fn in _execute_code_sandboxed, instead of
only honouring the wall-clock timeout. Non-POSIX platforms log a warning.
2. Sync chat()'s managed-backend branch now applies the rate limiter and
cooperative cancellation check before delegating, matching achat().
3. _format_tools_for_litellm now imports the canonical GEMINI_INTERNAL_TOOLS
constant instead of a hand-duplicated set.
Co-authored-by: Mervin Praison <[email protected]>
The malformed-JSON cases in test_tool_call_parsing encoded the old buggy
behaviour (args -> {}), which silently ran tools with wrong arguments and
reported success. Defect 1 of #4241 replaces {} with a distinct
_TOOL_ARGUMENTS_PARSE_FAILED sentinel. Update the test to assert the
sentinel (not weaken it) so it keeps guarding that malformed args are
surfaced as retryable errors instead of dispatched.
Co-authored-by: Mervin Praison <[email protected]>
The new sanitise tests embedded realistic secret-shaped literals (Stripe
sk_live_/sk_test_ keys, an AWS-style secret value) as fixtures, which
GitGuardian flagged as hardcoded secrets and blocked CI. Construct those
fixtures by concatenation at runtime so no scannable secret literal lives
in source, while the redaction regexes are still exercised against a
matching string. No change to what the tests assert.
Co-authored-by: Mervin Praison <[email protected]>
The hard-limit check and failure-path fallback in _apply_context_management
counted only message-history tokens. A large system prompt or tool schema
could push the request over the model window while the history alone stayed
under 95%, so truncation was skipped and an over-limit request was sent.
Both paths now add system-prompt + tool-schema tokens via a new
_estimate_request_overhead_tokens helper, and the emergency target reserves
that overhead so the whole request lands near 80% of the window. Adds
regression tests covering the fallback with an oversized system prompt.
Addresses CodeRabbit and Greptile review on PR #4242.
Co-authored-by: Mervin Praison <[email protected]>
os.replace(tmp, out_path) clobbers a symlink itself, leaving its target
holding the stale corpus. Resolve the final-path symlink to its real
target before creating the temp file and replacing, so generate/dedup
update the file consumers read through the link. Adds a regression test.
Co-authored-by: Mervin Praison <[email protected]>
Defect #1: a truncated/invalid tool-call argument string no longer executes
the tool with {} and reports success. _parse_tool_call_arguments now returns a
distinct sentinel on JSON parse failure (kept separate from {} = "no args"),
and every tool-execution site emits a retryable tool-error message instead of
dispatching. Covers sync/async, streaming, batched and Responses-API paths.
Defect #2: a temperature configured via Agent(llm={'temperature': ...}) now
actually reaches the request. Public entry points default temperature to None
and _build_completion_params resolves it from self.temperature once; chat/achat
and the internal completion helpers default to None so the configured value is
no longer overridden by a hardcoded 1.0. Unset temperature is omitted so the
provider default applies rather than sending an explicit None.
Co-authored-by: MervinPraison <[email protected]>
- eval/grader.py + judge.py: passing now requires a parsed numeric SCORE
(score_parsed), so a reasoning-only response can no longer fabricate a
passing 5.0 against a low threshold. Multi-line REASONING is captured.
- crawl4ai_tools.py: crawl_many preserves input->output positional order for
mixed safe/blocked batches instead of hoisting blocked entries to the front.
- gateway.py: _force_kill_process polls until the PID is confirmed gone before
returning True, so the PID lock is not released while a process may survive.
- test_grader.py: assert fail-closed (1.0) for an unparseable score.
Co-authored-by: Mervin Praison <[email protected]>
Address reviewer findings on #4236:
- Route direct RuntimeConfig(runtime=...) through resolve_runtime so a
preferred_runtime typo raises instead of silently dropping capabilities.
- resolve_runtime returns a normalised copy of a RuntimeConfig instead of
mutating the caller's object.
- canonical_runtime_name passes the full alias set to the error builder so a
close typo (e.g. "reducd") suggests the matched alias.
- Rename knowledge_qdrant.py -> knowledge_chroma.py (now demonstrates Chroma)
and restore qdrant_wow.py as a genuine Qdrant adapter example that skips
cleanly, matching filenames to content.
- Add tests: no-mutation, typo suggestion, Agent-level normalisation + typo.
Co-authored-by: Mervin Praison <[email protected]>
mkstemp creates the temp file 0600 and os.replace would make that the
final mode, stripping group/other read that a plain open(..., "w") would
grant via umask and locking shared-corpus consumers out. Restore the
destination's existing mode when overwriting, else 0666 & ~umask.
Applies to both generate and dedup; adds two regression tests.
Co-authored-by: Mervin Praison <[email protected]>
- run --continue: restore chat history by position instead of a content-based
filter, so repeated turns (e.g. a bare "yes" confirmation) are no longer
silently dropped; _auto_save_last_index tracks the full restored length.
- session share / export redaction: mask sk_live_/sk_test_ Stripe keys, anchor
the key=value rule on keys that *contain* a secret word (AWS_SECRET_ACCESS_KEY,
STRIPE_SECRET_KEY), and mask secret values whole so a value containing '/' is
not half-masked by the path regex.
- session share now defaults --redact-level to strict, since it publishes a
transcript for wider distribution.
Co-authored-by: MervinPraison <[email protected]>
Address reviewer findings on #4234 (issue #4228):
- agent.py: use `is None` (not falsiness) so an explicit empty permissions
policy (`permissions={}`) owns denial instead of inheriting default denials.
- tool_execution.py: normalize argument keys (strip trailing '=') before
build_permission_target so a malformed `command=` kwarg cannot evade a
scoped deny that only normalizes after the gate.
- tool_execution.py: re-run the deny gate against `decision.modified_args` in
both sync and async paths so an approval backend cannot rewrite allowed args
into a denied command; BYPASS still opts out.
- tests: add regression coverage for all three.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Covers the #4227 failure mode directly (member propagation, not just the
container field) per CodeRabbit review, without a live LLM call.
Co-authored-by: Mervin Praison <[email protected]>
ContextManager built one union kwargs dict and passed it to every optimizer,
but only SmartOptimizer accepted that signature. The other six raised
TypeError, which chat_mixin swallowed with a blanket except, disabling context
management entirely — including the emergency hard-limit truncation.
- get_optimizer now filters kwargs to each optimizer's constructor signature
(single choke point; fixes all six strategies without touching call sites).
- chat_mixin._apply_context_management falls back to emergency truncation on
failure instead of returning the unchanged, over-budget history.
- Add regression tests covering every strategy.
Co-authored-by: MervinPraison <[email protected]>
Four HIGH-severity silent-data-loss bugs in praisonai-train:
- train llm <dataset>: forward the path as --dataset (the option the train
branch reads) instead of a bare positional the legacy dispatcher drops,
which silently trained on yahma/alpaca-cleaned.
- generate: write to a temp file and os.replace only when rows are produced
(mirrors dedup), so an all-failures run no longer truncates an existing
corpus to zero bytes.
- Ollama export: dedent the Modelfile TEMPLATE so continuation lines sit at
column 0 and the served prompt format matches the trained one.
- agent training: a genuine agent failure now re-raises instead of being
captured as "Error: ..." output, graded as training data, and reported as
success with exit 0.
Adds regression tests for all four.
Co-authored-by: MervinPraison <[email protected]>
The scheduler monitor's total-deadline watchdog was a no-op for
Connection: close responses. http.client.getresponse() calls close()
for close-delimited replies, nulling connection.sock, so when the
watchdog fired on exactly the responses that can hang forever there was
no socket left to shut down. A page dripping one byte per socket window
stalled the whole sequential scheduler tick while holding its lease.
Retain a separate raw-socket handle the close() path does not clear and
fall back to it in _abort_connection; clear it after each probe so the
fd is not held past the (per-probe) connection.
Co-authored-by: MervinPraison <[email protected]>
- #4195: grader.py/judge.py now parse markdown-bolded labels and fail closed
(score 1.0) instead of fabricating a mid-range 5.0 that could pass a threshold
- #4192: gateway stop distinguishes PermissionError from a dead process and
keeps a live cross-uid holder's lock
- #4196: telemetry re-entrancy guard uses a ContextVar so concurrent executions
on one agent are counted independently
- #4189: crawl4ai_tools now validates every URL entry point via is_safe_http_url,
and mentions.py re-validates each redirect hop instead of only the first
Co-authored-by: MervinPraison <[email protected]>
(a) The code generator advertised a hardcoded memory capability list that
still named removed backends (redis/postgres/qdrant), so generated agent
code raised before the API. Derive supports_presets/supports_url_schemes
from the live resolver registries (MEMORY_PRESETS, MEMORY_URL_SCHEMES) so
the generator can never teach a dead value. Update the four shipped
examples that crashed at the config boundary to use shipped backends.
(b) runtime= stored any string verbatim, silently dropping nine of twelve
capabilities on a typo. Normalise through canonical_runtime_name() so
spelling variants (NATIVE, " native ", Native) all map to the native
matrix, and raise on a close typo (nativ -> "Did you mean native?").
A genuinely unknown plugin runtime name is still accepted and falls back
to the reduced harness via the runtime registry, not a closed literal.
Co-authored-by: MervinPraison <[email protected]>
(a) The ApprovalConfig and dict approval branches left _perm_deny at its
empty init value, making a config object a WEAKER posture than passing
nothing (ApprovalConfig(timeout=30) silently dropped all 8 default
denials). They now fall back to the env-driven default deny set when no
declarative permissions policy is supplied, so configuring approval never
removes the default denials. PRAISONAI_TOOL_SAFETY=off still fully bypasses.
(b) The PermissionManager deny gate only asked with the tool *name*, so
argument-level deny rules (e.g. bash:rm *) never fired. _check_permission_manager_deny
now also builds the argument-scoped target via build_permission_target and
checks it, so an argument-scoped rule can narrow an allowed shell tool.
Name-level rules keep their all-or-nothing behaviour.
Co-authored-by: MervinPraison <[email protected]>
Three closed defects still reproduced on main, each shielded by a test that
passed on the broken behaviour.
1. Agent.as_tool() returned a success string without running the sub-agent.
ContextPolicy.NONE discards history, so no prompt was ever derived. The
generated tool now advertises a `task` parameter and passes it verbatim as
the sub-agent's prompt.
2. `--type openai-compat` was refused though listed as registered. The endpoint
registry loads under both `praisonai_code.*` and the `praisonai.cli.features`
shim namespace; the relative `from ..._wrapper_bridge` resolved to the
non-existent `praisonai._wrapper_bridge` under the shim. Made it absolute.
3. `from praisonaiagents import db` (and `obs`) yielded a non-callable module,
because a real submodule shadows the package `__getattr__`. The submodules
now swap their `__class__` to a callable ModuleType subclass that proxies to
the lazy singleton, so `db(...)`/`obs(...)` and `db.PraisonDB` both work.
Tests: added a behavioural as_tool test asserting the sub-agent call, a
resolve() assertion under the shim namespace, an obs-callable test, and removed
the bug-detecting workaround from the db test so its assertion can fail without
the fix. Each new test was confirmed to fail against the unfixed tree.
Co-authored-by: MervinPraison <[email protected]>
The containers called resolve_model_alias (alias rule only) while the seven
media/specialist agents call resolve_model_name (alias rule + LLMConfig
unwrapping). AgentTeam/AgentFlow therefore pushed the raw LLMConfig into every
member via _apply_default_llm, and the member's chat() failed silently with
"'LLMConfig' object has no attribute 'lower'", returning None.
Switch both container sites to resolve_model_name and widen the regression
test's parametrize from UNWRAPPING to ALL.
Co-authored-by: MervinPraison <[email protected]>
Evict the 'Task' key from _lazy_cache before spawning threads so the
concurrent access hits the double-checked locking path in
_lazy.lazy_import instead of the unlocked cache fast path. Addresses
Greptile P2: prior test could read an already-cached attribute after
suite collection, letting concurrent first-load regressions go
undetected.
Co-authored-by: Mervin Praison <[email protected]>
Remove dead _lazy_cache_local threading.local and _get_lazy_cache()
helper from praisonaiagents/__init__.py. The runtime lazy-loader only
uses the plain _lazy_cache dict (guarded by the lock in _lazy.py);
the thread-local cache had no runtime consumer.
Repoint TestLazyCacheThreadSafety at the real lazy-loading path
(concurrent access of praisonaiagents.Task resolving to one cached
object) instead of the removed self-referential helper.
Co-authored-by: MervinPraison <[email protected]>
- AuthProfile.credential_id: stable, non-secret (hashed) identity keyed on
provider+api_key+base_url so coordinator benches track the credential, not
the local profile label. Prevents same-name collisions ("default") benching
unrelated keys and different names on the same key breaking propagation.
- mark_success: only clear the shared bench when it is not newer than the
cooldown being recovered from, so a stale in-flight success cannot clobber a
newer fleet-wide bench set by a concurrent failure.
- All three coordinator call sites now use credential_id consistently.
- Tests: add same-name-distinct-keys isolation, stale-success guard, and
own-bench clear coverage; update existing tests to key on credential_id.
Co-authored-by: Mervin Praison <[email protected]>
- state(): catch TypeError so a valid-JSON sentinel with a non-numeric `at`
(e.g. a list) still fails safe engaged instead of raising.
- engage(): commit via tempfile.mkstemp in the sentinel dir + fsync file and
parent dir, closing a predictable-tmp symlink pre-creation vector and making
an engaged brake durable across an abrupt crash; cleanup tmp on failure.
- bot GatewayServerSchema: declare `control` and `turn_lock` so the documented
`gateway.control` YAML block loads under extra="forbid".
- tests: drop hardcoded /tmp path (S108) and add structured-`at` fail-safe case.
Skipped (scope/lightweight mandate): async FileEmergencyStop variants (no live
async admission consumer yet; is_engaged is a fast local stat/read) and
agent.start() agentic tests (this PR ships the core contract + config only, no
admission wiring to exercise via the LLM).
Co-authored-by: Mervin Praison <[email protected]>
Adds a pure, dependency-free QuotaCoordinatorProtocol + QuotaCoordinatorConfig
and an in-memory LocalQuotaCoordinator in core (praisonaiagents/llm/quota.py).
FailoverManager now consults an optional coordinator so a credential benched
by any replica (429/auth/billing cooldown) is skipped by all replicas sharing
the same backend. Defaults to the local in-memory coordinator, so single-replica
/ no-backend deployments behave exactly as before with no new dependency and no
hot-path change. All coordinator calls are fail-open (never wedge failover) and
benches carry TTLs that self-expire.
Co-authored-by: MervinPraison <[email protected]>
Introduce a pure, dependency-free EmergencyStopProtocol in core gateway
plus a zero-cost NullEmergencyStop default and a durable, fail-safe
FileEmergencyStop sentinel. Wire an EmergencyStopConfig (gateway.control)
into GatewayConfig defaulting to backend "off" so behaviour is unchanged.
This is the shared contract every new-work admission seam can consult to
halt new runs while preserving in-flight ones; a corrupt/unreadable
sentinel fails safe (engaged).
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: MervinPraison <[email protected]>
- Only genuine booleans count as a restart_safe declaration; malformed values
(e.g. the string "False") are treated as unsafe instead of coerced truthy.
- Empty tool names fail closed rather than falling through to the read-only
heuristic which returns True for "".
- Declaration lookup now compares canonicalised names so an explicit
restart_safe declaration survives execute_tool's case/separator repair.
Co-authored-by: Mervin Praison <[email protected]>
CodeRabbit: session.persist:true but a failed persistent-store init degrades
to in-memory (self._session_store is None). The old config-based default still
enabled ExecutionConfig(durable=True), journalling against no durable store.
Resolve the auto-default from the instantiated self._session_store instead;
explicit gateway.durable_runs still wins. Adds a regression test.
Co-authored-by: Mervin Praison <[email protected]>
Add a `restart_safe` declaration to the tool contract (@tool / BaseTool /
FunctionTool) and honour it during durable resume. An in-flight tool call
(journalled tool_call with no tool_result at the crash) is now re-run only
when the tool resolves as restart-safe (explicit declaration, else the
read-only name heuristic); effectful/undeclared tools fail closed with a
typed NotSafelyResumable outcome instead of silently re-executing, removing
the duplicated-side-effect risk on crash recovery.
Co-authored-by: MervinPraison <[email protected]>
Auto-enable durable (journal-backed) gateway runs when a durable session
store is present (the default), so a restart mid-turn replays completed
model/tool steps instead of re-executing side-effecting tools or re-billing
the model. Zero-overhead escape hatches: explicit `gateway.durable_runs:
false` or `gateway.reliability: "off"`, and sessions with `persist: false`.
An explicit `durable_runs` and per-agent `durable` still win.
Co-authored-by: MervinPraison <[email protected]>
- firestore.hdel: count only fields actually present instead of len(fields)
- dynamodb.hset/hdel: migrate legacy JSON-string hashes into native map so
existing fields stay visible and legacy deletions are effective; count actual
- recipe/serve.py: drain SSE queue + stop event on consumer cancellation so the
producer worker thread unblocks instead of leaking the executor
Co-authored-by: Mervin Praison <[email protected]>
- integrations/base.py: reap the child in a finally block in execute_async
and execute_async_with_stderr so caller cancellation (CancelledError) no
longer leaks a running subprocess plus its stdout/stderr pipes.
- recipe/serve.py: route sync recipe.* calls through asyncio.to_thread and
bridge the sync run_stream generator to an asyncio.Queue on a worker
thread so a single recipe run no longer blocks the whole event loop.
- persistence/state/firestore.py: scope credentials to the client instead
of mutating process-wide os.environ, and use atomic field-level merge /
DELETE_FIELD for hset/hdel to avoid lost concurrent updates.
- persistence/state/dynamodb.py: use atomic UpdateExpression on a native
map attribute for hset/hdel to avoid non-atomic read-modify-write races.
Co-authored-by: MervinPraison <[email protected]>
- handoff.py: make seeded handoff context invocation-scoped via a
restore-on-exit context manager so target chat_history no longer leaks
across sequential/concurrent handoffs or grows unbounded (CodeRabbit/Greptile P1)
- handoff.py: exclude the exact message folded into the prompt (by index)
from seeded history instead of always dropping the final list item
- memory.py: get_context returns "" for empty/None query (no LIKE "%%"
unrestricted match) and propagates the effective user_id for user-scoped memories
- tool_execution.py: resolve explicit idempotent flag on process-global
registry tools before falling back to the shared name registries
Co-authored-by: Mervin Praison <[email protected]>
Bug #1 — retrieved memory never reached the prompt:
- build_context_for_task defaulted include_in_output to a DEBUG-only gate, so
Agent(memory=True) retrieved hits but returned "" under normal logging. Default
to True (the method's primary purpose is feeding memory into the prompt).
- Added Memory.get_context() so the non-cache path (get_memory_context) works;
previously only FileMemory had it, so hasattr(...) was always False.
Bug #2 — timed-out tool auto-retried while still running:
- future.cancel() is a no-op once a worker starts, so the tool body keeps running.
Added _is_tool_idempotent() and gated the _outer_timeout retry on it, reusing
the escalation loop_guard read-only/mutating registry plus an optional per-tool
`idempotent` flag. Mutating tools now surface the timeout once instead of
duplicating side effects.
Bug #3 — HandoffConfig context policy computed then discarded:
- _prepare_context() result was thrown away; the target only got the prompt string.
Added _seed_target_history() and threaded the filtered messages through
_execute_with_runtime_resolution(_async) for sync/async Handoff and TypedHandoff.
Co-authored-by: Mervin Praison <[email protected]>
- llm/llm.py: add response.reasoning_summary_text.delta branch to
_stream_responses_api_async so async streaming emits reasoning-summary
deltas, matching the sync path.
- _warning_patch.py: replace over-broad bare "Expected" substring with
precise "fields but got" so unrelated third-party/user warnings are no
longer swallowed process-wide.
Co-authored-by: MervinPraison <[email protected]>
Address the two P1 findings on the inbound webhook dedup durability change
(#4208):
- SQLite backend was unreachable: _get_hook_idem_store read a GatewayConfig
field that no config path populates. Capture hooks.idempotency.store_backend
in _apply_hooks_from_config (the only path that sees the raw hooks dict),
supporting both the mapping-shaped hooks.idempotency and a sibling
hooks_idempotency key, and rebuild the store on a hot-reload backend flip.
- In-flight claims survived a crash: a process exit between reserve and
record/release left a durable inflight row that deduplicated the provider's
post-restart retry for the full TTL. Add a bounded inflight lease; a stale
inflight reservation is reclaimed on reserve so the retry re-runs, while
recorded keys keep deduplicating until TTL.
Adds regression tests for config wiring (default/sqlite/sibling/hot-reload) and
crash reclaim (stale inflight reclaimed; recorded not reclaimed).
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Add a core IdempotencyStoreProtocol (reserve/record/release) with a bounded
in-memory default, and a durable SQLite backend in praisonai-bot. The gateway's
inbound hook handler now delegates dedup to a swappable store selected via
hooks.idempotency.store_backend ("memory" default; "sqlite" for restart/
multi-replica durability), so a provider redelivery after a restart no longer
starts a duplicate agent run. Mirrors the existing ingress-journal/outbound-
queue durability.
Co-authored-by: MervinPraison <[email protected]>
Register MODEL_FALLBACK_STREAM, RETRY_STREAM, TODO_STREAM, and
TOOL_RESULT_STREAM in the streaming capability handshake and the
session-history allowlist so clients can discover these events and
so they receive a cursor for reconnect/resume replay (fixes gap
flagged by CodeRabbit/Greptile reviews on #4206).
Co-authored-by: Mervin Praison <[email protected]>
The WebSocket gateway relay dropped four StreamEventTypes the SDK already
emits (MODEL_FALLBACK, RETRY, TODO_UPDATED, TOOL_CALL_RESULT), causing live
clients to see an unexplained token-stream stall during fallback/backoff.
- Add additive EventType members (MODEL_FALLBACK_STREAM, RETRY_STREAM,
TODO_STREAM, TOOL_RESULT_STREAM) to gateway protocol enum
- Map the four events through the existing cross-thread relay send path,
carrying their existing metadata untouched
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
The smoke job installs praisonai-mcp==0.0.15 as editable, but the wrapper's
`praisonai-mcp>=0.1.0` constraint then made pip fetch the stale PyPI wheel
praisonai_mcp-0.1.1 (no `cli` submodule), clobbering the editable install and
breaking `praisonai_mcp.cli` (test_mcp_list). Bumping the local package to
0.1.2 satisfies the constraint so the editable install is retained.
Co-authored-by: Mervin Praison <[email protected]>
- schedules_runner: pass timeout=None to run_sync_or_offload so long
scheduled agent/command runs are not cancelled by the bridge's default
300s timeout after ScheduleLoop has already claimed the occurrence
(would silently drop one-shot / long-interval work). Restores the prior
unbounded asyncio.run(...) behaviour. (Greptile P1)
- security/audit: close the file handle best-effort in the rotation
OSError branch before dropping the reference, so an fstat/close failure
cannot leak the descriptor. (Greptile P2)
Co-authored-by: Mervin Praison <[email protected]>
- scheduler on_trigger now uses run_sync_or_offload instead of asyncio.run,
so scheduled ticks share the async bridge / per-loop connection pools
- AuditLogHook reopens its handle when the log path is rotated (mv/rm),
preventing silent loss of audit records after logrotate
- LazyCache memoises every terminal loader failure (not just ImportError),
while letting KeyboardInterrupt/SystemExit propagate, avoiding hot-path
cache stampedes on broken optional deps
Co-authored-by: MervinPraison <[email protected]>
Addresses reviewer P1 findings on the Memory batch-commit path:
- Deadlock: commit_memory_batch no longer holds the non-reentrant
_write_lock while calling store_short_term/store_long_term (which
reacquire it). Writes now dispatch outside the lock.
- Atomicity/cancellation: both sync and async batch commits route each
write through _AtomicCommitGuard.commit(deadline=...) so cancelled or
past-deadline facts are skipped; acommit offloads blocking stores via
asyncio.to_thread instead of blocking the event loop.
- Path traversal: default sqlite/chroma store paths derive a
filesystem-safe suffix from user_id, rejecting separators/parent refs
and sanitizing other characters (bare stores keep legacy defaults).
Co-authored-by: Mervin Praison <[email protected]>
- Thread the per-agent mem_user_id into every Memory(...) construction path in
agent.py (string and dict forms) via config.setdefault, and scope the default
sqlite/chroma paths and collection_name by user_id in Memory so two agents in
one process no longer silently share one store. Bare stores keep legacy
defaults for backward compatibility.
- Add commit_memory_batch/acommit_memory_batch to the Memory class so the
pre-compaction fact flush durably commits extracted facts for
sqlite/chroma/mongodb/mem0 instead of raising and being swallowed.
- Propagate a nested on_error="stop" stop signal out of Parallel: _execute_parallel
now returns a stop flag, the nested dispatcher forwards it, and the top-level
loop halts like Route/Loop/Repeat/If. Keep parallel_outputs index-aligned with
the branch list on partial_ok failures.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: MervinPraison <[email protected]>
The URL monitor's response.read() bounded bytes and per-socket waits but
had no total deadline, so a slow drip-feed endpoint could keep the
synchronous read alive within each socket window and stall the sequential
scheduler tick, delaying other due jobs. Read the body in bounded chunks
and check an absolute deadline between reads so a slow response fails the
probe at the monitor timeout instead of blocking progress.
Co-authored-by: Mervin Praison <[email protected]>
The existing collision guard only ensured no two keys collapse to the same
canonical form. It did not catch a single non-canonical key (e.g. 'full-auto'),
which validation would accept but the direct dict.get(canonical_preset_key(...))
lookup would miss, silently falling back to the disabled default. Add an
invariant test enforcing key == canonical_preset_key(key) for all four
resolver preset dicts. (addresses Greptile review)
Co-authored-by: Mervin Praison <[email protected]>
Validation normalised strip().lower().replace('-','_') while the four
resolvers did a raw dict .get(), so blessed spellings like
autonomy='full-auto' or context='sliding-window' were accepted then
silently ran with the feature off.
Add canonical_preset_key() in parse_utils and route both the validator
and the context/autonomy/output/execution resolvers through it. Replace
the vacuous test_normalized_preset_accepted assertion with the
resolution checks its own comment described.
Co-authored-by: MervinPraison <[email protected]>
_maybe_deliver_failure only recorded the negative outcome, leaving
JobResult.delivered False even when the failure summary was delivered
successfully — so monitoring reported a delivered notification as
undelivered (Greptile P1 on PR #4198). Set result.delivered = True on
the success branch and add regression tests for both the delivered and
failed failure-summary paths.
Co-authored-by: Mervin Praison <[email protected]>
_deliver_scheduled_result returned None on every path, so the executor
treated 'the handler did not raise' as success — a routing failure was
recorded delivered=True with delivery_error=None next to a logged
'Failed to deliver'. Return a bool from the gateway handler, propagate it
through _dispatch_delivery, and key delivered/delivery_error off it at the
three executor call sites plus the failure-summary path.
Co-authored-by: MervinPraison <[email protected]>
Snapshot and restore the pre-existing module entry in the vendored-fallback
import helper so the forced standalone re-import cannot leak the fallback
PluginRegistry into later tests expecting the bridged canonical class.
Addresses CodeRabbit review on #4184.
Co-authored-by: Mervin Praison <[email protected]>
vendored fallback copies used when praisonai-sandbox / praisonai-deploy are
installed standalone did not get it. Apply the same guard so an installed
distribution can never replace a built-in loader via entry-point discovery.
Add a class-parametrised test that forces the standalone fallback import path,
proving each vendored copy is protected (the previous test only exercised the
canonical class through varied group-name strings).
Co-authored-by: MervinPraison <[email protected]>
EndpointProviderRegistry.default() caches a per-class singleton whose
entry-point discovery runs once at construction. cmd_invoke resolves
providers through that cache, so under the CI root shard (-n 2 --dist
loadfile) a singleton built by an earlier test on the same worker — before
this file publishes the `acme` plugin — never sees it, and invoke falls back
to the recipe HTTP path (assert http == [] => assert 2 == 0). Evict the
cached singletons in the `published` fixture before and after each case so
the plugin is rediscovered and no poisoned instance leaks forward.
Test-only change in the praisonai wrapper; no production or praisonai-agents
code touched. Strengthens isolation rather than weakening any assertion.
Co-authored-by: Mervin Praison <[email protected]>
Wrapping only chat() dropped all execution telemetry for start(stream=True)
(-> _start_stream) and backend-backed run()/start() (-> _delegate_to_backend),
neither of which funnels through chat(). Re-instrument run/start/chat behind a
per-agent re-entrancy flag so the outermost call records exactly one execution,
preserving single-count for run()->chat() while covering stream/backend paths.
Co-authored-by: Mervin Praison <[email protected]>
The full-suite CI failure (`assert 2 == 0`, "Unknown provider type: acme")
was a test-isolation bug: the CLI handler's cmd_invoke resolves
EndpointProviderRegistry via the `praisonai.cli.features._endpoint_registry`
shim namespace, a distinct class object from the `praisonai_code...` one the
test imports. Their default() singletons are cached independently, so an
earlier full-suite test that warmed the handler's cache left it stale and the
monkeypatched entry points never reached it. Reset the cached _default_instance
on both class objects so discovery re-runs under the patched entry points.
Unrelated to PR #4187's session-docs changes; fixes the pre-existing flake.
Co-authored-by: Mervin Praison <[email protected]>
- token_collector: total_tokens no longer double-counts cached/reasoning/audio
tokens (they are subsets of input/output, not additional buckets)
- cost_utils: replace loose substring matching with longest-key exact/prefix
match so gpt-4o-mini is no longer billed at gpt-4o rates (16.7x); strip
provider prefixes; exclude "default" from matching
- performance_monitor: consult shared telemetry state live so a later
disable_telemetry() actually stops the import-time global monitor
- telemetry.__init__: atexit handler no longer resurrects a shut-down/opted-out
telemetry instance at interpreter exit
- integration: instrument only chat()/execute_tool(); run()/start() delegate to
chat() so wrapping them double-counted executions and errors
- telemetry.flush: only zero counters after a successful send
Co-authored-by: MervinPraison <[email protected]>
- _execute_loop/route/repeat/if now return a `stop` flag so a nested
on_error="stop" step halts the enclosing workflow instead of only its
own pattern iteration. Both nested dispatch and top-level _run_impl
honor the propagated signal.
- Parallel fail_fast/fail_all no longer `raise ... from <str>` (which
raised TypeError and masked the real failure); the string branch error
is preserved in WorkflowStepError.errors and only real exceptions chain.
- Added regression tests: nested-stop halts outer workflow, and parallel
fail_fast reports failed without TypeError.
Co-authored-by: Mervin Praison <[email protected]>
Parse safety judge responses tolerantly (markdown bolding, bullets, case)
and fail closed when nothing usable is parsed. Previously a bolded field
label - the default output style of most models - matched nothing and the
verdict silently fell through to 10.0/10 SAFE, even on a detected severe
violation. An unparsed verdict is now treated as UNSAFE (1.0), matching the
existing exception handler in evaluate_safety.
Co-authored-by: MervinPraison <[email protected]>
- _is_process_running: treat PermissionError as running so a gateway owned
by another uid is not reported dead and its lock deleted, admitting a
second poller for the same bot token.
- Record a create_time fingerprint in the lock so a recycled PID cannot be
mistaken for the original gateway; verified before stop/refuse decisions.
- check_port_available: use net_connections with a connections() fallback and
a broad except so the port-collision diagnostic works on psutil 7 instead
of raising 'invalid attr name connections'.
Co-authored-by: MervinPraison <[email protected]>
Previously is_safe_http_url returned True for any allowlisted hostname before
resolving/classifying its addresses, so SEARXNG_URL_ALLOWLIST=169.254.169.254
could reach the cloud metadata endpoint. Now every address is classified and an
allowlisted host only bypasses the loopback class; private, link-local,
multicast and unspecified addresses stay blocked. Docstring corrected to match.
Co-authored-by: Mervin Praison <[email protected]>
Nested patterns (loop/parallel/when/route/repeat/if) routed failing steps
through _apply_step_policies, which folded f"Error: {e}" into the step output
and never consulted on_error. Wrapping a pipeline in any pattern therefore lost
failure detection: the run reported status="completed" and the next step
consumed the exception text as input.
_apply_step_policies now returns (output, step_error) instead of folding the
error into output. _execute_single_step_internal applies the same
on_error/status logic the top-level _run_impl already uses: it marks the run
failed, signals a stop when on_error="stop", and never hands the exception text
forward. Pattern executors honor the stop signal, and Parallel on_failure modes
fire again since the branch failure is now surfaced.
Co-authored-by: MervinPraison <[email protected]>
The shared is_safe_http_url unconditionally allowlisted loopback and
consulted it before the IP-class checks, re-opening web_crawl to
127.0.0.1/localhost/::1. Split the allowlist into an explicit per-caller
opt-in consulted after the IP checks. validate_searxng_url opts into
loopback (SearXNG is self-hosted); the crawler passes none.
Co-authored-by: MervinPraison <[email protected]>
The restored TOP_LEVEL_KWARG regex only balanced one level of parens, so
a top-level rejected kwarg after a two-level nested call
(Agent(memory=MemoryConfig(db=db(...)), session_id=...)) escaped the guard,
re-opening the #4178 regression (greptile). Replace the regex with a
depth-aware scanner that attributes each kwarg to its enclosing call at any
nesting depth, and skips string literals and comments so dict keys
(memory={"session_id": ...}) and comments (# session_id = resume) are not
false positives. Add regression tests for the nested-call, dict-key, comment
and prose cases.
Co-authored-by: Mervin Praison <[email protected]>
Addresses Greptile's P2 finding on this PR plus one gap found reviewing the
diff independently.
- pattern-d-platform.md: the note added in the previous commit corrected the
platform agent roster path, but line 25 still listed it as /api/v1/agents,
which the same note defines as the unrelated endpoint served by
`praisonai serve agents`. A reader following the numbered list would have
integrated against the wrong service. Also softened "Three registries may
coexist" — a full install has more than three; the three listed are the ones
relevant to agent_id correlation.
- auth/__init__.py: the module docstring said implementations "live in the
platform package" without saying where that is, which is now ambiguous since
the package left this repository. Points at the separate repo and, more
usefully, states first that you can implement the protocols against your own
store. This matches the change made to protocols.py in the previous commit.
src/praisonai-agents/tests/unit/auth/ passes (33 tests).
Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_014ZfTXTzdudKb4oswNSHpHw
praisonai-platform is extracted to MervinPraison/PraisonAI-Platform, with full
history carried over via git filter-repo.
Why it belongs outside this repo:
- Nothing here imports it. A grep for praisonai_platform across every .py
outside its own directory returns no hits, and no pyproject declares it.
- It is in no CI job. No workflow under .github/ references it — it is absent
from install-monorepo-packages and from pypi-release.yml, which enumerates the
nine tiered packages and notes it is near GitHub's 25-input cap.
- It is absent from ARCHITECTURE.md, which describes a nine-package tiered
model; the platform was a tenth, untiered package with no boundary manifest.
- Separate-repo is the ecosystem norm: PraisonAI-Tools, PraisonAI-Plugins,
PraisonAIUI and Agent-Recipes all live outside and consume praisonaiagents as
a plain versioned PyPI dependency. The platform already did exactly that, and
already carried its own uv.lock.
- Its releases were already documented as an independent semver line.
Changes here:
- Remove src/praisonai-platform/ (9,263 lines).
- SECURITY.md: drop the platform row from supported packages and point
vulnerability reports at the new repository's advisories.
- security-audit.md: the platform is no longer triaged, released or audited
from this runbook. Removes publish steps 13 and 15 and the two table rows so
an agent executing it cannot cd into a directory that no longer exists.
- auth/protocols.py: WorkspaceContextProtocol's example named
PlatformWorkspaceContext, a class no longer in this tree. Renamed to a
generic example and noted where the reference implementation lives. Core
keeps the protocol with no in-tree implementation, which is the documented
design — auth/__init__.py already states that implementations live in the
platform package, and the core tests use local mocks.
- pattern-d-platform.md: kept, since it documents an integration contract
rather than platform internals. Adds a pointer to the new repo and corrects
the agent roster path, which is /api/v1/workspaces/{id}/agents — /api/v1/agents
is a different endpoint served by `praisonai serve agents`.
src/praisonai-agents/tests/unit/auth/ passes (33 tests).
Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_014ZfTXTzdudKb4oswNSHpHw
PR #4179 replaced the textual kwarg guard with an executing one but the
executor is blind to session/__init__.py (documented via an indented
docstring, zero python fences) and to README blocks excluded by
_is_self_contained. The surviving text check only covered _EXAMPLE_FILES,
so the original #4178 bug (a top-level Agent(session_id=...)) could be
reintroduced with the suite green.
- Restore test_docs_do_not_pass_rejected_kwargs_to_agent, widened to cover
DOCS as well as _EXAMPLE_FILES. TOP_LEVEL_KWARG matches only inside
Agent(, so prose mentioning session_id= is not a false positive.
- Add test proving an executor-only guard is blind to a fenceless file.
- Fix session README "Using with DB Adapter" block: import the callable
via `from praisonaiagents.db import db` instead of `from praisonaiagents
import db`, which yields the non-callable module and raised
TypeError: 'module' object is not callable whenever the wrapper was
importable (README.md#3 was green only via importorskip).
Co-authored-by: MervinPraison <[email protected]>
The deprecated entry-point group bypassed #4171's built-in guard because
_discover_legacy_entry_points ran first and called _add_loader
unconditionally. A plugin published under the legacy spelling could thus
replace a built-in, contradicting the docstring. Apply the same built-in
guard to the legacy path.
Co-authored-by: MervinPraison <[email protected]>
One helper resolves the llm=/model= pair everywhere: model= is canonical,
llm= is a deprecated alias, passing both raises TypeError, and LLMConfig is
unwrapped for classes that store a bare model name. Adds model= to CodeAgent,
RealtimeAgent, AgentTeam and AgentFlow.
Co-authored-by: MervinPraison <[email protected]>
The main (3.11) job dropped the plugin `aider` across every registry-backed
surface (fixture tests + entry-point discovery test). The base guard and
production code are correct; the failure is a test-isolation issue that only
surfaces under `pytest -n --dist loadfile` + coverage on CI:
- The entry-point discovery test patched `praisonai_code._registry.entry_points`
by dotted string. Under editable-install + coverage import tracing a
re-imported copy of that module can differ from the one the
`ExternalAgentRegistry` class actually discovers through, leaving the real
path unpatched and silently dropping `aider`. Patch `entry_points` on the
exact base module the class resolves via `__mro__`, and accept `group`
positionally or by keyword.
- The `registered_plugin` fixture now also clears and restores the per-class
`PluginRegistry.default()` cache so no sibling test file sharing the xdist
worker can shadow the registered plugin.
No assertions weakened: built-ins still win over colliding entry points,
plugins can still add new names, and every surface must still agree.
Co-authored-by: Mervin Praison <[email protected]>
Addresses two blind spots greptile flagged in the executing session-doc guard:
- ImportError from our own packages (praisonaiagents/praisonai) now re-raises
instead of being swallowed by the optional-dependency skip, so a doc that
advertises a renamed/removed symbol fails the guard. Optional third-party
deps still skip.
- Blocks dropped by the self-contained filter are now asserted against a known
set of documentation idioms, so a typo/omitted import in an otherwise-complete
example fails a diagnostic test rather than vanishing from execution.
Co-authored-by: Mervin Praison <[email protected]>
The #4127 guard regexed the docs for four hard-coded kwarg names, so
renaming the fixed example's session_id= to sessionid= left it green while
the documented MemoryConfig call raised. Replace the text match with a
primary guard that extracts every ```python fence, keeps the AST
self-contained ones (used - bound - builtins == set()), and execs them with
Agent.start/chat stubbed and PRAISONAI_HOME isolated. It now fails on the
sessionid= reproduction with the exact TypeError, and catches the next
mistake too. Non-hermetic examples opt out via <!-- praisonai: skip=true -->
and wrapper-backed db examples are skipped when praisonai is absent.
Co-authored-by: MervinPraison <[email protected]>
The entry-point shadowing guard is added inside praisonai-code 0.0.64, but the
wrapper floor was praisonai-code>=0.0.64 — the same version number that shipped
without the guard. A pre-fix 0.0.64 install would satisfy >=0.0.64 yet lack the
protection, restoring the shadowing path once the wrapper's local guard was
removed. Bump praisonai-code to 0.0.65 and raise the wrapper floor so the
dependency constraint actually guarantees the fix is present.
Co-authored-by: Mervin Praison <[email protected]>
Add deterministic tests exercising the public execute_tool_async path
(not just the impl) to close the coverage gap CodeRabbit flagged:
- a tool-owned `retryable` field does not drive the async retry loop
(body runs exactly once, field preserved)
- the private `_praison_retryable` control key is not visible on the
async surfaced result
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Extract the tool function name before json.loads so callers (streaming
verbose warning, deferred-media path) report the actual tool name instead
of 'unknown function' on malformed arguments.
Co-authored-by: Mervin Praison <[email protected]>
Relocate praisonaiagents/runtime/example_harness.py (365-line, unreferenced
demonstration module) to examples/runtime/example_harness.py so it no longer
ships in the installed praisonaiagents wheel. Convert its relative imports to
absolute and correct the pre-existing broken TurnRuntimeProtocol import
(runtime.protocols, not runtime.turn_context) so the example runs standalone.
Update the AGENTS.md path reference. No public API or runtime module changes.
Co-authored-by: MervinPraison <[email protected]>
The primary --external-agent execution path (get_integration/execute) called
_catalog() which discarded the too-old-wrapper diagnostic and returned an empty
catalog, producing a misleading "Unknown integration" error on a version-skewed
install (Greptile P1). Add _require_catalog() that raises the upgrade guidance on
the execution path while listing surfaces (help/argparse/UI) keep degrading
quietly. execute() now catches RuntimeError to print the guidance cleanly.
Also fix test hygiene: restore the process-global root logger handlers via
monkeypatch instead of permanently clearing them (CodeRabbit).
Co-authored-by: Mervin Praison <[email protected]>
#4158 patched only ExternalAgentRegistry. The real hole was in the base
PluginRegistry: builtins are registered first and entry points second, so any
installed distribution declaring a built-in name silently replaced it across
all ten registries (openai, docker, aws, ...). Those loaders decide where user
code runs.
Record built-in names once and skip colliding entry points during discovery,
matching the existing BotPlatformRegistry precedent (DEBUG, not WARNING, since
packages legitimately re-declare their own builtins). Runtime register() still
overrides -- deliberate dependency injection. The now-redundant re-assertion in
ExternalAgentRegistry is removed.
Co-authored-by: MervinPraison <[email protected]>
Extract a private _extract_tool_call_name_and_args helper and reuse it in
the non-streaming, streaming, and deferred-media tool-calling paths. Each
call site keeps its own failure handling (tool-role reply vs. yield), so
behaviour is unchanged.
Co-authored-by: MervinPraison <[email protected]>
The retry machinery tagged its own verdict with an un-namespaced `retryable`
key, so a tool whose result legitimately contained `retryable` (common for
HTTP-API wrappers) had its body re-executed up to 3x and the internal verdict
leaked to the model. The sync outer loop separately escalated any returned
error dict of an uncovered type to retryable, re-running the tool body for a
decision it had already made.
- Rename the framework verdict to the private `_praison_retryable` key in the
async impl (exception + timeout branches) and the sync `_execute_tool_impl`
exception flatten, matching the `_outer_timeout` convention from #4133.
- Read and strip `_praison_retryable` in both retry loops so it never reaches
the model and cannot collide with a tool's own `retryable` field.
- Sync outer loop escalates only framework-produced transients
(`_outer_timeout`, `circuit_open`, or a flattened raised exception via
`_praison_retryable`, and only when the type is not already re-driven by the
inner loop). A plain returned error dict now runs exactly once.
- Update existing parity tests to the new key and add regression tests proving
a tool's own `retryable` field does not drive the loop and the verdict is not
visible to the model.
Co-authored-by: MervinPraison <[email protected]>
- list_external_agents() now derives from external_agent_catalog() so argparse
--help choices can never advertise a plugin the handler then rejects
- registry uses a module logger instead of the root logger (no basicConfig on
the embedding application)
- praisonai-code distinguishes an absent wrapper from a too-old wrapper: a
mixed-version install now reports "too old" instead of a silent empty catalog
Co-authored-by: MervinPraison <[email protected]>
The prefix filter in _mistyped_command_suggestions spared both extensions
(``tests`` for ``test``) and truncations (``deplo`` for ``deploy``) of a
command. Truncations are typos: sparing them forwarded the word to ``run``
and billed a mistaken LLM call per invocation. Drop the truncation half so
only extensions — plausible prompts — stay untouched.
Co-authored-by: MervinPraison <[email protected]>
After the bounded verify loop exhausts, nothing was persisted, so returning
True made the caller's 'history was lost' branch unreachable and printed a
misleading 'raced with a concurrent writer' warning. Return False and log the
real failure so the caller's existing warning fires.
Co-authored-by: MervinPraison <[email protected]>
If _EXAMPLE_ROOTS is renamed/moved the guard silently emitted no
parametrized cases, letting the Agent(session_id=)/db= regression it
protects against slip back in. Raise a clear collection error instead.
Co-authored-by: Mervin Praison <[email protected]>
Passing limit=None to migrate legacy transcripts (fixing #4160) turned an
already per-agent full-scan into a full-disk scan on every save: the save
loop over N agents re-enumerated every stored session N times, even once
migrated. Cache the scan result per Session keyed on the opt-in flag, since
legacy records are a frozen migration artefact never mutated by save or
restore. Addresses the P2 hot-path regression raised in PR review.
Co-authored-by: Mervin Praison <[email protected]>
Replace the fictional PostgresAdapter import in session/README.md with the
real db(database_url=...) shortcut under MemoryConfig, and move the top-level
db=/session_id= Agent kwargs into MemoryConfig across the db package
docstrings and the runnable redis example. Also align the session_dir default
path in the API reference (~/.praisonai/sessions).
Extend the doc-example guard to discover all Agent( examples under the db
package and examples/persistence, and assert none reference a class we do not
ship, closing the gap the previous two-file textual guard left open.
Co-authored-by: MervinPraison <[email protected]>
_legacy_agent_histories called list_sessions() with no argument, inheriting
its default limit=50 (sorted by updated_at desc). A legacy per-agent record is
by definition older than anything written after the upgrade, so any user who
touched 50 sessions since upgrading had their tagged sub-agent transcript
silently skipped on restore. Pass limit=None (with a TypeError fallback for
stores whose limit is not optional) so migration scans every stored session.
Co-authored-by: MervinPraison <[email protected]>
Re-assert built-in loaders after entry-point discovery so a third-party
distribution publishing a built-in name (e.g. "claude") can no longer
silently replace the shipped ClaudeCodeIntegration. Plugins may still add
new external agents. Adds a regression test.
Co-authored-by: MervinPraison <[email protected]>
- praisonai-code endpoint registry loaded openai-compat via a static
`from praisonai.endpoints...` import, tripping the C7 hot-path import gate
(smoke CI). Route it through the sanctioned _wrapper_bridge dynamic import so
the standalone package no longer statically imports the wrapper.
- Provider adapter routed --stream through invoke(stream=True), whose terminal
InvokeResult the CLI cannot render (Greptile P1). Consume
BaseProvider.invoke_stream() instead and print SSE-shaped events.
- Add a streaming test asserting --stream drives invoke_stream, not invoke.
Co-authored-by: Mervin Praison <[email protected]>
- praisonai-code external_agents handler now resolves the registry catalog
through _wrapper_bridge.optional_wrapper_attr instead of a direct
``from praisonai.integrations.registry import ...`` reverse import. This
restores the C7/C8 import boundary (the smoke `check_c7_imports.sh` gate)
and degrades to an empty catalog when the wrapper is absent so the handler
stays usable on a standalone praisonai-code install.
- external_agent_catalog() now skips any external agent whose entry point
raises a non-ValueError during load (Greptile P1), so one broken optional
plugin can no longer blank the catalog for argparse/CLI/UI surfaces.
Co-authored-by: MervinPraison <[email protected]>
Resolves two Greptile P1 issues on PR #4155:
- validate command accessed provider.value which crashes when the
provider is a registry plugin string; now handles both enum and str.
- sample YAML generation fell through to a hardcoded aws block for
plugin providers; now emits the requested provider name.
Co-authored-by: Mervin Praison <[email protected]>
_apply_default_llm reset _llm_instance but left the chat-mixin
_unified_dispatcher cached against the old model, so a used agent (team
default applied post-execution, or an AgentFlow re-run with a new llm)
kept calling the previous model. Drop the dispatcher too; add regression
tests for used and pinned agents.
Co-authored-by: MervinPraison <[email protected]>
Address the two P1 review findings on the retry consolidation:
- N² attempts: the outer loop re-escalated timeout/circuit_open results as
retryable even though the inner circuit-breaker loop already retries those
error types to exhaustion, restarting the whole inner budget on every outer
pass (up to max_attempts^2 tool-body runs on a persistently-timing-out MCP
tool). Route every error dict through one guard: only escalate error types
the inner loop does NOT retry. A genuine outer wall-clock timeout is tagged
(_outer_timeout) so it still earns its single outer retry pass.
- Backoff parity: translating ExecutionConfig into a RetryPolicy silently
dropped the delay cap from BackoffPolicy's 60s to RetryPolicy's 30s. Lift the
translated max_delay_ms back to 60s so existing ExecutionConfig users keep the
same delay ceiling.
Adds 5 tests: inner-retried timeout capped at max_attempts (not N^2),
non-inner-retried errors still get outer passes, and the 60s cap is preserved.
Co-authored-by: Mervin Praison <[email protected]>
Both endpoint-provider readers now scan the canonical
`praisonai.endpoint_providers` group, with `praisonai.endpoints.providers`
honoured as a deprecated alias (DeprecationWarning). Registers the orphaned
`openai-compat` provider, adapts BaseProvider subclasses into the CLI dispatch
shape, re-asserts CLI builtins so a plugin cannot hijack a shipped type, and
replaces the silent `_invoke_recipe` fallback for unknown `--type` with a
validation error. Declares the group in pyproject.toml and documents it.
Co-authored-by: MervinPraison <[email protected]>
Collapse the four hand-written copies of the external-agent list into a
single source of truth in the registry. Adds list_external_agents() and
external_agent_catalog() to praisonai.integrations.registry; the argparse
--external-agent choices, the praisonai_code CLI handler INTEGRATIONS, and
the UI EXTERNAL_AGENTS toggles now all read the registry. Presentation
metadata (display_label, install_hint) moves onto the integration classes.
Backward-compatible: INTEGRATIONS and EXTERNAL_AGENTS stay Mappings
supporting in / iteration / []. Built-in order and labels are unchanged on
a default install.
Co-authored-by: MervinPraison <[email protected]>
The CloudProvider enum could not be extended at runtime, so plugin
providers discovered/resolved via the praisonai.deploy.providers
entry-point group were rejected by validation. Widen CloudConfig.provider
to Union[CloudProvider, str] with a mode="before" validator that consults
the registry via coerce_cloud_provider. Built-ins keep enum identity and
byte-identical serialisation; plugins validate as normalised lowercase names.
Co-authored-by: MervinPraison <[email protected]>
The broad async exception handler flattened every raised exception into an
error dict with retryable = not isinstance(e, (ValueError, TypeError,
AttributeError)). A ToolExecutionError(is_retryable=False) is none of those,
so it was silently marked retryable=True and re-run up to max_attempts,
diverging from the sync path (tool_execution.py) which preserves an existing
ToolExecutionError's explicit verdict. Now the async path honours
e.is_retryable for ToolExecutionError and only applies the programming-error
rule to other exceptions.
Adds tests for terminal and retryable ToolExecutionError parity.
Co-authored-by: Mervin Praison <[email protected]>
IntegrationRegistry.__init__ reassigned self._loaders = {} right after
super().__init__() populated it from the entry-point group, discarding
every discovered third-party plugin. Remove the reassignment (builtins are
registered afterwards and still win on name clashes) and document the
entry-point group.
Co-authored-by: MervinPraison <[email protected]>
Presence of the vector_store.provider key (not its truthiness) now marks an
explicit choice, so an explicitly empty ("") or null (None) provider surfaces
the preset error instead of silently degrading to Mem0. Adds parametrized
regression coverage for both falsey values.
Co-authored-by: Mervin Praison <[email protected]>
The as_tool() Handoff conversion in _process_handoffs produces a closure
bound to the source agent (its chat_history/tools/memory). clone_for_channel()
shallow-copied that closure verbatim, so a channel clone would delegate using
the ORIGINAL agent's state, leaking one channel's context into another.
Tag the generated closure with its source Handoff and, during cloning, swap it
back so the clone's own _process_handoffs rebinds it to the clone -- mirroring
the existing _praison_sandbox_tool drop-and-regenerate pattern. Adds a clone
regression test asserting the clone's converted tool is bound to the clone, not
the origin.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
to_knowledge_config() emitted reranker.config.model without a provider.
mem0's RerankerConfig requires a provider and Knowledge._prepare_mem0_config
strips all but provider/config, so a provider-less rerank_model was silently
dropped. Derive the provider from a "provider/model" prefix (falling back to
the model string) so the requested reranker is instantiated.
Co-authored-by: Mervin Praison <[email protected]>
AgentTeam stored self.llm and nothing read it, so members silently kept
gpt-4o-mini. AgentFlow(llm=) only reached agents it built itself, never a
ready-made Agent step. Add Agent._apply_default_llm to adopt a container
default as a fill-in (agents that named their own model keep it), and call
it from both containers.
Co-authored-by: MervinPraison <[email protected]>
Agent(auth="claude-code") was silently billed to the API key because auth=
was dropped on the commonest construction branch (bare model name / no model)
and self.auth was never assigned, so clone_for_channel() always lost it.
- Land auth on the final else branch: bare-name + auth= now builds an LLM
instance that injects the resolved OAuth credentials.
- Assign self.auth so clone_for_channel() forwards it.
- Resolve the subscription provider eagerly at construction so an unknown or
unusable provider raises instead of silently downgrading to API-key billing.
- Default the model to the auth provider's vendor when no model is given.
- Inject subscription credentials in _build_responses_params too, mirroring
_build_completion_params.
- Add regression tests and wire the subscription-auth smoke tests into CI.
Co-authored-by: MervinPraison <[email protected]>
as_tool() returns a Handoff, and its own docstring passes the result into
tools=[...]. But tools= stores objects verbatim and only handoffs= ran
to_tool_function(), so an unconverted Handoff was invisible to both the LLM
tool schema and execute_tool(). Convert Handoff entries found in self.tools
inside _process_handoffs, the first point where the parent agent that
to_tool_function() needs actually exists.
Co-authored-by: MervinPraison <[email protected]>
MemoryConfig declared backends (redis/valkey/postgres) that had no adapter,
so requests were silently redirected to a local SQLite/JSON store, and
"sqlite" was overloaded (Agent built ChromaDB while Memory built SQLite).
- MemoryBackend enum now mirrors the registry (file + registered adapters)
- Unimplemented backends raise a clear error instead of substituting
- "sqlite" now builds SQLite on both Agent and Memory (no rag rewrite)
- Memory provider with no adapter fails loudly; deliberate fallbacks warn
- Drop redis/postgres presets and URL schemes that dropped host/credentials
- register_memory_adapter() remains the escape hatch for custom backends
Co-authored-by: MervinPraison <[email protected]>
Eight of KnowledgeConfig's ten fields never reached the internal config:
chunk_size, chunk_overlap, chunking_strategy, chunker, vector_store,
auto_retrieve, rerank_model and retrieval_threshold were read then dropped.
Also config={...} replaced the whole resolved dict, silently resetting
retrieval_k.
- agent.py: forward every declared field with the keys RetrievalConfig
reads (min_score, not threshold); config= now overrides instead of
replacing.
- feature_configs.py: ChunkingStrategy gains TOKEN/RECURSIVE, FIXED/PARAGRAPH
kept as aliases; declared chunking defaults aligned to the effective ones.
- chunking.py: normalize_chunker_type maps strategy names to real chunkers.
- knowledge.py: chunker reads from config instead of hardcoding recursive/512/50.
- retrieval_config.py: add rerank_model + chunking fields, round-trip them,
and emit a chunker block from to_knowledge_config.
Defaults unchanged so existing users are unaffected on upgrade.
Co-authored-by: MervinPraison <[email protected]>
ToolConfig(retry_policy=RetryPolicy(max_attempts=N)) now caps how many
times a tool body runs. Previously two nested loops consumed two
independent vocabularies (RetryPolicy vs ExecutionConfig) in different
units, so max_attempts was silently overridden by max_retry_limit,
running non-idempotent tools more times than configured.
The effective RetryPolicy is now the single budget; ExecutionConfig's
retries/seconds/fraction spelling is translated into it in one place
(_effective_tool_retry_policy). No behaviour change for users who do not
set retry_policy=.
Co-authored-by: MervinPraison <[email protected]>
An all-or-nothing all(isinstance(t, str)) gate silently left every
tool-name string unresolved as soon as one callable was present, so
tools=[my_tool, 'read_file'] dropped 'read_file'. Resolve per element
via a new resolve_tools_list() helper that passes non-strings through
untouched and reports/strict-checks unknown names exactly as the
all-strings path already does.
Co-authored-by: MervinPraison <[email protected]>
execute_tool_async caught a raised tool exception and returned an untyped
error dict; the caller re-classified it as "unknown", which no default
RetryPolicy.retry_on contains, so async always ran a failing tool exactly
once. Carry the retry verdict across the flattening (same rule as the sync
path: programming errors terminal, everything else retryable) and honour it
in the retry loop.
Co-authored-by: MervinPraison <[email protected]>
Knowledge.memory used provider_mapping.get(provider, "mem0"), silently
substituting Mem0 for any provider outside a hardcoded four-name list —
discarding every adapter registered via register_knowledge_adapter() and
swallowing typos. Match memory.py: keep the table for genuine legacy
aliases and pass everything else to the registry, raising a helpful
make_preset_error when an explicit provider is unknown.
Co-authored-by: MervinPraison <[email protected]>
Prompt caching is not applied automatically. LLM._explicit_cache_breakpoints()
gates Anthropic cache_control injection on prompt_caching being truthy, and
Agent defaults it to None. Document the correct spelling
caching=CachingConfig(prompt_caching=True).
Co-authored-by: Mervin Praison <[email protected]>
Resolves two P1 review findings on the closed-set preset validation:
- approval hyphen aliases (accept-edits, bypass-permissions, full-auto,
dont-ask, ...) were rejected by the new guard even though
PermissionMode.resolve accepts them (-/_ interchangeable). The validator
now normalizes hyphens too, restoring previously-valid construction.
- learn= used case-sensitive, non-stripped == comparisons, so a validated
value like "AGENTIC" or " agentic " fell through to else and SILENTLY
disabled learning. It now uses .strip().lower() like self_improve does.
- resolve()'s preset lookup and the approval deny-set lookup now normalize
whitespace/hyphens too, so every spelling the guard accepts also resolves
(previously " sliding_window "/"read-only" passed validation but the
deny-set lookup produced an EMPTY deny set — the exact read-only-sandbox
bypass this PR exists to prevent).
Adds regression tests for hyphen aliases, case/whitespace-normalized
presets (learn actually enabled), and the read-only deny-set security path.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Replace the single module-level identity pointer (_autocreated_store/
_autocreated_dir) with a per-instance marker attribute stamped on any store
this module auto-creates. A partial teardown that restores only
_default_store without restoring the out-of-band tracking variable could
otherwise misclassify a previously auto-created store as caller-injected and
pin it to a stale session directory (Greptile P1).
Also make the DEFAULT_SESSION_DIR __getattr__ hook honour an explicit module
override consistently via _resolve_default_session_dir(), and fix the
override test's leaky monkeypatch (the lazy __getattr__ made setattr restore
a computed value as a real global, leaking into later tests). Adds a
regression test for the restored-store scenario.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
The session module's __init__.py and README.md documented
Agent(name=..., session_id=...), which Agent.__init__ rejects with TypeError.
session_id/user_id/db were consolidated into MemoryConfig, and prompt_caching
was never a parameter (caching is applied automatically per model capability).
Fixes the docs to the working spelling and adds a two-sided guard test.
Co-authored-by: MervinPraison <[email protected]>
Address two P1 review findings on the sub-agent transcript relocation:
- Partial migration: legacy per-agent records were only consulted when the
parent held no current-format histories, so a second agent still living in
a tagged legacy record silently resumed empty. A new _merged_agent_histories
helper always layers legacy under current-format entries (current wins), used
by both single and bulk restore paths.
- Concurrent saves: _store_agent_history read the whole map outside the store
lock then replaced it, letting a concurrent writer under the same parent drop
another agent. It now re-reads the freshest map before each write and verifies
no other key regressed, retrying a bounded number of times.
Adds regression tests for partial-migration recovery and concurrent-save
preservation.
Co-authored-by: Mervin Praison <[email protected]>
The mistyped-command guard used difflib ratio >= 0.8 alone, which also
matches legitimate one-word prompts that are plurals or extensions of a
command word (`tests`->`test`, `runs`->`run`, `server`->`serve`). Those
wrongly exited 2 before reaching the bare-prompt path.
Drop prefix-related matches: an extension contains the command as a prefix
(or vice-versa) whereas a genuine typo (`deploi` vs `deploy`) does not, so
real prompts reach `run` while typos still exit 2 with a suggestion.
Co-authored-by: Mervin Praison <[email protected]>
Seven Agent(...) preset params (output, execution, context, autonomy,
approval, learn, self_improve) silently fell back to defaults on a typo'd
preset name. Worst case: approval="read_onl" produced an empty deny set,
allowing all 17 dangerous tools instead of the intended read-only sandbox.
Wire the existing make_preset_error helper to these params via a small
validate_preset_string() in parse_utils.py plus a compact
_PRESET_STRING_PARAMS table and _validate_preset_params() loop run at the
top of the consolidated-params block, before every fast path that could
swallow the value. Free-form string params (knowledge, guardrails, skills,
runtime, auth) are deliberately excluded.
Co-authored-by: MervinPraison <[email protected]>
An empty list/tuple resolved to None (no-op) on main, but the new
fail-loud guard rejected it with TypeError. Exempt empty collections
so an empty opt-in stays backward-compatible; genuinely unsupported
values still raise. Adds a regression test.
Co-authored-by: Mervin Praison <[email protected]>
ExecutionConfig.parallel_tool_calls now uses None as an internal "not set"
sentinel (normalised to bool in __post_init__) so Agent._merge_parallel_tool_calls
can tell an explicit False from an omitted default. A ToolConfig(parallel=True)
alongside an explicit ExecutionConfig(parallel_tool_calls=False) now raises
TypeError instead of silently enabling parallel tool calls (Greptile P1).
Co-authored-by: Mervin Praison <[email protected]>
Sub-agent transcripts were persisted as separate top-level sessions named
"{session_id}_{name}:{role}", whose sanitised path collided with real user
sessions of the same name (e.g. Session("chat") + Agent("support", "agent")
-> chat_support_agent.json). An ordinary close()/save_state() then silently
overwrote an unrelated user's conversation and could leak it back into the
agent on restore.
Move sub-agent histories into the parent session's own
metadata["agent_histories"][agent_key], removing the second namespace
entirely. Legacy tagged records migrate forward on save; untagged pre-tag
records are restored only behind PRAISONAI_SESSION_LEGACY_AGENT_KEYS=1
(ambiguous by construction) and are never deleted.
Co-authored-by: MervinPraison <[email protected]>
DEFAULT_SESSION_DIR was evaluated at module import time, freezing the
store root to whatever PRAISONAI_HOME resolved to during the first import.
Any later override -- a container exporting PRAISONAI_HOME after the
package was imported, or a test monkeypatching get_sessions_dir -- was
silently ignored, so the store read, wrote and deleted sessions in the
wrong directory.
- Resolve the directory live in DefaultSessionStore.__init__ via
_resolve_default_session_dir().
- Keep DEFAULT_SESSION_DIR readable/assignable via PEP 562 __getattr__.
- Rebuild the singleton when the resolved directory changes, while
never second-guessing a store a caller injected.
- Fix two repo tests that set the unread PRAISONAI_SESSIONS_DIR env var
and reset the wrong singleton attribute.
- Add tests/unit/session/test_session_store_dir_resolution.py.
Co-authored-by: MervinPraison <[email protected]>
Add behavioural coverage for require_approval's sync and async wrappers.
The existing approval suite only asserted registration metadata, so both
denial `raise PermissionError` lines could be deleted with the suite green.
New tests install a denying backend, call a decorated tool, and assert the
PermissionError plus that the wrapped body never ran (side-effect probe).
Positive controls, modified_args, fail-closed, and async-context cases
included.
Co-authored-by: MervinPraison <[email protected]>
The praisonai dispatcher only introspected the `run` subcommand's options,
never the root callback's global flags (`--output-format`/`-o`). As a result:
- `praisonai --output-format json version` misrouted to the legacy engine,
dropped `version`, sent `json` to an LLM, and exited 0.
- A typo'd verb like `praisonai deploi` fell through to the bare-prompt path,
was billed to an LLM, created a session, and exited 1.
Fix, entirely in the dispatcher:
1. Introspect the root callback and union with `run`'s options for argv
tokenisation, so `--output-format` routes correctly.
2. Hoist global-only flags ahead of `run` when synthesising a `run` call
(Click accepts group options only before the subcommand). Options declared
by both (`-o`, `-v`) stay with `run`, preserving existing semantics.
3. Add an unknown-subcommand guard: a lone positional that difflib rates a
close match (>= 0.8) to a registered command exits 2 with a suggestion,
guarded so genuine one-word prompts still work.
Co-authored-by: MervinPraison <[email protected]>
Agent(guardrails=<validator object>) previously fell past every dispatch
branch and was dropped with no exception or warning, so the agent ran with
zero enforcement. Adapt protocol-conforming guardrail objects (and lists of
them) into GuardrailChain, raise TypeError on unsupported values instead of
storing something that never runs, and wire _tool_call_guardrails so
validate_tool_call is no longer dead code.
Co-authored-by: MervinPraison <[email protected]>
ToolConfig.parallel is now a deprecated alias (None = unset) that feeds
ExecutionConfig.parallel_tool_calls, which every public entry point forwards
to the LLM. A bare ToolConfig() no longer silently disables an explicit
parallel_tool_calls=True, and conflicting explicit spellings raise TypeError.
Co-authored-by: MervinPraison <[email protected]>
Previously any --transport value other than exactly "stdio" fell through
to the SSE branch, so a typo (e.g. `stido`) or the advertised-but-
unimplemented `http-stream` silently started a listening socket instead
of a stdio pipe. Add explicit validation rejecting unknown/unimplemented
transports with exit code 2 before any branch can bind.
Co-authored-by: MervinPraison <[email protected]>
- Workflow YAMLs run through YAMLWorkflowParser, which has no cli_backend
wiring; the framework-level compatibility check passes for 'praisonai'
and the field was silently dropped, running the workflow on the native
LLM path. _build_yaml_workflow now fails fast with a clear error,
mirroring the existing tool_timeout and CLI-capability rejections.
- _chat_via_cli_backend: post-success hook emission and chat-history
bookkeeping failures are contained (logged) instead of being reported
as backend-execution failures, which invited callers to retry work the
external CLI already completed; the failure hook now receives the
backend's error result (with its audit metadata) instead of None.
- Tests: workflow-YAML rejection, post-execution containment, and
error-result metadata propagation.
Co-Authored-By: Claude <[email protected]>
Claude-Session: https://claude.ai/code/session_01Pwwvk68iPoNnGw6ov5Lpga
The precise duplicate-add detection introduced in this PR classifies a
schedule add as successful only when the response contains the producer-owned
confirmation "Schedule '<name>' added". The pre-existing timezone-surface test
stubbed schedule_add with a generic "Schedule added" string lacking the job
name, so the new guard correctly treated it as a rejection and the CLI exited
non-zero. Update the stub to return the real success shape; the guard is
unchanged (test was stale, not the code).
Co-authored-by: Mervin Praison <[email protected]>
- schedule add: failure detected as absence of the producer-owned
success confirmation instead of substring matching, so a schedule
literally named 'Error monitor' no longer exits 1 on success
- --backend-timeout: nan/inf/-inf rejected before the job is created
(inf previously raised OverflowError AFTER the schedule was stored);
guard tolerates direct calls passing Typer OptionInfo defaults
- backend gate: go-path state_updates (cursor/watermark) now persist
only after the backend turn succeeds — a policy block, resolution
failure, timeout, or backend error no longer advances the cursor past
unprocessed work; skip-path persistence unchanged; regression test
- CLI session: result validated and resume state recorded BEFORE the
cancellable hook await, so cancellation during the hook cannot lose
is_resume for the next turn (and the lock is already released)
Cross-event-loop lock coordination (two OS threads sharing one Agent,
each with its own loop) is documented as out of scope: sharing an Agent
across threads is unsupported for the wider Agent state; the re-key
path preserves per-loop serialisation, which is the supported usage.
Co-Authored-By: Claude <[email protected]>
Claude-Session: https://claude.ai/code/session_01Pwwvk68iPoNnGw6ov5Lpga
- CLI-backend session lock: asyncio.CancelledError bypasses 'except
Exception', which could leave the per-session lock held forever; a
dedicated handler now releases (guarded by a lock_held flag so a lock
re-acquired by a concurrent turn is never stolen) and re-raises. The
same flag guards the generic exception path.
- Backend pre-run gate now mirrors the native path's state handling:
persisted gate state is loaded, passed to state-aware gates, and
decision.state_updates persist on both skip and go — a backend
monitor job keeps its cursor/watermark across ticks.
- schedule add --backend-timeout: positive sub-millisecond values no
longer collapse to 0 (which the executor replaced with the 300s
default); rounded up to at least 1ms.
Co-Authored-By: Claude <[email protected]>
Claude-Session: https://claude.ai/code/session_01Pwwvk68iPoNnGw6ov5Lpga
The defensive conflict check marked the run failed but returned before
_audit_output and _maybe_deliver_failure, unlike every other backend
failure path — audited deployments would lose the record and the owner
notification. Now consistent; regression test asserts the audit.
Co-Authored-By: Claude <[email protected]>
Claude-Session: https://claude.ai/code/session_01Pwwvk68iPoNnGw6ov5Lpga
A duplicate-name add creates nothing and (post the job_created guard) mutates
nothing, but still printed success and exited 0 — misleading scripts/CI. Treat
the 'already exists'/'Error' responses as failures so a rejected add exits 1 in
both text and --json modes. Adds a regression test asserting no mutation + exit 1.
Co-authored-by: Mervin Praison <[email protected]>
- all backend-branch _audit_output calls now go through
asyncio.to_thread, matching the native-agent failure paths so slow
audit storage cannot block ticker/delivery coroutines
- 'cli_backend: null' in YAML behaves as unset (backward compatible);
the fail-closed error fires only for a non-null value that cannot
resolve
Co-Authored-By: Claude <[email protected]>
Claude-Session: https://claude.ai/code/session_01Pwwvk68iPoNnGw6ov5Lpga
ef6bb47b started scrubbing secret ENV lines on capture via
container.commit(..., changes=scrub) -- a real docker-py kwarg -- but the
suite's _FakeContainer.commit() still took only (repository, tag). Every
capturing provision raised TypeError, fell back to ephemeral, and left
commit_log/list_captures empty: the IndexError and 0==N failures in CI.
Production code is correct; the fake had drifted from the API it mocks.
Widened the fake to the real signature so a successful commit stays a
successful commit.
Co-authored-by: Mervin Praison <[email protected]>
Addresses the remaining review findings:
- --command and --backend are mutually exclusive at the CLI; the
executor fails loudly on persisted jobs carrying both (defensive)
- backend jobs now evaluate the pre-run condition gate (skipped, no
subprocess when nothing to do; gate context appended to the prompt)
and pass the message through RunPolicy.scan_prompt when configured,
matching native-agent jobs
- CLI session establishment is serialised per session id with an
asyncio lock (cross-event-loop safe) so concurrent turns cannot
spawn two fresh CLI conversations for one session
Co-Authored-By: Claude <[email protected]>
Claude-Session: https://claude.ai/code/session_01Pwwvk68iPoNnGw6ov5Lpga
Addresses the three review findings:
- schedule add: trusted post-add options apply only when this invocation
actually created the job — a duplicate-name rejection can no longer
reconfigure a live schedule
- YAML cli_backend that cannot resolve now raises with remediation
instead of silently running the native LLM path
- backend resolution/timeout/launch failures now write the durable
audit record before failure delivery (all three early-return sites)
Co-Authored-By: Claude <[email protected]>
Claude-Session: https://claude.ai/code/session_01Pwwvk68iPoNnGw6ov5Lpga
Greptile P1: the retry loop still mutated self._current_profile on
rotation, and mark_failure/mark_success plus token-model attribution read
that shared pointer. Concurrent requests on one LLM instance could mark
the wrong profile failed/healthy or misattribute cost.
Rotation is now a call-local: _handle_retry_exception takes the active
profile in and returns the (possibly rotated) profile out; both retry
loops keep it in a local and use it for mark_failure/mark_success.
self._current_profile stays pinned to the initial profile. Token usage
is attributed from the serving model on the response (race-free), so the
now-unused _active_profile_values() is removed.
Co-authored-by: Mervin Praison <[email protected]>
Schedule a job that runs its message as one headless turn through a
registered coding-CLI backend (claude-code, codex-cli, gemini-cli,
grok-cli): new ScheduleJob.backend/backend_options fields, an executor
action that resolves backends lazily via the sanctioned _code_bridge
seam (bot never hard-depends on praisonai-code), and
'praisonai schedule add --backend/--backend-cwd/--backend-timeout'.
Output is bounded, failures flow through run records, audit and
failure delivery, and the pinned model is passed to the CLI.
Backend fixes shipped alongside, all previously silent:
- timeouts now return CliBackendResult(error=...) instead of escaping
as bare TimeoutError (all four backends)
- captured stderr reaches the error message (codex/gemini/grok)
- codex: 'exec resume <id>' subcommand order; TOML-safe instructions
escaping; -m model flag; -C honors cwd
- gemini/grok/claude: model flag + cwd threading
- CliSessionBinding.is_resume is now set on the second turn of a
session, activating the resume branches in all four backends
- YAML 'cli_backend:' resolves through _resolve_yaml_cli_backend into
the cli_backend kwarg instead of misrouting into the runtime
registry (shipped example now works)
- 'praisonai backends' registered as a Typer command (standalone
praisonai-code installs previously could not reach the legacy path)
Tests: 19 new (backend action + serialisation round-trip + fixes);
existing scheduler/backend suites verified unchanged vs main;
check_bot_code_imports gate passes.
Co-Authored-By: Claude <[email protected]>
Claude-Session: https://claude.ai/code/session_01Pwwvk68iPoNnGw6ov5Lpga
_switch_to_profile wrote the rotated profile's api_key/base_url/model
onto the shared LLM instance. With one instance serving concurrent
requests (asyncio.gather on a shared Agent, or a cached per-session
Agent), a failover rotation for request A changed the credentials and
model that request B read on its next completion build, silently
sending B's traffic to the wrong provider. Rotation is now a per-call
concern: the retry loop threads the active profile through request
kwargs, and instance attributes keep the initial profile values.
Token tracking follows the profile actually used for the call.
Closes#3613 (gap 2).
_release() called asyncio.run() directly, so GC on a thread already driving
an event loop raised RuntimeError before shutdown ran -- the instance leaked.
Bridge the loop the way SharedCompute._run_sync does (offload to a private
thread when a loop is live) so teardown survives either case.
DockerSandbox.execute() labelled its ephemeral --rm containers praisonai=managed,
the sole input to DockerCompute.list_instances(). Those praisonai-<uuid> names
then surfaced in `managed ps` but `managed stop` resolves praisonai_<id> and
could never reclaim them. Relabel as praisonai=sandbox-exec; the timeout kill
uses --name and is unaffected.
Adds a regression test proving _release reclaims when invoked on a live loop.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Mervin Praison <[email protected]>
Both found by adversarial review, both pre-existing, both leaks.
A TIMED-OUT execution left its container running. The handler called
proc.kill(), which ends the docker CLI while the container it started
carries on. The container also had no --name, so it got a random Docker
name -- neither the timeout handler nor `praisonai managed ps` could
find it, and the user was left with something they could see in
`docker ps` and had no supported way to stop. It is named and labelled
now, and the timeout kills the container rather than the client.
The sibling run_command() path already did this, with the comment "Kill
the container, not just the client". execute() never got the same
treatment; the two paths have been quietly different ever since.
run_on= NEVER RECLAIMED ITS INSTANCE. ComputeManagedAgent defaults to
keep_alive=True, which is right -- an instance should survive between
turns -- but it registered no finalizer, so it also survived the process.
For docker that was a container per script; for e2b, modal, daytona,
tenki and flyio it is a billed cloud instance whose only other reaper is
the provider's own idle timer, and docker and flyio have none.
It now uses the same weakref.finalize treatment tools_placement uses for
agents, which covers collection and interpreter exit, and stands down
when the caller shuts down deliberately. The finalizer deliberately does
not close over the backend -- that would keep alive the very object whose
collection it waits for.
Verified from a confirmed-zero baseline: 0 containers after a timeout
(was 1), 0 after a run_on= script exits (was 1), and ordinary runs
unaffected.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Address two P1 review findings on the YAML adapter/drop-in feature:
- Trust gate bypass: project-local .praisonai/channels/*.py files were
classified by the plugins-scoped _is_project_local() (which checks
.praisonai/plugins), so they executed without PRAISONAI_ALLOW_PROJECT_PLUGINS.
Add _is_project_local_channel() scoped to the channels dir and gate on it.
- adapter field reaching constructor: the loader-only YAML `adapter:` import
ref was passed through into adapter_cls(**init_kwargs), raising TypeError for
adapters that don't accept an `adapter` kwarg. Skip it in the gateway
pass-through alongside platform/token.
Adds regression tests for project-local opt-in enforcement (blocked/allowed)
and the adapter-field exclusion.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Restores the CLI/YAML/Python 3-way surface for custom gateway channels:
- ChannelConfigSchema gains an optional `adapter:` dotted "module:Class"
import string; unregistered platforms are lazily imported, validated
against BasePlatformAdapter, and self-registered before startup.
- BotPlatformRegistry auto-discovers single-file adapters dropped into
./.praisonai/channels/ and ~/.praisonai/channels/, reusing the same
trust gate as single-file plugins.
Backward compatible: absent the adapter key and drop-in dir, resolution
behaves exactly as before.
Co-authored-by: MervinPraison <[email protected]>
The sandbox directory is mounted at /sandbox, so that is the path a user
sees from inside the container and the one they naturally reach for. But
the file API treats "/" as the sandbox root, so the container spelling
was joined onto the root a second time:
write_file("/sandbox/report.txt") -> True
cat /sandbox/report.txt -> No such file or directory
find /sandbox -name report.txt -> /sandbox/sandbox/report.txt
and the reverse direction failed too -- a file the container had just
written to /sandbox/out.txt was invisible to read_file("/sandbox/out.txt")
and absent from list_files("/sandbox"), while read_file("out.txt") found
it. Two spellings of one location, one of them silently wrong, and the
wrong one is the spelling the container itself shows you.
Both now resolve to the same file. Only the exact mount prefix is
stripped, so a genuine subdirectory called "sandbox" is not swallowed --
there is a test for that, because prefix-stripping is the kind of fix
that quietly breaks the case it was not thinking about.
Introduced by the mount added to make writes reach the container at all;
before that, /sandbox did not exist inside it, so nothing could be
addressed either way.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Three valid P1s from adversarial review:
- execute()'s _build_docker_command passed max_processes straight to
--pids-limit, so the default 10 killed the container before python
started (exit 125). Apply MIN_CONTAINER_PIDS floor, matching run_command().
- docker commit scrubbed only a fixed secret-name set. ComputeConfig.env is
public (.praisonai/environment.yaml), so an arbitrary custom secret was
baked into the persistent image. Scrub the union of the known set and the
config's own env names -- the values actually injected into the container.
- open_in_sandbox/makedirs_in_sandbox referenced os.O_DIRECTORY / O_NOFOLLOW
and dir_fd unconditionally, raising AttributeError on Windows. Gate the
openat walk behind a capability flag; fall back to the resolved-string
guard where openat is unavailable (Docker there runs a Linux VM, so no
host-shared dir exists to race).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Mervin Praison <[email protected]>
Four defects found by adversarial review of the merged consolidation. The
first two are mine.
ESCAPE. The bind mount added so write_file() actually reaches the
container turned a harmless check-then-use into an exploitable race.
safe_sandbox_path() validates a path STRING; the caller then opens that
string -- two syscalls with a gap. Nothing but the host could write to
that directory before it was mounted. Afterwards, code inside the
container could swap a name between a regular file and a symlink:
for i in $(seq 1 6); do (while true; do
rm -f /sandbox/notes.txt; ln -s /etc/passwd /sandbox/notes.txt
rm -f /sandbox/notes.txt; : > /sandbox/notes.txt
done) & done
Measured before the fix: an escape to an arbitrary host file on write
attempt 375, and a host secret disclosed on read attempt 4. Arbitrary
host read and write, from code that where_does_it_run() calls "a Docker
container".
No amount of stricter string checking fixes this -- anything verified
before the open can be invalidated after it. So the file is never
re-opened by name: open_in_sandbox() walks the path one component at a
time against an open directory descriptor with O_NOFOLLOW at each step,
so a symlink substituted at any level fails the open rather than
redirecting it. Re-running the attack: host file untouched, secret not
disclosed, ordinary writes unaffected.
LEAK ON EVERY EXIT. tools_run_on= releases its sandbox from a weakref
finalizer, which usually runs as the process ends -- and by then
concurrent.futures has set its own atexit flag, so run_in_executor raises
"cannot schedule new futures after interpreter shutdown". The failure was
swallowed and logged as a successful release, so every run left a
container up while reporting it had cleaned up. Docker and Fly.io have no
idle reaper, so those were indefinite.
_offload() now falls back to calling inline when the executor is gone,
which is correct there: no event loop is left to starve. Unrelated
RuntimeErrors still propagate. DockerCompute was never converted to the
shared base in the earlier extraction, so it had the same bug in four
more places; it inherits now. Teardown reports failure instead of
claiming success, since a failed release means something is still
running -- or still billing.
SECRETS IN A COMMITTED IMAGE. `docker commit` preserves Config.Env, so
the model API keys forwarded into a container were baked into an image
that persists for days and is readable by anyone who can run `docker
inspect`. The capture exists to reuse installed packages, not the
credentials that happened to be present while installing them, so the
commit now scrubs them.
FORK BOMBS. run_command() accepted max_processes and ignored it while
the other execution path applied it. Docker's --pids-limit is per
container, so unlike RLIMIT_NPROC it means what it says -- but the
default of 10 was chosen for the rlimit world and kills the container
before the shell finishes starting. The cap has a floor a container can
live within; it still bounds a fork bomb, it just stops the bound from
being the bug.
Also drops `native` from the not-a-boundary list: it aliases sandlock,
which applies Landlock and seccomp, so the two spellings of one backend
were giving opposite security advice.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Seed the outbound carrier with provider headers first, then inject the
active trace context last so a fresh traceparent/tracestate always wins
over any stale provider-supplied values (Greptile review on #4103).
Co-authored-by: Mervin Praison <[email protected]>
Extend the dependency-free GatewayTraceHook seam so an exporter can continue
an upstream caller's distributed trace and propagate context downstream:
- stage() gains an optional parent_carrier (inbound traceparent/tracestate)
so a stage can be entered under an extracted parent span context.
- inject_context()/extract_carrier() no-op defaults let egress call sites
write the active traceparent and ingress boundaries continue a caller's
trace. Real extract/inject lives in the OTel exporter plugin.
NullGatewayTraceHook stays the zero-cost, OpenTelemetry-free default:
inject_context leaves the carrier untouched and extract_carrier returns None.
Additive and backward compatible.
Co-authored-by: Mervin Praison <[email protected]>
The error branch in _parse_tool_call_arguments (PR #4075, commit 991b2ff28)
intentionally reads the real tool name from tool_call["function"]["name"] so a
malformed/truncated arguments string is reported back to the model for the
correct tool instead of aborting the turn with a fabricated name. The stale
test still asserted the old "unknown_function" behaviour, causing a pre-existing
test-core failure unrelated to the docker-sandbox changes on this branch.
Update the assertion to the current contract and add a case proving the
"unknown_function" fallback still applies when no name is recoverable.
Co-authored-by: Mervin Praison <[email protected]>
run_in="docker" goes through execute(), which mounted only its own
script under /code -- so it could not see files write_file() wrote and
anything it created vanished with the container. Mount the sandbox dir
and run the script from there, matching run_command(). Adds a regression
test proving execute() reads a written file and its output persists.
Co-authored-by: Mervin Praison <[email protected]>
It said "backends extracted from the praisonai wrapper", which stopped
being the whole truth when the seven compute providers moved in. The
package now holds both shapes: eight sandboxes (one object IS one
environment) and seven compute providers (one object hands out many).
The distribution name stays. "sandbox" is imprecise for a package that
also contains fleet managers, but it is published, it appears in every
install hint and extra, and renaming a released package costs more than
the imprecision does. The precision lives in the subpackage instead:
praisonai_sandbox.compute is unambiguous about which shape you are
importing.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Two user-visible defects, found by comparing the two docker
implementations now that they sit in one package.
WRITES WENT NOWHERE. write_file() writes into a host temp directory, and
`docker run` never mounted it. So the write reported success, the file
landed outside the container, and reading it back failed:
write_file("/data.txt", ...) -> True
run_command("cat /data.txt") -> exit 1, No such file or directory
Nothing carried between commands either, since each one got a fresh --rm
container with no shared storage. The directory is now mounted at
/sandbox and commands run there by default, so a write is visible to the
next read and to the next command.
LISTING LEAKED THE HOST PATH. list_files() returned entries like
"/../../../../../../private/var/folders/.../praisonai_sandbox_xxx/a.txt".
On macOS the sandbox directory comes back as /var/folders/... while
os.walk reports /private/var/folders/... -- /var being a symlink -- so
the relative-path computation escaped upward and handed back the real
host location. Both sides are resolved before comparing now, and any
entry that still escapes the root is dropped rather than reported.
Isolation is unchanged and tested: the host filesystem stays invisible,
only the sandbox directory crosses.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The C13 sandbox import gate flags any `from praisonai` line in
praisonai_sandbox/. The moved compute providers still documented the
legacy `praisonai.integrations.compute.*` alias in their docstring
examples, tripping the gate and failing test-core, test-core (sandbox)
and smoke. Point every example at the canonical
`praisonai_sandbox.compute.*` path (the old path is now only an alias),
which both satisfies the gate and gives users the correct import.
Co-authored-by: Mervin Praison <[email protected]>
- praisonai-sandbox[all] now includes tenki and flyio, so a user who runs
`praisonai-sandbox[all]` and selects tools_run_on="tenki" gets the SDK
instead of a missing-dependency error (Greptile P1).
- _compute_bridge _EXTRA_HINTS now point at praisonai-sandbox[<vendor>] rather
than the heavy praisonai wrapper — the whole reason the providers moved
(58 vs 143 resolved packages) — and cover the previously-missing tenki hint.
Co-authored-by: Mervin Praison <[email protected]>
Reaching E2B through `tools_run_on=` required the praisonai wrapper: 20
hard dependencies and 8 sibling packages, including a browser package and
a Telegram bot, to run a command in a sandbox. The identical capability
through `run_in="e2b"` needed only praisonai-sandbox[e2b]. Measured, that
was 143 resolved packages against 58, for the same vendor.
The seven compute providers now live in praisonai_sandbox/compute/,
beside the sandbox backends they share a vendor with. That package was
already the right shape for this: four hard dependencies and one optional
extra per vendor, sitting directly above core. Nothing needed inventing --
the extras grid already existed and was already correct.
Verified with the wrapper made genuinely unimportable: providers resolve
and a real Docker container runs. That property now has a test, so the
providers cannot quietly drift back behind a dependency users should not
need.
Compatibility. The old modules alias the new ones through sys.modules
rather than re-exporting from them. A plain `from ... import X` shim
looks equivalent right up until someone monkeypatches a module-level name
through the old path -- the patch lands on the shim and the real module
never sees it, which is exactly what the wrapper's docker-capture tests
do. Aliasing keeps one shared module object, so every existing import,
attribute and patch keeps working.
tenki's SDK pin follows its implementation; flyio needs none, since it
speaks plain HTTP through aiohttp, which praisonaiagents already
requires.
This does not merge the two implementations of the four shared vendors.
That decision is still open, and it is now easier to make because the
pairs finally sit in the same distribution.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
When a provider's SDK was missing, the error told the user what to
install. Three of those instructions were wrong:
praisonai[e2b] did not exist
praisonai[docker] did not exist
praisonai[daytona] existed but was EMPTY -- installed nothing
pip warns about an unknown extra and then carries on succeeding, so the
user followed the official hint, waited for the install, and hit the
identical failure again. That is worse than no hint at all, because it
looks like it is helping.
The wrapper extras are now real and delegate to praisonai-sandbox, which
already pins every vendor SDK correctly, rather than standing up a second
grid of pins to drift against the first.
A test walks every hint, resolves the extra it names against the real
pyproject, and asserts it exists and is non-empty. The only reason this
survived is that nothing checked whether the advice was true.
Rebased onto main and rebuilt rather than merged: this branch and main
had both appended to test_provider_matrix.py, so a textual merge cut a
function in half. Main's copy is taken whole and the one test unique to
this branch re-applied on top.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Compute truncation before emit_run_result in the actions/custom-agent
paths so --output stream-json consumers never receive a contradictory
run.result {ok:true} ahead of the status:"truncated" outcome (exit 2).
Adds a regression test exercising the stream-bridge ordering.
Co-authored-by: Mervin Praison <[email protected]>
auth._PROVIDER_ENV_KEYS retained only each provider's first catalogue
env-var, so providers with multiple credential spellings (together:
TOGETHER_API_KEY/TOGETHERAI_API_KEY, fireworks: FIREWORKS_API_KEY/
FIREWORKS_AI_API_KEY) had their secondary alias dropped. The runtime
(env.py) already honours all aliases, so `auth list`/`status` reported
"not found" for a credential the runtime accepts — the exact drift this
PR set out to eliminate. Now the map keeps all aliases and auth prefers
whichever the user actually set. Adds parametrised coverage over every
multi-alias provider.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Denials now support optional free-text guidance surfaced back to the model
as a course-correction instead of a bare "User denied" dead-end.
- ApprovalDecision gains optional feedback field (backward-compatible).
- ConsoleBackend adds a [d] "deny & redirect" choice capturing one line
of guidance.
- Tool-loop denial handlers fold feedback into the tool result the model
sees next turn (reuses existing result path, no new subsystem).
- InteractiveCLIApprovalBackend now also sets decision.feedback.
Co-authored-by: MervinPraison <[email protected]>
A run that hits its max_iter/max_steps budget returns a non-empty
finalisation summary, which the CLI's _run_succeeded accepted as success —
masking incomplete work with exit 0 and status "success".
The core already records the terminal reason on the agent via
last_stop_reason ("max_steps" on truncation), so consult it on the
in-process run paths that hold the Agent object and report a distinct
tri-state outcome:
- new _run_was_truncated(agent): reads last_stop_reason (best-effort)
- new _report_run_truncated(output, result): preserves the summary text,
emits status "truncated" for --output json, prints a one-line stderr
notice for interactive users, and exits 2 (distinct from failure=1 and
completion=0)
Wired into the actions, custom-agent, and profiled-prompt paths. Genuine
completion and hard-failure paths are unchanged.
Co-authored-by: MervinPraison <[email protected]>
Wire the two remaining parallel provider->env-var maps to the canonical
PROVIDER_ENV_CATALOGUE so key auto-detection, provider inference, and the
auth surface can no longer drift:
- model_resolver._provider_for_model() now resolves via the catalogue
(provider_for_model + env_vars_for_provider), covering openrouter,
mistral, deepseek, xai, together, fireworks, ... instead of returning
None. Keeps the historical eight-provider ladder as an offline fallback.
- auth._PROVIDER_ENV_KEYS is derived from the catalogue at import, with the
historical literal map retained as an offline fallback.
- Add parametrised drift tests asserting every catalogued provider is
resolvable by auth, model_resolver, and env first-run detection, so
future drift fails CI.
Co-authored-by: MervinPraison <[email protected]>
- audit.py: bind sensitive_keys to the built-in redactor via functools.partial
at construction so both default and custom redactors are always invoked with
a single argument, honouring the declared Callable[[Any], Any] contract.
Custom one-arg redactors no longer raise TypeError before _write runs.
- db_session_adapter.py: add per-session init lock so concurrent first access
calls the non-idempotent on_agent_start exactly once, preventing duplicate-key
races in SQL conversation stores. Init locks are cleaned up on delete_session.
Co-authored-by: Mervin Praison <[email protected]>
- security/audit.py: redact sensitive tool_input keys (api_key, token, etc.)
via a default denylist redactor; chmod the log file to 0o600.
- integrations/db_session_adapter.py: guard the four in-memory containers with
a threading.RLock (DB I/O stays outside the lock) to prevent dropped messages
and duplicated on_agent_start under concurrent multi-agent load.
- __init__.py: disambiguate ModuleNotFoundError on e.name so a broken transitive
dependency surfaces the real cause instead of a misleading "has no attribute".
Co-authored-by: MervinPraison <[email protected]>
Address two P1 review findings on the untrusted-request fencing:
- use_system_prompt=False bypass: add a self-describing inline notice
(request_payload_notice) prepended once outside the fence at each
ingress boundary (webhook render_prompt, hook render_template), so the
untrusted-data semantics travel with the payload even when the agent
never receives the system-prompt trust clause.
- deliver_only markup leak: resolve_message gains a fence flag; the
gateway deliver_only path calls it with fence=False so recipients of
direct channel deliveries never see literal fence tags.
Tests updated for the inline notice and unfenced deliver_only output.
Co-authored-by: Mervin Praison <[email protected]>
Address reviewer-flagged issues on the unified schedule management surface:
- schedule_update now clears last_run_at on cadence change so a new at:/every/
cron schedule is evaluated fresh (a previously-run job updated to at: was
treated as already-fired and never ran).
- CLI pause/resume/update/remove/delete mutate the exact record resolved by id
(via store.update/store.remove) instead of round-tripping through the
name-based tool, so duplicate names cannot cause the wrong job to change.
- schedule list --json emits a single valid JSON document ({store, daemon})
instead of mixing a JSON array with the daemon's human-readable table.
- schedule describe consults the canonical store first, so store-backed jobs
authored by schedule add can be inspected; falls back to the daemon.
Adds a regression test for the cadence-reset fix. Full scheduler suite passes.
Co-authored-by: Mervin Praison <[email protected]>
Address final-review findings on the unattended-run wiring:
- schedules_runner: on the canonical store, claim_due advances last_run_at at
claim time, so raising in on_trigger still consumed the occurrence. Only
start the poll loop when an executor was built; otherwise leave the loop
unstarted so no due job is claimed/consumed (P1: atomic claim consumes
failed occurrence).
- schedules_runner: drop the misleading "process-global registry" claim from
the resolver docstring — no such registry exists in host embedding; message
jobs are recorded failed (auditable) and command jobs run (P1: agent
resolution).
- gateway server: rebuild RunPolicy each tick from the current _loaded_config
so a hot-reloaded scheduler: block applies without a process restart
(P1: reloaded policy remains stale).
- test: replace the tautological on_trigger stub test with one that asserts
the real bridge does not start the loop when no executor is available.
Full scheduler unit suite: 307 passed, 8 skipped (no regressions).
Co-authored-by: Mervin Praison <[email protected]>
Addresses Greptile P1 on PR #4088: resolve_launch_host() previously wrote the
process-wide PRAISONAI_LAUNCH_AUTH_TOKEN before the no-agents / missing-deps
guards, so a launch that never started a server could still flip global auth
and retroactively 401 an already-running endpoint. The bind guard now runs only
after both paths are committed to serving. A generated token is also reused for
the process lifetime so a later non-loopback launch cannot mint a fresh token
and lock out an endpoint already serving with the previous one.
Co-authored-by: Mervin Praison <[email protected]>
- run_stream() now records a terminal RecipeResult (success/failed/policy/
missing-deps/dry-run) via best-effort history, closing the streaming gap
- recipe runs: label the identifier column "Run ID" and align judge guidance,
since `recipe judge` consumes the run_id (the index has no trace_id)
- legacy praison_ai: use direct attribute access (removes Ruff B009)
- tests: add streaming-persistence coverage; legacy test now exercises the
wrapper-bridge resolution path the legacy branch actually uses
Co-authored-by: Mervin Praison <[email protected]>
Addresses reviewer P1s in github_commit_and_push:
- Safety refusals now run BEFORE staging a commit, so a refused push leaves
pending changes intact and a retry can succeed.
- Existing local target branches are switched to with a plain checkout instead
of `checkout -B`, so their local-only commits are not discarded.
- Divergence (force-push) refusal is factored out and applied to every branch,
including agent-prefixed ones, and is never overridable.
Co-authored-by: Mervin Praison <[email protected]>
Defect 1: gateway now constructs a default RunPolicy (deliver-on-failure,
prompt scan, denied toolsets) with optional gateway.yaml `scheduler:` overrides,
so failed scheduled jobs notify the owner and unattended tool downscoping fires.
Defect 2: the host-app schedule bridge now executes due jobs via
ScheduledAgentExecutor; when no executor can be built it raises so ScheduleLoop
leaves the job due instead of silently absorbing it.
Defect 3: the BotOS scheduler path now enforces pin_model via the canonical
_check_model_drift before agent.chat — a drifted pinned job takes no model turn
and is recorded failed with the drift reason.
Co-authored-by: MervinPraison <[email protected]>
Wire the existing untrusted-content fencing at the HTTP ingestion boundary so
webhook/hook payloads arrive labeled as data, not instructions:
- Add reusable wrap_request_payload() + <external_request_payload> fence
constants to tools/trust.py (ingress counterpart to wrap_if_external).
- Extend the system trust clause to name the new fence.
- Fence payload-derived content in the webhook channel render_prompt: template
interpolations and the raw-body default are fenced; the no-prompt case gains a
fixed operator prefix so attacker text is never the sole instruction.
- Fence payload interpolations in the gateway hook resolve_message; operator
template text stays outside the fence.
Fence closers embedded in payloads are delimiter-escaped to prevent breakout.
Co-authored-by: MervinPraison <[email protected]>
Address CodeRabbit/Greptile feedback: the prompt-only regression test
previously never asserted that execution completed or that the agent
branch ran, so it could pass while the job stayed queued. Now records
the agent-branch call and asserts a 200 result of "agent-result".
Co-authored-by: Mervin Praison <[email protected]>
- Persist every RecipeResult via history.store_run at the end of recipe
core.run(); gated by PRAISONAI_RECIPE_HISTORY (default on), write
failures never fail the run (logged and ignored).
- Add `praisonai recipe runs [name] [--status] [--session] [--limit]`
to the Typer app, rendering recipe/version/status/when/session/trace-id
and delegating to history.list_runs.
- Fix the broken legacy import in praisonai-code by routing through the
wrapper bridge to the real praisonai.cli.features.recipe module.
- Add unit tests for persistence, env flag, safe write failure, status
filtering, registry independence, and clean handler import.
Co-authored-by: MervinPraison <[email protected]>
Agent.launch served an unauthenticated prompt-execution HTTP endpoint on
0.0.0.0, while Agents.launch enforced PRAISONAI_LAUNCH_AUTH_TOKEN. Factor the
request authoriser and a fail-closed bind guard into a shared
launch_security module and apply it to both paths:
- Agent.launch HTTP route now returns 401 without the bearer token.
- Both paths auto-generate and print a one-time token when bound to a
non-loopback host keyless (loopback keyless dev flow unchanged).
- Default host changed 0.0.0.0 -> 127.0.0.1 for both launch methods.
- Bearer compare is now constant-time.
Co-authored-by: MervinPraison <[email protected]>
Make store-backed jobs first-class in the CLI so what `schedule add`
writes is what `list`/`delete` and the new subcommands read.
- CLI: `list` now merges store jobs (labeled [store]) with daemon
schedulers; add `runs`, `pause`, `resume`, `update`, `remove` operating
on the ScheduleJob store; `delete` finds store jobs first; `add --once`.
- Agent tools: add `schedule_pause`, `schedule_resume`, `schedule_update`;
expose `once` on `schedule_add` (maps to delete_after_run). Registered
in TOOL_MAPPINGS for lazy string resolution.
Scope: kept to praisonaiagents + praisonai per AGENTS.md. `schedule tick`
requires the Tier-2 praisonai-bot executor and is intentionally not added.
Co-authored-by: MervinPraison <[email protected]>
Refuse autonomous pushes to the default/protected branch, foreign-author
branches, and diverged remotes (never force). Auto-create praisonai/ branch
when on default. Opt-in override via allow_unsafe_branch / env.
Co-authored-by: MervinPraison <[email protected]>
The runs API declared recipe_name/recipe_config on JobSubmitRequest and the
executor implemented the recipe branch, but the router never copied those
fields into the Job — so POST /api/v1/runs {"recipe_name": ...} silently ran
nothing recipe-related. Copy the fields through and add regression tests.
Co-authored-by: MervinPraison <[email protected]>
`docker` is implemented twice -- once as a compute provider, once as a
sandbox backend -- and the two defaults had drifted a minor version
apart. Same word, different container:
tools_run_on="docker" -> Python 3.12.14
run_in="docker" -> Python 3.11.16
Nobody decided that. Two independent implementations of one idea simply
diverged, and unifying the vocabulary made the divergence easier to reach
rather than harder, because both spellings now look like the same thing.
The sandbox side moves to python:3.12-slim to match, along with the CLI,
docs and examples that quoted the old default.
The parity test compares the values a caller actually gets --
SandboxConfig.docker().image against ComputeConfig().image. An earlier
version of it scanned the DockerCompute docstring, which meant it passed
while the defaults were genuinely 3.11 and 3.12 apart. A test that cannot
fail is worse than no test, because it is counted as coverage.
Rebased onto main and rebuilt rather than merged: this branch and main
had both appended to test_provider_matrix.py, and a textual merge cut a
function in half. Main's copy is taken whole and the one test unique to
this branch re-applied on top.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Addresses reviewer P1 findings on the async batch/window fixes:
- _depends_on_pending now also detects dependencies expressed via
task.previous_tasks (workflow next_tasks edges are stored as task names),
not only task.context, so a workflow successor is no longer queued in the
same async batch as its predecessor and forced to read an empty result.
- New _deps_failed method extends the failure cascade to the async_execution
path in both the sequential and workflow branches: after a same-batch flush,
an async dependent whose prerequisite failed is marked failed instead of
running with missing upstream context (previously only sync dependents were
guarded).
- TruncateOptimizer re-skips leading orphaned tool results after its
token-budget pop loop, which could otherwise drop an assistant tool_calls
message while retaining its role="tool" result and leave the trimmed
transcript starting on an orphan (Issue #3089).
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
1. Guard the tool-call argument JSON parse in the non-streaming native
loops (openai_client.chat_completion_with_tools / achat_completion_with_tools)
so a malformed/truncated arguments string is reported back to the model
instead of aborting the whole agent turn, matching the streaming path.
Also read the real tool name from tool_call["function"]["name"] in
llm._parse_tool_call_arguments' error branch instead of the never-present
top-level "name" key.
2. Route DefaultSessionStore._enforce_window's window slice through the
existing _trim_preserving_tool_exchanges guard, and skip leading orphaned
role="tool" messages in the context TruncateOptimizer/SlidingWindowOptimizer,
so a persisted/optimized window never starts mid tool-exchange.
3. Split an async task batch on an intra-batch context dependency in
arun_all_tasks (sequential + workflow) so a dependent async task's context
is built after its same-batch dependency completes, not before.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
The generic ComputeManagedAgent forwards image= through ComputeConfig.image,
which Docker/Daytona/Fly read but E2B (used metadata[e2b_template]) and Modal
(hardcoded debian_slim) ignored -- so run_on='e2b', image=... silently booted
the provider default. E2B now takes a non-default image as its template; Modal
builds it via from_registry. The default value leaves both unchanged. Adds
boundary conformance tests asserting the value each SDK actually receives.
Co-authored-by: Mervin Praison <[email protected]>
Every cloud SDK here is synchronous and ComputeProviderProtocol is async,
so each provider grew the same five methods whose entire body is "hand the
matching _*_sync call to a thread":
async def provision(self, config):
loop = asyncio.get_running_loop()
return await loop.run_in_executor(None, self._provision_sync, config)
Measured: provision, execute, shutdown, upload_file and download_file were
byte-identical across e2b, daytona, modal and tenki -- six identical pairs
per method, about 210 lines of the same four statements.
That was the largest genuinely duplicated block in the project, larger
than all four cross-stack vendor pairs combined. It stayed invisible
because it sits *within* one stack rather than between two, and the
attention had been on the cross-stack pairs, where the real overlap turns
out to be about 6%.
A vendor now implements only the _*_sync half it differs in. Anything a
provider genuinely does differently it overrides, because these are
ordinary methods -- flyio does exactly that, since it speaks HTTP through
aiohttp and is natively async rather than sync-wrapped.
Each unimplemented operation raises NotImplementedError naming the
provider, rather than silently returning a wrong answer.
Net -119 lines. Verified live: docker and modal both still provision and
execute, and the provider matrix passes for all thirteen places.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
`run_on="docker"` had its own 321-line managed backend while the other
seven places shared one generic implementation. The justification written
into that file -- it talks to the daemon directly and skips a
provisioning layer -- did not survive being checked.
It named its containers `praisonai-agent-<hex>`, while DockerCompute's
lookup expects `praisonai_<instance_id>`. So:
praisonai managed ps -> shows the container
praisonai managed stop -> ValueError: No docker container found
Listed but unreclaimable, which is the worst combination: the user can
see the thing they cannot stop. Routing through the provider fixes it by
construction, and 321 lines go with it.
Two gaps in the generic backend had to close first, both real:
- `image=` fell into **kwargs and was silently ignored, so asking for a
specific image quietly got the provider's default.
- the failure when a place is unavailable now names the place and
offers tools_run_on=, which needs no daemon.
The generated class is still called DockerManagedAgent -- make_loader
names each backend after its place -- but it is now a ComputeManagedAgent
subclass, so there is one code path for every runtime.
Also adds the conformance tests that would have caught this class of
problem: the four vendors implemented twice must agree on their
conventions. Docker-only parity is exactly what let Daytona drift into
asking for 1024 GiB of RAM.
Verified live: docker provisions, runs a whole agent loop, appears in
`managed ps`, and `managed stop` now reclaims it.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
test_hosted_agent_only_accepts_anthropic encoded a pre-run_on= assumption
that modal/e2b were unavailable managed runtimes. The placement feature
intentionally registered them via the backend registry, so HostedAgent now
resolves them. Assert the guarantee that still holds — providers with no
registered backend (openai/gemini) raise a helpful ValueError — instead of
the stale one.
Co-authored-by: Mervin Praison <[email protected]>
Replace inspect.getsource() substring checks with behavioral tests that
mock the Daytona SDK and assert the actual value passed: memory converted
to GiB (2048MB->2, 512MB->1) and upload_file(src, dst) argument order.
Addresses Greptile p2: source inspection let equivalent regressions pass
and harmless refactors fail.
Co-authored-by: Mervin Praison <[email protected]>
Two live defects on the compute side of Daytona, both found by comparing
it against the sandbox side, which had already learned the conventions.
MEMORY UNITS. daytona_sdk documents Resources.memory as "Amount of memory
in GiB to allocate". The compute provider passed ComputeConfig.memory_mb
straight through, so the default configuration asked Daytona for 1024 GiB
of RAM. That is a provisioning failure, not a rounding error. The sandbox
implementation converts correctly and always has.
ARGUMENT ORDER. FileSystem.upload_file(src, dst) takes the content first
and the destination second. The compute side called
upload_file(remote_path, content), so an upload wrote the path into a
file named after the content. The sandbox side calls it correctly.
Neither is a typo in the ordinary sense: both are the same class of
failure, where one of two implementations of a single vendor learned a
convention and the other never did. Nothing compared them, so nothing
noticed. The wrapper's daytona tests only assert provider_name and that
the constructor exists -- nothing exercises provision() or upload.
Tests now assert both conventions on the compute side, because a shared
vendor name is not a shared understanding of that vendor.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The provisioning tests asserted an exact count of one. SharedCompute
provisions LAZILY, so a run that never touches a tool correctly
provisions nothing -- the exact count was asserting when provisioning
happened rather than the property that matters, and it flaked.
The guarantee is that a run never provisions MORE than one sandbox, and
that a three-row batch does not mean three. Verified the weaker assertion
still has teeth: mutating _needs_tools_scope to always open a scope fails
six tests including the batch one.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
An ephemeral place (keep_alive=False) provisions a billable cloud
instance, but execute() only tore it down on the success path -- a
failed write, remote run, or parse left the instance running until
external cleanup. Move shutdown into a finally so teardown is
unconditional; keep_alive=True still keeps the warm instance.
Fixes the Greptile P1 on compute_managed_agent.py.
Co-authored-by: Mervin Praison <[email protected]>
SANDBOX_ONLY was a hardcoded tuple of four names. The sandbox registry
accepts plugins by entry point, so a contributed backend worked with
run_in= and could not be selected with tools_run_on= at all -- the same
hardcoded-list bug just fixed for the compute registry, one layer down.
`capsule` was the live example: it ships from praisonai-plugins, resolves
fine through run_in=, and was missing from the tools_run_on= vocabulary
for no reason a user could see.
The names now derive from the registry, with the original four kept as a
floor so nothing depends on discovery succeeding. Anything the compute
registry already provides is excluded, so docker/e2b/modal/daytona keep
their richer implementations instead of being downgraded to the
one-instance adapter.
SANDBOX_ONLY stays a tuple subclass that re-reads the registry on
membership and iteration, because several call sites predate this and
import it directly.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The phrase table is a literal, so it cannot know about a package
installed later: an external place printed as a bare name
(tools_run_on='demo') while every built-in got a readable phrase. A
provider may now declare `display_name` and have it used in the repr and
in where_does_it_run().
Verified with a plugin installed from outside the repo: it reports
"a Demo cloud sandbox" in both. Declaring it stays optional and the
fallback to the bare name is unchanged, so nothing existing shifts.
That leaves one derived surface still hand-maintained -- the ToolPlace
Literal -- which is inherent to static typing rather than fixable: a type
checker cannot see a runtime plugin. Its union already stays open, so an
unknown name type-checks and only loses autocomplete.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
_PS_PROVIDERS was a hardcoded tuple, so a place contributed by another
package could be provisioned and then never listed or stopped. An
unreclaimable cloud sandbox is a bill nobody sees, which makes this the
one remaining hand-maintained list with a cost attached.
Exclusions are now stated with reasons rather than by omission: local and
subprocess run here and have nothing to reclaim, ssh is someone else's
machine and not ours to stop, sandlock is a process rather than an
instance, and adapter-backed places have no cross-process registry to
enumerate.
_PS_PROVIDERS stays as a module attribute so existing imports keep
working.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Modal's `run_in=` path was broken in five separate ways and nothing
noticed, because nothing had ever run it. Most of what breaks an
integration is checkable for free, so this checks it: for all ten places
the class resolves, satisfies the protocol, exposes coroutines rather
than sync methods (a sync one here does not raise -- it returns a
coroutine nobody awaits, so the call silently does nothing), answers
is_available without throwing, is accepted by tools_run_on=, is accepted
or refused by run_on= according to whether it can host a loop, and is
described in the repr as the place it was actually given.
The one that matters most in practice is the last check: a missing
credential has to fail with something actionable -- naming the key, the
install command or the daemon -- rather than an AttributeError from
inside a vendor SDK. All seven credential-less places pass it today.
Live where the machine allows: docker, subprocess, local and modal
provision and execute for real; the rest skip loudly.
Also removes a latent flake. The batch-provisioning test asserts an exact
provision count, and agents from earlier tests release their sandbox when
collected -- which could land inside the measurement window now that
lifetime is tied to a finalizer. The window is opened after a collection
instead of hoping the timing misses.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
run_on= accepted two names while tools_run_on= accepted twelve. That was
not a fact about the places -- a place that can run a command can run the
agent loop, which is just one more command -- it was an implementation
detail: no backend had been written for the rest.
One generic ComputeManagedAgent wraps any ComputeProviderProtocol rather
than eleven near-identical vendor backends, taking run_on= from 2 places
to 8: anthropic, docker, e2b, modal, daytona, flyio, tenki, novita.
Verified live end to end on Modal -- the whole loop ran there and came
back with the answer, having installed the package remotely first.
Excluded deliberately, with tests asserting they still raise: `local`
would run the agent in your own shell, which is what you get by passing
nothing; `ssh` needs an object, not a name; `subprocess`/`sandlock`
isolate tools rather than host a runtime. `docker` keeps its specialised
backend since it can talk to the daemon directly.
Two details worth keeping:
- the registry loader returns a real subclass, not a factory function,
because HostedAgent's factory path calls issubclass() on it
- files reach the remote machine through a quoted heredoc, since execute()
is the only primitive every compute place has, and the delimiter is
uppercase for the same reason as elsewhere: a lowercase hex delimiter
contains "dd", a blocked command, about a tenth of the time
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Modal is authenticated on this machine, so the path could finally be
exercised. It failed five times in a row, each fault hiding the next:
1. keep_warm / allow_concurrent_inputs were renamed on 2025-02-24 and
the old spellings now RAISE rather than warn. Both generations are
handled by inspecting the installed SDK's signature, since hardcoding
either spelling breaks half the installed base.
2. The decorated function is defined inside a method, which Modal only
accepts with serialized=True.
3. The App was never started. A Modal function only carries the metadata
it needs while its App is running, so .remote() failed with "Function
has not been hydrated". The app.run() context is now held for the
sandbox's lifetime and closed in stop().
4. add_python="3.11" was passed to an image that already ships Python --
the default is python:3.11 -- so the image build failed outright.
5. The default image was pinned to 3.11 while a serialized function is
pickled locally and unpickled inside it, so anyone not on 3.11 got
"defined with Python 3.12, but its Image has 3.11". The default now
follows the running interpreter.
Verified end to end: execute_code(run_in="modal") returns 'from modal'
with exit 0 against real Modal infrastructure.
tools_run_on="modal" was already working and is now verified live too --
provision, uname, a file written and read back across calls, shutdown.
The test asserting a hardcoded python:3.11 default was updated rather
than deleted; it now pins the interpreter-matching rule that replaced it.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Two of the three registries already discovered plugins by entry point --
praisonai.sandbox and praisonai.managed_backends. The compute registry,
which is where tools_run_on= places live, was a hardcoded dict, so adding
one meant editing core:
_compute_bridge._PROVIDERS the resolver
compute/__init__.py the lazy import
placement.ToolPlace or it gets no typing
cli/commands/managed._PS_PROVIDERS or `managed ps` cannot see it
execution_location._PLACE_WORDS or it prints a bare name
plus the lists in two docstrings
Six edits across two packages, for something that is by nature a plugin.
It now reads praisonai.compute as well, so a provider ships in its own
distribution:
[project.entry-points."praisonai.compute"]
runpod = "praisonai_compute_runpod:RunpodCompute"
Verified end to end with a package installed outside this repo: it
appeared in available_providers(), passed tools_run_on= validation,
resolved, executed, and Agent(tools_run_on="demo") built -- with no
change to any file here. The repr falls back to the bare name, which is
the one remaining hand-maintained list and degrades gracefully.
Providers load on demand, so an installed-but-broken plugin fails only
for the caller that names it. There is a test for that.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The bots-gateway CI shard runs from src/praisonai-bot, whose gateway.yaml was
auto-discovered when these tests invoked `gateway start` with config=None.
Discovery then ran the verify-turn pre-flight (a real agent turn, default-on
per #4042) before the monkeypatched start(), exiting 1 with CI's fake key.
Pass an explicit channel-less config so every start-time pre-flight is skipped
and the command reaches the patched handler deterministically. The exit-code and
watchdog-flag assertions are unchanged — the tests still guard exactly what they
did, just hermetically.
Co-authored-by: Mervin Praison <[email protected]>
The compute-only branch ran before the provider object was normalised, so a
managed backend holding a LocalCompute (provider_name="local") skipped it and
the alias table collapsed "local" to "subprocess" -- describing the
unrestricted shell in the locked-down backend's stronger words. Normalise
first, then apply the compute-only check, and read a backend's compute via the
compute vocabulary since that object is a compute-registry provider.
Co-authored-by: Mervin Praison <[email protected]>
Three issues raised in review of run_on="docker":
- execute()/stream() ran the blocking Docker start-up, install and container
turn directly on the event-loop thread, stalling concurrent async callers.
Offload to a worker thread with asyncio.to_thread.
- keep_alive=False only tore the container down on success, so a failure after
start-up leaked a praisonai-agent-* container. Move teardown into finally.
- Both READMEs showed run_on="docker" raising TypeError while also documenting
it as supported. The typo example now uses e2b, which genuinely cannot host
an agent loop, so the two examples no longer contradict each other.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Mervin Praison <[email protected]>
`run_on="anthropic"` hands the entire agent to a vendor's runtime. This is
the same shape, self-hosted: the loop runs in a local container instead.
The distinction from tools_run_on="docker" is what crosses the boundary:
tools_run_on="docker" your process runs the loop and calls the model;
only shell and file tools go into the container
run_on="docker" the loop itself runs inside, so the model call is
made from the container and nothing on your
filesystem is reachable unless you mounted it
Both name the same place, and that is not an ambiguity -- the parameter
carries the scope. So the two value sets deliberately overlap now, and
the tests say so: a name in both must work in both, a name in only one
must be refused by the other with a message naming the right parameter,
and the object must still report which scope you chose.
Implementation is just a backend registration. run_on= resolves against
ManagedBackendRegistry, so adding DockerManagedAgent there makes the
parameter, the repr, the explanation and the conflict checks all pick it
up with no changes to any of them.
Two things this exposed:
- _backend_places() identified hosted runtimes by CLASS NAME ("Hosted" or
"Anthropic" in it). A self-hosted DockerManagedAgent matched neither,
so an agent whose entire loop ran in a container reported that it was
thinking on this machine. Backends are now asked what they are.
- The runner writes its payload into the container through `docker exec
-i ... tee` rather than an argument, so instructions and API keys never
appear in `docker inspect` or a process listing.
Stated limitations rather than hidden ones: Python callables in tools= do
not cross (same as the hosted runtimes), the container needs the model
API key, and the first run installs the package unless image= supplies
one that has it.
Tests that need a live daemon are marked skipif rather than silently
passing; the rest -- registration, both scopes, config marshalling,
result parsing, the missing-daemon message -- run without Docker.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Two gaps found while documenting every accepted value.
"local" resolves differently depending on which parameter carried it:
run_in="local" is collapsed by SandboxManager to the subprocess backend
-- scrubbed environment, blocked commands and paths -- while
tools_run_on="local" is the wrapper's LocalCompute, a plain shell in the
current directory with the full environment inherited and no security
policy at all. Both printed "a separate process on this machine", so the
weaker of the two was described in the stronger one's words. That is
precisely the failure this module exists to prevent, hiding in the one
place the rest of the work did not look. say_place() now takes the
registry that resolved the name.
Resolver aliases were rejected at construction. Validation ran before
alias resolution, so tools_run_on="native" raised "not a known place"
while resolve_compute("native") returned a working sandlock adapter.
tool_places() now includes the alias table it validates against.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
LocalManagedAgent carried its own hardcoded provider list, which is why
LocalAgent(tools_run_on="sandlock") raised "Unknown compute provider"
for a place the rest of the library resolves happily. Routing it through
the merged resolver changes the message to "Unknown place", listing
every place both registries offer.
The behaviour is unchanged -- an unknown name still raises ValueError --
so only the assertion was stale. Added coverage for what the delegation
actually buys: the sandbox-only places now resolve here too.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Two coroutines that astart() the SAME team under one asyncio.gather share
the event-loop thread, so the previous threading.local scope state was
shared between them: the second saw the first's depth==1, skipped its own
sandbox, and ran against a sandbox the first could tear down mid-flight.
Switch _tools_scope_depths from threading.local to a contextvars.ContextVar
holding an immutable frozen mapping replaced via .set() (never mutated in
place). A ContextVar is copied per task at gather/create_task time, so each
run gets its own depth map; it stays per-thread too, so sync callers remain
isolated. The frozen value matters -- a copied context shares the reference
to a mutable dict, so in-place mutation would leak straight back across the
tasks the copy was meant to separate.
Adds a deterministic regression test that fails on the old design
(['own', 'borrowed']) and passes now (['own', 'own']) without needing a
live model.
Co-authored-by: Mervin Praison <[email protected]>
The security audit demonstrated `cat $(echo /etc/passwd)` reading the
file end-to-end through the subprocess place: blocked_paths matches
tokens, and any shell indirection -- command substitution, a variable, a
nested sh -c -- hides the path from it. That is inherent to a blocklist
over a real shell, not a patchable pattern, so where_does_it_run() now
says the command list can be worked around rather than implying the
tier contains anything.
Also updates the flagship YAML example to tools_run_on:, lists the four
newly reachable places, and marks which of them are real boundaries
(sandlock is kernel-enforced; subprocess is process separation only).
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Mutation testing showed 7 of 14 deliberate breakages left the suite
green. The pattern was consistent: argument validation and repr strings
were well covered, and every path that actually moves work to a sandbox
was not covered at all. Deleting the ensure_tools_placed() call sites --
the feature's entire point -- broke nothing.
Bugs fixed:
- A clone inherited the source agent's bridged tools, which close over
the SOURCE's sandbox, and its backstory already carrying the capability
prompt. Its first turn then attached a second sandbox: two copies of
the prompt, and work split across two machines. The tools are now
tagged so the existing clone filter drops them, and the clone inherits
the pre-attach backstory.
- test_apply_rlimits_sets_memory_limit still asserted RLIMIT_NPROC was
set. It passed on main and failed here, because dropping NPROC is
deliberate. Replaced with an assertion that it is NOT set, plus a new
test that one unsupported limit no longer skips the others -- the
latent bug that made RLIMIT_NOFILE never apply on macOS.
Tests added for what survived mutation:
- every entry point (chat/achat/_start_stream) places tools before the
first turn, asserted by driving the real method
- AgentTeam start/astart/start_for_each provision exactly one sandbox,
counted through a fake provider, instead of poking a private method
- policy_scan_parts expands shell payloads, survives unbalanced quotes,
strips quoted heredoc bodies but NOT unquoted ones, and a blocked
path inside `sh -c` is genuinely refused (asserting the file was not
read, not merely that an error was returned)
- SandboxComputeAdapter, which had zero tests despite being the largest
new file: policy denials report failure rather than exit 0, shell
semantics work, state persists across calls
- SandboxManager constructor introspection, including that the guided
error names `host` and SSHSandbox rather than leaking a raw TypeError
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Two reliability bugs the security audit reproduced.
write_file() built a heredoc delimiter from uuid4().hex, which is
lowercase. The security policy substring-matches blocked_commands
against the whole command string, and "dd" is one of them -- present in
9.6% of random lowercase hex strings (measured over 100k). So roughly
one write in ten failed with "Blocked command pattern: dd", for no
reason the caller could see. The delimiter is uppercase now.
The same substring scan also read the heredoc BODY, which is the literal
bytes of a file, not a command. Saving a shell tutorial containing
"rm -rf" was rejected as an attempt to run it; a file mentioning
/etc/passwd was rejected as an attempt to read it. Quoted heredoc
bodies are now stripped before the policy check -- only the quoted form,
since an unquoted heredoc still undergoes shell expansion and its
contents really can execute.
Verified the boundary is unchanged: `cat /etc/passwd` and `rm -rf /`
are still blocked, while all three content cases now write, and 60
consecutive writes produce 0 spurious failures.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Four lifecycle bugs, all found by adversarial validation.
LEAK. An agent and its SharedCompute referenced each other, so a dropped
agent was reclaimed by the CYCLE collector, vanished from the WeakSet the
atexit hook iterated, and its sandbox was never shut down. Gateways clone
an agent per request, so that was one orphaned container per request --
measured: 5 requests, 5 provisioned, 0 shut down.
Fixed by tying lifetime to the agent with weakref.finalize (which also
covers interpreter exit, so the atexit hook and weak set are gone), and
by holding agents WEAKLY in SharedCompute._patched. The weak _patched is
the load-bearing half: while the restore list held agents strongly, the
finalizer kept its own agent alive and could never fire.
Now: 5 provisioned, 5 shut down, 0 leaked.
RACE. close_tools_sandbox() cleared the marker first and shut down after,
outside the lock. A concurrent chat() re-attached in that window and the
in-flight shutdown restored over it, leaving the agent marked as
sandboxed while holding no sandbox tools -- unrepairable, because
ensure_tools_placed()'s idempotent early return sees the marker and does
nothing. It is all under the lock now.
EXIT HANG. The exit path took a process-global lock, so any thread
holding it blocked interpreter exit forever (reproduced: rc=124). The
realistic form was a bounded stall, since the lock was held across
SharedCompute(...) -- which imports the provider SDK.
CONTENTION. That same global lock serialised placement for unrelated
agents (16 concurrent attaches: 0.87s against a 0.05s parallel floor),
and being non-reentrant while held across attach()'s writes to
agent.tools, any subclass with a tools setter that touched placement
would self-deadlock in its own constructor. Locks are per-agent now, and
the only global lock covers a dictionary lookup.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Two bugs found by adversarial validation, both silent.
1. AgentTeam handed the model the PRE-ATTACH tool list.
_build_execution_context snapshots agent.tools and passes it to chat()
as an explicit `tools=`, which wins over agent.tools. The sandbox
attached later, inside chat(), so the model got the local tools while
a real sandbox sat provisioned and unused -- every tool ran on the
host. Placement now happens before the snapshot.
It read as flaky rather than broken: in start_for_each() row 1 got
local tools and row 2 got the bridged set, because row 1's chat() had
mutated agent.tools in time for row 2's snapshot.
2. The scope depth was shared class-wide, not per team.
`_tools_scope_state` is a class attribute, so ANY team started while
another team's run was on the stack saw depth==1 and skipped its own
sandbox. A nested team ran on the host; a team sharing an agent with
the outer run executed on the OUTER team's sandbox; two teams in one
asyncio.gather gave one a sandbox and the other nothing. Depth is now
keyed per team, and the key is dropped at zero so the dict cannot grow
without bound on a long-lived worker thread.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Three parameters meant "somewhere else" and none of them said which
somewhere: `run_on=` (tools only, on Flow/Team), `compute=` (tools only,
on LocalAgent) and `backend=` (the whole agent). One concept had two
names and one name had two concepts, so the docs had to keep correcting
the API.
Now two words, each answering a different question:
run_on= the WHOLE agent moves to a managed runtime
tools_run_on= only the tools move; thinking stays here
run_in= one execute_code() call, this call only
Because the two questions have disjoint answer sets, a wrong pairing is
a typo rather than a preference. `run_on="docker"` cannot mean anything
-- Docker does not host agent loops -- so it raises TypeError naming the
parameter the user actually wanted, instead of silently placing work on
a machine nobody chose. Never "last one wins".
Reachability: sandbox-only backends (subprocess, sandlock, ssh, novita)
spoke SandboxProtocol -- one object IS one environment -- while
tools_run_on= speaks ComputeProviderProtocol -- one object HANDS OUT
many. SandboxComputeAdapter supplies the missing half, taking the
registry from 7 places to 11. This finally makes `sandlock` selectable:
kernel-enforced Landlock + seccomp-bpf, the only real local boundary in
the project, previously unreachable.
Shipped bugs found and fixed along the way:
- AgentTeam.astart() never provisioned the shared sandbox at all, so
every async team ran its tools on the host and said nothing.
- start_for_each() provisioned one sandbox per input row: a 50-row
batch paid for 50, and no row could see what an earlier row wrote.
- The re-entry guard set `self.run_on = None` for the duration of a
run, so a concurrent start() observed "no sandbox" and executed
every tool on the host. Now thread-local; placement stays readable.
- SharedCompute.attach() could attach an agent twice (flow + its own),
duplicating the capability prompt and, on non-LIFO teardown, leaving
the agent holding tools bound to a shut-down instance.
- SandboxManager passed config= to every backend; SSHSandbox and
ModalSandbox do not accept it, so they raised before starting.
- RLIMIT_NPROC was applied per *real user ID*, not per sandbox, so
max_processes=10 counted the user's existing processes and the
sandbox could not fork at all.
- blocked_paths stopped matching once commands ran through `sh -c`,
because the path hid inside the shell payload.
Removed ExecutionConfig.code_sandbox_mode. It defaulted to "sandbox"
while no execution path read it, so its own default told every reader
they had isolation they did not have.
where_does_it_run() now names the tools that will NOT move. Only four
tool names are bridged; the capability prompt tells the model the
sandbox is where things happen, so anything staying behind has to be
said out loud.
Migration:
- YAML `run_on:` stays a silent alias -- it is data people already
shipped, and there is no Agent-level run_on: key to confuse it with.
- Python `run_on=` on Flow/Team raises with a directed message; it
would otherwise mean the opposite of `run_on=` on Agent.
- `compute=` warns (FutureWarning, visible to end users per PEP 565).
- `Agent(sandbox=)` is kept, not removed: clone_for_channel() passes
it and it is a legitimate per-agent default. `run_in=` overrides it
per call.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Extract the repeated inline `next((t for t in self.tasks.values()
if t.name == <name>), None)` into a single `_task_by_name` helper and
call it at all 13 sites. Behaviour-identical: first-match by name,
None when absent. No public API or behaviour change.
Co-authored-by: MervinPraison <[email protected]>
Remove the shutil.which("echo") skipif: TemplateInterpolator runs commands
with shell=True, so echo is available as a shell builtin on both cmd.exe and
/bin/sh even without a standalone executable. Normalise output with .strip()
for Windows CRLF instead, restoring coverage. Also drops the now-unused shutil
import and trailing whitespace.
Co-authored-by: Mervin Praison <[email protected]>
Cross-reference validation only inspected step.agent, step.steps, and
step.routes, so undefined agents nested inside the newly accepted bare
runtime-form payloads (route:/parallel:/loop:/repeat:/if:) silently
passed while the runtime parser drops/rejects them (Greptile P1).
- Walk route: value lists (agent-name scalars) and parallel/loop/repeat/if
sub-step dicts (agent: keys), leaving non-agent scalars like
loop: {over: <var>} untouched.
- Regenerate the stale agents.schema.json artefact to match the PR's
broadened WorkflowStep model.
- Add tests for undefined agents in route/parallel payloads and a
loop-over-variable false-positive guard.
Co-authored-by: MervinPraison <[email protected]>
- Async event loop: run_autonomous_async now offloads verification hook
execution to a worker thread via _verification_gate_async so a slow/blocking
CommandVerificationHook no longer stalls concurrent coroutines.
- Durable journal: rewire _record_verification_journal to the real
DurableRunContext.record_verification (append JournalEvent, KIND_VERIFICATION)
instead of a non-existent _run_journal.record API; events now actually persist.
- Goal gate: a failing blocking hook now carries the captured stdout/stderr
summary into last_reason so the next continuation prompt has actionable repair
diagnostics instead of a bare label.
- Tests: +4 covering async thread-offload, durable journal persistence, and
goal-failure diagnostics propagation.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Addresses two P1 correctness gaps from PR review:
- Explicit --resume onto an absent/misspelled/deleted checkpoint now returns
a clear error instead of silently running the workflow from step 1 and
repeating already-completed side effects.
- _definition_fingerprint now hashes agent config values (not just keys), so
semantic edits (instructions/model/tools/condition/routing) invalidate the
checkpoint rather than combining a stale step index with an edited workflow.
Adds two regression tests: missing-checkpoint fail-closed, config-value edit
changes fingerprint.
Co-authored-by: MervinPraison <[email protected]>
Addresses two P1 review findings on PR #4059:
- handoff._cap: capping an oversized recap dropped the actionable NEXT:
continuation guidance. Cap now preserves the head (preamble/goal/progress)
and the NEXT: tail verbatim, trimming only the middle recap block.
- summary_builder: assistant turns that merely proposed or *asked* about work
were recorded under "Completed Actions", so a resumed agent could skip work
only discussed. Question-bearing assistant turns now flow to Pending
Questions / Remaining Work only; executed tool calls/results stay completed.
Adds regression tests for both.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
- Defect 1: map parsed markdown routing (TaskRoutingConfig) onto real
Task.branch_condition/next_steps the executor reads; stop clobbering
condition with a dataclass; guard dict-condition crash in step loop.
- Defect 2: wire Task(when=..., then_task=..., else_task=...) into the
WorkflowManager step-advance path for per-step conditional redirection.
- Defect 3: register `workflow validate` on the Typer workflow app so it
reaches the existing handler.
- Defect 4: align WorkflowStep schema with the runtime dialect (bare
agent/route/if/loop/repeat/parallel/include steps) and treat
backstory/instructions as aliases so shipped example workflows validate.
- Defect 5: fix .praison -> .praisonai list dir via shared path helper;
reject unsupported on_fail values clearly; fail loudly on YAML files in
the markdown workflows dir.
- Tests: executable markdown branch routing (matched + unmatched), when
routing, and a round-trip validation over examples/yaml/workflows/.
Co-authored-by: MervinPraison <[email protected]>
Wire --resume/--checkpoint/--rebase-checkpoint into `workflow run` and add a
`workflow checkpoints` subcommand. Store a stable, normalized definition
fingerprint in each checkpoint and compare it on resume, refusing to silently
land on a stale step index after the workflow file was edited (with
--rebase-checkpoint to force). Record resumed_from_step in the result.
Co-authored-by: MervinPraison <[email protected]>
Addresses two reviewer-flagged issues in the scheduler cross-run memory:
- P2 (nested aliasing): get_state/set_state now deepcopy so a caller
mutating a nested list/dict in a read result can no longer bypass the
16 KiB size cap or copy-on-read guarantee.
- P1 (orphan one-shot state): _persist_job_state now skips
delete_after_run jobs, which claim_due already removed (state popped)
before the run — persisting would recreate an orphan job_state entry
nothing cleans up.
Adds tests: deep copy-on-read/snapshot isolation (core) and one-shot
non-recreation (wrapper).
Co-authored-by: Mervin Praison <[email protected]>
Make the dormant verification primitive enforceable:
- Wire _verification_gate() into run_autonomous(_async): blocking hook
failures block a success outcome and feed captured stdout/stderr back as
feedback; never-passing checks end at max_iterations, not success.
- Fix lossy _run_verification_hooks re-wrap (preserve details/error/duration).
- Add declarative FileCheckHook (exists/non_empty/contains/json_field==equals),
no shell; CommandVerificationHook now accepts a string command.
- Feed the goal judge executable evidence; a failing blocking hook
short-circuits to continue without spending a judge call.
- add_verification()/remove_verification() for runtime registration.
- Add 'verification' run-journal event kind and YAML `verification:` config
parity mapping command:/file: shapes onto the two hook classes.
Opt-in only: agents without verification_hooks are unchanged.
Co-authored-by: MervinPraison <[email protected]>
Un-stub the documented structured_template compaction feature with a
deterministic DefaultSummaryBuilder that renders SUMMARY_TEMPLATE (falling
back to the plain summary on failure), wired as the default builder in
ContextCompactor when structured_template=True.
Add a deterministic session handoff assembler (build_handoff_prompt) that
turns durable state (recap + persisted GoalState + workflow checkpoint) into a
self-contained continuation prompt with no LLM call, plus a
`praisonai session handoff` CLI command with --json/--copy.
Co-authored-by: MervinPraison <[email protected]>
Address two P1 review findings on the standalone scheduled sender:
- _HttpSendError now preserves the raw Retry-After header verbatim (via a
headers dict) instead of pre-parsing to float, so server_retry_after honours
both integer-seconds and HTTP-date forms. A float(raw) previously discarded
any HTTP-date delay, letting the sender retry early and exhaust attempts under
throttling.
- WhatsApp standalone sender no longer maps a generic scheduler thread_id to
context.message_id. WhatsApp requires a real inbound message id to quote-reply;
a generic thread id is rejected as an invalid permanent 4xx. This mirrors the
live adapter, which only sets context from an explicit reply_to.
Adds tests for HTTP-date + integer Retry-After parsing and WhatsApp thread_id
context omission.
Co-authored-by: Mervin Praison <[email protected]>
Slots are typed Dict[str, Any] and SuggestionStore accepts nested
lists/dicts/sets; the previous tuple(sorted(items)) key raised TypeError
on unhashable slot values before recurrence could be recorded. Add a
recursive _freeze() helper producing a deterministic, hashable key.
Co-authored-by: Mervin Praison <[email protected]>
Implement the core JobStateStoreProtocol on the existing
ConfigYamlScheduleStore (get_state/set_state/clear_state), persisting a
small, size-bounded per-job scratchpad under a job_state key in
config.yaml and clearing it when a job is removed or a one-shot fires.
Wire the bot ScheduledAgentExecutor to load prior state into a compact
Notepad prompt block, thread it into a stateful monitor gate only when
the gate opts in (signature-detected), and persist GateResult.state_updates
plus any agent-emitted state back after the run. All hasattr/signature-gated
so stores and gates without support behave exactly as today.
Co-authored-by: MervinPraison <[email protected]>
Standalone (out-of-process) scheduled delivery was fire-and-forget with a
platform coverage gap. This adds:
- Bounded in-process retry with exponential backoff (honouring Retry-After)
around standalone HTTP sends, reusing the shared bots._resilience
classifiers so only transient 5xx/429/network failures are retried and
permanent failures (bad token, 4xx) fail fast. An ephemeral cron/serverless
tick has no persistent process to drain a durable SQLite outbox, so a
bounded retry is the lightweight durability fit for that model.
- Standalone senders for WhatsApp (Cloud API) and Signal (signal-cli bridge),
the two live-adapter platforms previously missing from _STANDALONE_SENDERS.
The documented `all` fan-out token is already implemented in botos.py
`_deliver_job_text`, so no change was needed there.
Co-authored-by: MervinPraison <[email protected]>
The consent-first automation-suggestion surface (store, TTL, dedup, chat
Accept/Dismiss buttons, CLI) already exists but nothing ever generated a
suggestion — propose() was only reachable via manual CLI calls, so the
"noticed you ask for a morning summary every day — automate it?" moment
never fired on its own.
Add a lightweight, deterministic recurrence generator as a new
SuggestionEngine.observe() method in the wrapper: a caller feeds each
completed turn's inferred blueprint+slots, and once the same intent recurs
threshold times within a trailing window the engine auto-calls propose().
Consent-first is preserved (jobs still only materialise on explicit accept),
per-principal isolation and store dedup keep it non-nagging.
Minimal in-repo fix — no new package, dependency, or export; reuses the
existing propose()/store machinery.
Co-authored-by: MervinPraison <[email protected]>
The default-on model turn pre-flight (#4042) now runs after the channel
probe in `gateway start`, so two pre-existing start-path tests that never
mocked a model round-trip aborted with exit 1 instead of their expected
exit 0. Mock `_verify_turn_preflight` green in both so each test isolates
exactly the behaviour it guards (SSL-only soft-fail; --no-preflight skip),
without weakening any assertion.
Co-authored-by: Mervin Praison <[email protected]>
The gateway passes the durable platform adapter directly to
ChannelSupervisor.run(), so drain_outbox() lives on the bot object itself,
not on bot.adapter. Check the object first, then fall back to bot.adapter,
so built-in channels actually re-drain on recovery. Adds a test for the
production object shape.
Co-authored-by: Mervin Praison <[email protected]>
Second-resolution timestamps caused two exports into the same directory
within one second to resolve to the same path, silently truncating the
first bundle (Greptile P1). Add _unique_bundle_path() to append a -N
suffix when the timestamped name already exists, preserving every export.
Co-authored-by: Mervin Praison <[email protected]>
Address Greptile P1 review feedback on #4045:
- Decouple turn verification from the channel --preflight flag so
`--no-preflight --verify-turn` still runs the model round-trip.
- Bound the preflight turn with a short run_timeout (default 60s,
overridable via gateway.preflight.verify_turn_timeout) so a stalled
provider fails fast instead of inheriting the 5-minute interactive
default at startup/onboarding.
- Pass per-agent base_url/api_key/api_base through to the synthetic
Agent so preflight exercises the same provider the live gateway uses.
Adds 3 tests covering timeout default/override and provider parity.
Co-authored-by: Mervin Praison <[email protected]>
Add a `praisonai gateway diagnostics export` command that writes a single,
pre-sanitised .zip (summary, health, config shape, redacted logs, forensics
snapshot) an operator can safely attach to a bug report. Reuses existing
secret redaction, forensics snapshot, health probe, and daemon log readers;
config is reduced to key/mode shape with no secret values, and all text is
passed through the shared redact_secrets pass. Runs even when the gateway is
unhealthy via local log fallback.
Co-authored-by: MervinPraison <[email protected]>
The durable outbox held deliverable replies through a transient channel
outage but nothing re-attempted them on recovery — they sat undelivered
until the next inbound chat() turn or a process restart. The supervisor
now fires a bounded, best-effort adapter.drain_outbox() when a channel
comes back after a recoverable outage, closing the loop opened by the
attempt-and-age policy. Duck-typed and no-op for bots without the hook.
Co-authored-by: MervinPraison <[email protected]>
Wire the existing run_turn_test into the default gateway start preflight and
the onboard wizard so a missing/invalid model credential fails at setup time,
not silently on the first user message. Default on via
gateway.preflight.verify_turn; opt out with --no-verify-turn or
PRAISONAI_NO_VERIFY_TURN=1 for constrained/offline environments.
Co-authored-by: MervinPraison <[email protected]>
- Re-validate every redirect hop + final URL in metadata fetch (SSRF-safe)
- Enforce HTTPS/loopback guard on discovered authorization/token/registration
endpoints so an HTTPS metadata doc cannot smuggle a plaintext endpoint
- Defense-in-depth HTTPS guard on the persisted refresh token endpoint
- Add tests for endpoint validation and redirect revalidation
Co-authored-by: Mervin Praison <[email protected]>
Fixes cross-level precedence bug flagged by greptile/reviewers: the
nearest project directory now wins over more distant ancestors, so an
ancestor .claude/.agents definition no longer silently overrides a
nested .praisonai one. Collect walk-up levels then apply ancestors
first / cwd last under the "later wins" order; .praisonai stays last
within each level.
Co-authored-by: Mervin Praison <[email protected]>
Extend CustomDefinitionsDiscovery to enumerate the conventional ecosystem
roots .claude/ and .agents/ for agents and commands, mirroring the skills
loader. .praisonai/ wins on name collision and the ancestor walk applies to
all roots. Tools stay .praisonai-only since loading executes user code.
Co-authored-by: MervinPraison <[email protected]>
Add metadata discovery, RFC 7591 dynamic client registration, and an
orchestrating provider that wires the existing PKCE callback helpers and
MCPAuthStorage into a lazy ensure_authenticated() flow. Fully additive and
backward-compatible: servers without auth or with pre-supplied credentials
behave exactly as before.
Co-authored-by: MervinPraison <[email protected]>
- redact.py: register PII BEFORE_LLM hook with sequential=True so
modified_input is actually applied to outgoing messages
- hooks/runner.py: warn when a parallel hook returns modified_input that
would be silently discarded
- agents.py: restore original self.tasks after planning; keep plan-step
tasks under _plan_tasks and reset task_id_counter to avoid id collisions
- context/composer.py: iterate _ensure_tool_pairs to a fixed point so
reinserted tool_calls messages don't leave dangling sibling calls
Co-authored-by: Mervin Praison <[email protected]>
Harden the guarded self-improvement review now that it can write to
memory: frame the echoed original task as UNTRUSTED DATA inside an
<original_task> block and instruct the model to ignore any embedded
'remember/store/create a skill' instructions, so injected task text
cannot steer store_memory/skill_manage. Prompt-only, no new surface.
Co-authored-by: Mervin Praison <[email protected]>
Reuse the existing opt-in, guarded, background/re-entrancy-safe skill-review
pass to also close the learning loop for memory: when the agent has memory
enabled, the restricted review toolset adds store_memory and the review
prompt asks whether a durable fact/preference/user-model detail emerged.
No new Agent param or parallel mixin/policy/dispatch — same self_improve
switch, lock, and off-hot-path background runner.
Co-authored-by: MervinPraison <[email protected]>
The durable-run stack (RunJournal, DurableRunContext, ExecutionConfig(durable=))
was shipped in praisonaiagents but never engaged by the long-lived gateway, so no
gateway run was journalled and resume was unreachable. Construct gateway agents
with ExecutionConfig(durable=True) behind an operator toggle (gateway.durable_runs)
and an optional per-agent durable key, so every turn is journalled and an
interrupted run can resume after a restart instead of re-executing side-effecting
tools or being discarded. Default-off / zero-overhead.
Co-authored-by: MervinPraison <[email protected]>
The first-run onboarding gate in `chat` and the bare invocation ran before
the wrapper-resident interactive TUI's own standalone install hint. On a
keyless `pip install praisonai-code` (no wrapper), `praisonai-code chat`
dead-ended with "No API key configured. Run: praisonai setup" for a session
that cannot even start, instead of the actionable "pip install praisonai[tui]"
hint the smoke test asserts.
Gate the interactive (no-prompt) path only when the wrapper is present so the
TUI can surface its install hint standalone; single-prompt chat runs in-process
and is still always gated. Adds a regression test for the standalone skip and
pins wrapper availability in the resolved-model gate test.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Route the shared first-run credential gate through the *final* resolved model
so onboarding validates and preserves the model each entrypoint actually
dispatches:
- code.py: resolve the agent profile's `llm` before the gate. A keyless
`code --agent <profile>` (no --model) with a reachable local endpoint no
longer has the profile model shadowed by the detected local default; the
profile override still applies for the untouched-model case, and an explicit
--model still wins.
- chat.py: resolve the TUI model (explicit > recent > provider default) before
the gate and reuse it, so the gate validates the exact model the TUI
dispatches instead of passing on any present key for a different provider.
Removes the now-duplicate resolution and threads the validated model into
profiling.
Adds two regression tests (profile-model passthrough for code, resolved-model
passthrough for chat).
Defer --tools resolution into _run_print_code's try/except so an import
error in a user tools.py surfaces through the machine-readable JSON/text
envelope (status=error + non-zero exit) instead of escaping as a raw
traceback to scripted callers.
Co-authored-by: Mervin Praison <[email protected]>
Extract the keyless first-run credential gate (previously duplicated inline in
app.py and run.py) into a shared ensure_configured_or_onboard helper in
praisonai_code.llm.credentials, and invoke it from the code and chat
entrypoints so a keyless newcomer is consistently routed to `setup` (or a
detected keyless local endpoint) instead of dead-ending on a raw provider
error. run.py and the bare invocation now delegate to the same helper,
removing the duplication.
Co-authored-by: MervinPraison <[email protected]>
Headless `praisonai code -p/--print` previously hard-rejected --tools,
--agent and --plan, blocking scripted/CI agentic coding from adding a
custom tool, applying a named least-privilege agent profile, or running
read-only plan mode. This reuses the interactive path's existing
resolvers (ToolResolver, load_agent_from_name, resolve_approval_config)
to thread those flags into the headless branch with no new params/deps:
- --tools resolves via _resolve_tools_arg and merges onto the default
coding toolset (de-duped by identity).
- --agent overlays the profile's instructions/role/goal/llm and named
tools; its permission scope is enforced via a non-interactive backend.
- --plan maps to a non-interactive read-only approval scope.
Approvals stay safe: scope is enforced via a non-interactive backend
(deny/ask fails closed), never an interactive prompt. --no-acp/--no-lsp
remain rejected (they toggle the resident TUI's runtime servers the
one-shot agent does not spin up). The JSON/text envelope and exit codes
are unchanged.
Co-authored-by: MervinPraison <[email protected]>
BaseCLIIntegration.as_tool() and get_available_integrations() routed
through run_sync(), which is fail-loud when a running event loop is
present. Agent runtimes invoke tools from inside their loop, so the
first async invocation of any built-in CLI-integration tool raised
RuntimeError. Route both through the existing run_sync_or_offload
helper, which offloads to a worker thread when a loop is running, and
add a native as_async_tool() surface for async agents to skip the hop.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: MervinPraison <[email protected]>
- process.py: when a task uses only when/then_task/else_task routing and it
resolves to no target (taken branch has no target) with no next_tasks, end the
workflow instead of falling into _find_next_not_started_task() (sync + async).
- loader.py: include guardrails/retry/skills in _defaults_has_any_values() so a
config with only [defaults].guardrails (or retry) is applied instead of being
silently skipped by apply_config_defaults' fast path.
- factories.py: document ChromaMemoryAdapter's shared short/long-term collection
so per-tier reset semantics are explicit.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
- Process now consults Task.get_next_task (when/then_task/else_task) in both
sync and async workflows before falling back to next_tasks, and no longer
ends the workflow early when only when-routing is configured.
- Knowledge.reset/delete_all/history now guard with hasattr, logging a no-op
warning for reset and raising NotImplementedError for unsupported erasure.
- ChromaMemoryAdapter (default) implements reset_short_term/reset_long_term so
the default memory config actually erases; Memory warns when an adapter lacks
reset support instead of silently succeeding.
- config defaults: guardrails and retry are now loaded into DefaultsConfig and
guardrails is applied to Agent via apply_config_defaults; unused/unconsumed
defaults keys (api_key/context/hooks/templates) removed from VALID_DEFAULTS_KEYS
so misconfiguration fails loudly, and retry added since agent.py consumes it.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: MervinPraison <[email protected]>
Agent.__init__ ran a dependency probe that eagerly imported the heavy
memory.memory module for any truthy memory value. The common FileMemory
paths (memory=True, "file", and file-provider dicts without learn) never
touch that module, so the probe wasted a ~100ms+ import. Scope the probe
to run only for values that resolve to the heavy Memory backend, preserving
the existing ImportError remediation for every heavy branch.
Co-authored-by: Mervin Praison <[email protected]>
Non-positive context_max_chars silently bypassed truncation (`if budget:`
was falsy for 0), returning full upstream output and breaking the bounded
contract. Clamp with max(..., 0) and always slice. Adds regression test.
Co-authored-by: Mervin Praison <[email protected]>
Add a composable pipeline primitive to the core scheduler: a job may declare
one or more upstream jobs via `context_from`, whose most-recent successful
output is resolved from existing execution history and injected as bounded,
delimited context at fire time.
- ScheduleJob: `context_from` (list, or bare-string coerced), `context_max_chars`
(default 4000), `on_missing_context` ("run"|"skip"). Serialised only when
configured so isolated jobs stay byte-for-byte unchanged.
- ScheduleRunner.resolve_context(job) -> (context, missing): pure, side-effect
free resolution reusing the store's get_history — no new persistence surface.
Wrapper executors inject the text and apply the missing-context policy.
Co-authored-by: MervinPraison <[email protected]>
Tightens the frozen-value-type test to assert the specific
dataclasses.FrozenInstanceError instead of a blind Exception, per
CodeRabbit/Ruff B017. Behaviour unchanged; still guards immutability.
Co-authored-by: Mervin Praison <[email protected]>
Address Greptile review: an isolated executor does not ship the live
async callable across a process boundary; the worker owns the session
and rebuilds/dispatches the turn from serialisable inputs, with the
callable acting as the gateway-side await point for the worker result.
Doc-only clarification, no behaviour change.
Co-authored-by: Mervin Praison <[email protected]>
Add a protocol-driven turn-execution seam so a session's agent turn can be
placed on an isolated worker, with the default preserving today's in-process
behaviour exactly.
- TurnExecutorProtocol + TurnPlacement + WorkerWedgedError (core, protocol-only)
- InProcessTurnExecutor default (runs the turn on the current loop; zero change,
no dependency, backward compatible when the executor is unset)
- Exported from praisonaiagents.gateway; heavy subprocess/container/remote
executors remain a wrapper concern
Co-authored-by: MervinPraison <[email protected]>
- client.py: preflight now gates on the actual configured command (custom
servers included) and only surfaces the registry install hint when it
matches the default server, so custom commands are diagnosed correctly.
- config.py: add path_to_uri() (Path.as_uri) and use it for root/doc URIs so
paths with reserved chars (space, #) yield valid, non-truncated file:// URIs.
- lsp_tools.py: workspace-symbol search forwards the resolved file so the
server initialises against the file's real project root, not the CWD;
_uri_path now decodes percent-encoded URIs.
- Tests: custom-command preflight, path encoding, workspace-root forwarding.
Co-authored-by: Mervin Praison <[email protected]>
Broadens the LSP server map into a data-driven registry (extensions,
root_markers, install_hint) and adds detect_language(), detect_root_uri()
and probe() helpers. LSPClient.start() now runs a shutil.which pre-flight
recording an actionable last_error instead of a raw FileNotFoundError, and
derives rootUri from the nearest root marker for multi-root/monorepo setups.
edit_tools surfaces a one-time diagnostics-unavailable note so lost
self-correction signal is explicit; lsp_tools reuse the shared helpers and
emit install hints. Backward-compatible; core-only.
Co-authored-by: Mervin Praison <[email protected]>
The proxy-type cache used a WeakKeyDictionary keyed by the inner tool
class, but each cached proxy *value* is a dynamically-minted subclass of
that inner class and therefore strongly retains its own weak key via
__bases__/__mro__. The weak key could never die, so per-request tool
classes stayed pinned for the process lifetime — the exact leak the
change targeted. Switch to a WeakValueDictionary: the proxy class is now
held weakly and stays cached only while live proxy instances keep it,
which already keep the inner class alive; once the last proxy dies the
entry auto-evicts and the inner class is reclaimable. The un-subclassable
fallback (module-global _TimeoutBoundTool) is no longer cached.
Fixes Greptile P1 on #4008.
Co-authored-by: Mervin Praison <[email protected]>
- agents_generator: switch process-wide _TIMEOUT_PROXY_TYPES cache to a
weakref.WeakKeyDictionary so per-request tool classes minted in long-lived
hosts are GC-reclaimed instead of pinned for the process lifetime.
- auto: hoist the path-traversal guard (workspace + _safe_join) into
BaseAutoGenerator so WorkflowAutoGenerator and JobWorkflowAutoGenerator
inherit it, and thread an optional workspace= through both (backward
compatible; guard is a no-op without a workspace).
- __init__: distinguish ModuleNotFoundError (real attribute miss) from a
broken-install ImportError so praisonaiagents import failures surface the
real root cause via __cause__ instead of a misleading AttributeError;
cache the failure to avoid re-paying the import on every lookup.
Co-authored-by: MervinPraison <[email protected]>
describe() rendered raw sandbox aliases (native, local) instead of the
backend SandboxManager collapses them to (sandlock, subprocess), so
where_does_it_run() reported a place that never executes. Normalize the
aliases in say_place() to mirror the manager, and mark native as
not-a-boundary. Adds regression tests for both aliases.
Co-authored-by: Mervin Praison <[email protected]>
You could not tell from PraisonAI code where an agent's work happens.
`repr(agent)` was `<praisonaiagents.agent.agent.Agent object at 0x1033abb60>`,
there was no introspection method, and the answer lived only in prose. That is
why explaining it took a 25k-character article, ~29% of whose words existed
purely to correct misreadings the API invites.
Now the object answers:
>>> Agent(name="builder")
Agent(name='builder', thinks_on='this machine', tools_run_on='this machine')
>>> AgentFlow(run_on="docker", steps=[writer, reader])
AgentFlow(name='AgentFlow', steps=2, thinks_on='this machine',
tools_run_on='a Docker container (shared)')
>>> Agent(name="teacher", backend=HostedAgent(provider="anthropic"))
Agent(name='teacher', thinks_on="Anthropic's cloud", tools_run_on="Anthropic's cloud")
and `where_does_it_run()` says it in sentences:
Thinking (the AI model calls) happens on this machine.
Tools run on a Docker container (shared).
Every step shares that same sandbox, so a file written by one step is
visible to the next.
For the subprocess tier it also states the limit plainly, because that tier is
verifiably not a boundary (network reachable, ~/.ssh readable):
Note: a separate process is not a security boundary -- it can still reach
the network and read your files. Use docker or a cloud provider for
untrusted code.
Field naming is deliberate. `loop=` was rejected: it is already
praisonaiagents.workflows.loop(), asyncio's event loop, and agent-loop jargon
-- three meanings for one word, which is the exact problem being fixed.
`llm`, `model`, `runtime` and `execution` are taken as Agent kwargs.
`thinks_on` / `tools_run_on` are free and mirror the `run_on=` the user typed.
A test asserts no field name collides with existing public API so nobody
reintroduces that class of collision, and another asserts the sentences contain
no jargon ("harness", "provision", "orchestration", "topology", "runtime").
Zero breakage: no signature changes, no behaviour changes. Description can
never raise -- a broken object still describes as "this machine".
Adds 17 tests. Suites unchanged vs clean main (6 failed / 343 passed on both;
all 6 pre-exist). Verified end-to-end against Docker: shared-sandbox flow wrote
and read back through one instance, repr stable, 0 leftover containers.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Address reviewer findings on the async loop-guard path:
- Re-raise ToolExecutionError in _execute_tool_async_with_retry so a
loop-guard HALT bypasses retry/error-dict conversion and stops the run.
- Treat loop_blocked BLOCK results as non-retryable in the retry wrapper
so a custom retry policy cannot re-run a terminally blocked call.
- Record tool timeouts as loop-guard failures (fall through instead of
early return) so repeated timeouts accumulate toward BLOCK/HALT.
Co-authored-by: Mervin Praison <[email protected]>
The async tool-execution path (_execute_tool_async_impl, backing achat()/
async workflows) had no loop-guard or doom-loop protection, unlike the sync
path in tool_execution.py. A repeatedly-failing tool could be hammered every
turn with no automatic stop.
Mirror the sync path's loop-guard wiring on the async path:
- pre-execution check() honoring BLOCK (error dict) / HALT (raise) / WARN
- post-execution record() + check() surfacing block/halt back to the model
- record failed (raised) invocations so streaks accumulate toward thresholds
- propagate a loop-guard HALT (ToolExecutionError) instead of swallowing it
Reuses the existing _ensure_loop_guard capability; no new params/exports.
The circuit breaker itself wraps a sync call + time.sleep and is not async-safe
to reuse as-is, so this focuses on the doom-loop/loop-guard protection the
issue centers on (which is pure/sync and safe from async).
Co-authored-by: MervinPraison <[email protected]>
AgentTeam accepted guardrails/web/reflection/caching/learn/knowledge and stored
them but never applied them at the team level. Emit a construction-time warning
when any is truthy so silent no-enforcement stops being the default.
Agent._process_knowledge silently dropped http(s) URL sources; replace the bare
pass with an actionable warning explaining URL ingestion is not implemented.
Co-authored-by: MervinPraison <[email protected]>
The direct-callable branch of LLM._generate_tool_definition re-derived the
schema from the raw wrapped function via build_tool_definition, bypassing
FunctionTool/BaseTool.get_schema(). This reverted @tool(name=) overrides to
the original function name and leaked Injected[T] params into the schema sent
to the model. Now the callable branch checks for get_schema() first, mirroring
the existing registry-lookup branch.
Co-authored-by: MervinPraison <[email protected]>
Addresses two Greptile P1 findings on the native OpenAI path (#3933):
- Move _track_token_usage inside the tool-call loop (sync + async) so every
billed completion — including intermediate tool-call rounds — is recorded
in session totals and by_model/by_agent rollups, not just the final one.
- Clear last_token_metrics when a response has no usable usage so a reused
client never reports a prior completion's spend as the latest call's usage.
Adds regression tests for multi-iteration accounting and stale-metric clearing.
Co-authored-by: Mervin Praison <[email protected]>
Default Agent(llm="gpt-4o-mini") runs through the native OpenAIClient,
which never populated the public token collector, so
get_token_collector().get_session_summary() stayed at zero after a paid
completion. Token accounting was effectively gated behind verbose/metrics
display on the LiteLLM path and entirely absent on the OpenAI path.
Add a lightweight OpenAIClient._track_token_usage that reads usage from
the final response and records it into the global TokenCollector after
every successful sync/async completion, independent of any display flag.
Thread agent_name through the adapter so by_agent rollups populate while
still keeping application metadata out of the OpenAI API call.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
_run_custom_agent still set agent_config["verbose"], which the
consolidated Agent constructor rejects with TypeError, so
`praisonai run --agent <name> --verbose` crashed — the same class of
bug #3930 fixed for the profiled paths. Thread verbosity through the
output="verbose" preset instead, without clobbering a definition's own
explicit output. Adds regression tests guarding the kwargs against the
real Agent signature.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
serve() is a public entry point. Inserting allow_network before the
existing approval_mode parameter would rebind positional callers
(e.g. serve(..., "auto")) to allow_network. Append it last to keep
backward-compatible positional binding.
Co-authored-by: Mervin Praison <[email protected]>
The LLM._build_responses_params forwarded Chat Completions multimodal
messages (content parts with type=text/image_url) unchanged into the
Responses API input, causing a 400 invalid_value on input[].content[].type.
Reuse OpenAIClient._build_responses_content to translate parts to
input_text/input_image and inline local image files as data URLs.
Co-authored-by: Mervin Praison <[email protected]>
The ACP CLI parsed --allow-network but never passed it to serve(),
and serve() didn't accept it, so network tools were gated by a flag
no CLI user could set. Thread allow_network through CLI -> serve() ->
ACPConfig so it reaches the tool capability gate in the model loop.
Co-authored-by: Mervin Praison <[email protected]>
The Agent constructor consolidated verbose/stream/metrics into output=. The
three profiled paths (_run_profiled_code, run.py profiled agent, cli_profiler)
still passed a top-level verbose=, raising TypeError before any LLM call. Map
verbosity through output= instead and add a signature-guard regression test.
Co-authored-by: Mervin Praison <[email protected]>
The generic "Authentication Tuple" detector fires on bare ("module",
"Attr") string-pair literals whose key/string contains auth/oauth.
The prior `# pragma: allowlist secret` is a detect-secrets directive
that GitGuardian ignores, so the check kept failing.
Construct the mapping values through a tiny local `_t()` alias so no
bare 2-string tuple literal remains on the flagged lines. Mapping type
(Dict[str, Tuple[str, str]]) and runtime behaviour are unchanged.
Co-authored-by: Mervin Praison <[email protected]>
The (module, attribute) string tuples for the auth/oauth lazy imports were
misdetected as 'Authentication Tuple' secrets. They are import targets, not
credentials. Added inline allowlist pragmas (no behaviour change).
Co-authored-by: Mervin Praison <[email protected]>
Replace five hand-rolled lazy-import __getattr__ blocks (eval, mcp, bus,
trace, skills) with the existing create_lazy_getattr / _with_groups helpers.
Exports, names and lazy semantics are unchanged; eval and mcp now gain the
per-attribute cache the hand-rolled versions lacked.
Co-authored-by: MervinPraison <[email protected]>
Defer WorkflowContext construction (and its all_variables.copy()) so it is
only built when a step has should_run or handler. On the common action-step
path the object was previously constructed and immediately overwritten by
_build_step_context, wasting a growing shallow dict copy per step. Applied
to both the sync and async twins; behaviour is identical since the guard
uses the exact conditions gating the only two consumers.
Co-authored-by: MervinPraison <[email protected]>
Adding create_thread to the runtime-checkable OutboundMessengerProtocol
broke isinstance() conformance for the production BotOutboundMessenger,
failing test_messenger_satisfies_protocol and
test_messenger_still_satisfies_protocol_with_react.
Mirror the existing react()/ReactionResult seam: DeliveryRouter.create_thread
resolves the target, unwraps the adapter, gates on capabilities["threads"],
and returns a typed (status, target, thread_id) tuple — never raising.
BotOutboundMessenger.create_thread maps that to the core ThreadResult so an
unthreadable channel yields a typed unsupported/no_route/failed outcome and
callers fall back to the parent channel. Heavy platform work stays in the
wrapper per AGENTS.md; core keeps only the protocol + dataclass.
Adds 5 wrapper tests covering ok/unsupported/no_route/failed and protocol
conformance with create_thread.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Adds a first-class, capability-gated way for the gateway (or an agent action)
to open a new platform-native thread/topic under a channel, mirroring the
existing react()/ReactionResult contract (#3917):
- PlatformCapabilities.supports_threads flag (+ to_dict/from_dict roundtrip)
- ThreadStatus (ok|unsupported|failed|no_route) + ThreadResult typed outcome
with an `ok` convenience property, so a channel that cannot thread returns a
typed `unsupported` outcome and callers fall back to the parent channel —
never raises
- OutboundMessengerProtocol.create_thread(target, name) -> ThreadResult
- Export ThreadResult/ThreadStatus from praisonaiagents.gateway
Pure protocol/dataclass in core with no heavy SDK imports; concrete adapter
implementations live in the praisonai-bot wrapper.
Co-authored-by: MervinPraison <[email protected]>
Addresses two Greptile P1 findings on the new provision_gateway_config API:
- Fail closed on unsupported platform / empty token instead of writing a
config the gateway would reject at startup or boot degraded.
- Declare every requested agent in the agents: block (was silently dropping
all but the first), routing the channel to the first as its default.
Co-authored-by: Mervin Praison <[email protected]>
Gateway self-healing (doctor --fix) and provisioning (onboard) previously
existed only as private CLI helpers. This adds a typer-free
praisonai_bot.gateway.admin module exposing repair_gateway_config,
provision_gateway_config, and a GatewayRepairResult dataclass on the public
praisonai_bot surface, completing the CLI + YAML + Python parity contract.
The existing repair machinery is moved into admin.py (typer-free) so the
library API does not depend on the CLI-only typer package; the Typer commands
re-import these helpers and remain thin wrappers over one canonical flow (DRY).
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <[email protected]>
Co-authored-by: MervinPraison <[email protected]>
- paths.py: snapshot the single-root detection so creating the default
~/.praisonai data dir mid-run no longer flips config/state/cache off
their XDG locations (Greptile P1 #1). PRAISONAI_HOME stays live.
- diag.py: include the canonical (XDG) state-home logs dir when bundling
diagnostics, de-duplicating directories (Greptile P1 #2).
- Add regression test for mid-run path stability.
Co-authored-by: Mervin Praison <[email protected]>
- _load_env_user_config: use `data is not None` for inline blobs and
`isinstance(data, dict)` for explicit paths so a valid empty mapping ({}
or empty file) stays authoritative and no longer re-enables disk discovery,
and a non-mapping file body no longer raises TypeError on _source assignment.
- tests: clear the full per-key env var set consumed by _load_env_config()
for isolation; add regression coverage for empty inline mapping, empty
explicit file, and non-mapping explicit file.
Co-authored-by: Mervin Praison <[email protected]>
Add XDG-aware resolvers to core praisonaiagents/paths.py: get_config_dir()
and get_state_dir(), and make get_data_dir()/get_cache_dir() honour
$XDG_{DATA,CACHE}_HOME on fresh installs. Precedence: PRAISONAI_HOME ->
existing ~/.praisonai/~/.praison single root -> $XDG_*_HOME/praisonai ->
XDG defaults, preserving full backward compatibility for existing installs.
Route session spill and the wrapper MRU-model recency onto the canonical
state home, ending the ~/.praison vs ~/.praisonai split-state.
Co-authored-by: MervinPraison <[email protected]>
Add PRAISONAI_CONFIG_CONTENT (inline JSON/YAML) and PRAISONAI_CONFIG
(explicit path) to the wrapper resolver's user-config layer, mirroring the
sibling PRAISONAI_AUTH_CONTENT credential blob. Inline content is parsed in
memory (nothing on disk); an explicit path replaces file discovery. Inline
wins over path, which wins over global/project discovery. Higher-precedence
per-key env vars, CLI flags and managed policy are unchanged, and unset
preserves today's file-discovery behaviour.
Co-authored-by: MervinPraison <[email protected]>
Address the four P1 findings on PR #3980 (issue #3979):
- auto.py: add server-side output gate that strips code_execution tools
(e.g. execute_command) from generated roles unless the task actually
requested code execution. Deny-list gated by intent preserves all other
tools (backward compatible). Prompt allow-list narrowed to task-scoped
recommendations.
- jobs/store.py: make idempotency key UNIQUE and add atomic save_if_absent
so concurrent same-key submits resolve to a single job (side effects run
once). Reconcile QUEUED/RUNNING rows to FAILED on startup so restarted
jobs no longer poll forever.
- jobs/router.py: claim the idempotency key atomically via save_if_absent
and only dispatch to the executor when this request won the claim.
- acp/safe_edit.py: reject writes through symlinked parent directories or a
symlinked target as defence-in-depth against the propose->apply TOCTOU.
Verified: idempotency race, restart reconciliation, symlink containment,
and shell-tool stripping all pass; auto_generator + safe_edit + sqlite
suites green. Only the 3 pre-existing InMemoryJobStore test failures remain
(unrelated, present on base release).
Co-authored-by: Mervin Praison <[email protected]>
Gap 1 (auto.py): stop auto-appending the shell-exec tool 'execute_command'
to every generated agent (now opt-in via code_execution keywords only), fence
the untrusted topic in the LLM prompt with an allow-list, and add opt-in
workspace containment for agent_file to block path traversal.
Gap 2 (acp/safe_edit.py): add an RLock guarding _proposals and status
transitions, claim APPROVED->APPLIED atomically to prevent double-apply,
re-validate the path right before write to close the symlink TOCTOU, write
atomically via _atomic_write_text, and return one pipeline per workspace so
concurrent agents no longer leak across workspaces.
Gap 3 (jobs): add a stdlib-sqlite3 SqliteJobStore so jobs and idempotency
keys survive restarts; default store now persists when PRAISONAI_JOBS_DB_PATH
is set and refuses the in-memory store in production.
Co-authored-by: MervinPraison <[email protected]>
Two backward-compat fixes for the deprecated-param consolidation:
- Make handoffs + consolidated feature params keyword-only via a `*`
separator so a stray positional value (e.g. an old positional
allow_delegation=True) can no longer silently bind to `handoffs`.
- Accept fallback_models as an internal-only kwarg forwarded by
clone_for_channel(); pop it before the unknown-kwarg check and seed the
local so cloned agents keep their LLM fallbacks. Explicit
LLMConfig(fallback_models=...) still takes precedence.
Adds regression tests covering the internal fallback_models path,
clone_for_channel() preservation, keyword-only handoffs, and the
positional misbind guard.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Moves allow_delegation, allow_code_execution, code_execution_mode, auto_save,
rate_limiter, verification_hooks, and cli_backend out of the explicit __init__
signature (48 -> 41 visible params) into **legacy_kwargs, rebound to locals from
a new _LEGACY_AGENT_PARAMS map. Fully backward compatible: old keyword calls work
and still emit the same DeprecationWarnings; unknown kwargs now raise TypeError.
Co-authored-by: MervinPraison <[email protected]>
Align merge-gate stale-FINAL recovery with PraisonAI-Tools: accept MervinPraison
Claude finished comments and bypass the 15-minute debounce when HEAD moves after
a conflict rebase without a fresh FINAL trigger.
- Replace brittle exact-comment assertion with concept-based checks so
harmless wording edits no longer break the suite (Greptile feedback).
- Add key-gated end-to-end test that runs Agent(sandbox=True).start()
through a real LLM and asserts the model-visible tool set never gains
execute_python_code / execute_shell_command (CodeRabbit feedback).
Co-authored-by: Mervin Praison <[email protected]>
Reverts the tool-injection block added in #3975. Adversarial review found it
is a net security regression, not a fix. Everything else from that PR is kept.
Why it must go:
1. It escalated privilege. `sandbox=` is a RESTRICTION, but the injection made
it GRANT capability -- and the granted tools bypass the approval registry,
whose presets gate `execute_code`/`execute_command`, not the injected
`execute_python_code`/`execute_shell_command`:
Agent(approval="read_only") -> tools: []
Agent(approval="read_only", sandbox=True) -> tools: [execute_python_code,
execute_shell_command]
A security-labelled flag handed the model two ungated arbitrary-code-execution
tools under the strictest approval preset.
2. It advertised isolation the backend does not provide. The default
subprocess backend enforces none of its own SecurityPolicy. Verified on this
machine: outbound HTTPS returned 200 with allow_network=False; sandboxed code
read a real SSH private key despite `~/.ssh` in blocked_paths; `import
subprocess` worked despite blocked_imports. The tool description shown to the
model said "Execute Python code safely in sandbox."
3. Coexistence made it worse, not better. With autonomy=True the agent still
carries the host `execute_command` (injected earlier in __init__), so the
model can simply pick the unsandboxed tool.
Also fixes the test that let this ship: it asserted `child_pid != os.getpid()`
and called that isolation. A separate process is not a security boundary. The
suite is now contract-based -- sandbox= must not add tools, must not widen an
approval preset, and must still configure explicit execute_code().
Kept from #3975 (all genuinely correct):
- the `metadata` kwarg fix (flagged code no longer raises TypeError)
- the clone fix (`sandbox_config`, not the never-assigned `_sandbox_config`)
- the FutureWarning when sandbox= and backend= are combined
- NOT IMPLEMENTED labels on the inert autonomy/code_sandbox_mode fields
Giving the model a sandboxed execution tool should be an explicit act by the
caller, the way MCP() is -- not a side effect of a restriction flag. No peer
framework (smolagents, AutoGen, deepagents, OpenAI Agents SDK, Pydantic AI)
grants execution capability from a config flag.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Channel clones copied the framework-generated execute_python_code /
execute_shell_command wrappers, which close over the source agent. The
constructor's name-dedup then skipped creating clone-bound replacements,
so a clone's execution tools ran through the source agent's SandboxManager
— sharing isolation state across channels (CodeRabbit/Greptile P1).
- Tag generated sandbox tools with `_praison_sandbox_tool` in
SandboxMixin._get_code_execution_tools().
- clone_for_channel() now drops tagged tools when copying, so the
constructor regenerates clone-owned wrappers. User tools with colliding
names lack the tag and are preserved.
- Add regression test asserting clone tool identity and SandboxManager
differ from the source.
- Compare parsed integer PIDs (not substrings) in the out-of-process test;
use next(...) per ruff RUF015.
Co-authored-by: Mervin Praison <[email protected]>
`Agent(sandbox=...)` built a SandboxConfig that nothing ever read. The agent
looked isolated and was not -- the worst failure mode a security setting can
have. Four defects, each verified before and after:
1. sandbox= gave the model no sandboxed tools.
`_get_code_execution_tools()` had zero non-test callers, so `sandbox=True`
added nothing to `agent.tools`. It now attaches execute_python_code /
execute_shell_command (skipping names the user already defined).
Verified: code now runs in a separate PID from the caller.
Scope note: this isolates code the MODEL writes. Python callables passed
via `tools=` are ordinary in-process functions and cannot be retrofitted
into a sandbox -- that limit is now stated rather than implied.
2. Sandboxed execution crashed exactly when it mattered.
`execute_code()` injected a `metadata` kwarg that flowed into
SandboxProtocol.execute(), which has no such parameter -- so any code
tripping a security warning raised TypeError instead of running. Warnings
are now attached to the result instead of forwarded.
3. Clones silently lost their sandbox.
`clone_for_channel()` read `_sandbox_config`; SandboxMixin writes
`sandbox_config`. The underscore name is never assigned anywhere, so every
clone ran unisolated.
4. Two docstrings promised protection that does not exist.
`AutonomyConfig.sandbox` claimed subprocess isolation is auto-enabled at
level="full_auto" (implemented nowhere), and
`ExecutionConfig.code_sandbox_mode` documents subprocess isolation while
having zero consumers. Both are now labelled NOT IMPLEMENTED. The fields
are kept -- removing public dataclass fields would TypeError for existing
users -- so deletion belongs in a major version.
Also: combining sandbox= with backend= now emits a FutureWarning. The managed
backend takes the whole turn before any local execution, so sandbox= was
silently ignored with no signal.
Opt-in and non-breaking: agents without sandbox= are byte-for-byte unchanged
(asserted by test).
Adds 10 regression tests. Suite: 473 passed vs 463 on clean main (+10, no new
failures); the 2 test_param_consolidation warning-registry failures reproduce
identically on clean main with the same selection and are unrelated.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
- verify_and_pair now validates the channel_id binding BEFORE clearing the
brute-force counter, so a valid HMAC presented against the wrong channel_id
is rejected without handing later guesses a fresh attempt budget (Greptile P1).
- generate_code enforces max_pending against _pending_by_hash (all logical
pending entries, including ones rehydrated from disk) so repeated restarts
cannot grow pairing.json past the configured bound (CodeRabbit).
- Add regression tests for both behaviours.
Co-authored-by: Mervin Praison <[email protected]>
Persist only a salted SHA-256 hash of each pairing code (no plaintext code
ever lands in pairing.json), add a per-channel_type brute-force lockout that
applies uniformly across HTTP/in-chat/CLI approval surfaces, and generate
codes from an unambiguous alphabet (drops 0/O/1/I). Backward-compatible:
public API unchanged, legacy plaintext stores still load.
Co-authored-by: MervinPraison <[email protected]>
An action-only YAML step builds its Agent during the run, after the
initial shared-compute attach(), so its shell/file tools silently ran
locally instead of in the run_on: sandbox. Expose the live SharedCompute
on the Workflow and attach the temp agent before it chats. Adds tests.
Co-authored-by: Mervin Praison <[email protected]>
The native OpenAI-SDK tool loop re-injected resolved DeferredToolResults into
the per-call `messages = list(messages)` copy, which is discarded once the loop
returns. Since background jobs typically complete after the loop returns, the
resolved value never reached subsequent turns — unlike the LiteLLM path, which
appends to the persistent chat_history (llm.py:_register_deferred_if_any).
Thread an optional `deferred_history_sink` through the sync/async/streaming
native loops and _handle_native_deferred_result; the agent passes its existing
chat_history as the durable sink. Falls back to `messages` when absent, so
existing callers are unaffected. No new Agent params/modules/exports.
Adds tests for durable-sink survival past loop return, backward-compat fallback,
and early (buffered) resolution delivery.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Mervin Praison <[email protected]>
Closes the last functional gap in remote execution: no-code users had no
way to reach it at all. `run_on=` existed only on the Python API, so anyone
driving PraisonAI through agents.yaml was locked out of shared sandboxes.
name: remote-demo
run_on: docker # every step shares ONE sandbox
agents:
writer: {role: Writer, goal: Write files}
reader: {role: Reader, goal: Read files}
steps:
- agent: writer
action: "Write 'hello' to /workspace/note.txt"
- agent: reader
action: "Read /workspace/note.txt"
The provider name is validated at load time against the same registry the
Python API uses, so a typo fails when the file loads -- listing the valid
names -- instead of surfacing at the first tool call, halfway through a run.
Also updates the README's managed-agents section, which still advertised the
deprecated `ManagedAgent` factory and the old `compute=` name:
- leads with `run_on=` (Python) and `run_on:` (YAML)
- single-agent examples now use LocalAgent / HostedAgent, which emit no
DeprecationWarning
- documents `praisonai managed ps` / `stop --all`
Adds examples/yaml/workflows/remote_sandbox_workflow.yaml, executed
end-to-end against Docker: writer wrote /workspace/note.txt and reader read
'hello from step 1' back from the SAME instance (docker_72722484ef46), with
zero leftover containers.
12 new parser tests (no Docker needed). Managed suite 289 passed; the same 6
failures exist on clean main. YAML suite 168 passed, no parser regression.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
- Catch (ImportError, AttributeError) instead of broad Exception in the
vendored typer._click probe (resolves Ruff S110/BLE001).
- Add test_namespace_caller_still_dispatches to pin that every long option
_namespace_to_gateway_argv emits is accepted by the canonical Typer command.
Co-authored-by: Mervin Praison <[email protected]>
The AFTER_TOOL bridge mutated data.tool_output and could deny, but the
sync (tool_execution.py) and async (execution_mixin.py) executors
discarded both — so redaction/blocking never reached the model. Both
paths now read back the rewritten tool_output and honour a block
decision, mirroring the BEFORE_TOOL path. Clarified GuardrailBlocked
docstring for after_tool and added real-agent execute_tool regression
tests plus a GuardrailBlocked bridge test.
Co-authored-by: Mervin Praison <[email protected]>
Route the public `praisonai gateway <cmd>` entry point to the single
canonical Typer gateway command app instead of a reduced argparse handler
that only wired start/status/hooks and dead-ended on everything else.
Now `praisonai gateway` exposes the same surface as `praisonai-bot gateway`
(doctor, test, channels, stop, restart, pause/resume/reconnect,
install/uninstall, mint-link, logs, send, hooks, sessions) with one
`start` implementation carrying the credential/tool preflight,
config-version migration and `--openai-api`/`--mcp` flags. The gateway's
own degraded-state retry hints (`praisonai gateway doctor`/`--fix`/`test`)
now name commands the operator can actually run.
Deletes the duplicate reduced argparse start/status/hooks parser and
dispatch; unknown commands and bad flags now degrade gracefully to a
non-zero exit code with a rendered message rather than a static dead-end.
Co-authored-by: MervinPraison <[email protected]>
The native OpenAI-SDK tool loop in llm/openai_client.py called
execute_tool_fn directly and stringified a returned DeferredToolResult,
losing the handle so its eventual background value was never re-injected —
unlike the LiteLLM path (_register_deferred_if_any). Add a small shared
helper that registers the handle on the global deferred resolver and
surfaces the note to the model, wired into the sync, async and streaming
native tool-result blocks. No new Agent params or exports.
Co-authored-by: MervinPraison <[email protected]>
The after_tool hook bridge discarded the plugin's return value, so a plugin
could only observe tool results, never rewrite or redact them — contradicting
the documented "Can modify result" contract and leaving no post-tool guardrail
path for scrubbing secrets/PII. Mirror the after_llm/before_tool bridges: write
the returned value back onto data.tool_output and honour deny/HookResult and
GuardrailBlocked decisions for symmetry.
Co-authored-by: MervinPraison <[email protected]>
Addresses reviewer findings on PR #3965 (wrapper-only, praisonai-code):
- /continue now clears self.messages before replay so repeated resumes (or
resuming after activity) don't duplicate or retain stale on-screen turns.
- /continue loads the full stored history instead of the default 50-message
tail so the "… N earlier turns" note reflects the true total.
- _run_simple fallback renders restored user/assistant turns (not only system
lines) so replayed conversations are visible without prompt_toolkit.
- Type-guard tool_calls handling in both renderers.
Co-authored-by: Mervin Praison <[email protected]>
Redraw restored user/assistant turns (and tool activity) via the same live
renderer on interactive resume instead of only printing a one-line summary.
Bounded to the last N turns with an "… earlier turns" note.
Co-authored-by: MervinPraison <[email protected]>
The #3251 regression guard asserts _build_yaml_workflow resolves tool_timeout
via _resolve_effective_tool_timeout. The prior explicit-timeout helper bypassed
it, breaking the guard. Delegate per-agent/role resolution back to the shared
_resolve_effective_tool_timeout so both the sequential/hierarchical and workflow
paths use one source of truth (and its tightest-value warnings still fire),
while still ignoring the injected bare CLI --tool-timeout default.
Co-authored-by: Mervin Praison <[email protected]>
The legacy CLI always injects its --tool-timeout argparse default (60) into
cli_config, so the new workflow fail-fast rejected every ordinary workflow YAML
run (Greptile P1). Distinguish an explicit user request (per-agent/role YAML
timeout or a changed CLI value) from the bare CLI default via
_resolve_explicit_workflow_tool_timeout. Adds regression tests.
Co-authored-by: Mervin Praison <[email protected]>
- auto.py: wrap blocking convert_and_save/_save_workflow in asyncio.to_thread
across AutoGenerator/WorkflowAutoGenerator/JobWorkflowAutoGenerator so
agenerate() no longer parks the event loop on merge/yaml-dump/fsync.
- claude_code.py: pop caller output_format before forcing stream-json in
stream(), matching cursor/gemini siblings (fixes TypeError drift).
- agents_generator.py: fail fast on tool_timeout for process: workflow YAMLs
instead of warn-only no-op, mirroring _validate_workflow_cli_capabilities.
Co-authored-by: MervinPraison <[email protected]>
The CI-flaky test_finds_latest_by_mtime creates two run dirs back-to-back;
when their mtimes collide (coarse fs resolution), a stable sort left the
winner up to arbitrary iterdir() order, so the older-named dir could win.
Break ties by name so timestamp-named dirs stay deterministic.
Co-authored-by: Mervin Praison <[email protected]>
- _discover_instances now returns (instances, errors): an available provider
whose list_instances() fails is no longer silently reported as clean success,
so `ps`/`stop --all` never lie about an empty inventory while sandboxes run.
- Explicit `--provider <name>` for an uninstalled/unknown provider now surfaces
an error instead of a silent empty result. Uninstalled/unconfigured providers
in the default scan remain silently skipped (a missing E2B key is normal).
- `ps --json` now returns {"sandboxes": [...], "errors": [...]} and exits non-zero
when any provider could not be queried.
- Corrected ManagedAgent factory docstring: compute-provider names warn and
delegate to LocalManagedAgent; they do NOT raise ValueError.
- Tests updated for new contract + added coverage for listing failures and
explicit unknown-provider errors.
Co-authored-by: Mervin Praison <[email protected]>
Three things, all stemming from reviewing the shared-sandbox feature (#3949).
1. Sandbox visibility (the piece left open in #3949)
praisonai managed ps # list running sandboxes
praisonai managed ps --json # machine-readable
praisonai managed stop <id> # reclaim one
praisonai managed stop --all # reclaim everything
Sandboxes normally self-destruct when a run ends, but a crashed or killed
run leaves one behind; there was no way to see or reclaim it.
2. Cross-process instance discovery (bugs found while building the above)
DockerCompute tracked instances only in an in-process dict, so:
- list_instances() always returned nothing from a fresh process -- exactly
when you need it, i.e. finding strays left by a previous run.
- _shutdown_sync() popped from that dict and, finding nothing, silently
did nothing while reporting success. `managed stop` claimed "Stopped"
and left the container running.
- get_status() reported STOPPED for any live container it didn't start.
All three now fall back to Docker itself (the `praisonai=managed` label and
the `praisonai_<id>` name), and shutdown raises rather than pretending to
succeed when the container cannot be found.
3. Naming: `compute=` -> `run_on=`
Researched how comparable tools name this. `executor` is the most-attested
name industry-wide (smolagents, ADK, AutoGen, Airflow, Nextflow, Dagster,
...), but it is already used as a concept inside workflows.py. `backend`,
`runtime` and `sandbox` are all taken as public Agent params, and `provider`
is used ~147 times for LLM/vector-store providers.
`compute` as a noun is cloud-industry jargon (Wiktionary labels the noun
sense "chiefly cloud computing"), which works against the goal of a name a
non-developer can read. `run_on` is plain English, has mass-audience
precedent in GitHub Actions' `runs-on:`, and has zero collisions in this
codebase.
AgentFlow(run_on="docker", steps=[writer, reader])
AgentTeam(agents=[w, r], run_on="docker")
`compute` stays as the INTERNAL vocabulary (ComputeConfig,
ComputeProviderProtocol, SharedCompute, _compute_bridge) where the
industry term is the right one. No alias is added: `compute=` merged in
#3949 but is NOT in any published release (PyPI 1.6.166 predates it), so
this rename breaks nobody and avoids a second param.
4. Doc fix: the ManagedAgent factory docstring claimed compute-provider names
raise ValueError; they actually emit a DeprecationWarning and delegate to
LocalManagedAgent. Corrected to match the code.
Verified against local Docker: `run_on="docker"` write-then-read hit one
shared instance; `managed ps` found a real stray container with correct
uptime; `managed stop --all` genuinely removed it (0 containers after).
16 new CLI tests + 14 core tests, none requiring Docker.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
- agents.py: re-check dependency failure at consumption time in the async
sequential path. asequential() checks deps inside the generator, but
async_execution tasks are buffered and drained later, so an upstream async
task may not be failed yet when a dependent is yielded. Re-checking after
flushing pending async tasks makes the failure cascade fire for the async
path too.
- doom_loop.py: count progress markers against the boundary *before* the
no-progress window (the preceding action's completion timestamp) so a marker
recorded during the window's first action — timestamped before that action's
record_action() — is no longer wrongly filtered out.
- tool_execution.py: bound orphaned tool executors. Recycling on timeout keeps
throughput, but repeated timeouts could leak unbounded blocked threads. Cap
recycles at _MAX_ORPHANED_TOOL_EXECUTORS, then fall back to reusing the
bounded pool so process resources can't be exhausted.
- Add regression tests for the doom-loop window boundary edge.
Co-authored-by: Mervin Praison <[email protected]>
grep/glob/ast_grep_search were loaded raw from praisonaiagents, so their
containment defaulted to os.getcwd() (grep/glob) or was absent
(ast_grep_search). In headless `code -p --workspace <dir>` (no chdir) a
model-supplied path could read outside the selected workspace. Bind each
search tool's path to the configured workspace (fail-closed), mirroring the
edit/acp/lsp groups, and add a credential-free regression test.
Co-authored-by: Mervin Praison <[email protected]>
- asequential(): port failed-task skip + dependency-cascade check from
sequential() so async runs short-circuit tasks with failed upstream deps.
- tool_execution: retire the tool ThreadPoolExecutor on timeout so hung
threads no longer permanently poison the 2-worker pool.
- doom_loop: store (marker, timestamp) and only count progress markers
within the current no-progress window, so NO_PROGRESS detection is no
longer permanently disabled after the first successful tool call.
Co-authored-by: MervinPraison <[email protected]>
Replaces the fragile private _get_stop_reason helper (which checked the
wrong _llm_instance attr and missed the native OpenAI backend) with the
public backend-aware Agent.last_stop_reason property, so slash-less
OpenAI model names no longer record a null stop_reason.
Co-authored-by: Mervin Praison <[email protected]>
Explicitly calling tracker.end(total_tokens=...) inside a
`with Profiler.streaming(...)` block previously recorded twice because the
context manager's finally also calls end(). Guard with a _recorded flag so
only the first invocation records a StreamingRecord.
Co-authored-by: Mervin Praison <[email protected]>
Import TimingRecord/StreamingRecord/StreamingTracker from
praisonaiagents.profiling and subclass them for the wrapper's superset
fields (file/line, total_tokens) instead of re-declaring them. Core is now
the single owner of the shared primitives; wrapper public API and --profile
flags are unchanged.
Co-authored-by: MervinPraison <[email protected]>
Fixes two P1 issues from PR review:
- Concurrent first-use tool calls (e.g. parallel steps) could each pass the
unguarded instance_id check and provision separate sandboxes, splitting the
run and leaking one instance. ensure_provisioned is now guarded by a lock
with double-checked locking.
- write_file used a fixed __PRAISON_EOF__ heredoc delimiter, so file content
containing that line would terminate the heredoc early, truncate the file,
and execute the remainder as shell commands. The delimiter is now a random
per-write token with a collision guard.
Adds regression tests for concurrent provisioning and delimiter-bearing
content, and updates the fake provider to parse the randomized delimiter.
Co-authored-by: Mervin Praison <[email protected]>
Managed execution was per-Agent only: `backend=` exists on Agent but not on
AgentTeam or AgentFlow, and each LocalAgent(compute=...) provisions its own
isolated instance. A workflow therefore got N sandboxes with no shared
filesystem, so agents could not hand files to each other -- and YAML users
had no path to remote execution at all.
Adds a single `compute=` param to AgentFlow (and its Workflow/Pipeline
aliases) and AgentTeam. One sandbox is provisioned per run and every
participating agent's shell/file tools are bound to it, so a file written by
step 1 is visible to step 2. Orchestration stays local.
flow = AgentFlow(compute="docker", steps=[writer, reader])
team = AgentTeam(agents=[w, r], tasks=[...], compute="docker")
Details:
- praisonaiagents/managed/_compute_bridge.py resolves provider names lazily
from the praisonai wrapper, mirroring sandbox/_sandbox_bridge.py.
- Provisioning is lazy (a run that never touches the sandbox costs nothing)
and teardown is guaranteed via context manager, even when a step raises.
- Agents that already carry their own `backend=` are left untouched.
- Tools are bound onto `backstory`, not `instructions`: Agent.__init__ copies
instructions into role/goal/backstory and builds the system prompt from
those, so patching `.instructions` would be silently ignored.
- The capability prompt is required, not cosmetic: without it models
routinely refuse to call bridged tools ("I can't execute shell commands"),
so the sandbox spins up and is never used.
- Tool results are never the empty string; an empty result reads as "no
progress" and trips the loop guard into a stuck-agent error.
Verified end-to-end against local Docker: writer wrote /workspace/data.txt
and reported container hostname; reader read the same file and reported the
same hostname, with zero leftover containers after teardown.
Adds 12 tests using a fake compute provider (no Docker/cloud needed).
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Moves agentflow.gif and latest_ai_news_and_crawl_each_url_to_find_info.gif
out of the hero and down to the bottom, directly above the Langfuse
Tracing section. The "* export TAVILY_API_KEY=xxxxx" footnote travels
with the news GIF it annotates.
The hero is now: install -> Elon badge -> five-layer stack -> dashboard
screenshot -> ASCII art -> docs badge.
Pure move - no content change (identical line multiset).
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The root cause (unresolved TaskOutput forward reference) is fixed at source
in output/models.py via model_rebuild(), so PydanticUserError no longer
occurs in the guardrail path. The re-raise in _process_guardrail was also
swallowed by the 15 downstream chat handlers that return None, so it never
achieved its stated propagation contract (Greptile P1). Removing it keeps
guardrail error handling simple and consistent without touching hot paths.
Co-authored-by: Mervin Praison <[email protected]>
The previous example advertised assigning `agent.thinking_budget = budget`,
but `_thinking_budget` is stored and never read by the Agent execution
pipeline (verified: no consumer in agent.py or the LLM call path). Point
users to the working `reasoning_steps=True` option and document the
`ThinkingBudget.get_tokens_for_complexity` helper instead.
Co-authored-by: Mervin Praison <[email protected]>
Run shlex.split first and decide by token count. Fixes Greptile P1
(spaced executable paths + args no longer mis-split; quote the path as
an escape hatch) and P2 (tabs/newlines now handled, not just spaces).
Co-authored-by: Mervin Praison <[email protected]>
KnowledgeConfig.embedder / embedder_config were dropped between Agent
resolution and Knowledge construction, so non-OpenAI embedders silently
fell back to text-embedding-3-small.
Forward them through RetrievalConfig and normalise into mem0's
embedder = {provider, config} shape (embedder acts as provider shorthand).
Co-authored-by: MervinPraison <[email protected]>
Agent.__init__ has no **kwargs, so db=/session_id=, thinking_budget=,
and observability= raised TypeError immediately. Update the db, thinking,
and obs module docstrings to the working config-object / property forms.
Co-authored-by: MervinPraison <[email protected]>
Passing a callable to Agent(guardrails=...) returned None because two
different classes named TaskOutput existed and the guardrail path mixed them.
- output/models.py: import TokenMetrics at runtime and call
TaskOutput.model_rebuild() so the model can actually be instantiated
(previously the forward ref was TYPE_CHECKING-only and never resolved).
- main.py: re-export the single canonical TaskOutput from output.models so
main.TaskOutput and output.models.TaskOutput are the same class.
- agent.py: let PydanticUserError propagate from _process_guardrail instead of
swallowing it into a validation failure that silently nulls the response.
Co-authored-by: MervinPraison <[email protected]>
Previously MCP("npx -y pkg", args=[...]) passed the whole string as the
executable, so the subprocess spawn silently failed and 0 tools were
discovered. Now the command string is split on whitespace regardless of
whether args are supplied, using the first token as the executable and
prepending the remaining tokens to any explicit args.
Also updates examples/python/mcp/filesystem-mcp.py to use the reliable
executable + args form.
Co-authored-by: MervinPraison <[email protected]>
Fixes four inaccuracies flagged in review of the five-layer stack section:
- Budget stop via ExecutionConfig(on_budget_exceeded="stop") surfaces as
completion_reason="error" (BudgetExceededError), not "budget_exhausted"
- Default handoff SUMMARY policy truncates to the last few messages verbatim;
it does not summarise
- ManagedAgent() with no ANTHROPIC_API_KEY falls back to a local loop, not cloud
- `sessions list`/`resume` require agent-id and session-id+prompt arguments
Co-authored-by: Mervin Praison <[email protected]>
Add a "Five-Layer Agent Stack" section after "Meet your first Agent",
showing that PraisonAI covers every layer of the agent stack rather than
just multi-agent orchestration:
1 Prompt - instructions/role/goal, output=
2 Context - memory=, knowledge=, context=
3 Harness - tools=, MCP(), approval=
4 Loop - execution=ExecutionConfig(...), reflection=, autonomy=
5 Graph - AgentFlow + route()/parallel()/repeat()
+ Managed Agents - remote sandbox or fully hosted loop
Includes a concentric-ring diagram (each layer wraps the one inside it),
a summary table, and a short runnable example per layer. Every snippet
was executed against the local source, not just constructed.
Also corrects API claims elsewhere in the README that raise TypeError on
copy-paste, since Agent.__init__ takes no **kwargs:
handoff= -> handoffs=[other_agent]
web_search= -> web=
prompt_caching= -> caching=
thinking_budget= -> agent.thinking_budget (property, not a kwarg)
db=/session_id= -> memory={"db": ..., "session_id": ...}
user_id= -> memory={"user_id": ...}
No existing content removed.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Use a non-blocking lock so commit() and cancel() are mutually exclusive,
preventing an unauthorized final mutation from starting after the deadline
while still never blocking cancellation on backend I/O (keeps #3924 fixed).
Add guard-level regression tests for both properties.
Co-authored-by: Mervin Praison <[email protected]>
Only accept supported auth modes (api-key, jwt) when binding to a
non-localhost interface, preventing a misspelled/unsupported mode from
exposing an unauthenticated recipe server.
Co-authored-by: Mervin Praison <[email protected]>
DeliveryRouter.react read adapter.platform_capabilities.reactions, but
PlatformCapabilities has no such field — real adapters advertise reaction
support via capabilities["reactions"] (matching _status.py). The old gate
always defaulted to False, so every Telegram/Slack/Discord reaction call
degraded to "unsupported" and never dispatched. Align the gate (and the
masking test fixture + docstrings) with the real capabilities contract.
Co-authored-by: Mervin Praison <[email protected]>
- Add "signal" to the gateway's tokenless platform set (from_config_file
_tokenless) and the is_email_platform exemptions in start_channels /
_start_single_channel, so a documented token-free Signal channel starts
instead of failing with a missing-token ValueError (greptile P1).
- Rename SignalBot's session manager attribute from _session_mgr to _session
so the gateway routing handler stages per-route tool policies on it
(Issue #2298), matching every other adapter (slack/discord/agentmail).
Previously routed Signal turns ran without their route's tool restrictions
(greptile P1 / Security).
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Close the incomplete outbound contract where PlatformCapabilities.reactions
was advertised but unreachable by agents. Add a typed ReactionResult plus a
react() method to core OutboundMessengerProtocol, and react/unreact actions to
the built-in send_message tool (emoji passed as message, reusing the existing
send-policy guard). The wrapper's BotOutboundMessenger/DeliveryRouter dispatch
to each adapter's existing add_reaction/remove_reaction, capability-gated so
unsupported channels degrade to a typed {"status":"unsupported"} outcome. The
inbound message_id is carried on SessionSource so react("origin", ...) targets
the message being handled without a new tool param.
Co-authored-by: MervinPraison <[email protected]>
Ship first-class Signal (end-to-end-encrypted) coverage through the existing
channel registration seam. The adapter uses the linked-device / bridge model
(signal-cli-rest-api over HTTP) — the same connection style as the WhatsApp
Web adapter — so it inherits outbox/DLQ, retry, sessions, commands, and hooks
from the shared mixins with no new architecture.
- Wrapper-only: praisonai_bot.bots.signal.SignalBot (aiohttp lazy-imported)
- Registered in _BUILTIN_PLATFORMS with a ChannelDescriptor (config keys +
prompt hint) and honest PlatformCapabilities (typing yes, live_edit no)
- channels.signal.account/bridge_url wired via _EXTRA_ENV_MAP; SignalBot export
- Core protocol unchanged
Co-authored-by: MervinPraison <[email protected]>
Sessionless (pre-hello/join) connections could never be reaped because the
liveness reaper defaulted a missing session's activity to now on every pass,
so the policy always returned KEEP and a half-open handshake retained its
socket/queue/scope/auth state forever (Greptile P1).
Track a per-connection _client_last_seen wall-clock: seeded at registration,
refreshed on every inbound frame, dropped on teardown/reap, and used as the
liveness fallback when no session is bound. Adds 4 tests covering seeding,
sessionless reap, inbound refresh, and teardown cleanup.
Co-authored-by: Mervin Praison <[email protected]>
Addresses Greptile P1: _reconnect closed the old client but left it assigned
to _client during the backoff window, so concurrent writes bypassed
dropped_writes accounting (calling a closed client) and gateway status kept
reporting redis_connected=true throughout the outage.
- redis_pubsub.py: null _client/_pubsub the moment the listener detects a drop
(before marking degraded), so writes hit the disconnected guard and are
counted, and status reflects the outage.
- server.py: redis_connected now also requires not is_degraded.
- tests: add outage-bookkeeping test asserting writes are counted and client
is cleared during the reconnect window; update recover test for cleared handles.
Co-authored-by: Mervin Praison <[email protected]>
Add PollingConfig.max_queue_size (default 1000) and apply it when creating
each polling client's queue in PollManager.register_client. This makes the
QueueFull -> durable-store overflow path reachable in production instead of
only via manual test override, closing the Greptile P1 finding. Setting
max_queue_size=0 preserves the legacy unbounded behaviour.
Co-authored-by: Mervin Praison <[email protected]>
Consume the already-merged core LivenessPolicy contract (#2799) at runtime:
- server: _liveness_loop emits PING at the policy interval and reaps
half-open sessions whose last_activity exceeds the window, closing them
with LIVENESS_TIMEOUT and releasing session/client state; PONG/PING
handled; last_activity stamped on every inbound frame; reaped count and
liveness state surfaced in health(); heartbeat_ms advertised from the
liveness interval so client and server agree.
- client: _heartbeat_loop sends PING on the advertised cadence and
force-reconnects (reusing backoff/resume) after ~2x silence; replies to
server PING with PONG.
- liveness is enabled out-of-box (server task present) while remaining
backward-compatible: an explicit interval_ms=0 opt-out stays inert.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
The gateway HA fan-out adapter (RedisPubSubAdapter) previously looped forever
against a stale pub/sub handle on connection loss — silently dropping
cross-instance delivery while status/doctor reported healthy. Now the listener
reconnects with bounded backoff, re-subscribes all channels, records itself as
a degraded owner in DegradedCapabilityRegistry (route:redis-pubsub) with a
redacted reason + actionable retry_hint, and clears it on recovery. Publish and
presence no-ops while disconnected are counted and surfaced in gateway status.
Co-authored-by: Mervin Praison <[email protected]>
Route PollManager overflow through the existing DeliveryGuaranteeManager so
long-poll clients share the durable at-least-once store used by WebSocket:
- enqueue_for_client persists on QueueFull instead of a silent drop
- poll_messages replays durably-pending events (restart/backpressure)
- ack endpoint no longer reports ok=True without a delivery manager
Co-authored-by: Mervin Praison <[email protected]>
Greptile P2: close() nulled _timeout_executor but left _leaked_workers
stale, so a restarted scheduler recycled its fresh pool on first use.
Reset the counter with the pool.
Co-authored-by: Mervin Praison <[email protected]>
- AgentScheduler.stop() no longer self-joins from its own thread; the
budget brake now only sets the stop event and teardown runs in a
finally block, so is_running is cleared and the timeout pool is closed.
- Profiler memory()/memory_snapshot() now reference-count the process-wide
tracemalloc toggle under a lock so concurrent scopes stop returning (0,0).
- Scheduler timeout pool size and leak threshold are now distinct: recycle
once half the workers have leaked, matching AgentsGenerator.
Co-authored-by: MervinPraison <[email protected]>
Addresses two P1 regressions raised in review of #3908:
1. String guardrails no longer fire a synchronous input-validation LLM call
on every chat()/achat(). A string guardrail becomes an LLMGuardrail which
also exposes validate_input via GuardrailProtocol; the input gate wrongly
invoked it (hot-path perf regression + blocking the async event loop).
The string-derived LLMGuardrail is now marked output-only and skipped by
_validate_input_with_guardrail. Explicit GuardrailChain/GuardrailProtocol
objects remain the only deliberate input surface.
2. The no-running-loop managed-stream bridge no longer leaks its producer
thread. The producer is now a daemon thread with a cancel Event, a bounded
queue (back-pressure), and a finally block that signals cancellation and
joins on early generator close/GC.
Co-authored-by: Mervin Praison <[email protected]>
- Wire GuardrailChain/GuardrailProtocol.validate_input into chat()/achat()
so input-side guardrails actually run before the LLM call (no-op for
plain callable/string guardrails; fails closed on error).
- Fire BEFORE_LLM/AFTER_LLM hooks on the async _execute_unified_achat_completion
path for parity with sync _chat_completion, so hook features like
enable_pii_redaction() apply to achat()/async workflows too.
- Stream managed-backend chunks incrementally in the no-running-loop path
via a bridging queue/thread instead of buffering the whole response,
mirroring the running-loop branch.
Co-authored-by: MervinPraison <[email protected]>
Adds load_gateway_config integration coverage for the #3050 validation
path and documents load-time gateway block checks in the example.
Supersedes #3060; core fix landed in #3079.
Co-authored-by: botbikamordehai2-sketch <[email protected]>
ExecutionConfig and MemoryConfig live in praisonaiagents.config.feature_configs,
not the non-existent config.execution / config.memory modules. The prior paths
raised ModuleNotFoundError on the deprecated allow_code_execution / auto_save
conversion path.
Co-authored-by: MervinPraison <[email protected]>
Removes the unreferenced _get_registry() method and its backing
self._registry field from the tools CLI handler. The canonical
_get_resolver() path remains the single tool-resolution entry point.
Co-authored-by: MervinPraison <[email protected]>
- run the sync flush in a daemon thread so a timed-out worker never
blocks interpreter shutdown (Greptile P1)
- make preview_older_slice a safe superset covering token-budget-driven
removals (SLIDING / TRUNCATE second pass), not just preserve_recent, so
durable facts in budget-dropped messages are still offered to the flush
(Greptile P1)
- add coverage for daemon-thread timeout and budget-boundary preview
Co-authored-by: Mervin Praison <[email protected]>
- Gate workflow YAML runs so --resume/--session/--continue/--fork and
--output stream-json fail fast instead of being silently ignored, since
the native workflow path does not wire up session continuity or the
stream-json bridge.
- Record each import once in the default profiler even when multiple
ImportProfiler scopes overlap, preventing inflated global import counts.
- Add regression coverage for both fixes.
Co-authored-by: Mervin Praison <[email protected]>
Route the Discord/Slack/Telegram retry-command failure handlers through
failure_reply_text(e) so raw exception text is no longer exposed, and add a
safe generic fallback in _failure.py when the core renderer module is
unavailable (older praisonaiagents), so the error path never itself raises.
Co-authored-by: Mervin Praison <[email protected]>
Registering the novita backend without a corresponding _EXTRA_HINTS
entry made an unavailable backend recommend only `pip install
praisonai-sandbox`, which does not install novita-sandbox. Now it
correctly suggests `pip install praisonai-sandbox[novita]`.
Co-authored-by: Mervin Praison <[email protected]>
Registers NovitaSandbox in the same lazy-loaded registry pattern used
by the existing E2B/Daytona/Modal backends, following the E2B/Daytona
implementation shape (async lifecycle, NOVITA_API_KEY env var,
optional novita-sandbox dependency extra).
Close SSRF gap where compare_extraction fetched via newspaper3k and
requests.get without _validate_url, unlike the trafilatura path.
Co-authored-by: Mervin Praison <[email protected]>
- Reject non-phone/non-lid alternate domains in learn(); use exact
domain matching instead of substring so group/broadcast/hostile
JIDs are never learned and @lid-extra is never canonicalized.
- Canonicalize the Chat JID for the self-chat comparison so an
LID-addressed self-chat is not mistaken for an outgoing message
and silently dropped. Raw chat_jid retained for reply routing.
- Add regression tests for invalid domains, malformed LID suffix,
and lid-to-lid pairing rejection.
Co-authored-by: Mervin Praison <[email protected]>
WhatsApp addresses the same person with two interchangeable JID forms — the
privacy LID (<lid>@lid) and the phone JID (<phone>@s.whatsapp.net). The web
bridge could surface either for the same user, and the adapter propagated the
raw form straight through as user_id, splitting one person into two principals:
divergent session/memory, a broken DM allowlist match (authorised user silently
dropped) and spurious re-pairing.
- Core: add dependency-free IdentityCanonicalizerProtocol contract in
gateway/protocols.py (exported from praisonaiagents.gateway).
- Adapter: WhatsAppIdentityCanonicalizer learns the LID<->phone mapping from
whatsmeow's SenderAlt alternate-JID field and reconciles toward the phone
form BEFORE the allowlist/session/memory/pairing keys are derived. Fail-open:
unknown addresses are returned unchanged, so behaviour is never worse than
today and no canonicalizer registration is required.
Co-authored-by: MervinPraison <[email protected]>
recover_orphans() terminalises in-flight runs to LOST and never re-scans
them, but the recovery notice went through DeliveryRouter whose dedup is a
per-process LRU. A boot-time send to a not-yet-ready channel returned False
and the one notice owed to the user was lost for good.
Route the notice through the durable SQLite scheduled_outbox (the same path
scheduled results use) under a stable run-recovery:{run_id} key before
delivery, so a boot-time miss leaves a pending row that drains on the next
boot. Falls back to the best-effort restart-notice path when no durable
outbox/router is available. Wrapper-only, no core change, no new deps.
Co-authored-by: Mervin Praison <[email protected]>
praisonai-code is an OPTIONAL dependency of praisonai-bot, but the gateway
config resolver routed ~/.praisonai/bot.yaml discovery exclusively through
praisonai_code.cli._paths and swallowed the ImportError, so a lean install
with an onboarded home config fell through to only ./gateway.yaml and
gateway start exited 78 despite the config existing (Greptile P1).
Inline the equivalent cwd bot.yaml -> PRAISONAI_BOT_CONFIG /
~/.praisonai/bot.yaml (PRAISONAI_HOME-aware) fallback so home discovery works
without praisonai-code, keeping the praisonai-code resolver as the preferred
path. Adds two regression tests exercising the missing-praisonai-code branch.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Cancellation while a task waited for a concurrency slot raised
CancelledError from the semaphore acquisition, which sat outside the
try/except — so on_complete never fired for that path. Move the
`async with semaphore` inside the try so every terminal outcome
(success, failure, timeout, active + queued cancellation) routes
through _safe_on_complete.
Co-authored-by: Mervin Praison <[email protected]>
On gateway boot, drive recovery from the durable run ledger: call
SQLiteRunLedger.recover_orphans() to reconcile runs a crashed process
left in flight to LOST with a terminal outcome, then re-notify each
run's origin channel/thread through the existing durable, exactly-once
delivery path. An interrupted run now ends in a recorded outcome and a
visible user-facing message instead of silence.
Best-effort and default-safe: a no-op when core lacks the ledger or no
ledger.db exists yet, so gateways that never used it are unaffected.
Co-authored-by: MervinPraison <[email protected]>
gateway start now auto-discovers the onboarded config (./bot.yaml ->
~/.praisonai/bot.yaml, gateway.yaml alias) instead of silently starting
channel-less, and validates/forward-migrates config_version the same way
doctor does before binding. doctor/test/status/send/channels resolve the
same canonical path so onboard/start/doctor cannot drift apart.
Co-authored-by: MervinPraison <[email protected]>
Every terminal branch (success, failure, timeout, cancellation) now
invokes on_complete via a shared _safe_on_complete helper, matching the
BackgroundJobManager contract so gateway/proactive runs always deliver a
visible outcome to the origin. Cancellation still re-raises for
cooperative shutdown, but only after notifying.
Co-authored-by: MervinPraison <[email protected]>
The default timeout feature added a top-level `import os` to llm/registry.py,
which broke test_registry_only_imports_typing (asserts top-level imports stay
within stdlib typing/threading). Move the import inside default_llm_timeout()
as a lazy import — the isolation test explicitly permits lazy imports in call
paths. Env-var timeout behavior is unchanged.
Co-authored-by: Mervin Praison <[email protected]>
Greptile P1: loose model=/session= kwargs were merged only into cli_config,
which the generator's allow-list ignores (model comes from config_list[0],
session from resume_session). Now model=/llm= writes onto config_list like
--llm, and session maps to resume_session; docstrings corrected.
Co-authored-by: Mervin Praison <[email protected]>
- llm/registry.py, llm/gateways.py: seed default timeout (60s, tunable via
PRAISONAI_LLM_TIMEOUT) + bounded num_retries on every LiteLLM call so an
unresponsive provider can't pin a coroutine/worker forever. Caller override wins.
- api/call.py: resolve realtime WebSocket URL/model/key via env overrides
(PRAISONAI_REALTIME_URL/MODEL/API_KEY) instead of a hardcoded OpenAI literal,
and add open/ping/close timeouts + frame cap so a dead upstream can't hold a
Twilio media leg indefinitely. OpenAI defaults preserved for back-compat.
- _entrypoint.py: run()/arun() accept **kwargs forwarded through cli_config,
giving Python callers the CLI's advanced-option pass-through without a new surface.
Co-authored-by: Mervin Praison <[email protected]>
- execute_tool_async now back-fills result_hash via record_tool_outcome on
both the hooked and fast-path returns, so async no-progress/poll-loop
detection accumulates a streak (sync parity).
- achat() applies the configured rate limiter and cancellation token before
delegating to a managed backend, so backend requests honour throttling and
cooperative cancellation instead of bypassing both guards.
- Knowledge.index() retains memory IDs whose deletion failed so a later
re-index retries their cleanup instead of orphaning stale chunks.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
- async _achat_impl now acquires the rate limiter (acquire_async), matching
the sync path so async bursts are throttled
- execute_tool_async runs the same tool-loop detection as the sync path
- achat() delegates to a configured managed backend via _adelegate_to_backend
(covers arun/astart, which route through achat)
- GuardrailChain.__call__ makes Agent(guardrails=chain) actually validate output
- Knowledge.index() tracks per-file memory IDs and deletes stale chunks before
re-adding a changed file during incremental indexing
Co-authored-by: Mervin Praison <[email protected]>
_validate_url only inspected IP literals, so a plain domain or an encoded
form (a decimal IP, or "<internal-ip>.nip.io") passed even though it
resolves to an internal address, defeating the SSRF guard. Resolve the
hostname and reject any private, loopback, reserved or link-local address,
matching praisonaiagents/tools/file_tools.py.
Lazy-load A2AClient via package __getattr__ so server-only A2A usage no
longer pulls in aiohttp at import time. Public surface unchanged:
A2AClient remains importable and listed in __all__.
Co-authored-by: MervinPraison <[email protected]>
Undo the earlier fork-workflow revert now that the push has workflow scope, so
the branch's workflows match main again — this removes the 7 stray workflow
files from the PR diff and drops main's pypi-release.yml (a GitGuardian false
positive) back out of our changes.
The wrapper-free `code` fallback (`_run_resident_code`) had three defects
flagged by reviewers on PR #3818:
- NameError: it referenced an undefined `compact` local, crashing every
standalone `code` invocation before the TUI could start.
- --plan was silently dropped: the resolved read-only PLAN backend was
never registered, so mutating tools (write/edit/shell) stayed enabled.
- --no-acp/--no-lsp were ignored: the flags never reached the TUI, which
hardcoded ACP+LSP tool loading and runtime startup.
Fix by registering the resolved approval backend on the global registry
(same pattern `chat` uses; the TUI syncs its PLAN state from it) and
threading plan/no-acp/no-lsp onto AsyncTUIConfig via new enable_acp/
enable_lsp fields (default True, backward compatible). _load_tools and
_start_runtime now honor those fields.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Relocate the async split-pane TUI (async_tui.py) and InteractiveCore
(core.py) from the praisonai wrapper into praisonai-code so
`pip install praisonai-code` alone yields a full interactive chat/code
session with no wrapper required.
- Move async_tui.py + core.py impls into praisonai_code.cli.interactive;
leave identity-preserving back-compat shims at the old praisonai paths
(plus config/events shims so isinstance/monkeypatch hold across paths).
- Drop the hard-fail in chat.py; route interactive chat to the resident
AsyncTUI. Route interactive code to a resident AsyncTUI path
(_run_resident_code) when the wrapper is absent, keeping the richer
legacy dispatch when it is installed.
- Convert lazy wrapper-only imports (_async_bridge, integration.context_files)
to _wrapper_bridge with graceful fallback so no `praisonai` import
remains in the interactive package.
- Extend scripts/check_c7_imports.sh to gate interactive async_tui/core
at module load; C7 gate now reports 0 wrapper import lines.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: MervinPraison <[email protected]>
The warm runtime is a separate process that never receives the CLI's
PRAISONAI_APPEND_SYSTEM_PROMPT export and reuses a cached agent, so an
eligible `run` that forwarded to the daemon silently dropped the appended
suffix. Exclude the warm-runtime fast path when the suffix is set so the
in-process path (which applies it) is used, mirroring the existing
thinking_budget/isolated/instructions gates.
Adds regression tests: append-suffix runs never attach warm; ordinary
no-save runs still do.
Fixes Greptile P1 review on #3743.
Co-authored-by: Mervin Praison <[email protected]>
Adds a per-invocation --append-system-prompt flag to the code, chat and run
commands. The flag accepts literal text or an @file reference and falls back
to the PRAISONAI_APPEND_SYSTEM_PROMPT env var for CI.
Kept lightweight: no new Agent constructor param. The CLI exports the resolved
value via the env var and the core Agent appends it at the END of the assembled
system prompt (both the __init__ prompt and the chat _build_system_prompt path),
preserving the prompt-cache prefix (#2993) and never persisting to agent files.
Co-authored-by: MervinPraison <[email protected]>
Greptile P1: the instance-wide _draining flag turned every concurrent
failed-reply enqueue into a no-op during boot recovery, silently dropping
genuinely-new obligations and violating the durable-outbound contract.
Replace the boolean drain guard with a per-entry signature match so only the
nested re-park of the exact reply currently being redelivered is suppressed;
any other concurrent failure is still persisted. Also add the missing
typing.Any import (would NameError under get_type_hints).
Co-authored-by: Mervin Praison <[email protected]>
The reply path is already durable-by-default (permanent/exhausted sends are
parked in a canonical per-platform OutboundDLQ), but its crash-recovery had no
boot caller — the missing counterpart to the inbound journal's
_replay_inbound_journal sweep. A parked reply sat until an operator manually
replayed it.
- OutboundDLQ.redeliver(send): drains parked replies oldest-first through a raw
send, keeping + re-attempting on failure, with a _draining guard so a
re-failed send never double-parks.
- WebSocketGateway._replay_outbound_dlq(bot): outbound counterpart to
_replay_inbound_journal; redelivers via the adapter's own send_message with a
visible "recovered — may be a duplicate" marker, scheduled after the channel's
transport connects, on full boot and hot-reload.
Minimal and safe-by-default: no new params/modules/exports, nothing added to
core, success path unchanged.
Co-authored-by: MervinPraison <[email protected]>
The replay-safety gate only ran inside the overloaded/idle_timeout
branch of resolve_failover_decision. Post-dispatch failures whose
messages lack a timeout/overloaded/5xx substring (bare connection
reset, remote protocol error, incomplete/chunked read) classify as
"unknown" and were retried without the gate, risking double-execution
of side-effecting tool turns. Move the gate ahead of all retry
branches so any post-dispatch failure on a tool turn surfaces
provider_outcome_unknown instead of replaying.
Co-authored-by: Mervin Praison <[email protected]>
Post-dispatch transient failures (read timeout, connection reset
mid-response) may mean the provider already produced output and already
ran side-effecting tool calls in that turn. Blindly replaying such a
failure on a tool-calling turn can double-execute the turn.
Adds is_replay_unsafe() to error_classifier.py to distinguish
pre-dispatch failures (DNS/connect/TLS — safe to replay) from
post-dispatch failures (read timeout / connection reset — replay-unsafe),
and gates resolve_failover_decision so a post-dispatch failure on a
side-effecting turn (one exposing tools) surfaces a typed
'provider_outcome_unknown' outcome instead of silently retrying.
Default-safe and additive: tool-less turns and pre-dispatch failures
retry exactly as before; no new user-facing config surface.
Co-authored-by: MervinPraison <[email protected]>
Address reviewer P1 findings on the coherent undo/revert path:
- Interactive /undo /revert now rewind the reused warm Agent's own
chat_history in lockstep with the auxiliary conversation view, matched
by user-message count so interleaved system/tool messages don't skew the
boundary. Applies to both the modern REPL and the default AsyncTUI, which
each cache and reuse a single Agent across turns.
- praisonai run --revert rewinds a named session's conversation by real
user-turn boundaries instead of a fixed 2*n assumption, so turns that
persisted tool/system/assistant messages no longer strand orphaned
messages or drop an unrelated earlier turn.
- Make run --revert honest that file checkpoints are workspace-wide and may
not correspond exactly to a named session; point users to interactive
/undo for fully per-session coherence.
- Add unit coverage for agent chat_history rewind (with interleaved tool
messages), clear-to-preamble, and best-effort no-agent safety.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Wire the existing SessionCheckpointManager into the modern/default CLI
surfaces so /undo and /revert roll back files + conversation together,
and reconcile the split checkpoints.auto default.
- session_checkpoints: add a `default` param to from_config so one
checkpoints.auto key drives both file checkpoints and coherent revert
(interactive surfaces pass default=True; programmatic default stays False).
- modern repl.py: register /undo + /revert, checkpoint each turn, and rewind
the in-memory conversation via a thin store adapter.
- default AsyncTUI: register /undo + /revert and checkpoint file-mutating turns.
- run.py: add --revert (files + conversation) distinct from file-only --restore.
- tests: assert /undo restores both file and conversation on the default path.
Co-authored-by: MervinPraison <[email protected]>
- db/adapter.py: sync on_agent_start now passes an async-safe create_session
dispatcher so an async-mode store actually persists a new session instead of
dropping an un-awaited coroutine (Greptile P1).
- db/adapter.py: aon_agent_start/aon_agent_end now share the agent:{session_id}
state key and the end transition updates the started record in place, keeping
agent_name/metadata context instead of writing a disconnected record
(Greptile P2).
- api/agent_invoke.py: AgentRegistry.unregister uses a sentinel so a removal is
reported correctly even when the stored value is None/falsy (Greptile P2).
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
- api/agent_invoke.py: introduce thread-safe AgentRegistry (atomic pop
removes unregister TOCTOU 500) with optional per-embedding scoping via
a `registry=` kwarg; public functions stay backward-compatible.
- observability/hooks.py: memoize discover_observability_sinks() so the
importlib.metadata entry-point walk no longer runs on every run/request;
add reset_observability_sink_discovery() escape hatch.
- db/adapter.py: align PraisonAIDB.aon_agent_start/aon_agent_end with the
AsyncDbAdapter protocol (correct arg names/order, persist user_id instead
of dropping it); guard the sync on_agent_start against async-mode-store
coroutines via _resolve_sync to avoid the opaque 'coroutine not iterable'
crash.
Co-authored-by: MervinPraison <[email protected]>
Address reviewer findings on PR #3855:
- json.dumps guards now catch (TypeError, ValueError) so circular tool
results are stringified instead of aborting the sync tool loop (llm.py x2,
openai_client.py x2).
- _build_metadata_filter overwrites any conflicting metadata_filter["user_id"]
with the explicit user_id, preventing cross-tenant memory reads.
- Short/long-term memory searches over-fetch (limit*10) from mem0, MongoDB,
ChromaDB, and SQLite when a metadata_filter is present, then post-filter and
truncate to limit, so scoped records ranked beyond limit are not dropped.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
- llm.py/openai_client.py: capture tool failures and non-JSON-serializable
results into an error/result payload fed back to the model instead of
raising out of get_response(), matching the async execution_mixin path.
- hooks/runner.py: a hook that raises or times out now yields an explicit
deny (fail-closed) so BEFORE_TOOL security gates block instead of
silently allowing the call.
- memory/memory.py: search_short_term/search_long_term now accept and apply
metadata_filter/user_id scoping instead of silently dropping them into
**kwargs, restoring the SearchMixin contract for multi-tenant isolation.
Co-authored-by: MervinPraison <[email protected]>
The upstream merge pulled in .github/workflows changes that aren't part of this
feature; revert them to the fork's versions so the push doesn't require the
workflow OAuth scope. Main's workflows win at merge time and are what run for
the PR anyway.
Align the integration-test skip guard with the credential resolution added in
d2fa4df8 — otherwise the tests skip even when only TENKI_AUTH_TOKEN is set.
(Greptile follow-up)
- managed_local.provision_compute() now forwards `networking` and `metadata`
into ComputeConfig. Without this they were dropped, so Tenki's allow_outbound
/ tenki_image (the first provider to read them) always saw defaults regardless
of the caller's request. (Greptile: 'networking policy is dropped')
- TenkiCompute credential resolution now matches the SDK's precedence
(auth_token -> TENKI_AUTH_TOKEN -> TENKI_API_KEY), so is_available agrees with
what Client() resolves; docstring + is_available test updated. (CodeRabbit)
- networking: allow_outbound now keys off the real enum — only 'unrestricted'
gets outbound; 'limited' (also used for --no-networking) disables it. The old
check compared against a nonexistent 'restricted' value, so outbound was never
actually disabled.
- get_status/list_instances: a refresh() *exception* is now treated as unknown
(assume running) rather than STOPPED, so a transient outage no longer hides a
live, still-billing sandbox. A successful refresh with a non-RUNNING state
still reports stopped.
- failed-install teardown: terminate() before dropping the local handle, so a
failed terminate keeps the sandbox tracked instead of leaking it (matches the
shutdown path).
- don't log raw pip/npm specs (can carry private-index URLs/tokens); log counts.
Remove two unreferenced pure helpers (json_type_to_python_type,
extract_schema_properties) that have no callers, are not in __all__,
and have no test coverage. Also drop the now-unused Optional import.
Live helpers (fix_array_schemas, build_openai_tool_dict,
python_type_to_json_schema, ThreadLocalEventLoop) are unchanged.
Co-authored-by: MervinPraison <[email protected]>
Lift the multimodal tool-result wrapper into a single module-level helper
try_append_multimodal_tool_result in agent/tool_execution.py, next to its
canonical build_tool_result_message_pair. openai_client.py imports it directly
under the same private alias; the LLM method now delegates to it, preserving its
signature for any external subclass override. No behaviour change.
Co-authored-by: MervinPraison <[email protected]>
Replace the duplicated public-callable extraction walk in the legacy
recipe/workflow tools.py path with the canonical owner in
praisonai_code.tool_resolver. Adds extract_functions_from_loaded_module
(single authority over the walk) and reuses it from both
ToolResolver.load_functions_from_module and workflow_commands, preserving
the PRAISONAI_ALLOW_LOCAL_TOOLS gate, safe-loader, own-module-origin
filter, and "Loaded N tools" notice.
Co-authored-by: MervinPraison <[email protected]>
- GateResult.__post_init__ forces run=False when no_change is set so a
silent-suppress outcome can never let a runner fire a suppressed tick.
- ScheduleJob.to_dict persists monitor when not None (incl. {}) so an
explicitly configured empty spec round-trips instead of reverting to
stateless.
- Document caller contract: detect state capability before passing
state= so legacy stateless gates never raise TypeError.
Co-authored-by: Mervin Praison <[email protected]>
Extend the core scheduler contract so change-detection monitor
automations can be expressed across CLI + YAML + Python, keeping heavy
implementation (shell/URL probe, hashing, diffing, persistence) in the
wrapper. Additive and backward-compatible: jobs that set neither
`monitor` nor per-job state behave exactly as today.
- GateResult: add `no_change` (distinct silent-suppress outcome) and
`state_updates` (bounded KV a gate persists for the next tick).
- JobConditionProtocol.should_run: optional keyword-only `state` so a
stateful monitor gate can compare against prior state; existing
stateless gates satisfy the protocol unchanged.
- New JobStateStoreProtocol: bounded per-job get/set/clear scratchpad.
- RunRecord.status: add `no_change` alongside succeeded/failed/skipped.
- ScheduleJob: add optional `monitor` source spec with round-trip.
Co-authored-by: Mervin Praison <[email protected]>
- Core: FleetSupervisionPolicy no longer records events while cooling down and
clears its event window when the cooldown elapses, so the breaker re-arms
without an external reset() and held (non-)restarts cannot re-trip it.
- Monitor: evaluate the failing-channel fraction on every sweep (note_fleet_state
now has a live caller) and re-evaluate/clear the breaker inside the monitor
loop, so the degraded-owner fact clears without a status read.
- Monitor: a disabled per-channel restart budget (max_restarts_per_hour=0) no
longer counts idle channels as failing.
- Tests: fix CI regression in test_gateway_health_block_matches_runtime_consumer
(new fleet keys are genuinely consumed by from_dict), add monitor-loop cooldown
recovery coverage, tighten failing-fraction assertion, correct misleading comment.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Address reviewer findings on PR #3842:
- core: migrate_config_with_doctor now rejects a config stamped by a newer
build (version > GATEWAY_CONFIG_VERSION) and a malformed/boolean stamp via
new ConfigVersionError, so an older binary can never downgrade a newer
config or coerce config_version: true to 1. Exported from gateway package.
- wrapper: doctor guards the migration import (ImportError-safe for older core),
surfaces the version error as a warning without migrating, and rewrites
gateway.yaml atomically (tmpfile + fsync + os.replace) so an interrupted
--fix can't truncate the config. --fix help/docs document config migration.
- tests: newer-version rejection, boolean/non-integer stamp rejection, export.
Co-authored-by: Mervin Praison <[email protected]>
Per-channel restart budgets are blind to a systemic fault that restarts
every channel at once. Add a pure core FleetSupervisionPolicy breaker
(praisonaiagents/gateway) enforced by the wrapper ChannelHealthMonitor,
which holds restarts and records ONE gateway degraded-owner fact on the
shared DegradedCapabilityRegistry when the fleet thrashes. Wire the
gateway's shared registry into the single supervision owner and expose
gateway.health.fleet_* YAML thresholds.
Co-authored-by: MervinPraison <[email protected]>
Add a canonical GATEWAY_CONFIG_VERSION stamp and a declarative
LegacyConfigRule contract in core (praisonaiagents/gateway/config.py) with a
single migrate_config_with_doctor executor. Wire `gateway doctor` to detect an
out-of-date config and `--fix` to migrate it forward once and stamp the new
version, so cross-release upgrades no longer silently drift.
Co-authored-by: MervinPraison <[email protected]>
Address reviewer feedback on PR #3839:
- When litellm is installed but a capability helper is missing or raises,
preserve litellm as authoritative (return False) instead of overriding
with the static heuristic. Heuristics now run only when litellm is
genuinely absent (litellm is None), preventing unsupported params
(response_format / web_search_options) from reaching provider requests.
- supports_parallel_function_calling now uses a dedicated, narrower
heuristic instead of the general function-calling one, so serial-only
tool-calling families are not over-reported as supporting parallel calls.
- Add tests for installed-litellm error path and serial-vs-parallel.
Co-authored-by: Mervin Praison <[email protected]>
Capability helpers (supports_structured_outputs / function_calling /
parallel_function_calling / web_search / prompt_caching) delegated entirely
to litellm and returned False for every model when litellm was absent,
silently disabling structured-output / tool-calling / caching / web paths on
lean provider-native installs. Each helper now falls back to a small,
conservative, pattern-based static heuristic only when litellm is
unavailable. litellm remains authoritative when installed (no behaviour
change for existing deployments); no new deps, no network, no config knobs.
Co-authored-by: MervinPraison <[email protected]>
The before-tool injection hook allowed a tool call whenever no scanned
string matched. Because _extract_strings bounded the walk by bytes /
cardinality and returned a partial result, an attacker controlling
tool_input could pad benign strings ahead of an injection payload so the
payload was never reached, and the gate allowed the call (Greptile P1).
_extract_strings_bounded now reports whether the walk was truncated, and
create_hook blocks (fail-closed) on truncated, un-vettable input instead
of allowing it. _extract_strings is kept as a back-compat shim.
Co-authored-by: Mervin Praison <[email protected]>
- security/injection.py: _extract_strings walks iteratively bounded by bytes+
cardinality instead of a depth-4 cutoff, scans dict keys, and is cycle-safe so
nested tool inputs can no longer bypass the scanner.
- db/adapter.py: share one _serialize_tool_call helper across sync/async paths
that persists the full tool result verbatim (no silent [:1000] truncation).
- persistence/orchestrator.py: add aretrieve_knowledge/aadd_knowledge that
offload sync stores via asyncio.to_thread (and await native async stores) so
RAG no longer blocks the event loop.
Co-authored-by: Mervin Praison <[email protected]>
Gap 1: add shared require_scope() in knowledge/protocols.py and enforce it in
ChromaKnowledgeAdapter.delete_all and SQLiteKnowledgeAdapter.delete_all so an
unscoped delete_all raises ScopeRequiredError instead of wiping the whole
shared store, matching mem0's existing contract.
Gap 2: add MemoryMixin._apersist_message async wrapper that offloads
_persist_message to a worker thread, and await it at every _achat_impl call
site so file-locked disk I/O no longer blocks the event loop each turn (sync
_chat_impl and the sync _start_stream generator keep the sync call).
Gap 3: skip VAR_POSITIONAL/VAR_KEYWORD in build_parameters_schema so *args and
**kwargs are no longer emitted as required parameters, matching
build_tool_definition and preventing invalid schemas / tool-call TypeErrors.
Co-authored-by: Mervin Praison <[email protected]>
The step retry exponential-backoff + progress-print block was duplicated
byte-for-byte between the top-level _run_impl loop and the shared
_apply_step_policies helper. Extract it into a single private
_retry_backoff() used by both paths. Behaviour is unchanged: same
2**(retry_count-1) timing, same verbose print, same time.sleep. All
retryability, guardrail, on_step_error and guardrail_failed semantics are
preserved.
Co-authored-by: MervinPraison <[email protected]>
Wrapper BaseFrameworkAdapter._resolve_llm now delegates the spec->model-name
precedence to core's super()._resolve_llm instead of re-implementing it, then
derives base_url/api_key locally to build the PraisonAIModel provider object.
Removes duplicate logic and drift risk. Behaviour-preserving.
Co-authored-by: MervinPraison <[email protected]>
Move the workflow_runs page implementation into praisonai_bot where its
consumer (host_app.py) expects it, following the established bot_health
C9 shim pattern. The wrapper module becomes a backward-compat shim.
Co-authored-by: MervinPraison <[email protected]>
- Use self._hook_runner (agent-scoped registry) instead of the process-wide
default so agent-registered MODEL_FALLBACK hooks actually fire.
- Add async _aemit_model_fallback that awaits the runner; the async recovery
path no longer drops hooks via execute_sync() inside a running loop.
- Sync fallback now forwards the active stream callback so streaming consumers
receive the MODEL_FALLBACK stream event.
- Async fallback honours emit_events (no stream leak when emit_events=False).
- Extract shared _build_model_fallback_input / _emit_model_fallback_stream.
- Tests: agent-registry isolation, async hook dispatch, suppression.
Co-authored-by: Mervin Praison <[email protected]>
When the primary model becomes unavailable mid-turn and the runtime switches to
the next entry in fallback_models, the switch was invisible except for a log
line. Add HookEvent.MODEL_FALLBACK (+ typed ModelFallbackInput) and
StreamEventType.MODEL_FALLBACK, emitted at both switch sites in chat_mixin.py
via a guarded _emit_model_fallback helper. Zero overhead when nothing is
subscribed; provider internals stay redacted (only the failure class is
exposed). Follows the existing SESSION_PERSIST_FAILED observability precedent.
Co-authored-by: MervinPraison <[email protected]>
Widen the plugin bridge so before_message/after_message receive the full
resolved context (platform, sender_id, channel_id, channel_type, message_id,
session_id) alongside content, enabling per-user rate limiting, access
control, and channel-scoped redaction. Add message_sent/message_undelivered
base methods bridged to the already-emitted MESSAGE_SENT/MESSAGE_UNDELIVERED
events for delivery observability. Additive and backward-compatible.
Co-authored-by: Mervin Praison <[email protected]>
asyncio.wait_for cannot cancel a sync tool already running in the executor,
so the async retry loop was re-invoking timed-out tools up to max_attempts
times while the original invocation kept running — duplicating DB writes,
API calls, and file mutations (Greptile P1).
Mark the async timeout result with retryable=False and short-circuit it in
_execute_tool_async_with_retry alongside the other non-retryable outcomes.
Co-authored-by: Mervin Praison <[email protected]>
- process=hierarchical: drive the ahierarchical()/hierarchical() generators
manually so the real manager_task id is sent back via .send()/.asend(),
restoring the self-delegation guard and manager-task exclusion (was always
None under plain for/async for).
- execute_tool_async: apply the per-agent ToolConfig.timeout via
asyncio.wait_for so the async path no longer hangs indefinitely on a stuck
tool, matching the sync path.
- guardrails: fail loud with a clear ValueError when unenforced policy-string
guardrails (guardrails=["policy:..."] or GuardrailConfig.policy/.policies)
are passed, instead of running with silent zero enforcement; fixed the
misleading GuardrailConfig docstring.
Co-authored-by: Mervin Praison <[email protected]>
Resolve the shared background runner once and inject it into
BackgroundHandler in _handle_tasks_command so a single /tasks
invocation uses one instance, and harden the test fixture to own the
process-wide singleton lifecycle (bypassing the package's lazy
__getattr__) so a cross-file daemon can't empty the dedicated runner.
Co-authored-by: Mervin Praison <[email protected]>
Address greptile P1 review findings on tools list MCP discovery:
- Naming mismatch: the run path registers MCP tools by their bare __name__
(e.g. `read`), but `tools list` previously fabricated `<server>_<tool>`
names that would not resolve. Discovery now lists tools under the exact
runtime callable name, with cross-server duplicates disambiguated as
`name (server)` so nothing is hidden.
- Timeout blocking: each server is now discovered in a worker thread under a
hard per-server cap (_MCP_DISCOVERY_TIMEOUT_S), so a slow/unreachable server
is abandoned and reported as unavailable instead of stalling the listing.
Updated + added unit tests (runtime names, duplicate disambiguation, timeout).
Co-authored-by: Mervin Praison <[email protected]>
Add an `mcp` source to `praisonai tools list` so the terminal shows the
tools exposed by configured MCP servers alongside built-in, local,
external, and registered tools. Discovery is lazy (only when the default
view or `--source mcp` is requested) and fail-soft: an unreachable or
misconfigured server is reported as unavailable with a reason instead of
blocking the rest of the listing. Reuses the existing guarded
`MCPHandler.create_mcp_from_server` and `_collect_mcp_servers_from_config`
so no new dependencies or Agent params are introduced.
Co-authored-by: MervinPraison <[email protected]>
The two failing CLI tests (test_tasks_detail_and_cancel,
test_tasks_lists_background_tasks_in_repl) are a pre-existing cross-worker
flake unrelated to this PR's todo-streaming changes: under
`pytest -n 2 --dist loadfile` a background daemon from another file mutates
the process-wide BackgroundRunner singleton mid-assertion, so the handler
resolves a different runner than the test pinned.
Add an optional `runner=` dependency-injection seam to
`_handle_tasks_command` (None in all production call sites, so behaviour is
unchanged) and have the tests inject their dedicated runner directly. This
bypasses global-singleton resolution entirely, making the assertions immune
to the race. Verified deterministic across 500 iterations under active
singleton chaos.
Co-authored-by: Mervin Praison <[email protected]>
The async tool-execution path (_execute_tool_async_impl) never entered
tool_progress_channel, so emit_todo_update / emit_tool_progress always
returned False during async single-Agent runs — live TODO_UPDATED events
were invisible to subscribers. Mirror the sync execute_tool path: build a
progress sink from the existing stream emitter and activate the channel
around both the coroutine await and the run_in_executor call (set before
copy_context_to_callable so the contextvar propagates into the worker
thread). Zero overhead when no stream callbacks are registered.
Adds regression tests covering the TODO_UPDATED event, TodoTools emission,
the single-in_progress invariant, and async-path channel propagation.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Adds StreamEventType.TODO_UPDATED plus a small emit_todo_update() helper
that reuses the existing thread-local progress sink (already active around
every tool call). The built-in todo tool now publishes the full ordered
list on each add/update, so any frontend can render a live checklist.
Enforces the "exactly one in_progress" convention and consolidates the
planning TodoItem status vocabulary to include cancelled.
Co-authored-by: MervinPraison <[email protected]>
Per-request AgentsGenerators borrow the cached generator's tool-timeout
executor but previously kept leak accounting local, so a stuck sync tool
never incremented the owner's _leaked_workers and the shared pool was
never recycled — eventually starving all requests (Greptile P1).
Delegate _get_tool_timeout_executor/_note_leaked_worker/_timeout_owner_key
to the cached owner so leaks are counted on, and recycling happens on, the
generator that actually owns the pool.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
- serve agents: build a per-request AgentsGenerator that borrows the cached
generator's warm immutable pieces (adapter, config_list, tool resolver,
tool-timeout pool) instead of mutating shared cli_config under a global
lock, so concurrent requests are no longer serialised.
- persistence: add scan_prefix() to StateStore with a prefix-scoped default;
override with non-blocking SCAN on Redis and Upstash so get_runs/get_traces
never issue KEYS praison:* across the whole keyspace.
- security: split strict jailbreak patterns (auto-HIGH) from soft role-play /
imperative patterns (MEDIUM alone, HIGH only when combined), so benign
prompts like "You are now analyzing..." are not blocked while real attacks
("ignore all previous instructions", DAN) still block on a single hit.
Co-authored-by: MervinPraison <[email protected]>
Pre-existing xdist race (unrelated to PR #3810's agent/knowledge changes):
under -n 2 --dist loadfile a persistent worker's process-wide background
runner could interleave with these tests, surfacing as "No background tasks"
and an uncancelled RUNNING task. Add an explicit xdist_group so the file's
tests stay serial on one worker, and reset the module-level _shared_runner on
fixture teardown so no dedicated instance leaks into a later module. Assertions
are unchanged.
Co-authored-by: Mervin Praison <[email protected]>
cleanup_launch_registration filtered the shared FastAPI router by path
only, so closing an agent launched at a path that also serves a
different verb (e.g. built-in GET /health, GET /) removed that unrelated
route too. Filter on path AND POST method since launch() always
registers via .post(path).
Co-authored-by: Mervin Praison <[email protected]>
- Agent.close() now tears down the routes launch() actually registered
(module-level state in execution_mixin.py) instead of a disconnected,
never-populated ServerRegistry — closes the launched-endpoint handle leak.
- Remove dead Agent.checkpoints/Agent.background pass-through state and
properties that were never consumed by any code path (no live consumer),
keeping the surface lightweight.
- MongoDBKnowledgeAdapter.add/search now honor user_id/agent_id/run_id
scoping, matching SQLite/Chroma adapters, fixing the silent cross-tenant
data leak.
Co-authored-by: MervinPraison <[email protected]>
The /tasks CLI resolves the runner via ``from praisonaiagents.background
import get_background_runner``, which reads the name off the package (whose
__init__ exposes it through a lazy __getattr__), imported at call time by
BackgroundHandler._get_runner. The fixture only patched the ``runner``
submodule binding, so once another worker file materialised the package
attribute, the CLI bypassed the patch and resolved the process-wide shared
runner instead — letting a concurrent cross-file daemon race the two tests
under ``pytest -n 2 --dist loadfile`` (the observed "No background tasks"
and uncancelled RUNNING failures). Patch the name on the package too so the
CLI deterministically sees the dedicated per-test runner. Test-only; no
assertions weakened and no SDK behaviour changed.
Co-authored-by: Mervin Praison <[email protected]>
Move the byte-for-byte-identical _deliver_result and _build_delivery
methods from AgentScheduler and AsyncAgentScheduler up to the shared
_BaseAgentScheduler, mirroring the existing consolidation of
_should_suppress_delivery, _budget_exceeded and _build_stats. Removes
~55 lines of duplication and the drift risk on a safety-relevant
delivery path. No behaviour change: both methods are plain synchronous
methods referencing only attributes both subclasses set identically.
Co-authored-by: MervinPraison <[email protected]>
Addresses CodeRabbit & Greptile P1 review feedback on the YAML/prompt CLI
router (#3793):
- main() now classifies the first positional value-aware when flags are
present, so a leading value-taking run option (e.g. `--session abc123
agents.yaml`) consumes its value instead of mistaking it for the target.
Discovery is skipped on the flagless fast path and falls back conservatively
when introspection fails.
- Quarantine `-s`/`-f` (legacy `--save`/`--file` vs modern
`--session`/`--framework`) from the modern forwarders so existing YAML/prompt
invocations carrying them stay on legacy — zero silent reinterpretation.
Unambiguous long forms still reach the modern engine.
- Reuse the derived value_opts in the bare-prompt branch (no double
introspection).
Tests: added leading-value-option (YAML + prompt) regressions and
legacy-colliding-short-opt coverage for both classifiers.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Workflow YAML invocations (praisonai agents.yaml) were routed to the legacy
argparse path, bypassing the modern run features: session continuity
(--continue/--session/--fork), --output modes, the first-run credential gate
and permission flags. The modern `run` command already fully handles YAML
files inside that envelope; only the CLI router diverted YAML to legacy.
Add _looks_like_yaml_run_target() and forward a workflow YAML target to
`run <file>` when all flags are run-supported, restoring YAML parity with the
CLI/Python surfaces. YAML with a genuinely legacy-only flag still falls back to
legacy with the existing one-line notice.
Co-authored-by: MervinPraison <[email protected]>
The two failing CLI tests (test_tasks_detail_and_cancel,
test_tasks_lists_background_tasks_in_repl) are a pre-existing shared
BackgroundRunner singleton isolation flake, unrelated to this PR's
gateway-only changes. Port the already-authored isolation fixture that
pins a dedicated runner per test and monkeypatches get_background_runner
to return it, so no other file's daemon loop can reach the instance
_handle_tasks_command resolves. Assertions (list, detail, real CANCELLED
status) are unchanged.
Co-authored-by: Mervin Praison <[email protected]>
The two test_interactive_tasks_command.py tests fail intermittently under CI's
pytest -n 2 --dist loadfile because the process-wide BackgroundRunner singleton
(and a live daemon loop another file left running on it) races these tests,
surfacing as "No background tasks" and an uncancelled RUNNING task. This is
unrelated to the scheduler-delivery changes in this PR.
The prior fix only reset _shared_runner, still sharing a process-wide object
other threads could touch. Instead, pin a dedicated BackgroundRunner per test
and monkeypatch get_background_runner to return exactly it, so no other file's
daemon can reach the instance _handle_tasks_command resolves. No assertions
weakened: list, detail, and the real CANCELLED status are all still verified.
Verified passing even with a pre-polluted singleton.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Addresses reviewer findings on PR #3806:
- Greptile P1 (blocking): the pin no longer permanently mutates the shared
registry Agent. _check_model_drift now returns a run-scoped restore callable
applied in a finally around the whole run (gate/policy/turn/exception paths),
so a scheduled job's model never leaks into attended turns on the same agent.
Extracted the run tail into _run_pinned for a single guaranteed restore point.
- CodeRabbit (Major): provider/model are normalized (embedded "openai/gpt-4o"
prefix lifted out) before comparison, so a provider-qualified pin and a bare
resolved model no longer false-drift; split provider snapshots compare equal
to embedded agent strings too.
- CLI: clarified --pin/--no-pin help — pinning enforces a snapshot only once one
exists via an explicit --model; kept the CLI lightweight (no agent/LLM
instantiation at creation time) per AGENTS.md.
Tests: added run-scoped-restore and provider-prefix-normalization cases; core
scheduler (127) and wrapper scheduler (274) suites pass.
Co-authored-by: Mervin Praison <[email protected]>
A NaN/inf budget or rss slipped past the `rss <= target` check (all NaN
comparisons are False) and spuriously evicted every warm cache. Guard with
math.isfinite and safely coerce headroom_ratio, falling back to 0.9.
Co-authored-by: Mervin Praison <[email protected]>
Unattended scheduled runs resolved their model at fire time, so a job created
against a cheap/local default silently inherited whatever the default later
became — an invisible cost/behaviour drift for automations run without
supervision.
- core: additive provider/model/pin_model snapshot fields on ScheduleJob with
backward-compatible round-trip serialisation (unset = today's behaviour).
- wrapper executor: before the model turn, compare the resolved agent's model
with the snapshot; on drift fail closed (recorded error + optional fail-closed
delivery) with no model turn; otherwise pin the run to the snapshot.
- CLI: `schedule add --model` / `--pin/--no-pin`.
Co-authored-by: MervinPraison <[email protected]>
Add a pure, import-free core planner plan_pressure_evictions plus a
WarmSession fact and a MemoryPressureProtocol (cgroup limit + anon RSS)
to the gateway protocols. Under memory pressure the gateway can now name
the coldest (LRU) rebuildable warm session-agent caches to soft-evict
before the kernel OOM-kills the whole process, guarding against evicting
in-flight or not-yet-flushed sessions. Mirrors the existing
MemoryPressurePolicy admission contract; the decision is testable in
isolation and the gateway enacts the returned plan.
Co-authored-by: MervinPraison <[email protected]>
- failure.py: map validation/invalid_output -> format_error and OR in the
source outcome's is_retryable() so invalid_output stays retryable
- presentation.py: DegradedDelivery now uses immutable Tuple fields; report
derived from the same conversion/selection as adapt_presentation (select->
buttons, priority/cap truncation), passes callback_store, and reports
callback shortening only for genuinely lossy payloads (reply actions & select
options), never plain callbacks or store-backed lossless refs
- tests: pytest.raises for frozen checks; add invalid_output-retryable,
long-callback-with-store, plain-callback, and long-select-option coverage
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Addresses reviewer feedback on #3800/#3802:
- P1: Build SchedulerDelivery eagerly in the (sync/async) scheduler __init__
when a deliver token is set, via a shared _build_delivery() helper. The
creation-time pre-flight warning/preview now fires the moment the scheduler
is created instead of lazily at fire time (after the first run). Fire-time
lazy build is retained as a fallback; self-heal remains the second line.
- P2: Move optional validate_target/preview_target off the runtime_checkable
DeliveryResolverProtocol into a separate DeliveryPreflightProtocol so
existing resolve()-only resolvers still satisfy the base protocol under
isinstance. Export DeliveryPreflightProtocol from praisonaiagents.gateway.
Backward-compatible, no new deps, no Agent params. Scheduler suite: 262
passed, 7 skipped; preview suite: 9 passed.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Add a creation-time pre-flight so a scheduled/agent-initiated send's
DeliveryTarget is checked and previewed the moment it is created, not only
when the job fires. Core gains a thin protocol seam (DeliveryValidation,
ScheduleTargetError, DeliveryResolverProtocol.validate_target/preview_target)
and a pure DeliveryTarget.preview(); the wrapper SchedulerDelivery validates
its target on construction, logging an actionable warning for unroutable
tokens and a preview otherwise. Fire-time self-heal is kept as second defence.
Co-authored-by: MervinPraison <[email protected]>
Add two pure, dependency-free core primitives so every bot turn ends in a
visible, actionable outcome and presentation downgrades are never silent:
- praisonaiagents/bots/failure.py: FailureReply + render_failure_reply maps an
AgentRunOutcome or PraisonAIError to typed, user-facing next-step copy keyed
by failure class (expired auth, missing key, rate limit, timeout, budget,
doom-loop, needs-help), reusing the existing remediation_hint.
- praisonaiagents/bots/presentation.py: DegradedDelivery + a backward-compatible
adapt_presentation_with_report returning the adapted presentation plus a typed
record of dropped controls with machine-readable reason codes. Existing
adapt_presentation signature is unchanged.
Mirrors classify_final / resolve_ingress_admission so no adapter re-decides the
failure/degradation outcome. No new deps, no config knobs.
Co-authored-by: MervinPraison <[email protected]>
- env.py: _provider_from_model prefers the env-set credential alias so
Together/Fireworks (TOGETHERAI_API_KEY, FIREWORKS_AI_API_KEY) resolve a key
instead of always using the first declared var.
- credentials.py: _stored_providers_for_vars derives from PROVIDER_ENV_CATALOGUE
so a stored key for any catalogued provider (Mistral, DeepSeek, xAI, Together,
Perplexity, Fireworks) satisfies is_configured() for its explicit model.
- setup/handler.py: _provider_setup_info picks the catalogue env-var (honouring
the alias actually set) and the catalogue representative model for
catalogue-only providers.
- tests: derive the env-clearing/detection key lists from the catalogue so
default-model and interactive-path assertions stay deterministic even when the
CI host exports a catalogued key (e.g. OPENROUTER_API_KEY). Fixes the three
failing test-core (cli) checks without weakening assertions.
Co-authored-by: Mervin Praison <[email protected]>
Replace the three hardcoded provider lists (is_configured's 8-key tuple,
_PROVIDER_DEFAULTS, and the setup wizard's 4-key env auto-detect) with a
single data catalogue PROVIDER_ENV_CATALOGUE mapping provider id ->
env-var(s) + representative model + model prefix.
Zero-config `praisonai run` now recognises a valid key for any catalogued
provider (Mistral, DeepSeek, Together, Fireworks, xAI, Perplexity, …) and
selects a provider-appropriate default model instead of gating on the old
~8-provider set. The catalogue keeps the historical 8 at its head so
existing ordered-preference behaviour is unchanged and new providers are
purely additive and backward compatible.
Co-authored-by: MervinPraison <[email protected]>
Auto-compaction previously read a static per-model context-window table with a
flat 128k default, mis-estimating the trigger point for any non-hardcoded model
(overflow for small windows, premature compaction for large ones).
get_model_limit()/get_output_reserve() now consult litellm's model_cost registry
(max_input_tokens/max_output_tokens) first, then fall back to the static tables.
Lazy-imported: zero overhead and fully backward compatible when litellm is absent.
Co-authored-by: MervinPraison <[email protected]>
- auto.py: _rewrite_agent_refs now rewrites route target strings
(route: {label: [agent_id]}) and loop/branches payload refs including
feedback_to, so renamed _auto_N agents are no longer routed to the
pre-existing colliding agent.
- orchestrator.py: PRAISONAI_SESSION_CACHE_MAX now falls back to the
documented default (1024) on empty/non-numeric values instead of raising
ValueError during persistence init.
Co-authored-by: Mervin Praison <[email protected]>
- Gap 1: PersistenceOrchestrator._session_cache is now a bounded LRU
(OrderedDict + PRAISONAI_SESSION_CACHE_MAX, default 1024) to prevent
unbounded memory growth in long-running serve/jobs/bot processes.
- Gap 2: flow.start_flow() now joins LANGFLOW_COMPONENTS_PATH with a comma
(pydantic list separator) instead of ';', matching the CLI helper so a
pre-existing env value no longer silently disables all components.
- Gap 3: merge_with_existing_workflow now tracks agent renames and rewrites
step agent references (including nested parallel/route/loop/branches) so
merged steps dispatch to the freshly-generated agent, with a log line on
each rename.
Co-authored-by: MervinPraison <[email protected]>
Remove calculate_cost_from_tokens and get_model_cost_info, which are
never referenced anywhere in the package, wrapper, tests, docs, or
public API. Also drop the now-unused Dict import. The live cost path
(calculate_cost) and tracking helpers remain unchanged.
Co-authored-by: MervinPraison <[email protected]>
Security: _caller_principal now treats the authenticated SessionContext.
unified_user_id as authoritative — an agent-supplied `principal` tool argument
can no longer override it, closing the cross-tenant impersonation gap flagged by
CodeRabbit/Greptile. Explicit principal still applies on the trusted no-session
path (CLI / gateway bridge).
CI regressions (stale test doubles):
- _FakeEngine now accepts principal= (matches the real principal-aware
SuggestionEngine API the gateway threads through).
- async_tui parity fake _execute now accepts read_only= (param added by the
earlier /code-review PR); pre-existing failure unrelated to this feature.
Tests: rewrote impersonation coverage (session wins), added no-session explicit
path test, and restore both global schedule stores in teardown for determinism.
Co-authored-by: Mervin Praison <[email protected]>
_execute_in_background now calls _execute_prompt(prompt, read_only=...) after
the read-only review work landed, but the test's _fake_execute only accepted
`prompt`, so the extra kwarg raised TypeError (swallowed by the background
error handler) and captured["prompt"] was never set -> KeyError: 'prompt'.
The fake now accepts read_only; assertions (single expansion, sentinel body
reaches the prompt) are unchanged.
Co-authored-by: Mervin Praison <[email protected]>
Multi-agent review found the npm package (praisonai 1.7.3) does not compile
from a clean checkout and has several core-loop bugs. This makes v1.7.4
releasable.
Build was broken everywhere but the author's machine:
- src/db/ (6 files) and src/cli/output/ (4 files) were never committed --
the repo-root .gitignore entries `db` and `output` swallowed them, so 63
of 65 tsc errors were missing-module. Committed the files and added
negation rules.
- pnpm-lock.yaml was out of date (axios spec, better-sqlite3, removed
optional ai-sdk providers); regenerated.
- @jest/types and @jest/globals were not direct devDependencies, so jest
could not even load its config under pnpm; added, plus
@ai-sdk/provider-utils and @opentelemetry/api for the dynamic imports.
- adapter.ts imported tool()/jsonSchema() from @ai-sdk/provider-utils,
which never exported them (they live in `ai`); now tries `ai` first with
the old fallback preserved.
Core bugs fixed (each confirmed at runtime by the review):
- require('praisonai') threw at import when OPENAI_API_KEY was unset, even
for Anthropic/Google users; check moved to client creation.
- Agent.chat() sent every user prompt to the model twice (pushed to
history, then start() replayed history AND appended it again).
- Constructor tool processing aliased and mutated the caller's tools array
while iterating it: raw functions plus duplicate definitions were sent
to the API. Now iterates a snapshot and rebuilds this.tools.
- Plain-function tools received the parsed args OBJECT as their first
positional parameter ("Weather in [object Object]"); named args are now
mapped positionally via declared parameter names.
- Tool results were serialized with .toString() -- objects became
"[object Object]", null/undefined threw; now JSON.stringify.
- Tools and outputSchema silently ignored on non-OpenAI providers; now
logged loudly (proper support is follow-up work).
- OpenAIService defaulted to gpt-5-nano while hardcoding temperature 0.7,
which reasoning-family models reject with a 400; the default temperature
is now omitted for gpt-5*/o1*/o3*/o4*.
New capability (Python parity: output_json/output_pydantic):
- Agent outputSchema / outputSchemaName wired through generateText and
generateChat as OpenAI response_format json_schema.
- The exported parity MCP class's callTool() returned null (placeholder);
it now delegates to the real MCPClient (stdio/HTTP/SSE).
Release readiness: version 1.7.4 (1.7.3 is already on npm), LICENSE file
added (files list referenced it but it did not exist), engines.node >=18
(openai@4 requires it; >=14 was wrong).
Results: tsc 65 errors -> 0; jest "cannot start" -> 59/59 suites, 999
tests passing (87 skipped are live-API); npm pack produces a complete
tarball including LICENSE. Also added 9 unit tests covering every fix
above.
Co-Authored-By: Claude Fable 5 (1M context) <[email protected]>
- Move PresentationRendererProtocol to bots/protocols.py (core extension-point
convention), re-exported from presentation.py for backward-compatible imports.
- Normalize platform ids (case-insensitive) in the renderer registry to match
the channel registry, so mixed-case plugin ids resolve their renderer.
- Validate registrations at the API boundary: reject empty platform ids and
renderers missing get_limits/render, failing loudly at registration.
- Make wrapper built-in registration older-core safe (swallow ImportError) and
non-destructive (only fill empty slots, so plugin overrides win).
- Case-insensitive older-core fallback in get_renderer.
- Fix pre-existing CLI test failure: _execute_prompt fake stub now accepts the
read_only kwarg the production signature passes.
Co-authored-by: Mervin Praison <[email protected]>
- pairing.py: reject empty/whitespace secrets, fail closed on read errors of
an existing secret (no silent HMAC rotation), and create the secret atomically
with O_CREAT|O_EXCL so racing processes converge on one key.
- _pairing_ui.py: narrow the callback-secret fallback to storage errors and warn
explicitly instead of silently substituting a diverging random key.
- bot_checks.py: doctor guidance now notes PRAISONAI_CALLBACK_SECRET must be
unset/identical across hosts for button signatures to align.
- test_interactive_surfaces_parity.py: update the _execute_prompt fake to accept
read_only (matching the real signature added in #3758), fixing KeyError:'prompt'.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
The async TUI review path calls self._execute_prompt(prompt, read_only=...),
but the parity test's fake stub only accepted `prompt`. The resulting TypeError
was swallowed by the broad except in _execute_in_background, so the fake never
recorded the prompt (KeyError: 'prompt'). Align the fake with production.
Co-authored-by: Mervin Praison <[email protected]>
Aligns resolve_ingress_admission with the live BotConfig.group_policy
default (mention_only) instead of respond_all, so an adapter forwarding
an unset policy fails safe (mention-gated) rather than replying to all
group traffic. Clarifies allowlist/pairing docstring contract.
Co-authored-by: Mervin Praison <[email protected]>
Add PresentationRendererProtocol + register_presentation_renderer /
get_presentation_renderer to praisonaiagents.bots.presentation so any
channel — built-in or a pip-installed plugin — can register a native
renderer the same way it already contributes config via ChannelDescriptor.
The wrapper now registers the four built-in renderers through this seam and
resolves via the core registry, so plugin channels no longer silently
degrade interactive UI to plain text.
Co-authored-by: MervinPraison <[email protected]>
Add pure, zero-dependency resolve_ingress_admission(...) -> IngressDecision
in praisonaiagents.bots.admission, mirroring evaluate_channel_health and
BotLoopGuard. Unifies channel/user allowlist, block-list, group policy
(respond_all/mention_only/command_only/observe) and pairing into one typed
verdict with a machine-readable reason_code so drops are recordable instead
of logger.debug-only and cannot drift per transport. Adds no new user knob.
Co-authored-by: MervinPraison <[email protected]>
Route the callback-button HMAC secret (bots/_pairing_ui.py) through the
same auto-provisioned, owner-only persisted secret used by the pairing
code path, so approve/deny buttons keep verifying across process restarts
with zero operator action. Explicit PRAISONAI_CALLBACK_SECRET override
still wins. Also collapse the stale ephemeral _get_secret() onto the
persisted store and correct the doctor check message.
Co-authored-by: MervinPraison <[email protected]>
Addresses the reviewer-flagged P1 that ``--pure`` / ``--no-plugins`` leaked
across in-process invocations: the flag set PRAISONAI_NO_PLUGINS with no
restore, so a later run/chat/code call in the same process inherited the
plugin-free baseline it never asked for.
- Add scoped_no_plugins() context manager + scopes_no_plugins() decorator in
cli/utils/env_utils.py that set PRAISONAI_NO_PLUGINS for the duration of one
command and always restore the prior value on return (mirrors the existing
--allow-local-tools save/restore pattern). functools.wraps preserves the
Typer signature so the real option set is unchanged.
- Apply the decorator to run/chat/code callbacks and drop the unscoped env
mutation from each body.
- Add regression tests for set/restore, prior-value restore, no-op, exception
safety, and decorator signature preservation.
Also repair pre-existing (present on main) test stubs broken by the earlier
read_only review-agent change: async-TUI stubs must accept the read_only
kwarg. Source is correct; only the stubs were stale.
Not implemented (out of scope per issue #3773): suppressing praisonai.tools /
praisonai.tool_sources entry-point discovery. The issue scopes suppression to
the praisonai.plugins group; tool suppression is explicitly optional/secondary
and would be scope creep.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
_execute_in_background calls _execute_prompt(prompt, read_only=...) since the
review-command work (#3734). The parity test's _fake_execute stub only accepted
`prompt`, so the extra kwarg raised TypeError inside the inlined execute thread,
which was swallowed and left `captured` empty (KeyError: 'prompt'). Mirror the
real signature in the stub; assertions (single-pass expansion + sentinel body)
are unchanged.
Co-authored-by: Mervin Praison <[email protected]>
Address reviewer feedback on the doom_loop approval gate:
- Reset the whole matching (tool,args) streak on an explicit allow instead of a
blind pop() so a legitimate repeat gets a fresh critical_threshold window and
is not re-prompted on every subsequent call. Removing by identity also leaves
concurrent unrelated records intact (fixes the pop() race).
- Move the synthetic gate out of DEFAULT_DANGEROUS_TOOLS to a namespaced
internal target (__doom_loop__) so it can never reserve/collide with a real
user tool named doom_loop or leak into the safe/read_only presets.
- Honour an explicit PermissionManager allow/deny on the doom_loop policy alias
before consulting a backend, so Agent-level policy is not bypassed.
- Scope the approval request to the exact repeated call via a stable args
fingerprint so an allow for one loop cannot silently authorise another.
Adds regression tests: streak-reset (no per-call reprompt), per-argument
scoping, user-tool-name isolation, and internal-target criticality.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
- credentials: treat a set-but-empty PRAISONAI_AUTH_CONTENT as a
misconfiguration (ValueError) instead of silently falling back to disk,
preserving the zero-disk contract; validate that each provider entry is a
JSON object so malformed entries fail fast with a clear error.
- tests: add regression coverage for empty value and non-object provider entry.
- fix pre-existing CI failure in test_async_tui_expands_at_mentions: the
_fake_execute stub predated the read_only kwarg on _execute_prompt, so the
real call raised a swallowed TypeError and left the prompt uncaptured.
Co-authored-by: Mervin Praison <[email protected]>
Add an ephemeral, per-run flag to suppress discovery/loading of external
plugins without mutating persisted enable/disable state.
- Core: PluginManager honours a PRAISONAI_NO_PLUGINS env var and an optional
`disabled` constructor param (Python parity for plugins=False) that
short-circuits discover_entry_points()/auto_discover_plugins(), emitting a
single "running without external plugins" notice.
- Wrapper: add --pure / --no-plugins to run/chat/code, which set
PRAISONAI_NO_PLUGINS for the process only.
- Surface reproduction hint / suppression status in `plugins doctor`.
Co-authored-by: MervinPraison <[email protected]>
Route a critical loop verdict through the unified approval pipeline as a
synthetic `doom_loop` permission target instead of unconditionally blocking.
This gives human override, per-project policy control (allow|ask|deny) and
cost safety while preserving the historical hard-stop default.
Co-authored-by: MervinPraison <[email protected]>
Load the whole credential store from a single env var (JSON) in memory when
PRAISONAI_AUTH_CONTENT is set; skip all disk reads and make writes in-memory
no-ops so nothing is persisted. Surface the in-memory source in auth list/status.
Co-authored-by: MervinPraison <[email protected]>
- tools.py: read max_bytes+1 and reject when a github: tool file exceeds the
1 MiB cap instead of silently persisting truncated (broken) source as success
(Greptile P1).
- test_interactive_surfaces_parity: _fake_execute now accepts read_only= to
match _execute_prompt(prompt, read_only=...) — the stub predated the read-only
review signature, so the real path swallowed a TypeError and never set the
captured prompt (CI KeyError: 'prompt'). Test guarantee (expand-once) preserved.
Co-authored-by: MervinPraison <[email protected]>
Gap 2 (security): praisonai tools add now honours PRAISONAI_ALLOW_LOCAL_TOOLS
like every other loader, inspects added files via ast.parse instead of
exec_module, and hardens GitHub downloads (HTTPS-only, 1 MiB cap, safe basename).
Gap 3 (async safety): OpenAI-compat handlers offload sync provider.invoke via
asyncio.to_thread; simulated streaming emits word-by-word instead of per-char;
A2UEventBus mutations are guarded by a threading.RLock, the singleton is
double-checked-locked, and /a2u/health now requires authentication.
Gap 1 (adapter parity): add warn_unsupported_fields to surface YAML fields a
backend silently drops, wired into CrewAI/AutoGen adapters; AutoGen agent_callback
is now fired per agent.
Co-authored-by: MervinPraison <[email protected]>
Address reviewer feedback on #3769:
- memory_mixin: rollback now removes only the failing turn's own messages by
object identity (tracked per-turn via contextvars, thread/task-isolated) so a
concurrent turn's messages are never clobbered; positional fallback kept for
untracked callers (backward compatible).
- chat_mixin: wire _begin/_end/_clear_turn_tracking into sync chat() (try/finally)
and async achat() custom-LLM paths.
- agent: stop persisting a live Memory/db() backend in _memory_config so
clone_for_channel() isolates it via _memory_instance instead of sharing one
store across channel clones.
- test_interactive_surfaces_parity: fix outdated _fake_execute signature that
didn't accept _execute_prompt's read_only kwarg (pre-existing CI failure).
- Gap 1: clone_for_channel() now re-instantiates a fresh memory backend per
clone (via _isolated_memory_for_clone), so per-channel/per-user clones no
longer share one live Memory store. Also persists _memory_config on self so
clones actually receive the memory config.
- Gap 2a: add _rollback_chat_history_to() which only removes this turn's own
appended slice, so a failing turn can't clobber a concurrent turn's messages;
all chat()/achat() rollbacks now use it instead of _truncate_chat_history.
- Gap 2b: achat() custom-LLM path now uses the atomic
_add_to_chat_history_if_not_duplicate() helper (like sync chat()) instead of
an unlocked check-then-act, closing the TOCTOU duplicate-message race.
- Gap 3: forward Agent(retry=...) into LLM init params for all _using_custom_llm
branches (provider/model, dict, base_url) so max_retries is honored instead of
LLM's hardcoded default; user-set max_retries in dict configs still wins.
Co-authored-by: MervinPraison <[email protected]>
The async TUI passes read_only= to _execute_prompt in _execute_in_background,
but the test's fake only accepted (prompt), causing a TypeError swallowed by
the surrounding except, so captured['prompt'] was never set (KeyError). Align
the fake signature with production. Unrelated to PR #3764's LLM changes.
Co-authored-by: Mervin Praison <[email protected]>
Per-call max_tokens overrides bypassed the reasoning-model conversion because
override_params were merged after the instance-level mapping. Move the
max_tokens -> max_completion_tokens normalization (and sampling-param drop)
to after the override merge so o1/o3/gpt-5.x calls never carry the rejected
max_tokens. Explicit max_completion_tokens takes precedence.
Co-authored-by: Mervin Praison <[email protected]>
Reasoning models (o1/o3/gpt-5.x) reject the legacy max_tokens parameter
and require max_completion_tokens. They also reject sampling params like
temperature/top_p. The Chat Completions param builder now detects
reasoning models via litellm.supports_reasoning() (with a prefix fallback)
and emits the correct token param while dropping unsupported sampling params.
Co-authored-by: MervinPraison <[email protected]>
Addresses reviewer findings on PR #3747:
- Route /code-review and /security-review through a cached read-only review
agent whose tool set excludes write/command-execution tools, enforcing the
advertised read-only boundary at the capability level (not just by prompt).
- Skip @file expansion for generated review prompts so a `@../../secret`
token inside an untrusted diff cannot exfiltrate files.
- Distinguish diff-collection failures (raise ReviewDiffError) from a
successful empty diff, so errors are no longer masked as "Working tree clean".
- Parse review args with shlex so quoted paths survive; reject multiple
positional paths with a usage message.
- Derive slash-command autocomplete from _BUILTIN_COMMANDS so code-review /
security-review are discoverable and stay in sync with registration.
- Tests: option forwarding, multi-path rejection, diff-error vs clean tree,
ReviewDiffError propagation, and read-only tool filtering.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <[email protected]>
Under CI's `pytest -n 2 --dist loadfile`, a worker process persists across
files, so the process-wide BackgroundRunner singleton (and any tasks other
files scheduled on its daemon loop) leaked into these REPL /tasks tests. The
old fixture only cleared `_tasks`, which a concurrently-mutating daemon task
could repopulate — surfacing as "No background tasks" and an uncancelled
RUNNING task. Fully reset the singleton so `_handle_tasks_command` resolves the
same fresh instance we seed. No assertions weakened; behaviour still fully
verified (list, detail, actual CANCELLED status).
Co-authored-by: Mervin Praison <[email protected]>
Resolve two P1 correctness gaps from Greptile's second review pass:
- session fork: the store persists sessions under a *sanitized* filename
(non [alnum-_] -> _), so a global-only id containing e.g. '.' or ':' was
found by session_exists_anywhere but missed by the literal '{id}.json'
store-dir check, forking an empty history from the project store. Sanitize
identically when resolving the store dir.
- REPL /branch: replace the inline, unlocked busy check with the shared
_worker_busy() helper, which reads current_task and queue size under the
worker's processing_lock. This closes the dequeue/publish race where a turn
is in-flight but momentarily invisible.
Tests: sanitized-global-id fork resolution; /branch busy state read under lock.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
When the legacy REPL is launched with --approval plan the backend already
enforces PermissionMode.PLAN, but session_state['plan_mode'] defaulted to
False so the first no-arg /plan re-enabled an already-active mode instead of
exiting it (Greptile P1). Seed plan_mode from backend.permission_mode on first
use, mirroring the async TUI's _sync_plan_mode_from_backend. Adds a source
regression test.
Co-authored-by: Mervin Praison <[email protected]>
The Enter handler expanded @file mentions before _queue_or_execute, but
_execute_in_background already expands canonically. Since
_process_file_mentions is not idempotent, the second pass re-interpreted
@tokens embedded in attached file contents and appended unrequested files.
Removes the redundant enter-handler expansion so all paths expand once.
Strengthens the parity test to drive the real _execute_in_background path
and assert _process_file_mentions runs exactly once.
Co-authored-by: Mervin Praison <[email protected]>
Address three P1 review findings on the mid-session forking feature:
- session fork CLI now resolves the store directory from the same
canonical CLI stores session_exists_anywhere() searched (project then
global), so forking a global-only session copies its real history
instead of producing an empty fork from the project-scoped store.
- session fork rejects an out-of-range --at-message (negative or >=
message count) up front rather than silently wrapping via Python slice
semantics while reporting success.
- REPL /branch refuses to fork while a turn is still executing (worker
busy or queue pending), preventing the async worker from saving the
parent's in-flight turn onto the freshly-switched fork.
Adds tests for out-of-range indices, global-only forking, and
branch-while-busy rejection.
Co-authored-by: Mervin Praison <[email protected]>
Address two Greptile P1s on the headless `praisonai code -p` path:
- Profiling no longer bypasses headless output. The `-p` branch now runs
before the `--profile` branch and rejects the `-p` + `--profile/--profile-deep`
combination, so the machine-readable JSON/text contract and status exit code
are always honored instead of a human report exiting 0.
- `-p` fails closed on options the minimal headless agent cannot honor
(`--tools`, `--agent`, `--plan`, `--no-acp`, `--no-lsp`) rather than silently
dropping the caller's tools/profile/scope. Options that ARE honored
(`--model`, `--thinking`, `--verbose`, `--workspace`, `--resume/--session/--continue`)
remain allowed. Chose fail-closed over re-implementing the heavy ACP/LSP
wiring to keep the command lightweight (AGENTS.md).
Adds tests for both guards.
Co-authored-by: Mervin Praison <[email protected]>
Address four valid P1 findings from Greptile review of the /tasks feature:
1. Bot command dispatch was missing: wire handle_tasks_command into the
telegram, discord and slack adapters (was advertised but never invoked).
2. Task registries were disconnected: arun_background now submits to the
process-wide get_background_runner() so /tasks and `background list` see
the same tasks (previously each call built its own runner).
3. Ownerless tasks bypassed isolation: _owned now fails closed — a bot user
only sees/acts on tasks whose metadata.user_id matches exactly.
4. Cancellation left execution running: add BackgroundRunner.cancel_task_sync
(hops to the background loop) and use it so the underlying future is
actually cancelled instead of merely marking the record.
Tests updated for fail-closed ownership + new ownerless-isolation case.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Addresses Greptile P1: the TUI lazily built the checkpoint manager only on
the first /diff or /undo, so its "session start" snapshot captured an
already-modified workspace — /diff omitted prior edits and /undo restored the
post-edit state. Now on_mount() eagerly establishes the baseline before any
turn, and each submission records a pre-turn checkpoint so /undo can roll back
individual turns. Both paths are best-effort and no-op when checkpointing is
disabled. Adds two lifecycle regression tests.
Co-authored-by: Mervin Praison <[email protected]>
resolve_session accepts legacy-only ids via the deprecation-window
fallback, but rename_session did a canonical-only lookup so `session
rename` failed on a pre-existing session the CLI otherwise lists,
resumes, deletes and exports. Add a _legacy_rename fallback mirroring
_legacy_delete, backed by a new SessionManager.rename that persists the
title in the existing metadata `name` field (empty clears it, matching
canonical store semantics). Adds regression tests for the store and CLI
legacy paths.
Co-authored-by: Mervin Praison <[email protected]>
Addresses Greptile P1 findings and CI failures on PR #3750:
- async_tui/legacy: exiting PLAN now restores the launch-time policy
(accept-edits/bypass) instead of forcing DEFAULT.
- async_tui: sync config.plan_mode from a live PLAN backend at startup so
the [PLAN] indicator shows and the first /plan toggles off, not on.
- Fix collision with pre-existing planning tests: /plan <task> message keeps
"Creating plan" substring; /plan no-arg test updated for the intentional
persistent-toggle behavior.
- Add regression tests for restore-on-exit and startup sync.
Co-authored-by: Mervin Praison <[email protected]>
Address two Greptile P1 issues in the interactive shell escape:
- attach !!cmd output even when the command fails (do not silently
drop context the user explicitly requested)
- retain _pending_context until agent.start() succeeds so a model
error does not lose the attached shell output
Applies to both the REPL and TUI paths; adds regression tests.
Co-authored-by: Mervin Praison <[email protected]>
Cap build_recap() at RECAP_MAX_CHARS (3500) so an unbounded persisted/
compaction summary can never exceed Telegram's 4096-char message limit or
flood a terminal. Only the older summary is trimmed; the recent tail is
always preserved. max_chars<=0 disables the cap for full-block callers.
Fixes the valid unbounded-output concern raised in review; keeps the fix at
the core layer so every channel (CLI + all bots) benefits without per-adapter
plumbing.
Co-authored-by: Mervin Praison <[email protected]>
Address reviewer findings on the custom-command bridge (#3729):
- Telegram: register a catch-all MessageHandler(filters.COMMAND, ...) after
the built-in/registered CommandHandlers so file-based and entry-point
slash commands (never registered as explicit handlers) actually reach
handle_command and render, instead of being silently dropped.
- Resolver: require BOTH deployment opt-in and the command's own
allow_shell frontmatter before live !`cmd` substitution runs, so a
deployment enabling shell can't upgrade a command that declared it off.
- Telegram custom-command reply now routes through the normal delivery
pipeline (pop_last_presentation, fire_message_sending,
_send_response_with_media, render_presentation, fire_message_sent) and
sanitizes errors via safe_log_message/extract_root_cause_from_error/
safe_error_message instead of leaking raw exceptions to chat users.
- /help and native command-menu entries now merge resolver-discovered
file/entry-point commands (builtin/registered precedence preserved).
- Tests: add per-command allow_shell gating coverage.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
- Record SKILL.md mtime when a LoadedSkill enters the index (discover/reload/
add_skill) so an edit made between discover() and the first reload() is
detected instead of silently masked.
- Track discovery-owned skill names so reload() no longer reports skills
registered via add_skill() as removed (backward compatible).
- Refresh the change-detection baseline after manager-owned telemetry writes
so a telemetry-only SKILL.md update is not misread as a content change and
does not drop an activated skill.
- Make `praisonai skills reload` an honest scan report (no live-session
consumer exists cross-process) instead of an always-empty reload diff.
- Add tests: edit-before-first-reload, add_skill preservation, telemetry-only
no-false-change.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
- Force stream=False so a TTY streaming generator is not str()'d into a repr;
defensively materialize any generator that slips through.
- Explicitly set autonomy=False on the side agent so it can never trigger the
tool-using autonomous loop regardless of ambient config (read-only contract).
- Parse --keep only as the leading option so '/btw what does --keep mean?' is
preserved as question text.
- Replace the unconditional 'or True' rendering assertion with a real stdout
capture; add tests for leading-only --keep, autonomy=False, and generator
materialization.
Co-authored-by: Mervin Praison <[email protected]>
Address blocking reviewer findings on #3728 plugin runtime:
- discovery: trust gate now judges a plugin file by its own location, so a
repository-controlled symlink under .praisonai/plugins can no longer bypass
PRAISONAI_ALLOW_PROJECT_PLUGINS by pointing its target outside the project.
- discovery: track only tools a module actually contributed (pre-exec registry
snapshot) so unload never unregisters tools owned by another plugin; guard
_loaded_plugin_tools with a lock.
- loader: preserve boolean `plugins.enabled: true` (no longer collapses to an
empty allow-list that disables everything); refuse ambiguous disable.
- loader: fail fast when writing a TOML config without tomli_w instead of
writing an ignored YAML sidecar (config split-brain).
- CLI plugins: reload unloads stale single-file modules before rediscovery and
reports real counts + the discovery gate; disable unloads single-file plugin
tools; doctor checks registered-plugin hooks; plain-text output (no Rich
markup via typer.echo); chained exceptions; logged swallowed errors.
- tests: add symlink-gate, boolean-enabled, and isolated unload cases.
Co-authored-by: Mervin Praison <[email protected]>
Give the flagship `code` command a scripting-grade headless mode at parity
with `run --output json`/`chat --json`. `-p/--print` routes around the
decorated interactive path (which prints `Chat mode:`/`Prompt:` diagnostics
+ a profiling block and always exited 0), builds the code agent directly,
and emits a clean machine-readable envelope {result, session_id,
usage:{in,out,cost}, status} on stdout. Exit code reflects status (0 ok,
nonzero on error/empty result). `--resume <id> -p` composes for scripted
multi-turn. Usage is read from the existing token collector + cost tracker,
so no new Agent params, exports, or wrapper wiring are introduced.
Co-authored-by: MervinPraison <[email protected]>
Expose mid-session conversation forking that previously only existed as a
startup flag. Adds:
- /branch [title] [--at N] in the interactive REPL, forking the live
UnifiedSession, switching onto the fork, and recording parent/child lineage.
- praisonai session fork <id> [--at-message N] [--title ...] mirroring the
existing run --fork HierarchicalSessionStore substrate.
- Fork lineage (parent_id/children_ids) on UnifiedSession, merge-safe, shown
in /session and session list.
Wrapper-only change; no praisonaiagents core edits, no new deps.
Co-authored-by: MervinPraison <[email protected]>
Sessions were addressable only by opaque id. Add a lightweight,
metadata-only rename:
- DefaultSessionStore.rename_session() stores metadata["title"] via the
existing locked read-modify-write path; empty title clears it.
- list_sessions() surfaces "title"; _session_title() prefers it.
- session_resolver.rename_session() targets the canonical store holding
the id (mirrors delete_session).
- `praisonai session rename <id> <title>` subcommand; `session list`
Name column prefers the title, falling back to agent name.
Backward compatible: un-renamed sessions still resolve/resume by id.
Co-authored-by: MervinPraison <[email protected]>
Surfaces the already-complete background-task substrate on the interactive
surfaces so users can check on backgrounded work without leaving the session.
- interactive_legacy: /tasks (list), /tasks <id> (detail), /tasks cancel <id>
via the existing BackgroundHandler renderer
- bots/_commands: register `tasks` + handle_tasks_command with compact,
per-user-scoped rendering (owner via task metadata user_id)
- background: add lazy process-wide get_background_runner() so all surfaces
share one runner view
- fix latent crash in the CLI detail renderer when duration_seconds is None
Co-authored-by: MervinPraison <[email protected]>
Adds a working /diff to the coding REPL showing all file changes made this
session (session baseline -> working dir), with --turn and <file> scopes,
reusing the existing CheckpointService engine via SessionCheckpointManager.
Replaces the wrapper TUI's dead /diff and /undo stubs (which only printed
"use git diff" help text) with real handlers backed by the same engine as
the legacy REPL. Default-safe: when checkpointing is disabled, /diff reports
how to enable it rather than failing silently.
Also verifies and regression-tests the wrapper-resident `context` command
mapping (resolves via praisonai.cli.commands.context, not the placeholder
local module).
Co-authored-by: MervinPraison <[email protected]>
Reuses the existing gated executor (PRAISONAI_ALLOW_SHELL env-gate, 30s
timeout, 100KB output cap) from custom_definitions.py via a new shared
run_shell_escape helper. Wires !cmd / !!cmd handling into the legacy REPL
and async TUI input paths before command/prompt dispatch, rendering output
inline without consuming a model turn. !!cmd attaches output as context for
the next turn.
Co-authored-by: MervinPraison <[email protected]>
Wire the existing PermissionMode.PLAN enforcement into the REPL /plan slash
command instead of a one-shot prompt template. /plan toggles read-only mode
(set_permission_mode(PLAN)), /plan off exits, /plan <task> plans under
enforcement; async TUI shows a [PLAN] status indicator. Also list plan,
accept-edits and bypass in the --approval help text.
Co-authored-by: MervinPraison <[email protected]>
Reuse the existing summariser purely to inform the user with a 'where were we' block, without mutating the transcript or triggering compaction. Adds a core build_recap() primitive, the /recap bot command, and a --recap flag on session show.
Co-authored-by: MervinPraison <[email protected]>
Re-scan skill sources into a running session without restart. reload()
diffs discovery against the current registry, swaps the index atomically
(index changes take effect on the next turn, not mid-turn), preserves
activation/telemetry for unchanged skills, and deactivates removed ones.
Adds a thin `skills reload` CLI parity command reporting +added/~changed/-removed.
Co-authored-by: MervinPraison <[email protected]>
Ask a side question in a parallel, throwaway context so the main task's
history and momentum stay untouched. Builds a fresh read-only agent, runs
the question in isolation, renders a distinct block, and never appends to
the main conversation history. Opt-in `/btw --keep` records a one-line note.
Co-authored-by: MervinPraison <[email protected]>
Address reviewer findings on $1..$n interpolation:
- preserve literal out-of-range dollar-number text (e.g. legacy "$100")
instead of erasing it
- tokenize with non-POSIX shlex so Windows paths (C:\Users\alice) survive
- merge $ARGUMENTS + positional substitution into a single pass so injected
tokens that look like $1/$ARGUMENTS are never re-scanned
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Bots were a command island: .praisonai/commands/*.md and plugin-bundle
commands surfaced only in the code REPL/TUI, never in Telegram/Slack/etc.
This adds a shared CustomCommandResolver in praisonai-bot that consumes the
existing custom_definitions loader/interpolator (via the sanctioned
_code_bridge seam — no cross-tier hard dependency, no reimplementation) with
a bot-appropriate safety posture:
- Shell (!`cmd`) substitution OFF by default regardless of frontmatter;
opt in per deployment via bots.commands.allow_shell. When off, live
segments render inert instead of executing or failing the command.
- Project-scope only by default (user ~/.praisonai excluded unless
include_user_scope), allow-listable via expose.
- Builtin precedence preserved; file commands merged into /help and the
command menu through the shared ChatCommandMixin (all adapters benefit).
- praisonai.bot_commands entry-point group lets installed packages add bot
commands without forking; file/project commands win on collision.
Telegram is wired as the reference adapter (catch-all dispatch renders the
command and submits it via the normal session.chat path). Adds config schema
(BotCommandsConfigSchema) and TDD tests covering project command execution,
shell-off-by-default, allow-list, user-scope exclusion, builtin precedence /
help merge, and entry-point resolution.
Co-authored-by: MervinPraison <[email protected]>
Defect 1 (config split-brain / fake CLI): add core get_plugin_registry()
returning real entry-point, registered and single-file plugins with
provenance and enabled state; the praisonai-code plugins CLI now lists/
inspects/enables against it and deletes the hardcoded four-plugin list.
enable/disable write the plugins.enabled allow-list in .praisonai/config.yaml
(the same file the runtime reads) via a new config-loader write path — no
more ~/.praisonai/config.json split-brain.
Defect 2 (trust-gate bypass): route project-local single-file plugin exec
in plugins/discovery.load_plugin through an opt-in gate
(PRAISONAI_ALLOW_PROJECT_PLUGINS / plugins.allow_project_plugins, default
false), mirroring the project-tools gate. A cloned repo's
.praisonai/plugins/*.py no longer runs until the user opts in. User-global
plugins remain trusted.
Defect 3 (leaky unload / unreachable reload): unload_plugin now unregisters
the tools a module harvested (tracked per module) instead of leaking them;
new `praisonai plugins reload` forces rediscovery + hook rewire so plugins
take effect without a restart.
Co-authored-by: MervinPraison <[email protected]>
Adds the minimal, self-contained slice of the plugin-bundles proposal that
strengthens existing local commands without a new subsystem: parse
argument-hint/model/tools (allowed-tools) frontmatter onto CustomCommand and
support shell-style positional $1..$n interpolation alongside $ARGUMENTS.
Positional tokens are split with shlex, injected before $ARGUMENTS (so user
input is never re-scanned), and escaped identically so they can never
introduce shell substitution. Legacy two-field command files are unchanged.
Co-authored-by: MervinPraison <[email protected]>
Address reviewer feedback on PR #3726 (Greptile/CodeRabbit):
- Never silently drop unsupported delivery targets: _can_deliver now always
dispatches a configured target so _dispatch_delivery raises and the caller
records delivery_error (matches PR's stated contract).
- Reuse chunk_message so Telegram/Slack/Discord size limits are not exceeded.
- Fall back to the gateway's persisted HomeChannelRegistry state file when
{PLATFORM}_HOME_CHANNEL env is unset, so gateway-registered home channels
resolve out of process.
- Preserve Discord threaded context via message_reference (parity with the
Telegram/Slack thread_id handling).
- Tests updated to lock the new contract (chunking, discord thread reference,
registry fallback, unsupported-target error recorded).
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
The bot layer's is_permanent_target_failure recognises a broader set of
whole-target death patterns (bot is not a member, need administrator
rights, channel_archived, ...) than core's deliberately narrow text
classifier. Previously classify_send_failure returned "unknown" for those,
so DeliveryRouter persisted a misleading "unknown: bot is not a member"
dead-target reason. Now, when core returns "unknown" but the broader
predicate confirms a permanent failure, the kind is upgraded to
"forbidden" so diagnostics read "forbidden: ..." — without over-classifying
genuine unknowns/transient errors (they stay unknown/transient, retryable).
Addresses Greptile P2 review feedback on PR #3725.
Co-authored-by: Mervin Praison <[email protected]>
Scheduled jobs could only deliver their `deliver:` target when a live,
in-process bot adapter was running in the same process as the scheduler.
Running `praisonai schedule tick` out of process (OS cron, CI, serverless,
scale-to-zero) computed the result but silently dropped delivery because the
executor's injected `delivery_handler` was None.
This adds a stateless, token-authenticated standalone sender per platform
(Telegram/Slack/Discord) in the praisonai-bot wrapper. When no live
`delivery_handler` is wired, the executor falls back to a single HTTP call
using the same `{PLATFORM}_BOT_TOKEN` env the gateway uses, with a bare
`deliver: telegram` home-channel target resolving its chat id from
`{PLATFORM}_HOME_CHANNEL`. Delivery failures are recorded as `delivery_error`
exactly as the live-adapter path does.
Wrapper-only change (no core edits, no new Agent params, zero new deps —
stdlib urllib). The live-adapter path is unchanged.
Co-authored-by: MervinPraison <[email protected]>
Add SendErrorKind enum + error_kind/retryable fields to core SendResult, a
pure status/text-aware classify_send_error fallback, and a classify_error seam
on BasePlatformAdapter. _send_with_retry now classifies failures once and
short-circuits provably-permanent kinds (forbidden/target_not_found/auth_fatal/
invalid_request) instead of blindly retrying. The bot-layer DeliveryRouter now
records dead targets by kind via the shared taxonomy, replacing English-only
substring reasons.
Co-authored-by: MervinPraison <[email protected]>
A fast-exiting command (e.g. sys.exit(3)) could be mis-reported as a
[exit 124] timeout on a loaded CI runner: after the reader thread hit
stdout EOF, proc.poll() could transiently return None before the exit
status was reaped, and the old logic inferred a timeout purely from
process state and SIGKILL'd the already-exiting process. Timeout is now
decided solely by the wall-clock deadline, with a brief grace wait to
reap fast exits, so the real exit code is preserved.
Co-authored-by: Mervin Praison <[email protected]>
- DeferredResolver.resolve now buffers values that arrive before the handle
is registered (early completion) instead of discarding them; the buffered
value is delivered when register()/register_if_absent() runs.
- Add register_if_absent() so the LLM run loop registers atomically and a
gateway-owned or concurrent-turn callback is never clobbered.
- LLM._register_deferred_if_any uses register_if_absent (no check-then-set race).
- cancel() clears any buffered early resolution.
- Add tests for early-resolution buffering, atomic no-clobber, cancel-clears-buffer.
Co-authored-by: Mervin Praison <[email protected]>
Move max_rpm<=0 validation ahead of the explicit-limiter check in both
Agent.__init__ and yaml_parser so ExecutionConfig(max_rpm=0, rate_limiter=obj)
raises ValueError as required by the behaviour matrix. Add regression test.
Co-authored-by: Mervin Praison <[email protected]>
Address reviewer feedback on PR #3720:
- Catch UnicodeDecodeError alongside JSONDecodeError so corrupt/binary
session files are quarantined instead of propagating an uncaught
decode error (both DefaultSessionStore and HierarchicalSessionStore).
- Make _quarantine_corrupt() pick a collision-free destination so two
corrupt files in the same millisecond are each preserved distinctly.
- Strengthen tests: assert exact byte-for-byte preservation, add an
invalid-UTF-8 regression, and add a HierarchicalSessionStore
corruption-recovery smoke test verifying the SESSION_PERSIST_FAILED
hook metadata.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
max_rpm was stored on the Agent but never wired to a runtime RateLimiter,
so ExecutionConfig(max_rpm=N) did not throttle requests. Now the Agent
auto-builds RateLimiter(requests_per_minute=N) when max_rpm is set and no
explicit rate_limiter is provided. Explicit rate_limiter still takes
precedence; max_rpm<=0 raises ValueError. YAML max_rpm now also wires a
live limiter.
Co-authored-by: Dhivya-Bharathy <[email protected]>
Add a lightweight DeferredResolver registry in tools/call_executor.py that
links a deferred handle_id to a resolution callback. The run loop now registers
any deferred tool result (via LLM._register_deferred_if_any) so that a later
resolve_deferred(handle_id, value) — fired on background completion — re-injects
the result instead of it being lost. Exposes register_deferred/resolve_deferred/
get_deferred_resolver/DeferredResolver from praisonaiagents.tools.
Co-authored-by: MervinPraison <[email protected]>
A malformed session JSON file was read as an empty session and then
overwritten by the next write, permanently destroying a user's history
with only a log line. Now the corrupt file is quarantined aside
(<file>.json.corrupt-<ts>) before starting fresh, preserving recoverable
bytes, and the event is surfaced via the existing SESSION_PERSIST_FAILED
hook rather than silently dropped. Applied to both the default and
hierarchical stores.
Co-authored-by: MervinPraison <[email protected]>
Extend the existing import-free header parser so a single-file plugin can
declare its capability surface (Channels, Provides/Tools, Config,
Auto Enable When Configured) statically. discover_plugins()/list_plugins
already surface this metadata to onboarding/doctor without importing the
plugin's runtime, enabling capability enumeration and config validation
before runtime loads.
Co-authored-by: MervinPraison <[email protected]>
Address reviewer findings on plugins/tools add commands:
- uv pip install now pins --python sys.executable so the package lands in the
interpreter running the CLI rather than an env uv auto-discovers.
- Add importlib.invalidate_caches() after install so a just-installed
distribution is importable before discovery runs.
- tools add now builds a fresh ToolResolver after install so instance-level
availability caches (e.g. praisonai_tools importability) are re-evaluated;
invalidate() only clears the per-name resolve cache.
- Add --global option to both commands (uv --system / plain pip) for installing
into the ambient system environment.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Concurrent callers of discover_plugins() could both pass the _discovered
check before either set it, double-loading entry points and double-counting.
Wrap the first scan in the re-entrant registry lock so concurrent callers
block, then observe _discovered and return 0 without rescanning. The get()
path already holds the RLock, so re-acquisition is deadlock-safe.
Co-authored-by: Mervin Praison <[email protected]>
Adds one-command install-and-verify for plugin/tool packages from the CLI.
Installs via the resolved installer (uv pip or python -m pip), triggers
discovery, and reports exactly which plugins/tools registered (name, type,
hooks/source) or exits non-zero with a clear message if nothing was
discovered. Supports --dry-run (verify only) and --upgrade.
Co-authored-by: MervinPraison <[email protected]>
The core tool registry now discovers the documented canonical
`praisonai.tools` entry-point group in addition to the legacy
`praisonaiagents.tools` and `praisonai.tool_sources` groups (kept as
deprecated aliases with a one-cycle DeprecationWarning). Because the CLI,
YAML and Python surfaces all defer to the core registry, an installed
third-party tool package is now resolvable by name across all three
surfaces automatically. The canonical group wins on a name collision and
the lazy, cached entry-point loading pattern is preserved.
Co-authored-by: MervinPraison <[email protected]>
- run_sync_or_offload now holds the in-flight bridge future and cancels it
when the worker join times out, so stuck async work stops instead of
lingering on the bridge loop (CodeRabbit).
- A2U _MAX_SUBS/_QUEUE_MAX now fall back to defaults on non-positive or
unparsable env values, preventing asyncio.Queue(maxsize<=0) from silently
becoming unbounded (CodeRabbit).
Co-authored-by: Mervin Praison <[email protected]>
- glob/grep: PRAISONAI_WORKSPACE confinement is now opt-in; without it set,
no sandbox is enforced (cwd was never a real boundary and enforcing it
broke all callers passing an explicit directory + 15 CI tests).
- a2u_server: fail-closed guard now reads the launcher-set
PRAISONAI_CALL_BIND_HOST (with PRAISONAI_A2U_BIND_HOST override) and
rejects unauthenticated non-loopback/unknown binds, matching the existing
call-server security contract (fixes Greptile P1).
Co-authored-by: Mervin Praison <[email protected]>
- _async_bridge: add awaitable arun_sync_or_offload() sibling and bound the
run_sync_or_offload() worker join with a timeout so a stuck coroutine can no
longer pin the caller (and, when the caller is the loop thread, the loop)
indefinitely.
- tools (glob/grep/multiedit): confine to PRAISONAI_WORKSPACE root, filter
security.is_protected paths from results/reads, refuse edits to protected
files, and cap per-line length in grep to bound ReDoS cost.
- endpoints/a2u_server: refuse fail-open auth on non-loopback binds, cap
subscriptions, and bound per-subscription queues with drop-on-full so a
slow/stalled consumer or subscription flood cannot OOM the process.
Co-authored-by: MervinPraison <[email protected]>
Address two P1 review findings on PR #3708:
1. Racy output-mode registration: concurrently-constructed Agents could
both observe "no mode enabled" and clobber each other's process-global
display callbacks. Wrap the check-and-enable in a module-level lock
(_output_mode_lock); the common silent path stays lock-free.
2. MCP "Error: " prefix misclassification: a successful MCP tool may
legitimately return text starting with "Error: ", which the prefix-only
normalizer converted into a retryable error dict. Narrow normalization
to MCP's unambiguous internal timeout signatures only, preserving valid
tool output.
Co-authored-by: Mervin Praison <[email protected]>
- __init__.py: point HarnessProfile/resolve_harness/register_profile lazy map at
praisonaiagents.model_harness.profiles (real submodule) so top-level access no
longer re-enters the module package __getattr__ under the non-reentrant lock.
- _lazy.py: make _cache_lock an RLock as defense-in-depth so any future mapping
of this shape degrades to redundant work instead of a self-deadlock.
- agent/agent.py: make process-global output modes (editor/trace/status)
mutually exclusive — first mode wins, so a second Agent with a different mode
cannot clobber another agent's callbacks (wrong formatting/redaction routing).
- agent/tool_execution.py: normalize MCP "Error: ..." string failures into the
native {"error": ..., "timeout": ...} dict shape so MCP tool failures engage
retry, doom-loop detection and circuit-breaking like native tool failures.
Co-authored-by: MervinPraison <[email protected]>
- Reset task status/result/retry_count/variables before each batch item so
run_task/arun_task actually re-execute (previously items 2..N returned the
first item's stale "completed" result).
- Snapshot task run state before the batch and restore it in finally, keeping
the public Task API backward-compatible.
- Validate each input is a dict: fail_fast raises ValueError, continue records
a per-item error instead of crashing.
- Add regression tests: two-item lifecycle reset, invalid-input handling.
Co-authored-by: Mervin Praison <[email protected]>
Match the injected manager_task by its actual task id (manager_task_id)
instead of its name in both sync and async hierarchical paths. A legitimate
user task named "manager_task" is no longer incorrectly rejected/hidden.
Also state 0-based ids in the manager schema and add regression coverage.
Co-authored-by: Mervin Praison <[email protected]>
The hierarchical manager could delegate to the injected manager_task because
validation only checked membership in self.tasks (which includes it) and the
schema field described task_id as "1-based" while runtime IDs are 0-based. As a
result the manager would self-select task_id=1 and the real user task never ran.
- manager_schema.py: task_id description now references the exact 0-based ids
and forbids selecting manager_task.
- process.py (sync + async): reject unknown ids AND manager_task; re-prompt with
only delegable (non-manager) task ids in the error context.
Co-authored-by: Dhivya-Bharathy <[email protected]>
When a Task sets output_pydantic (or output_json) but the agent returns
freeform prose, the task no longer silently succeeds with pydantic=None.
- default_completion_checker: structured output that was requested but not
produced is now treated as NOT complete, driving the existing retry loop
and leaving the task "failed" after retries instead of succeeding on prose.
- _process_task_result: use model_validate, include the schema name and the
underlying error in the warning, and return TaskResult(success=False) with
a clear error when structured output could not be produced. Raw output is
preserved for debugging.
Co-authored-by: Dhivya-Bharathy <[email protected]>
Adds a lightweight map-over-inputs primitive that runs the same team once
per input dict, reusing the existing {{key}} `variables` interpolation
(per-run task copy => template immutability + isolation). Returns an
aggregate dict with per-item outcomes, ordered results, continue/fail_fast
error policy, and a batch token-usage rollup. No new heavy classes/modules.
Co-authored-by: Dhivya-Bharathy <[email protected]>
FunctionTool.get_schema was a near-verbatim copy of the inherited
BaseTool.get_schema producing byte-identical output. Since __init__
always sets _schema_override and parameters, the parent's hasattr guard
is always satisfied, making the override dead duplication. Removed it so
FunctionTool inherits BaseTool.get_schema, and dropped the now-unused
copy import.
Co-authored-by: MervinPraison <[email protected]>
Replace triplicated eight-field mapping in Agent.context_manager with a
single _manager_config_from_context_config helper. Pure DRY clean-up,
identical output for all input types (ContextConfig, preset string, dict).
Co-authored-by: MervinPraison <[email protected]>
- await awaitable on_event results so async callbacks actually run
- when a progress sink is passed, route through subprocess so SDK mode
never silently drops progress events
- replace vacuous stream test assertion with exact event equality
- add async-callback coverage
Co-authored-by: Mervin Praison <[email protected]>
ClaudeCodeIntegration.stream() built `claude -p --output-format stream-json`
without --verbose, which the CLI rejects, so it could never run -- and nothing
added --include-partial-messages, so no token/tool-use deltas were emitted.
_build_command now forces both flags for stream-json.
execute() gains an optional on_event/on_progress callback: when supplied, the
run is streamed and every parsed event (system/init, tool-use, text deltas,
result) is forwarded live so a caller or UI can show progress, while the final
result text is still returned. A failing progress sink never breaks the run.
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Prefer as_dict(), fall back to dataclasses.asdict for a bare
GatewayStatus-shaped snapshot, and use json.dumps(default=str) so a
partially-populated or non-standard snapshot never dead-ends.
Co-authored-by: Mervin Praison <[email protected]>
Adds a lightweight, read-only introspection tool so an agent can inspect
and report its own live gateway state (run status, active-session
inventory, delivery/DLQ backlog, degraded owners) from inside a turn.
Mirrors the send_message / OutboundMessengerProtocol pattern: core ships
GatewayStatusProtocol + GatewayStatus snapshot shape and the built-in
gateway_status tool, which resolves the live source from the per-turn
session context (register_gateway_status). When no gateway is running,
the tool is simply not offered and fails cleanly. No Agent-class changes,
no new heavy dependencies; the concrete live binding belongs in the
praisonai-bot wrapper.
Co-authored-by: MervinPraison <[email protected]>
A non-numeric persisted command_timeout (e.g. a hand-edited "five") raised
ValueError at float(...) outside the command error handler, escaping the ticker
loop and breaking every other job. Normalise defensively in the executor:
non-numeric, non-positive, or non-finite values fall back to 60s and the job
still runs. Adds a regression test.
Co-authored-by: Mervin Praison <[email protected]>
- Fix CI: test_command_action.py used the deprecated
asyncio.get_event_loop().run_until_complete() which raises RuntimeError
on Python 3.10+ with no current loop. Switch to asyncio.run() to match
the sibling test_condition_gate.py / test_run_policy.py convention.
- Address Greptile P1 (memory): stream and cap command output as it is read
(bounded to _MAX_COMMAND_OUTPUT_CHARS) instead of buffering the full
stream via communicate(), so a chatty/runaway command in the long-running
gateway cannot exhaust memory. Timeout still kills the process group.
Co-authored-by: Mervin Praison <[email protected]>
Adds a model-free command action to scheduled jobs: a job carrying a
`command` runs that shell command on its schedule and delivers stdout
verbatim to its DeliveryTarget — no agent resolved, no model turn taken.
- core: `command`/`command_timeout` fields on `ScheduleJob` with
backward-compatible serialisation (persisted only when set).
- wrapper (praisonai-bot): executor runs the command off the event loop,
bounded by `command_timeout` and killed with its process group on POSIX
(mirrors ShellConditionGate); non-zero exit surfaces exit code + output;
output is bounded before verbatim delivery via the existing path.
- CLI: `praisonai schedule add --command/--script [--command-timeout]`.
Additive and backward-compatible: agent-driven jobs are untouched.
Co-authored-by: MervinPraison <[email protected]>
Non-numeric, non-finite (NaN/inf), or non-positive timeout_s values now
fall back to the 120s default and are clamped to a 3600s upper bound so a
model-controlled timeout can never undermine the tool's bounded-wait
"never a silent hang" guarantee (Greptile review, PR #3691).
Co-authored-by: Mervin Praison <[email protected]>
Adds an agent-callable request/reply tool that sends a prompt to a symbolic
target and awaits that target's next correlated reply, returning it into the
agent's turn. Unlike fire-and-deliver send_message, it always resolves to a
typed outcome (reply | timeout | undelivered | no_route) so a path never hangs
silently.
Core-only surface mirroring the existing send_message pattern:
- ConversationReply + ConversationReplyStatus + ConversationRequestProtocol in
gateway/protocols.py (protocol seam bound by the running gateway/bot).
- register/get/clear_conversation_requester context slot in session/context.py.
- ask_conversation tool in messaging_tools.py, reusing the send-policy guard
and cross-thread loop scheduling used by send_message.
Co-authored-by: MervinPraison <[email protected]>
Close two gaps where the read-only --plan contract silently downgraded:
- run --plan --profile: thread the resolved approval backend
(PermissionMode.PLAN) into _run_prompt_profiled and
_run_from_file_profiled so profiled runs stay permission-gated.
- code --plan REPL: the interactive worker's _build_agent now unpacks
args.agent_approval into Agent(**agent_extra_kwargs), matching the
single-prompt path, so REPL sessions deny mutating tools instead of
falling back to the legacy approval prompt.
Adds regression tests for both paths.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
- run.py: move config + recorded-session model resolution ahead of the keyless
local-first credential gate so a resumed session on a reachable local endpoint
is no longer silently switched to the local model (Greptile/CodeRabbit).
- store.py: SessionData.from_dict now folds legacy top-level model/llm (mirrored
by to_dict) back into metadata so historical sessions recover their recorded
model on resume (CodeRabbit backward-compat).
- tests: add latest-turn-wins and legacy top-level normalization coverage.
Skipped async get_session_model accessor: no async consumer exists; only the
synchronous CLI resume path calls it, so it would be dead API surface (AGENTS.md).
Co-authored-by: Mervin Praison <[email protected]>
Add a first-class `--plan` boolean flag to `praisonai run` and `praisonai code`
that selects the existing read-only planning permission mode
(PermissionMode.PLAN). It maps onto the same approval plumbing as
`--approval plan` rather than a bespoke deny-set, so the agent may
explore/read/search while every mutating tool is denied.
Wrapper-only change: core (Agent(approval="plan")) and YAML (mode: plan)
already thread onto PermissionMode.PLAN, so no new enforcement logic or Agent
params are introduced. Contradictory permission flags fail closed.
Co-authored-by: MervinPraison <[email protected]>
Resume restored conversation history but not the model the session was
running: with no explicit --model, it re-resolved the current default, so a
change to the user's default between runs silently switched the model
mid-conversation. Now --continue/--session restore the recorded model
(explicit --model still wins and updates it going forward).
- core: add DefaultSessionStore.get_session_model() reading the session-level
metadata model, falling back to the latest turn's recorded model.
- wrapper: resolve and restore the recorded model in run_main before dispatch
when no model was chosen, with an info line noting the restored model.
Co-authored-by: MervinPraison <[email protected]>
install_hook()/_resolve_backend() were never called by any runtime path
(Greptile P1). Approval is already enforced via the adapter's
_resolve_agent_approval() -> Agent(approval=ApprovalConfig(...)) core gate,
so these methods were a redundant, untested, second before_tool enforcement
that would double-gate. Removing per AGENTS.md (no dead code with no live
consumer / duplicate behaviour). Tests unchanged and green.
Co-authored-by: Mervin Praison <[email protected]>
- praisonai_adapter: resolve YAML/CLI handoff {to:[roles],...} into core
Agent.handoffs after all agents exist, mapping timeout/max_depth/
max_concurrent/detect_cycles onto HandoffConfig. The --handoff family is
no longer silently dropped.
- _approval_spec.install_hook: replace the two TODO no-op stubs with real
backend dispatch (prompt via resolved backend, deny on rejection, fail
safe when no backend is available).
- auto.py: drop the duplicated LEGACY TOOLS block on the resolver-available
path (it repeated the installed tool list for zero information gain).
Co-authored-by: MervinPraison <[email protected]>
PR #3681 fixed the Windows cp1252 UnicodeEncodeError only in docker.py, but
the same bare-emoji print() crash remained in the other Python-API deploy
paths that also bypass the CLI's _configure_stdio() bootstrap:
- api.py foreground serve (🚀📁🔗💬)
- providers/aws.py, azure.py, gcp.py deploy/destroy (📦📝🚀🛑🗑️🔧🌍)
Replace them with ASCII [api]/[aws]/[azure]/[gcp] prefixes. cli/features
uses Rich console.print (encoding-safe) and is left unchanged.
Co-authored-by: Mervin Praison <[email protected]>
The praisonai-deploy Python API path (Deploy.deploy) bypasses the CLI's
UTF-8 stdio bootstrap from #3605, so bare emoji print() lines in docker.py
raised UnicodeEncodeError on default Windows cp1252 consoles and were masked
as "Docker build failed". Replace the six emoji status prints with portable
ASCII "[docker]" prefixes so both CLI and Python API paths are encoding-safe.
Co-authored-by: Dhivya-Bharathy <[email protected]>
Addresses the two P1 findings from Greptile on PR #3679:
1. Secret-context capture reuse: definition_hash excluded env values, so a
capture whose setup baked env-derived state into the filesystem could be
reused across provisions with the same env names but different values. Add
capture_key() which binds env *values* and use it as the docker image tag /
reuse key; keep the value-free definition_hash only as a non-sensitive
display label in the registry.
2. Concurrent registry lost-update: registry.json read-modify-write was
unlocked. Add a best-effort fcntl file lock (no-op on non-POSIX) and route
capture/touch/prune through an atomic _update_registry() so concurrent
writers don't drop each other's entries. Image deletion in prune moved
outside the critical section.
Tests: +4 core capture_key tests, +3 docker tests (secret isolation, concurrent
preservation, definition label). 28 core + 10 docker tests green.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Amortise environment provisioning: after packages + setup: run once, the
docker backend commits the prepared container to a local image keyed by a
stable definition hash, and subsequent provisions of the same definition
start from that capture — skipping pull + install + setup.
Core (praisonaiagents):
- definition_hash(config): stable sha256 over image/packages/setup/env-names/
resources (env values excluded so secrets never enter the key).
- SupportsCapture optional protocol (default: backends without it stay ephemeral).
- Loader accepts refresh: and capture: keys (carried in metadata; no new
ComputeConfig field without a typed consumer).
Docker compute (praisonai wrapper):
- capture()/has_capture() via docker commit -> praisonai-env:{hash12}.
- Reuse-on-match; edited definition -> new hash -> full rebuild + new capture.
- refresh: runs only on capture-based starts (cheap incremental step).
- Registry ~/.praisonai/environments/registry.json + list_captures()/
prune_captures() age-based GC.
- Failed commit degrades to today's ephemeral behaviour with a log line.
managed_local.provision_compute carries capture metadata (refresh/capture)
from the definition to the backend.
Tests: definition-hash stable/sensitive + env-value exclusion; docker
capture+reuse skips setup; definition change invalidates; refresh on hit
only; capture failure degrades ephemeral; non-capturing no-op; registry GC.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
On a second .start()/.run() of the same AgentTeam, the prior run's
synthetic manager_task remains last in self.tasks, so the return-task
snapshot picked it and returned the previous Manager output instead of
the final user-task result. _last_hierarchical_task_id now walks tasks
in reverse and skips any manager_task, selecting the real final task.
Addresses Greptile P1 review on agents.py.
Co-authored-by: Mervin Praison <[email protected]>
- process="hierarchical": track the last real (user-supplied) task id before
the synthetic manager_task is injected, so .start()/.astart()/.run() return
the final delegated task's result instead of the Manager's own output.
- FileMemory/LearnManager: re-read the on-disk state before each write so two
instances sharing the same user_id no longer clobber each other's entries
(last-writer-wins fixed for short/long-term, entities, auto-promotion, learn
stores).
- Approval registry: scope the "already approved" cache key to the requesting
agent so one agent's approval can't silently pre-authorize an identical call
from a different, stricter agent in the same context.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: MervinPraison <[email protected]>
Multi-agent gap review of the release pipeline surfaced 17 findings across
the gate, the workflow, and the bump script. This fixes the confirmed ones.
Gate (release-gate.js + nightly-release-gate.yml):
- A pypi-release run stuck in `waiting` (environment approval) blocked all
auto-releases with no age limit -- GitHub only auto-fails unapproved
deployments after 30 days, and exactly this stalled releases for 16h this
week. Waiting runs older than 6h are now ignored (with a warning linking
the run); in_progress/queued runs still block unconditionally, and the
stuck run is never cancelled -- if later approved, the concurrency group
serializes it and pypi_exists no-ops anything already published.
- PACKAGE_PATHS covered 3 of 9 published packages, so a change landing only
in e.g. praisonai-bot was never auto-released. Now lists all nine.
- The 3-day dedupe counted any successful run -- including dry_run=true,
which publishes nothing -- blocking real releases for 3 days after a dry
run. Dedupe now keys on v* GitHub releases, which only real releases create.
- The nightly path required last-green-Core-Tests SHA == HEAD exactly; a
docs-only or [skip ci] commit at the tip (the release safety-net commit
itself!) stalled the cron path indefinitely. A green ancestor with no
package-path changes since is now accepted.
- Replaced the dead 'Bump praisonai' workflow_run filter (those commits no
longer exist) with 'chore(release):', and wired the previously never-run
release-gate selftest into the gate as a step.
Workflow (pypi-release.yml):
- New `only` input: a dedicated single-package release is one dropdown pick
instead of eight skip flags. A "Resolve effective skips" step is the single
source of truth; the 19 publish/wait conditions are untouched (they gate
via the seeded pypi_exists outputs).
- PyPI existence probes now distinguish 404 (publish) from outages (fail the
run before anything is published) instead of treating any error as "not
published" and then dying on duplicate upload midway.
- The token-refresh step is continue-on-error and its consumer only swaps
tokens on success -- a failed re-mint previously overwrote a possibly-valid
token with an empty string, guaranteeing the safety net could not push.
- The safety net now (a) reverts uncommitted wrapper-side rewrites when the
wrapper release didn't complete, so a wrapper version that never reached
PyPI is not committed and then skipped past forever, and (b) retries
rebase+push 3x preferring the version bumps on conflict -- losing that
commit deadlocks future auto-releases ("already published" forever).
- "Verify PyPI versions" actually probes PyPI now; it previously echoed
checkmarks derived from input flags for publishes that may never have run.
- Dedicated releases get per-package tags (praisonai-mcp-v0.0.12) since the
wrapper's "Release v..." tag doesn't exist on that path; only packages
confirmed on PyPI are tagged.
- uv publish --check-url makes re-uploads idempotent (partial-upload
recovery); dry-run summary now includes sandbox/deploy and the effective
skip plan.
Bump script (bump_and_release.py):
- A conflicted `git pull --rebase` previously printed "trying to continue"
and proceeded from a mid-rebase detached HEAD -- tagging the wrong commit
and cascading conflict markers into the safety net. It now aborts, retries
preferring the release commit, and exits before pushing if that fails.
- Commit failures are no longer swallowed (only "nothing to commit" is
tolerated), so the tag can't silently point at the previous HEAD.
- `gh release create` is idempotent (view-then-create), unblocking reruns
after a transient failure between push and wrapper publish.
- Tag push is scoped to the release's own tag; `git push --tags -f` could
force-move historical tags.
Verified: node selftest (10 checks incl. new stale-waiting/dry-run-dedupe
cases), py_compile, YAML parse, actionlint (same 3 pre-existing SC2129
style warnings as main, nothing new), and the rebase-conflict retry logic
exercised against a scratch remote (bump wins, upstream commit preserved).
Co-Authored-By: Claude Fable 5 (1M context) <[email protected]>
Two existing tests asserted PraisonAIAgents raises ImportError (a v4
"removed" decision). Issue #3674 (owner) explicitly restores it as a
root-level silent alias for AgentTeam, which PR #3675 implements. Update
those tests to assert the restored back-compat contract instead.
Co-authored-by: Mervin Praison <[email protected]>
PraisonAIAgents was exported from praisonaiagents.agents but omitted from
the root lazy-import map and __all__, so `from praisonaiagents import
PraisonAIAgents` raised ImportError. Added it alongside its siblings and a
regression test covering all back-compat aliases.
Co-authored-by: MervinPraison <[email protected]>
Add functools.lru_cache to the pure model-capability predicates so the
same (model_name -> bool) result is computed once per process instead of
on every request/turn. Behaviour is unchanged: guards, litellm-None
fallbacks and except paths are all preserved, and keys are hashable
strings.
Co-authored-by: MervinPraison <[email protected]>
Addresses the three Greptile P1 findings on PR #3671:
- Wire load_environment_definition() into provision_compute() as an opt-in
baseline (explicit kwargs/instance config still win) so a committed
.praisonai/environment.yaml is actually applied.
- Validate nested config shapes in the loader so malformed values raise a
contextual ValueError (with file path) instead of incidental
AttributeError/TypeError.
- Tear down the just-started Docker container if package install or setup
fails, so a failed provision no longer leaks an unreachable container +
registry entry.
Co-authored-by: Mervin Praison <[email protected]>
Add the missing repo-committed environment definition joint: a lightweight
loader that maps .praisonai/environment.yaml onto the existing ComputeConfig
schema, plus the one new field (setup) with a live consumer.
- Core (praisonaiagents): ComputeConfig.setup: List[str]; load_environment_definition()
and find_environment_definition() (walks up like config discovery). YAML is
lazy-imported; unknown top-level keys raise ValueError with the file path.
network/backend preferences carried in existing typed fields (no new surface).
- Live consumer: docker compute provider runs setup commands once post-provision,
streamed to logs, with failures surfaced (raised) rather than swallowed.
- No file -> byte-identical behaviour (loader returns None; callers keep defaults).
Deliberately minimal per AGENTS.md (lightweight & powerful): no new CLI group,
no dispatcher rewrite, no SandboxConfig bridge, no RuntimeConfig remap.
Co-authored-by: MervinPraison <[email protected]>
Fix two valid reviewer (Greptile) findings in the research-writer example:
- The roles-file loader (praisonai_adapter._build_agents_and_tasks) sequences
tasks by declaration order and does not consume the top-level dependencies:
block; annotate agents.yaml and README to state this accurately.
- praisonai.run() is the Python API equivalent of the positional
`praisonai <agent_file>` CLI form (there is no `praisonai run <yaml>` CLI
subcommand for roles files); correct the README prose accordingly.
Docs/example only — no core SDK changes.
Co-authored-by: Mervin Praison <[email protected]>
The example passed topic via team.start(inputs=...), but AgentTeam.start
swallows **kwargs and never consumes `inputs`; interpolation reads only
task/team `variables` and replaces double-brace {{key}} placeholders.
Switch to AgentTeam(variables=...) with {{topic}} so the example actually
substitutes the topic instead of emitting a literal placeholder.
Co-authored-by: Mervin Praison <[email protected]>
Documents that Task.on_task_complete 2-param callbacks receive
(task_output, metadata) — NOT (task, task_output) like AgentTeam's hook.
Adds a copy-pasteable sequential human-review example and a regression
guard test. No new API surface (lightweight per AGENTS.md).
Co-authored-by: Dhivya-Bharathy <[email protected]>
Adds examples/yaml/teams/research-writer/ with a runnable single-file
agents.yaml (roles + nested tasks + dependencies) and README documenting
the existing praisonai run / AgentsGenerator loader path. No new core
modules or wrapper exports — examples/docs only, per the narrow scope.
Co-authored-by: Dhivya-Bharathy <[email protected]>
Addresses Greptile finding: the lint guard scanned examples/ + internal
CLI but omitted src/praisonai-agents/tests, where this PR migrated an
AgentTeam(...) call (crewai-tools-example.py). Reintroducing verbose=
there would previously go undetected.
Adds a scoped _SCAN_FILES list covering the specific migrated file rather
than sweeping the entire tests tree (which holds ~40 unrelated legacy
scripts still using verbose=/max_iter= that are out of scope for this PR).
Co-authored-by: Mervin Praison <[email protected]>
- flat layout (drop src/) so `python -m <slug>.main` works from the
project root without an install step
- switch YAML placeholders to double-brace {{topic}} and pass
variables= to AgentTeam (start(inputs=) was silently dropped)
- reject Python keywords in slugify to avoid invalid imports
- update pyproject packages.find to flat include and extend tests
Co-authored-by: Mervin Praison <[email protected]>
The delegate_task tool documented a `timeout` param but discarded it,
letting delegated work block past its deadline (Greptile P1). Run the
synchronous subagent spawn on a bounded ThreadPoolExecutor and return a
structured timeout failure on expiry. timeout<=0 disables the bound.
No new params/exports; reuses existing create_subagent_tool runtime.
Co-authored-by: Mervin Praison <[email protected]>
The rich.table import was executed before the console None-check, so an
ImportError bubbled to the outer handler and showed the static model list
instead of the real catalogue. Guard the import so the plain-text table
renders the live catalogue when Rich is absent (greptile P2).
Co-authored-by: Mervin Praison <[email protected]>
- Reject empty/whitespace query in forget() to prevent broad LIKE '%%'
deletion of unrelated short-term and long-term records (Greptile P1)
- Scope query-based forget() to long_term to mirror remember()/recall()
- Fix test fixture to use sqlite provider (was 'none' -> in_memory)
- Add empty-query guard test
Co-authored-by: Mervin Praison <[email protected]>
AgentTeam.__init__ accepts neither verbose= nor **kwargs, so passing
verbose= raised TypeError at construction. Verbosity is controlled via the
consolidated output= param (silent/minimal/verbose) and iteration limits via
execution=. Migrated all internal CLI, template generators, and examples off
the removed verbose=/max_iter=/session= kwargs, and added an AST lint guard
that scans examples + internal CLI for invalid AgentTeam kwargs to prevent
regression.
Co-authored-by: Dhivya-Bharathy <[email protected]>
Replace the always-failing stub in delegate_task with a call into the
existing create_subagent_tool runtime. A lightweight sub-Agent is spawned
(role derived from agent_type) to execute the task, preserving the JSON
response schema and the @require_approval(risk_level="medium") gate.
Co-authored-by: Dhivya-Bharathy <[email protected]>
praisonai models list crashed on Windows cp1252 consoles when Rich rendered
emoji (U+1F527 wrench) in the Capabilities column. Added stdout_supports_unicode()
helper and _capabilities_label() ASCII fallback, routed the table through the
encoding-aware output console, and applied the same guard to models describe/validate.
Co-authored-by: Dhivya-Bharathy <[email protected]>
Adds thin, intuitive aliases over existing long-term store/search/delete
methods and makes Memory(config=...) optional so Memory() works standalone.
No new modules, dataclasses, exports, or backend changes; fully backward
compatible.
Co-authored-by: Dhivya-Bharathy <[email protected]>
Define ManagerInstructions once at module level with extra="forbid" so the
generated JSON schema includes additionalProperties: false, which OpenAI's
strict structured-output API requires. Removes two duplicate inline class
definitions in process.py and adds a regression test.
Co-authored-by: Dhivya-Bharathy <[email protected]>
resolve_output and resolve_execution live in param_resolver.py, not
feature_configs.py. Split the test imports so resolver functions come
from param_resolver while config dataclasses stay in feature_configs.
Unblocks the entire praisonai-agents unit suite collection.
Co-authored-by: Dhivya-Bharathy <[email protected]>
Address reviewer feedback on the local-first session mirror:
- set_chat_history now mirrors the replaced transcript (Session save_state
and bot session manager persist via this path, not add_message, so those
histories were never reaching the mirror). Records carry stable ids so a
re-append is idempotent last-writer per id — the append-only shape the
mirror expects.
- _SessionMirrorWriter.enqueue drops-to-log after close() instead of
silently queuing records with no running consumer.
- The mirror writer thread is now started AFTER os.makedirs so a failed
construction on an unusable session dir never leaks an idle daemon thread.
Adds tests for all three; full session suite (123 tests) green.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Adds the core, unblocked half of session sync: a tiny SessionMirrorProtocol
(append/load/list_sessions) plus an optional mirror= on DefaultSessionStore
that appends persisted records to the mirror on a bounded background thread.
Local-first: the local write always happens first and a mirror outage never
blocks, fails, or corrupts a turn. Zero overhead / no thread when unset.
Heavy backend adapters + `session sync` CLI are deferred to the wrapper and
depend on the store-unification sibling (#3645, not yet merged).
Co-authored-by: MervinPraison <[email protected]>
- protocols.py: LocalTurnLock.release() now identity-checked via a per-key
holder map so a stale/duplicate token can never release a waiter's lease
(fixes concurrent-turns-on-one-session race). Add type-only asyncio import
under TYPE_CHECKING to resolve the 'asyncio.Lock' annotations (F821).
- config.py: reject NaN ttl (not self.ttl > 0); from_dict tolerates explicit
YAML nulls for backend/ttl via the 'or default' idiom.
- tests: add stale-token release regression, NaN-ttl rejection, null-tolerant
from_dict; make same/distinct-session concurrency tests deterministic with
asyncio.Event barriers (3.10-safe, no Barrier).
Co-authored-by: Mervin Praison <[email protected]>
UnifiedSessionStore hardcoded ~/.praison/sessions/ while every other CLI
surface reads/writes the canonical ~/.praisonai/sessions/ root via
paths.get_sessions_dir(). This made `praisonai code` conversations live in
a separate directory, invisible to `session list/show/export` and the
dashboard.
Resolve the default sessions directory from the canonical paths helper
(with a safe fallback to the legacy path if the helper is unavailable), so
code sessions land under the shared root. Explicit session_dir overrides
and the backward-compatible DEFAULT_SESSION_DIR attribute are preserved.
Co-authored-by: MervinPraison <[email protected]>
Turn serialisation is enforced by an in-process asyncio.Lock (LockMap) that
cannot see across processes/hosts, so a horizontally-scaled gateway
(replicas > 1) runs concurrent turns on one session — corrupting the shared
transcript, tripping provider strict-alternation, duplicating replies and
double-billing.
Add a pure, dependency-free TurnLockProtocol + TurnLeaseToken and a zero-cost
in-process LocalTurnLock default to core gateway protocols, plus a TurnLockConfig
selector wired into GatewayConfig (Python + YAML). The "local" default reproduces
today's asyncio.Lock behaviour byte-for-byte (single-replica unchanged, no new
dependency); "redis" is the seam for a distributed lease implementation in the
wrapper/bot package (reusing RedisConfig + the scheduler's owner+TTL pattern).
Mirrors how every other gateway robustness knob (drain, admission, rate-limit,
liveness, dead-letter) is a swappable pure protocol in core.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Address reviewer findings (CodeRabbit, Greptile) on PR #3641:
- Plumb the gateway's real bind host into enable_shell_tools via a new
keyword-only gateway_bind_host param. Production callers construct a
per-channel BotConfig that never carried the bind host, so an externally
bound (0.0.0.0) gateway was invisible to the exposure downgrade. The
gateway now passes self.config.bind_host / self._host explicitly.
- Treat every configured group_policy (including command_only) as a
multi-user surface: a group member's command can reach execute_command,
so blanket auto-approve must downgrade to approval.
- Call callable host accessors (e.g. GatewayServer.host) before
stringifying so is_loopback classifies loopback deployments correctly.
- Add tests for command_only downgrade, explicit external/loopback
gateway_bind_host, and callable host accessor resolution.
Co-authored-by: Mervin Praison <[email protected]>
- Keep DegradedCapabilityProtocol unchanged (mark/clear/list_degraded); move
find() onto new DegradedCapabilityLookupProtocol so existing external
registries retain structural isinstance conformance.
- Module guard falls back to list_degraded() when a legacy registry lacks both
the guard and find(), failing-closed instead of raising AttributeError.
- Export DegradedCapabilityLookupProtocol.
- Fix Ruff B015 pointless-comparison in no-op guard tests (assert ... is None).
- Add legacy-registry coverage for base/lookup protocol conformance and the
list_degraded() fallback.
Co-authored-by: Mervin Praison <[email protected]>
Complete the degraded-owner contract's read side (Issue #3518) by adding
the core fail-closed primitive so a request targeting a degraded owner
short-circuits to a typed, redacted "unavailable — next action" outcome
instead of proceeding and failing silently.
Adds to praisonaiagents/gateway/degraded_state.py:
- OwnerUnavailable exception carrying only DegradedOwner's redacted fields
- DegradedCapabilityRegistry.find() point read
- DegradedCapabilityRegistry.assert_owner_available() guard
- module-level assert_owner_available() no-op-safe for an optional registry
Exports both from praisonaiagents.gateway and covers with unit tests.
Co-authored-by: Mervin Praison <[email protected]>
Blanket auto_approve_shell now degrades to explicit approval when the
gateway binds to a non-loopback interface or the channel is a
multi-user/group surface, mirroring the auth token's assert_external_bind_safe
posture. Operators can opt back into blanket auto-approve with
auto_approve_shell_acknowledge_exposed: true.
Co-authored-by: Mervin Praison <[email protected]>
Address reviewer findings on PR #3638:
- Loop detection & loop guard now observe the FULL tool result; the compact
model-facing view is swapped in only right before return, so a stable
compact summary no longer masks progressing polls as no-progress loops.
- The compact override now passes through wrap_if_external, so external/
untrusted model_output cannot bypass the prompt-injection fence.
- Model-facing annotations (AFTER_TOOL additional_context, loop-guard notices)
are re-applied to the compact view so they always reach the model.
- Unified the to_model_output hook contract (receives the output value in both
safe_run and the executor) and guarded it in safe_run so a failing builder
degrades to full output instead of corrupting a successful result.
- Corrected resolve_model_output docstring to match implementation.
Co-authored-by: Mervin Praison <[email protected]>
Address reviewer findings on PR #3637:
- save_session_state now returns the SessionStore bool result so a silent
False (serialisation/disk failure) no longer reports success to callers.
- Tests use pytest tmp_path (no leaked temp dirs) and verify cross-instance
durability via a separate DefaultSessionStore over the same directory.
Co-authored-by: Mervin Praison <[email protected]>
Add an optional, backward-compatible way for tools to feed the LLM a
compact summary while keeping the full result for display/hooks/tracing:
- ToolResult(model_output=...) compact view + resolve_model_output helper
- BaseTool.to_model_output(result) override, wired through safe_run
- @tool(to_model_output=fn) on the decorator / FunctionTool
- tool_execution.py resolves the compact view and swaps it in for the
model only after tracing + AFTER_TOOL hooks saw the full payload
No override => unchanged behaviour (model sees full output).
Co-authored-by: MervinPraison <[email protected]>
Route AgentTeam.save_session_state/restore_session_state through the
durable, project-scoped SessionStore (the same store single-Agent
--continue uses), keyed deterministically by session_id via
update_session_metadata/get_session. This removes the fuzzy
search_short_term(limit=10) lookup and the memory-gating: multi-agent
runs now resume deterministically even with memory=False.
shared_memory is demoted to optional enrichment, and the legacy
semantic lookup is kept only as a fallback for pre-existing sessions,
preserving full backward compatibility. No new params or exports.
Co-authored-by: MervinPraison <[email protected]>
- _resolve_framework gains require_workflow: WorkflowAutoGenerator now
rejects an installed-but-non-workflow default (e.g. when native praisonai
is absent) instead of emitting a workflow YAML AgentsGenerator would later
reject (Greptile/CodeRabbit P1).
- PushClient.supports_publish now also requires an active connection, closing
the disconnected/pre-connect false-positive that let gated producer calls
proceed and fail with ConnectionError (Greptile P1).
- Tests: _fake_registry sets SUPPORTS_WORKFLOW; framework-resolution tests now
assert exact create()/pick_default() interactions (CodeRabbit).
Co-authored-by: Mervin Praison <[email protected]>
- agents_generator: let FileNotFoundError bubble from _load_config and drop
the `if config is None: return` guards so run/arun/serve raise instead of
returning a silent None for a missing agent file.
- auto: add BaseAutoGenerator._resolve_framework and route both AutoGenerator
and WorkflowAutoGenerator through registry.pick_default() with adapter
validation, so defaults and validation are a single source of truth.
- push: PollingTransport.send now raises NotImplementedError for unmapped
message types (publish/create/presence) instead of silently dropping them;
PushClient logs the capability loss on fallback and exposes supports_publish.
Co-authored-by: MervinPraison <[email protected]>
- read-only policy preset now denies real dangerous tool names
(tool:write_*/delete_* + *_write*/*_delete* globs) instead of
patterns that never match the SDK's own tools
- LLMGuardrail._llm_validate recognizes the SDK's LLM.get_response
interface, so string/LLM-instance guardrails validate instead of
silently failing closed on every call
- iter_stream warns when an output guardrail is attached, since
token-level streaming cannot retroactively validate output
Co-authored-by: MervinPraison <[email protected]>
Strengthen test_generate_dockerfile_includes_gunicorn_timeout per reviewer
feedback (Greptile/CodeRabbit): bare "--timeout" substring also matched the
HEALTHCHECK --timeout=10s option, so a malformed CMD could pass. Now assert
the exact option-value pairs in the generated Gunicorn command.
Co-authored-by: Mervin Praison <[email protected]>
Agent LLM workloads (cold import + first model round-trip) routinely
exceed Gunicorn's 30s default worker timeout, causing the worker to be
SIGKILL'd mid-request on the first /chat call. Add explicit --timeout 120
and --graceful-timeout 30 to the generated CMD.
Co-authored-by: Dhivya-Bharathy <[email protected]>
Collapsing the release to a single commit (#3572) removed the per-package
"Bump praisonai-mcp to 0.0.12" commits. On a full release that is fine --
the wrapper's "Release v<x.y.z>" commit describes the whole batch. But a
single-package release (every other skip_* set, including skip_wrapper)
never reaches the wrapper, so its bump lands via the safety-net step and
was labelled with the generic "persist version bumps".
Derive the package list from the staged paths so that case reads
"chore(release): bump praisonai-mcp [skip ci]" instead. Falls back to the
generic message when nothing under src/ is staged.
Verified the extraction against a scratch repo: single package, multiple
packages, and the no-src fallback.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Address reviewer feedback on the memoisation:
- Replace unbounded functools.lru_cache with a WeakKeyDictionary so cached
bound methods no longer keep their owning Agent alive (memory leak in
long-lived processes creating many short-lived agents).
- Fall back to direct signature inspection for unhashable/unweakreferenceable
callables (e.g. objects with __hash__ = None) instead of raising TypeError,
preserving correct 3-arg tool dispatch.
- Drop now-unused functools import.
Co-authored-by: Mervin Praison <[email protected]>
Cache the inspect.signature() on_progress-kwarg probe on the callable so it
runs once per dispatcher callable instead of once per tool call. execute_tool_fn
is invariant per agent, so the memoised result is identical. The
(TypeError, ValueError) fallback for non-introspectable built-in/C callables is
preserved. No behaviour or API change.
Co-authored-by: MervinPraison <[email protected]>
Addresses the three P1 reviewer findings on PR #3624:
- telegram.py: streaming branch now calls _maybe_send_voice_reply after
finalize, so voice.mode always/match_inbound is honoured when streaming
is enabled (previously text-only).
- gateway/server.py: the Telegram handler serving VOICE|AUDIO now threads
inbound_was_voice into _send_response_with_media, so match_inbound fires
for gateway-owned channels.
- tools/audio.py + bots/_tts.py: forward configured voice.speed through
tts_tool -> AudioAgent.speech (previously dropped).
- tests: update fake tts_tool signature and add speed-forwarding regression.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Adds a first-class, opt-in outbound voice-reply path mirroring the existing
inbound `stt` setting. New `bots/_tts.py` provides TtsConfig,
resolve_tts_config, should_voice_reply and synthesize_voice_reply (reusing
tools.audio.tts_tool so heavy TTS deps stay in tools). A TtsConfigSchema +
`voice` channel field give tri-surface (YAML/metadata) parity with `stt`,
carried through config.metadata by the gateway. Telegram wired as the
reference consumer: replies are spoken per the off/always/match_inbound mode,
degrading cleanly to the already-sent text on failure.
Co-authored-by: Mervin Praison <[email protected]>
Address the three Greptile P1 findings on PR #3622:
- Channel system_prompt_hint now reaches the model: inject into
backstory + rebuild system_prompt (the consumed prompt fields) instead
of the construction-only `instructions` attribute, which the runtime
prompt builder never re-reads. Idempotent and cache-stable.
- empty_final override is now reachable via the existing BotConfig.metadata
seam (no new typed knob); direct attribute still honoured for callers.
- Inbound crash-replay docstring/log corrected to state its real effect
(unblock stranded claimed rows so redelivery / session-resume can
reprocess) rather than over-claiming standalone re-drive, which is
already owned by _resume_interrupted_turns (#3379).
Co-authored-by: Mervin Praison <[email protected]>
Gap 1 — visible-outcome guarantee for empty finals: add a dependency-free
core classifier praisonaiagents.bots.silence.classify_final() that separates
deliberate silence from a blank/whitespace/[tool_calls: …] final, and resolve
"empty, not silence" once at the shared fire_message_sending funnel with a
recorded, typed fallback (operator log; optional empty_final_message config).
Every adapter (Slack/Telegram/etc.) now delivers a visible outcome instead of
silently dropping, DLQ-parking an empty send, or leaking a machine placeholder.
Gap 2 — wire the dead system_prompt_hint seam: inject a channel's declared
system_prompt_hint into the per-channel cloned agent's instructions via the
already-existing get_channel_system_prompt_hint() helper (the missing caller),
bounded and prompt-cache-stable. No-op for built-ins; third-party channels can
now teach the agent their constraints as the ChannelDescriptor contract states.
Gap 3 — invoke un-wired inbound crash-replay: call InboundJournal.replay() at
channel start-up (and hot-reload) so an inbound stranded 'claimed' by a crash
is re-driven exactly-once on the default-durable path, honouring the module's
own durability contract. Replayed counts are logged for operator visibility.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
- Fix NameError regression: _run_custom_agent referenced an undefined
`instructions` var (broke test-core cli suite). Add the param and thread
merged_instructions from the caller so the --agent path injects declared
instruction sources into the backstory.
- Forward merged_instructions on the --command path and skip the warm-runtime
attach when instructions are present (per-invocation context can't cross the
runtime process boundary), so declared instructions are no longer dropped.
- SSRF guard for remote instruction URLs: reject private/loopback/link-local/
reserved destinations and re-validate redirects, matching the existing
managed-config resolver policy. Opt-out via PRAISONAI_INSTRUCTIONS_ALLOW_LOCAL_URLS.
- Add regression tests for custom-agent instruction injection and the SSRF guard.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
PraisonAI.main() replaces args via parse_args() and previously carried
over only session fields, silently dropping the approval/permission
settings that the YAML run path threads onto praison.args. YAML workflows
launched with --approval/--approve-all-tools/--approval-timeout or
--allow/--deny (which derive a console backend) therefore bypassed the
approval gate. Preserve these fields unconditionally across the reparse,
independently of session flags (--no-save sets approval but not
cli_project_sessions). Adds regression tests exercising the real main()
preservation boundary.
Co-authored-by: Mervin Praison <[email protected]>
Adds a wrapper-level `instructions` config key and repeatable
`run --instructions <path|glob|url>` flag so teams can declare extra
instruction/context sources (files, globs, ~ paths, http(s):// URLs)
loaded alongside the convention-only AGENTS.md/CLAUDE.md auto-load.
- context_files: resolve_instruction_sources() expands globs/~, reads
local files, and lazily fetches remote URLs (stdlib urllib, size-bounded,
best-effort with warnings) — no new heavy deps.
- run.py: resolve config `instructions` (layer-concat via the existing
ConfigResolver list-merge), merge repeatable --instructions on top, and
inject up front into the agent backstory via the existing subtree-context
hook (passed as already_loaded to dedup nested files).
- schema: add `instructions` to config_hierarchy CONFIG_SCHEMA and the
resolver's KNOWN_TOP_LEVEL_KEYS (so it validates and is not warned).
Wrapper-only; no core changes, no new Agent params.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: MervinPraison <[email protected]>
Thread the existing --approval/--approve-all-tools/--approval-timeout and --allow/--deny/--permissions rules from praisonai run workflow.yaml into the YAML engine args so YAML agents are permission-gated exactly like single-agent run. Session continuity and structured --output already flow through _run_from_file; no new engine wiring or core changes are added.
Co-authored-by: MervinPraison <[email protected]>
The write tools resolved the symlink only inside is_protected() but then
open()'d the original path, so (a) an in-workspace symlink to an out-of-
workspace file bypassed the workspace-confinement check and (b) a symlink
retargeted between check and write could redirect an approved edit into a
protected file. Add security.resolve_real_path() and resolve abs_path once
in write_file/append/apply_diff/search_replace so the protection check,
workspace-confinement check and the actual read/write all act on the same
real target. New files are unaffected (realpath returns the path unchanged).
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
1. Call/agent-invoke server auth: constant-time token compare via
hmac.compare_digest; media-stream no longer carries the shared server
token in the URL (mints a one-shot, TTL-bound session token instead);
guard active_connections/client_ips mutations with asyncio locks to
close the async TOCTOU on the rate/connection limits.
2. Protected-path guard: resolve symlinks in is_protected /
get_protection_reason so a same-directory symlink to .env is no longer
treated as harmless (bypass fix; centralised so all writers inherit it).
3. run_python: pass code as an argv list to subprocess.run instead of
building a shell-quoted string re-tokenised by shlex, preserving the
caller's exact source (newlines/backslashes/quotes) on POSIX and Windows.
Co-authored-by: MervinPraison <[email protected]>
Cloud providers shell out to external CLIs and never generate the API
server, so the parsed deploy.api config had no live consumer and was
silently ignored. Remove it to avoid misleading config (per reviewer
feedback from CodeRabbit/Greptile). Docker path already honors the
sibling api block; add runtime tests asserting PRAISONAI_API_AUTH is
propagated when auth_enabled: false and omitted otherwise.
Co-authored-by: Mervin Praison <[email protected]>
Docker deploy ignored the optional sibling `deploy.api` block, so
`auth_enabled: false` was silently dropped and the generated server
defaulted auth on, returning 401 on /chat.
- schema.py: parse optional `deploy.api` for type docker and cloud
- main.py: pass PRAISONAI_API_AUTH=disabled to container when disabled
- add unit test + update example agents-docker.yaml
Co-authored-by: Dhivya-Bharathy <[email protected]>
The @require_approval decorator now keys approvals on the tool's effective
arguments, so a bare mark_approved(name) no longer unlocks arbitrary-value
positional calls (the sticky-cache bypass this PR closes). Update the test to
mark/check with the same args the calls use, preserving the mark->call intent
without weakening the security guarantee.
Co-authored-by: Mervin Praison <[email protected]>
The require_approval decorator only keyed approvals on kwargs, so
directly-invoked decorated tools called positionally (read_file("/a"))
all collapsed to the same empty-argument key — one approval unlocked any
later positional value. Bind positional + keyword args into a normalized
dict via the function signature so the approval key reflects the actual
call. Falls back to an __args__ tuple for C-callables without a bindable
signature. Adds regression tests.
Co-authored-by: Mervin Praison <[email protected]>
- approval: thread `arguments` through mark_approved/is_already_approved,
the require_approval decorator wrappers, and the Agent tool path so a
single approval no longer permanently unlocks a tool for any later
attacker-chosen arguments (safe-by-default).
- agent memory: stop defaulting to the shared constant "praison"/"default";
when memory is enabled without an explicit user_id, generate a per-instance
non-shared id and warn, preventing silent cross-session memory merges.
Co-authored-by: MervinPraison <[email protected]>
- _kill_pid now returns result.returncode == 0 on Windows and catches OSError
- _destroy_api returns success=False with failed PIDs when any kill fails
- tests: mock zero returncode, add nonzero-taskkill and partial-kill cases
Co-authored-by: Mervin Praison <[email protected]>
Add regression coverage for the separate _configure_stdio() helper in
__main__.main(), asserting utf-8 + errors="replace" are applied before app
dispatch, plus a no-op safety case. Also assert errors=="replace" in the
existing deploy._configure_stdio test.
Co-authored-by: Mervin Praison <[email protected]>
Replace Unix-only lsof in _destroy_api() with cross-platform port
discovery (netstat -ano on Windows, lsof on Unix) and cross-platform
process termination (taskkill on Windows, SIGTERM on Unix). Prevents
orphaned Flask API servers on Windows after destroy.
Co-authored-by: Dhivya-Bharathy <[email protected]>
Windows default consoles use cp1252, which cannot encode the emoji banner
prefixes emitted by the deploy CLI, causing UnicodeEncodeError on every
command. Reuse the established _configure_stdio() pattern from
praisonai-browser to reconfigure stdout/stderr to UTF-8 (errors=replace)
at both the praisonai-deploy console entry and the praisonai deploy bridge
entry (handle_deploy_command).
Co-authored-by: Dhivya-Bharathy <[email protected]>
Replace NamedTemporaryFile + os.unlink pattern with pytest tmp_path fixture
to avoid PermissionError [WinError 32] on Windows where the file handle
cannot be deleted while still open inside the context manager.
Co-authored-by: Dhivya-Bharathy <[email protected]>
The generated Flask API server was spawned with a bare 'python' which
resolves to a different interpreter than the parent venv on Windows and
multi-Python setups, causing ModuleNotFoundError: No module named 'flask'.
Spawn with sys.executable and preserve the parent environment so the child
inherits Flask and OPENAI_API_KEY for /chat.
Co-authored-by: Dhivya-Bharathy <[email protected]>
Extract the triplicated "build a ToolResolver, bucket its
list_available_sources(), then fall back to a TOOL_MAPPINGS +
praisonai_tools scan" helper into one internal module
templates/_tool_sources.py. tools.py, tools_doctor.py and
dependency_checker.py now call the shared helper; per-module
presentation stays local so output is byte-identical.
Co-authored-by: MervinPraison <[email protected]>
Add a pure next_fire_time(cron_expr, base) helper in
praisonaiagents.scheduler.due as the single owner of the "compute next
cron fire from a base" step. Core is_due and the wrapper's
ScheduleTicker.is_due now both call it, removing the duplicated
croniter().get_next(float) logic from the wrapper. No behaviour or API
change; croniter-missing graceful degradation preserved.
Co-authored-by: MervinPraison <[email protected]>
Address final-review findings on the durable-write salvage path:
- spill filenames add a random token so consecutive same-ms/PID
failures no longer overwrite each other (no lost turns)
- _reingest_spill runs _enforce_window before persisting so recovered
turns respect the retention policy like any ordinary write
- guard spill payload shape (non-object root / non-list messages /
non-object message) so a malformed spill can't block recovery
Co-authored-by: Mervin Praison <[email protected]>
When a durable session write fails (disk-full / SQLite-FTS corruption /
permission OSError) the store previously collapsed it to a silent False that
no caller reads, so the already-produced turn lived only in the in-memory
cache and was permanently lost on the next shutdown/crash — with no operator
signal.
This adds a safe-by-default, stdlib-only salvage path in the core session
store that triggers only on the failure path (no hot-path regression):
- New SESSION_PERSIST_FAILED lifecycle hook + SessionPersistFailedInput so a
failed durable write is observable (metrics/alerting/forensics), mirroring
the outbound MESSAGE_UNDELIVERED posture.
- On write failure, spill the unpersisted turn to an atomic fallback file
(~/.praisonai/state/session_spill/*.json, 0600, temp-file + os.replace +
best-effort dir fsync) instead of holding it only in memory.
- On session load, re-ingest any spilled turns (dedup on role+content+
timestamp), persist them back, and delete each spill file only after a
successful re-insert.
No new Agent params, no new dependencies, no behaviour change on the happy
path. Adds 6 unit tests.
Co-authored-by: MervinPraison <[email protected]>
Flipping SessionConfig.persist to True (durable-by-default) exposed two
latent bugs that the prior off-by-default masked:
1. CLI opt-out ignored: the multi-bot CLI builds WebSocketGateway with a
default session config, so __init__ selected a persistent store before
start_with_config loaded the YAML — and that loader never read the
session: block. A documented session.persist: false was silently ignored.
Fix: start_with_config now re-reads the session: block and re-selects the
store (unless an explicit store was passed to the constructor).
2. Startup crash on unwritable home: SqliteTranscriptStore/DefaultSessionStore
eagerly makedirs(~/.praisonai/sessions); on a read-only/absent home both
the primary store and its fallback raised, escaping __init__ and crashing
the gateway. Fix: the store selection now degrades to in-memory sessions
instead of aborting startup.
Store-selection logic extracted into a shared _build_session_store helper so
__init__ and start_with_config pick identically. Adds regression tests for
the opt-out, the explicit-store precedence, and from_dict persist defaults.
Co-authored-by: Mervin Praison <[email protected]>
fallback_text() unconditionally imported table_to_markdown/chart_to_text
and referenced BlockType.TABLE/CHART, which raised ImportError/AttributeError
on praisonaiagents releases predating those symbols (bot pins >=1.6.152) —
breaking fallback delivery even for text-only presentations.
- Import the two new helpers defensively with inline fallbacks
- Dispatch table/chart blocks via string block-type values (getattr-guarded)
Co-authored-by: Mervin Praison <[email protected]>
Add TABLE and CHART members to the portable presentation vocabulary so
agents can describe tabular and chart data once and have each channel
render it natively where supported or degrade deterministically to a
markdown table / compact text summary elsewhere.
- BlockType.TABLE / BlockType.CHART + PresentationBlock.make_table/make_chart
- columns/rows/chart_kind/series fields with dict round-trip
- PresentationLimits: supports_tables/supports_charts + max_table_rows/cols
- adapt_presentation clamps and degrades table/chart per capability flags
- table_to_markdown/chart_to_text helpers (exported) + fallback_text branch
Co-authored-by: MervinPraison <[email protected]>
Flip SessionConfig.persist from False to True so an out-of-box gateway
remembers conversations across restarts via the existing SQLite
transcript store. Updates the two YAML-parse fallbacks to match. Users
who want ephemeral sessions can still opt out with session.persist: false.
Co-authored-by: MervinPraison <[email protected]>
The previous approach replaced the bash:<command> approval target with a
shell:external-path:<path> target for out-of-workspace commands. This both
broke command-specific deny rules (a hard `deny: bash:rm *` no longer matched,
regressing DENY -> ASK and letting a user approve a denied command) and
collided with the existing `shell:` shell-prefix namespace in
PermissionManager.check().
The out-of-workspace boundary is already fully implemented in
PermissionManager (`_check_shell_command` + `_external_dir_target`): with a
workspace_root configured, a broad `bash:*` allow escalates external paths to
ASK while a command-specific deny still fires. build_permission_target now
keeps the verbatim `bash:<command>` target so that machinery applies and
command identity is preserved.
- approval/utils.py: drop the redundant shell:external-path namespace and the
_shell_external_paths helper; shell tools map back to bash:<command>.
- tests: replace target-mangling assertions with boundary-enforcement tests
that verify (a) broad bash:* does not cover external paths, (b) in-workspace
stays allowed, (c) command-specific deny still fires on external paths, and
(d) backward-compat with no workspace_root.
Fixes the deny-bypass flagged by Greptile and CodeRabbit.
Co-authored-by: Mervin Praison <[email protected]>
- share: atomic temp-file write + os.replace so a failed/interrupted
write never truncates a previously published transcript
- share/unshare: guard OSError (unwritable/full data home) as clean
command errors with chained context instead of raw tracebacks
- unshare: unlink unconditionally, treat FileNotFoundError as an
idempotent no-op (fixes concurrent-deletion race + ruff B904)
- soften overstated 'always redacts secrets' copy to accurate
best-effort wording (redactor #3426 is high-signal/best-effort)
- test: isolate test_share_path_is_stable_per_session via project fixture
Co-authored-by: Mervin Praison <[email protected]>
Adds `praisonai session share <id>` / `unshare <id>` to the CLI. `share`
reuses the existing session resolver + transcript redactor to publish a
single self-contained HTML transcript to ~/.praisonai/shares and returns a
file:// link; `unshare` revokes it. Zero external infrastructure or new
dependencies; sharing is opt-in and always redacts secrets first.
Co-authored-by: MervinPraison <[email protected]>
Make build_permission_target emit a distinct shell:external-path:<path>
target when a shell command touches a path outside the workspace root,
so a broad bash:*/"allow shell"/session grant cannot silently authorise
out-of-workspace access. Reuses the existing command_parser and
path_safety.resolve_within_root primitives (no new modules/params).
Default-on and fail-closed, with a PRAISONAI_SHELL_WORKSPACE_BOUNDARY
opt-out for trusted sandboxed/CI runs.
Co-authored-by: MervinPraison <[email protected]>
_TimeoutBoundTool was a plain proxy that did not subclass the wrapped tool's
class, so isinstance(proxy, BaseTool) returned False. Downstream executors
(praisonaiagents tool_execution, CrewAI/LangChain) route on that isinstance
check to call .run; the proxy failed it and, being non-callable, also skipped
the generic callable branch -> a BaseTool plugin tool with tool_timeout set
silently executed nothing.
Build the proxy as an instance of a dynamic subclass of type(inner) so
isinstance keeps passing (verified for praisonaiagents BaseTool and pydantic
CrewAI/LangChain-style tools) while still never mutating the shared inner
object and still routing _run/run through the per-generator timeout wrapper.
Added regression tests for isinstance/schema preservation and cross-generator
executor isolation.
Co-authored-by: Mervin Praison <[email protected]>
Gap 1: create_unified_app now enforces the api_key via the shared
_api_auth middleware (previously accepted but never referenced), and
serve unified refuses to bind a non-localhost host without an API key,
mirroring serve agents.
Gap 2: tool timeout wrapping no longer mutates shared framework tool
objects in place; each generator installs its own _TimeoutBoundTool
proxy that delegates schema attributes but routes _run/run through its
own executor. Owner identity is a stable per-generator uuid compared by
value, so the idempotency guard actually matches.
Gap 3: resume_or_create_session accepts a create_session dispatcher; the
orchestrator routes it through _sync so async conversation stores have
their create-session coroutine awaited instead of silently dropped.
Co-authored-by: MervinPraison <[email protected]>
Replace the fixed .tmp.<pid> temp filename with tempfile.mkstemp so
concurrent writers in the same process (multiple threads or FileMemory
instances writing the same file) cannot clobber each other's temp file,
where the first os.replace would remove the temp the sibling still needs.
Matches the atomic-write convention used elsewhere in the SDK
(storage/base.py, session/store.py). Addresses Greptile P1.
Co-authored-by: Mervin Praison <[email protected]>
- agents.py: add _gather_with_isolation so a failing async task no longer
orphans its siblings; siblings are awaited to completion and the first
exception is re-raised (return_exceptions=True) across all 3 gather sites.
- handoff.py: guard finally:_pop_handoff() with a `pushed` flag at all 5
call sites so a _check_safety rejection (which raises before _push_handoff)
no longer pops an ancestor's entry and corrupts the cycle/depth guard.
- file_memory.py: write JSON to a temp file + fsync + os.replace so a crash
mid-write can no longer truncate the persisted memory store.
Co-authored-by: MervinPraison <[email protected]>
Delete create_autogen_tool_function() and the 17 generated autogen_<Tool>
symbols plus their __all__ from inbuilt_tools/autogen_tools.py. Their only
consumer, ToolRegistry.register_builtin_autogen_adapters(), was removed in
the #1590 fix; the canonical AutoGen path is framework_adapters/autogen_adapter.py.
Keeps the praisonai_tools availability probe that feeds PRAISONAI_TOOLS_AVAILABLE
and the release `import *` smoke test.
Co-authored-by: Mervin Praison <[email protected]>
Address the three P1 findings on the declarative webhook channel:
- Gateway wiring: add a `webhook` branch to WebSocketGateway._create_bot and
recognize WebhookBot in the supervisor's own-aiohttp-server start branch, so a
`type: webhook` YAML channel actually constructs and starts (was silently
skipped by the hardcoded adapter switch). Guard _inject_routing_handler for
ingress channels without an on_message hook.
- Fail-loud dispatch: the HTTP handler now returns 500 when agent dispatch
raises, so providers retry instead of receiving a false 200 ack.
- Durable ingress id: fall back to a deterministic sha256(path + raw_body) when
no delivery header is present, keeping ingress journaling/dedup active for
generic senders (an empty message_id disabled both).
Adds tests for 500-on-failure, delivery-header and body-hash message ids, and
gateway construction of the webhook adapter.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Add a first-class `webhook` gateway channel that turns any HTTP event into an
agent trigger through configuration alone — no bespoke adapter code.
- core (praisonaiagents.bots): a small, import-light declarative filter
(WebhookFilter + evaluate_webhook_filter/resolve_field) with all/any/not
combinators and exists/equals/contains/in/regex leaf operators. Pure logic,
no HTTP, fail-safe on malformed input.
- wrapper (praisonai-bot): WebhookBot HTTP-ingress adapter + WebhookRoute,
reusing existing HmacWebhookVerifier / enforce_webhook_verification, the
aiohttp server pattern, and BotSessionManager (durable dedup ingress). Adds
prompt templating ({{ dotted.path }}) and a silent (ack-only) route.
- register `webhook` as a built-in loader in the channel registry.
Reuses existing primitives and ChannelRouteConfig.metadata; no core config
schema change or new Agent params.
Co-authored-by: MervinPraison <[email protected]>
Route WebSocketGateway._create_bot through the shared platform registry
(resolve_adapter) instead of a hardcoded if/elif over the seven built-ins.
Any channel the registry resolves — built-in, register_platform(), or a
praisonai.channels entry point — is now instantiated and started, with
ch_cfg passed through generically (mirroring probe_channels). An
unresolvable or unconstructable platform is recorded as a degraded channel
(visible in health/doctor) rather than a silent skip. Per-platform token
env-var fallbacks (email/AgentMail/Linear) are preserved.
Co-authored-by: MervinPraison <[email protected]>
- agent_invoke: _apply_agent_config now rejects overrides on non-isolatable
(shared registry) agents instead of mutating a shared object, preventing
config from leaking across concurrent/subsequent requests. Drop the
never-settable `temperature` key from the whitelist so the surface is honest.
- vector_stores: warn (once per collection) when an existing/legacy Chroma
collection uses a non-cosine distance metric, surfacing incomparable scores
without a destructive auto-migration of stored vectors.
Co-authored-by: Mervin Praison <[email protected]>
- ChromaVectorStore: centralise namespace->collection resolution so ad-hoc
namespaces keep the cosine metric; return the stored embedding (not the
query vector) from query(); scope delete_all to the caller's namespace.
- agent_invoke: honour agent_config overrides against the isolated clone
via a whitelist, rejecting unknown/unsettable keys with 400 (route) or a
clean error dict (standalone) instead of silently ignoring them.
- a2u_server.publish_sync: use get_running_loop, track the scheduled task
(WeakSet) so it can't be GC'd and surface its exceptions; expose
last_publish_task() for the real delivered count.
- push/client + acp/server: replace deprecated asyncio.get_event_loop()
with get_running_loop()/to_thread inside coroutines.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Both create-github-app-token steps omitted `repositories:`, so the run log
read "creating token for all repositories for given owner MervinPraison" --
the token carried write access to every repo under the account while the
job only ever touches PraisonAI.
Verified single-repo before narrowing: the workflow makes no cross-repo
call, and bump_and_release.py's only gh invocation is `gh release create`
against this repo, with all git operations on origin.
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
- failover.py: snapshot next_profile + callbacks under the RLock, then
invoke callbacks after releasing it. User callbacks may block or take
external locks; running them under the shared credential-pool lock could
stall every concurrent agent and risk lock-ordering deadlocks (Greptile).
- chat_mixin.py: _run_id -> _current_run_id at the second tool-output
truncation call site the PR missed; previously passed None into
get_tool_output_store, defeating the run isolation Gap 3 restores.
Co-authored-by: Mervin Praison <[email protected]>
- LLMGuardrail.__call__ now fails closed on ambiguous LLM replies, matching
_llm_validate() and the class's documented fail-closed contract.
- FailoverManager gains a threading.RLock guarding all _profiles reads/mutations
and AuthProfile status transitions, since it is a shared credential pool by design.
- Fix _run_id -> _current_run_id typo that silently disabled tool-output
run-scoped isolation; harden get_tool_output_store so a None run_id no longer
adopts the first run's process-wide store.
- Add regression tests asserting both guardrail entry points fail closed.
Co-authored-by: MervinPraison <[email protected]>
- docker-compose: require POSTGRES_PASSWORD (no known fallback) and bind
Postgres to loopback by default (POSTGRES_BIND) — resolves GitGuardian
finding and the default-credentials exposure P1.
- railway starter: ship a Dockerfile so railway.json's DOCKERFILE build
and start command reference real files (fixes missing-file P1).
Co-authored-by: Mervin Praison <[email protected]>
A full pypi-release run landed 9 separate commits and 9 pushes on main --
one per package -- all authored as MervinPraison.
Collapse to one commit: delete the 8 per-package "Commit <pkg> version
bump" steps. They were redundant, since the wrapper step already calls
bump_and_release.py --no-add-all whose release_files list is a superset
of every file those steps staged, so all bumps now land in the script's
single "Release v<x.y.z>" commit. That needs --force, because the tree is
now dirty when the script runs and its pre-flight guard exits 1 under
--no-add-all; --no-add-all still restricts staging to the explicit list.
A trailing "Persist any uncommitted version bumps" step covers what the
single commit cannot: a package failing midway (those versions are
already live on PyPI, so the bumps must not be lost), skip_wrapper, or a
wrapper failure. It is a no-op on a clean run, and uses `git add -u` so
untracked build output stays out.
Attribute the release to praisonai-triage-agent[bot] by minting an
installation token from CLAUDE_APP_ID/CLAUDE_APP_PRIVATE_KEY -- the app
already behind that bot in claude.yml, claude-merge-gate.yml and
pipeline-status-sync.yml. GH_TOKEN is exported via $GITHUB_ENV, so the
commit, the tag push and gh release create are all the bot's;
secrets.GH_TOKEN is no longer referenced.
Two details this depends on: app tokens expire after 1h and this job can
exceed that (9 packages x up to a 600s PyPI wait each), so the token is
re-minted immediately before the wrapper release. And checkout sets
persist-credentials: false -- otherwise its http.extraheader would
outrank the remote URL and pin the first, expiring token.
Requires the App to be able to push to main (contents: write, plus a
ruleset bypass entry if main requires PRs).
Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Add the same overlap-guard assertion used in eval/tokens.py so RAG-specific
extras can never silently shadow canonical MODEL_LIMITS entries and re-introduce
the drift that #3567 fixed.
Co-authored-by: Mervin Praison <[email protected]>
Deduplicate the canonical tool-argument identity scheme
(json.dumps(sort_keys=True, default=str) -> sha256[:16]) that was
independently re-implemented in the approval registry and doom-loop
detector. Both safety subsystems now delegate to a single
hash_tool_args() helper in approval/utils.py, removing the drift risk
between approval de-duplication and doom-loop detection. Behaviour is
byte-for-byte identical (verified against the original scheme).
Co-authored-by: MervinPraison <[email protected]>
Guard the BEFORE_LLM and AFTER_LLM payload construction with the existing
registry.has_hooks() primitive, matching the idiom already used at the
AFTER_TOOL/BEFORE_TOOL/AFTER_AGENT/BEFORE_AGENT sites. Also skip the
str(result) stringification when the trace emitter is a disabled NoOp by
guarding on _trace_emitter.enabled. Behaviour is identical whenever a hook
or emitter is registered; zero cost on the hot path otherwise.
Co-authored-by: MervinPraison <[email protected]>
Deduplicate the model->context-window data by sourcing exact values from
context/budgeter.MODEL_LIMITS (the canonical table) and layering only
RAG-specific extras underneath, mirroring eval/tokens.py. This removes the
drift where gpt-4.1/gemini-1.5-pro resolved to different windows in RAG vs
the rest of the SDK. The get_model_context_window wrapper (None guard,
normalisation, prefix/heuristic fallbacks) is unchanged.
Co-authored-by: MervinPraison <[email protected]>
Extract a single _iter_argv_tokens classifier as the one source of truth for
flag/value-consumption semantics. _find_first_command, _flag_names and
_build_run_argv now all consume it, so routing and rewrite can no longer
diverge. _find_first_command accepts the shared value_opts (defaulting to the
historical narrow static set) rather than a separate hardcoded VALUE_FLAGS.
Behaviour-preserving internal DRY refactor; no CLI surface change.
Co-authored-by: MervinPraison <[email protected]>
CLI (cli/features/deploy.py):
- extract compose up|down action before generic parse so `compose up`
without --file no longer sets file="up"
- drop duplicate `-r` key (F601) so --region short flag works again
- route `doctor --provider fly|railway|render` via provider registry
- wrap the four new handlers in the class try/except convention
- thread --force into create scaffolding
compose.py:
- _ensure_postgres_password now resolves the *effective* (last) value,
handling quoted-empty and inline-comment cases
- restrict generated project .env to 0600 on POSIX
- report the effective host API port (runtime env → .env → default)
- add 600s timeouts to docker compose up/down
helm.py: add 600s timeout to helm upgrade
starters.py: refuse to overwrite existing files unless force=True
Helm agents-api deployment.yaml:
- pass agents/port/serverFile via env vars (no Python-source injection)
- include POSTGRES_PASSWORD in DATABASE_URL via k8s $(VAR) interpolation
starters: railway.json/render.yaml use the prebuilt GHCR image instead of
a nonexistent Dockerfile/api_server.py; fix compose+helm README manifest links.
Adds regression tests (160 passed).
Co-authored-by: Mervin Praison <[email protected]>
Split the "POSTGRES_PASSWORD:-praisonai" and "change-me" string literals in
the compose security regression tests so GitGuardian no longer flags them as
hardcoded secrets. The assertions still guard the exact same behaviour (no
default password baked into compose; generated password differs from the old
placeholder). Also replace the static "change-me" placeholder in the
agents-api Helm README with an openssl-generated example.
Co-authored-by: Mervin Praison <[email protected]>
- docker-compose.yml: drop `:-praisonai` default password (GitGuardian);
require POSTGRES_PASSWORD via `:?` and bind Postgres to 127.0.0.1 by default
- .env.example: ship empty POSTGRES_PASSWORD (no repo-known credential) + POSTGRES_BIND
- compose.py: auto-generate a strong POSTGRES_PASSWORD into project .env when empty
- README + tests: document security defaults and guard against regressions
Co-authored-by: Mervin Praison <[email protected]>
TRUNCATE is the default compaction strategy but did not preserve
tool_calls/result pairs: the recent-window slice could orphan a tool
result, and the token-budget pop loop could drop an assistant
tool_calls message while leaving its tool result behind. Snap the
recent boundary and drop leading tool pairs atomically so strict
providers never receive an orphaned tool message.
Co-authored-by: Mervin Praison <[email protected]>
When register(..., overwrite=True) replaces a tool under the same name,
evict the previous tool's availability cache and last-success timestamp so
a broken replacement can't be served as available on its first failing
probe via the inherited grace window.
Co-authored-by: Mervin Praison <[email protected]>
Compaction strategies chose their recent/older boundary purely by token or
message count, which could split an assistant tool_calls message from its
matching tool result. The resulting orphaned tool message made strict
providers (OpenAI/Anthropic/Azure) reject the transcript with a 400,
wedging long-lived gateway/bot sessions on every subsequent turn.
Add ContextCompactor._snap_to_pair_boundary() which moves a chosen boundary
outward so a tool pair is never separated, and apply it in _sliding_window,
_summarize, _prune, _llm_summarize and _llm_summarize_async. Behaviour-only,
backward compatible, no new knobs.
Co-authored-by: MervinPraison <[email protected]>
Track last-success timestamp per tool in ToolRegistry. On a probe
exception within a grace window of a recent success, serve the last-good
True and skip caching a durable negative, so a flaky availability check
no longer strips a healthy tool from a long-lived agent. Sustained
failures beyond the grace window still mark the tool unavailable.
Co-authored-by: MervinPraison <[email protected]>
The new TestAgentOSChatSessionIsolation tests replaced Agent.achat at the
class level (`type(template).achat = _fake_achat`) and never restored it,
so the stub leaked into test_async_gemini_fix.py where the real achat is
called with a `tools=` kwarg the stub did not accept.
Use pytest's monkeypatch fixture (auto-restore) and accept *args/**kwargs
in the stub so it matches the real achat signature.
Co-authored-by: Mervin Praison <[email protected]>
Addresses reviewer feedback on #3555:
- Greptile P1: _preflight_tools now loads ~/.praisonai/.env before resolving
so a local tools.py enabled via PRAISONAI_ALLOW_LOCAL_TOOLS in that file is
not falsely rejected in strict mode (mirrors GatewayHandler.start).
- CodeRabbit: describe_unresolved excludes the exact name from difflib typo
candidates so a mapped-but-unloadable tool yields an install/generic hint
instead of a useless "Did you mean '<same name>'?".
- Add regression tests for both.
Co-authored-by: Mervin Praison <[email protected]>
An explicit (non-${ENV}) weak gateway.auth_token in gateway.yaml wins over
GATEWAY_AUTH_TOKEN at both startup (GatewayConfig.auth_token) and doctor
re-validation, so the env-only repair left the weak YAML value active and
falsely reported success. The repair now also rewrites the YAML token in
place when it holds an explicit weak value, while preserving ${ENV}
references. Fixes Greptile P1 on #3556.
Co-authored-by: Mervin Praison <[email protected]>
The degraded registry's retry_hint advertised `praisonai gateway doctor --fix`,
but no such flag existed — a dead-end on the gateway's primary recovery path.
Add `--fix`/`--dry-run` to `gateway doctor` that mints a strong GATEWAY_AUTH_TOKEN
when weak/missing, persists it to ~/.praisonai/.env (same store as onboard), and
re-validates the finding cleared. Align the core retry_hint docstring so the
advertised command is guaranteed to exist.
Co-authored-by: MervinPraison <[email protected]>
Add a start-time tool pre-flight gate so a mistyped, uninstalled, or
gated tool named in gateway.yaml is surfaced with a per-name reason and
fix hint instead of being silently skipped. Strict by default (mirrors
the credential pre-flight); --no-strict-tools / strict_tools: false
preserve today's skip-and-continue.
- tool_resolver.py: add describe_unresolved() (difflib "did you mean" +
local-tools/dependency hints) and a module-level wrapper.
- gateway start: add --strict-tools/--no-strict-tools and a
_preflight_tools() gate reusing the existing validate_yaml_tools.
Co-authored-by: MervinPraison <[email protected]>
- cli/features/deploy.py: API & Cloud shortcut commands now honor deploy.api
and deploy.cloud YAML when CLI flags are unset (defaults changed to None
sentinels; explicit CLI still overrides). Fixes YAML being silently ignored.
- providers/azure.py: create->update fallback now builds a proper
`az containerapp update` command (previous `cmd[1]='update'` produced the
invalid `az update containerapp`); env vars passed under a single --env-vars
flag so later pairs no longer override earlier ones.
- scheduler/deployment.py: replace buggy nested DeployArgs (dead self-ref,
missing attrs) with SimpleNamespace carrying all fields handle_deploy reads;
derive success from SystemExit code instead of always True; interruptible
retry wait via _stop_event so stop() works; drop unused time import.
- main.py: replace `assert docker_cfg` with explicit ValueError (assert is
stripped under python -O).
- _wrapper_bridge.py: optional_wrapper_attr now returns default when attr is
missing, not just on ImportError.
- docker.py: prepare_docker_build_context validates agents file before writing
api_server.py; docker_container_name sanitizes invalid chars.
- tests: add regression tests for API and Cloud YAML merge precedence.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
- Route the optional subtree-context helper through praisonai_bot (canonical
home) with a praisonai wrapper-shim fallback, removing the module-/function-
level ``from praisonai`` import that tripped the C7 hot-path import gate
(fixes smoke: test_c7_import_gate_script_passes). Feature now also works on
installs shipping praisonai_bot without the full wrapper.
- Propagate --no-rules to the custom-agent and profiled prompt paths
(_run_custom_agent, _run_prompt_profiled) so the opt-out is honoured on every
non-interactive Agent construction site, not just _run_prompt.
- Add an execution-path test asserting all three paths accept/forward no_rules.
Co-authored-by: Mervin Praison <[email protected]>
- ACCEPT_EDITS previously set _permission_mode but the decision resolver
deferred it (no-op), so advertised auto-accept-edits behaviour never
applied. Add an ACCEPT_EDITS branch that auto-approves edit-class tools
(write/edit/append/create/save/patch/mkdir) via a new _is_edit_tool
heuristic, deferring destructive/exec/external tools to normal flow.
- Remove the misleading `read_only`-as-mode line from PermissionMode.resolve
docstring (read_only is a deny-set preset and resolves to None).
- Tests: auto-approve edit tools, defer non-edit tools, auto_edit alias.
Co-authored-by: Mervin Praison <[email protected]>
The interactive REPL lazily attaches a subdirectory's AGENTS.md/CLAUDE.md the
first time the agent reads/edits a file under it, but the scriptable
`praisonai run` path built Agent(**agent_config) without it. In a monorepo,
`praisonai run "refactor packages/foo/bar.py"` therefore never picked up
packages/foo/AGENTS.md while `praisonai chat` in the same repo did.
Reuse the existing subtree hook (praisonai.integration.context_files) and the
existing Agent(hooks=...) seam via a small `_wire_subtree_context_hook` helper,
registered on a fresh session-scoped registry at all three run.py Agent sites.
Gated by the existing --no-rules / PRAISON_NO_RULES off-switch and honouring the
shared PRAISON_CONTEXT_BUDGET character budget. No new Agent params, no new core
module, no agent.py changes — keeping the surface area unchanged.
Co-authored-by: MervinPraison <[email protected]>
Add PermissionMode.resolve() as the single mapper from historical mode
spellings (AutonomyMode/ApprovalMode/CLI-flag aliases) onto the canonical
PermissionMode enum, and route the existing Agent(approval=<preset>) string
branch through it. Agent(approval='plan'|'bypass'|'accept_edits'|'dont_ask')
(plus aliases like yolo/auto_edit/reject/full_auto) now resolve to one
coherent model. Deny-set presets (safe/read_only/full/off/default) keep
their exact behaviour. No new Agent params or exports.
Co-authored-by: MervinPraison <[email protected]>
- call.py: module globals (OPENAI_API_KEY, CALL_SERVER_TOKEN, NGROK_AUTH_TOKEN,
rate limits) were frozen at import, before main()'s explicit load_dotenv(),
so a .env-only key was silently ignored. Add _refresh_env_globals() invoked
after load_dotenv() (also refreshes the n8n router's CALL_SERVER_TOKEN).
- agentos.py: clone_for_channel intentionally drops handoffs; agents with
handoffs now stay on the shared template so delegation is never silently lost.
- test: cover the handoffs-not-cloned path (9 passed).
Co-authored-by: Mervin Praison <[email protected]>
Gap 1: /chat now clones a per-request/session agent (reusing the existing
_supports_session_isolation / _clone_agent helpers from api/agent_invoke.py)
so concurrent callers no longer share mutable chat_history, and session_id is
bound to the clone instead of merely echoed. Plain mocks fall back to the
shared instance for backward compat.
Gap 2 (minimal): api/call.py no longer calls load_dotenv() unconditionally at
import time; it is gated behind PRAISONAI_CALL_LOAD_DOTENV and loaded
explicitly in main() so the CLI keeps working. Importing the module no longer
mutates os.environ.
Gap 3 rejected as scope creep (breaking public-API churn with a deprecation
window; deferred per the issue).
Co-authored-by: MervinPraison <[email protected]>
- Docker deploy no longer disables auth by default; falls back to the
secure APIConfig() default (auth_enabled=True, token auto-generated)
instead of exposing an unauthenticated /chat on 0.0.0.0 (Greptile P1).
- Write the generated API server into a private per-invocation mkdtemp
(mode 0700) instead of a predictable shared tmp path, preventing
local replacement before launch (Greptile P1).
- Update pre-existing GHSA deploy-codegen test to assert the genuine
security property (repr-escaped path, no raw injection) rather than the
old implementation-coupled `PraisonAI(agent_file=...)` string; the PR
intentionally forwards the chat message via the wrapper `run(..., cli_config)`
entrypoint since `PraisonAI.run()` takes no args.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
- llm_guardrail: assign self.logger before _initialize_llm so unsupported/
string-fail/dict-fail paths can log and fail closed instead of raising
AttributeError (CodeRabbit major).
- llm_guardrail: __call__ now checks `self.llm is None` (matches _llm_validate)
instead of truthiness (CodeRabbit minor).
- tests/permissions: lock the scoped-approval bypass fix — an agent-scoped
approval must reject an unnamed (agent_name=None) caller.
Co-authored-by: Mervin Praison <[email protected]>
- cancel_task now cancels any non-terminal task (PENDING or RUNNING),
fixing test_cancel_task regression and Greptile P1: queued/PENDING
delegations no longer escape cancel_all.
- delegate() re-raises external CancelledError (Greptile P1) and only
swallows delegator-initiated cancels into a result, so wait_for /
cooperative shutdown behave correctly.
- _execute_task and the semaphore-guarded path early-return when a cancel
landed before execution, so a cancelled task never runs.
Co-authored-by: Mervin Praison <[email protected]>
Move API, Docker, and cloud deployment from the wrapper into a standalone
praisonai-deploy package with backward-compat shims, CI/publish wiring,
and fixes for chat message forwarding, Docker build context, and CLI YAML merge.
Co-authored-by: Cursor <[email protected]>
- permissions/rules.py: PersistentApproval.matches now rejects agent-scoped
approvals for callers that can't prove identity (including agent_name=None),
closing the short-circuit bypass while leaving unscoped approvals unaffected.
- guardrails/llm_guardrail.py: LLMGuardrail.__call__ now fails closed on a
missing/unsupported LLM, matching its docstring and sibling _llm_validate.
- agents/delegator.py: cancel_task/cancel_all now propagate cancellation to the
real asyncio.Task; _execute_task no longer clobbers a CANCELLED status with a
late COMPLETED assignment.
Co-authored-by: MervinPraison <[email protected]>
Add a `skills add` subcommand as a thin alias over the existing
`skills install` path so `praisonai skills add https://...` works,
mirroring the familiar `npx skills add <url>` verb. Reuses existing
install/remote-fetch machinery; no new deps, modules, or core params.
Co-authored-by: MervinPraison <[email protected]>
- @tool(requires_approval=False) now emits DeprecationWarning (any use of the
deprecated spelling nudges migration); use a sentinel to tell "omitted" from
explicit False. approval= still wins for the resolved value.
- Agent/PraisonAIAgents launch(protocol="mcp") now keep the serve_agents() call
inside the ImportError guard, so a praisonai-mcp installed without its
transport extras yields one actionable install message instead of an uncaught
traceback.
- Tests: explicit-False-warns, omitted-no-warn, both-set-warns, and
missing-transport-extras for single- and multi-agent launch.
Co-authored-by: Mervin Praison <[email protected]>
- @tool now accepts canonical approval= (mirrors Agent(approval=...));
requires_approval= kept as a deprecated alias with a DeprecationWarning,
approval= wins when both set. Both funnel to the same ApprovalRegistry.
- PraisonAIAgents.launch(protocol="mcp") and Agent.launch(protocol="mcp")
now both delegate to praisonai_mcp.serve_agents (lazy import, clear
"pip install praisonai-mcp" error). Replaces the bespoke single-agent SSE block.
- Add praisonai_mcp naming constants list_sessions / awaiting_approval.
- http launch behaviour untouched.
Co-authored-by: MervinPraison <[email protected]>
A stop-on-error failure inside a loop_over step now aborts the whole
workflow instead of only the inner item iteration, and a completed
loop_over step now persists a checkpoint so resume does not re-run every
loop item. Both fixes live in the shared _run_workflow_loop generator so
they apply to sync execute() and async aexecute() alike.
Co-authored-by: Mervin Praison <[email protected]>
Extract the duplicated step-loop from execute() and aexecute() into a single
sans-io generator (_run_workflow_loop) that owns all orchestration:
condition-skip, loop_over iteration, checkpoint save/resume, branch_condition/
next_steps routing, early-stop and on_error handling.
execute() drives it with the sync _execute_single_step; aexecute() drives the
same generator with a new async _aexecute_single_step that awaits async
executors / agent.achat / async handlers (true-async preserved).
This restores loop_over, branch, and checkpoint/resume parity to the async
path and adds checkpoint/resume params to aexecute. Public signatures and
return shapes are unchanged.
Co-authored-by: MervinPraison <[email protected]>
Catch import errors in _load_bundled_dashboard_app so that when the
bundled ui_dashboard preset is unavailable, the loader returns None and
the existing build_host_app fallback runs, instead of the exception
escaping to the outer handler and dropping aiui to the standard dashboard.
Addresses Greptile (P1) and CodeRabbit (Major) review findings on #3535.
Co-authored-by: Mervin Praison <[email protected]>
Route _run_aiui_dashboard through the bundled ui_dashboard/default_app.py
preset so the documented 9-page unified dashboard actually ships, making
the preset the single source of truth instead of a divergent hardcoded
5-page list. Falls back to the previous build_host_app defaults if the
preset cannot be loaded. Adds the missing ui_dashboard/__init__.py for
consistency with the other bundled UI presets.
Co-authored-by: MervinPraison <[email protected]>
- Namespace per-session transcripts by tool name so reusing a client
session_id across different ask_* agents no longer leaks history.
- Serialize each session's load->run->save under a per-session lock to
stop concurrent turns clobbering each other's completed turn.
- Disambiguate agents whose names normalize to the same tool suffix so a
later registration never silently shadows an earlier agent.
- Raise ValueError on unknown serve_agents() transport instead of
silently falling back to http-stream.
- Add regression tests for all four cases.
Co-authored-by: Mervin Praison <[email protected]>
Address reviewer P1 security findings on PR #3530:
- Fail closed: if registering the approval requirement raises, the
decorator now re-raises RuntimeError instead of logging and handing
back an executable but ungated tool.
- Validate risk-level strings against ("critical","high","medium","low")
so a typo like requires_approval="critial" is rejected up front rather
than silently treated as non-critical.
Adds regression tests for both cases.
Co-authored-by: Mervin Praison <[email protected]>
- praisonai-mcp: new serve_agents() + agent_adapter publishing ask_{name}
per agent and list_agents, with per-call session_id minting and in-adapter
per-session transcript continuity, running over the existing spec-compliant
http-stream transport. Server-side agents only; no client-set instructions.
- Fix Defect C: rebind memory adapter to the real core API
(store_short_term/search/get_all_memories/reset_all); the old bindings
(get_session/get_all/clear_session/clear_all/list_sessions/add) never existed.
- Drop client-controllable `instructions` from praisonai.agent.chat/run so the
connecting client can no longer rewrite the persona.
- Tests for per-agent tools, session continuity, no-client-instructions, and
memory adapter against the real API.
Co-authored-by: MervinPraison <[email protected]>
Adds a one-place approval declaration to the @tool decorator that
registers the tool with the existing global ApprovalRegistry at
definition time. `requires_approval=True` maps to the "high" risk
level; a string sets the risk level explicitly. No behaviour change
when unset. Backward compatible.
Co-authored-by: MervinPraison <[email protected]>
Addresses two valid reviewer findings on PR #3527:
- Stale anchor: the sync & async loops advanced `_last_run_at` *after*
`_execute_with_retry` persisted daemon state, so a restart restored the
prior slot and replayed an already-completed run/delivery. Mark the
wall-clock anchor *before* executing so the state write records this slot.
- Silent degrade: without the optional `croniter` engine a `cron:` schedule
reverted to the pre-#3526 process-relative interval with no signal. Emit a
one-time actionable warning (matching core `scheduler.due`) instead.
Tests: new default-install warning + state-persistence cases (run without
croniter); ticker cron tests gated per-class so they no longer skip the
whole module. Scheduler suite: 259 passed (3 pre-existing dotenv env
failures unrelated).
Co-authored-by: Mervin Praison <[email protected]>
The AgentScheduler / AsyncAgentScheduler wrapper loops collapsed cron
expressions to a coarse integer interval anchored to process start, so a
"daily 09:00 brief" fired at whatever o'clock the daemon launched, re-phased
on restart, and silently dropped runs across downtime/dormancy.
Add a lightweight, wrapper-local ScheduleTicker that reuses core's croniter
engine to sleep until the next real wall-clock occurrence, catch up a missed
slot exactly once on resume, and persist last_run_at in the existing daemon
state file so restarts don't re-phase. Plain intervals (hourly, */30m, raw
seconds) keep identical behaviour. No new core surface, exports, or params.
Co-authored-by: MervinPraison <[email protected]>
- Always inject the env var as GATEWAY_AUTH_TOKEN (the only name the gateway
reads); auth.secretKey now only selects the Secret data key.
- validateAuth now fails fast whenever auth.enabled is true without a token
source, not only when ingress is also enabled — the default install
previously referenced a Secret that was never created.
- Update README security note to match the stronger validation.
Co-authored-by: Mervin Praison <[email protected]>
The bot's dependency floor (praisonaiagents>=1.6.152) admits core releases
that predate AttemptAndAgeDeadLetterPolicy (first shipped 1.6.161). On those
installs the import guard previously bound None and both durable queues
silently reverted to attempt-only dead-lettering, re-introducing the #3519
transient message loss. Add a dependency-free LocalDeadLetterPolicy in
_resilience (mirroring core semantics: attempt+age gate, permanent-error
short-circuit, min_age=0 legacy) and bind it as the import fallback so the
age gate holds on any allowed core version. Adds older-core coverage tests.
Co-authored-by: Mervin Praison <[email protected]>
Ship a single, self-contained Helm chart under deploy/helm/praisonai-gateway
that reuses the existing GHCR image (no new build pipeline, no core code
change). Grounded in real gateway behaviour: port 8765, /health probes, and
GATEWAY_AUTH_TOKEN via a Kubernetes Secret. Includes optional ingress with
WebSocket-friendly annotations and an optional CPU HPA. Chart refuses to render
if the gateway would be exposed via ingress without an auth token.
Co-authored-by: Dhivya-Bharathy <[email protected]>
- Enforce closed OWNER_KINDS/DEGRADED_STATES in DegradedOwner.__post_init__
so unsupported values can never reach operator-facing records (Greptile P2).
- Route the existing channel-credential degradation path through new
gateway helpers _mark_degraded_owner/_clear_degraded_owner so the shared
_degraded_registry has a genuine live producer feeding degraded_owners,
not just an empty registry read by health() (Greptile P1).
- Drop unused dataclasses.field import; add vocabulary-rejection tests.
Co-authored-by: Mervin Praison <[email protected]>
Dead-lettering decided on attempt-count alone burned the default five
attempts in ~45s of channel outage, permanently dropping deliverable
inbound/outbound messages during routine transient incidents.
Add a core DeadLetterPolicyProtocol + default AttemptAndAgeDeadLetterPolicy
in praisonaiagents/gateway that requires BOTH attempt-exhaustion AND a
minimum wall-clock age (default 6h) before dead-lettering, while known
permanent errors (credential/permanent_target) still short-circuit. The
bot durable queues (OutboundQueue.drain, InboundJournal redelivery/replay)
consume the policy where they previously tested attempts >= max_attempts,
gaining a dead_letter_min_age knob. min_age=0 restores legacy behaviour.
Co-authored-by: MervinPraison <[email protected]>
Adds a small, process-local DegradedCapabilityRegistry + DegradedOwner
contract in core (praisonaiagents/gateway/degraded_state.py), mirroring the
existing gateway policy-protocol + default-impl pattern. Any owner (channel,
provider, capability, route, gateway) records degradation with a consistent,
redacted, actionable shape.
Wires the bot gateway health() as a live consumer: it aggregates existing
channel degradation facts (plus any provider/capability/route degradation
recorded into a shared registry) into a single degraded_owners surface, so a
degraded provider or unresolved secret-backed capability is no longer
classified-but-invisible. The channel-only surface stays for backward compat.
Co-authored-by: MervinPraison <[email protected]>
The wrapper YAML schema types `autonomy` as an int 0-10 but core
Agent only accepts bool/str/dict/AutonomyConfig; forwarding the raw
int hit core's disable branch and silently ignored a configured
level. Map the numeric level onto core's string presets (0 => off,
1-3 => suggest, 4-7 => auto_edit, 8-10 => full_auto) and pass
bool/str/dict through unchanged.
Co-authored-by: Mervin Praison <[email protected]>
- praisonai_adapter._resolve_agent_approval: map the wrapper approval dict
onto the real ApprovalConfig fields (approve_all_tools->all_tools, resolve
string backend) instead of passing extra keys into the dataclass, which
raised TypeError on every --trust/--approve-* run against the native adapter.
- praisonai_adapter.run + persistence sync stores + async TUI: route through
the existing run_sync_or_offload helper instead of run_sync, so the flagship
sync praisonai.run(...) API and sync persistence hooks no longer crash from
inside a running loop (FastAPI, async test, notebook).
- praisonai_adapter._build_agents_and_tasks: forward agent-level fields the
core Agent already accepts (planning, reflection, guardrails, web, autonomy,
skills) instead of silently dropping them.
Co-authored-by: MervinPraison <[email protected]>
The per-instance async semaphore fix (correctly) enforces each Handoff's
own max_concurrent, but moved _semaphore_lock to instance level, breaking
the architectural test that asserts Handoff._semaphore_lock is a single
shared class attribute. Restore it as a class-level threading.Lock guarding
lazy semaphore creation while keeping the semaphore itself per-instance.
Co-authored-by: Mervin Praison <[email protected]>
- llm.py: add LLMResponseError and re-raise instead of swallowing a
mid-tool-loop error and returning "" as if the call succeeded, so the
existing try/except in chat_mixin.py can surface the real failure.
- memory.py: make adapter search/reset/delete gates symmetric with the
adapter-agnostic store path (any configured memory_adapter, not just
the hardcoded sqlite/in_memory providers). Also make store_long_term
adapter-agnostic to match store_short_term so adapter-stored memories
(e.g. "dakera") remain findable.
- handoff.py: make the concurrency semaphore instance-level (created once
per Handoff, rebound if the running event loop changes) instead of a
class-level singleton, so per-handoff max_concurrent limits no longer
override each other and multiple asyncio.run() lifecycles don't crash.
Co-authored-by: MervinPraison <[email protected]>
Reads the 'unchanged default = use stock image' sentinel off ComputeConfig's
dataclass field default instead of hardcoding "python:3.12-slim", so the
image-selection logic can't silently drift if that default changes
(CodeRabbit out-of-diff nit).
- get_status/list_instances now refresh remote Tenki state (sandbox.refresh
+ .state) instead of trusting the local map, so a server-side idle timeout
no longer surfaces as RUNNING while execute() hits a dead sandbox. Mirrors
the E2B provider's is_running() reconciliation.
- add exception chaining on the SDK ImportError (raise ... from e)
- drop the misleading docstring image example (it passed the default sentinel
that is intentionally treated as the stock image)
load() acquired the exclusive lock over max(file_size, 1) bytes on
Windows but discarded the returned length, so _release_exclusive_lock
fell back to unlocking only 1 byte. For session files larger than one
byte this left the remaining range locked until file close, blocking
concurrent access. Pass the acquired lock_length to the release call
to unlock the full range, mirroring save().
Co-authored-by: Mervin Praison <[email protected]>
- Persist reasoning/tool-progress/stream-error frames for reconnect replay (CodeRabbit)
- Missing agent now resolves terminally (final+error) instead of a dangling accepted ack (Greptile P1)
- Drain relay futures before final frame so final never overtakes trailing stream events (Greptile P1)
Co-authored-by: Mervin Praison <[email protected]>
Forward a closed set of structured progress events (reasoning, tool
progress, stream errors) to WS clients instead of dropping everything
but text/tool-call/end, and disambiguate the overloaded response frame
with status: "accepted" (provisional) vs status: "final" (with a
structured outcome).
Co-authored-by: MervinPraison <[email protected]>
Closes the two P1 gaps flagged in review: name-based schedule lookups/removals
had no principal check (a gateway user could read/delete another's automation by
guessing its name), and suggestion admission caps/dedup were measured globally
(one tenant could starve another's suggestions).
- store.py / config_store.py: get_by_name/remove_by_name gain optional principal
filter; a cross-owner match is skipped. principal=None stays global.
- protocols.py: ScheduleStoreProtocol get_by_name/remove_by_name updated.
- suggestion_store.py: add() scopes the pending cap & dedup window to the
suggestion's principal; principal=None keeps the global pool.
- tests: +6 cases for name-based mutation ownership and per-principal caps/dedup.
Co-authored-by: Mervin Praison <[email protected]>
Wire BasePlatformAdapter.format_message() (the existing deliver() seam) to
call format_for_dialect(text, caps.markdown_dialect) so the capability is
actually consumed in core — Telegram replies are MarkdownV2-escaped and Slack
gets mrkdwn. Default "markdown" dialect keeps existing adapters unaffected.
Fix strip_markdown to only unwrap *paired* emphasis/code spans so literal
identifiers (svc_1), globs (*.py) and arithmetic (a*b) are no longer corrupted.
Adds regression tests for both fixes.
Co-authored-by: Mervin Praison <[email protected]>
Add an optional `principal` owner key to the core scheduler data model so
a multi-user gateway isolates each user's automations and suggestions
instead of sharing one global, single-tenant store.
- Suggestion.principal + SuggestionStore.list_pending/accept/dismiss gain
an optional principal filter that rejects cross-owner access.
- ScheduleJob.principal round-trips through to_dict/from_dict; FileScheduleStore
and ConfigYamlScheduleStore .list() gain an optional principal filter.
- ScheduleStoreProtocol.list signature updated.
principal=None preserves the current global behaviour, so single-user
deployments are unaffected (fully backward compatible).
Co-authored-by: MervinPraison <[email protected]>
The bare-tool-name guard skipped the stdout-reporting instruction for
preconfigured agents whose own system prompt mentions execute_command,
leaving the "no output" bug reachable. Guard on a stable marker phrase
instead, keeping injection idempotent. Strengthen assertions and add
regression coverage for the preconfigured-prompt and duplicate paths.
Co-authored-by: Mervin Praison <[email protected]>
Addresses the durable at-least-once guarantee gaps flagged in review:
- Persist the recipient client_id alongside each pending event and
reconstruct _pending_acks on startup, so replayed events are scheduled
for retry/reconnect redelivery instead of being silently dropped.
- Evict acknowledged events from the SQLite store (and in-memory cache)
so acked rows are not resurrected after a restart.
- Backfill client_id column for pre-existing stores; strengthen tests to
assert redeliverability after restart and ack-eviction.
Co-authored-by: Mervin Praison <[email protected]>
Strengthen the shell-tool instruction in enable_shell_tools so the
gateway agent actually invokes execute_command and returns its stdout
verbatim, instead of intermittently replying "there was no output".
This addresses the flaky E2E sandbox marker check (E2E_SANDBOX_OK).
Co-authored-by: Dhivya-Bharathy <[email protected]>
Path.home() resolves via USERPROFILE on Windows, not HOME. The fixture
only set HOME, so on Windows the tool wrote to the real user profile and
the positive test asserted a file under tmp_path that was never created.
Set USERPROFILE alongside HOME so the fake home is honored on all
platforms and no writes escape the sandbox.
Co-authored-by: Dhivya-Bharathy <[email protected]>
Make the gateway's at-least-once push delivery guarantee durable by default
without an external Redis server. DeliveryConfig.store_backend now accepts
"sqlite" (new default), "redis" and "memory", validated in core. The wrapper
gains a SqlitePushStore mirroring the existing OutboundQueue pattern (WAL,
stdlib sqlite3, TTL eviction) at ~/.praisonai/state/push_delivery.sqlite, so
pending un-acked events survive a restart and replay on reconnect. "memory"
stays an explicit ephemeral opt-out; "redis" stays for multi-process fan-out.
Co-authored-by: MervinPraison <[email protected]>
- discovery.py: auto-include synced remote-skill cache (`current` aliases) in
default skill dirs so agents pick up `skills sync` output without install;
scan now treats a returned dir that is itself a skill (root-level SKILL.md)
as a single skill.
- remote.py: return the fetched dir as-is (never its parent) so a root-level
skill is not double-counted alongside its cache `current` alias.
- skills.py (CLI): `sync` reuses discover_skills (no re-implemented scan / no
double-count); no-URL sync now reads project praisonai.yaml/.yml as well as
the user-global config.
- test_remote.py: regression test for root-level SKILL.md repo discovered once.
Co-authored-by: Mervin Praison <[email protected]>
Task._setup_guardrail selected `agent.llm or agent.llm_instance`; since
agent.llm is always a non-empty model-name string it always won, discarding
the configured LLM instance (base_url/api_key/auth) and authenticating against
the wrong backend. Reorder to `llm_instance or llm`, matching
Agent._setup_guardrail. small_model routing still applies only to the bare
string case. Adds Task guardrail routing/instance-preference tests.
Co-authored-by: Mervin Praison <[email protected]>
Internal, non-user-facing LLM calls (context compaction/summarisation and
LLM guardrail validation) always ran on the primary agent model. Thread the
existing get_small_model resolver through these live auxiliary call sites so
a configured small_model is used, while leaving it unset preserves today's
behaviour (unset -> primary model).
- agent._create_llm_summarize_fn: resolve the summariser model via
get_small_model(primary_model=<agent model>) instead of hardcoding self.llm.
- Agent/Task LLM guardrail setup: when the guardrail LLM would default to the
bare primary model-name string, route it through get_small_model.
Change is strictly additive and backward-compatible: an explicit LLM instance
or per-call model always wins.
Co-authored-by: MervinPraison <[email protected]>
Introduce an opt-in RemoteSkillSourceProtocol and a default git-backed
implementation that syncs skills into a versioned local cache with atomic
swaps and offline-safe fallback to the last-good cache. Wired into
discover_skills via a new sources= param (backward compatible, zero
import-time cost) and surfaced through a `praisonai skills sync` CLI
command reading skills.urls / skills.sources from config.
Co-authored-by: MervinPraison <[email protected]>
Addresses two P1 reviewer findings on the wrapper-layer PR:
- registry.py: move the capability cache off a process-global dict onto the
FrameworkAdapterRegistry instance so two registries that register different
adapters under the same name no longer read each other's flags.
- observability/hooks.py: record which AgentOps teardown a run owns
(per-session vs legacy singleton). A run whose start_session returned no
usable handle now ends nothing instead of falling back to the package-global
end_session and cross-finalizing a concurrent run.
- agents_generator.py: keep the "cannot verify" refusal for genuinely unknown
frameworks while treating known built-ins (DEFAULT_PRIORITY / registered)
whose adapter can't be constructed as unsupported, preserving the historical
"not supported for framework=..." message.
Adds regression tests for all three behaviours.
Co-authored-by: Mervin Praison <[email protected]>
Gap 1: scope AgentOps to each ObservabilityRun (per-run start_session
handle + lock) instead of the process-global singleton so concurrent
runs don't cross-contaminate tags or cross-finalize sessions.
Gap 2: add run_sync_or_offload() to _async_bridge as the single
sync-or-offload driver; delete the duplicated copies in auto.py, use it
in PersistenceOrchestrator._sync (was silently raising inside a running
loop), and replace deprecated get_event_loop().run_in_executor with
asyncio.to_thread in api/agent_invoke.py.
Gap 3: add adapter_capability() and route SUPPORTS_RUNTIME_FEATURES /
SUPPORTS_WORKFLOW decisions through it, removing the
str(framework)=="praisonai" fallbacks so third-party adapters aren't
silently demoted on transient resolution failures.
Co-authored-by: MervinPraison <[email protected]>
The restore-all prune loop deleted every project file absent from the
target commit, silently destroying ignored/excluded files (.env, venv,
node_modules) that the snapshot never tracked. Mirror _sync_files()'s
ignore rules in restore so only would-be-tracked files are pruned.
Co-authored-by: Mervin Praison <[email protected]>
- snapshot: prune shadow files removed from the project in _sync_files() and
restrict restore() "restore all" to the target commit's tree (removing files
not in it), so undo() cannot resurrect deleted files or leak files from a
later snapshot.
- skills: guard the pending-store load-mutate-save cycle in _stage_pending/
approve/reject with a threading.Lock so concurrent proposals no longer
silently overwrite each other.
- permissions: consume a scope="once" approval/denial on first match in
_check_flat so it no longer becomes permanent for the process lifetime.
Co-authored-by: MervinPraison <[email protected]>
Delegate mcp.py's inline SSE-vs-HTTP URL check to the existing
mcp_transport.get_transport_type() helper so there is a single source of
truth for URL->transport classification. No behaviour change: /sse URLs
still use SSE and all other HTTP URLs use Streamable HTTP.
Co-authored-by: MervinPraison <[email protected]>
HooksQueryProtocol had zero importers, was not exported in
hooks/__init__.py __all__ or _LAZY_GROUPS. Consumers use
registry.list_hooks_for_api directly. No behaviour change.
Co-authored-by: MervinPraison <[email protected]>
Sync from_dict with to_dict so retry_initial_delay, retry_backoff_factor,
retry_jitter and compaction_strategy survive a to_dict/from_dict round-trip.
Also align code_sandbox_mode fallback with the dataclass default ("sandbox").
Co-authored-by: MervinPraison <[email protected]>
Both helpers in the praisonai wrapper's agents_generator.py were defined
but referenced nowhere (no callers, no tests, not exported). Also drops
the now-unused `import keyword` used only by the removed function.
Co-authored-by: MervinPraison <[email protected]>
- browser_available() now requires the playwright runtime importable, not just
praisonai_browser, so a base install without the Playwright extra falls back
to the cloud BrowserBaseTool instead of selecting a local tool that fails at
invocation (Greptile P1).
- create_browser_tool no longer advertises profile=X as active; PlaywrightBrowserAgent
has no profile param and uses a fresh context, so the value is now logged as
informational-only rather than misreported (Greptile P1).
- Add unit test covering the missing-Playwright fallback path.
Co-authored-by: Mervin Praison <[email protected]>
BotHandler._build_tools() now prefers praisonai-browser's local Playwright
automation (navigate/snapshot/click) over cloud-only BrowserBaseTool when
capabilities.browser is set, honouring --browser-headless / --browser-profile.
Falls back to BrowserBaseTool only when praisonai-browser is unavailable.
Adds a lazy _browser_bridge (mirroring _code_bridge) and an agent-callable
browser_automate tool wrapping PlaywrightBrowserAgent.
Co-authored-by: Dhivya-Bharathy <[email protected]>
Adds safe_print() to praisonai_bot.gateway.unicode_utils so E2E harnesses and
console reporters can echo Playwright's "playwright install" banner (drawn with
box chars like U+2551) without crashing on default Windows cp1252 consoles.
Falls back to safe_error_message() sanitization only when the stream encoding
rejects the text, keeping the actionable hint readable instead of masking it
behind a secondary UnicodeEncodeError.
Co-authored-by: Dhivya-Bharathy <[email protected]>
The CodeToolBridge.run_code(code) contract dropped the caller's per-run
allow-list, registry, timeout and max_output_size, so a transport could
only gate isolated tool calls by bridge-owned defaults — a weaker path
than the in-process executor and contrary to the "never a weaker path"
guarantee. Forward the invocation policy and limits to run_code so the
transport gates each call by exactly what the caller authorised.
- CodeToolBridge.run_code now takes allowed_tools/registry/timeout/
max_output_size as keyword-only params (new protocol, no external
implementers — fully backward compatible for existing callers).
- execute_code_with_tools forwards the invocation context to the bridge.
- Tests: recording bridge now uses only forwarded policy; added coverage
for policy/limit propagation and forwarded-allow-list enforcement.
Co-authored-by: Mervin Praison <[email protected]>
Add a transport-agnostic CodeToolBridge protocol and parent-side
serve_tool_call helper in core, plus a backward-compatible bridge=
option on execute_code_with_tools. When a bridge is supplied, code runs
under isolation and reaches tools over the bridge (same allow-list +
approval gate); omitting it preserves today's in-process behaviour.
Concrete per-backend transports remain a follow-up in the sandbox layer;
core only defines the contract to stay lightweight.
Co-authored-by: MervinPraison <[email protected]>
Address three P1 gaps in the gateway cancellation/timeout work:
- Timeout was unreachable: add per_turn_timeout to the bot GatewayServerSchema
(extra="forbid" was rejecting it) and stamp it onto self.config in
start_with_config so the documented YAML knob actually takes effect.
- Turn isolation: pass the InterruptController per-turn as the entry point's
cancel_token instead of mutating the shared agent.interrupt_controller, so
overlapping sessions on one Agent instance no longer interrupt each other.
Legacy agents without a cancel_token kwarg fall back to the shared attribute.
- Cancellation honesty: interrupt cooperatively first and wait a bounded grace
window (_ABORT_GRACE_SECONDS) for the turn — including a sync agent.chat in a
worker thread that cannot be force-killed — to unwind before the serial
session queue advances; hard task.cancel() only as a fallback.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Empty-string targets were skipped by the `if target` truthiness check,
retaining the silent fallback/misroute this validation prevents. Skip
only None (omitted) so every supplied string target is validated.
Co-authored-by: Mervin Praison <[email protected]>
Wire per-turn abort + timeout into the gateway so a runaway turn can no
longer wedge the serial per-session queue:
- Advertise the `abort` method (+ `message_abort` event) in the hello
capability handshake instead of the "abort not implemented" placeholder.
- Handle `abort`/`message_abort` WS frames and a portable `/stop` chat
command; both drive the existing InterruptController and cancel the
driving asyncio task via a new `_active_turns` registry.
- Run each turn under an optional `gateway.per_turn_timeout` (YAML/config
knob, 0 = disabled) via `_drive_turn`, normalising cancelled/timed-out
turns to a typed terminal message instead of leaving them hanging.
Reuses core's InterruptController (already checked by the agent run loop)
and `agent.interrupt_controller`; no new agent params.
Co-authored-by: MervinPraison <[email protected]>
Cross-check every channel's routes/routing targets (including default) and
bindings.agent against the declared agents: map in the canonical schema
validator. A typo now fails fast at load time (and in gateway doctor, which
loads via this schema) with the channel, bad target, and closest valid agent
id — instead of a silent logger.warning + misroute. Only enforced when
agents: is declared, so single-bot configs stay backward-compatible.
Co-authored-by: MervinPraison <[email protected]>
A run with session_id now routes to the stateful per-session agent
(_get_session_agent), not _get_agent. The test only stubbed _get_agent,
so it built a real Agent with no LLM backing and start() returned ''.
Stub the session builder too so the event fan-out contract is exercised
without a live LLM.
Co-authored-by: Mervin Praison <[email protected]>
Fixes Greptile P1: a value-taking run option whose separated value begins
with a dash (e.g. `--session -abc`, `--output -json`) was mis-classified by
`_flag_names` as an unsupported flag, diverting an otherwise fully
run-supported prompt to the legacy engine and losing session continuity,
--output modes, the credential gate and permissions.
`_flag_names` now accepts the `value_opts` set and skips the token consumed
by a value-taking option (with `--opt=value` handled inline). `_looks_like_
bare_prompt` passes `run`'s value-taking options in, and short-circuits the
no-dash case before the (potentially heavy) run-option introspection.
Co-authored-by: Mervin Praison <[email protected]>
Address 3 P1 review issues on the stateful warm-runtime session path:
- Attach id no longer replaces session identity: `run.py` passes the
persistence/conversation id as `session_id` and the `--attach` label as a
distinct `event_id`. A `--no-save --attach <id>` run streams events to the
attach id but stays on the isolated anonymous path (no persistence).
- Model override rebuilds the session agent: the per-session warm agent is now
keyed by the resolved model, so a later turn with a different model no longer
silently runs the previous provider/model.
- Continuity-wiring failure is not cached: when session-store wiring fails, the
turn runs one-shot but the unwired agent is not retained, so a later turn
retries wiring instead of permanently serving an uncoupled agent.
Wrapper-only (praisonai-code); no core SDK changes, no new Agent params, no new
deps. Adds tests for model override, continuity-failure, and event/session id
separation; updates the attach mock to accept `event_id`.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Address Greptile P1 findings on the interruptible-turn wrapper:
- Primary prompt-toolkit path now requests cooperative cancellation on
Ctrl-C when a turn is in flight (previously only reset the input
buffer), and clears any stale request at the start of each background
turn so a fresh turn is not immediately interrupted.
- _execute_prompt_interruptible refuses to start a new turn (and to clear
the shared controller) while a prior abandoned worker is still alive,
preventing the abandoned turn from being un-cancelled and resuming
against the warm session.
- Added test_abandoned_worker_blocks_new_turn.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
The CLI router treated any -/-- flag as a signal to fall back to the legacy
argparse engine, so common cases like `praisonai "fix the bug" --model gpt-4o`,
`--continue`, or `--output json` silently bypassed the modern `run` engine and
lost session continuity, --output modes, the credential gate and permissions.
_looks_like_bare_prompt now derives the run-supported option names by
introspecting the run command's Click parameters and routes a bare prompt to
`run` when every flag present is one run accepts; genuinely legacy-only flags
(and .yaml/.yml workflows) still fall back to legacy, now with a one-line
notice so the fallback is never silent. _build_run_argv reconstructs the
prompt + flags into a single `run "<prompt>" <flags>` invocation.
Co-authored-by: MervinPraison <[email protected]>
The warm runtime was a cold-start cache only: every /run cleared history
and --continue/--session runs bypassed the warm path, paying cold-start
each turn. Add a per-session warm agent registry keyed by session id that
rehydrates history once (via the existing apply_cli_session_continuity
wiring) and retains it across turns, while the anonymous path stays
isolated. Relax runtime_eligible so --continue/--session route to the warm
stateful path (fork/isolated/thinking/tool runs stay in-process).
Co-authored-by: MervinPraison <[email protected]>
Attach the core InterruptController to the interactive agent and run each
turn in a worker thread so the main thread stays responsive. Ctrl-C during
a turn now requests cooperative cancellation; the core chat loop honours it
at the next step boundary, returns partial output, and keeps the warm agent
and session intact. Wrapper-only change reusing the existing core primitive.
Co-authored-by: MervinPraison <[email protected]>
- write_file compute bridge: replace heredoc with base64-decoded stdin so
content can no longer terminate the heredoc early (silent truncation) or
inject host commands.
- LocalCompute._install_packages: validate pip specifiers against the strict
allowlist and shlex.quote each token before host execution.
- LocalManagedAgent._ensure_agent: pass api_key/base_url directly to the inner
Agent instead of os.environ.setdefault, preventing process-wide credential
pollution and subprocess env leakage across tenants.
Co-authored-by: MervinPraison <[email protected]>
Do not clear task._execution_context inside _build_execution_context.
The run_task/arun_task retry loops re-enter this helper on guardrail /
completion failures; clearing stripped the upstream output and validation
feedback the retry needs (Greptile P1). The Process engine already owns
this field's lifecycle (re-set before each yield, reset to None before
selecting the next task), so no cross-task leak.
Co-authored-by: Mervin Praison <[email protected]>
- mcp.py: wrap session.call_tool/read_resource/get_prompt in asyncio.wait_for
so a hung server fails one request without wedging the runner loop forever
- agents.py: fold task._execution_context (inter-task context + validation
feedback built by Process._build_task_context) into the prompt builder, and
clear it after consumption so it doesn't leak into later runs
- workflows.py: track future->idx map in parallel loop so error attribution
survives exceptions instead of using an unbound/stale idx
Co-authored-by: MervinPraison <[email protected]>
The legacy async tool loop in _achat_completion fired BEFORE_TOOL/AFTER_TOOL
inline and then again inside execute_tool_async, double-firing hooks when
registered and building hook inputs (os.getcwd/time.time) with no consumer
when none are. Rely on the single guarded dispatch in execute_tool_async,
which already handles blocking, arg mutation and after-context aggregation.
Co-authored-by: Mervin Praison <[email protected]>
The --entrypoints option was documented and parsed into use_entrypoints
but never wired to any discovery behavior. Removed the dead flag and
updated the docstring to reflect the actual --include-only interface.
Co-authored-by: Mervin Praison <[email protected]>
action_discover now reads built-in/external/registered/local from the
canonical ToolResolver.list_available_sources() in a single authoritative
walk, matching the resolver-first pattern already used by _get_builtin_tools
and templates/tools_doctor.py. The original praisonai_tools + TOOL_MAPPINGS
scan is preserved as an explicit offline fallback (_legacy_manual_scan) for
environments without praisonai-code. --include/--entrypoints flags and
grouped output are unchanged.
Co-authored-by: MervinPraison <[email protected]>
Downstream _execute_tool_async_impl matched only on __name__ and called
func(**args) directly, so a BrowserBaseTool-style BaseTool instance
(resolved by .name in dispatch) returned "not found" / never ran. Mirror
the robust sync resolution (BaseTool.name, FunctionTool .name alias, class
name) and invoke func.run() for BaseTool instances.
Also fix the short-circuiting `or` chain in async dispatch so an aliased
.name that differs from __name__ resolves instead of being dropped.
Adds regression tests exercising the real (unmocked) execute_tool_async
for a BaseTool instance and an aliased callable name.
Fixes#3450
Co-authored-by: Mervin Praison <[email protected]>
Address CodeRabbit review: when neither the monorepo praisonai-mcp sibling
nor an installed praisonai_mcp.mcp_server is available, the C12 shim cannot
resolve. Convert the resulting bare ModuleNotFoundError collection error into
a clean module-level pytest.skip. Guard find_spec against ModuleNotFoundError/
ValueError for an absent/broken parent, mirroring praisonai._bootstrap.
Co-authored-by: Mervin Praison <[email protected]>
Bot --browser wired BrowserBaseTool (a BaseTool instance without
__name__), causing async tool dispatch to raise
'BrowserBaseTool' object has no attribute '__name__'. Harden the
lookup in _achat_completion to resolve by __name__, .name, or class
name so all BaseTool subclasses dispatch safely, and drop the ad-hoc
__name__ monkey-patch in bots_cli.
Co-authored-by: Dhivya-Bharathy <[email protected]>
- Guard Unix-only ``resource`` import so _admission.py loads on Windows;
sampler self-disables gracefully when unavailable (Greptile P1 #1).
- Wire ``max_rss_mb`` through BotOS + gateway.yaml via a single-knob
build_memory_pressure_policy() so the feature has a live production
consumer instead of a dormant param (Greptile P1 #3).
- Surface max_rss_mb in admission stats; document resource-only soft-queue
degradation honestly rather than silently misleading (Greptile P1 #2).
- Correct MemoryPressurePolicy docstring to reference the real config key.
- Add tests: Windows-safe sampler, single-knob policy, BotOS wiring, stats.
Co-authored-by: Mervin Praison <[email protected]>
Move the new continuable param to the end of schedule_add() so the
pre-existing 9th positional slot still binds accept_suggestion, avoiding
a silent behaviour change for positional callers (Greptile P1).
Co-authored-by: Mervin Praison <[email protected]>
A transient DLQ-init failure no longer latches _outbound_resilience_ready,
so a later delivery re-attempts initialization once storage recovers,
instead of permanently degrading to retry-only and silently dropping
permanently-failed replies. Adds a regression test.
Co-authored-by: Mervin Praison <[email protected]>
Runtime exception messages could contain non-cp1252 characters that
would re-trigger UnicodeEncodeError on Windows consoles when printed.
Wrap exception interpolation in ascii() for all 7 failure messages.
Co-authored-by: Mervin Praison <[email protected]>
A delivered automated brief now seeds a resumable session so the user's
reply in the same chat resumes the job's conversation with full context,
instead of landing as a contextless new turn.
- core: add declarable DeliveryTarget.continuable field (opt-out only,
round-tripped in to_dict/from_dict) as the 3-way surface contract
- wrapper: gateway _deliver_scheduled_result seeds the reply session via
the existing mirror_to_session path when continuable
- tool/CLI: thread continuable through schedule_add + a --no-continuable
flag for fire-and-forget notices
Co-authored-by: MervinPraison <[email protected]>
Gateway admission was concurrency/CPU-scaled only and blind to memory, so a
burst of concurrent turns on a small always-on host drives RSS up until the
OOM killer fires — observed only post-mortem. This adds a resource-pressure
policy that queues under soft RSS pressure and sheds under hard pressure,
reusing the existing admission seam.
Core (praisonaiagents/gateway): ResourceSample, ResourcePressurePolicyProtocol
and a stdlib-first MemoryPressurePolicy (pure decision, no heavy imports),
sitting beside the concurrency / rate-limit / scale-to-zero policy family.
Wrapper (praisonai_bot/bots/_admission.py): a lightweight _RssSampler
(psutil-optional, resource.getrusage fallback, self-disables on unsupported
platforms) and AdmissionGate(resource_policy=...) wiring that folds the
resource decision into admit() by escalating to the more restrictive outcome.
Co-authored-by: MervinPraison <[email protected]>
Mirror the durable inbound journal on the outbound side: when no
outbound DLQ path is configured, default to the canonical per-platform
store (~/.praisonai/state/<platform>/outbound_dlq.sqlite) so a
permanently-failed or exhausted reply is parked (auditable + replayable)
instead of silently dropped. Escape hatch: outbound_resilience.enabled=false.
Co-authored-by: MervinPraison <[email protected]>
The wrapper permits a range of praisonaiagents versions (>=1.6.152), but
_attach_gateway_runtime imported GatewayRuntimeSeams/GatewayAdapterContractError
unconditionally — symbols only present in current core. On an older-but-allowed
core that import raised ImportError on every start()/probe()/health() (Greptile
P1). Guard the import and fall back to the pre-contract duck-typed splices so
those installs keep wiring identity resolution, delivery routing, admission
control, and cross-platform turn locking. The no-seams path now returns before
any import, staying a pure no-op independent of core version.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Classify loopback numerically via ipaddress so 127.0.0.2,
127.255.255.255, and expanded IPv6 ::1 keep the snappy loopback drain
instead of the 15s production window. Addresses Greptile review feedback.
Co-authored-by: Mervin Praison <[email protected]>
- classify_reload now rejects empty channel names (channels., channels..enabled)
and falls through to the fail-safe FULL restart instead of restarting channel ""
- wrapper _build_reload_plan gracefully degrades to full restart if an older
supported praisonaiagents lacks classify_reload, instead of crashing the reload
- add regression tests for malformed channel paths
Co-authored-by: Mervin Praison <[email protected]>
The unset (None) reliability posture now resolves to a backpressured
deployment — bounded admission ceiling + fair wait queue + graceful drain —
instead of the old no-admission one. It is bind-aware: a non-loopback bind
(a real deployment) resolves to the full production window, loopback keeps a
snappy 5s drain. reliability="off" opts back into today's immediate-teardown
behaviour; explicit reliability="default" keeps the legacy no-ceiling posture.
Co-authored-by: MervinPraison <[email protected]>
Add a pure, side-effect-free ReloadScope/classify_reload registry to the
core SDK so hot-appliable vs channel-scoped vs agents vs full-restart is
classified identically by every runtime, instead of being duplicated
ad-hoc in the wrapper. The wrapper's _build_reload_plan now delegates to
core, keeping the existing scoped per-channel restart behaviour while the
contract "grows" in the authoritative layer. Backward-compatible.
Co-authored-by: MervinPraison <[email protected]>
Addresses reviewer feedback on PR #3437:
- Greptile P1: the published editor schema was stricter than the runtime.
generate_agents_schema() now relaxes AgentConfig (drops required
role/goal/backstory, which the runtime auto-fills or maps from
'instructions') and allows list-form roles/agents (runtime _list_to_dict),
so editors no longer flag valid, executable YAML. The strict YAMLConfig used
by ConfigValidator is unchanged.
- Greptile P2: replace the silent `except Exception: pass` around the
yaml-language-server header write with a debug log so a dropped directive is
diagnosable.
- Regenerate agents.schema.json; add a runtime-parity guard test.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
- Legacy-only sessions now honour --sanitise instead of returning a raw
verbatim transcript, closing a secret-leak gap.
- Enforce --redact-level contract: validate against REDACT_LEVELS (standard|
strict), reject typos at the CLI, and give strict a real effect (masks
bearer tokens and PEM private-key blocks).
- Path matcher now covers single-segment POSIX (/tmp), C:/ Windows, and UNC
(\\server\share) paths; the cwd is masked as a stable path placeholder so it
is no longer half-masked as a secret leaving a dangling suffix.
- Add tests for single-segment/UNC paths, cwd suffix, strict mode, invalid
level, and exported REDACT_LEVELS.
Co-authored-by: Mervin Praison <[email protected]>
Derive a JSON Schema from YAMLConfig (generate_agents_schema), publish it as
a committed agents.schema.json artefact, expose it via `praisonai validate
schema --agents/--output`, and prepend a `# yaml-language-server: $schema=`
header when auto.py scaffolds agents.yaml so editors give autocomplete /
inline validation out of the box. Authoring-time only; runtime parsing and
execution are unchanged (a leading YAML comment is ignored by safe_load).
Co-authored-by: MervinPraison <[email protected]>
Address CodeRabbit review on MCP test conftest:
- Check the shim's required praisonai_mcp.mcp_server submodule instead of only
the top-level package, so a partial/incompatible install can't pass the guard
while collection still fails.
- Emit a pytest_report_header when MCP tests are skipped so contributors see why
and how to install praisonai-mcp.
Co-authored-by: Mervin Praison <[email protected]>
Playwright's "playwright install" banner uses box-drawing frame characters
(U+2551 etc.). On Windows cp1252 consoles these could clutter the sanitized
error text with '?' placeholders, obscuring the actionable hint. Map the
common frame characters to spaces in safe_error_message's symbol table so the
hint stays readable while remaining ASCII-safe.
Co-authored-by: Dhivya-Bharathy <[email protected]>
Add a lightweight, deterministic redactor so `praisonai session export
<id> --sanitise` (alias `--sanitize`) replaces secrets, absolute paths,
the working directory, and embedded file contents with stable
`[redacted:<category>:<n>]` placeholders. Default export is unchanged.
- new redact.py helper with stable placeholder map (stdlib only)
- wire redact/redact_level through export_session (Python: redact=True)
- wire --sanitise/--sanitize + --redact-level CLI flags, default off
- unit tests over a seeded secret, absolute path, and stable placeholders
Co-authored-by: MervinPraison <[email protected]>
Add tests/unit/mcp/conftest.py that restores the monorepo dev layout via
ensure_praisonai_mcp() and uses collect_ignore_glob to skip the directory
when praisonai_mcp is neither installed nor present as a sibling checkout,
turning a ModuleNotFoundError collection error into a clean no-op.
Co-authored-by: Dhivya-Bharathy <[email protected]>
The basic smoke script crashed with UnicodeEncodeError on Windows
default consoles (cp1252) because print() statements embedded emoji
(U+1F9EA, U+2705, U+274C, U+1F389) that cannot be encoded to stdout.
Replace all emoji with ASCII status tags ([TEST], [OK], [FAIL]) so the
script runs on any terminal encoding without decoration loss.
Co-authored-by: Dhivya-Bharathy <[email protected]>
Addresses CodeRabbit nitpick: add praisonai.yml / legacy praison.yml
discovery tests and a precedence test asserting canonical praisonai.yaml
wins over legacy praison.yaml when both are present.
Co-authored-by: Mervin Praison <[email protected]>
The praisonai-code resolver only searched for `praison.yaml` at the
project root, which is inconsistent with the agents SDK loader
(`praisonaiagents/config/loader.py`) that uses the canonical
`praisonai.yaml`. Add `praisonai.yaml`/`praisonai.yml` as the primary
project-root names while retaining `praison.yaml`/`praison.yml` for
backward compatibility, and update the docstring reference. Adds
regression tests covering both the canonical and legacy names.
Co-authored-by: Leebana <[email protected]>
CapabilityValidator cached the MCP server snapshot once, so servers that
connected after the first validation stayed invisible under STRICT
enforcement. Read the process-level registry live each call (cheap
set-copy under lock); tool cache is unchanged. (#3307)
Co-authored-by: Mervin Praison <[email protected]>
Gap 1: port loop-task pre-expansion from workflow() into aworkflow() so
async workflows with a CSV-driven loop start task expand per-row instead
of running once.
Gap 2: guard the per-turn _turn_tools_used buffer with the same
AsyncSafeState lock that protects chat_history, routing all sites through
_reset/_record/_drain helpers so concurrent chat()/achat() turns on one
Agent no longer corrupt hook/self-improve tool data. Backward-compatible
_turn_tools_used property retained.
Gap 3: track namespaced MCP server names in a process-level registry
(MCP.list_active_server_names(), populated in with_tool_prefix) and read
it from CapabilityValidator._get_available_servers so MCP-server-gated
skills can pass STRICT validation instead of always failing closed.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
parallel_handoffs runs children via asyncio.gather, which copies the
context per task. A copied ContextVar binding still references the same
parent list object, so when parallel_handoffs runs inside a non-empty
parent handoff chain, sibling tasks mutated a shared list and corrupted
cycle/depth tracking. Rebind each task's chain to a fresh per-task copy
at _run_one entry so siblings are fully isolated.
Co-authored-by: Mervin Praison <[email protected]>
- memory_mixin: append per-instance uuid suffix to default session_id so
same-named agents can no longer collide and bleed chat history
- handoff: replace threading.local() with contextvars.ContextVar so handoff
chain/depth is isolated per asyncio.Task under parallel_handoffs
- hooks/runner: add HookRunner.execute_async alias so async retry-with-backoff
no longer crashes with AttributeError
Co-authored-by: MervinPraison <[email protected]>
Address reviewer-flagged concurrency gaps in the scheduler + template cache:
- TemplateCache locks are now process-wide (class-level, keyed by path) so two
independent instances over the same dir coordinate; get() reads under the
per-key lock so it never observes the intermediate two-rename window; put()/
invalidate() take root+key locks and clear() takes the root lock, so a
concurrent clear() can no longer rmtree a half-written entry. put() stages
into a reserved .staging subdir (same fs, atomic os.replace) that clear()
skips, eliminating the put-vs-clear FileNotFoundError.
- AsyncAgentScheduler.start() no longer reports a successful start (and no
longer spins up a background task) when the immediate run trips the budget
brake (e.g. max_cost=0), matching the actually-stopped state.
Verified: 4 writer/clearer + 2 reader concurrency smoke test -> 0 races;
zero-budget start returns False with no task; 335 scheduler+template tests pass.
Co-authored-by: Mervin Praison <[email protected]>
- Async scheduler now honours the intentional-silence marker on delivery
(shared _should_suppress_delivery on _BaseAgentScheduler); removes the
duplicate budget guard, replacing both with a single _budget_exceeded()
helper that treats max_cost=0 as a real zero budget.
- TemplateCache.put()/invalidate() now stage into a sibling temp dir and
atomically os.replace() under a per-key lock, so concurrent readers never
observe a half-populated or mid-rmtree cache entry (multi-agent/interprocess).
- Scheduled agents.yaml tools now resolve through the canonical ToolResolver
(same path as `praisonai run`), instead of dropping everything but a
hardcoded search_tool — keeping CLI/YAML/Python behaviour identical.
Co-authored-by: MervinPraison <[email protected]>
- agents.py: _build_execution_context gains skip_memory_init; aexecute_task
passes True so a failed initialize_memory_async() no longer falls through
to the synchronous initialize_memory() on the event-loop thread.
- execution_mixin.py: reset app.openapi_schema after registering a shared-port
route so later launch() calls appear in /openapi.json and /docs.
Co-authored-by: Mervin Praison <[email protected]>
- Agent.launch(): register every path (not only first per port) and move the
keep-alive loop outside _server_lock so a second agent on a shared port is
no longer silently dropped and the process-wide lock isn't held forever.
- aexecute_task(): initialize memory via initialize_memory_async() to avoid
blocking the shared event loop on synchronous Memory() construction.
- MongoDBMemoryAdapter: factor embedding logic into shared _store/_search
helpers so short-term memory also gets/uses embeddings when
use_vector_search=True, matching the long-term tier.
Co-authored-by: MervinPraison <[email protected]>
These modules log exclusively via get_logger and never reference the
logging. namespace; the standalone import logging is dead code left over
from the get_logger migration. Removed it only where logging. is never
referenced (111 files); files that genuinely use logging. are untouched.
Co-authored-by: MervinPraison <[email protected]>
Delete two unreachable modules under context/fast/ that are never
imported, exported, or referenced anywhere in the SDK, tests, examples,
or docs:
- indexer/file_watcher.py (FileWatcher, IncrementalIndexer, ...)
- search_strategy.py (SearchStrategy, SearchState, SearchPhase)
Grep confirms only the definition sites matched; no importers exist.
Live FastContext path (fast_context, search_backends, parallel_executor,
indexer/file_indexer, symbol_indexer) is unchanged. No __init__.py edits
needed since neither module is exported.
Co-authored-by: Mervin Praison <[email protected]>
The registry.py copy of get_available_integrations() was unreferenced dead
code duplicating the canonical base.py implementation. The public symbol is
exported from integrations/__init__.py and lazily resolved via
_unified_registry.py, which binds to the base.py version. No importer, no
__all__ entry, and no internal caller referenced the registry.py copy.
Co-authored-by: MervinPraison <[email protected]>
Address three P1 review findings on the prompt-cache-stability contract:
- Wire GatewayMetrics into per-bot sessions via a new _stamp_metrics splice
(mirrors _stamp_admission_gate/_stamp_identity_resolver), called from both
start_channels and hot-reload, so prompt_cache_invalidations_total actually
increments in production instead of staying zero.
- Clear _prefix_sig in every session-clear path (_clear_session_data,
reap_stale, reset_all) so a reopened session establishes a fresh baseline
instead of emitting a false PROMPT_PREFIX_INVALIDATED against the old one.
- Fingerprint the full provider-visible tool schema (name + description +
parameters for dict tools, name + docstring for callables) instead of only
tool names, so a same-name schema edit is detected. Best-effort; never raises.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Core (praisonaiagents): new advisory HookEvent.PROMPT_PREFIX_INVALIDATED
and a pure prompt_prefix_signature(agent) that fingerprints only the
cache-relevant prefix (model + sorted tool names + system-prompt fp),
excluding volatile per-turn data. Kept out of agent.py to avoid bloat.
Wrapper/bot: BotSessionManager computes the signature after its per-turn
tool/model swaps, meters drift via an optional prompt_cache_invalidations_total
GatewayMetrics counter, and fires the advisory hook so silent provider
prompt-cache misses on long-lived conversations become auditable.
Co-authored-by: MervinPraison <[email protected]>
When team.astart() raises during a YAML/AgentTeam `--output stream-json`
run, the adapter now emits a terminal run.error event (best-effort,
without masking the original exception) before detaching the bridge,
matching the single-agent path's contract so consumers can distinguish
a failed run from an incomplete/still-running one. Fixes greptile P1.
Co-authored-by: Mervin Praison <[email protected]>
AgentTeam now exposes a lazy aggregate stream_emitter that fans in member
agents' StreamEventEmitter events, tagging each with the emitting agent's
agent_id. The PraisonAI adapter attaches the CLI stream-json bridge to this
team emitter around team.astart(), so `--output stream-json` on a YAML/team
run emits the same per-agent, per-step NDJSON stream as single-agent runs.
Both paths are zero-overhead no-ops outside structured output mode.
Co-authored-by: MervinPraison <[email protected]>
The event-loop liveness watchdog flags were only registered on the legacy
argparse parser in cli/features/gateway.py, which the real
`praisonai gateway start` Typer entrypoint (cli/commands/gateway.py) never
uses — so `--watchdog` / `--watchdog-timeout` were rejected at the primary
opt-in surface. Add both options to the Typer command and forward them to
GatewayHandler.start using the same None-means-fall-back-to-YAML convention
as the other store_true flags. `restart` already replays them via the
persisted start-flags. Adds 3 CLI-surface tests.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-Authored-By: Claude <[email protected]>
Arm the existing core LoopWatchdog (#3385) around the gateway serving loop
so a frozen event loop dumps all-thread stacks and hard-exits with the
restart exit code, letting systemd/launchd/Docker relaunch the process.
Opt-in via gateway.watchdog YAML block and --watchdog/--watchdog-timeout
CLI flags; zero cost when disabled. No systemd unit change needed since it
reuses GATEWAY_RESTART_EXIT_CODE (75).
Co-authored-by: MervinPraison <[email protected]>
- Make add_message/_modify_session_locked run the whole read-modify-write
inside a single BEGIN IMMEDIATE transaction so concurrent gateway
processes cannot lose appends (the process-local RLock alone did not
serialize across processes). Fixes Greptile P1 lost-update.
- Import legacy per-session JSON transcripts once when the SQLite store
first opens beside them, so upgrading to the sqlite default preserves
durable/resumable history. Fixes Greptile P1 legacy-invisibility.
- Wire the YAML session.store key through MultiChannelGatewayConfig.from_dict
so store: file|sqlite is actually honoured.
- Add concurrent-writer and legacy-migration tests.
Co-authored-by: Mervin Praison <[email protected]>
Addresses two P1 review findings on the RunOutcome terminal-outcome contract:
- Nested operation timeouts no longer misreported as run-budget hard_timeout.
RunOutcome.from_exception no longer promotes a bare asyncio.TimeoutError to
hard_timeout; the run-level budget is now the sole authoritative source of
hard_timeout, enforced explicitly in _astart_with_outcome via a task+wait so
only our own budget expiry maps to hard_timeout (inner TimeoutErrors -> failed).
- External asyncio.CancelledError is re-raised instead of being swallowed into a
benign RunOutcome, so cooperative cancellation / host shutdown is honoured.
Updates tests accordingly and adds coverage for nested-timeout->failed and
external-cancellation-propagates.
Co-authored-by: Mervin Praison <[email protected]>
Implement SqliteTranscriptStore(DefaultSessionStore) storing session
transcripts as one row per session in a WAL SQLite DB (concurrent readers,
transactional single-row writes, indexed lookups) instead of per-session JSON
files under a cross-process FileLock. It overrides only the persistence
primitives, inheriting all retention/compaction, message API, search scoring,
bookends and lineage-dedup logic unchanged.
Directory scans (list/search/gateway routing) are replaced with indexed
SELECTs. The gateway now defaults to this store when persistence is enabled,
selectable via a new `session.store` config key (`sqlite` | `file`).
Co-authored-by: MervinPraison <[email protected]>
Adds a small, closed RunOutcome result type in core plus an opt-in
return_outcome=True on run()/astart() so long-running hosts (gateways/bots)
can decide delivery/retry/DLQ from one field instead of inferring the
terminal state from exception identity. Distinguishes
completed|hard_timeout|cancelled|aborted|failed. String return unchanged.
Co-authored-by: MervinPraison <[email protected]>
Core save/restore_session_state only persist team._state, not per-agent
chat_history, so resumed/forked YAML team runs did not actually continue
the prior conversation (Greptile P1). Add wrapper-only capture/rehydrate
helpers that stash each agent's chat_history into team state on save and
re-inject it on restore — parity with the single-agent path, no core
change and no new Agent/AgentTeam params.
Also replace the source-text arun test with a behavioral call-order test
and add roundtrip/no-duplicate coverage for the chat-history helpers.
Co-authored-by: Mervin Praison <[email protected]>
Route YAML/team runs through the same --continue/--session/--fork/--no-save
continuity the single-agent prompt path uses, via existing core APIs.
- praisonai_adapter.arun(): resolve resume_session/auto_save from cli_config,
force-enable shared memory when a session is active, restore_session_state
before astart() and save_session_state after (save never fails a run).
- praison_ai._extract_cli_config_for_yaml(): thread resume_session/auto_save
into cli_config for `run agents.yaml`.
Wrapper-only; no new params/deps/core changes. Adds regression tests.
Co-authored-by: MervinPraison <[email protected]>
Address final-review P1s on #3401:
- Composite readers (AutoReader/DirectoryReader/GlobReader) now idempotently
wire the default readers into the core registry on first load(), so they no
longer silently return [] when register_default_adapters() was never called.
Keeps imports side-effect free (wrapper does heavy wiring at call time).
- _ensure_sibling() guards importlib.util.find_spec against ImportError/
ValueError from a discoverable-but-broken installed sibling, falling back to
the monorepo checkout instead of crashing.
Co-authored-by: Mervin Praison <[email protected]>
- Remove import-time auto-registration in adapters/{retrievers,rerankers,
readers}.py so importing them no longer mutates core-SDK singletons;
add idempotent, thread-safe register_default_adapters() single edge
(mirrors vector_stores.py policy).
- Make aretrieve()/arerank() genuinely async via asyncio.to_thread so the
blocking provider call no longer freezes the caller's event loop.
- Collapse the six copy-pasted ensure_praisonai_* functions in
_bootstrap.py into one _ensure_sibling() helper + table, fixing the
sys.path double-insert race with a lock.
Co-authored-by: MervinPraison <[email protected]>
Update _load_project_config docstring to reflect that home is now
excluded from project config discovery, and add two regression tests
covering the home-directory walk-up boundary.
Co-authored-by: Mervin Praison <[email protected]>
Address reviewer P1s on MTP fast-inference PR:
- export gguf now produces a LOCAL .gguf (needed by serve/--mtp-draft) and
only additionally pushes to the Hub when --hf is given (was Hub-only).
- find_llama_binary no longer returns a differently-named executable when
LLAMA_CPP_BIN points at one binary and a sibling is requested; falls through
to PATH / raises instead of launching e.g. llama-cli with server flags.
- Ollama disk preflight only enforces the 1.5x requirement when the source
size is known; skips (no false-positive block) for Hub-backed FROM.
Adds 6 tests (binary-lookup mismatch cases, gguf local/push dispatch,
unknown-source disk skip); full praisonai-train unit suite 118 passed.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Mervin Praison <[email protected]>
Remove three module-level helpers that were never referenced anywhere in
the monorepo and were not part of the public API (no __all__, absent from
config/__init__.py and the top-level lazy-import map):
- parse_url_to_config
- is_numeric_string
- make_array_error
All exported/used helpers remain untouched.
Co-authored-by: MervinPraison <[email protected]>
Move the module-level `from pathlib import Path` into each
`ensure_praisonai_*` monorepo-dev fallback branch. Path is only ever
referenced after the `import praisonai_<pkg>` early-return fails, so the
installed-wheel hot path no longer pays pathlib's ~8.7ms cold-import cost.
Behaviour is byte-for-byte identical.
Co-authored-by: MervinPraison <[email protected]>
Addresses two correctness gaps in the crash-recovery labelling (PR #3388):
- CodeRabbit: hand recovery_annotator its own fresh payload copy and only
adopt a dict result, so a mutate-then-raise no longer leaks a half-labelled
payload; validate non-dict returns.
- Greptile P1: keep a crash-recovered entry in the 'recovered' state on a
transient re-send failure (mark_failed keep_recovered) so the duplicate
label survives the retry instead of being demoted to 'failed' and dropped.
Adds 3 regression tests (mutation-then-raise fallback, non-dict return,
sticky-recovered retry). All 69 outbox/delivery/reconcile tests pass.
Co-authored-by: Mervin Praison <[email protected]>
- disarm racing an in-flight wedge no longer triggers os._exit (re-check
_stop before the destructive exit) so a deliberate disarm never causes a
supervisor restart (Greptile P1)
- reject NaN/inf probe_interval_s to avoid a dead watchdog worker or a
hung shutdown via Event.wait/Thread.join (Greptile P2)
- add tests for both cases
Co-authored-by: Mervin Praison <[email protected]>
Add an optional recovery_annotator hook to OutboundQueue.drain, applied only
on the unreconciled 'recovered' branch, so a mid-send-crash message re-sent
at-least-once can be visibly marked as a possible duplicate instead of being
re-delivered silently. DurableDelivery gains a backward-compatible
mark_recovered flag (off by default) that prefixes recovered string replies
via _annotate_recovered_payload, threaded through setup_durable_delivery.
Co-authored-by: MervinPraison <[email protected]>
Add a pure-stdlib, fail-open LoopWatchdog primitive to core
(praisonaiagents.gateway) that runs on a dedicated OS thread, probes the
asyncio loop via call_soon_threadsafe, and after N missed probes dumps
all-thread stacks (faulthandler) and hands the process back to the
supervisor via os._exit(EX_TEMPFAIL). Opt-in and fail-open by design.
Co-authored-by: MervinPraison <[email protected]>
Passive-recorded group messages now land on the same shared per_chat
group key that a subsequent addressed turn reads from, so under
session_scope="per_chat" the bot can actually see the preceding
conversation (Greptile P1 / CodeRabbit Major). record_passive() threads
chat_id/thread_id/account routing and appends directly under a per-key
threading lock instead of the cross-thread mirror bridge, which would
dead-lock when called inline on the inbound handler's own event loop.
Strengthened the observe test to assert routing is threaded and added a
real BotSessionManager per_chat persistence test proving the passive
entry is visible under the group key and does not leak into the sender's
per_user history.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Address reviewer P1s on the restart-continuation path:
- boot scan requested an explicit large limit so interrupted turns beyond
the store's 50-session default window are no longer silently skipped
- channel_target now falls back to the persisted client_id when it encodes
a channel:target origin, so the field is a live consumer of existing
state rather than dead code for sessions the setter never touched
Adds tests for client_id-derived origin and >50-session scan coverage.
Co-authored-by: Mervin Praison <[email protected]>
A malformed gateway.drain_timeout / gateway.reload_drain_timeout in a
hot-reload edit made _coerce_timeout() return None, which was assigned
unconditionally and silently cleared a previously-configured live drain
window. Distinguish malformed (keep live value via _KEEP sentinel) from
explicit disable (None/absent -> None). Update/extend tests accordingly.
Co-authored-by: Mervin Praison <[email protected]>
On boot, before serving traffic, scan persisted sessions for an in-flight
turn (is_executing / non-empty pending_inbox) lost to a restart. For
channel-originated sessions, deliver an exactly-once "interrupted — resuming"
notice via the existing durable delivery router (idempotency keyed on
(session_id, event_cursor)) and re-drive the turn when the agent is still
registered — independent of any client reconnect.
Reuses the existing durable session store + delivery router rather than
adding new core protocol machinery, keeping the change lightweight and
backward-compatible.
Co-authored-by: MervinPraison <[email protected]>
Add a core HOT_APPLIABLE_KEYS registry + SupportsHotReload protocol in
praisonaiagents/gateway/config.py declaring the closed set of config paths
safe to apply in place. The bot gateway now classifies those paths as HOT in
_build_reload_plan (unknown keys still fall back to a restart plan — fail-safe)
and implements apply_hot_reload to mutate live state (logging level, drain /
reload_drain timeouts) without restarting channels or agents. Applied paths are
already reflected in the existing reload status/health.
Co-authored-by: MervinPraison <[email protected]>
Under the observe policy, group messages that do not mention the bot are
recorded into the session transcript as passive user context (no agent run)
so the bot has memory of the conversation when it is next addressed.
Reuses the existing thread-safe mirror append path via a new
BotSessionManager.record_passive() instead of adding a new core enum /
classifier, keeping the surface area minimal.
Co-authored-by: MervinPraison <[email protected]>
- Reject path-separator/traversal agent names (validate_agent_name) so
writes stay inside .praisonai/agents/ (Greptile Security P1).
- Post-write validation now re-parses the exact file written instead of a
precedence lookup, and warns when a higher-precedence definition shadows
the name so the reported `run --agent` step is never misleading (P1).
- Add tests for traversal rejection and global/project shadow warning.
Co-authored-by: Mervin Praison <[email protected]>
Add a `create` command beside `list`/`show` on the agent Typer app that
authors a valid, permission-scoped .praisonai/agents/<name>.md from a one-line
description. Interactive prompts plus a scriptable
--describe/--model/--permission/--global/--yes form. Permission presets reuse
the existing `mode` shorthands (MODE_RULES) so authored agents round-trip
losslessly through CustomDefinitionsDiscovery and inherit the runtime's
permission grammar. System-prompt drafting reuses the plain Agent path proven
by `init --generate`, degrading to an editable stub on any failure.
Co-authored-by: MervinPraison <[email protected]>
- _shim.py: skip None placeholders in sys.modules when pre-aliasing the
moved subtree so an unloaded optional module can't poison the old dotted
name (import old.sub -> "None in sys.modules"); _AliasFinder still resolves
it on demand.
- codex_cli.py: use an _UNSET sentinel in _build_command so an explicit
output_file=None disables the instance default and parses stdout, instead
of silently falling back to self.output_file (execute_with_schema).
Co-authored-by: Mervin Praison <[email protected]>
Restores eager subtree pre-registration in _shim._register_submodules. The
lazy-only variant broke module identity: a combined `from praisonai.mcp_server.cli
import X` imported the parent shim, then resolved `.cli` through _AliasFinder,
whose nested import_module re-entered mid-import under the import lock and
double-loaded the moved file — producing duplicate classes and breaking the
15 mcp/doctor CI tests that patch the shim path.
Also make the forced-format integration helpers (gemini stream/execute_with_stats,
codex stream, cursor stream) pop caller-supplied override keys before threading
the forced value, matching claude_code.py, so callers can't trigger a duplicate-
keyword TypeError (greptile P2).
Co-authored-by: Mervin Praison <[email protected]>
Address 4 P1 review findings in eval/trials.py:
- Isolation: rebind clone.chat_history to a fresh list and give the clone its
own system-prompt cache so per-attempt state resets never mutate/evict the
caller's live agent state.
- Scorer safety: a raising EvalCase.verify (and any scorer path) is now
recorded as a failed TrialScore instead of propagating through gather and
aborting the whole report.
- Timeout: run attempts on a dedicated ThreadPoolExecutor shut down with
wait=False so a wedged agent call cannot block run_trials past the timeout;
documented that a leaked worker thread cannot be force-killed.
- Duplicate case names: merge/extend attempts (with re-numbered indices)
instead of overwriting, so no attempts are silently discarded.
Add 4 regression tests covering each fix.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Address three P1 issues in the trials→SFT exporter:
- --all (only_passed=False) now retains unscored attempts instead of
dropping them in _classify.
- Alpaca conversion no longer drops the user prompt when a system message
is present; system→instruction, all user turns→input.
- Score-only pass detection compares against the report's pass_threshold/
threshold/min_score when present, falling back to score>0 only otherwise.
Co-authored-by: Mervin Praison <[email protected]>
- session/hierarchy.py: mirror base loader contract so a transient OSError on
an existing file re-raises (instead of swallowing IOError and returning an
empty session), letting _modify_session_locked abort the write and preserve
history. Malformed JSON still starts fresh.
- approval/registry.py + agent/tool_execution.py: add per-call `force` to
approve_sync/approve_async so a PermissionManager `ask` rule gates only the
current call without mutating shared registry state, fixing the leak where an
unnamed agent's rule registered globally and gated other agents.
Co-authored-by: Mervin Praison <[email protected]>
Bridge verification to data generation: take a serialised trials report
(K scored attempts per case with captured trajectories), keep the passing
attempts via rejection sampling, and write them as a ShareGPT dataset the
existing trainer consumes unchanged. Adds export_trials() + ExportSummary,
provenance sidecar ({path}.meta.json), and a `from-trials` CLI command
beside generate/dedup/validate. Report is duck-typed over JSON (the contract
with the sibling core trials engine) so there's no hard dependency on unlanded
core code. Pure stdlib, additive, confined to the data namespace.
Co-authored-by: MervinPraison <[email protected]>
Gap 1: replace threading.local() handoff-chain storage with contextvars.ContextVar so concurrent asyncio handoffs no longer share one chain and corrupt each other's cycle/depth checks.
Gap 2: distinguish a transient OS read error from no-file/corrupt-JSON in the session store so a momentary read failure aborts the write (returns False) instead of silently overwriting real history with an empty session.
Gap 3: scope ApprovalRegistry tool-requirement state per agent so a per-agent PermissionManager ask rule no longer leaks an approval gate onto unrelated agents in the same process. Global registration (DEFAULT_DANGEROUS_TOOLS) is unaffected.
Co-authored-by: MervinPraison <[email protected]>
- Accept cached `huggingface-cli login` (get_token) in preflight, not just HF_TOKEN env (Greptile P1)
- Gate the hard CUDA check on train enabled so publish/export-only (train: false) validates on CPU (CodeRabbit Major)
- Resolve Ollama readiness endpoint from OLLAMA_HOST instead of hardcoded 127.0.0.1:11434 (Greptile P1)
- Translate `ollama create` failure into a clean RuntimeError and catch CalledProcessError in main()/export (CodeRabbit)
- Close serve_err TemporaryFile deterministically (CodeRabbit)
- Fix "Free up free space" typo (CodeRabbit)
- Guard non-mapping YAML config and require --model-dir to be a directory in export (CodeRabbit)
- Validate quantization_method in for_export too (CodeRabbit)
- Add tests for cached-login, train:false CPU, OLLAMA_HOST, and ollama-create failure
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Mervin Praison <[email protected]>
Make praisonai-train usable by a non-developer: replace raw tracebacks with
clean actionable errors, validate the config up front, and harden the
Ollama/GGUF/HF export paths against the exact failures hit in practice.
trainer.py:
- main() wraps construction + run(); ValueError/RuntimeError print as a single
"ERROR: <msg>" line and exit 1 (no traceback); KeyboardInterrupt exits cleanly.
- validate_config() preflight (fails fast BEFORE model/GPU load): no-CUDA GPU,
missing HF_TOKEN when publishing, <10GB free disk, invalid quantization_method.
- check_gpu() guarded so it no longer crashes raw on a CPU-only box.
- Unknown-key warning now collects all keys and suggests the closest known key
(difflib) in one clear block.
- Silent-behavior NOTES: num_samples head-N-before-shuffle, split_type
validation/test contamination into training, and the max_steps=2800 default.
- HF push (merged/gguf) translates HfHubHTTPError 401/403 into actionable
messages; rmtree guarded so a namespaced repo id ("user/model") is never
treated as a local path to delete.
- Template fixes: warn when no known chat template matches, drop the broken empty
DeepSeek stop tokens, and never emit an empty PARAMETER stop line.
- for_export() classmethod to build an export-only trainer (no dataset needed).
_ollama.py:
- create_and_push_ollama_model() accepts optional quantization (--quantize),
disk pre-check on the OLLAMA_MODELS volume, and translates push 401/403 into a
message pointing at ~/.ollama/id_ed25519.pub + ollama.com/settings/keys.
- ensure_ollama_running() waits 15s, probes GET /api/version, and surfaces serve
stderr in the timeout message.
cli/commands/train.py:
- New `export <ollama|gguf|hf>` command to publish an already-trained model
without re-running training.
tests: tests/unit/train/test_robustness.py (14 tests, all deps stubbed).
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Add build_openai_tool_dict to mcp_schema_utils.py and delegate from the
three transport tool classes (HTTPStreamMCPTool, SSEMCPTool,
WebSocketMCPTool). Output dicts, including the __praisonai_deferrable__
marker, are unchanged.
Co-authored-by: MervinPraison <[email protected]>
Replace flat len(text)//4 offline fallback in ContextCompactor.estimate_tokens
with the canonical estimate_tokens_heuristic from context.tokens, mirroring
context/aggregator.py. This removes duplicate logic and fixes under-counting
of non-ASCII (CJK/dense-script) text on the offline path.
Co-authored-by: MervinPraison <[email protected]>
Move wrapper-package discovery out of the Tier 2 ui.py CLI into the lazy
_wrapper_bridge via a new wrapper_package_path() helper, per ARCHITECTURE.md
§2 cross-tier boundary. Preserves preset resolution and the None fallback
(install hint) when the wrapper is absent.
Co-authored-by: Mervin Praison <[email protected]>
The UI loader was extracted to praisonai_code but resolved the bundled
default_app.py path via __file__-relative arithmetic anchored in
praisonai_code, which has no ui_* directories. The five bundled UI presets
ship in the praisonai wrapper package. Resolve the path against the installed
wrapper via importlib.util.find_spec("praisonai"), falling back to a clear
'pip install "praisonai[ui]"' hint when the wrapper is absent.
Co-authored-by: MervinPraison <[email protected]>
The executor context manager called shutdown(wait=True) on __exit__, which
re-blocked on a coroutine still hung past PRAISONAI_RUN_SYNC_TIMEOUT — defeating
the timeout (Greptile P1). Manage the pool explicitly and shutdown(wait=False)
in finally so a timed-out tool call returns immediately.
Co-authored-by: Mervin Praison <[email protected]>
The wrapper copy of agent_tools.py had drifted from the canonical
praisonai_code copy (missing the ACP cwd forwarding fix), and the two
resolved via different import spellings. Collapse the wrapper copy to a
thin re-export of the canonical praisonai_code implementation so both
import styles resolve to a single owner.
Reconcile the canonical module-local _run_sync bridge to keep the union
of both historical guarantees: running-loop safety (offload to a worker
thread) AND a timeout, without adding a wrapper dependency (C7 gate).
Co-authored-by: MervinPraison <[email protected]>
Address Greptile P1 review findings on PR #3358:
- _remove_worktree now returns a reason string when `git worktree remove`
fails (nonzero exit or exception) instead of silently returning None.
The caller keeps the tracking entry and records a preservation comment,
preventing orphaned worktrees/branches with dropped tracking.
- create_task persists the resolved top-level repo_path into task metadata
so the repo linkage that drove the worktree auto-upgrade is retained
between create and dispatch (an explicit metadata.repo_path still wins).
Adds tests for failed/exception removal tracking and repo_path persistence.
Co-authored-by: Mervin Praison <[email protected]>
Refinement 1: repo-linked tasks auto-upgrade workspace_kind to "worktree" at
create_task time (linkage-based, not content-inspecting). Explicit
workspace_kind and auto_worktree=false are respected. Derived branch
kanban/<task_id> is persisted for the dispatcher to consume.
Refinement 2: _remove_worktree is lossless by default — refuse to delete a
worktree that is dirty or has commits not in base; preserve it and record a
worktree_preserved comment. Removal with outstanding work is an explicit
force operation only.
Co-authored-by: Mervin Praison <[email protected]>
Addresses two P1 review issues on the workspace-binding change:
- Resolve the UnifiedSession once (before workspace binding + tool load) and
pass it into _bind_resume_workspace, eliminating a second independent
last-session lookup that could race a concurrent CLI process and bind tools
to a different directory than the loaded conversation.
- When a resumed session's saved workspace no longer exists, pin
PRAISONAI_WORKSPACE to cwd instead of leaving it unset, so a stray legacy
PRAISON_WORKSPACE cannot leak through the tool loader and contradict the
"using current directory" warning.
Adds regressions for cwd-pinning over the legacy var and for
provided-session-without-relookup; updates the existing fallback test.
Co-authored-by: Mervin Praison <[email protected]>
Bot/gateway file tools resolve against a per-session Workspace attached to
the agent after construction, but the FileSnapshot backing Agent.undo was
created rooted at os.getcwd() — so /undo tracked the wrong directory.
Add Agent.set_snapshot_root() (core, parameter-only) and call it from the
bot smart-defaults after attaching the workspace so change tracking follows
the tools. Deliberately minimal: the per-turn workspace swap (bug 3) and
policy worktrees (blocked on #3354's WorktreeService) are out of scope here.
Co-authored-by: MervinPraison <[email protected]>
The `praisonai code --workspace` flag was dead: it wrote PRAISONAI_WORKSPACE
but ToolConfig.from_env read PRAISON_WORKSPACE, and _load_interactive_tools
unconditionally overrode config.workspace with os.getcwd(). Fix the env-name
mismatch (honour both, prefer canonical PRAISONAI_) and resolve the workspace
as PRAISONAI_WORKSPACE -> PRAISON_WORKSPACE -> cwd instead of hardcoding cwd.
Also bind resumed sessions to their directory: --continue/--session now reads
back the persisted UnifiedSession.workspace and roots the tools there, warning
and falling back to cwd when that directory is gone.
Scope kept minimal per AGENTS.md: no new WorktreeService — worktree isolation
already exists via core GitWorktreeAdapter (wired into `praisonai run`), so a
parallel wrapper service would duplicate it.
Co-authored-by: MervinPraison <[email protected]>
The gateway status command now passes the additive deep flag to
handler.status(); update the assertion to match the new backward-
compatible default.
Co-authored-by: Mervin Praison <[email protected]>
- Only attach GATEWAY_AUTH_TOKEN over loopback or HTTPS; never over remote
plaintext HTTP in preflight probes and version-skew check
- Slack @mention: use hook-returned content verbatim so an intentionally
emptied/redacted message is not silently restored to raw event text
- Inbound metrics: track whether a baseline pre-existed so the first check
against pre-existing traffic reports "baseline established" instead of a
false "no inbound"
Co-authored-by: Mervin Praison <[email protected]>
Extend gateway test/status with --check-runtime, --check-inbound, and
--check-duplicates; add sessions list/show, enriched /health, metrics
delta, doctor deep checks, and Slack @mention liveness fixes so operators
can prove live delivery and detect competing gateways.
Addresses the Greptile finding that reconnect() restarts the same bot
instance still holding the rejected token. On wake from the parked
credential state the supervisor now opportunistically calls an optional,
duck-typed refresh_credentials() hook so an out-of-band credential repair
(e.g. a rotated env var) driving a bare reconnect() self-heals without a
full restart. No-op for bots without the hook (env-var tokens are already
re-resolved by start()/hot-reload). Best-effort: a failing hook cannot
wedge supervision.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Address two P1 review findings on the gateway restart-replay change:
- Only persist the start-flags artefact AFTER startup validation passes
(import/config/agent-file), just before the gateway binds, so a failed or
rejected start on the same host:port no longer clobbers the running
gateway's saved posture.
- restart --drain-timeout now defaults to None; an omitted flag replays the
persisted drain window (and falls back to 10s only when none is persisted)
instead of silently forcing a fixed 10s and shortening production drains.
An explicit value still wins for both the OLD-process drain and the relaunch.
Adds 3 regression tests covering omitted/explicit drain replay and the
no-persisted-value fallback.
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Direct (non-service) `gateway restart` silently dropped the runtime flags
the process was started with (--openai-api, --reliability,
--max-concurrent-runs, ...), reverting production settings to defaults.
`start` now persists the non-None runtime flags to
~/.praisonai/gateway.start.<host>.<port>.json (keyed by bind host:port,
matching the PID lock), and `restart` loads and replays them so the
relaunch faithfully reproduces the running gateway. Explicit restart flags
(config / agents / drain-timeout) still win over persisted values.
Co-authored-by: MervinPraison <[email protected]>
Classify runtime 401/403 (and platform text equivalents like invalid_auth/
token_revoked) as a distinct CREDENTIAL_UNAVAILABLE outcome instead of a
generic FAILED. On a runtime credential rejection the supervisor now parks in a
named, redacted degraded state (reusing the boot-time "credential unavailable"
surface from #3159 in health()), stops hammering the invalid token, and
auto-recovers on reconnect/hot-reload without a full process restart.
Co-authored-by: MervinPraison <[email protected]>
Address two P1 review findings on praisonai init --generate:
- Streaming stringified: _generate_agents_md used agent.start(), which
auto-enables streaming in a TTY and returns a generator whose repr was
written to AGENTS.md. Switch to agent.run() (always silent, returns str).
- Global mode wrote ~/AGENTS.md: with --global, base.parent is $HOME so the
agent scanned home and wrote home-tailored rules outside the repo. Resolve
the AGENTS.md target from git root / cwd independently of --global.
Add tests: --global still writes AGENTS.md to the repo root (not home), and
_generate_agents_md calls run() (not start()) returning the string body.
Co-authored-by: Mervin Praison <[email protected]>
Addresses the two Greptile P1 findings on #3346 so the non-zero-on-failure
contract holds across every reachable run path:
- _run_from_file: add `except typer.Exit: raise` so the deliberate failure
exit is not recaught by the broad handler (fixes duplicate reporting).
- _try_attach_runtime: classify the warm-runtime result and report failure so
an empty result exits non-zero instead of silently succeeding.
- _run_prompt_profiled / _run_from_file_profiled: apply the same failure
contract after the profiling report so profiled runs honour it too.
Adds a regression test for the warm-runtime attach path.
Co-authored-by: Mervin Praison <[email protected]>
Adds an opt-in `--generate` flag to `praisonai init` that runs a short,
read-only analysis agent (reusing the existing Agent runtime) to produce a
concise, repository-tailored AGENTS.md at the repo root. Feeds the agent a
cheap pre-scan (top-level tree, detected manifests, README head) to bound cost.
Non-destructive: respects --force, never overwrites an existing AGENTS.md, and
degrades gracefully to the static scaffold when no provider credential is
present or generation fails. The output lands where rules_manager already
discovers it on the next run.
Co-authored-by: Mervin Praison <[email protected]>
praisonai run reported success and exited 0 regardless of whether the
agent produced a result. Wire the existing run result (None/empty ==
failure) through the CLI: emit ok=<success> to the event bridge, a
machine-readable {"status": "failed"} object under --output json, an
actionable remediation, and raise typer.Exit(1) on failure — mirroring
the existing arg-error exit convention. Successful runs are unchanged.
Co-authored-by: Mervin Praison <[email protected]>
The running-loop fallback in _structured_completion/_run_coro_sync spawned a
bare threading.Thread, which does not inherit contextvars. run_sync() inside it
therefore resolved via _default_bridge() -> empty _bridge_var -> shared _BG,
bypassing an active scoped_bridge() and leaking the fallback onto the global
loop. Run the worker under contextvars.copy_context() so both paths resolve the
same AsyncBridge (scoped override, else shared default), preserving per-session
loop isolation.
Co-authored-by: Mervin Praison <[email protected]>
- auto.py: runner threads in _structured_completion and _run_coro_sync now
dispatch to the shared AsyncBridge via run_sync() instead of asyncio.run(),
reusing one process-wide loop/thread and per-loop connection pools.
- auto.py: _completion_impl preserves the original LiteLLM exception and
chains it into the OpenAI fallback failure (raise ... from) so users see
both provider tracebacks instead of only the masking OpenAI one.
- registry.py: _validate_adapter treats a **kwargs catch-all as satisfying
the protocol keywords and also validates arun, unblocking third-party
entry-point adapters that forward **kwargs.
Co-authored-by: MervinPraison <[email protected]>
Embed turn prerequisite errors into the JSON payload instead of printing a
trailing plain-text line, so --json consumers get a single valid document.
Also drop dead critical-tool branch in is_already_approved.
Co-authored-by: Mervin Praison <[email protected]>
1. Circuit breakers: register weakref.finalize at breaker creation so the
process-global registry entry is removed when the Agent is GC'd, closing
the CPython id-reuse window where a new agent could inherit a stale OPEN
breaker. No longer relies on close()/aclose() being called. Uses a
staticmethod callback so the finalizer does not keep the agent alive.
2. Global tool-registry fallback: gate the @tool registry lookup in
execute_tool() behind ToolConfig(allow_global_tools=True) (default False).
By default an agent is scoped strictly to its declared tools=[...] and
cannot execute an @tool-decorated callable it was never given. Plugin-host
style dynamic dispatch can opt in via tool_config.
3. Sync run_task(): re-raise on fail_on_callback_error / fail_on_memory_error,
mirroring arun_task() so the documented fail-fast flags behave identically
on the sync and async surfaces.
Co-authored-by: MervinPraison <[email protected]>
Extract shared probe/shell/turn logic to praisonai_bot.gateway.preflight,
add praisonai gateway test orchestrator, doctor bots shell/probe checks,
fix doctor --json single-document output, and per-channel turn probe gate.
Critical tools honour mark_approved via the approval registry, shell enable
syncs AutoApproveBackend to the registry, @mentions run routing handlers,
and gateway doctor gains an offline --turn probe for inbound simulation.
Addresses two Greptile P1 findings on the allow_shell opt-in:
1. Routed agents lose shell tools: _inject_routing_handler swapped in a raw
agent from self._agents, stripping execute_command applied to the default
channel clone. Re-apply enable_shell_tools to the routed agent (cloned once
per channel+agent so non-shell channels never gain the shell tool).
2. Manual approval retained auto-approval (security): with auto_approve_shell
false and no Slack approval channel, a pre-existing AutoApproveBackend was
left installed, silently auto-approving shell. Now fail-closed with a
deny-by-default backend that rejects shell commands.
Adds tests for both fail-closed approval paths.
Co-authored-by: Mervin Praison <[email protected]>
- Fix missing approval_webhook_url becoming the literal string "None"
which bypassed WebhookApproval's ValueError guard; now falls through
to platform/gateway approval instead of building a broken backend
- Add fail-closed approval_mode validator (channel|gateway|http|webhook)
so config typos are rejected at load time, matching other enum fields
- Add regression tests for webhook-mode with and without a URL
Co-authored-by: Mervin Praison <[email protected]>
Extend allow_shell to route human-in-the-loop approvals through platform
backends (Slack/Telegram/Discord) plus gateway, HTTP, and webhook modes,
with gateway fallback for channels without native wiring.
Address reviewer feedback on the CLI_BACKEND_EXECUTE hook path:
- Security: redact prompt/system argv values (redact_command) at the
payload serialization boundary and in the plugin bridge, so prompts and
system instructions do not leak into downstream log sinks. The live
in-memory command field is preserved for programmatic consumers.
- Observability: emit the hook on failure too (extracted
_emit_cli_backend_hook helper) so subprocess startup errors and timeouts
remain traceable via error=<message>, instead of only on success.
- Tests: cover redaction (serialization + plugin bridge) and failure-path
hook emission.
Co-authored-by: Mervin Praison <[email protected]>
Log subprocess command and confirm PraisonAI skips LLM HTTP when cli_backend delegates a turn.
Enable with PRAISONAI_CLI_BACKEND_DEBUG=1 or LOGLEVEL=DEBUG.
Gemini backend forwarded --resume on every turn including the first,
which would fail resuming a non-existent session. Gate on
CliSessionBinding.is_resume for parity with codex/grok/claude.
Co-authored-by: Mervin Praison <[email protected]>
Codex backend never forwarded the session id to `codex exec`, so
multi-turn conversations lost context (Greptile P1). Now forwards
`resume <session_id>` on resume turns. Gate both codex and grok
session forwarding on CliSessionBinding.is_resume so the first turn
does not attempt to resume a non-existent session.
Co-authored-by: Mervin Praison <[email protected]>
- Isolate ANTHROPIC_TOKEN/CLAUDE_CODE_OAUTH_TOKEN env in the expiring-token
test so the Keychain read-only path is deterministically exercised (was
leaking a real CI OAuth token and returning the wrong access token).
- Assert both anthropic-beta policy changes: fine-grained-tool-streaming is
present and the unsupported context-1m long-context beta stays absent
(per CodeRabbit review).
Co-authored-by: Mervin Praison <[email protected]>
PraisonAI read Keychain OAuth tokens but refreshed without persisting back,
rotating refresh tokens and breaking Claude CLI and other tools on the same
machine. Use read-only credential resolution, skip LLM auth refresh for
claude-code, fix invalid_request_error misclassification, and drop the
context-1m beta header unsupported on many subscriptions.
The async retry loop emitted RETRY events via the sync emit() path, so
consumers registered through the public add_async_callback() API passed
has_callbacks but never received the event. Add an async-aware
_aemit_retry_stream_event helper (using emit_async) and share event
construction via _build_retry_stream_event. Adds tests for the async-only
callback path and the no-callback no-op case.
Co-authored-by: Mervin Praison <[email protected]>
Add StreamEventType.RETRY emitted alongside the existing ON_RETRY hook (guarded by has_callbacks for zero-overhead) in both sync and async retry loops, carrying attempt/max_attempts/delay/reason in metadata. Map it to a canonical run.retry NDJSON event in the CLI stream-json bridge so consumers get a live 'retrying in Ns (attempt k/N)' signal. Non-JSON/silent modes stay silent.
Co-authored-by: Mervin Praison <[email protected]>
A TypeError/ValueError raised inside a successfully-bound tool (domain
validation) no longer receives a misleading required/optional parameter
hint. The hint is now gated on inspect.signature().bind() confirming the
failure is an argument-binding error, so runtime errors surface their
real message and the model fixes the value, not the parameter names.
Co-authored-by: Mervin Praison <[email protected]>
Adds a zero-overhead resilience layer to the core agent tool-dispatch path.
When a tool call cannot be resolved, the runtime now:
1. Self-repairs case/separator drift (e.g. WebSearch/web-search -> web_search)
against the agent's active tools and executes if a unique match exists.
2. Otherwise returns a model-readable error naming the nearest valid tool
(fuzzy) and listing the available tools so the model can self-correct.
3. On an argument-binding failure, echoes the tool's required/optional params.
No new public API or Agent params; stays on the existing dispatch path.
Co-authored-by: MervinPraison <[email protected]>
- Security: refuse non-localhost bind without --api-key/PRAISONAI_SERVE_API_KEY,
mirroring jobs/server.py; enforce the resolved key unconditionally.
- Performance: cache one AgentsGenerator per app via FastAPI lifespan (built at
startup, closed on shutdown) instead of rebuilding YAML parse + framework
resolution + a 32-worker pool per request; falls back to praisonai.arun if
caching fails.
- Correctness: /agents and /agents/{name} now run the same cached generator, so
identical YAML gets identical lowering (ToolResolver, tool_timeout, approval,
guardrails, retry). Removed the hand-rolled PraisonAgent registration that
silently dropped those safety fields.
Co-authored-by: Mervin Praison <[email protected]>
Address reviewer findings on PR #3321:
- Core neutralize_untrusted_text now also collapses U+2028/U+2029/U+0085,
which render as line breaks but bypassed the ASCII control filter.
- Bot _attribute() fallback (core helper unavailable / version skew) now
mirrors the sanitiser: collapses all newline-like separators, strips
control chars, and bounds length.
- Added tests for Unicode separators (core + bot) and the fallback path.
Co-authored-by: Mervin Praison <[email protected]>
Add a core, pure-stdlib helper neutralize_untrusted_text() in
praisonaiagents.session.context and apply it by default to the
third-party-controlled sender display name before it is interpolated into
the [{sender}] attribution prefix. Newlines/CR are collapsed, control chars
stripped and length is bounded, so a hostile name can no longer masquerade
as a fake system directive the model re-reads every turn. Well-behaved names
render byte-identically. On by default, no new config knobs.
Co-authored-by: Mervin Praison <[email protected]>
Addresses greptile P1: CapabilityValidator cached the first _get_available_servers()
snapshot, so a skill validated before its MCP server registered via with_tool_prefix()
stayed permanently UNAVAILABLE under STRICT even after the server connected. The MCP
registry read is a cheap set copy, so query it live and drop the dead _server_cache
field (issue #3307).
Co-authored-by: Mervin Praison <[email protected]>
The durable-reference encoding for long interactive reply/select values only
took effect when a shared store was explicitly passed in tests; every
production renderer/registry used the no-store default and fell back to the
unrecoverable hash. This shares one InMemoryCallbackPayloadStore between the
Telegram render side (render_presentation -> adapt_presentation) and the inbound
registry so long values round-trip losslessly past the 64-byte callback cap.
- create_registry(store=): thread an optional store into the InteractiveRegistry
- TelegramPresentationRenderer.render(callback_store=): pass store to adapt
- TelegramBot: construct one shared store, inject into registry + render
- add regression test asserting production render+dispatch round-trip
Co-authored-by: Mervin Praison <[email protected]>
- POST /agents/{agent_name} now dispatches to the requested registered agent
and returns 404 for an unknown name, instead of silently running the whole
YAML workflow (fixes named-agent regression flagged in review).
- Both routes build a lightweight per-request AgentsGenerator that borrows the
cached generator's shared adapter, tool-timeout pool and resolver while owning
its own cli_config, so concurrent requests overlap without a run-length lock.
Co-authored-by: Mervin Praison <[email protected]>
Addresses two P1 review findings on the tool self-repair path:
- Fold the bind-failure parameter schema into the error string so it survives
conversion to ToolExecutionError (which keeps only the message) and reaches
the model.
- Expand MCP instances into their contained tools via a shared
_iter_active_named_tools() helper so MCP tool names participate in
case/separator repair and appear in the corrective inventory instead of an
empty/opaque container.
Adds 3 tests (public-path param hint, MCP inventory, MCP name repair).
Co-authored-by: Mervin Praison <[email protected]>
Address reviewer feedback on the prompt-injection defence:
- Greptile P1 (security): the bot's _attribute() fallback (taken when the
core helper import fails on an older praisonaiagents still allowed by the
>=1.6.152 range) only replaced CR/LF, leaking control chars and oversized
display names into every shared-chat prompt. It now mirrors the core
helper: collapse newlines, strip control chars, collapse whitespace and
length-bound to 240 — byte-identical to neutralize_untrusted_text.
- Greptile P2: neutralize_untrusted_text with max_chars<=3 returned the
3-char "..." string, exceeding the advertised bound. Small bounds now
truncate hard so len(out) <= max_chars always holds.
- Tests: add small-bounds regression (core) and a fallback-path hostile-name
regression that forces the helper import to fail (bot).
Co-authored-by: Mervin Praison <[email protected]>
An unquoted bare prompt (praisonai build a weather agent) arrives as
multiple argv tokens, but the modern `run` command takes a single
positional target. Join the flag-free tokens into one argument so the
whole prompt reaches `run` intact instead of Typer rejecting the extra
positionals. Addresses Greptile P1 (multi-token prompt).
Also adds a regression test pinning that flagless operational commands
(serve/call/realtime/debug/lsp/diag) stay Typer commands and are never
misrouted to `run` as prompts (Greptile P1 #2 was a false positive).
🤖 Generated with [Claude Code](https://claude.ai/code)
Co-authored-by: Mervin Praison <[email protected]>
Interactive reply/select values that exceed a channel's callback byte-cap
(e.g. Telegram's 64-byte limit) were hashed with no way to recover the
original value, so long option values (URLs, file paths, free-text) made
menus silently non-functional. This generalises the durable-reference
pattern already used by approvals to ordinary interactive callbacks.
- Add CallbackPayloadStoreProtocol (peer of ApprovalStoreProtocol) plus a
bounded, zero-dependency InMemoryCallbackPayloadStore default in core.
- Encoders persist an overflowing value under a short reference and emit
reply:@<ref> / select:<action_id>:@<ref>; inline values are unchanged.
- InteractiveRegistry(store=...) resolves @<ref> back to the exact value on
dispatch, preserving the select action_id prefix, and fails closed on an
unknown/expired reference. Without a store the prior hash behaviour is kept.
Additive and backward compatible: adapt_presentation gains an optional
callback_store kwarg; registry gains an optional store arg.
Co-authored-by: MervinPraison <[email protected]>
Gap 1: Port sync workflow()'s loop-task pre-expansion into aworkflow() so
async CSV-driven loop start tasks run per-row instead of once.
Gap 2: Guard the per-turn tool buffer (_turn_tools_used) with a DualLock via
_reset_turn_tools/_record_turn_tool/_drain_turn_tools helpers, matching the
existing chat_history protection, so concurrent chat()/achat() turns on one
Agent no longer corrupt hook/self-improvement data.
Gap 3: Track namespaced MCP server names in a process-level registry and let
the skills CapabilityValidator discover them, so MCP-server-gated skills can
pass STRICT validation instead of always failing closed.
Co-authored-by: Mervin Praison <[email protected]>
- Refuse non-localhost bind without --api-key/PRAISONAI_SERVE_API_KEY,
mirroring jobs/server.py policy (POST /agents can run YAML-defined tools).
- Cache one AgentsGenerator per app via FastAPI lifespan instead of rebuilding
it (YAML re-parse, registry re-resolve, fresh 32-worker pool) per request;
serialise the shared cli_config with an asyncio.Lock and close() on shutdown.
- Converge /agents and /agents/{agent_name} on the same generator path so both
apply identical YAML lowering (ToolResolver, tool_timeout, approval,
guardrails, retry) instead of the safety-stripped hand-rolled PraisonAgent.
Co-authored-by: Mervin Praison <[email protected]>
Add StreamEventType.RETRY and emit it alongside the existing ON_RETRY hook in both the sync and async retry loops (guarded by has_callbacks, so it stays zero-overhead when no consumer is attached). The event carries attempt, max_attempts, delay and reason in metadata.
The CLI stream-event bridge maps it to a canonical run.retry NDJSON event so consumers can render a live 'retrying in Ns (attempt k/N)' status instead of a silent, hung-looking terminal. Non-JSON/silent modes stay silent.
Co-authored-by: MervinPraison <[email protected]>
When the LLM emits an unresolvable tool call, the runtime now:
- attempts a deterministic self-repair by normalising case/separator drift
(e.g. 'WebSearch' -> 'web_search') against the agent's active tools;
- otherwise returns a corrective, model-readable error naming the nearest
valid tool and listing the currently available tools;
- on argument-bind failure, echoes the tool's required/optional parameters.
Reuses existing dispatch path; no new public API or Agent params.
Co-authored-by: Mervin Praison <[email protected]>
Add a pure-stdlib core helper neutralize_untrusted_text() in
praisonaiagents.session.context and apply it by default to the sender
display name in the bot's _attribute() prefix. Collapsing newlines/control
chars and bounding length stops a hostile group display name / title from
masquerading as a fake heading or system directive in the per-turn prompt,
while well-behaved names render byte-identically. Safe-by-default; no new
config knobs.
Co-authored-by: Mervin Praison <[email protected]>
A bare free-text prompt (`praisonai "do something"`) now forwards to the
same modern `run` path as `praisonai run`, inheriting session continuity,
--output modes, the credential gate and permissions. `.yaml` workflows and
flag-bearing legacy invocations remain on the legacy dispatcher.
Co-authored-by: MervinPraison <[email protected]>
The maintainer's review bot flagged these but couldn't push to a fork, so
applying directly:
- Raise on a configured-but-unknown TENKI_WORKSPACE_ID/PROJECT_ID instead of
silently using the first workspace/project (wrong-workspace billing).
- shlex.quote every pip/npm spec (command-injection hardening).
- Honour a non-default ComputeConfig.image, not just metadata["tenki_image"].
- Respect ComputeConfig.networking (restricted -> allow_outbound=False).
- Fail provisioning and tear down the sandbox when package install fails
(no false RUNNING / leaked sandbox).
- Terminate before dropping the handle in shutdown, so a failed terminate keeps
the sandbox tracked for retry instead of silently leaking it.
Add Tenki Cloud (https://tenki.cloud) as a compute provider for managed
agents, alongside E2B, Daytona, Modal, Fly.io, Docker and local.
- TenkiCompute implements ComputeProviderProtocol (provision / execute /
shutdown / get_status / upload_file / download_file / list_instances),
running tools in disposable Tenki microVMs. Sync SDK wrapped via
run_in_executor, matching the existing providers.
- Registered as "tenki" in the compute barrel, the _resolve_compute factory,
and the compute-provider hint sets.
- Uses only stable Tenki features (exec + file I/O). Default stock image
installs pip packages on demand; set metadata["tenki_image"] for a custom
image. Auto-resolves workspace/project from the API key.
- Enabled via TENKI_API_KEY; optional `tenki` extra (tenki-sandbox).
- Unit + live (skipped-by-default) tests mirroring the E2B/Daytona suites.
Document Evolink's OpenAI-compatible endpoint in the sample environment and add a provider example that uses the existing PraisonAI base_url/api_key configuration path. Cover the config wiring with an offline unit test so the integration stays regression-tested without live API calls.
2026-06-23 19:12:11 +08:00
1725 changed files with 223013 additions and 29279 deletions
<p>praisonai-mcp is Tier 2e — the heavy MCP server host: full <code>MCPServer</code>, tool/resource/prompt registries, recipe bridge, HTTP-stream auth, and MCP client config management. Depends only on <code>praisonaiagents</code>. v0.0.2. Protocol: MCP 2025-11-25.</p>
<figureclass="wp-block-table"><table><thead><tr><th>Registry</th><th>Commands</th><th>Gate</th></tr></thead><tbody><tr><td>MCP-resident Typer</td><td>list, add, remove, sync, test, serve, doctor</td><td><code>mcp_package_available()</code></td></tr><tr><td>MCPServerCLI host</td><td>serve, list-tools, list-resources, config-generate, tasks, auth</td><td>Direct via <code>praisonai-mcp <cmd></code></td></tr><tr><td>Code-resident light</td><td><code>serve mcp</code></td><td>Always available with code + agents</td></tr><tr><td>Wrapper-resident</td><td>dashboard, schedule, langfuse</td><td><code>wrapper_package_available()</code></td></tr></tbody></table></figure>
<!-- /wp:table -->
<!-- wp:paragraph -->
<p>Standalone <code>praisonai-code</code> hides <code>mcp</code> from <code>--help</code> when <code>praisonai-mcp</code> is not installed. Host commands like <code>praisonai-mcp serve</code> skip the <code>mcp</code> prefix; <code>praisonai mcp serve</code> goes through the Typer group.</p>
<p>Heavy MCP hosting needs only <code>praisonaiagents</code> + <code>praisonai-mcp</code>. Full capability registry (workflows, deploy, extended tools) activates when the wrapper is co-installed via <code>_wrapper_bridge</code>.</p>
<!-- /wp:paragraph -->
<!-- wp:heading -->
<h2class="wp-block-heading">Bridges (no PyPI cycles)</h2>
<p>Wrapper pins <code>praisonai-mcp>=X</code> after mcp is on PyPI. CI: <code>.github/workflows/pypi-release.yml</code>. Import gate: <code>scripts/check_c12_mcp_imports.sh</code>.</p>
<p>praisonai is Tier 3 — the integration wrapper that wires <code>praisonaiagents</code> + five Tier-2 packages (<code>praisonai-code</code>, <code>praisonai-bot</code>, <code>praisonai-train</code>, <code>praisonai-browser</code>, <code>praisonai-mcp</code>) into one install, with dashboard, framework adapters, jobs API, serve orchestration, and backward-compat shims. v4.6.150.</p>
<p>Each Tier-2 package is installable standalone with its own console script. The wrapper pins all of them and preserves every old import path via shims. Use the wrapper when you need several surfaces together — HTTP serve, dashboard, framework YAML, jobs/recipe — without managing tier pins yourself.</p>
<p>Protocols live in <code>praisonaiagents/frameworks/</code>; adapter implementations in wrapper <code>framework_adapters/</code>. Entry-point group: <code>praisonai.framework_adapters</code>.</p>
<figureclass="wp-block-table"><table><thead><tr><th>Package</th><th>Status</th><th>Choose when…</th><th>Standalone install (planned)</th></tr></thead><tbody><tr><td><code>praisonai-sandbox</code></td><td><strong>C13 preferred</strong> (execution goal)</td><td>Isolated agent code execution — Docker/E2B/Modal/Daytona/Sandlock</td><td><code>pip install praisonai-sandbox[docker]</code></td></tr><tr><td><code>praisonai-deploy</code></td><td><strong>C13 alt</strong> (deploy goal)</td><td>Ship <code>agents.yaml</code> to Docker/AWS/GCP/Azure</td><td><code>pip install praisonai-deploy</code></td></tr><tr><td><code>praisonai-replay</code></td><td>Conditional C14+</td><td>Deterministic replay from run ledger / traces</td><td>After product sign-off</td></tr><tr><td><code>praisonai-serve</code></td><td>Deferred C15</td><td>HTTP API hosting without full umbrella (~14k LOC)</td><td>With recipe/jobs decision</td></tr><tr><td><code>praisonai-recipe</code></td><td>Deferred</td><td>NL → agent YAML without jobs UI</td><td>Tied to jobs + serve</td></tr><tr><td><code>praisonai-jobs</code></td><td>Deferred</td><td>Async long-running agent jobs API</td><td>Extract with serve or stay wrapper</td></tr></tbody></table></figure>
<!-- /wp:table -->
<!-- wp:paragraph -->
<p>C13 decision rule: <strong>sandbox</strong> = where code runs; <strong>deploy</strong> = where the agent service lives. Ship one first after product sign-off.</p>
<figureclass="wp-block-table"><table><thead><tr><th>Criterion</th><th>Pass (browser/MCP)</th><th>Fail (example)</th></tr></thead><tbody><tr><td>Named user goal without full <code>praisonai</code></td><td><code>pip install praisonai-browser</code> → automate Chrome</td><td><code>pip install praisonai-persist</code> → ???</td></tr><tr><td>Coherent product boundary</td><td>One Typer group / one console script</td><td>Whole <code>cli/features/</code> orchestration layer</td></tr><tr><td>PyPI deps: <code>praisonaiagents</code> only</td><td>Tier-2 + lazy <code>_wrapper_bridge</code></td><td>Hard <code>import praisonai</code> at module level</td></tr><tr><td>Worth a separate install</td><td>User who never wants dashboard/serve/bots</td><td>Internal docs tooling</td></tr><tr><td>Extraction shape</td><td>C10 single PR (~3–11k LOC)</td><td>Mega-epic without product sign-off</td></tr></tbody></table></figure>
<!-- /wp:table -->
<!-- wp:heading -->
<h2class="wp-block-heading">When to use which tier</h2>
<!-- /wp:heading -->
<!-- wp:table -->
<figureclass="wp-block-table"><table><thead><tr><th>Scenario</th><th>Install</th></tr></thead><tbody><tr><td>Pure Python agents, minimal deps</td><td><code>pip install praisonaiagents</code></td></tr><tr><td>Terminal coding agent, CI, headless</td><td><code>pip install praisonai-code</code></td></tr><tr><td>Telegram/Discord gateway only</td><td><code>pip install "praisonai-bot[gateway,bot]"</code></td></tr><tr><td>Agent training (no GPU)</td><td><code>pip install praisonai-train</code></td></tr><tr><td>LLM fine-tuning (GPU)</td><td><code>pip install "praisonai-train[llm]"</code></td></tr><tr><td>MCP server for Cursor/Claude</td><td><code>pip install "praisonai-mcp[all]"</code></td></tr><tr><td>Browser automation (extension/CDP)</td><td><code>pip install "praisonai-browser[all]"</code></td></tr><tr><td>CrewAI/AutoGen YAML</td><td><code>pip install "praisonai[crewai]"</code></td></tr><tr><td>Full ops + channels + dashboard</td><td><code>pip install "praisonai[claw]"</code></td></tr><tr><td>Everything in one install</td><td><code>pip install praisonai</code></td></tr><tr><td>Library author / embedding</td><td><code>praisonaiagents</code> only</td></tr></tbody></table></figure>
@@ -269,7 +319,7 @@ function finalClaudeCompletedOnSha(comments, headPushedAt) {
}
constFINAL_CLAUDE_REVIEW_BODY=
'@claude You are the FINAL architecture reviewer. If the branch is under MervinPraison/PraisonAI (not a fork), you are able to make modifications to this branch and push directly. SCOPE: Focus ONLY on Python packages (praisonaiagents, praisonai). Do NOT modify praisonai-rust or praisonai-ts. Read ALL comments above from Gemini, Qodo, CodeRabbit, and Copilot carefully before responding.\n\n**Phase 1: Review per AGENTS.md**\n1. Protocol-driven: check heavy implementations vs core SDK\n2. Backward compatible: ensure zero feature regressions\n3. Performance: no hot-path regressions\n4. SDK value: review in depth whether the change genuinely adds value to the SDK — never add features for the sake of adding them. It must strengthen the SDK (simpler, more user-friendly, robust, world-class, secure). If it does not clearly add value, request changes or recommend rejecting/closing rather than merging scope creep\n5. Do not bloat the Agent class with additional params — only if absolutely required; we already support many params.\n6. Repo routing: agent-callable tools → PraisonAI-Tools; lifecycle plugins → PraisonAI-Plugins; optional sandbox backends → PraisonAI-Plugins (`praisonai.sandbox` entry point) — request changes if wrongly added to praisonaiagents/\n\n**Phase 2: FIX Valid Issues**\n7. For any VALID bugs or architectural flaws found by Gemini, CodeRabbit, Qodo, Copilot, or any other reviewer: implement the fix\n8. Also independently identify and fix any gaps or issues you find in the changed code — do not rely only on prior reviewer feedback\n9. Push all code fixes directly to THIS branch (do NOT create a new PR)\n10. Comment a summary of exact files modified and what you skipped\n\n**Phase 3: Final Verdict**\n11. If all issues are resolved, approve the PR / close the Issue\n12. If blocking issues remain, request changes / leave clear action items';
'@claude You are the FINAL architecture reviewer. If the branch is under MervinPraison/PraisonAI (not a fork), you are able to make modifications to this branch and push directly. SCOPE: Review changes in this PR. Python SDK: praisonaiagents, praisonai. TypeScript SDK: src/praisonai-ts/. Do NOT modify src/praisonai-rust. Read ALL comments above from Gemini, Qodo, CodeRabbit, and Copilot carefully before responding.\n\n**MANDATORY READ (before reviewing):**\n- Always read src/praisonai-agents/AGENTS.md\n- If this PR touches src/praisonai-ts/, also read src/praisonai-ts/AGENTS.md §2.1.2 (TS triage + PR review checklist)\n\n**Phase 1: Review per AGENTS.md**\n1. Protocol-driven: check heavy implementations vs core SDK\n2. Backward compatible: ensure zero feature regressions\n3. Performance: no hot-path regressions\n4. SDK value: review in depth whether the change genuinely adds value to the SDK — never add features for the sake of adding them. It must strengthen the SDK (simpler, more user-friendly, robust, world-class, secure). If it does not clearly add value, request changes or recommend rejecting/closing rather than merging scope creep\n5. Do not bloat the Agent class with additional params — only if absolutely required; we already support many params.\n6. Repo routing: agent-callable tools → PraisonAI-Tools; lifecycle plugins → PraisonAI-Plugins; optional sandbox backends → PraisonAI-Plugins (`praisonai.sandbox` entry point) — request changes if wrongly added to praisonaiagents/\n\n**MANDATORY COMMENT FORMAT — include this Phase 1 table in your review comment:**\n#### Phase 1 — AGENTS.md review\n| Check | Result |\n|---|---|\n| Protocol-driven / no heavy impl in core | ✅ or ❌ + one-line rationale |\n| Backward compatible | ✅ or ❌ + one-line rationale |\n| Performance (hot path) | ✅ or ❌ + one-line rationale |\n| **SDK value** | ✅ or ❌ + one-line rationale (explicitly judge whether the change strengthens the SDK) |\n| No Agent param bloat | ✅ or ❌ + one-line rationale |\n| Repo routing | ✅ or ❌ + one-line rationale |\n\nFor TypeScript PRs (src/praisonai-ts/), also add:\n| TS types / parity / tests | ✅ or ❌ + one-line rationale (npm run build && npm test) |\n\n**Phase 2: FIX Valid Issues**\n7. For any VALID bugs or architectural flaws found by Gemini, CodeRabbit, Qodo, Copilot, or any other reviewer: implement the fix\n8. Also independently identify and fix any gaps or issues you find in the changed code — do not rely only on prior reviewer feedback\n9. Push all code fixes directly to THIS branch (do NOT create a new PR)\n10. Comment a summary of exact files modified and what you skipped\n\n**Phase 3: Final Verdict**\n11. If all issues are resolved, approve the PR / close the Issue\n12. If blocking issues remain, request changes / leave clear action items';
body: '🤖 Auto-triaging with Claude. Analyzing issue and implementing a fix...\n\nClaude will:\n1. Route correctly: agent tools → PraisonAI-Tools; lifecycle plugins → PraisonAI-Plugins\n2. Search codebase for root cause\n3. Implement a minimal fix following AGENTS.md\n4. Create a PR with the changes'
body: '🤖 Auto-triaging with Claude. Analyzing issue and implementing a fix...\n\nClaude will:\n1. Route correctly: TypeScript → src/praisonai-ts/; agent tools → PraisonAI-Tools; lifecycle plugins → PraisonAI-Plugins\n2. Search codebase for root cause\n3. Implement a minimal fix following AGENTS.md\n4. Create a PR with the changes'
if (await mergeGate.shouldSkipMergeGateDispatch(github, owner, repo, prNumber, core)) {
return;
}
await github.rest.repos.createDispatchEvent({
owner,
repo,
@@ -288,7 +293,7 @@ jobs:
Review checklist:
1. Read AGENTS.md and the PR diff on the current branch.
2. Read all PR comments and reviews (FINAL architecture reviewer / Lead Engineer must have run).
3. Confirm SDK value gate: change strengthens praisonaiagents (no scope creep). The aim is a LIGHTWEIGHT AND POWERFUL package — BLOCK changes that add params/modules/exports duplicating existing Agent capabilities (instructions/backstory/tools/hooks/memory), or add knobs/fields with no live consumer, i.e. scope creep for the sake of it.
3. Confirm SDK value gate: change strengthens the relevant SDK (Python: praisonaiagents/praisonai; TypeScript: src/praisonai-ts/) — no scope creep. The aim is a LIGHTWEIGHT AND POWERFUL package — BLOCK changes that add params/modules/exports duplicating existing Agent capabilities (instructions/backstory/tools/hooks/memory), or add knobs/fields with no live consumer, i.e. scope creep for the sake of it. FINAL architecture review must include the Phase 1 table with an explicit **SDK value** row.
4. Repo routing: BLOCK if agent-callable tools (→ PraisonAI-Tools), lifecycle plugins (→ PraisonAI-Plugins), or optional sandbox backends (→ PraisonAI-Plugins via `praisonai.sandbox`) were added to praisonaiagents/ instead of the external repo.
5. Do not bloat the Agent class with additional params — only if absolutely required; we already support many params.
6. If agent.py adds >100 lines or new Agent __init__ params, respond MERGE_GATE_VERDICT: BLOCK (manual review required).
'**Routing:** Agent-callable tools → [PraisonAI-Tools](https://github.com/MervinPraison/PraisonAI-Tools); lifecycle plugins (tracing/hooks/guardrails) → [PraisonAI-Plugins](https://github.com/MervinPraison/PraisonAI-Plugins). TypeScript/JavaScript SDK fixes land in `src/praisonai-ts/` in this repo.'
].join('\n')
});
}
// --- Auto-trigger Claude for owner issues and actionable external bug/enhancement reports ---
// --- Auto-trigger Claude for bug/enhancement reports ---
Read AGENTS.md to understand the architecture rules.
SCOPE: Focus ONLY on Python packages (praisonaiagents, praisonai). Do NOT modify or touch praisonai-rust or praisonai-ts packages.
SCOPE: Python SDK (praisonaiagents, praisonai) and TypeScript SDK (src/praisonai-ts/) live in this monorepo. Do NOT modify src/praisonai-rust. For TS issues read src/praisonai-ts/AGENTS.md.
AIM: This package must stay LIGHTWEIGHT AND POWERFUL. Do a CRITICAL REVIEW at each stage (issue triage, fix planning, PR review/implementation) and reject scope creep for the sake of adding features. Prefer existing Agent capabilities (instructions/backstory/tools/hooks/memory) over new params/modules/exports. Even when fixing a raised issue, keep the fix minimal and lightweight — do NOT expand the surface area or add knobs with no live consumer.
4. Documentation (PraisonAIDocs): Documentation pages, guides, API references.
5. Plugins → MervinPraison/PraisonAI-Plugins: framework lifecycle extensions (tracing, logging, metrics, hooks, guardrails). Not agent tools — use STEP 3-ALT.
6. Sandbox backends (optional/niche, e.g. Capsule) → PraisonAI-Plugins via `praisonai.sandbox` entry point; core keeps protocol/config/manager only.
7. TypeScript/JavaScript SDK → src/praisonai-ts/ in this monorepo (not praisonaiagents/).
For items routed to an EXTERNAL repository (Tools, Docs, Plugins), follow STEP 3-ALT below.
- Does it duplicate existing functionality? Check if Agent already supports this via existing params (reflection, planning, tools, hooks, memory). If it does, reject the change as scope creep and prefer the existing capability — the aim is lightweight and powerful, not more knobs.
- Do not bloat the Agent class with additional params — only if absolutely required; we already support many params.
@@ -7,9 +7,22 @@ You are working on the PraisonAI project.
- Be concise and helpful in responses
- Test implementation thoroughly
- Ensure backward compatibility with existing APIs
- Follow protocol-driven design across the eight packages: core protocols in `praisonaiagents/`, agentic terminal CLI in `praisonai-code/`, bots/gateway in `praisonai-bot/`, LLM fine-tuning + agent training in `praisonai-train/`, browser automation in `praisonai-browser/`, MCP server host in `praisonai-mcp/`, sandbox backends in `praisonai-sandbox/`, integrations/serve/dashboard in the `praisonai/` wrapper
- Follow protocol-driven design across the nine Python PyPI packages plus the TypeScript SDK: core protocols in `praisonaiagents/`, agentic terminal CLI in `praisonai-code/`, bots/gateway in `praisonai-bot/`, LLM fine-tuning + agent training in `praisonai-train/`, browser automation in `praisonai-browser/`, MCP server host in `praisonai-mcp/`, sandbox backends in `praisonai-sandbox/`, deployment in `praisonai-deploy/`, integrations/serve/dashboard in the `praisonai/` wrapper, TypeScript/JavaScript SDK in `src/praisonai-ts/` (`npm: praisonai`)
- **TypeScript review routing:** For TS/JS issues and PRs, read [`src/praisonai-ts/AGENTS.md`](src/praisonai-ts/AGENTS.md) (not just this file). Canonical source is `src/praisonai-ts/` in this monorepo; [MervinPraison/praisonai-js](https://github.com/MervinPraison/praisonai-js) is the npm mirror only (sync: monorepo → praisonai-js via workflow **Sync to praisonai-js**). Do not implement TS fixes in praisonai-js for PraisonAI issues.
- Preserve old `praisonai.*` import paths via shims when moving code between packages (see §2.3 in `src/praisonai-agents/AGENTS.md`; shim helpers in `src/praisonai/praisonai/cli/_shim.py`)
- Package boundaries and dependency rules: `ARCHITECTURE.md` §2 (Tier 2 packages must never PyPI-depend on the wrapper; cross-tier access goes through lazy `_*_bridge` modules)
- When reviewing a PR or an issue, evaluate whether the change addresses a framework concern or a user goal, and design its surface (params, naming, defaults) accordingly
- The aim of this package is to stay **lightweight and powerful**. Do a critical review at each stage — when triaging an issue, when planning a fix, and when reviewing/implementing a PR. Reject scope creep for the sake of adding features: if a capability already exists (e.g. via existing Agent params like `instructions`/`backstory`/`tools`/`hooks`/`memory`), prefer it over a new API surface. A change must genuinely strengthen the SDK (simpler, more robust, more user-friendly) — do not add knobs, params, modules, or exports that have no live consumer or that merely duplicate existing behaviour.
- The aim of this package is to stay **lightweight and powerful**. Do a critical review at each stage — when triaging an issue, when planning a fix, and when reviewing/implementing a PR. Reject scope creep for the sake of adding features: if a capability already exists (e.g. via existing Agent params like `instructions`/`backstory`/`tools`/`hooks`/`memory`), prefer it over a new API surface. A change must genuinely strengthen the SDK (simpler, more robust, more user-friendly) — do not add knobs, params, modules, or exports that have no live consumer or that merely duplicate existing behaviour.
## Issue and PR routing
| Area | Where to implement | AGENTS.md to read | Tests |
| npm mirror (read-only for fixes) | [praisonai-js](https://github.com/MervinPraison/praisonai-js) | mirror of `src/praisonai-ts/AGENTS.md` | CI on praisonai-js |
| 2a | `src/praisonai-code/` | `run`/`chat`/`code`, Typer, runtime, LLM, tool resolution | **`praisonai` as a PyPI dependency** (optional lazy imports via `_wrapper_bridge` only) |
| 2b | `src/praisonai-bot/` | Bots, gateway, channel CLI, OS daemon, gateway scheduler tick | **`praisonai` as a PyPI dependency** (optional lazy `_wrapper_bridge` for jobs/UI) |
| 2c | `src/praisonai-train/` | LLM fine-tuning (Unsloth), agent training, `train` CLI, conda env setup | **`praisonai` as a PyPI dependency** (lazy `_code_bridge` for legacy dispatch) |
| 2d | `src/praisonai-browser/` | Extension bridge, CDP/hybrid automation, `browser` CLI | **`praisonai` as a PyPI dependency** (none required; depends on `praisonaiagents` only) |
| 2e | `src/praisonai-mcp/` | MCP server host, auth, transports, `mcp` CLI | **`praisonai` as a PyPI dependency** (lazy `_wrapper_bridge` for full capability registry) |
| 2f | `src/praisonai-sandbox/` | Sandbox backends (Docker, E2B, Modal, Sandlock, SSH), `SandboxRegistry` | **`praisonai` as a PyPI dependency** (lazy `_code_bridge` for `PluginRegistry`) |
| 2g | `src/praisonai-deploy/` | Deploy API/Docker/cloud, `deploy` CLI, scheduler integration | **`praisonai` as a PyPI dependency** (lazy `_plugin_registry` via `_code_bridge`) |
| 3 | `src/praisonai/` | `framework_adapters/`, serve, dashboard, async jobs API | — |
### Repo infra (not PyPI)
Deployment packaging that stays in the git checkout, not in any tier-2 wheel:
@@ -106,6 +96,232 @@ agent.start("Analyze the top 3 tech trends of 2026 and format as a markdown tabl
---
## 🧬 The Five-Layer Agent Stack
Most frameworks hand you one or two layers and leave the rest as homework. PraisonAI covers **all five** — plus the outer layer that decides *where* your agent actually runs.
Each layer wraps the one inside it. When an agent misbehaves, the layer tells you where to look.
| **1 · Prompt** | Did I say it clearly? | `instructions=`, `role`/`goal`/`backstory`, `output=`, `templates=` |
| **2 · Context** | Is the right thing in the window? | `memory=`, `knowledge=`, `context=`, handoff `ContextPolicy` |
| **3 · Harness** | Can it act, and be checked? | `tools=`, `MCP()`, `guardrails=`, `approval=`, `hooks=`, `sandbox=` |
| **4 · Loop** | When do we stop? | `execution=ExecutionConfig(...)`, `reflection=`, `autonomy=`, doom-loop detection |
| **5 · Graph** | Who runs when, and who checks whom? | `AgentFlow`, `route()`, `parallel()`, `loop()`, `repeat()` |
| **⬡ Managed** | *Where does it actually run?* | `tools_run_on="docker"` — one shared sandbox for the tools, or `run_on="anthropic"` for the whole agent |
### Layer 1 · Prompt — *Did I say it clearly?*
Role, instructions, examples, output format.
```python
frompraisonaiagentsimportAgent
agent=Agent(
role="Senior Data Analyst",
goal="Turn raw numbers into decisions",
output="verbose",# markdown-formatted output
)
agent.start("Summarise Q3 revenue trends")
```
### Layer 2 · Context — *Is the right thing in the window?*
Write, select, compress, isolate — the four context operations, one parameter each.
```python
frompraisonaiagentsimportAgent
agent=Agent(
instructions="You are a support engineer.",
memory={"user_id":"u-42"},# write — persists across runs (needs a user_id)
knowledge=["docs/"],# select — retrieves only what's relevant
context="summarize",# compress — auto-compacts before the limit
)
```
> **Isolate** is `handoffs=[specialist]` — a sub-agent inherits the last few messages and the intersection of your tools, not your whole transcript. [📖 Handoffs](https://docs.praison.ai/docs/concepts/handoffs)
### Layer 3 · Harness — *Can it act, and be checked?*
*Agent = Model + Harness.* Tool dispatch, plus the guides that steer before acting and the sensors that observe after.
# (with on_budget_exceeded="stop", hitting the cap raises BudgetExceededError,
# surfaced here as completion_reason="error")
```
> **Doom-loop detection is on by default.** Repeated identical tool calls and A→B→A→B oscillation get caught — while a poller whose output keeps changing does not. [📖 Doom Loop Detection](https://docs.praison.ai/docs/features/doom-loop-detection)
### Layer 5 · Graph — *Who runs when, and who checks whom?*
Topology as a versionable artifact: prompt chaining, routing, parallelisation, orchestrator-worker.
> The same graph is expressible in YAML with no Python at all. [📖 AgentFlow](https://docs.praison.ai/docs/concepts/agentflow)
### ⬡ Outside the stack: Managed Agents — *Where does it actually run?*
The harness is commoditising; **where** the agent executes is the next multiplier. Rather than burning your laptop's CPU, hand an agent a short-lived cloud sandbox — repo, tools and tests run there.
```bash
pip install praisonai
```
The simplest way in is `tools_run_on=` — one whole team or workflow shares **one** sandbox, so a file written by step 1 is there for step 2. Thinking stays on your machine:
Sandboxes shut themselves down when idle (`auto_shutdown`, `idle_timeout_s`), and a post-setup snapshot is reused so the next run skips the image pull and dependency install. Commit a `.praisonai/environment.yaml` and the environment travels with the repo.
> 📖 [20 runnable examples](examples/python/managed-agents/) · manage sessions with `praisonai managed sessions list <agent-id>` or `praisonai managed sessions resume <session-id> "<prompt>"`
<sub>Stack framing adapted from [The Five-Layer Agent Stack](https://mer.vin/2026/07/five-layer-agent-stack-match-bug-to-right-layer/) and [Agent Harnesses vs Orbs](https://mer.vin/2026/08/agent-harnesses-vs-orbs-why-remote-sandboxes-beat-local-agent-loops/).</sub>
---
## 🌌 The PraisonAI Ecosystem
Start simple with the core SDK, or expand to full visual builders and dashboards when you're ready.
@@ -200,9 +416,9 @@ Powered by 100+ LLMs (OpenAI, Anthropic, Gemini & local models).
Report issues against the **specific package** where the vulnerability exists. A platform-only issue does not necessarily affect the core SDK, and vice versa.
Examples demonstrating the MCP Server v2 features per MCP Protocol Version 2025-11-25.
## Features Demonstrated
@@ -130,3 +157,19 @@ These examples comply with MCP Protocol Version 2025-11-25:
-`destructiveHint`: true
-`idempotentHint`: false
-`openWorldHint`: true
## Build Remote Agent (`gbr_pair.py`)
Pair a phone running [Build Remote Agent](https://grokbuildremote.com/) to a PraisonAI agent via MCP stdio `gbr-mcp` (protocol `gbr/1`). Requires `gbr-agent pair && gbr-agent run`. Phone is spectator. Never put mailbox keys in the example.
```bash
python gbr_pair.py
```
## What the phone sees
**Terminal windows** on this PC (machine-wide mailbox). Not headless OpenCode / CodeNomad sidecar / Electron. `:8788` in a sidecar is Bot API JSON, not a transcript.
Platform releases are **independent** of `praisonai` / `praisonaiagents` version numbers. A platform-only fix (e.g. `0.1.8`) does **not** require bumping the main SDK.
13.**praisonai-platform**advisories are handled in a different repository:
| `praisonai-platform` | Independent semver, **separate repository** | Not released from this repo — see [PraisonAI-Platform](https://github.com/MervinPraison/PraisonAI-Platform) |
Always set the advisory `patched_versions` to the **package that actually contains the fix**. Do not imply users must upgrade all packages when only one changed.
@@ -217,9 +215,11 @@ Close (or publish advisory with no code change only if already mitigated) when:
**Monorepo bootstrap:**`praisonai._bootstrap.ensure_praisonai_code()` adds sibling `src/praisonai-code` to `sys.path` so `PYTHONPATH=src/praisonai-agents:src/praisonai` works without an explicit code entry.
**Install order (CI and local dev):**`praisonai-agents` → `praisonai-code` → `praisonai` (see `.github/actions/install-monorepo-packages`).
**Install order (CI and local dev):**`praisonai-agents` → `praisonai-code` →`praisonai-bot` → `praisonai-train` → `praisonai-browser` → `praisonai-mcp` → `praisonai-sandbox` → `praisonai-deploy` →`praisonai` (see `.github/actions/install-monorepo-packages`).
**Invocation paths that must remain valid:**
@@ -207,6 +207,7 @@ and features (capabilities, bots, framework adapters) — use
2. Implement fixes in **`src/praisonai-ts/`** in this monorepo (not in `praisonaiagents/`).
3. Verify with `cd src/praisonai-ts && npm install && npm run build && npm test`.
4. After merge, maintainers sync the npm mirror: `gh workflow run "Sync to praisonai-js" --repo MervinPraison/PraisonAI`.
[MervinPraison/praisonai-js](https://github.com/MervinPraison/praisonai-js) is the public npm checkout; direction is **monorepo → praisonai-js** only. Claude merge gate and `@claude` review TS changes under `src/praisonai-ts/` using the TS AGENTS.md criteria (lightweight, type-safe, Python parity where applicable).
@@ -1074,7 +1088,7 @@ PraisonAI's reliability engineering rests on three pillars — **C**ontext, **H*
> **Evaluator status.** The `ContextEvaluator` / `HarnessEvaluator` / `LoopEvaluator` classes named in the rubric are **planned follow-ups** (PA-CHL-001–004), not yet in the repo. Until they land, the equivalent checks are covered by existing modules:
>
> - **Context** — `context/tokens.py` and `eval/tokens.py` (`estimate_tokens` / `count_tokens`) for budget; `compaction/compactor.py` (`ContextCompactor`) for compaction/retention.
> - **Harness** — `runtime/turn_context.py` for turn-context parity; `runtime/example_harness.py` and `tests/` for harness/artifact checks.
> - **Harness** — `runtime/turn_context.py` for turn-context parity; `examples/runtime/example_harness.py` and `tests/` for harness/artifact checks.
> - **Loop** — `eval/loop.py` (`EvaluationLoop`) and `agent/autonomy.py` for convergence and doom-loop guards.
>
> Keep terminology consistent with the `agent/context_agent.py` (`ContextAgent`) PRP methodology.
"""Register an Agent turn and consume any request made while idle."""
withself._lock:
self._next_turn_id+=1
turn_id=self._next_turn_id
self._active_turns.add(turn_id)
ifself._pending_turn_cancel:
self._cancelled_turns.add(turn_id)
self._pending_turn_cancel=False
returnturn_id
def_turn_is_cancelled(self,turn_id:int)->bool:
"""Return whether a registered turn was targeted by a request."""
withself._lock:
returnturn_idinself._cancelled_turns
def_end_turn(self,turn_id:int)->None:
"""Unregister a turn so its request cannot affect a future turn."""
withself._lock:
self._active_turns.discard(turn_id)
self._cancelled_turns.discard(turn_id)
defclear(self)->None:
"""Clear the cancellation request."""
withself._lock:
self._reason=None
self._flag.clear()
self._pending_turn_cancel=False
self._cancelled_turns.clear()
defis_set(self)->bool:
"""Check if cancellation has been requested.
Loaded 100 of 1725 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
