[parity][P3] Export `RunTerminal` in praisonai-ts
Los mantenedores suelen responder en 1 día
Nadie ha tomado este issue todavía.
- #5301 de @praisonai-triage-agent — cerrado sin fusionar
Evaluación
- Dificultad
- 4/5
- Tiempo estimado
- 3-5 días
- Aptitud para principiantes
- 30/100
- Tipo de issue
- Nueva funcionalidad
- Claridad
- Bastante claro
- Estado de actividad
- Estancado
- Stack tecnológico
- python, typescript
- Área
- api
Línea de trabajo
Start with the Python definition of RunTerminal, the frozen dataclass near line 371 of src/praisonai-agents/praisonaiagents/run_outcome.py, plus is_sticky, merge_run_terminal and collapse, which depend on it. Read the closed, unmerged PR #5301 before starting, since the work has already been attempted. Port the type to src/praisonai-ts/src/agent/run-outcome.ts and export it from the root barrel src/index.ts. Done means the round-trip test in tests/unit/test_run_outcome.py::TestRunTerminal has a TypeScript equivalent and the parity generator reports the symbol as present.
Escrito por el modelo de indexación a partir del texto del issue.
Descripción
Executive summary
Python exposes RunTerminal 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 | RunTerminal |
| Priority | P3 |
| Effort (generator estimate) | high |
| 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 whenRunTerminalis 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 — RunTerminal
RunTerminal is the immutable value type for “how a run ended” when multiple observers
can report concurrently. It lives in praisonaiagents/run_outcome.py alongside (but distinct from)
AgentRunOutcome.
Fields (Python dataclass, frozen)
| Field | Type | Meaning |
|---|---|---|
kind |
TerminalKind |
ok | failed | timeout | aborted |
source |
TerminalSource |
Which observer produced this terminal |
detail |
Optional[str] |
Free-text detail (e.g. user /stop) |
Serialization
to_dict()/from_dict()for JSON/SQLite persistence — keyskind,source,detail.- Immutability: refinement only via
merge_run_terminal, never mutation.
TypeScript deliverable
RunTerminalclass or frozen interface insrc/agent/run-outcome.ts.- Export from package root as
RunTerminal(exact parity name). - Dependency:
merge_run_terminal,is_sticky, andcollapseconsumeRunTerminal; land in same
release train or implement this type first in PR 1 of 4.
Tests to port first (subset)
From tests/unit/test_run_outcome.py::TestRunTerminal:
test_round_trip_serialisationtest_collapse_covers_all_kinds(usesRunTerminalinstances)
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") == "RunTerminal":
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: RunTerminal 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["RunTerminal"]
PA --> F
end
subgraph ts [praisonai-ts]
IDX[src/index.ts barrel]
MOD[domain modules]
IDX --> MOD
GAP["RunTerminal — 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 |
324 | # by a newer turn, normal completion). ``RunTerminal`` is the single closed |
src/praisonai-agents/praisonaiagents/run_outcome.py |
371 | class RunTerminal: |
src/praisonai-agents/praisonaiagents/run_outcome.py |
375 | observer produced it (used to decide stickiness). ``RunTerminal`` is frozen |
src/praisonai-agents/praisonaiagents/run_outcome.py |
389 | def from_dict(cls, data: Dict[str, Any]) -> "RunTerminal": |
src/praisonai-agents/praisonaiagents/run_outcome.py |
398 | def is_sticky(outcome: RunTerminal) -> bool: |
src/praisonai-agents/praisonaiagents/run_outcome.py |
409 | current: Optional[RunTerminal], observed: RunTerminal |
src/praisonai-agents/praisonaiagents/run_outcome.py |
410 | ) -> RunTerminal: |
src/praisonai-agents/praisonaiagents/run_outcome.py |
447 | def collapse(outcome: RunTerminal) -> RunStatus: |
src/praisonai-agents/praisonaiagents/run_outcome.py |
448 | """Project a ``RunTerminal`` onto the existing ``RunStatus`` vocabulary. |
src/praisonai-agents/praisonaiagents/run_outcome.py |
463 | "RunTerminal", |
Code excerpt (src/praisonai-agents/praisonaiagents/run_outcome.py)
316| return "failure"
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] = {
TypeScript references (sample)
| File | Line | Snippet |
|---|---|---|
src/praisonai-ts/PARITY.md |
183 | ` |
If matches exist only in comments/tests, still add the public export and wire implementation.
Implementation plan (TypeScript)
Phase 1 — Discovery
- Locate Python definition(s) for
RunTerminal(see tables above). - Identify dependent types, protocols, and exceptions referenced by the implementation.
- Search
src/praisonai-tsfor partial implementations under different names (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
RunTerminalis 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 RunTerminal 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/**/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/**/run_terminal.test.ts |
| Docs | src/praisonai-ts/PARITY.md (auto-generated) |
Detailed test scenarios
### TS-RunTerminal-001 — Export surface
- **Given** a clean install of `praisonai-ts`
- **When** importing `RunTerminal` from the package root
- **Then** the symbol is defined and typed (not `any`)
### TS-RunTerminal-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-RunTerminal-003 — Failure semantics
- **Given** invalid inputs used in Python tests
- **When** invoking TypeScript API
- **Then** reject with equivalent error class / message pattern
### TS-RunTerminal-004 — Concurrency / async
- **Given** parallel callers (if applicable)
- **When** stress-testing async entrypoints
- **Then** no lost errors; bounded concurrency matches Python defaults
### TS-RunTerminal-005 — Regression guard
- Add a unit test that fails if `RunTerminal` disappears from exports (meta-test scanning `index.ts`).
| ID | Scenario | Verification |
|----|----------|--------------|
| export-present | import { RunTerminal } 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
- [ ] `RunTerminal` 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 `RunTerminal` 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 RunTerminal
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
RunTerminalfor 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 RunTerminal?
A: No — consume via praisonai-ts once exported.
Q: Effort says RunTerminal 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
RunTerminal - 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: merge_run_terminal, 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.
- Lenguaje dominante
- Python
- Estrellas
- 9.3k
- Forks
- 1.5k
- Merge medio
- 1 d 5 h
- PR fusionados (30 d)
- 520
Preparar el entorno
Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.
Primeros pasos
- Lee el issue completo y luego la guía de contribución del proyecto.
- Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
- Haz un fork del repositorio y trabaja en una rama.
- Abre un pull request que haga referencia al número del issue.
Más de MervinPraison/PraisonAI
-
Dificultad 2/5 1-3 horas Aptitud para principiantes 82/100
MervinPraison/PraisonAI#6710 · 1 comentario ·
Los mantenedores suelen responder en 1 día
-
claude
Dificultad 2/5 1-3 horas Aptitud para principiantes 74/100
MervinPraison/PraisonAI#6707 ·
Los mantenedores suelen responder en 1 día
-
bug claude
Dificultad 1/5 Menos de una hora Aptitud para principiantes 90/100
MervinPraison/PraisonAI#6671 ·
Los mantenedores suelen responder en 1 día
-
Compaction budget regression fixture remains below budget with accurate tokenizationQuizá libre de nuevo Un pull request para esta issue se cerró sin fusionarse. Abierto
Dificultad 2/5 1-3 horas Aptitud para principiantes 62/100
MervinPraison/PraisonAI#5418 · 3 comentarios ·
Los mantenedores suelen responder en 1 día
-
bug claude documentation
Dificultad 2/5 1-3 horas Aptitud para principiantes 70/100
MervinPraison/PraisonAI#5341 · 3 comentarios ·
Los mantenedores suelen responder en 1 día
Todos los issues de MervinPraison/PraisonAI
Issues similares
-
Dificultad 2/5 1-3 horas Aptitud para principiantes 76/100
Los mantenedores suelen responder en 2 días
-
[Bug]: LANGSMITH_SAMPLING_RATE ignores fractional values (isdigit check), traces 100% of requestsAbierto
Dificultad 2/5 1-3 horas Aptitud para principiantes 84/100
Los mantenedores suelen responder en 1 día
-
platform/backend tests
Dificultad 2/5 1-3 horas Aptitud para principiantes 78/100
Significant-Gravitas/AutoGPT#17100 ·
Los mantenedores suelen responder en 1 día
-
bug good first issue
Dificultad 2/5 1-3 horas Aptitud para principiantes 64/100
-
scverse link in README is brokenAbierto
Dificultad 1/5 Menos de una hora Aptitud para principiantes 61/100
scverse/infercnvpy#238 ·
Los mantenedores suelen responder en 1 día