[parity][P3] Export `RunTerminal` in praisonai-ts

Aperta
#5,295 2 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

  • #5301 di @praisonai-triage-agent — chiusa senza merge

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
30/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Ferma
Stack tecnologico
python, typescript
Ambito
api

Direzione di ricerca

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.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

claude documentation enhancement javascript

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 when RunTerminal is 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 gapCount elevated 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 — keys kind, source, detail.
  • Immutability: refinement only via merge_run_terminal, never mutation.
TypeScript deliverable
  • RunTerminal class or frozen interface in src/agent/run-outcome.ts.
  • Export from package root as RunTerminal (exact parity name).
  • Dependency: merge_run_terminal, is_sticky, and collapse consume RunTerminal; 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_serialisation
  • test_collapse_covers_all_kinds (uses RunTerminal instances)

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
  1. Locate Python definition(s) for RunTerminal (see tables above).
  2. Identify dependent types, protocols, and exceptions referenced by the implementation.
  3. Search src/praisonai-ts for partial implementations under different names (run_terminal, camelCase variants).
Phase 2 — API design
  1. Mirror Python names at the package boundary (PascalCase types, camelCase functions) per existing TS conventions.
  2. Add types to the closest module (avoid any; prefer strict structs matching Python dataclasses/TypedDicts).
  3. Export from the module index and root src/index.ts if Python exports from top-level praisonaiagents.
Phase 3 — Implementation
  1. Port logic incrementally; keep I/O boundaries explicit (async vs sync parity with Python).
  2. Reuse existing utilities (logging, config, agent runtime) instead of duplicating parallel stacks.
  3. Guard feature flags if Python gates behavior behind config objects.
Phase 4 — Tests
  1. Add unit tests under src/praisonai-ts/tests/ mirroring Python test scenarios where they exist.
  2. Add a parity-focused test asserting RunTerminal is exported from the package entry used by consumers.
  3. Run npm test / pnpm test in src/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

  1. Implementation merged to main.
  2. Parity tracker regenerated in the same PR (or immediately follow-up) so CI reflects closure.
  3. Release notes mention RunTerminal for 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.

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

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di MervinPraison/PraisonAI

Tutte le issue di MervinPraison/PraisonAI

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.