agent-orcha 0.0.5 → 0.0.8

package/dist/templates/skills/orcha-builder/SKILL.md

@@ -5,106 +5,95 @@ description: Documentation for creating and modifying ORCHA resources (agents, w
 
 # ORCHA Resource Schemas
 
-Use this reference when creating or modifying ORCHA resources. All resource files live in the workspace root under their respective directories.
-
----
-
 ## Agents (`agents/<name>.agent.yaml`)
 
 ```yaml
-name: my-agent                    # Unique identifier (kebab-case)
-description: What the agent does  # Human-readable description
-version: "1.0.0"                  # Optional, defaults to 1.0.0
-
+name: my-agent
+description: What the agent does
 llm:
-  name: default                   # LLM config name from llm.json
-  temperature: 0.7                # 0.0 = deterministic, 1.0 = creative
-
+  name: default
+  temperature: 0.7
 prompt:
   system: |
-    You are a helpful assistant.
-    Your instructions go here.
+    Your system prompt here.
   inputVariables:
-    - query                       # Variables injected at runtime
-
-tools:                            # Optional tool references
-  - mcp:server-name               # All tools from an MCP server
-  - knowledge:store-name          # Knowledge search tools
-  - function:my-function          # Custom function tool
-  - builtin:tool-name             # Built-in tool
-  - sandbox:exec                  # Sandbox tools (exec, web_fetch, web_search)
-  - workspace:read                  # Workspace tools (read, write, list, list_resources)
-
-skills:                           # Optional skills
-  - skill-name                    # Skill name from skills directory
-  # OR
-  mode: all                       # Include all available skills
-
-output:                           # Optional output config
-  format: text                    # text | json | structured
-  schema:                         # Required if format is structured
-    type: object
-    properties:
-      result:
-        type: string
-
-memory:                           # Optional conversation memory
+    - query
+tools:                                # mcp:<server> | knowledge:<store> | function:<name>
+  - mcp:server-name                   # builtin:<name> | sandbox:<tool> | workspace:<tool>
+  - knowledge:store-name              # workspace: read, write, delete, list, list_resources, diagnostics
+  - sandbox:browser_navigate          # sandbox: exec, shell, web_fetch, web_search
+                                      # sandbox: browser_navigate, browser_observe, browser_screenshot,
+                                      #   browser_content, browser_click, browser_type, browser_evaluate
+                                      # sandbox: vision_screenshot, vision_navigate, vision_click,
+                                      #   vision_type, vision_scroll, vision_key, vision_drag
+                                      #   (requires EXPERIMENTAL_VISION=true)
+                                      # sandbox: file_read, file_write, file_edit, file_insert, file_replace_lines
+                                      # builtin: ask_user, save_memory
+                                      #   (conditional: integration_post, integration_context, email_send)
+skills:
+  - skill-name                        # or use mode: all to attach all skills
+output:
+  format: text                        # text | structured
+memory:
   enabled: true
-  maxLines: 100                   # Max conversation history lines
-
-metadata:                         # Optional metadata
-  category: general
-  tags:
-    - example
-
-integrations:                     # Optional integrations
+  maxLines: 100
+integrations:
   - type: collabnook
-    url: wss://collabnook.com/ws
+    url: "wss://collabnook.com/ws"          # optional — defaults to wss://collabnook.com/ws
     channel: general
-    botName: MyBot
-
-triggers:                         # Optional triggers
+    botName: Bot
+  - type: email
+    imap:
+      host: imap.gmail.com
+      port: 993
+    smtp:
+      host: smtp.gmail.com
+      port: 587
+    auth:
+      user: agent@example.com
+      pass: pw
+    pollInterval: 60
+    folder: INBOX
+triggers:
   - type: cron
-    schedule: "*/5 * * * *"       # Cron expression
+    schedule: "*/5 * * * *"
     input:
-      query: "Periodic task"
+      query: "Task"
+publish: true                         # or { enabled: true, password: "secret" }
+sampleQuestions:                       # optional — clickable chips shown in chat UI on initial load
+  - "What can you help me with?"
+  - "Summarize the latest report"
 ```
 
----
+Published agents are accessible at `/chat/<agent-name>` with optional per-agent password.
 
 ## Step-Based Workflows (`workflows/<name>.workflow.yaml`)
 
 ```yaml
 name: my-workflow
 description: What the workflow does
-version: "1.0.0"
-type: steps                       # "steps" for step-based workflows
-
+type: steps
 input:
-  schema:                         # Typed input fields
+  schema:
     query:
-      type: string                # string | number | boolean | array | object
+      type: string
       required: true
-      description: "The user query"
-
 steps:
-  - id: step-one                  # Unique step identifier (NOT "name")
-    agent: agent-name             # Agent to invoke
+  - id: step-one
+    agent: agent-name
     input:
-      query: "{{query}}"          # Variable interpolation
-    output:                       # Output is an object (NOT a string)
-      key: step_one_result        # Variable name to store result
-      extract: output             # Optional: extract a specific field
-
+      query: "{{query}}"
+    output:
+      key: step_one_result
+      extract: output
   - id: step-two
     agent: another-agent
     input:
       query: "{{step_one_result}}"
     output:
       key: step_two_result
-    condition: "{{step_one_result}}"  # Optional: skip if falsy
-
-  - parallel:                     # Parallel execution (no "name" key here)
+    condition: "{{step_one_result}}"
+  - parallel:
       - id: branch-a
         agent: agent-a
         input:
@@ -117,223 +106,167 @@ steps:
           query: "{{query}}"
         output:
           key: result_b
-
-config:                           # Optional workflow config
-  timeout: 300000                 # Default 300000ms
-  onError: stop                   # stop | continue | retry
-
+config:
+  timeout: 300000
+  onError: stop                       # stop | continue | retry
 output:
   result: "{{step_two_result}}"
+chatOutputFormat: text                  # text | json
+sampleQuestions:
+  - "Run the pipeline"
 ```
 
----
-
-## LangGraph Workflows (`workflows/<name>.workflow.yaml`)
+## ReAct Workflows (`workflows/<name>.workflow.yaml`)
 
 ```yaml
-name: my-graph-workflow
-description: Graph-based workflow with tool and agent discovery
-version: "1.0.0"
-type: langgraph
-
+name: my-react-workflow
+description: Autonomous workflow with tool and agent discovery
+type: react
 input:
-  schema:                         # Typed input fields (same as step-based)
+  schema:
     query:
       type: string
       required: true
-      description: "The user query"
-
-prompt:                           # REQUIRED for langgraph workflows
+prompt:
   system: |
-    You are a helpful assistant that uses available tools and agents.
-  goal: "Answer the user's query using available tools"
-
+    You are a helpful assistant.
+  goal: "Answer the user's query"
 graph:
-  model: default                  # LLM config name, defaults to "default"
+  model: default
   tools:
-    sources:                      # Tool sources to discover
+    sources:
       - mcp
       - knowledge
       - function
       - builtin
-    mode: all                     # all | none | include | exclude
-    exclude:                      # Optional exclusion list
+    mode: all                         # all | none | include | exclude
+    exclude:
       - dangerous_tool
   agents:
-    mode: all                     # all | none | include | exclude
+    mode: all
     exclude:
-      - architect                  # Prevent recursive invocation
-  executionMode: react            # react | single-turn (default: react)
-  maxIterations: 10               # Max tool-call loops (default: 10)
-  timeout: 300000                 # Timeout in ms (default: 300000)
-
+      - architect
+  executionMode: react                # react | single-turn
+  maxIterations: 10
+  timeout: 300000
 output:
   result: "{{result}}"
+chatOutputFormat: text                  # text | json
+sampleQuestions:
+  - "What can you do?"
 ```
 
----
-
 ## Knowledge Stores (`knowledge/<name>.knowledge.yaml`)
 
 ```yaml
 name: my-knowledge
-description: What this knowledge store contains
-
+description: What this store contains
 source:
-  # Directory source
-  type: directory                 # directory | file | database | web | s3
-  path: ./docs                    # Relative to workspace root
-  pattern: "**/*.md"              # Glob pattern for file matching (NOT "glob")
-  recursive: true                 # Default: true
-
-  # --- OR file source ---
-  # type: file
-  # path: ./data/report.pdf
-
-  # --- OR database source ---
-  # type: database
-  # connectionString: postgresql://user:pass@host:5432/db  # postgresql://, mysql://, or sqlite://
-  # query: "SELECT content FROM documents"
-  # contentColumn: content        # Default: "content"
-  # metadataColumns: [id, title]  # Optional
-  # batchSize: 100                # Optional, default: 100
-
-  # --- OR web source ---
-  # type: web
-  # url: https://example.com/docs
-  # selector: ".main-content"     # Optional CSS selector
-  # headers:                      # Optional custom headers
-  #   Authorization: "Bearer token"
-
-loader:                           # REQUIRED (has defaults)
-  type: text                      # text | pdf | csv | json | markdown
-
+  type: directory                     # directory | file | database | web
+  path: ./docs
+  pattern: "**/*.md"
+  # Web-specific: url, selector (html only), headers, jsonPath (dot-notation for nested arrays)
+loader:                               # optional — defaults: html (web), text (file/directory)
+  type: text                          # text | pdf | csv | json | markdown | html
 splitter:
-  type: recursive                 # character | recursive | token | markdown
+  type: recursive                     # character | recursive | token | markdown
   chunkSize: 1000
   chunkOverlap: 200
-
-embedding: default                # String reference to llm.json config (NOT an object)
-
-search:                           # Optional
+embedding: default                    # reference to llm.json config
+search:
   defaultK: 4
-  scoreThreshold: 0.5             # Optional minimum score
-
-graph:                            # Optional: enable graph entities via direct mapping
+  scoreThreshold: 0.5
+reindex:                              # optional — periodic refresh
+  schedule: "0 * * * *"              # cron expression
+graph:                                # optional — works with database, csv, json (array of objects)
   directMapping:
     entities:
-      - type: Person              # Entity type label
-        idColumn: id              # Column for entity ID
-        nameColumn: name          # Optional: column for display name
-        properties:               # Columns to include as properties
-          - email                 # String = same column name
-          - { role: job_title }   # Object = { propertyName: columnName }
-    relationships:                # Optional: define relationships
+      - type: Person
+        idColumn: id
+        nameColumn: name
+        properties:
+          - email
+          - role: job_title
+    relationships:
       - type: WORKS_FOR
-        source: Person            # Source entity type
-        target: Organization      # Target entity type
+        source: Person
+        target: Organization
         sourceIdColumn: person_id
         targetIdColumn: org_id
-        groupNode: department     # Optional: group by column
 ```
 
----
+Web sources support all loader types. Use `loader.type: json` for APIs, `text` for raw content, `html` (default) for web pages with optional `selector`. Add `headers` for authenticated endpoints. Use `jsonPath` (e.g., `items` or `data.results`) to extract a nested array from the JSON response before parsing.
 
 ## Custom Functions (`functions/<name>.function.js`)
 
 ```javascript
-export const metadata = {
-  name: "my-function",
-  description: "What this function does",
-  version: "1.0.0",
-  tags: ["utility"]
-};
-
+export const metadata = { name: "my-function", description: "What it does" };
 export const parameters = {
   type: "object",
-  properties: {
-    input: {
-      type: "string",
-      description: "The input parameter"
-    }
-  },
+  properties: { input: { type: "string", description: "Input" } },
   required: ["input"]
 };
-
 export default async function({ input }) {
-  // Your logic here
   return { result: `Processed: ${input}` };
 }
 ```
 
----
+Function parameters support automatic type coercion — if an LLM passes a number as a string, it is auto-coerced to the declared type.
 
 ## Skills (`skills/<name>/SKILL.md`)
 
-```markdown
----
-name: my-skill
-description: What this skill teaches the agent
----
+Markdown files with YAML frontmatter (`name`, `description`). Content is injected into the agent's system prompt. Add `sandbox: true` if the skill requires sandbox tools.
 
-# Skill Title
+## MCP Servers (`mcp.json`)
 
-Instructions, context, and knowledge that get injected into the agent's prompt.
-Use markdown formatting for structure.
+```json
+{ "servers": { "name": { "url": "https://example.com/mcp", "enabled": true } } }
 ```
 
-Skills with `sandbox: true` in frontmatter indicate they require sandbox tools.
-
----
-
-## MCP Server Configuration (`mcp.json`)
+Remote: `url`. Local: `command` + `args`. Optional: `headers`, `env`, `timeout`, `transport`, `description`. Transport is auto-detected. To add a server: read `mcp.json`, add entry, write back, then reference as `mcp:<name>` in agent tools.
 
-The `mcp.json` file in the workspace root configures external MCP servers. Agents reference them via `mcp:<server-name>` in their tools list.
+## LLM Configuration (`llm.json`)
 
 ```json
 {
-  "version": "1.0.0",
-  "servers": {
-    "server-name": {
-      "url": "https://example.com/mcp",
-      "description": "What this server provides",
-      "timeout": 30000,
-      "enabled": true
-    }
+  "default": "llama-cpp",
+  "llama-cpp": {
+    "engine": "llama-cpp",
+    "model": "qwen3-8b",
+    "temperature": 0.7,
+    "reasoningBudget": 4096,
+    "thinkingBudget": 4096
   },
-  "globalOptions": {
-    "throwOnLoadError": false,
-    "prefixToolNameWithServerName": true,
-    "additionalToolNamePrefix": "",
-    "defaultToolTimeout": 30000
+  "ollama-model": {
+    "engine": "ollama",
+    "model": "llama3",
+    "temperature": 0.5
+  },
+  "embeddings": {
+    "engine": "llama-cpp",
+    "model": "nomic-embed",
+    "type": "embedding"
+  },
+  "engineUrls": {
+    "llama-cpp": "http://localhost:8080",
+    "mlx-serve": "http://localhost:8081",
+    "ollama": "http://localhost:11434",
+    "lmstudio": "http://localhost:1234"
   }
 }
 ```
 
-**Server config fields:**
-- `url` — Required for remote servers (auto-detects `streamable-http` transport)
-- `command` + `args` — Required for local stdio servers (auto-detects `stdio` transport)
-- `transport` — Explicit: `stdio`, `sse`, `streamable-http`, or `sse-only` (auto-detected if omitted)
-- `headers` — Optional HTTP headers (e.g. for auth)
-- `env` — Optional environment variables (for stdio servers)
-- `description` — Optional human-readable description
-- `timeout` — Request timeout in ms (default: 30000)
-- `enabled` — Set to `false` to disable without removing (default: true)
+The `"default"` key is a string pointer to another config name. Engines: `llama-cpp`, `mlx-serve`, `ollama`, `lmstudio`. Use `reasoningBudget`/`thinkingBudget` for thinking models. Values support `${ENV_VAR}` substitution.
 
-**Adding a new MCP server:**
-1. Read `mcp.json` first to preserve existing servers
-2. Add the new server entry to the `servers` object
-3. Write the updated `mcp.json` back
-4. Create an agent that references it with `tools: [mcp:server-name]`
+## Environment Variable Substitution
 
----
+All YAML and JSON config files support `${ENV_VAR}` and `${ENV_VAR:-default}` syntax. Use this for secrets, URLs, and any values that differ between environments.
 
 ## Best Practices
 
-- **Naming**: Use kebab-case for all resource names (e.g. `weather-bot`, `data-pipeline`)
-- **Temperature**: Use 0.0-0.3 for structured/deterministic tasks, 0.5-0.7 for creative/conversational
-- **Tools**: Only include tools the agent actually needs — fewer tools = better focus
-- **Prompts**: Be specific and include examples in system prompts; use inputVariables for dynamic content
-- **Read before write**: Always read an existing resource before modifying it to preserve fields you're not changing
-- **Uniqueness**: Check `workspace_list_resources` before creating to avoid name collisions
-- **Skills**: Use skills to share knowledge across multiple agents without duplicating prompt content
+- Use kebab-case for all resource names
+- Temperature: 0.0-0.3 for structured tasks, 0.5-0.7 for creative
+- Only include tools the agent actually needs
+- Always read existing resources before modifying them
+- Check `workspace_list_resources` before creating to avoid name collisions
+- Use skills to share knowledge across agents without duplicating prompts

package/dist/templates/skills/pii-guard/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: pii-guard
+description: PII and OWASP security filtering rules
+---
+
+# PII Guard
+
+## Sensitive Data Categories (NEVER include in responses)
+
+- SSN, tax IDs, government identifiers
+- Salary, compensation, financial data
+- Home addresses, personal phone numbers
+- Dates of birth, ages
+- Full email addresses (mask as j***@company.com)
+- Medical, legal, or disciplinary records
+
+## Behavior
+
+- **Default:** silently omit PII from responses — don't announce filtering
+- **Explicit request:** decline politely citing company data policy
+- **User provides PII:** refuse to process, store, or format it
+- **Partial info OK:** name, title, department, general location, hire year

package/dist/templates/skills/sandbox/SKILL.md

@@ -1,63 +1,40 @@
 ---
 name: sandbox
-description: Execute JavaScript code and fetch web content in an isolated sandbox
+description: Execute JavaScript, shell commands, fetch web content, and control a browser
 sandbox: true
 ---
 
-# Sandbox Execution
+# Sandbox Tools
 
-You have access to sandbox tools for running JavaScript code and fetching web content.
+## sandbox_exec
+Run JavaScript in isolated VM. Use `console.log()` for output, `return` for result. No `fetch`/`require` — use `sandbox_web_fetch` for HTTP.
 
-## Tool: sandbox_exec
+## sandbox_shell
+Run shell commands in `/tmp` with limited permissions (Docker only).
 
-Execute JavaScript code in an isolated VM sandbox.
+## sandbox_web_fetch
+Fetch web pages (auto-converted to markdown) or APIs (`raw: true`).
 
-**Parameters:**
-- `code` (required): JavaScript code to execute (runs in async context, so `await` works)
-- `timeout` (optional): Execution timeout in milliseconds
+## sandbox_web_search
+Search DuckDuckGo. Params: `query`, `num_results`.
 
-**Returns:** JSON with `stdout` (console output), `result` (return value), and `error` (if any)
+## Browser Tools
 
-**Available globals:** JSON, Math, Date, Buffer, URL, URLSearchParams, TextEncoder, TextDecoder, setTimeout, and standard JS built-ins.
+Observe → Act → Observe loop. Elements have short refs (e1, e2...) — use them in click/type.
 
-**Not available:** `fetch`, `require`, file system access. Use `sandbox_web_fetch` for HTTP requests.
-
-## Tool: sandbox_web_fetch
-
-Fetch web page content or API responses.
-
-**Parameters:**
-- `url` (required): HTTP or HTTPS URL to fetch
-- `raw` (optional): Return raw content without HTML-to-markdown conversion
-- `runScripts` (optional): Run page JavaScript before extracting content (default: true)
-
-**Returns:** JSON with `content`, `url`, `status`, and `truncated`
-
-## Tool: sandbox_web_search
-
-Search the web using DuckDuckGo.
-
-**Parameters:**
-- `query` (required): Search query
-- `num_results` (optional): Max results to return (default 10)
-
-**Returns:** JSON with `results` (formatted list) and `query`
-
-## Usage Examples
-
-Run JavaScript code:
-```
-sandbox_exec({ code: "const sum = [1,2,3].reduce((a,b) => a+b, 0); console.log(sum); return sum;" })
-```
-
-Fetch a web page:
-```
-sandbox_web_fetch({ url: "https://example.com" })
-```
+| Tool | Use |
+|------|-----|
+| `sandbox_browser_observe` | Text snapshot with element refs. Primary verification tool. |
+| `sandbox_browser_navigate` | Go to URL, wait for ready, return snapshot |
+| `sandbox_browser_click` | Click by ref (`"e3"`) or text (`"Submit"`) |
+| `sandbox_browser_type` | Type by ref (`"e5"`), dispatches input/change events |
+| `sandbox_browser_content` | Page as markdown (optional selector) |
+| `sandbox_browser_evaluate` | Run JS, reports side effects |
+| `sandbox_browser_screenshot` | PNG screenshot (expensive, last resort) |
 
 ## Best Practices
 
-1. Use `console.log()` for output and `return` for the final result
-2. Use `sandbox_web_fetch` for HTTP requests instead of trying to use `fetch` in sandbox_exec
-3. Check the `error` field in results to verify execution success
-4. Handle errors gracefully — read `error` for diagnostics
+1. Use `sandbox_web_fetch` for HTTP — not `fetch` in sandbox_exec
+2. Use observe to verify page state — not screenshots
+3. Use refs from observe output in click/type — don't guess selectors
+4. Check `sideEffects` in evaluate results

package/dist/templates/skills/web-pilot/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: web-pilot
+description: Browser automation — observe-act loop with refs
+sandbox: true
+---
+
+# Web Pilot
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `sandbox_browser_observe` | Text snapshot: URL, title, headings, textExcerpt, elements with refs |
+| `sandbox_browser_navigate` | Go to URL, wait for ready, return snapshot with textExcerpt |
+| `sandbox_browser_click` | Click by ref (e.g. "e3") or visible text |
+| `sandbox_browser_type` | Type into input by ref (e.g. "e5") |
+| `sandbox_browser_content` | Page as markdown (optional CSS selector) |
+| `sandbox_browser_evaluate` | Run JS, reports side effects |
+| `sandbox_browser_screenshot` | PNG screenshot (expensive, last resort) |
+| `sandbox_web_search` | Search DuckDuckGo for URLs |
+
+## Workflow: Observe → Act → Observe
+
+1. **Navigate** → returns snapshot with element refs
+2. **Act** using refs from snapshot: `click({ ref: "e3" })` or `type({ ref: "e5", text: "hello" })`
+3. **Observe** → verify action worked
+4. Repeat. Screenshot only if text can't answer your question.
+
+## Refs
+
+Observe output lists elements like:
+```
+- button "Submit" [ref=e1]
+- textbox [ref=e2] name=email placeholder="Enter email"
+- link "Home" [ref=e3]
+```
+Use refs in click/type: `{ "ref": "e1" }`. Refs update on each observe — always use latest.
+
+## Data Extraction Strategy
+
+1. **Check textExcerpt first** — observe/navigate returns the first 2000 chars of visible text. For many tasks this is enough.
+2. **Use content(selector)** over content() — target a specific section (e.g. `{ selector: "main" }` or `{ selector: ".repo-list" }`) to avoid huge dumps.
+3. **Use evaluate() for structured extraction** — `evaluate({ expression: "..." })` with JS that returns exactly the data you need (e.g. `[...document.querySelectorAll('.repo')].map(...)`)
+4. **Prefer web_fetch for read-only pages** — if you just need page content without interaction, `sandbox_web_fetch` is cheaper than navigating.
+5. **Never repeat a failed approach** — if a tool call returns nothing useful, switch to a different strategy immediately.
+
+## Patterns
+
+- **Click by text:** `{ "text": "Accept cookies" }` (when ref unavailable)
+- **Scroll:** evaluate `window.scrollBy(0, 500)` then observe
+- **Dropdown:** evaluate with value set + change event dispatch