plugin-agent-orchestrator 1.1.4 → 1.1.5

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.
Files changed (148) hide show
  1. package/README.md +204 -114
  2. package/dist/client/index.js +1 -1
  3. package/dist/client-v2/117.7565cff57c39318a.js +10 -0
  4. package/dist/client-v2/214.106635011859dede.js +10 -0
  5. package/dist/client-v2/418.41ed200e7d6da332.js +10 -0
  6. package/dist/client-v2/53.349fff8db80b19d4.js +10 -0
  7. package/dist/client-v2/981.e4a1f41cfc94a856.js +10 -0
  8. package/dist/client-v2/index.js +1 -1
  9. package/dist/externalVersion.js +7 -8
  10. package/dist/locale/en-US.json +226 -170
  11. package/dist/locale/vi-VN.json +226 -170
  12. package/dist/locale/zh-CN.json +226 -170
  13. package/dist/server/collections/agent-execution-spans.js +8 -0
  14. package/dist/server/collections/agent-loop-action-approvals.js +1 -0
  15. package/dist/server/collections/agent-loop-runs.js +7 -1
  16. package/dist/server/collections/agent-loop-steps.js +7 -0
  17. package/dist/server/collections/skill-executions.js +8 -0
  18. package/dist/server/plugin.js +3 -1
  19. package/dist/server/resources/agent-harness-profile.js +117 -0
  20. package/dist/server/resources/agent-knowledge-insights.js +1 -3
  21. package/dist/server/resources/agent-loop-approval.js +25 -0
  22. package/dist/server/resources/agent-loop.js +3 -1
  23. package/dist/server/services/AgentMemoryContextService.js +34 -0
  24. package/dist/server/services/HarnessCompiler.js +35 -2
  25. package/dist/server/services/HarnessProfileService.js +74 -9
  26. package/dist/server/services/HarnessSchema.js +30 -3
  27. package/dist/server/services/LoopPatternSchema.js +16 -1
  28. package/dist/server/services/LoopRunRepository.js +80 -0
  29. package/dist/server/services/LoopRunStateMachine.js +92 -3
  30. package/dist/server/services/LoopTriggerService.js +37 -0
  31. package/dist/server/services/LoopWorkerService.js +261 -23
  32. package/dist/server/services/NativeSubAgentObserver.js +165 -23
  33. package/dist/server/services/PluginAiRuntimeAdapter.js +16 -5
  34. package/dist/server/services/ToolLoopDetectionService.js +210 -0
  35. package/dist/server/services/VerificationService.js +66 -0
  36. package/dist/server/services/harness-runtime-policy.js +139 -0
  37. package/dist/server/skill-hub/plugin.js +36 -3
  38. package/dist/server/skill-hub/tasks/SkillExecutionTask.js +29 -0
  39. package/package.json +53 -53
  40. package/src/client/ApprovalsTab.tsx +2 -0
  41. package/src/client/OrchestratorSettings.tsx +11 -0
  42. package/src/client/skill-hub/components/GitSkillImport.tsx +3 -3
  43. package/src/client/skill-hub/components/SkillMetrics.tsx +15 -10
  44. package/src/client/skill-hub/index.tsx +0 -52
  45. package/src/client-v2/components/AgentRunsTab.tsx +576 -576
  46. package/src/client-v2/components/ApprovalsTab.tsx +337 -0
  47. package/src/client-v2/components/HarnessProfilesTab.tsx +385 -105
  48. package/src/client-v2/components/MemoryInspectorTab.tsx +141 -141
  49. package/src/client-v2/components/TracingTab.tsx +515 -515
  50. package/src/client-v2/hooks/useApiRequest.ts +141 -141
  51. package/src/client-v2/pages/ApprovalsPage.tsx +10 -0
  52. package/src/client-v2/plugin.tsx +6 -6
  53. package/src/client-v2/skill-hub/components/SkillMetrics.tsx +5 -2
  54. package/src/locale/en-US.json +226 -174
  55. package/src/locale/vi-VN.json +226 -174
  56. package/src/locale/zh-CN.json +226 -174
  57. package/src/server/__tests__/circuit-breaker.test.ts +248 -248
  58. package/src/server/__tests__/harness-compiler.test.ts +83 -0
  59. package/src/server/__tests__/harness-profile-service.test.ts +51 -0
  60. package/src/server/__tests__/harness-runtime-policy.test.ts +293 -0
  61. package/src/server/__tests__/harness-tool-plan.test.ts +24 -0
  62. package/src/server/__tests__/loop-approval-decision.test.ts +512 -0
  63. package/src/server/__tests__/loop-approval-expiry.test.ts +258 -0
  64. package/src/server/__tests__/loop-budget-service.test.ts +255 -255
  65. package/src/server/__tests__/loop-control-plane-backfill.test.ts +266 -266
  66. package/src/server/__tests__/loop-pattern-schema.test.ts +18 -1
  67. package/src/server/__tests__/loop-pattern-service.test.ts +148 -148
  68. package/src/server/__tests__/loop-run-state-machine.test.ts +11 -0
  69. package/src/server/__tests__/loop-trigger-service.test.ts +148 -0
  70. package/src/server/__tests__/loop-worker-claim.test.ts +341 -341
  71. package/src/server/__tests__/loop-worker-execution.test.ts +82 -1
  72. package/src/server/__tests__/native-sub-agent-observer.test.ts +288 -4
  73. package/src/server/__tests__/path-lock-service.test.ts +254 -254
  74. package/src/server/__tests__/skill-execution-task-policy.test.ts +140 -0
  75. package/src/server/__tests__/smoke.test.ts +162 -162
  76. package/src/server/__tests__/tool-loop-detection.test.ts +275 -0
  77. package/src/server/collections/agent-execution-spans.ts +8 -0
  78. package/src/server/collections/agent-harness-profile-versions.ts +26 -26
  79. package/src/server/collections/agent-harness-profiles.ts +71 -71
  80. package/src/server/collections/agent-loop-action-approvals.ts +1 -0
  81. package/src/server/collections/agent-loop-artifacts.ts +25 -25
  82. package/src/server/collections/agent-loop-circuit-states.ts +23 -23
  83. package/src/server/collections/agent-loop-control-settings.ts +21 -21
  84. package/src/server/collections/agent-loop-events.ts +98 -98
  85. package/src/server/collections/agent-loop-path-locks.ts +27 -27
  86. package/src/server/collections/agent-loop-patterns.ts +42 -42
  87. package/src/server/collections/agent-loop-runs.ts +7 -1
  88. package/src/server/collections/agent-loop-steps.ts +7 -0
  89. package/src/server/collections/agent-loop-usage-buckets.ts +22 -22
  90. package/src/server/collections/agent-loop-worktrees.ts +25 -25
  91. package/src/server/collections/skill-executions.ts +8 -0
  92. package/src/server/migrations/20260427000002-change-packages-to-text.ts +52 -52
  93. package/src/server/migrations/20260429000000-add-llm-fields.ts +47 -47
  94. package/src/server/migrations/20260429000001-fix-inputargs-json-to-text.ts +45 -45
  95. package/src/server/migrations/20260503000000-add-orchestrator-trace-fields.ts +33 -33
  96. package/src/server/migrations/20260524000000-add-agent-loop-fields-to-skill-executions.ts +31 -31
  97. package/src/server/migrations/20260803010000-backfill-loop-control-plane-data.ts +293 -293
  98. package/src/server/plugin.ts +3 -1
  99. package/src/server/resources/agent-harness-profile.ts +94 -0
  100. package/src/server/resources/agent-knowledge-insights.ts +5 -3
  101. package/src/server/resources/agent-loop-approval.ts +32 -0
  102. package/src/server/resources/agent-loop-artifact.ts +56 -56
  103. package/src/server/resources/agent-loop-events-stream.ts +105 -105
  104. package/src/server/resources/agent-loop.ts +3 -1
  105. package/src/server/resources/resource-helpers.ts +33 -33
  106. package/src/server/resources/tracing.ts +266 -266
  107. package/src/server/services/AgentMemoryContextService.ts +44 -0
  108. package/src/server/services/DurableCircuitBreakerService.ts +239 -239
  109. package/src/server/services/ExecutionSpanService.ts +2 -0
  110. package/src/server/services/HarnessCompiler.ts +37 -0
  111. package/src/server/services/HarnessProfileService.ts +92 -10
  112. package/src/server/services/HarnessSchema.ts +31 -0
  113. package/src/server/services/LoopBudgetService.ts +275 -275
  114. package/src/server/services/LoopControlService.ts +124 -124
  115. package/src/server/services/LoopPatternSchema.ts +19 -1
  116. package/src/server/services/LoopPatternService.ts +143 -143
  117. package/src/server/services/LoopRunRepository.ts +99 -0
  118. package/src/server/services/LoopRunStateMachine.ts +100 -3
  119. package/src/server/services/LoopSchedulerService.ts +199 -199
  120. package/src/server/services/LoopTriggerService.ts +42 -0
  121. package/src/server/services/LoopWorkerService.ts +327 -27
  122. package/src/server/services/NativeSubAgentObserver.ts +186 -21
  123. package/src/server/services/PathLockService.ts +321 -321
  124. package/src/server/services/PluginAiRuntimeAdapter.ts +24 -7
  125. package/src/server/services/ToolLoopDetectionService.ts +213 -0
  126. package/src/server/services/VerificationSchema.ts +31 -31
  127. package/src/server/services/VerificationService.ts +81 -2
  128. package/src/server/services/harness-runtime-policy.ts +141 -0
  129. package/src/server/skill-hub/plugin.ts +41 -3
  130. package/src/server/skill-hub/services/RegistrySkillSnapshotService.ts +235 -235
  131. package/src/server/skill-hub/services/__tests__/RegistrySkillSnapshotService.test.ts +61 -61
  132. package/src/server/skill-hub/tasks/SkillExecutionTask.ts +43 -2
  133. package/src/server/utils/ensure-indexes.ts +96 -96
  134. package/src/server/utils/logging.ts +62 -62
  135. package/src/server/utils/loop-pattern-context.ts +20 -20
  136. package/dist/client-v2/214.b063f33ba044a808.js +0 -10
  137. package/dist/client-v2/373.f5d5292e53c4e832.js +0 -10
  138. package/dist/client-v2/418.58fa350f5496efd3.js +0 -10
  139. package/dist/client-v2/53.9a10455323390f14.js +0 -10
  140. package/dist/client-v2/677.a991ce0250ff5c77.js +0 -10
  141. package/dist/client-v2/925.e5925bf21ed68e7a.js +0 -10
  142. package/src/client/AIEmployeeSelect.tsx +0 -47
  143. package/src/client/AIEmployeesContext.tsx +0 -102
  144. package/src/client/RulesTab.tsx +0 -2
  145. package/src/client/TracingTab.tsx +0 -436
  146. package/src/client/skill-hub/components/ExecutionProgress.tsx +0 -51
  147. package/src/client-v2/components/RulesTab.tsx +0 -2
  148. package/src/client-v2/pages/AgentRunsPage.tsx +0 -13
