[parity][P3] Export `RunTerminal` in praisonai-ts
メンテナーはふだん 1 日以内に返信
まだ誰も着手していません。
- #5301 @praisonai-triage-agent による — マージされずにクローズ
評価
- 難易度
- 4/5
- 見積もり時間
- 3〜5日
- 初心者へのやさしさ
- 30/100
- issue の種類
- 機能追加
- 明瞭さ
- おおむね明確
- 活発さ
- 停滞
- 技術スタック
- python, typescript
- 領域
- api
調査の方向性
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.
索引モデルが issue の本文から書いたものです。
説明
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.
- 主要言語
- Python
- スター
- 9.3k
- フォーク
- 1.5k
- 平均マージ
- 1日 5時間
- マージ済み PR(30日)
- 520
環境構築
このプロジェクトには開発コンテナ、Dockerfile、コントリビューションガイドがありません。まず README を読み、一般的な手順ははじめてのコントリビューションガイドを参照してください。
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
MervinPraison/PraisonAI のほかの issue
-
難易度 2/5 1〜3時間 初心者へのやさしさ 82/100
MervinPraison/PraisonAI#6710 · コメント 1 件 ·
メンテナーはふだん 1 日以内に返信
-
claude
難易度 2/5 1〜3時間 初心者へのやさしさ 74/100
MervinPraison/PraisonAI#6707 ·
メンテナーはふだん 1 日以内に返信
-
bug claude
難易度 1/5 1時間未満 初心者へのやさしさ 90/100
MervinPraison/PraisonAI#6671 ·
メンテナーはふだん 1 日以内に返信
-
Compaction budget regression fixture remains below budget with accurate tokenization再び着手できるかも このイシューのプルリクエストはマージされずにクローズされました。 オープン
難易度 2/5 1〜3時間 初心者へのやさしさ 62/100
MervinPraison/PraisonAI#5418 · コメント 3 件 ·
メンテナーはふだん 1 日以内に返信
-
bug claude documentation
難易度 2/5 1〜3時間 初心者へのやさしさ 70/100
MervinPraison/PraisonAI#5341 · コメント 3 件 ·
メンテナーはふだん 1 日以内に返信
MervinPraison/PraisonAI の issue をすべて見る
似ている issue
-
cognition
難易度 2/5 1〜3時間 初心者へのやさしさ 82/100
メンテナーはふだん 1 日以内に返信
-
難易度 1/5 1時間未満 初心者へのやさしさ 78/100
collabnix/awesome-mcp-lists#433 ·
メンテナーはふだん 4 日以内に返信
-
CrossEntropyFilter raises on zero probabilities and single-class results対応中かも @NopeCharon が今日担当しました。 オープン
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
メンテナーはふだん 1 日以内に返信
-
bug
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
datajoint/datajoint-python#1703 ·
メンテナーはふだん 6 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
Archmonger/ServeStatic#129 ·