diff --git a/.cursor/skills/praisonai-js-hub-intake/SKILL.md b/.cursor/skills/praisonai-js-hub-intake/SKILL.md index 9145e983c..12b2afc09 100644 --- a/.cursor/skills/praisonai-js-hub-intake/SKILL.md +++ b/.cursor/skills/praisonai-js-hub-intake/SKILL.md @@ -1,86 +1,41 @@ --- name: praisonai-js-hub-intake description: >- - Explains Option B hub intake for PraisonAI TypeScript/JavaScript (npm praisonai): - accept TS issues on MervinPraison/PraisonAI, implement fixes in MervinPraison/praisonai-js, - sync to src/praisonai-ts/. Use when routing issues, implementing TS fixes, sync workflows, - merge-gate TS paths, or when the user mentions praisonai-js, praisonai-ts, npm SDK, or TS hub intake. + Explains TypeScript/JavaScript issue and fix routing in the PraisonAI monorepo: + TS issues filed on MervinPraison/PraisonAI, fixes implemented in src/praisonai-ts/. + Use when routing npm/TS issues, merge-gate TS paths, or when the user mentions + praisonai-ts, javascript label, or TypeScript SDK in the monorepo. --- -# praisonai-js hub intake (Option B) +# TypeScript SDK in the PraisonAI monorepo -## Model in one sentence +## Model -**Users file TypeScript issues on [PraisonAI](https://github.com/MervinPraison/PraisonAI); fixes land in [praisonai-js](https://github.com/MervinPraison/praisonai-js); the monorepo `src/praisonai-ts/` is a sync mirror only.** +**Issues and fixes both live in `MervinPraison/PraisonAI`.** TypeScript code path: `src/praisonai-ts/`. -Do **not** ask users to re-file on praisonai-js unless they opened a duplicate on the wrong repo. +Do **not** route TS fixes to external repos in automation prompts. The separate [praisonai-js](https://github.com/MervinPraison/praisonai-js) repo is optional for npm publishing/mirror — not the fix target for hub issues. ## Routing table -| Topic | Report | Fix repo | Monorepo mirror | -|-------|--------|----------|-----------------| -| Python SDK / CLI | PraisonAI | `src/praisonai-agents/`, `src/praisonai/` | — | -| TypeScript / npm `praisonai` | PraisonAI (preferred) or praisonai-js | **praisonai-js** | `src/praisonai-ts/` | -| Cross-language parity | PraisonAI | Often both Python + praisonai-js | sync after TS merge | -| Agent-callable tools | PraisonAI | PraisonAI-Tools | — | -| Lifecycle plugins | PraisonAI | PraisonAI-Plugins | — | - -## End-to-end flow - -``` -Issue on PraisonAI - → issue-triage: labels javascript, praisonai-js (if TS focus) - → claude label → Claude STEP 3-ALT clones praisonai-js - → PR on praisonai-js with body: Fixes MervinPraison/PraisonAI#N - → merge on praisonai-js (CI + merge gate there) - → Sync to PraisonAI Monorepo workflow on praisonai-js - → PR on PraisonAI: sync: update src/praisonai-ts/... -``` +| Topic | Report | Fix path | +|-------|--------|----------| +| Python SDK / CLI | PraisonAI | `src/praisonai-agents/`, `src/praisonai/` | +| TypeScript / npm | PraisonAI | **`src/praisonai-ts/`** | +| Agent-callable tools | PraisonAI | PraisonAI-Tools (external) | +| Lifecycle plugins | PraisonAI | PraisonAI-Plugins (external) | ## Agent rules -1. **Never implement TS features in `src/praisonai-ts/` on PraisonAI** — edit praisonai-js instead. -2. **External PR body** must include `Fixes MervinPraison/PraisonAI#` when fixing a hub issue. -3. **After praisonai-js merge**, run sync workflow (or tell maintainer to): - ```bash - gh workflow run "Sync to PraisonAI Monorepo" \ - --repo MervinPraison/praisonai-js \ - -f upstream_issue= - ``` -4. **Merge gate on PraisonAI** blocks direct `src/praisonai-ts/` changes unless sync PR (title `sync:` or body mentions praisonai-js). -5. **Tests for TS fixes**: `npm install && npm run build && npm test` in praisonai-js clone. +1. TS fixes → edit **`src/praisonai-ts/`** in the monorepo. +2. Read **`src/praisonai-ts/AGENTS.md`** for TS architecture rules. +3. Tests: `cd src/praisonai-ts && npm install && npm run build && npm test`. +4. Merge gate FINAL reviewer: Python + `src/praisonai-ts/` in scope; **no praisonai-js routing line**. +5. External STEP 3-ALT only for Tools, Docs, Plugins — not TS. -## TS issue detection (PraisonAI triage) +## Issue triage -Labels `javascript` + `praisonai-js` when issue mentions: `praisonai-js`, `praisonai-ts`, `src/praisonai-ts`, `typescript`+`praisonai`, `npm`+`praisonai` (not pypi). +`javascript` label when issue mentions typescript, javascript, or npm. -## Key files +## Key automation files -See [reference.md](reference.md) for paths in both repos. - -## Quick commands - -```bash -# Sync Claude secrets to praisonai-js (from PraisonAI hub) -gh workflow run "Sync Claude Secrets" \ - --repo MervinPraison/PraisonAI \ - -f target_repo=MervinPraison/praisonai-js - -# Sync code praisonai-js → monorepo mirror -gh workflow run "Sync to PraisonAI Monorepo" \ - --repo MervinPraison/praisonai-js \ - -f upstream_issue=1234 -``` - -## Related docs - -- Monorepo: `CONTRIBUTING.md` (hub intake table) -- praisonai-js: `AGENTS.md` §2.1.1 Hub intake -- Security: `SECURITY.md` (npm canonical = praisonai-js) - -## Cursor skill locations - -| Repo | Path | -|------|------| -| PraisonAI monorepo | `.cursor/skills/praisonai-js-hub-intake/` | -| praisonai-js | `.cursor/skills/praisonai-js-hub-intake/` | +See [reference.md](reference.md). diff --git a/.cursor/skills/praisonai-js-hub-intake/reference.md b/.cursor/skills/praisonai-js-hub-intake/reference.md index 2c64c6c3c..c64e2fde4 100644 --- a/.cursor/skills/praisonai-js-hub-intake/reference.md +++ b/.cursor/skills/praisonai-js-hub-intake/reference.md @@ -1,72 +1,37 @@ -# praisonai-js hub intake — file reference +# TypeScript SDK — monorepo reference -## PraisonAI monorepo (`MervinPraison/PraisonAI`) +## Fix path -| File | Role | -|------|------| -| `.github/workflows/claude.yml` | Issue triage labels; STEP 3-ALT to praisonai-js; npm test in external flow | -| `.github/scripts/merge-gate.js` | `tsMirrorPathReasons()` blocks non-sync edits to `src/praisonai-ts/` | -| `.github/workflows/claude-merge-gate.yml` | Assess checklist: TS → praisonai-js | -| `.github/scripts/ci-failure-claude.js` | CI fix guardrails include TS routing | -| `.github/actions/claude-code-action/action.yml` | Shared Claude routing (TS → praisonai-js) | -| `.github/praisonai-issue-triage.yaml` | `@praisonai` triage: TS-external routing | -| `.github/workflows/auto-issue-comment.yml` | Auto-triage comment mentions praisonai-js | -| `.github/ISSUE_TEMPLATE/bug_report.md` | Python / TS / cross-language selector | -| `CONTRIBUTING.md` | Hub intake table | -| `SECURITY.md` | npm canonical source = praisonai-js | -| `src/praisonai-ts/` | **Mirror only** — do not implement features here | -| `.cursor/skills/praisonai-js-hub-intake/` | This skill (agent reference) | +`src/praisonai-ts/` — canonical in monorepo. Read `src/praisonai-ts/AGENTS.md`. -### Commits (Option B rollout) +## Automation (no external TS routing) -- `4ab1ed280` — Implement Option B hub intake for praisonai-js TypeScript issues +| File | TS behaviour | +|------|----------------| +| `.github/workflows/claude.yml` | Fix in `src/praisonai-ts/`; STEP 3-ALT = Tools/Docs/Plugins only | +| `.github/scripts/merge-gate.js` | FINAL scope includes `src/praisonai-ts/`; no `tsMirrorPathReasons` block | +| `.github/workflows/claude-merge-gate.yml` | No BLOCK for src/praisonai-ts/ | +| `CONTRIBUTING.md` | TS fixes in monorepo | -## praisonai-js (`MervinPraison/praisonai-js`) - -| File | Role | -|------|------| -| `.github/workflows/sync-to-praisonai.yml` | Rsync to `src/praisonai-ts/`; optional `upstream_issue` input | -| `.github/pull_request_template.md` | `Fixes MervinPraison/PraisonAI#N` + sync checklist | -| `.github/ISSUE_TEMPLATE/bug_report.md` | TS bug template; link to PraisonAI for cross-stack | -| `.github/ISSUE_TEMPLATE/config.yml` | Contact links → PraisonAI for Python/cross-stack | -| `.github/scripts/gate-config.js` | Scope + `externalRepos` hub-intake config | -| `.github/workflows/claude.yml` | Hub caller (Claude automation) | -| `AGENTS.md` §2.1.1 | Hub intake for agents | -| `README.md` | Reporting issues table | -| `.cursor/skills/praisonai-js-hub-intake/` | This skill (agent reference) | - -### Commits - -- `0c8cc3f` — Complete Option B reciprocal hub intake -- `bfc5e34` — Add praisonai-js-hub-intake Cursor skill - -## github-automation-template - -| Item | Role | -|------|------| -| `install.sh --mode hub` | Thin callers on consumer repos | -| `stacks/claude/profiles/sdk/gate-config.js.tmpl` | Base gate config (customise per repo) | -| `AGENTS.md` | Install / rollout guide | - -praisonai-js uses hub mode `@v1.1.0`. - -## Decision tree for agents +## Tests +```bash +cd src/praisonai-ts && npm install && npm run build && npm test ``` -Is the issue about npm / TypeScript / praisonai-js / src/praisonai-ts? -├─ YES → Fix in MervinPraison/praisonai-js (STEP 3-ALT) -│ PR: Fixes MervinPraison/PraisonAI#N -│ After merge: Sync to PraisonAI Monorepo -└─ NO → Is it Python praisonaiagents / praisonai CLI? - ├─ YES → Fix in this monorepo - └─ NO → Tools / Plugins / Docs external repos (see claude.yml STEP 2) -``` + +## External repos (not TS) + +- PraisonAI-Tools — agent-callable tools +- PraisonAI-Plugins — lifecycle plugins +- PraisonAIDocs — documentation ## Anti-patterns | Wrong | Right | |-------|-------| -| Edit `src/praisonai-ts/` for a new TS feature | Edit praisonai-js, then sync | -| Tell user to re-file on praisonai-js only | Accept on PraisonAI; route fix externally | -| Merge gate approves direct TS mirror PR without sync metadata | Title `sync:` or body references praisonai-js | -| Skip `Fixes MervinPraison/PraisonAI#N` on external PR | Always cross-link hub issues | +| Route TS fix to praisonai-js in merge gate / Claude | Fix in `src/praisonai-ts/` | +| Block `src/praisonai-ts/` PRs as "must sync from praisonai-js" | Allow normal TS PRs | + +## Optional: praisonai-js mirror + +Separate repo may mirror for npm; not referenced in issue→fix automation. diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index b065177f1..fc7029055 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -8,7 +8,7 @@ assignees: '' ## SDK / package - [ ] Python (`pip install praisonai` / `praisonaiagents`) -- [ ] TypeScript / JavaScript (`npm install praisonai`) — fixes land in [praisonai-js](https://github.com/MervinPraison/praisonai-js); you can report here or there +- [ ] TypeScript / JavaScript (`npm install praisonai`) — fixes in `src/praisonai-ts/` - [ ] Cross-language / parity (file here on PraisonAI) ## Environment diff --git a/.github/actions/claude-code-action/action.yml b/.github/actions/claude-code-action/action.yml index 6f30ac18d..e176da4a8 100644 --- a/.github/actions/claude-code-action/action.yml +++ b/.github/actions/claude-code-action/action.yml @@ -225,10 +225,10 @@ runs: - CORE vs WRAPPER vs TOOLS vs PLUGINS ROUTING: 1. Core SDK (praisonaiagents/): Only core protocols, base classes, decorators. No heavy implementations. 2. Wrapper (praisonai/): CLI, heavy implementations, optional dependencies. - 3. TypeScript/JavaScript SDK → MervinPraison/praisonai-js: canonical npm repo. Do NOT edit src/praisonai-ts/ here. - 4. Tools → MervinPraison/PraisonAI-Tools: agent-callable integrations at runtime (Composio, Slack, APIs). Do NOT add to praisonaiagents/. - 5. Plugins → MervinPraison/PraisonAI-Plugins: lifecycle extensions (tracing, logging, hooks, guardrails). Not agent tools. - 6. Sandbox backends → PraisonAI-Plugins via `praisonai.sandbox` entry point (core protocol only). + 3. Tools → MervinPraison/PraisonAI-Tools: agent-callable integrations at runtime (Composio, Slack, APIs). Do NOT add to praisonaiagents/. + 4. Plugins → MervinPraison/PraisonAI-Plugins: lifecycle extensions (tracing, logging, hooks, guardrails). Not agent tools. + 5. Sandbox backends → PraisonAI-Plugins via `praisonai.sandbox` entry point (core protocol only). + 6. TypeScript SDK → src/praisonai-ts/ in this monorepo (read src/praisonai-ts/AGENTS.md for TS rules). - Does it duplicate existing functionality? Check if Agent already supports this via existing params (reflection, planning, tools, hooks, memory). - Do not bloat the Agent class with additional params — only if absolutely required; we already support many params. - Does it inherit from Agent properly? New agent types MUST inherit Agent, not wrap it with composition. diff --git a/.github/praisonai-issue-triage.yaml b/.github/praisonai-issue-triage.yaml index d51b76dca..c8cda11f6 100644 --- a/.github/praisonai-issue-triage.yaml +++ b/.github/praisonai-issue-triage.yaml @@ -35,7 +35,7 @@ steps: Third, read architecture guidelines: execute_command 'cat src/praisonai-agents/AGENTS.md'. Fourth, decide routing before planning: - - TypeScript/JavaScript SDK → MervinPraison/praisonai-js: canonical npm repo. Do NOT edit src/praisonai-ts/ in this monorepo. Cross-link upstream issue in external PR body: Fixes MervinPraison/PraisonAI#N. + - TypeScript/JavaScript SDK → src/praisonai-ts/ in this monorepo (read src/praisonai-ts/AGENTS.md). - Tools → PraisonAI-Tools: agent-callable integrations at runtime (Composio, Slack, APIs). - Plugins → PraisonAI-Plugins: lifecycle extensions (tracing, logging, hooks, guardrails). - Sandbox backends → PraisonAI-Plugins via `praisonai.sandbox` entry point. @@ -45,7 +45,7 @@ steps: - If YES: identify the exact files and lines that must change. Output a concrete file-level plan. - If NO (question, discussion, duplicate, invalid): say so clearly. No code changes needed. - Output: routing decision (Core / Wrapper / TS-external / Tools-external / Plugins-external / No-change), validation result, and exact files/lines to change. + Output: routing decision (Core / Wrapper / TS-monorepo / Tools-external / Plugins-external / No-change), validation result, and exact files/lines to change. expected_output: A decision on whether code changes are needed, and if so a concrete file-level plan. - name: Implement Fix diff --git a/.github/scripts/ci-failure-claude.js b/.github/scripts/ci-failure-claude.js index fb1777f4e..99b5dc1fe 100644 --- a/.github/scripts/ci-failure-claude.js +++ b/.github/scripts/ci-failure-claude.js @@ -157,7 +157,6 @@ function buildCiFixComment({ headSha, failedChecks, failureSummaries }) { '3. **Pre-existing flake or unrelated failure** — say so explicitly; prefer fixing the root cause over masking it.', '', '**SDK guardrails (AGENTS.md):**', - '- TypeScript/JavaScript SDK → MervinPraison/praisonai-js (not src/praisonai-ts/ in this monorepo).', '- Agent-callable tools → PraisonAI-Tools; lifecycle plugins → PraisonAI-Plugins; sandbox backends → PraisonAI-Plugins (`praisonai.sandbox`) — not praisonaiagents/.', '- Do not disturb core SDK contracts to accommodate a wrapper/feature change.', '- Tests must continue to guard backward compatibility and hot-path behaviour — passing CI by lowering test standards is not acceptable.', diff --git a/.github/scripts/merge-gate.js b/.github/scripts/merge-gate.js index 9e23134e6..bf13a651a 100644 --- a/.github/scripts/merge-gate.js +++ b/.github/scripts/merge-gate.js @@ -308,7 +308,7 @@ function finalClaudeCompletedOnSha(comments, headPushedAt) { } const FINAL_CLAUDE_REVIEW_BODY = - '@claude You are the FINAL architecture reviewer. If the branch is under MervinPraison/PraisonAI (not a fork), you are able to make modifications to this branch and push directly. SCOPE: Focus ONLY on Python packages (praisonaiagents, praisonai). Do NOT modify src/praisonai-rust or src/praisonai-ts in this repo — TypeScript SDK work belongs in MervinPraison/praisonai-js. Read ALL comments above from Gemini, Qodo, CodeRabbit, and Copilot carefully before responding.\n\n**Phase 1: Review per AGENTS.md**\n1. Protocol-driven: check heavy implementations vs core SDK\n2. Backward compatible: ensure zero feature regressions\n3. Performance: no hot-path regressions\n4. SDK value: review in depth whether the change genuinely adds value to the SDK — never add features for the sake of adding them. It must strengthen the SDK (simpler, more user-friendly, robust, world-class, secure). If it does not clearly add value, request changes or recommend rejecting/closing rather than merging scope creep\n5. Do not bloat the Agent class with additional params — only if absolutely required; we already support many params.\n6. Repo routing: TypeScript/JavaScript SDK → praisonai-js (not src/praisonai-ts/ here); agent-callable tools → PraisonAI-Tools; lifecycle plugins → PraisonAI-Plugins; optional sandbox backends → PraisonAI-Plugins (`praisonai.sandbox` entry point) — request changes if wrongly added to praisonaiagents/\n\n**Phase 2: FIX Valid Issues**\n7. For any VALID bugs or architectural flaws found by Gemini, CodeRabbit, Qodo, Copilot, or any other reviewer: implement the fix\n8. Also independently identify and fix any gaps or issues you find in the changed code — do not rely only on prior reviewer feedback\n9. Push all code fixes directly to THIS branch (do NOT create a new PR)\n10. Comment a summary of exact files modified and what you skipped\n\n**Phase 3: Final Verdict**\n11. If all issues are resolved, approve the PR / close the Issue\n12. If blocking issues remain, request changes / leave clear action items'; + '@claude You are the FINAL architecture reviewer. If the branch is under MervinPraison/PraisonAI (not a fork), you are able to make modifications to this branch and push directly. SCOPE: Review changes in this PR. Python SDK: praisonaiagents, praisonai. TypeScript SDK: src/praisonai-ts/. Do NOT modify src/praisonai-rust. Read ALL comments above from Gemini, Qodo, CodeRabbit, and Copilot carefully before responding.\n\n**Phase 1: Review per AGENTS.md**\n1. Protocol-driven: check heavy implementations vs core SDK\n2. Backward compatible: ensure zero feature regressions\n3. Performance: no hot-path regressions\n4. SDK value: review in depth whether the change genuinely adds value to the SDK — never add features for the sake of adding them. It must strengthen the SDK (simpler, more user-friendly, robust, world-class, secure). If it does not clearly add value, request changes or recommend rejecting/closing rather than merging scope creep\n5. Do not bloat the Agent class with additional params — only if absolutely required; we already support many params.\n6. Repo routing: agent-callable tools → PraisonAI-Tools; lifecycle plugins → PraisonAI-Plugins; optional sandbox backends → PraisonAI-Plugins (`praisonai.sandbox` entry point) — request changes if wrongly added to praisonaiagents/\n\n**Phase 2: FIX Valid Issues**\n7. For any VALID bugs or architectural flaws found by Gemini, CodeRabbit, Qodo, Copilot, or any other reviewer: implement the fix\n8. Also independently identify and fix any gaps or issues you find in the changed code — do not rely only on prior reviewer feedback\n9. Push all code fixes directly to THIS branch (do NOT create a new PR)\n10. Comment a summary of exact files modified and what you skipped\n\n**Phase 3: Final Verdict**\n11. If all issues are resolved, approve the PR / close the Issue\n12. If blocking issues remain, request changes / leave clear action items'; async function getMergeState(github, owner, repo, prNumber) { const query = ` @@ -600,24 +600,6 @@ function hasManualOnlyLabel(labels) { return labels.some((l) => MANUAL_ONLY_LABELS.has(l)); } -const TS_MIRROR_PREFIX = 'src/praisonai-ts/'; - -function tsMirrorPathReasons(files, pr) { - const touchesTs = files.some((f) => f.filename.startsWith(TS_MIRROR_PREFIX)); - if (!touchesTs) return []; - const title = (pr.title || '').toLowerCase(); - const body = (pr.body || '').toLowerCase(); - const isSyncPr = - title.startsWith('sync:') || - body.includes('sync from praisonai-js') || - body.includes('praisonai-js') || - body.includes('mervinpraison/praisonai-js'); - if (isSyncPr) return []; - return [ - 'src/praisonai-ts/ changed outside praisonai-js sync — implement in MervinPraison/praisonai-js, then run Sync to PraisonAI Monorepo workflow', - ]; -} - function sensitivePathReasons(files, labels = []) { if (labels.includes(WORKFLOW_ONLY_LABEL) && isCiOnlyChange(files)) { return []; @@ -841,7 +823,6 @@ async function evaluatePipelineQuiescent(github, owner, repo, prNumber, core, op if (agentManual) reasons.push(agentManual); reasons.push(...sensitivePathReasons(pullFiles, ctx.labels)); - reasons.push(...tsMirrorPathReasons(pullFiles, ctx.pr)); reasons.push(...prSizeReasons(pullFiles)); reasons.push(...secretScanReasons(pullFiles)); @@ -1008,7 +989,6 @@ module.exports = { touchesSdk, hasManualOnlyLabel, sensitivePathReasons, - tsMirrorPathReasons, prSizeReasons, missingTestsReason, secretScanReasons, diff --git a/.github/workflows/auto-issue-comment.yml b/.github/workflows/auto-issue-comment.yml index 465166036..95f81fd2c 100644 --- a/.github/workflows/auto-issue-comment.yml +++ b/.github/workflows/auto-issue-comment.yml @@ -42,5 +42,5 @@ jobs: issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, - body: '🤖 Auto-triaging with Claude. Analyzing issue and implementing a fix...\n\nClaude will:\n1. Route correctly: TypeScript/JavaScript SDK → praisonai-js; agent tools → PraisonAI-Tools; lifecycle plugins → PraisonAI-Plugins\n2. Search codebase for root cause\n3. Implement a minimal fix following AGENTS.md\n4. Create a PR with the changes (external repo PRs link back to this issue)' + body: '🤖 Auto-triaging with Claude. Analyzing issue and implementing a fix...\n\nClaude will:\n1. Route correctly: TypeScript → src/praisonai-ts/; agent tools → PraisonAI-Tools; lifecycle plugins → PraisonAI-Plugins\n2. Search codebase for root cause\n3. Implement a minimal fix following AGENTS.md\n4. Create a PR with the changes' }); \ No newline at end of file diff --git a/.github/workflows/claude-merge-gate.yml b/.github/workflows/claude-merge-gate.yml index e0699ebd8..2cc56f9c7 100644 --- a/.github/workflows/claude-merge-gate.yml +++ b/.github/workflows/claude-merge-gate.yml @@ -289,7 +289,7 @@ jobs: 1. Read AGENTS.md and the PR diff on the current branch. 2. Read all PR comments and reviews (FINAL architecture reviewer / Lead Engineer must have run). 3. Confirm SDK value gate: change strengthens praisonaiagents (no scope creep). The aim is a LIGHTWEIGHT AND POWERFUL package — BLOCK changes that add params/modules/exports duplicating existing Agent capabilities (instructions/backstory/tools/hooks/memory), or add knobs/fields with no live consumer, i.e. scope creep for the sake of it. - 4. Repo routing: BLOCK if TypeScript/JavaScript SDK changes in src/praisonai-ts/ (→ praisonai-js + sync workflow); agent-callable tools (→ PraisonAI-Tools); lifecycle plugins (→ PraisonAI-Plugins); or optional sandbox backends (→ PraisonAI-Plugins via `praisonai.sandbox`) were added to praisonaiagents/ instead of the external repo. + 4. Repo routing: BLOCK if agent-callable tools (→ PraisonAI-Tools), lifecycle plugins (→ PraisonAI-Plugins), or optional sandbox backends (→ PraisonAI-Plugins via `praisonai.sandbox`) were added to praisonaiagents/ instead of the external repo. 5. Do not bloat the Agent class with additional params — only if absolutely required; we already support many params. 6. If agent.py adds >100 lines or new Agent __init__ params, respond MERGE_GATE_VERDICT: BLOCK (manual review required). 7. BLOCK if labels security/breaking-change/needs-manual-review/release, sensitive paths (.github/workflows, auth, pyproject.toml), secrets in diff, PR >800 lines or >30 files, or SDK changes without tests. Label `merge-gate-ci-only` exempts CI-only changes under `.github/workflows/`, `.github/actions/`, or merge-gate scripts. diff --git a/.github/workflows/claude.yml b/.github/workflows/claude.yml index 608a57422..5cb7aceac 100644 --- a/.github/workflows/claude.yml +++ b/.github/workflows/claude.yml @@ -70,21 +70,9 @@ jobs: if (content.includes('documentation') || content.includes('docs')) { labels.push('documentation'); } - const isPraisonaiJsFocus = - content.includes('praisonai-js') || - content.includes('praisonai-ts') || - content.includes('src/praisonai-ts') || - content.includes('typescript sdk') || - content.includes('javascript sdk') || - (content.includes('typescript') && content.includes('praisonai')) || - (content.includes('javascript') && content.includes('praisonai')) || - (content.includes('npm') && content.includes('praisonai') && !content.includes('pypi')); - if (isPraisonaiJsFocus || content.includes('typescript') || content.includes('javascript') || content.includes('npm')) { + if (content.includes('typescript') || content.includes('javascript') || content.includes('npm')) { labels.push('javascript'); } - if (isPraisonaiJsFocus) { - labels.push('praisonai-js'); - } // Apply labels if (labels.length > 0) { @@ -112,7 +100,7 @@ jobs: '', '_Bug and enhancement reports are auto-triaged with Claude. Questions and other issues: a maintainer can comment `@claude` to trigger analysis._', '', - '**Routing:** TypeScript/JavaScript SDK → [praisonai-js](https://github.com/MervinPraison/praisonai-js) (canonical; monorepo `src/praisonai-ts/` is synced from there). Agent-callable tools → [PraisonAI-Tools](https://github.com/MervinPraison/PraisonAI-Tools); lifecycle plugins (tracing/hooks/guardrails) → [PraisonAI-Plugins](https://github.com/MervinPraison/PraisonAI-Plugins).' + '**Routing:** Agent-callable tools → [PraisonAI-Tools](https://github.com/MervinPraison/PraisonAI-Tools); lifecycle plugins (tracing/hooks/guardrails) → [PraisonAI-Plugins](https://github.com/MervinPraison/PraisonAI-Plugins). TypeScript/JavaScript SDK fixes land in `src/praisonai-ts/` in this repo.' ].join('\n') }); } @@ -305,7 +293,7 @@ jobs: STEP 1 — READ GUIDELINES: Read AGENTS.md to understand the architecture rules. - SCOPE: Focus ONLY on Python packages (praisonaiagents, praisonai). Do NOT modify praisonai-rust or src/praisonai-ts in this repo — TypeScript/JavaScript SDK work belongs in MervinPraison/praisonai-js (STEP 3-ALT). + SCOPE: Python SDK (praisonaiagents, praisonai) and TypeScript SDK (src/praisonai-ts/) live in this monorepo. Do NOT modify src/praisonai-rust. For TS issues read src/praisonai-ts/AGENTS.md. AIM: This package must stay LIGHTWEIGHT AND POWERFUL. Do a CRITICAL REVIEW at each stage (issue triage, fix planning, PR review/implementation) and reject scope creep for the sake of adding features. Prefer existing Agent capabilities (instructions/backstory/tools/hooks/memory) over new params/modules/exports. Even when fixing a raised issue, keep the fix minimal and lightweight — do NOT expand the surface area or add knobs with no live consumer. STEP 2 — ARCHITECTURE VALIDATION & ROUTING (MANDATORY before writing code): @@ -317,8 +305,8 @@ jobs: 4. Documentation (PraisonAIDocs): Documentation pages, guides, API references. 5. Plugins → MervinPraison/PraisonAI-Plugins: framework lifecycle extensions (tracing, logging, metrics, hooks, guardrails). Not agent tools — use STEP 3-ALT. 6. Sandbox backends (optional/niche, e.g. Capsule) → PraisonAI-Plugins via `praisonai.sandbox` entry point; core keeps protocol/config/manager only. - 7. TypeScript/JavaScript SDK → MervinPraison/praisonai-js: canonical npm SDK repo. Do NOT implement in src/praisonai-ts/ here — clone praisonai-js and use STEP 3-ALT. After merge there, run **Sync to PraisonAI Monorepo** workflow to update src/praisonai-ts/. - For items routed to an EXTERNAL repository (Tools, Docs, Plugins, praisonai-js), follow STEP 3-ALT below. + 7. TypeScript/JavaScript SDK → src/praisonai-ts/ in this monorepo (not praisonaiagents/). + For items routed to an EXTERNAL repository (Tools, Docs, Plugins), follow STEP 3-ALT below. - Does it duplicate existing functionality? Check if Agent already supports this via existing params (reflection, planning, tools, hooks, memory). If it does, reject the change as scope creep and prefer the existing capability — the aim is lightweight and powerful, not more knobs. - Do not bloat the Agent class with additional params — only if absolutely required; we already support many params. - Does it inherit from Agent properly? New agent types MUST inherit Agent, not wrap it with composition. @@ -331,7 +319,7 @@ jobs: ${{ steps.check_fork.outputs.is_pr == 'true' && (steps.check_fork.outputs.is_fork != 'true' || steps.check_fork.outputs.can_push_fork == 'true') && steps.check_fork.outputs.merge_state != 'DIRTY' && format('STEP 3 — IMPLEMENT ON EXISTING PR (branch: {0}, PR #{1}{2}):\n- DO NOT create a new branch or PR\n- git checkout {0}\n- Implement minimal, focused fixes from reviewer feedback\n- Follow protocol-driven design: protocols in core SDK, heavy implementations in wrapper\n- Keep changes small and backward-compatible\n- Commit: git add -A && git commit -m "fix: "\n- Push: git push origin {0}\n- Comment a summary of exact files modified and what you skipped\n', steps.check_fork.outputs.pr_branch, steps.check_fork.outputs.pr_number, steps.check_fork.outputs.can_push_fork == 'true' && format(', fork: {0}', steps.check_fork.outputs.fork_repo) || '') || '' }} ${{ steps.check_fork.outputs.is_pr != 'true' && 'STEP 3 — IMPLEMENT (for changes in THIS repo — PraisonAI):\n- Create a fix branch: git checkout -b claude/issue-$ISSUE_NUMBER-$(date +%Y%m%d)\n- Implement a minimal, focused fix\n- Follow protocol-driven design: protocols in core SDK, heavy implementations in wrapper\n- Keep changes small and backward-compatible\n- Commit: git add -A && git commit -m "fix: (fixes #$ISSUE_NUMBER)"\n- Push: git push origin claude/issue-$ISSUE_NUMBER-$(date +%Y%m%d)\nCRITICAL: After pushing, you MUST immediately run: gh pr create --title "fix: " --body "Fixes #$ISSUE_NUMBER" --head claude/issue-$ISSUE_NUMBER-$(date +%Y%m%d)\nDo NOT stop after pushing. Do NOT say "manually create a PR". Always create the PR automatically.\n' || '' }} - STEP 3-ALT — IMPLEMENT IN EXTERNAL REPO (for PraisonAI-Tools, PraisonAIDocs, PraisonAI-Plugins, praisonai-js): + STEP 3-ALT — IMPLEMENT IN EXTERNAL REPO (for PraisonAI-Tools, PraisonAIDocs, PraisonAI-Plugins): When work must happen in a different repository, follow these steps EXACTLY. Do NOT attempt to use `cd`, as directory state is not preserved. Use `git -C` for all commands. a) Clone the repository: gh repo clone MervinPraison/<REPO_NAME> /tmp/<REPO_NAME> @@ -349,11 +337,11 @@ jobs: gh pr create -R MervinPraison/<REPO_NAME> --head claude/issue-$ISSUE_NUMBER-$(date +%Y%m%d) --title "feat: <title>" --body "Fixes MervinPraison/PraisonAI#$ISSUE_NUMBER <body>" - h) Comment on THIS PraisonAI issue with the external PR URL. For praisonai-js: note that after merge, a maintainer runs **Sync to PraisonAI Monorepo** on praisonai-js (Actions → sync workflow) to update src/praisonai-ts/. + h) Comment on THIS PraisonAI issue with the external PR URL. STEP 4 — TEST: - - For SDK changes: cd src/praisonai-agents && PYTHONPATH=. python -m pytest tests/ -x -q --timeout=30 - - For praisonai-js: cd /tmp/praisonai-js && npm install && npm run build && npm test + - For Python SDK changes: cd src/praisonai-agents && PYTHONPATH=. python -m pytest tests/ -x -q --timeout=30 + - For TypeScript SDK changes: cd src/praisonai-ts && npm install && npm run build && npm test - For docs changes: verify files exist and are valid markdown/MDX - Ensure no regressions diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ddd470efa..905013da2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,21 +7,19 @@ Thank you for your interest! Here's how to get started: 3. Make your changes 4. Submit a pull request -## Where to report issues (hub intake) +## Where to report issues | Topic | Report here | Where fixes land | |-------|-------------|------------------| -| Python SDK, CLI, wrapper | **This repo** ([PraisonAI](https://github.com/MervinPraison/PraisonAI)) | `src/praisonai-agents/`, `src/praisonai/` | -| TypeScript / JavaScript SDK (`npm install praisonai`) | **This repo** (preferred) or [praisonai-js](https://github.com/MervinPraison/praisonai-js) | [praisonai-js](https://github.com/MervinPraison/praisonai-js) → synced to `src/praisonai-ts/` | -| Cross-language parity | **This repo** | Often both Python and praisonai-js PRs | +| Python SDK, CLI, wrapper | **This repo** | `src/praisonai-agents/`, `src/praisonai/` | +| TypeScript / JavaScript (`npm install praisonai`) | **This repo** | `src/praisonai-ts/` | +| Cross-language parity | **This repo** | Often both Python and TypeScript paths | | Agent-callable tools | **This repo** | [PraisonAI-Tools](https://github.com/MervinPraison/PraisonAI-Tools) | | Lifecycle plugins (tracing, hooks, guardrails) | **This repo** | [PraisonAI-Plugins](https://github.com/MervinPraison/PraisonAI-Plugins) | -You do **not** need to re-file TypeScript issues on praisonai-js — report on PraisonAI and automation routes fixes to the canonical TS repo. - ## Guidelines - Follow existing code style - Add tests for new features - Update documentation as needed -- TypeScript changes: implement in [praisonai-js](https://github.com/MervinPraison/praisonai-js), then run **Sync to PraisonAI Monorepo** workflow to update `src/praisonai-ts/` +- TypeScript changes: implement in `src/praisonai-ts/` and run `npm test` there diff --git a/SECURITY.md b/SECURITY.md index 8cceb9aaf..5c9156404 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -8,9 +8,7 @@ PraisonAI takes security seriously. We appreciate responsible disclosure from re |---------|----------|-------------| | `praisonaiagents` | [PyPI](https://pypi.org/project/praisonaiagents/) | `src/praisonai-agents/` | | `praisonai` | [PyPI](https://pypi.org/project/praisonai/) | `src/praisonai/` | -| `praisonai` | [npm](https://www.npmjs.com/package/praisonai) | [praisonai-js](https://github.com/MervinPraison/praisonai-js) (canonical); mirrored at `src/praisonai-ts/` | - -Report npm/TypeScript vulnerabilities on **PraisonAI** (hub intake) or [praisonai-js](https://github.com/MervinPraison/praisonai-js). Fixes land in praisonai-js first. +| `praisonai` | [npm](https://www.npmjs.com/package/praisonai) | `src/praisonai-ts/` | Report issues against the **specific package** where the vulnerability exists. A platform-only issue does not necessarily affect the core SDK, and vice versa.