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

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

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

claude documentation enhancement javascript

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 when merge_run_terminal 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 — 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)
  1. current is None → return observed.
  2. is_sticky(current) → return current.
  3. Higher kind rank wins (aborted > timeout > failed > ok).
  4. Equal rank: sticky observation promotes over non-sticky current.
  5. 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
  • RunTerminal type (#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
  1. Locate Python definition(s) for merge_run_terminal (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 (merge_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 merge_run_terminal 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 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

  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 merge_run_terminal 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 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

  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.