package/README.md CHANGED
@@ -1,114 +1,204 @@
1
- # plugin-agent-orchestrator
2
-
3
- ## Overview
4
- Hierarchical Multi-Agent orchestration for NocoBase AI Employees. Enables Leader agents to delegate tasks to Sub-Agent employees, with detailed execution tracing and context/memory management.
5
-
6
- ## Features
7
- - **Hierarchical Delegation**: Allows AI Leader agents to break down complex tasks and assign them to specialized sub-agents via native dispatching.
8
- - **Seamless Integration**: Plugs directly into the existing AI Employee framework, capturing execution spans.
9
- - **Execution Tracking**: Monitor sub-agent task execution and nested tool calls in detail within the main chat interface.
10
- - **External RAG Search**: Exposes `external_rag_search` so leaders and sub-agents can retrieve context from NocoBase knowledge bases, including external RAG services.
11
-
12
- ## Usage
13
- 1. Enable the plugin in the NocoBase Plugin Manager.
14
- 2. Navigate to the AI Employee configuration page.
15
- 3. Configure a primary "Leader" agent and specialized "Sub-Agent" employees.
16
- 4. Add the built-in **AI employee task dispatching** (`dispatch-sub-agent-task`) tool to the Leader agent.
17
- 5. Ensure the user role has access to both the Leader and Sub-Agent employees (configured via employee roles mapping).
18
- 6. Interact with the Leader agent; it will automatically delegate tasks to the sub-agents when necessary.
19
-
20
-
21
- ## External RAG / Embedding service
22
-
23
- Recommended approach: keep source ownership in NocoBase and move chunking, embedding, vector storage, and retrieval to an external lightweight RAG service. This plugin should not own vector infrastructure directly. It delegates search to `plugin-knowledge-base`, which already supports knowledge bases of type `EXTERNAL_RAG`.
24
-
25
- ### Architecture
26
-
27
- 1. NocoBase stores the source metadata:
28
- - uploaded file attachment id, filename, storage id, URL, owner/role access, or
29
- - datasource/collection/record id for database-backed knowledge.
30
- 2. The external RAG service owns:
31
- - document fetching or receiving source payloads,
32
- - parsing/chunking,
33
- - embedding,
34
- - vector index,
35
- - retrieval.
36
- 3. NocoBase creates a knowledge base with `type = EXTERNAL_RAG` and `options` such as:
37
- - `ragProvider: "external-http"`
38
- - `ragApiUrl: "https://rag.example.com/search"`
39
- - `ragApiKey`
40
- - `ragNamespace`
41
- - `ragTopK`
42
- - `ragScoreThreshold`
43
- 4. Agents use the `external_rag_search` tool. The tool calls `plugin-knowledge-base.searchKnowledgeBases()`, so access control and mixed local/external search remain centralized.
44
-
45
- ### External search contract
46
-
47
- The built-in `external-http` strategy expects:
48
-
49
- ```http
50
- POST /search
51
- Authorization: Bearer <ragApiKey>
52
- Content-Type: application/json
53
- ```
54
-
55
- ```json
56
- {
57
- "query": "search text",
58
- "topK": 5,
59
- "scoreThreshold": 0.3,
60
- "namespace": "optional-kb-namespace",
61
- "filter": {}
62
- }
63
- ```
64
-
65
- Response:
66
-
67
- ```json
68
- {
69
- "results": [
70
- {
71
- "id": "chunk-or-source-id",
72
- "content": "matched text",
73
- "score": 0.82,
74
- "metadata": {
75
- "fileId": "123",
76
- "filename": "contract.pdf",
77
- "collection": "orders",
78
- "recordId": "456",
79
- "sourceUrl": "/api/attachments/123:download"
80
- }
81
- }
82
- ]
83
- }
84
- ```
85
-
86
- The important rule is that every result should return enough metadata for NocoBase to resolve the original source: `fileId`/`filename` for files, or `collection`/`recordId` for datasource records.
87
-
88
- ### Lightweight open-source service target
89
-
90
- For a small but useful deployment, use a standalone service with:
91
-
92
- - Qdrant or LanceDB for vector search.
93
- - FastAPI or Express for `/ingest`, `/delete`, and `/search`.
94
- - A small embedding model such as `BAAI/bge-small-en-v1.5`, `intfloat/multilingual-e5-small`, or another model matching the deployment language.
95
- - A namespace per NocoBase knowledge base.
96
-
97
- Minimum API surface:
98
-
99
- - `POST /ingest`: receive `{ namespace, source, content | fileUrl | storageRef, metadata }`.
100
- - `POST /delete`: receive `{ namespace, sourceId }`.
101
- - `POST /search`: implement the contract above.
102
-
103
- For NocoBase datasource knowledge, send each record as a source document with metadata `{ collection, recordId, fields, updatedAt }`; the RAG service chunks and embeds the selected text fields, then returns `collection` and `recordId` in search results.
104
-
105
- ### E5/OpenAI-compatible embedding
106
-
107
- If the external RAG service uses an E5 family model behind an OpenAI-compatible `/v1/embeddings` API, configure the NocoBase knowledge base with `ragProvider: "e5-http"`. `plugin-knowledge-base` will read the selected embedding LLM service and forward its `baseURL`, `apiKey`, and model to the RAG service.
108
-
109
- - embed user queries as `query: <question>`;
110
- - embed document chunks as `passage: <chunk>`;
111
- - use the same model for ingest and search;
112
- - recreate the vector collection when changing models or vector dimensions.
113
-
114
- The RAG service still owns chunking, embedding calls, vector storage, and metadata mapping. NocoBase owns the LLM service configuration and search authorization path.
1
+ # plugin-agent-orchestrator
2
+
3
+ ## Overview
4
+
5
+ Agent orchestration layer for NocoBase AI Employees (plugin-ai). The plugin provides three main subsystems:
6
+
7
+ 1. **Agent Loop Control Plane** — durable, policy-governed multi-step runs with a leader/maker/verifier role model, cron/event/manual triggers, budgets, approvals, and independent verification.
8
+ 2. **Harness (Policy Profiles)** — versioned, tag-addressed policy bundles that constrain what each role may do (tools, memory, delegation, limits, isolation, observability), compiled layer-by-layer with most-restrictive-wins semantics.
9
+ 3. **Skill Hub** — sandboxed Python/Node.js skills that AI employees can execute as tools, with async execution, human-in-the-loop review, an MCP-style surface, and Git/registry import.
10
+
11
+ On top of these, the plugin observes native sub-agent dispatching from plugin-ai, records a unified execution-span tree, injects agent memory context, and exposes an external RAG search tool.
12
+
13
+ ## Agent Loop Control Plane
14
+
15
+ ### Patterns
16
+
17
+ A loop pattern (`agentLoopPatterns`) defines a repeatable unit of autonomous work:
18
+
19
+ - `key`, `goalTemplate` — identity and the goal rendered for each run.
20
+ - `autonomyLevel` — `L1` (supervised), `L2`, `L3` (autonomous). L2/L3 require repository identity (`repositoryKey`, `repositoryRoot`, `baseRef`, `actingOn[]`) and worktree isolation (`policy.harness.isolation.requireWorktree`).
21
+ - `triggerType` — `manual`, `cron` (`cronExpression` + `timezone`), or `event` (`eventKey`).
22
+ - Role bindings — `leaderUsername`, `makerUsernames[]`, `verifierUsername` (verifier must differ from leader and makers).
23
+ - Per-role harness tags — `leaderHarnessTag` / `makerHarnessTag` (default `default`), `verifierHarnessTag` (default `safe`).
24
+ - `policy` — concurrency, per-run/daily budgets (invocations, tool calls, delegations, verifications, tokens, cost), circuit-breaker limits, path restrictions (`maxFiles`, deny list), action approval settings (`autoAllowlist`, approvers, timeout), tool-loop detection thresholds (`warnAt`/`blockAt`/`escalateAt`), and required verification checks.
25
+
26
+ ### Run lifecycle
27
+
28
+ `LoopTriggerService` compiles the pattern (including layered harness compilation), snapshots role bindings and harness settings onto the run row, and enqueues it. `LoopWorkerService` claims queued runs with a lease + heartbeat, acquires path locks on `actingOn`, then drives the run:
29
+
30
+ `queued → preparing → waiting_lock → running → waiting_approval → verifying → waiting_human → succeeded | failed | canceled` (plus `paused`, `blocked`).
31
+
32
+ - **Leader** invocation plans the work but changes nothing.
33
+ - **Maker** invocations execute the plan, each under its own compiled harness.
34
+ - Tool calls gated as `ask` park the run in `waiting_approval` until the approval row is resolved via `agentLoopApprovals:decide` (approve — optionally substituting an edited input — or reject).
35
+ - **Tool-loop detection** (`ToolLoopDetectionService`, active in both worker and verifier) guards against repeated identical tool calls: `warnAt` injects a notice into the run, `blockAt` refuses the call, `escalateAt` escalates the run for human review.
36
+ - **Verifier** (via `VerificationService`) runs an independent pass and returns a JSON verdict: `pass` → `succeeded` (L1) or `waiting_human` (L2/L3); `reject` → `failed`; `escalate` → `waiting_human`. Required checks and artifact evidence ownership are enforced.
37
+
38
+ Human actions on runs: pause, resume, cancel, retry, escalate, accept result. Budgets, circuit-breaker state, usage buckets, events, steps, artifacts, and worktrees are persisted in dedicated collections.
39
+
40
+ ### Sub-agent observation and memory
41
+
42
+ - `NativeSubAgentObserver` wraps plugin-ai's native `dispatch-sub-agent-task` flow: it resolves harness policy, injects memory context into the delegated question, records root/tool spans in `agentExecutionSpans`, tracks tokens/cost, and links skill executions. Legacy `delegate_*` / `dispatch_subagents_*` tools are retired.
43
+ - `AgentMemoryContextService` builds an `<agent_memory_context>` block from `agentMemoryContexts` records (scopes `public`, `user`, `agent_user`, plus plugin-user-memory content), trimmed to the harness-configured character limit.
44
+ - `AgentRegistryService` resolves leader↔sub-agent bindings from `orchestratorConfig`, model overrides, and alternative sub-agents for retry.
45
+
46
+ ## Harness (Policy Profiles)
47
+
48
+ A harness profile is a versioned policy bundle addressed by a unique `tag`. Settings (validated by a strict zod schema in `HarnessSchema.ts`) have six sections:
49
+
50
+ | Section | Controls |
51
+ | --- | --- |
52
+ | `tools` | `allow` / `ask` / `deny` lists, per-tool `effects` (`read` / `write` / `external`), `trustedPreHandlerTools` |
53
+ | `memory` | `enabled`, `scopes` (`public` / `user` / `agent_user`), `maxChars` |
54
+ | `delegation` | `allowedEmployees`, `maxDepth`, `maxCount` |
55
+ | `limits` | `timeoutMs`, `recursionLimit`, max invocations/tool calls/tokens/cost |
56
+ | `isolation` | `mode` (`none` / `worktree`), `requireWorktree`, `allowedConnectors`, `networkAccess` (`deny` / `restricted` / `allow`) |
57
+ | `observability` | `enabled`, `tracingRetentionDays`, `captureInputs`, `captureOutputs` |
58
+
59
+ ### Layered compilation
60
+
61
+ `HarnessCompiler.compileHarness()` merges an ordered list of layers with most-restrictive-wins semantics: allow-lists and scopes are intersected, `ask`/`deny` are unioned, numeric limits take the minimum, booleans AND, network access takes the strictest value. For each run role, `LoopPatternService` stacks:
62
+
63
+ `platform` (hard ceilings) → `profile:<tag>@<version>` (published profile) → `pattern` → `employee:<username>` → per-run overrides.
64
+
65
+ The compiled result is persisted on the run as an immutable snapshot (`leaderHarnessSnapshot`, per-maker `makerHarnessSnapshot`, `verifierHarnessSnapshot`), so runs always execute against the policy that was in force at enqueue time.
66
+
67
+ ### Tool planning
68
+
69
+ At invocation time, `PluginAiRuntimeAdapter` converts the compiled harness into a tool plan: `deny` > `ask` > `allow`. Tools not explicitly allowed become `ask`; allowed tools with `write`/`external` effects stay `ask` unless listed in `trustedPreHandlerTools`. `ask` tools are attached without auto-call so they interrupt for approval; unenforceable system tools (e.g. web search) are blocked at the source.
70
+
71
+ ### Versioning
72
+
73
+ `HarnessProfileService` manages draft/publish lifecycle over `agentHarnessProfileVersions`: create draft → update draft → publish (points the profile's `currentVersionId` at the published version). One open draft per profile — `saveDraft` writes into the latest unpublished draft and only starts a new version once the previous one shipped, keeping the version history a clean publish trail. `createProfile` bootstraps a profile together with its first published version atomically, and version numbering is row-locked so concurrent saves/publishes cannot collide. Published versions are immutable. Profiles are resolved by tag via `getPublishedByTag(tag)`. Seeded profiles: `default`, `safe`, `file-heavy`.
74
+
75
+ ## Skill Hub
76
+
77
+ ### Skills
78
+
79
+ A skill (`skillDefinitions`) is a sandboxed Python or Node.js code unit with:
80
+
81
+ - immutable `toolName`, `title`, `description`, `instructions`;
82
+ - `codeTemplate` with `{{placeholder}}` rendering and a JSON Schema `inputSchema`;
83
+ - optional `interactionSchema` for human-in-the-loop review UI;
84
+ - `packages`, `timeoutSeconds`, `maxOutputSizeMb`, `enabled`, `autoCall`;
85
+ - `toolScope` (`CUSTOM` / `GENERAL` / `SPECIFIED`) controlling visibility across AI employees;
86
+ - storage source: database (zip upload), local, s3, plugin template, or Git.
87
+
88
+ ### Execution
89
+
90
+ `skill_hub_execute` and per-skill `skill_hub_<toolName>` tools validate input, check per-agent access (`SkillAccessService`), apply a per-user rate limit, create a `skillExecutions` row, and publish `skill-hub.task`. Sandbox workers claim executions, render and validate the code, run it in a sandbox, stream progress, and store stdout/stderr/output files (downloadable via `skillHub:download`). A poller recovers stale executions. Executions link into the tracing graph via `agentExecutionSpans` (span type `skill`).
91
+
92
+ ### MCP surface
93
+
94
+ The Skill Hub exposes an MCP-style server surface: `skillHub:mcpListTools` lists enabled skills as `{name, description, inputSchema}` tools; `skillHub:mcpCallTool` executes one and returns MCP content (including a file manifest).
95
+
96
+ ### Import and registry
97
+
98
+ - **Git import**: `gitListSkills` / `gitSyncSkills` read a `skills.json` manifest and `SKILL.md` frontmatter through plugin-git-manager (optional peer dependency).
99
+ - **Registry**: `RegistrySkillInstallationService` installs registry package versions into local `skillDefinitions` (disabled by default, with rollback chain), and `RegistrySkillSnapshotService` exports opt-in snapshots of local skills for an external registry plugin.
100
+
101
+ ### Human-in-the-loop review
102
+
103
+ `skillLoopConfigs` stores review templates (prompt + schema) per skill; the chat UI renders approval cards for skill executions that require review.
104
+
105
+ ## External RAG Search
106
+
107
+ The plugin registers the `external_rag_search` tool so leaders and sub-agents can retrieve context from NocoBase knowledge bases, including external RAG services. Source ownership stays in NocoBase; chunking, embedding, vector storage, and retrieval live in an external lightweight RAG service. The tool calls `plugin-knowledge-base.searchKnowledgeBases()`, so access control and mixed local/external search stay centralized.
108
+
109
+ Knowledge bases of type `EXTERNAL_RAG` carry options such as `ragProvider` (`external-http` or `e5-http`), `ragApiUrl`, `ragApiKey`, `ragNamespace`, `ragTopK`, `ragScoreThreshold`.
110
+
111
+ ### External search contract
112
+
113
+ The built-in `external-http` strategy expects:
114
+
115
+ ```http
116
+ POST /search
117
+ Authorization: Bearer <ragApiKey>
118
+ Content-Type: application/json
119
+ ```
120
+
121
+ ```json
122
+ {
123
+ "query": "search text",
124
+ "topK": 5,
125
+ "scoreThreshold": 0.3,
126
+ "namespace": "optional-kb-namespace",
127
+ "filter": {}
128
+ }
129
+ ```
130
+
131
+ Response:
132
+
133
+ ```json
134
+ {
135
+ "results": [
136
+ {
137
+ "id": "chunk-or-source-id",
138
+ "content": "matched text",
139
+ "score": 0.82,
140
+ "metadata": {
141
+ "fileId": "123",
142
+ "filename": "contract.pdf",
143
+ "collection": "orders",
144
+ "recordId": "456",
145
+ "sourceUrl": "/api/attachments/123:download"
146
+ }
147
+ }
148
+ ]
149
+ }
150
+ ```
151
+
152
+ Every result must return enough metadata for NocoBase to resolve the original source: `fileId`/`filename` for files, or `collection`/`recordId` for datasource records.
153
+
154
+ For E5-family models behind an OpenAI-compatible `/v1/embeddings` API, use `ragProvider: "e5-http"`: queries are embedded as `query: <question>`, chunks as `passage: <chunk>`, and the vector collection must be recreated when the model or vector dimensions change.
155
+
156
+ ## UI
157
+
158
+ Settings pages under **AI Employee → Agent Orchestrator** (both v1 client and client-v2):
159
+
160
+ | Tab | Purpose |
161
+ | --- | --- |
162
+ | Native Monitor | Loop run list with status, budgets, approvals |
163
+ | Execution Tracing | Span tree of sub-agent and tool executions |
164
+ | Policy Profiles | Harness profile CRUD with draft/publish versioning and version history |
165
+ | Approvals | Pending tool-call/escalation approvals; approve or reject with optional edited input |
166
+ | Agent Bindings | Leader↔sub-agent binding configuration |
167
+ | Knowledge Access | Per-agent knowledge base access matrix |
168
+ | Retrieval Trace | Retrieval tracing for knowledge lookups |
169
+ | Memory Inspector | Inspect agent memory context records |
170
+ | Skill Hub Definitions | Skill CRUD, editor, test panel, Git import |
171
+ | Execution History | Skill execution logs and output files |
172
+ | Skill Review Settings | Human-in-the-loop review templates |
173
+ | Metrics | Skill usage metrics |
174
+
175
+ ## API Resources
176
+
177
+ - `agentLoops` — list, get, runNow, pause, resume, cancel, retry, escalate, acceptResult, status
178
+ - `agentLoopApprovals` — list, get, decide
179
+ - `agentLoopArtifactsView` — list, get
180
+ - `agentLoopEventsStream` — stream
181
+ - `agentMonitor` — list, get, sync
182
+ - `agentKnowledgeInsights` — accessMatrix, retrievalTrace, memoryPreview
183
+ - `orchestratorTracing` — list, get
184
+ - `skillHub` — download, test, initEnv, clearStorage, mcpListTools, mcpCallTool, listTemplates, gitListSkills, gitSyncSkills
185
+ - `agentHarnessProfiles` — standard CRUD plus listVersions, saveDraft, publish, createProfile, validate
186
+ - Standard CRUD on `skillDefinitions`, `skillExecutions`, `agentMemoryContexts`, and related collections
187
+
188
+ ## Collections
189
+
190
+ Agent loops: `agentLoopPatterns`, `agentLoopRuns`, `agentLoopSteps`, `agentLoopEvents`, `agentLoopActionApprovals`, `agentLoopArtifacts`, `agentLoopCircuitStates`, `agentLoopControlSettings`, `agentLoopPathLocks`, `agentLoopUsageBuckets`, `agentLoopWorktrees`.
191
+
192
+ Harness: `agentHarnessProfiles`, `agentHarnessProfileVersions`.
193
+
194
+ Observation/memory: `agentExecutionSpans`, `orchestratorConfig`, `orchestratorLogs`, `agentMemoryContexts`.
195
+
196
+ Skill Hub: `skillDefinitions`, `skillExecutions`, `skillLoopConfigs`, `skillWorkerConfigs`, `skillRegistryInstallations`.
197
+
198
+ ## Usage
199
+
200
+ 1. Enable the plugin in the NocoBase Plugin Manager (requires plugin-ai; plugin-git-manager is optional for Git skill import).
201
+ 2. Configure **Policy Profiles** (harness tags) for your risk levels — the seeded `default`, `safe`, and `file-heavy` profiles are a starting point.
202
+ 3. For sub-agent delegation: configure leader↔sub-agent bindings in **Agent Bindings**, add the built-in **AI employee task dispatching** (`dispatch-sub-agent-task`) tool to the leader, and ensure the user role can access both employees.
203
+ 4. For autonomous loops: create a pattern (goal, autonomy level, trigger, roles, harness tags, policy), then trigger runs manually, by cron, or by event; monitor runs in **Native Monitor** and resolve approvals/verification escalations there.
204
+ 5. For skills: define skills in **Skill Hub Definitions** (or import from Git/registry), test them with the test panel, then bind the generated `skill_hub_*` tools to AI employees.