@tera-system/core 0.2.20 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,93 @@
1
+ # Technology Profile: node-ts-coolify-postgres
2
+
3
+ > **Status:** APPROVED — approved by Majed 2026-09-15 (response: «اعتمد»).
4
+ > **Active for:** APP-DISCOVERY-SURVEY (CLIENT-TERANOO-INTERNAL) as of 2026-09-15.
5
+ > **First consumer:** APP-DISCOVERY-SURVEY (CLIENT-TERANOO-INTERNAL) — reusable for small internal Node+TS tools on Coolify + Postgres.
6
+
7
+ ## 1. Profile Identity
8
+
9
+ - Profile ID: `node-ts-coolify-postgres`
10
+ - Language: TypeScript (strict) on Node.js 20+
11
+ - Framework: None (existing host app code — e.g. `tera-website`: `tsx server/index.ts` :3001). No new framework unless task requires it.
12
+ - Database: PostgreSQL 17-alpine as separate Coolify service (never shared with another app's DB).
13
+ - ORM: Decided per project at first DB task (default recommendation: Prisma — migrations + seed; alternatives: Drizzle / raw SQL via `pg`). No lock at profile level.
14
+ - Package Manager / CLI: npm (+ `npx`) / Coolify (Nixpacks: `npm ci` + `npm run build`) / GitHub flow (branch → master → Coolify redeploy).
15
+ - Default Project Type: Small internal web tool mounted inside an existing Node+TS app folder (Track A).
16
+
17
+ ## 2. Applicability
18
+
19
+ Use when: (a) the host is an existing Node+TS app deployed on Coolify via Nixpacks; (b) persistence is a dedicated Postgres 17 service; (c) scope is a small internal MVP (no public signup, single-admin or token-gated access).
20
+ Do NOT use for: .NET/Blazor stacks, Flutter/mobile, Phaser games, public multi-tenant SaaS (needs stronger tenancy review first).
21
+
22
+ ## 3. Default Execution Order
23
+
24
+ ```text
25
+ Profile lock → Auth gate (if admin area) → DB service + migrations + seed + isolation check
26
+ → Token/access → Forms/workflows → Dashboard/admin → Export/print
27
+ → Ops (retention/cron/domain/SSL) → Acceptance (T-*) → Phase 7 closure
28
+ Prototype (mock, no DB) always precedes real implementation unless WAIVED_BY_MAJED.
29
+ ```
30
+
31
+ ## 4. First Task Rule
32
+
33
+ Safest first task: **isolated mock prototype** (`TASK-PROTO-*`, no DB, no secrets, no deploy) rendered from the approved Design Source, reviewed by DesignReviewer, approved by owner (Gate 6) — before any `TASK-COD-*`.
34
+
35
+ ## 5. Scaffold Rules
36
+
37
+ - No new Coolify Application for Track-A tools — modify inside the existing app folder only (`app/`), same pipeline, same repo branch.
38
+ - No new framework/scaffolder by default. New files live in the task's Allowed Write Targets (absolute paths) — never outside.
39
+ - Reuse host app conventions first (read existing code before adding files). Follow the Engineering File Quality mandate: semantic folders, no junk-drawer `utils/`, no mixed responsibilities, non-generated files > ~500 lines need justification or splitting, WHY-comments, no dead code.
40
+
41
+ ## 6. ORM / Database Rules
42
+
43
+ - One dedicated database per tool (`tera-internal-db` pattern). DSN via Env/Coolify secrets only — never in repo, never logged.
44
+ - **Pre-deploy DSN check is mandatory before every deploy:** the DSN must point exclusively at the tool's own DB (prevents writes to foreign DBs such as `bustan_db`). Violation = immediate stop.
45
+ - Destructive deletes use `ON DELETE RESTRICT` + soft-delete first; `audit_log` tables are append-only (no UPDATE/DELETE).
46
+ - Migrations + seed are code-reviewed; seed data comes only from approved preparation inventory (e.g. literal field keys).
47
+
48
+ ## 7. CLI Side Effects
49
+
50
+ | Command | Side effect | Rule |
51
+ |---|---|---|
52
+ | `npm install <pkg>` | modifies `package.json`/`package-lock.json` | allowed only inside task scope; no PDF libs in MVP unless task says so |
53
+ | `npx prisma migrate dev --name X` | creates migration + touches DB | local/tool DB only; never against foreign DSN |
54
+ | `npx prisma db seed` | writes rows | seed file must match approved inventory exactly |
55
+ | `git add/commit/push` | publishes | commit message concise; **push only after Majed approval**; no force-push, no amend |
56
+ | Coolify service create / domain attach / schedule | infra change | Majed permission at deploy time; recorded in task file |
57
+
58
+ ## 8. Forbidden Defaults
59
+
60
+ - No plaintext secrets/tokens/passwords/hashes-of-record in repo, logs, screenshots, or task files (`[REDACTED]` only; values live in Env/Coolify secrets).
61
+ - No storing raw single-use tokens — hash-only (SHA-256 + Env pepper).
62
+ - No public/unsigned links for private data; no new auth system when an ADR already decided auth (reuse of a session-less marketing site's auth is forbidden — see ADR-01 pattern).
63
+ - No invented field keys/labels — payload keys must equal the approved template ids literally.
64
+ - No API write path outside explicitly allowed columns (pattern: CR-001 — anything else → 422 + audit entry).
65
+ - No PDF generation library in MVP unless explicitly tasked.
66
+ - No `utils/`/`helpers/`/`common/` junk drawers; no file mixing UI + logic + data + auth.
67
+
68
+ ## 9. Pre-Execution Gate Additions
69
+
70
+ Extends `TeraPreExecutionGate.md` for this profile — all must PASS before any `TASK-COD-*` delegation:
71
+
72
+ 1. `PROFILE_APPROVED = PASS` (Majed approved this Draft).
73
+ 2. `GATE6_PROTO_APPROVED = PASS` (prototype approval letter filed) — unless WAIVED_BY_MAJED.
74
+ 3. `DSN_ISOLATION_PLAN = PASS` (task names the tool's own DB; pre-deploy check step included).
75
+ 4. `SECRETS_PLAN = PASS` (all secrets named as Env/Coolify-secret names with zero values).
76
+ 5. `SCOPE_LOCK = PASS` (task maps to locked scope items only; deferred/excluded items absent).
77
+ 6. `WRITE_TARGETS_ABSOLUTE = PASS` (absolute paths or explicit `ClientAppPath`-relative).
78
+
79
+ ## 10. Acceptance Criteria Patterns
80
+
81
+ - Token/access: single-use display of raw secret, hash-only storage, expiry enforced, revoke kills immediately, single-active invariant, rate-limit returns 429 + audit.
82
+ - Forms: literal field inventory match (order/labels/keys), autosave draft recoverable, submit requires only the approved mandatory fields, completion % = answered-active / active.
83
+ - Admin: unauthenticated `/admin/*` rejected, login rate-limited with temporary ban + audit, respondent isolation (no cross-record access).
84
+ - Data: zero writes to foreign DBs (verified), submitted records never purged, audit entries for every sensitive action.
85
+ - Export/print: valid JSON + clean RTL print (nav/buttons/filters hidden, no broken sections).
86
+ - Ops: old drafts purged per N, expired links read-only, domain serves HTTPS with redirect, `git diff --check` clean.
87
+
88
+ ## Decision Request
89
+
90
+ ```text
91
+ To Majed: approve this Draft as the Active Technology Profile for APP-DISCOVERY-SURVEY (yes / amend / reject).
92
+ On approval: TeraAgent locks ORM choice at TASK-COD-02 and proceeds under this profile.
93
+ ```
@@ -1,6 +1,6 @@
1
1
  # Tera Runtime Protocols — Knowledge Management
2
2
 
3
- This file now contains **Section 19** (Project Knowledge Management Protocol) after the INS-02 continuation split (2026-08-01).
3
+ This file now contains **Section 19 ONLY** (Project Knowledge Management Protocol) after the INS-02 continuation split (2026-08-01). It is NOT the protocols master — for Sections 1–11 see `TERA_RUNTIME_PROTOCOLS_CORE.md`, for 12–18 see `TERA_RUNTIME_PROTOCOLS_CLIENT.md` (SCP-2026-09-16-003).
4
4
 
5
5
  ## Split Notice
6
6
 
@@ -43,6 +43,7 @@ Reference Files:
43
43
  Required Sections:
44
44
  Allowed Write Targets:
45
45
  Forbidden Files / Actions:
46
+ Tool Escalation: إن احتجت أداة خارج صلاحياتك → توقف واطلبها مني (لا تُكمل بأدلة ناقصة صامتة، ولا ترحّل الفجوة للمالك) — GAP-013
46
47
  Token Budget: Low / Medium / High / Critical
47
48
  Model Tier Recommendation: Light / Medium / Strong
48
49
  Minimum Acceptable Model Tier: Light / Medium / Strong
@@ -886,15 +887,15 @@ See `TERA_RUNTIME_PROTOCOLS_CLIENT.md` Section 18, Client Discovery Step 7 for t
886
887
 
887
888
  ## 27. Project Preparation Plan (Phase 3 Output)
888
889
 
889
- > ?? **������� ��� ������ (SCP-2026-07-28-118).** ������ ������ ���� ��:
890
- > `tera-system/runtime/TERA_SOLUTION_PREPARATION_TEMPLATES.md` �2 � Preparation Plan Template
890
+ > ⚠️ **مصدر التغيير (SCP-2026-07-28-118).** هذا القالب انتقل إلى:
891
+ > `tera-system/runtime/TERA_SOLUTION_PREPARATION_TEMPLATES.md` §2 — Preparation Plan Template
891
892
 
892
893
  ---
893
894
 
894
895
  ## 28. Agent Delegation Plan (Phase 4 Output)
895
896
 
896
- > ?? **������� ��� ������ (SCP-2026-07-28-118).** ������ ������ ���� ��:
897
- > `tera-system/runtime/TERA_SOLUTION_PREPARATION_TEMPLATES.md` �3 � Agent Delegation Plan Template
897
+ > ⚠️ **مصدر التغيير (SCP-2026-07-28-118).** هذا القالب انتقل إلى:
898
+ > `tera-system/runtime/TERA_SOLUTION_PREPARATION_TEMPLATES.md` §3 — Agent Delegation Plan Template
898
899
 
899
900
  ---
900
901
 
@@ -154,6 +154,8 @@ The generated file is saved to `project-control/EXECUTION_BATCH_PLAN.md`.
154
154
  | TASK-COD-002 | [e.g. Init ORM + DB] | EngineeringAgent | `prisma/schema.prisma`, `.env.example` | PASS |
155
155
  | ... | ... | ... | ... | ... |
156
156
 
157
+ > **قاعدة قياسية لكل مهمة (GAP-013):** إن احتاج الوكيل أداة خارج صلاحياته → توقف + اطلبها من Tera — لا يُكمل بأدلة ناقصة صامتة، ولا يرحّل الفجوة للمالك. (راجع `TERA_RUNTIME_TEMPLATES.md` §2 — Tool Escalation)
158
+
157
159
  ## 3. Not Included (Deferred to Later Batches)
158
160
 
159
161
  | Item | Reason | Expected Batch |
@@ -585,3 +587,60 @@ clients/CLIENT-[client-name-or-id]/applications/APP-[app-name-or-id]/delivery/CL
585
587
  - سجّل نتيجة الاختبار (تاريخ، نجاح/فشل) في وثائق التسليم.
586
588
 
587
589
  ---
590
+
591
+ ## 39. TERA Audit Trail Entry Template (moved from tera.md §26 — SCP-2026-09-16-004)
592
+
593
+ Operational core stays in `tera.md` §26 (file, sole owner, when in brief, minimum fields, closure gate). This section holds the full record-once reference: event list + entry structure + evidence guidance.
594
+
595
+ ### 39.1 When to Record (substantive events only)
596
+
597
+ Record an entry only at these events:
598
+ 1. Phase start
599
+ 2. Phase end
600
+ 3. Gate PASS / FAIL
601
+ 4. Execution Plan / Batch Plan created or approved
602
+ 5. `TASK-COD-*` created
603
+ 6. Task delegated to an agent
604
+ 7. Handback received from an agent
605
+ 8. Handback rejected / rework requested
606
+ 9. QA / Auditor / Reviewer invoked
607
+ 10. QA / Audit / Review result that affects a decision
608
+ 11. Owner decision or clarification that affects execution
609
+ 12. Open Item status change
610
+ 13. Scope Change Request
611
+ 14. Governance violation discovered
612
+ 15. Dependency or batch-order change
613
+ 16. TASK closed
614
+ 17. Batch accepted or rejected
615
+ 18. Phase 5 → 6 transition
616
+ 19. Phase 6 → 7 transition
617
+ 20. Final delivery / closure
618
+
619
+ Do **NOT** record: every file read, grep, shell command, internal message, minor failed attempt, small bug fix, or line edit. Record only events with value for governance, delegation, decision-making, quality, traceability, phase control, scope control, or accountability.
620
+
621
+ ### 39.2 Entry Structure
622
+
623
+ Fields (not all mandatory for every event):
624
+ - Audit ID (`AUD-0001`, `AUD-0002`, … — sequential, zero-padded, one format only)
625
+ - Timestamp
626
+ - Phase
627
+ - Event Type
628
+ - Actor
629
+ - Target
630
+ - Related Task / Batch
631
+ - Source of Truth
632
+ - Action Taken
633
+ - Decision
634
+ - Reason
635
+ - Evidence
636
+ - Gate Result
637
+ - Owner Approval Required
638
+ - Owner Approval Status
639
+ - Next Step
640
+
641
+ **Mandatory minimum per entry:** Audit ID, Timestamp, Phase, Event Type, Actor, Action Taken, Evidence (or Reference), Next Step. Never write an entry without these.
642
+
643
+ ### 39.3 Evidence
644
+
645
+ Point to real evidence wherever possible — never just "done successfully":
646
+ - file path, `TASK-ID`, `Batch-ID`, commit SHA, QA report, handback file, decision-log entry, gate-result file.
@@ -1,13 +1,52 @@
1
1
  rules:
2
- - id: tera-no-hardcoded-secrets
2
+ - id: tera-no-hardcoded-secrets-csharp
3
3
  message: >
4
4
  SECURITY [QG-SEC-001]: لا تخزن مفاتيح أو ConnectionStrings أو Secrets في الكود.
5
5
  استخدم User Secrets / Environment Variables / Azure Key Vault / أي آلية آمنة معتمدة.
6
6
  severity: ERROR
7
7
  languages:
8
8
  - csharp
9
+ patterns:
10
+ - pattern: |
11
+ $VAR = "..."
12
+ - metavariable-regex:
13
+ metavariable: $VAR
14
+ regex: (?i).*(password|secret|connection.?string|api.?key|apikey|passwd|pwd|credential).*
15
+
16
+ - id: tera-no-hardcoded-secrets-javascript
17
+ message: >
18
+ SECURITY [QG-SEC-001]: لا تخزن مفاتيح أو ConnectionStrings أو Secrets في الكود.
19
+ استخدم User Secrets / Environment Variables / Azure Key Vault / أي آلية آمنة معتمدة.
20
+ severity: ERROR
21
+ languages:
9
22
  - javascript
23
+ patterns:
24
+ - pattern: |
25
+ $VAR = "..."
26
+ - metavariable-regex:
27
+ metavariable: $VAR
28
+ regex: (?i).*(password|secret|connection.?string|api.?key|apikey|passwd|pwd|credential).*
29
+
30
+ - id: tera-no-hardcoded-secrets-typescript
31
+ message: >
32
+ SECURITY [QG-SEC-001]: لا تخزن مفاتيح أو ConnectionStrings أو Secrets في الكود.
33
+ استخدم User Secrets / Environment Variables / Azure Key Vault / أي آلية آمنة معتمدة.
34
+ severity: ERROR
35
+ languages:
10
36
  - typescript
37
+ patterns:
38
+ - pattern: |
39
+ $VAR = "..."
40
+ - metavariable-regex:
41
+ metavariable: $VAR
42
+ regex: (?i).*(password|secret|connection.?string|api.?key|apikey|passwd|pwd|credential).*
43
+
44
+ - id: tera-no-hardcoded-secrets-python
45
+ message: >
46
+ SECURITY [QG-SEC-001]: لا تخزن مفاتيح أو ConnectionStrings أو Secrets في الكود.
47
+ استخدم User Secrets / Environment Variables / Azure Key Vault / أي آلية آمنة معتمدة.
48
+ severity: ERROR
49
+ languages:
11
50
  - python
12
51
  patterns:
13
52
  - pattern: |
@@ -16,6 +55,23 @@ rules:
16
55
  metavariable: $VAR
17
56
  regex: (?i).*(password|secret|connection.?string|api.?key|apikey|passwd|pwd|credential).*
18
57
 
58
+ - id: tera-no-hardcoded-secrets-kotlin
59
+ message: >
60
+ SECURITY [QG-SEC-001]: لا تخزن مفاتيح أو ConnectionStrings أو Secrets في الكود.
61
+ استخدم User Secrets / Environment Variables / Azure Key Vault / أي آلية آمنة معتمدة.
62
+ severity: ERROR
63
+ languages:
64
+ - kotlin
65
+ patterns:
66
+ - pattern-either:
67
+ - pattern: |
68
+ val $VAR = "..."
69
+ - pattern: |
70
+ var $VAR = "..."
71
+ - metavariable-regex:
72
+ metavariable: $VAR
73
+ regex: (?i).*(password|secret|connection.?string|api.?key|apikey|passwd|pwd|credential).*
74
+
19
75
  - id: tera-no-eval
20
76
  pattern: eval(...)
21
77
  message: >
@@ -44,23 +100,76 @@ rules:
44
100
  metavariable: $VAR
45
101
  regex: (?i).*
46
102
 
47
- - id: tera-exposed-credentials
103
+ - id: tera-exposed-credentials-csharp
48
104
  message: >
49
105
  SECURITY [QG-SEC-001]: لا تخزن مفاتيح أو توكنز أو API Keys بشكل صريح في الكود.
50
106
  severity: ERROR
51
107
  languages:
52
108
  - csharp
109
+ patterns:
110
+ - pattern: $VAR = $VAL
111
+ - metavariable-regex:
112
+ metavariable: $VAL
113
+ regex: ^"(sk-|ghp_|AKIA|=).*"
114
+
115
+ - id: tera-exposed-credentials-javascript
116
+ message: >
117
+ SECURITY [QG-SEC-001]: لا تخزن مفاتيح أو توكنز أو API Keys بشكل صريح في الكود.
118
+ severity: ERROR
119
+ languages:
53
120
  - javascript
121
+ patterns:
122
+ - pattern: $VAR = $VAL
123
+ - metavariable-regex:
124
+ metavariable: $VAL
125
+ regex: ^"(sk-|ghp_|AKIA|=).*"
126
+
127
+ - id: tera-exposed-credentials-typescript
128
+ message: >
129
+ SECURITY [QG-SEC-001]: لا تخزن مفاتيح أو توكنز أو API Keys بشكل صريح في الكود.
130
+ severity: ERROR
131
+ languages:
54
132
  - typescript
133
+ patterns:
134
+ - pattern: $VAR = $VAL
135
+ - metavariable-regex:
136
+ metavariable: $VAL
137
+ regex: ^"(sk-|ghp_|AKIA|=).*"
138
+
139
+ - id: tera-exposed-credentials-python
140
+ message: >
141
+ SECURITY [QG-SEC-001]: لا تخزن مفاتيح أو توكنز أو API Keys بشكل صريح في الكود.
142
+ severity: ERROR
143
+ languages:
55
144
  - python
145
+ patterns:
146
+ - pattern: $VAR = $VAL
147
+ - metavariable-regex:
148
+ metavariable: $VAL
149
+ regex: ^"(sk-|ghp_|AKIA|=).*"
150
+
151
+ - id: tera-exposed-credentials-java
152
+ message: >
153
+ SECURITY [QG-SEC-001]: لا تخزن مفاتيح أو توكنز أو API Keys بشكل صريح في الكود.
154
+ severity: ERROR
155
+ languages:
56
156
  - java
157
+ patterns:
158
+ - pattern: $VAR = $VAL
159
+ - metavariable-regex:
160
+ metavariable: $VAL
161
+ regex: ^"(sk-|ghp_|AKIA|=).*"
162
+
163
+ - id: tera-exposed-credentials-kotlin
164
+ message: >
165
+ SECURITY [QG-SEC-001]: لا تخزن مفاتيح أو توكنز أو API Keys بشكل صريح في الكود.
166
+ severity: ERROR
167
+ languages:
168
+ - kotlin
57
169
  patterns:
58
170
  - pattern-either:
59
- - pattern: |
60
- $VAR = "=...="
61
- - pattern: |
62
- $VAR = "sk-..."
63
- - pattern: |
64
- $VAR = "ghp_..."
65
- - pattern: |
66
- $VAR = "AKIA..."
171
+ - pattern: val $VAR = $VAL
172
+ - pattern: var $VAR = $VAL
173
+ - metavariable-regex:
174
+ metavariable: $VAL
175
+ regex: ^"(sk-|ghp_|AKIA|=).*"
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@tera-system/core",
3
- "version": "0.2.20",
4
- "description": "Tera System OpenCode Plugin ط£آ¢أ¢â€ڑآ¬أ¢â‚¬â€Œ governance core, 20 agents, 11 commands, distribution tools (personal edition)",
3
+ "version": "0.3.1",
4
+ "description": "Tera System OpenCode Plugin — governance core, 23 agents, 11 commands, distribution tools (personal edition)",
5
5
  "license": "SEE LICENSE IN LICENSE.md",
6
6
  "type": "module",
7
7
  "engines": {
@@ -1,243 +0,0 @@
1
- # OpenHands — مرجع معماري للدراسة المستقبلية
2
-
3
- > **أنشئ:** 2026-07-26
4
- > **المصدر:** https://github.com/OpenHands/OpenHands (82.2k★)
5
- > **الغرض:** ملف مرجعي لدراسة OpenHands لاحقاً وتطبيق مفاهيمه على Tera
6
- > **حالة الدراسة:** ⏳ لم تبدأ بعد — أنشئ للرجوع إليه
7
-
8
- ---
9
-
10
- ## 1. ما هو OpenHands؟
11
-
12
- منصة **مفتوحة المصدر** لتشغيل وإدارة العملاء البرمجيين (Coding Agents) على نطاق واسع.
13
- ليست مجرد IDE أو CLI — بل **نظام تشغيل كامل للعملاء**.
14
-
15
- ### الإحصائيات
16
- - ⭐ 82.2k★
17
- - 🍴 10.5k Fork
18
- - 📝 7,082 Commit
19
- - 📜 Apache 2.0 License
20
-
21
- ---
22
-
23
- ## 2. المكونات المعمارية الأساسية
24
-
25
- ```
26
- ┌────────────────────────────────────────────────────────────┐
27
- │ OpenHands System │
28
- ├────────────────────────────────────────────────────────────┤
29
- │ │
30
- │ ┌───────────────────────┐ │
31
- │ │ Agent Canvas │ ← واجهة تحكم Frontend (UI) │
32
- │ │ @openhands/agent- │ تبوك: localhost:8000 │
33
- │ │ canvas │ تشغيل محلي أو سحابي │
34
- │ └──────────┬────────────┘ │
35
- │ │ HTTP/REST │
36
- │ ┌──────────▼────────────┐ │
37
- │ │ Agent Server │ ← REST API لتشغيل العملاء │
38
- │ │ (software-agent-sdk) │ • يشغّل عدة عملاء على Server │
39
- │ │ │ • يمكن تشغيل Servers متعددة │
40
- │ └──────────┬────────────┘ • Local / Docker / VM / Cloud│
41
- │ │ │
42
- │ ┌──────────▼────────────┐ │
43
- │ │ Automation Server │ ← تشغيل مجدول + أحداث │
44
- │ │ (github.com/ │ • Cron jobs │
45
- │ │ OpenHands/ │ • Webhooks (GitHub, Linear) │
46
- │ │ automation) │ • تكامل Slack, Discord │
47
- │ └────────────────────────┘ │
48
- │ │
49
- │ ┌────────────────────────┐ │
50
- │ │ ACP (Agent-Client │ ← بروتوكول تواصل موحّد │
51
- │ │ Protocol) │ • أي عميل (Claude, Codex, │
52
- │ │ │ Gemini, OpenHands) │
53
- │ │ │ • يتواصل مع أي Server │
54
- │ └────────────────────────┘ │
55
- │ │
56
- └────────────────────────────────────────────────────────────┘
57
- ```
58
-
59
- ---
60
-
61
- ## 3. Agent Canvas بالتفصيل
62
-
63
- | الخاصية | الوصف |
64
- |----------|--------|
65
- | **التركيب** | `npm install -g @openhands/agent-canvas` |
66
- | **التشغيل** | `agent-canvas` → localhost:8000 |
67
- | **التقسيم** | `--frontend-only` لواجهة فقط، `--backend-only` لخادم فقط |
68
- | **الغرض** | واجهة مرئية لعرض وتشغيل ومراقبة العملاء |
69
-
70
- ### الميزات
71
- - تشغيل عدة عملاء بالتوازي
72
- - Dashboard لكل عميل (حالته، مخرجاته، سجلاته)
73
- - التبديل بين Backends مختلفة دون فقدان السياق
74
- - إضافة Backends جديدة من الواجهة نفسها
75
-
76
- ---
77
-
78
- ## 4. Agent Server بالتفصيل
79
-
80
- ```
81
- Agent Canvas → HTTP REST → Agent Server → Agent (OpenHands/Claude/Codex)
82
- ```
83
-
84
- | الخاصية | الوصف |
85
- |----------|--------|
86
- | **التشغيل** | محلي، Docker، VM، Mac Mini، سحابة |
87
- | **اللغة** | Python (uv) |
88
- | **REST API** | نعم — endpoints لتشغيل وإدارة العملاء |
89
- | **Multi-Server** | يمكن التبديل بين Servers متعددة |
90
- | **Sandbox** | اختياري — Docker isolation |
91
-
92
- ### أين يُشغّل؟
93
- - مباشرة على اللابتوب (⚠️ وصول كامل للملفات)
94
- - على Mac Mini مخصص
95
- - على VM في السحابة
96
- - داخل Docker (موصى به)
97
- - OpenHands Cloud (تجاري)
98
-
99
- ---
100
-
101
- ## 5. Automation Server
102
-
103
- | الخاصية | الوصف |
104
- |----------|--------|
105
- | **الجدولة** | Cron — مجدولة زمنياً |
106
- | **الأحداث** | Webhooks — GitHub, Linear, Slack |
107
- | **التكاملات** | Slack, GitHub, Notion, Datadog |
108
- | **الغرض** | تشغيل العملاء دون تدخل يدوي |
109
-
110
- ### أمثلة
111
- - "كل صباح: راجع الـ PRs المفتوحة وقدم ملخصاً"
112
- - "عند إغلاق Issue → حلل السبب الجذري"
113
- - "عند Push إلى main → شغّل اختبارات الأمان"
114
-
115
- ---
116
-
117
- ## 6. ACP — Agent-Client Protocol
118
-
119
- **هذا أهم ما في OpenHands معمارياً.**
120
-
121
- ```
122
- [Agent Client Protocol - ACP]
123
- ┌─────────┐ ┌──────────────┐
124
- │ Claude │ │ OpenHands │
125
- │ Code │←────→│ Agent │
126
- └─────────┘ └──────────────┘
127
- ┌─────────┐ ┌──────────────┐
128
- │ Codex │←────→│ Agent │
129
- └─────────┘ └──────────────┘
130
- ┌─────────┐ ┌──────────────┐
131
- │ Gemini │←────→│ Agent │
132
- └─────────┘ └──────────────┘
133
- ```
134
-
135
- - بروتوكول REST موحّد
136
- - أي عميل يتوافق مع ACP يعمل مع أي Server يدعم ACP
137
- - يسمح بالتبديل بين العملاء دون تغيير البنية التحتية
138
- - **يذكّرني بـ TeraSubAgents.md لكن كبروتوكول رسمي**
139
-
140
- ---
141
-
142
- ## 7. مقارنة مع Tera — الوضع الحالي
143
-
144
- | المفهوم | OpenHands | Tera (حالياً) |
145
- |---------|-----------|---------------|
146
- | **واجهة تحكم** | Agent Canvas (UI) | ❌ لا يوجد |
147
- | **تشغيل العملاء** | Agent Server (REST) | ✅ task tool + .opencode/agents/ |
148
- | **أتمتة مجدولة** | Automation Server (Cron) | ❌ يدوي بالكامل |
149
- | **بروتوكول موحّد** | ACP | 🟡 TeraSubAgents.md (نصي) |
150
- | **عزل العملاء** | Sandbox (Docker) | ❌ لا يوجد |
151
- | **Multi-Backend** | Local + Docker + VM + Cloud | ❌ جهاز واحد |
152
- | **تكامل خارجي** | Slack, GitHub, Linear, Notion | ❌ لا يوجد |
153
- | **التوسع** | أفقي (Servers متعددة) | 🟡 عمودي (عملاء أكثر) |
154
-
155
- ---
156
-
157
- ## 8. ما يمكن استلهامه لتطوير Tera
158
-
159
- ### 8.1 ACP → TeraSubAgents.md v2
160
- تحويل TeraSubAgents.md من "ملف تعريف" إلى "بروتوكول اتصال" يحدد:
161
- - كيف يستدعي عميل عميلاً آخر
162
- - ما هي Request/Response format
163
- - كيف يُدار السياق بين العملاء
164
-
165
- ### 8.2 Agent Canvas → Tera Dashboard
166
- لوحة تحكم لـ Majed:
167
- - يرى كل العملاء (TeraAgent, Engineering, UI, QA...)
168
- - حالة كل عميل (شغال؟ منتظر؟ مكتمل؟)
169
- - سجلات ومخرجات كل عميل
170
-
171
- ### 8.3 Automation Server → Tera Scheduler
172
- تشغيل مهام دورية:
173
- - "افحص جميع المشاريع بـ Trivy كل أسبوع"
174
- - "أرسل تقرير الجودة كل يوم جمعة"
175
- - "راقب تحديثات الأمان في dependencies"
176
-
177
- ### 8.4 Agent Server → Tera Execution Layer
178
- فصل "من يقرر" عن "من ينفذ":
179
- - TeraAgent يقرر فقط (كما هو الآن)
180
- - Execution Layer جديد يشغّل العملاء (مثل Agent Server)
181
- - يمكن تشغيل Execution Layer على Docker أو VM
182
-
183
- ---
184
-
185
- ## 9. سيناريو التطبيق الجذري (نسخة أخرى من Tera)
186
-
187
- ```
188
- ┌──────────────────────────────────────────────┐
189
- │ Tera v2 (مقترح) │
190
- ├──────────────────────────────────────────────┤
191
- │ │
192
- │ ┌──────────────────────┐ │
193
- │ │ Tera Dashboard │ ← UI لإدارة العملاء │
194
- │ ├──────────────────────┤ │
195
- │ │ Tera Execution │ ← REST API Layer │
196
- │ │ Server │ لتشغيل العملاء │
197
- │ ├──────────────────────┤ │
198
- │ │ Tera Protocol │ ← ACP-like protocol│
199
- │ │ (TP-1) │ للتواصل بين │
200
- │ │ │ العملاء │
201
- │ ├──────────────────────┤ │
202
- │ │ Tera Scheduler │ ← Cron + Events │
203
- │ ├──────────────────────┤ │
204
- │ │ Sandbox Manager │ ← Docker isolation │
205
- │ └──────────────────────┘ │
206
- │ │
207
- │ ════════════════════════════════════════ │
208
- │ │
209
- │ يبقى Tera v1 (الحالي) كما هو للإنتاج. │
210
- │ Tera v2 يُبنى بالتوازي كإعادة هيكلة. │
211
- │ │
212
- └──────────────────────────────────────────────┘
213
- ```
214
-
215
- ---
216
-
217
- ## 10. روابط مهمة للدراسة
218
-
219
- | الرابط | الوصف |
220
- |--------|--------|
221
- | https://github.com/OpenHands/OpenHands | المستودع الرئيسي |
222
- | https://github.com/OpenHands/software-agent-sdk | الـ SDK الرسمي للـ Agent و Agent Server |
223
- | https://github.com/OpenHands/agent-canvas | واجهة التحكم الأمامية |
224
- | https://github.com/OpenHands/automation | سيرفر الأتمتة |
225
- | https://docs.openhands.dev/overview/introduction | التوثيق الرسمي |
226
- | https://docs.openhands.dev/openhands/usage/agent-canvas/acp-agents | ACP Protocol specs |
227
- | https://docs.openhands.dev/openhands/usage/agent-canvas/backend-setup/vm | دليل Self-Hosting |
228
-
229
- ---
230
-
231
- ## 11. حالة الدراسة
232
-
233
- - [ ] قراءة ACP Specifications
234
- - [ ] تحليل Agent Server Architecture
235
- - [ ] تحليل Agent Canvas Architecture
236
- - [ ] دراسة Automation Server
237
- - [ ] مقارنة مع TeraSubAgents.md
238
- - [ ] إنتاج SYSTEM_CHANGE_PROPOSAL للتحسينات المستوحاة
239
- - [ ] بدء Tera v2 بالتوازي (اختياري)
240
-
241
- ---
242
-
243
- > **ملاحظة:** هذا الملف مرجعي بحت. أي دراسة أو تطبيق يتطلب الرجوع إلى المصادر الأصلية والموافقة على SYSTEM_CHANGE_PROPOSAL قبل التنفيذ.