[parity][P3] Export `merge_run_terminal` in praisonai-ts
I maintainer di solito rispondono entro 1 giorno
Nessuno ha ancora preso questa issue.
- #5300 di @praisonai-triage-agent — chiusa senza merge
Valutazione
- Difficoltà
- 3/5
- Tempo stimato
- Mezza giornata
- Idoneità per principianti
- 58/100
- Tipo di issue
- Funzionalità
- Chiarezza
- Abbastanza chiara
- Stato di attività
- Tranquilla
- Stack tecnologico
- python, typescript
- Ambito
- backend
Direzione di ricerca
Start from the Python reference in src/praisonai-agents/praisonaiagents/run_outcome.py, where merge_run_terminal is defined around line 408, and read the merge rules alongside tests/unit/test_run_outcome.py. Port the pure function into src/praisonai-ts and export it from the root src/index.ts barrel, then add a unit test under src/praisonai-ts/tests/ covering the forward and reverse observation orders. Done when the export resolves from the package root, the tests pass with npm test, and the parity generator marks merge_run_terminal as typescript: true in FEATURE_PARITY_TRACKER.json.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Descrizione
Executive summary
Python exposes merge_run_terminal as part of the public SDK surface. TypeScript does not yet
export an equivalent symbol, so cross-language examples, mobile/Node clients, and parity
tests cannot rely on the same API shape.
| Field | Value |
|---|---|
| Feature | merge_run_terminal |
| Priority | P3 |
| Effort (generator estimate) | low |
| Category | other |
| Gap bucket | P3_Advanced |
| Python | present |
| TypeScript | missing |
| Source of truth | Python praisonaiagents |
Why this matters
- Cross-SDK parity: Teams porting Python agent code to TypeScript hit import errors or silent
behavior drift whenmerge_run_terminalis absent. - Downstream products: Runtimes that embed
praisonai-ts(CLI, mobile shell, server adapters)
cannot enable features guarded by this export. - Tracker integrity: The parity checker keeps
gapCountelevated until TypeScript exports
match Python for this symbol.
Out of scope for a minimal fix
- Renaming Python exports (Python remains canonical).
- Partial stubs that do not match Python semantics — parity tests should fail loudly until behavior matches.
Core issue deep dive — merge_run_terminal
Pure function folding a newly observed RunTerminal into the current authoritative terminal.
Order-independent: same multiset of observations → same result.
Merge rules (must match Python line-for-line)
current is None→ returnobserved.is_sticky(current)→ returncurrent.- Higher
kindrank wins (aborted>timeout>failed>ok). - Equal rank: sticky observation promotes over non-sticky current.
- Else keep
current.
Critical scenarios
| Scenario | Expected |
|---|---|
| Cancel then provider error | Keep aborted/external |
timeout/idle then timeout/run_budget |
Promote to sticky run_budget |
| Forward vs reverse observation order | Identical final terminal |
Export names
Parity matrix expects merge_run_terminal (snake_case). Also export mergeRunTerminal if
the package uses camelCase aliases elsewhere.
Depends on
RunTerminaltype (#1 in this pack)is_sticky(may implement together; still file separate issues for tracker rows)
Parity checker evidence
The official generator compares Python (praisonaiagents) exports against
praisonai-ts public surface and writes FEATURE_PARITY_TRACKER.json plus PARITY.md.
Regenerate and verify (from repository root)
cd src/praisonai
export PYTHONIOENCODING=utf-8
python -m praisonai._dev.parity.generator --target ts --check
On Windows PowerShell:
$env:PYTHONIOENCODING = 'utf-8'
cd src/praisonai
python -m praisonai._dev.parity.generator --target ts --check
When the tracker is not up to date, --check exits non-zero after rewriting files.
When up to date, output includes confirmation that src/praisonai-ts/FEATURE_PARITY_TRACKER.json
and src/praisonai-ts/PARITY.md match extracted exports.
Inspect this gap programmatically
python - <<'PY'
import json
from pathlib import Path
data = json.loads(Path("src/praisonai-ts/FEATURE_PARITY_TRACKER.json").read_text())
print("gapCount:", data["summary"]["gapCount"])
print("priority P0:", data["summary"]["priorityP0"])
for bucket, rows in data["gapMatrix"].items():
for row in rows:
if row.get("feature") == "merge_run_terminal":
print("bucket:", bucket)
print(json.dumps(row, indent=2))
PY
Snapshot at issue generation time
| Metric | Value |
|---|---|
| Total open export gaps | 4 |
| P0 gaps | 0 |
| P3 gaps | 4 |
| TypeScript tracked features | 2082 |
| Python core features | 421 |
This issue: merge_run_terminal is marked python: true, typescript: false, status: TODO
in gapMatrix.
Architecture context
flowchart TB
subgraph python [Python SDK — source of truth]
PA[praisonaiagents public exports]
F["merge_run_terminal"]
PA --> F
end
subgraph ts [praisonai-ts]
IDX[src/index.ts barrel]
MOD[domain modules]
IDX --> MOD
GAP["merge_run_terminal — missing export"]
MOD -.-> GAP
end
subgraph chk [Parity tooling]
GEN[praisonai._dev.parity.generator]
TR[FEATURE_PARITY_TRACKER.json]
GEN --> TR
end
F --> GEN
MOD --> GEN
TR --> ISSUE[GitHub issue / CI gate]
Category other indicates where the implementation likely lives in both trees
(agent, app, config, bots, ui, other). Start discovery in the matching package area before
adding a top-level re-export.
Python references (sample)
| File | Line | Snippet |
|---|---|---|
src/praisonai-agents/praisonaiagents/run_outcome.py |
325 | # discriminated union for "how a run ended". ``merge_run_terminal`` folds |
src/praisonai-agents/praisonaiagents/run_outcome.py |
377 | instance via :func:merge_run_terminal, never by mutation. |
src/praisonai-agents/praisonaiagents/run_outcome.py |
408 | def merge_run_terminal( |
src/praisonai-agents/praisonaiagents/run_outcome.py |
466 | "merge_run_terminal", |
src/praisonai-agents/praisonaiagents/__init__.py |
150 | 'merge_run_terminal': ('praisonaiagents.run_outcome', 'merge_run_terminal'), |
src/praisonai-agents/tests/unit/test_run_outcome.py |
211 | from praisonaiagents.run_outcome import RunTerminal, merge_run_terminal |
src/praisonai-agents/tests/unit/test_run_outcome.py |
214 | assert merge_run_terminal(None, observed) == observed |
src/praisonai-agents/tests/unit/test_run_outcome.py |
217 | from praisonaiagents.run_outcome import RunTerminal, merge_run_terminal, collapse |
src/praisonai-agents/tests/unit/test_run_outcome.py |
221 | merged = merge_run_terminal(cancel, error) |
src/praisonai-agents/tests/unit/test_run_outcome.py |
226 | from praisonaiagents.run_outcome import RunTerminal, merge_run_terminal, is_sticky, collapse |
Code excerpt (src/praisonai-agents/praisonaiagents/run_outcome.py)
317|
318|
319| # --------------------------------------------------------------------------
320| # Canonical terminal-outcome contract
321| #
322| # A gateway run can end for several reasons that observe the run concurrently
323| # (idle timeout, run-budget timeout, external /stop, provider error, supersede
324| # by a newer turn, normal completion). ``RunTerminal`` is the single closed
325| # discriminated union for "how a run ended". ``merge_run_terminal`` folds
326| # racing terminal observations into one authoritative outcome with a fixed,
327| # deterministic precedence so a deliberate cancellation or a hard timeout is
328| # never silently overwritten by a late, generic provider error. ``collapse``
329| # projects back onto the existing ``RunStatus`` vocabulary so nothing
330| # downstream breaks.
331| # --------------------------------------------------------------------------
332|
333| # How a run ended, in order of increasing attribution strength. ``merge`` may
334| # only refine toward a stronger kind; it never downgrades.
335| TerminalKind = Literal["ok", "failed", "timeout", "aborted"]
336|
337| # What observed the run ending.
338| TerminalSource = Literal[
339| "completion", # normal completion
340| "idle", # idle timeout
341| "run_budget", # run-budget / hard timeout
342| "external", # external /stop (deliberate user cancellation)
343| "provider", # provider error
344| "superseded", # superseded by a newer turn
345| ]
346|
347| # Precedence rank per kind: higher wins a merge. A weaker later observation
348| # never downgrades a stronger recorded one.
349| _TERMINAL_KIND_RANK: Dict[str, int] = {
350| "ok": 0,
TypeScript references (sample)
No matches under src/praisonai-ts — confirms the export gap is real (not just a barrel omission).
Implementation plan (TypeScript)
Phase 1 — Discovery
- Locate Python definition(s) for
merge_run_terminal(see tables above). - Identify dependent types, protocols, and exceptions referenced by the implementation.
- Search
src/praisonai-tsfor partial implementations under different names (merge_run_terminal, camelCase variants).
Phase 2 — API design
- Mirror Python names at the package boundary (PascalCase types, camelCase functions) per existing TS conventions.
- Add types to the closest module (avoid
any; prefer strict structs matching Python dataclasses/TypedDicts). - Export from the module index and root
src/index.tsif Python exports from top-levelpraisonaiagents.
Phase 3 — Implementation
- Port logic incrementally; keep I/O boundaries explicit (async vs sync parity with Python).
- Reuse existing utilities (logging, config, agent runtime) instead of duplicating parallel stacks.
- Guard feature flags if Python gates behavior behind config objects.
Phase 4 — Tests
- Add unit tests under
src/praisonai-ts/tests/mirroring Python test scenarios where they exist. - Add a parity-focused test asserting
merge_run_terminalis exported from the package entry used by consumers. - Run
npm test/pnpm testinsrc/praisonai-ts.
Phase 5 — Tracker refresh
cd src/praisonai
PYTHONIOENCODING=utf-8 python -m praisonai._dev.parity.generator --target ts
git diff src/praisonai-ts/FEATURE_PARITY_TRACKER.json src/praisonai-ts/PARITY.md
Expect merge_run_terminal to move to typescript: true / DONE in its bucket row.
Suggested file touch list (adjust after discovery)
| Area | Likely paths |
|---|---|
| Implementation | src/praisonai-ts/src/**/merge_run_terminal.ts or nearest domain folder |
| Barrel export | src/praisonai-ts/src/index.ts |
| Types | collocated *.types.ts or module index |
| Tests | src/praisonai-ts/tests/unit/**/merge_run_terminal.test.ts |
| Docs | src/praisonai-ts/PARITY.md (auto-generated) |
Detailed test scenarios
### TS-merge_run_terminal-001 — Export surface
- **Given** a clean install of `praisonai-ts`
- **When** importing `merge_run_terminal` from the package root
- **Then** the symbol is defined and typed (not `any`)
### TS-merge_run_terminal-002 — Runtime smoke
- **Given** minimal valid configuration mirrored from Python docs
- **When** executing the primary API path
- **Then** outputs match Python shape (fields, enums, error types)
### TS-merge_run_terminal-003 — Failure semantics
- **Given** invalid inputs used in Python tests
- **When** invoking TypeScript API
- **Then** reject with equivalent error class / message pattern
### TS-merge_run_terminal-004 — Concurrency / async
- **Given** parallel callers (if applicable)
- **When** stress-testing async entrypoints
- **Then** no lost errors; bounded concurrency matches Python defaults
### TS-merge_run_terminal-005 — Regression guard
- Add a unit test that fails if `merge_run_terminal` disappears from exports (meta-test scanning `index.ts`).
| ID | Scenario | Verification |
|----|----------|--------------|
| export-present | import { merge_run_terminal } from 'praisonai-ts' resolves | package exports map |
| types-compile | TypeScript strict build passes | tsc / build script |
| python-parity-smoke | Behavior matches Python reference for happy path | unit + manual script |
| error-paths | Validation errors align with Python exception types | unit tests |
| async-contract | Async functions return awaited types consistent with Python | unit tests |
| config-guards | Config flags disable/enable feature like Python | unit tests |
| tracker | Parity generator marks feature DONE | generator --target ts |
| docs | PARITY.md no longer lists gap for this feature | generated markdown |
| tree-shaking | Export does not pull unintended heavy deps | bundle size spot check |
| mobile-shell | Consumers (e.g. mobile) compile against new export | integration build |
## Acceptance criteria
- [ ] `merge_run_terminal` exported from `praisonai-ts` public API
- [ ] Unit tests cover happy path + primary error paths
- [ ] `python -m praisonai._dev.parity.generator --target ts --check` passes
- [ ] `FEATURE_PARITY_TRACKER.json` marks `merge_run_terminal` as TypeScript complete
- [ ] No breaking change to unrelated exports (semver note in PR if needed)
Risks and rollout notes
| Risk | Mitigation |
|---|---|
| Behavior drift vs Python | Port tests from Python; compare JSON snapshots |
| Bundle size increase | Lazy import heavy deps; keep core export thin |
| Partial stub shipped | Block merge until parity test green |
| Naming mismatch | Follow existing TS naming table in adjacent modules |
Related gaps
See src/praisonai-ts/PARITY.md for neighboring TODO rows in the same bucket. Closing merge_run_terminal
may unblock downstream exports that depend on shared protocols or event types.
Definition of Done
- Implementation merged to
main. - Parity tracker regenerated in the same PR (or immediately follow-up) so CI reflects closure.
- Release notes mention
merge_run_terminalfor TypeScript consumers.
Appendix A — Parity workflow diagram
sequenceDiagram
participant Dev as Contributor
participant Py as Python SDK
participant Gen as parity.generator
participant TS as praisonai-ts
participant CI as CI check
Dev->>Py: Read canonical API
Dev->>TS: Implement export
Dev->>Gen: --target ts
Gen->>TS: Refresh FEATURE_PARITY_TRACKER.json
Dev->>CI: --check must pass
Appendix B — FAQ
Q: Can we mark DONE without implementation?
A: No — extractor validates public exports, not comments.
Q: Should mobile re-implement merge_run_terminal?
A: No — consume via praisonai-ts once exported.
Q: Effort says merge_run_terminal is high — can we split?
A: Yes, use sub-PRs behind a tracking issue, but keep parity row IN_PROGRESS until complete.
Appendix C — Checklist (copy into PR)
- Read Python source for
merge_run_terminal - Map types 1:1 (names + optional/required)
- Implement module + export
- Unit tests
- Run parity generator
- Update release notes
Sibling gaps in this parity slice
Related exports still tracked separately: RunTerminal, is_sticky, collapse. Implement in coordinated PRs or one PR closing multiple tracker rows.
Filed 2026-09-24 from current parity pack (gapCount: 4 on main). Pre-flight: praisonai._dev.parity.generator --target ts --check.
- Lingua principale
- Python
- Stelle
- 9.3k
- Fork
- 1.5k
- Merge medio
- 1g 5h
- PR unite (30g)
- 520
Preparare l'ambiente
Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Altre issue di MervinPraison/PraisonAI
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 82/100
MervinPraison/PraisonAI#6710 · 1 commento ·
I maintainer di solito rispondono entro 1 giorno
-
claude
Difficoltà 2/5 1-3 ore Idoneità per principianti 74/100
MervinPraison/PraisonAI#6707 ·
I maintainer di solito rispondono entro 1 giorno
-
bug claude
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 90/100
MervinPraison/PraisonAI#6671 ·
I maintainer di solito rispondono entro 1 giorno
-
Compaction budget regression fixture remains below budget with accurate tokenizationForse di nuovo libera Una pull request per questa issue è stata chiusa senza essere unita. Aperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 62/100
MervinPraison/PraisonAI#5418 · 3 commenti ·
I maintainer di solito rispondono entro 1 giorno
-
bug claude documentation
Difficoltà 2/5 1-3 ore Idoneità per principianti 70/100
MervinPraison/PraisonAI#5341 · 3 commenti ·
I maintainer di solito rispondono entro 1 giorno
Tutte le issue di MervinPraison/PraisonAI
Issue simili
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 76/100
I maintainer di solito rispondono entro 2 giorni
-
[Bug]: LANGSMITH_SAMPLING_RATE ignores fractional values (isdigit check), traces 100% of requestsAperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 84/100
I maintainer di solito rispondono entro 1 giorno
-
platform/backend tests
Difficoltà 2/5 1-3 ore Idoneità per principianti 78/100
Significant-Gravitas/AutoGPT#17100 ·
I maintainer di solito rispondono entro 1 giorno
-
bug good first issue
Difficoltà 2/5 1-3 ore Idoneità per principianti 64/100
-
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 61/100
scverse/infercnvpy#238 ·
I maintainer di solito rispondono entro 1 giorno