[parity][P3] Export `is_sticky` in praisonai-ts
I maintainer di solito rispondono entro 1 giorno
Nessuno ha ancora preso questa issue.
- #5299 di @praisonai-triage-agent — chiusa senza merge
Valutazione
- Difficoltà
- 3/5
- Tempo stimato
- 1-2 giorni
- Idoneità per principianti
- 35/100
- Tipo di issue
- Funzionalità
- Chiarezza
- Abbastanza chiara
- Stato di attività
- Tranquilla
- Stack tecnologico
- python, typescript
- Ambito
- ai
Direzione di ricerca
Read is_sticky, _STICKY_SOURCES and merge_run_terminal in src/praisonai-agents/praisonaiagents/run_outcome.py, and the cases in tests/unit/test_run_outcome.py. Port the RunTerminal shape and is_sticky into src/praisonai-ts, then export it from the root src/index.ts barrel. Done when a TypeScript test imports is_sticky from the package entry and passes, and the parity generator --check reports is_sticky as present. A closed, unmerged pull request (#5299) already targets this issue, so check why it was closed first.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Descrizione
Executive summary
Python exposes is_sticky 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 | is_sticky |
| 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 whenis_stickyis 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 — is_sticky
_STICKY_SOURCES = frozenset({"external", "run_budget", "superseded"})
def is_sticky(outcome: RunTerminal) -> bool:
return outcome.source in _STICKY_SOURCES
Sticky terminals must never be overwritten by later weaker observations in merge_run_terminal.
Source stickiness table
TerminalSource |
Sticky? |
|---|---|
external |
Yes |
run_budget |
Yes |
superseded |
Yes |
completion, idle, provider |
No |
Tests
test_hard_timeout_is_stickytest_superseded_is_sticky- Sticky promotion cases in
test_equal_kind_sticky_promotes_over_nonsticky
Export as is_sticky at package boundary.
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") == "is_sticky":
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: is_sticky 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["is_sticky"]
PA --> F
end
subgraph ts [praisonai-ts]
IDX[src/index.ts barrel]
MOD[domain modules]
IDX --> MOD
GAP["is_sticky — 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 |
398 | def is_sticky(outcome: RunTerminal) -> bool: |
src/praisonai-agents/praisonaiagents/run_outcome.py |
436 | if is_sticky(current): |
src/praisonai-agents/praisonaiagents/run_outcome.py |
442 | if observed_rank == current_rank and is_sticky(observed): |
src/praisonai-agents/praisonaiagents/run_outcome.py |
467 | "is_sticky", |
src/praisonai-agents/praisonaiagents/__init__.py |
151 | 'is_sticky': ('praisonaiagents.run_outcome', 'is_sticky'), |
src/praisonai-agents/tests/unit/test_run_outcome.py |
225 | def test_hard_timeout_is_sticky(self): |
src/praisonai-agents/tests/unit/test_run_outcome.py |
226 | from praisonaiagents.run_outcome import RunTerminal, merge_run_terminal, is_sticky, collapse |
src/praisonai-agents/tests/unit/test_run_outcome.py |
230 | assert is_sticky(timeout) |
src/praisonai-agents/tests/unit/test_run_outcome.py |
269 | def test_superseded_is_sticky(self): |
src/praisonai-agents/tests/unit/test_run_outcome.py |
270 | from praisonaiagents.run_outcome import RunTerminal, merge_run_terminal, is_sticky |
Code excerpt (src/praisonai-agents/praisonaiagents/run_outcome.py)
390| """Rehydrate from a plain dict produced by :meth:`to_dict`."""
391| return cls(
392| kind=data["kind"],
393| source=data["source"],
394| detail=data.get("detail"),
395| )
396|
397|
398| def is_sticky(outcome: RunTerminal) -> bool:
399| """Whether ``outcome`` can never be overwritten by a later observation.
400|
401| Deliberate cancellations (``external``), hard run-budget timeouts
402| (``run_budget``), and supersedes (``superseded``) are intentional
403| terminals: once recorded they are authoritative.
404| """
405| return outcome.source in _STICKY_SOURCES
406|
407|
408| def merge_run_terminal(
409| current: Optional[RunTerminal], observed: RunTerminal
410| ) -> RunTerminal:
411| """Fold a newly-observed terminal into the current one (refine-only).
412|
413| Pure, deterministic, and **order-independent**: folding the same set of
414| observations always yields the same authoritative outcome regardless of the
415| sequence in which they arrive. Rules, in order:
416|
417| 1. No current outcome — the observation becomes authoritative.
418| 2. Current is sticky — it can never be downgraded; keep it.
419| 3. Observation has strictly stronger attribution
420| (``aborted`` > ``timeout`` > ``failed`` > ``ok``) — refine to it.
421| 4. Equal attribution strength but the observation is sticky while the
422| current writer is not — promote to the sticky observation so a later
423| ``run_budget`` / ``external`` / ``superseded`` of the same kind can no
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
is_sticky(see tables above). - Identify dependent types, protocols, and exceptions referenced by the implementation.
- Search
src/praisonai-tsfor partial implementations under different names (is_sticky, 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
is_stickyis 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 is_sticky 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/**/is_sticky.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/**/is_sticky.test.ts |
| Docs | src/praisonai-ts/PARITY.md (auto-generated) |
Detailed test scenarios
### TS-is_sticky-001 — Export surface
- **Given** a clean install of `praisonai-ts`
- **When** importing `is_sticky` from the package root
- **Then** the symbol is defined and typed (not `any`)
### TS-is_sticky-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-is_sticky-003 — Failure semantics
- **Given** invalid inputs used in Python tests
- **When** invoking TypeScript API
- **Then** reject with equivalent error class / message pattern
### TS-is_sticky-004 — Concurrency / async
- **Given** parallel callers (if applicable)
- **When** stress-testing async entrypoints
- **Then** no lost errors; bounded concurrency matches Python defaults
### TS-is_sticky-005 — Regression guard
- Add a unit test that fails if `is_sticky` disappears from exports (meta-test scanning `index.ts`).
| ID | Scenario | Verification |
|----|----------|--------------|
| export-present | import { is_sticky } 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
- [ ] `is_sticky` 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 `is_sticky` 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 is_sticky
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
is_stickyfor 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 is_sticky?
A: No — consume via praisonai-ts once exported.
Q: Effort says is_sticky 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
is_sticky - 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, merge_run_terminal, 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