symbiont

Category: Testing & Security | Uploader: ThirdKeyAI | Downloads: 0 | Version: v1.0（Latest）

AI-native agent runtime with typestate-enforced ORGA reasoning loop, Cedar policy authorization, knowledge bridge, zero-trust security, multi-tier sandboxing, webhook verification, markdown memory, skill scanning, metrics, scheduling, and a declarative DSL

Changelog: Source: GitHub https://github.com/ThirdKeyAI/Symbiont

Directory Structure

Current level: Root

📁 .github/
- 📁 workflows/
  - 📄 docker-build.yml 4.5 KB
  - 📄 docs.yml 3.4 KB
  - 📄 publish.yml 1.8 KB
  - 📄 test.yml 2.4 KB
📁 agents/
- 📄 api_aggregator.dsl 2.7 KB
- 📄 data_validator.dsl 2.7 KB
- 📄 format_converter.dsl 2.8 KB
- 📄 incident_tracker.dsl 4.1 KB
- 📄 knowledge_curator.dsl 3.1 KB
- 📄 nlp_processor.dsl 3.0 KB
- 📄 notification_router.dsl 4.4 KB
- 📄 README.md 21.4 KB
- 📄 security_scanner.dsl 4.2 KB
- 📄 webhook_handler.dsl 2.4 KB
- 📄 workflow_orchestrator.dsl 5.4 KB
📁 crates/
- 📁 channel-adapter/
  - 📁 src/
    
    📁 adapters/
    
    📁 mattermost/
    
    📄 api.rs 6.3 KB
    
    📄 events.rs 6.6 KB
    
    📄 mod.rs 8.9 KB
    
    📄 signature.rs 2.2 KB
    
    📁 slack/
    
    📄 api.rs 6.5 KB
    
    📄 events.rs 11.9 KB
    
    📄 mod.rs 10.7 KB
    
    📄 oauth.rs 3.7 KB
    
    📄 signature.rs 4.1 KB
    
    📁 teams/
    
    📄 api.rs 10.0 KB
    
    📄 auth.rs 6.4 KB
    
    📄 events.rs 9.8 KB
    
    📄 mod.rs 11.2 KB
    
    📄 mod.rs 135 B
    
    📄 config.rs 7.9 KB
    
    📄 error.rs 831 B
    
    📄 lib.rs 1.6 KB
    
    📄 logging.rs 4.8 KB
    
    📄 manager.rs 18.0 KB
    
    📄 traits.rs 4.4 KB
    
    📄 types.rs 5.9 KB
  - 📄 Cargo.toml 1.8 KB
  - 📄 README.md 2.3 KB
- 📁 dsl/
  - 📁 src/
    
    📄 lib.rs 51.3 KB
    
    📄 main.rs 3.7 KB
  - 📁 tests/
    
    📁 samples/
    
    📄 invalid_malformed_metadata.dsl 123 B
    
    📄 invalid_missing_brace.dsl 58 B
    
    📄 invalid_unknown_keywords.dsl 195 B
    
    📄 valid_agent_definition.dsl 452 B
    
    📄 valid_agent_with_sandbox.dsl 565 B
    
    📄 valid_channel_definition.dsl 488 B
    
    📄 valid_complete_example.dsl 907 B
    
    📄 valid_complex_metadata.dsl 128 B
    
    📄 valid_simple_metadata.dsl 31 B
    
    📄 valid_simple_metadata.symbi 105 B
    
    📄 parser_tests.rs 26.9 KB
  - 📁 tree-sitter-symbiont/
    
    📁 src/
    
    📁 tree_sitter/
    
    📄 alloc.h 985 B
    
    📄 array.h 10.2 KB
    
    📄 parser.h 7.4 KB
    
    📄 grammar.json 28.1 KB
    
    📄 node-types.json 17.0 KB
    
    📄 parser.c 150.0 KB
    
    📄 grammar.js 5.9 KB
    
    📄 package-lock.json 746 B
    
    📄 package.json 294 B
    
    📄 test.dsl 31 B
  - 📄 .dockerignore 598 B
  - 📄 build.rs 235 B
  - 📄 Cargo.lock 40.7 KB
  - 📄 Cargo.toml 1.5 KB
  - 📄 README.md 6.6 KB
- 📁 repl-cli/
  - 📁 src/
    
    📄 client.rs 1.6 KB
    
    📄 main.rs 5.8 KB
    
    📄 server.rs 4.8 KB
    
    📄 session_manager.rs 1.8 KB
  - 📄 Cargo.toml 798 B
  - 📄 README.md 7.4 KB
- 📁 repl-core/
  - 📁 src/
    
    📁 dsl/
    
    📄 agent_composition.rs 14.5 KB
    
    📄 ast.rs 13.8 KB
    
    📄 evaluator.rs 72.2 KB
    
    📄 lexer.rs 21.8 KB
    
    📄 mod.rs 499 B
    
    📄 parser.rs 54.8 KB
    
    📄 pattern_builtins.rs 19.9 KB
    
    📄 reasoning_builtins.rs 16.1 KB
    
    📄 tests.rs 6.6 KB
    
    📄 determinism.rs 1.1 KB
    
    📄 error.rs 1.1 KB
    
    📄 eval.rs 22.2 KB
    
    📄 execution_monitor.rs 16.1 KB
    
    📄 lib.rs 569 B
    
    📄 policy.rs 6.1 KB
    
    📄 runtime_bridge.rs 5.4 KB
    
    📄 session.rs 932 B
  - 📁 tests/
    
    📁 common/
    
    📄 mod.rs 148 B
    
    📁 samples/
    
    📄 simple_policy.policy 35 B
    
    📄 golden.rs 196 B
  - 📄 Cargo.toml 878 B
  - 📄 README.md 6.7 KB
- 📁 repl-lsp/
  - 📁 src/
    
    📄 backend.rs 2.0 KB
    
    📄 main.rs 304 B
  - 📄 Cargo.toml 604 B
- 📁 repl-proto/
  - 📁 src/
    
    📄 lib.rs 1.4 KB
  - 📄 Cargo.toml 502 B
- 📁 runtime/
  - 📁 .cargo/
    
    📄 config.toml 797 B
  - 📁 benches/
    
    📄 performance_claims.rs 16.3 KB
  - 📁 docs/
    
    📁 api/
    
    📄 internal_apis.md 16.0 KB
    
    📄 openapi.yaml 20.3 KB
    
    📄 tool_review_api.md 12.3 KB
    
    📄 logging.md 13.2 KB
    
    📄 README.md 11.8 KB
    
    📄 tool_invocation_enforcement.md 8.5 KB
    
    📄 tool_review_workflow.md 26.1 KB
  - 📁 examples/
    
    📁 openrouter_git_agent/
    
    📁 src/
    
    📄 config.rs 9.9 KB
    
    📄 git_tools.rs 20.2 KB
    
    📄 main.rs 4.0 KB
    
    📄 modifier.rs 20.5 KB
    
    📄 openai_client.rs 10.2 KB
    
    📄 openrouter.rs 19.4 KB
    
    📄 planner.rs 7.9 KB
    
    📄 validator.rs 7.1 KB
    
    📄 workflow.rs 8.0 KB
    
    📄 .env.example 4.3 KB
    
    📄 Cargo.lock 93.5 KB
    
    📄 Cargo.toml 668 B
    
    📄 config.toml 5.2 KB
    
    📄 README.md 10.5 KB
    
    📄 security_policies.yaml 4.9 KB
    
    📄 basic_agent.rs 2.7 KB
    
    📄 composio_smoke_test.rs 2.1 KB
    
    📄 context_example.rs 17.9 KB
    
    📄 context_persistence_test.rs 8.9 KB
    
    📄 full_system.rs 9.2 KB
    
    📄 rag_example.rs 13.9 KB
    
    📄 schemapin_test.rs 233 B
  - 📁 src/
    
    📁 api/
    
    📄 api_keys.rs 6.2 KB
    
    📄 composio_executor.rs 7.1 KB
    
    📄 coordinator.rs 9.2 KB
    
    📄 coordinator_executor.rs 7.7 KB
    
    📄 middleware.rs 18.0 KB
    
    📄 mod.rs 951 B
    
    📄 routes.rs 36.6 KB
    
    📄 server.rs 18.8 KB
    
    📄 streaming_journal.rs 3.8 KB
    
    📄 traits.rs 7.5 KB
    
    📄 types.rs 17.4 KB
    
    📄 ws_handler.rs 5.2 KB
    
    📄 ws_types.rs 2.1 KB
    
    📁 bin/
    
    📄 symbiont_mcp.rs 16.2 KB
    
    📁 cli_executor/
    
    📁 adapters/
    
    📄 aider.rs 9.9 KB
    
    📄 claude_code.rs 10.4 KB
    
    📄 codex.rs 12.4 KB
    
    📄 mod.rs 211 B
    
    📄 adapter.rs 2.8 KB
    
    📄 executor.rs 16.6 KB
    
    📄 mod.rs 676 B
    
    📄 watchdog.rs 4.9 KB
    
    📁 communication/
    
    📄 mod.rs 39.5 KB
    
    📁 context/
    
    📄 compaction.rs 16.2 KB
    
    📄 embedding.rs 16.2 KB
    
    📄 manager.rs 143.9 KB
    
    📄 markdown_memory.rs 24.2 KB
    
    📄 mod.rs 8.8 KB
    
    📄 token_counter.rs 6.8 KB
    
    📄 types.rs 21.7 KB
    
    📄 vector_db.rs 51.4 KB
    
    📄 vector_db_factory.rs 5.4 KB
    
    📄 vector_db_lance.rs 20.4 KB
    
    📄 vector_db_trait.rs 3.7 KB
    
    📁 error_handler/
    
    📄 mod.rs 28.2 KB
    
    📁 http_input/
    
    📄 config.rs 4.3 KB
    
    📄 llm_client.rs 9.6 KB
    
    📄 mod.rs 698 B
    
    📄 server.rs 25.8 KB
    
    📄 webhook_verify.rs 13.9 KB
    
    📁 integrations/
    
    📁 agentpin/
    
    📄 discovery.rs 7.6 KB
    
    📄 key_store.rs 6.3 KB
    
    📄 mod.rs 507 B
    
    📄 types.rs 9.0 KB
    
    📄 verifier.rs 12.4 KB
    
    📁 composio/
    
    📄 config.rs 10.0 KB
    
    📄 error.rs 2.4 KB
    
    📄 mod.rs 907 B
    
    📄 README.md 4.0 KB
    
    📄 source.rs 15.3 KB
    
    📄 transport.rs 14.5 KB
    
    📁 mcp/
    
    📄 client.rs 24.2 KB
    
    📄 mod.rs 425 B
    
    📄 types.rs 7.9 KB
    
    📁 policy_engine/
    
    📄 engine.rs 30.2 KB
    
    📄 existing.rs 15.5 KB
    
    📄 mod.rs 3.2 KB
    
    📄 types.rs 15.2 KB
    
    📁 schemapin/
    
    📄 key_store.rs 15.5 KB
    
    📄 mod.rs 657 B
    
    📄 native_client.rs 12.5 KB
    
    📄 types.rs 11.8 KB
    
    📄 mod.rs 2.1 KB
    
    📄 sandbox_orchestrator.rs 30.9 KB
    
    📄 tool_invocation.rs 35.8 KB
    
    📁 lifecycle/
    
    📄 mod.rs 27.3 KB
    
    📁 metrics/
    
    📄 file.rs 6.5 KB
    
    📄 mod.rs 15.2 KB
    
    📄 otlp.rs 9.5 KB
    
    📁 models/
    
    📄 catalog.rs 31.9 KB
    
    📄 mod.rs 731 B
    
    📄 README.md 8.2 KB
    
    📄 runners.rs 18.7 KB
    
    📁 rag/
    
    📄 engine.rs 26.4 KB
    
    📄 mod.rs 369 B
    
    📄 tests.rs 13.9 KB
    
    📄 types.rs 10.9 KB
    
    📁 reasoning/
    
    📁 providers/
    
    📄 cloud.rs 18.3 KB
    
    📄 mod.rs 194 B
    
    📄 slm.rs 12.7 KB
    
    📄 agent_registry.rs 5.8 KB
    
    📄 cedar_gate.rs 16.1 KB
    
    📄 circuit_breaker.rs 12.8 KB
    
    📄 context_manager.rs 13.0 KB
    
    📄 conversation.rs 25.0 KB
    
    📄 critic_audit.rs 14.8 KB
    
    📄 executor.rs 15.9 KB
    
    📄 human_critic.rs 11.8 KB
    
    📄 inference.rs 8.7 KB
    
    📄 journal.rs 11.6 KB
    
    📄 knowledge_bridge.rs 19.1 KB
    
    📄 knowledge_executor.rs 4.4 KB
    
    📄 loop_types.rs 20.2 KB
    
    📄 metrics.rs 8.5 KB
    
    📄 mod.rs 2.1 KB
    
    📄 output_schema.rs 14.4 KB
    
    📄 phases.rs 21.5 KB
    
    📄 pipeline_config.rs 11.9 KB
    
    📄 policy_bridge.rs 12.5 KB
    
    📄 pre_hydrate.rs 15.5 KB
    
    📄 progress_tracker.rs 11.0 KB
    
    📄 reasoning_loop.rs 34.3 KB
    
    📄 saga.rs 22.0 KB
    
    📄 scheduler.rs 12.1 KB
    
    📄 schema_validation.rs 17.4 KB
    
    📄 tool_profile.rs 7.9 KB
    
    📄 tracing_spans.rs 6.0 KB
    
    📁 resource/
    
    📄 mod.rs 32.3 KB
    
    📁 routing/
    
    📄 classifier.rs 14.1 KB
    
    📄 confidence.rs 2.2 KB
    
    📄 config.rs 15.5 KB
    
    📄 decision.rs 12.2 KB
    
    📄 engine.rs 45.2 KB
    
    📄 error.rs 7.1 KB
    
    📄 mod.rs 545 B
    
    📄 policy.rs 45.6 KB
    
    📁 sandbox/
    
    📄 e2b.rs 5.4 KB
    
    📄 mod.rs 3.2 KB
    
    📄 native.rs 20.4 KB
    
    📁 scheduler/
    
    📄 cron_scheduler.rs 52.2 KB
    
    📄 cron_types.rs 11.1 KB
    
    📄 delivery.rs 18.7 KB
    
    📄 heartbeat.rs 9.0 KB
    
    📄 job_store.rs 29.3 KB
    
    📄 load_balancer.rs 15.5 KB
    
    📄 mod.rs 51.6 KB
    
    📄 policy_gate.rs 12.7 KB
    
    📄 priority_queue.rs 5.6 KB
    
    📄 task_manager.rs 26.4 KB
    
    📁 secrets/
    
    📄 auditing.rs 11.3 KB
    
    📄 config.rs 14.0 KB
    
    📄 file_backend.rs 19.9 KB
    
    📄 mod.rs 7.6 KB
    
    📄 vault_backend.rs 21.3 KB
    
    📁 skills/
    
    📄 config.rs 2.0 KB
    
    📄 loader.rs 14.7 KB
    
    📄 mod.rs 108 B
    
    📄 scanner.rs 31.1 KB
    
    📁 types/
    
    📄 agent.rs 6.3 KB
    
    📄 communication.rs 6.0 KB
    
    📄 error.rs 11.1 KB
    
    📄 mod.rs 5.6 KB
    
    📄 resource.rs 6.1 KB
    
    📄 security.rs 8.3 KB
    
    📄 config.rs 51.5 KB
    
    📄 crypto.rs 16.8 KB
    
    📄 lib.rs 47.8 KB
    
    📄 logging.rs 41.2 KB
    
    📄 prelude.rs 1.4 KB
  - 📁 tests/
    
    📄 http_input_integration_tests.rs 11.9 KB
    
    📄 integration_tests.rs 11.3 KB
    
    📄 knowledge_reasoning_tests.rs 16.6 KB
    
    📄 mcp_client_tests.rs 13.9 KB
    
    📄 performance_claims.rs 20.2 KB
    
    📄 policy_engine_tests.rs 20.4 KB
    
    📄 rag_integration_tests.rs 22.4 KB
    
    📄 reasoning_live_tests.rs 20.3 KB
    
    📄 resource_policy_integration_tests.rs 14.9 KB
    
    📄 schemapin_integration_tests.rs 19.1 KB
    
    📄 security_tests.rs 14.1 KB
    
    📄 tool_invocation_tests.rs 14.5 KB
    
    📄 vector_backend_integration_tests.rs 2.5 KB
    
    📄 vector_db_integration_tests.rs 16.3 KB
  - 📄 .dockerignore 489 B
  - 📄 API_REFERENCE.md 23.1 KB
  - 📄 BUILD_OPTIMIZATION.md 2.8 KB
  - 📄 Cargo.lock 117.7 KB
  - 📄 Cargo.toml 5.3 KB
  - 📄 README-MCP-CLI.md 8.0 KB
  - 📄 README.md 24.4 KB
  - 📄 SANDBOX_COMMUNICATION.md 12.8 KB
- 📁 symbi-a2ui/
  - 📁 src/
    
    📁 api/
    
    📄 agents.ts 548 B
    
    📄 channels.ts 592 B
    
    📄 client.ts 1.8 KB
    
    📄 schedules.ts 410 B
    
    📄 system.ts 485 B
    
    📄 types.ts 3.9 KB
    
    📄 ws-client.ts 3.0 KB
    
    📄 ws-types.ts 1.5 KB
    
    📁 components/
    
    📁 panels/
    
    📁 audit-trail/
    
    📄 audit-entry-row.ts 3.6 KB
    
    📄 audit-filters.ts 2.9 KB
    
    📄 audit-timeline.ts 3.0 KB
    
    📄 audit-trail-panel.ts 6.5 KB
    
    📁 compliance/
    
    📄 channel-compliance.ts 3.7 KB
    
    📄 compliance-panel.ts 10.8 KB
    
    📄 compliance-score.ts 4.2 KB
    
    📄 policy-summary.ts 3.1 KB
    
    📄 violation-list.ts 3.5 KB
    
    📁 coordinator-chat/
    
    📄 chat-input.ts 2.4 KB
    
    📄 chat-message.ts 6.8 KB
    
    📄 coordinator-chat-panel.ts 8.2 KB
    
    📄 reasoning-trace.ts 1.4 KB
    
    📁 fleet-overview/
    
    📄 agent-card.ts 2.8 KB
    
    📄 agent-list.ts 1.9 KB
    
    📄 fleet-overview-panel.ts 4.2 KB
    
    📄 schedule-summary.ts 3.1 KB
    
    📄 system-health-bar.ts 4.3 KB
    
    📁 shared/
    
    📄 data-table.ts 3.4 KB
    
    📄 empty-state.ts 1.1 KB
    
    📄 loading-spinner.ts 1003 B
    
    📄 search-input.ts 1.6 KB
    
    📄 status-badge.ts 1.4 KB
    
    📄 time-ago.ts 1.5 KB
    
    📁 shell/
    
    📄 app-shell.ts 4.7 KB
    
    📄 header-bar.ts 3.5 KB
    
    📄 nav-sidebar.ts 2.5 KB
    
    📁 styles/
    
    📄 global.css 1.6 KB
    
    📄 main.ts 1.6 KB
  - 📄 .dockerignore 39 B
  - 📄 .gitignore 20 B
  - 📄 Caddyfile 626 B
  - 📄 Dockerfile 656 B
  - 📄 index.html 686 B
  - 📄 package-lock.json 58.0 KB
  - 📄 package.json 402 B
  - 📄 README.md 1.3 KB
  - 📄 tsconfig.json 479 B
  - 📄 vite.config.ts 415 B
📁 docker/
- 📄 compose.dev.yml 100 B
📁 docs/
- 📁 _includes/
  - 📄 head_custom.html 10.5 KB
  - 📄 mermaid.html 516 B
  - 📄 search_data.json 1.9 KB
  - 📄 search_data_by_lang.json 2.1 KB
- 📁 _plugins/
  - 📄 rouge_lexers.rb 947 B
- 📁 _sass/
  - 📁 color_schemes/
    
    📄 green.scss 2.6 KB
  - 📄 custom.scss 4.2 KB
- 📁 assets/
  - 📁 css/
    
    📄 custom.css 1.4 KB
  - 📁 js/
    
    📄 search-data-de.json 69 B
    
    📄 search-data-en.json 69 B
    
    📄 search-data-es.json 69 B
    
    📄 search-data-ja.json 69 B
    
    📄 search-data-pt.json 69 B
    
    📄 search-data-zh-cn.json 72 B
- 📄 .gitignore 248 B
- 📄 _config.yml 2.4 KB
- 📄 api-reference.de.md 28.7 KB
- 📄 api-reference.es.md 29.2 KB
- 📄 api-reference.ja.md 32.2 KB
- 📄 api-reference.md 27.0 KB
- 📄 api-reference.pt.md 29.4 KB
- 📄 api-reference.zh-cn.md 25.9 KB
- 📄 CNAME 17 B
- 📄 contributing.de.md 17.0 KB
- 📄 contributing.es.md 17.3 KB
- 📄 contributing.ja.md 18.9 KB
- 📄 contributing.md 15.5 KB
- 📄 contributing.pt.md 17.5 KB
- 📄 contributing.zh-cn.md 14.2 KB
- 📄 docker.de.md 6.0 KB
- 📄 docker.es.md 6.1 KB
- 📄 docker.ja.md 6.7 KB
- 📄 docker.md 5.6 KB
- 📄 docker.pt.md 6.1 KB
- 📄 docker.zh-cn.md 5.5 KB
- 📄 dsl-guide.de.md 17.7 KB
- 📄 dsl-guide.es.md 17.7 KB
- 📄 dsl-guide.ja.md 18.1 KB
- 📄 dsl-guide.md 17.1 KB
- 📄 dsl-guide.pt.md 17.7 KB
- 📄 dsl-guide.zh-cn.md 16.4 KB
- 📄 dsl-specification.md 8.4 KB
- 📄 favicon.ico 15.0 KB
- 📄 Gemfile 943 B
- 📄 getting-started.de.md 12.7 KB
- 📄 getting-started.es.md 12.5 KB
- 📄 getting-started.ja.md 14.2 KB
- 📄 getting-started.md 11.7 KB
- 📄 getting-started.pt.md 12.8 KB
- 📄 getting-started.zh-cn.md 11.1 KB
- 📄 http-input.de.md 11.6 KB
- 📄 http-input.es.md 11.9 KB
- 📄 http-input.ja.md 12.8 KB
- 📄 http-input.md 10.9 KB
- 📄 http-input.pt.md 11.9 KB
- 📄 http-input.zh-cn.md 10.3 KB
- 📄 index.de.md 10.3 KB
- 📄 index.es.md 10.6 KB
- 📄 index.ja.md 11.8 KB
- 📄 index.md 9.7 KB
- 📄 index.pt.md 10.7 KB
- 📄 index.zh-cn.md 9.1 KB
- 📄 logo-hz2.png 105.9 KB
- 📄 native-execution-guide.de.md 12.7 KB
- 📄 native-execution-guide.es.md 12.5 KB
- 📄 native-execution-guide.ja.md 13.6 KB
- 📄 native-execution-guide.md 11.9 KB
- 📄 native-execution-guide.pt.md 12.7 KB
- 📄 native-execution-guide.zh-cn.md 11.3 KB
- 📄 orga-adaptive.de.md 11.0 KB
- 📄 orga-adaptive.es.md 11.2 KB
- 📄 orga-adaptive.ja.md 12.3 KB
- 📄 orga-adaptive.md 10.3 KB
- 📄 orga-adaptive.pt.md 11.2 KB
- 📄 orga-adaptive.zh-cn.md 9.7 KB
- 📄 reasoning-loop.de.md 15.1 KB
- 📄 reasoning-loop.es.md 15.6 KB
- 📄 reasoning-loop.ja.md 16.4 KB
- 📄 reasoning-loop.md 14.3 KB
- 📄 reasoning-loop.pt.md 15.4 KB
- 📄 reasoning-loop.zh-cn.md 13.8 KB
- 📄 repl-guide.de.md 12.5 KB
- 📄 repl-guide.es.md 12.5 KB
- 📄 repl-guide.ja.md 13.7 KB
- 📄 repl-guide.md 11.6 KB
- 📄 repl-guide.pt.md 12.7 KB
- 📄 repl-guide.zh-cn.md 11.0 KB
- 📄 runtime-architecture.de.md 19.8 KB
- 📄 runtime-architecture.es.md 21.1 KB
- 📄 runtime-architecture.ja.md 21.5 KB
- 📄 runtime-architecture.md 27.8 KB
- 📄 runtime-architecture.pt.md 21.0 KB
- 📄 runtime-architecture.zh-cn.md 17.2 KB
- 📄 scheduling.de.md 24.6 KB
- 📄 scheduling.es.md 24.8 KB
- 📄 scheduling.ja.md 26.2 KB
- 📄 scheduling.md 22.6 KB
- 📄 scheduling.pt.md 24.6 KB
- 📄 scheduling.zh-cn.md 22.4 KB
- 📄 security-model.de.md 29.2 KB
- 📄 security-model.es.md 30.1 KB
- 📄 security-model.ja.md 30.3 KB
- 📄 security-model.md 27.7 KB
- 📄 security-model.pt.md 30.3 KB
- 📄 security-model.zh-cn.md 25.5 KB
📁 examples/
- 📄 native-execution-example.rs 5.1 KB
📁 src/
- 📁 commands/
  - 📄 agents_md.rs 30.6 KB
  - 📄 chat.rs 11.3 KB
  - 📄 cron.rs 16.4 KB
  - 📄 doctor.rs 3.0 KB
  - 📄 dsl.rs 4.5 KB
  - 📄 logs.rs 3.5 KB
  - 📄 mod.rs 147 B
  - 📄 new.rs 14.4 KB
  - 📄 skills.rs 8.4 KB
  - 📄 status.rs 2.4 KB
  - 📄 up.rs 32.1 KB
- 📁 mcp_server/
  - 📄 mod.rs 20.4 KB
- 📄 main.rs 23.2 KB
📁 tools/
- 📁 fuzz/
  - 📁 fuzz_targets/
    
    📄 api_key_store.rs 9.7 KB
    
    📄 crypto_roundtrip.rs 5.4 KB
    
    📄 dsl_evaluator.rs 8.2 KB
    
    📄 dsl_lexer_parser.rs 487 B
    
    📄 dsl_structure_aware.rs 25.8 KB
    
    📄 enforcement_policy_matrix.rs 7.1 KB
    
    📄 fail_closed_tool_invocation.rs 3.6 KB
    
    📄 mattermost_signature_verification.rs 3.7 KB
    
    📄 policy_evaluation.rs 7.6 KB
    
    📄 policy_parser.rs 193 B
    
    📄 schema_verification_garbage.rs 4.5 KB
    
    📄 schemapin_keystore_roundtrip.rs 8.3 KB
    
    📄 sensitive_arg_masking.rs 3.8 KB
    
    📄 slack_signature_verification.rs 9.7 KB
    
    📄 sse_jsonrpc_parsing.rs 9.8 KB
    
    📄 tofu_key_substitution.rs 2.5 KB
    
    📄 tool_substitution_detection.rs 12.1 KB
    
    📄 webhook_verify_generic.rs 6.5 KB
  - 📄 .gitignore 27 B
  - 📄 Cargo.lock 209.4 KB
  - 📄 Cargo.toml 3.0 KB
📄 .dockerignore 1.1 KB
📄 .env.example 3.7 KB
📄 .gitignore 6.8 KB
📄 .schemapin.sig 636 B
📄 AGENTS.md 5.6 KB
📄 Cargo.lock 259.6 KB
📄 Cargo.toml 2.5 KB
📄 CHANGELOG.md 59.9 KB
📄 CLAUDE.md 5.6 KB
📄 CODE_OF_CONDUCT.md 5.4 KB
📄 context7.json 4.0 KB
📄 deny.toml 2.6 KB
📄 Dockerfile 4.2 KB
📄 LICENSE 10.5 KB
📄 logo-hz.png 110.1 KB
📄 README.de.md 5.8 KB
📄 README.es.md 6.0 KB
📄 README.ja.md 6.7 KB
📄 README.md 9.3 KB
📄 README.pt.md 6.1 KB
📄 README.zh-cn.md 5.3 KB
📄 SECURITY.md 5.9 KB
📄 SKILL.md 44.0 KB
📄 symbi-trans.png 65.4 KB

SKILL.md

---
name: symbiont
title: Symbiont
description: AI-native agent runtime with typestate-enforced ORGA reasoning loop, Cedar policy authorization, knowledge bridge, zero-trust security, multi-tier sandboxing, webhook verification, markdown memory, skill scanning, metrics, scheduling, and a declarative DSL
version: 1.6.1
---

# Symbiont Agent Development Skills Guide

**Purpose**: This guide helps AI assistants quickly build secure, compliant Symbiont agents following best practices.

**For Full Documentation**: See [DSL Guide](https://github.com/thirdkeyai/symbiont/blob/main/docs/dsl-guide.md), [DSL Specification](https://github.com/thirdkeyai/symbiont/blob/main/docs/dsl-specification.md), and [Example Agents](https://github.com/thirdkeyai/symbiont/blob/main/agents/README.md)

## What Makes Symbiont Unique

- **ORGA Reasoning Loop**: Typestate-enforced Observe-Reason-Gate-Act cycle with compile-time phase safety
- **Cedar Policy Authorization**: Formal policy evaluation via `cedar-policy` crate's `Authorizer::is_authorized()`
- **Knowledge Bridge**: Context-aware reasoning with vector-backed retrieval and automatic learning persistence
- **Durable Journal**: All 7 loop event types recorded for crash recovery and replay without re-calling the LLM
- **Zero-Trust Security**: All inputs untrusted by default, explicit policies required
- **Policy-as-Code**: Declarative security rules enforced at runtime
- **Multi-Tier Sandboxing**: Docker → gVisor → Firecracker isolation
- **Enterprise Compliance**: HIPAA, SOC2, GDPR patterns built-in
- **Cryptographic Verification**: SchemaPin for MCP tools, AgentPin for agent identity, Ed25519 signatures
- **Webhook DX**: Signature verification middleware with GitHub/Stripe/Slack presets
- **Persistent Memory**: Markdown-backed agent memory with retention and compaction
- **ClawHavoc Security Scanner**: 30+ detection rules across 7 attack categories with 5-level severity model
- **Agent Registry & Lifecycle**: Persistent agent metadata with delete and re-execute lifecycle support
- **AGENTS.md Support**: Full bidirectional agent manifest files for ecosystem interoperability

---

## Quick Start Template

### Minimal Viable Agent

```dsl
metadata {
    version = "1.0.0"
    author = "Your Name"
    description = "Brief description of what this agent does"
    tags = ["category", "use-case"]
}

agent my_agent(input: String) -> String {
    capabilities = ["process_data", "validate_input"]

    policy security_policy {
        // Allow specific operations
        allow: ["read_input", "write_output"] if input.length() < 10000

        // Deny dangerous operations
        deny: ["network_access", "file_system"] if true

        // Require conditions
        require: {
            input_validation: true,
            output_sanitization: true
        }

        // Audit important actions
        audit: {
            log_level: "info",
            include_input: false,  // Don't log sensitive data
            include_output: true
        }
    }

    with memory = "ephemeral", security = "high", timeout = 30000 {
        try {
            // Validate input
            if input.is_empty() {
                return error("Input cannot be empty");
            }

            // Process data
            let result = process(input);

            // Return result
            return result;

        } catch (error) {
            log("ERROR", "Processing failed: " + error.message);
            return error("Processing failed");
        }
    }
}

fn process(data: String) -> String {
    // Your processing logic here
    return data.to_uppercase();
}
```

---

## Agentic Reasoning Loop (ORGA Cycle)

The reasoning loop drives autonomous agent behavior through a typestate-enforced cycle:

1. **Observe** — Collect results from previous tool executions
2. **Reason** — LLM produces proposed actions (tool calls or text responses)
3. **Gate** — Policy engine evaluates each proposed action
4. **Act** — Approved actions are dispatched to tool executors

### Minimal Reasoning Loop

```rust
use std::sync::Arc;
use symbi_runtime::reasoning::{
    ReasoningLoopRunner, LoopConfig, Conversation, ConversationMessage,
    circuit_breaker::CircuitBreakerRegistry,
    context_manager::DefaultContextManager,
    executor::DefaultActionExecutor,
    loop_types::BufferedJournal,
    policy_bridge::DefaultPolicyGate,
};
use symbi_runtime::types::AgentId;

let runner = ReasoningLoopRunner {
    provider: Arc::new(my_inference_provider),
    policy_gate: Arc::new(DefaultPolicyGate::permissive()),
    executor: Arc::new(DefaultActionExecutor::default()),
    context_manager: Arc::new(DefaultContextManager::default()),
    circuit_breakers: Arc::new(CircuitBreakerRegistry::default()),
    journal: Arc::new(BufferedJournal::new(1000)),
    knowledge_bridge: None, // Optional: add KnowledgeBridge for RAG
};

let mut conv = Conversation::with_system("You are a helpful agent.");
conv.push(ConversationMessage::user("What is 6 * 7?"));

let result = runner
    .run(AgentId::new(), conv, LoopConfig::default())
    .await;
```

### Phase Transitions (Compile-Time Safe)

Invalid transitions are caught at compile time:

```
Reasoning → PolicyCheck → ToolDispatching → Observing → Reasoning (loop)
                                                      → Complete (exit)
```

### Journal Events

The journal records all 7 event types for durable execution:

| Event | When | Purpose |
|-------|------|---------|
| `Started` | Loop begin | Configuration snapshot |
| `ReasoningComplete` | After LLM response, before policy | Crash recovery without re-calling LLM |
| `PolicyEvaluated` | After policy check | Action counts, denied counts |
| `ToolsDispatched` | After tool execution | Tool count, wall-clock duration |
| `ObservationsCollected` | After collecting results | Observation count |
| `Terminated` | Loop end | Reason, iterations, usage, duration |
| `RecoveryTriggered` | On tool failure recovery | Strategy, error context |

### Cedar Policy Gate (Feature: `cedar`)

Formal authorization using the `cedar-policy` crate:

```rust
use symbi_runtime::reasoning::cedar_gate::{CedarPolicyGate, CedarPolicy};

let gate = CedarPolicyGate::deny_by_default();

// Cedar policies use entity types: Agent (principal), Action (action), Resource (resource)
gate.add_policy(CedarPolicy {
    name: "allow_respond".into(),
    source: r#"permit(principal, action == Action::"respond", resource);"#.into(),
    active: true,
}).await;

gate.add_policy(CedarPolicy {
    name: "deny_search".into(),
    source: r#"forbid(principal, action == Action::"tool_call::search", resource);"#.into(),
    active: true,
}).await;
```

Action mapping: `tool_call::<name>`, `respond`, `delegate::<target>`, `terminate`.

Cedar semantics enforced: forbid overrides permit, default deny, skip-on-error.

### Knowledge Bridge (Optional)

Add context-aware reasoning with vector-backed retrieval:

```rust
use symbi_runtime::reasoning::KnowledgeBridge;

let bridge = Arc::new(KnowledgeBridge::new(knowledge_config));

let runner = ReasoningLoopRunner {
    // ... other fields ...
    knowledge_bridge: Some(bridge),
};
```

The bridge injects relevant context before each reasoning step and persists learnings after loop completion.

---

## Security-First Policy Patterns

### 1. Data Processing Agent (Read/Transform/Write)

```dsl
policy data_processing_policy {
    // Allow data operations with size limits
    allow: [
        "read_data",
        "transform_data",
        "write_output"
    ] if request.data_size < 10_000_000  // 10MB limit

    // Deny dangerous operations
    deny: [
        "execute_code",
        "spawn_process",
        "network_access"
    ] if true

    // Require validation
    require: {
        input_validation: true,
        output_sanitization: true,
        rate_limiting: "100/minute"
    }

    // Audit with PII protection
    audit: {
        log_level: "info",
        include_input: false,      // Protect PII
        include_output: false,     // Protect PII
        include_metadata: true,
        retention_days: 90
    }
}
```

### 2. API Integration Agent (External Calls)

```dsl
policy api_integration_policy {
    // Allow specific endpoints only
    allow: [
        "https_request"
    ] if request.url.starts_with("https://api.trusted-service.com/")

    // Deny everything else
    deny: [
        "http_request",           // Only HTTPS
        "file_access",
        "database_access"
    ] if true

    // Require security measures
    require: {
        tls_verification: true,
        api_key_rotation: "30_days",
        rate_limiting: "1000/hour",
        timeout: "5000ms"
    }

    // Audit all API calls
    audit: {
        log_level: "info",
        include_request_headers: true,
        include_response_status: true,
        include_latency: true,
        alert_on_errors: true
    }
}
```

### 3. Security Scanning Agent (Audit/Compliance)

```dsl
policy security_scanner_policy {
    // Allow read-only scanning
    allow: [
        "read_files",
        "analyze_code",
        "check_dependencies",
        "validate_configs"
    ] if scan.depth <= 5  // Limit recursion

    // Deny modifications
    deny: [
        "write_files",
        "modify_permissions",
        "execute_code"
    ] if true

    // Require strict controls
    require: {
        signature_verification: true,
        checksum_validation: true,
        sandbox_tier: "Tier2",  // gVisor isolation
        max_scan_time: "300000ms"  // 5 minutes
    }

    // Audit findings
    audit: {
        log_level: "warning",
        include_findings: true,
        include_risk_scores: true,
        alert_on_critical: true,
        compliance_tags: ["HIPAA", "SOC2"]
    }
}
```

### 4. Workflow Orchestration Agent (Multi-Step)

```dsl
policy orchestration_policy {
    // Allow agent coordination
    allow: [
        "invoke_agent",
        "message_passing",
        "state_management"
    ] if orchestration.depth < 10  // Prevent infinite loops

    // Deny resource-intensive ops
    deny: [
        "spawn_unlimited_agents",
        "recursive_orchestration"
    ] if true

    // Require controls
    require: {
        max_concurrent_agents: 50,
        total_timeout: "600000ms",  // 10 minutes
        failure_recovery: "retry_with_backoff",
        circuit_breaker: true
    }

    // Audit workflow
    audit: {
        log_level: "info",
        include_workflow_graph: true,
        include_timing: true,
        include_dependencies: true,
        trace_id: true
    }
}
```

---

## ClawHavoc Security Scanner

Symbiont includes an advanced security scanner with 30+ detection rules across 7 attack categories:

### Built-in Detection Rules

- **Reverse Shells** (7 rules): `pipe-to-shell`, `wget-pipe-to-shell`, etc.
- **Credential Harvesting** (6 rules): Environment file references, secret extraction patterns
- **Network Exfiltration** (3 rules): Data transmission to external endpoints
- **Process Injection** (4 rules): Code injection and process manipulation
- **Privilege Escalation** (5 rules): Permission elevation attempts
- **Symlink/Path Traversal** (2 rules): Directory traversal attacks
- **Downloader Chains** (3 rules): Multi-stage payload delivery

### Severity Model

- **Critical**: Immediate security threat (scans fail on Critical or High findings)
- **High**: Significant security risk
- **Medium**: Moderate security concern
- **Warning**: Potential security issue
- **Info**: Informational finding

### Custom Rules

Add domain-specific detection patterns:

```dsl
security_scanner {
    custom_rules = [
        {
            name: "custom-api-key-leak",
            pattern: "api[_-]?key\\s*[:=]\\s*['\"]?[a-zA-Z0-9]{32,}",
            severity: "Critical",
            description: "Potential API key exposure"
        }
    ]
}
```

### AllowedExecutablesOnly Rule

For strict sandboxed environments:

```dsl
policy strict_execution {
    require: {
        allowed_executables: ["/bin/bash", "/usr/bin/python3", "/usr/bin/curl"],
        executable_whitelist_only: true
    }
}
```

---

## Agent Registry & Lifecycle

Persistent agent metadata storage with full lifecycle management:

```rust
use symbi_runtime::registry::AgentRegistry;

let registry = AgentRegistry::new(registry_config).await?;

// Store agent metadata
registry.register_agent(agent_id, metadata).await?;

// Retrieve agent information
let agent_info = registry.get_agent(agent_id).await?;

// Delete and re-execute lifecycle
registry.delete_agent(agent_id).await?;
registry.re_execute_agent(agent_id, new_config).await?;
```

### AGENTS.md Support

Generate and parse agent manifest files for ecosystem interoperability:

```rust
use symbi_runtime::agents_md::{AgentsManifest, generate_manifest, parse_manifest};

// Generate AGENTS.md from registry
let manifest = generate_manifest(&registry).await?;
std::fs::write("AGENTS.md", manifest)?;

// Parse existing AGENTS.md
let agents = parse_manifest(&manifest_content)?;
for agent in agents {
    registry.register_agent(agent.id, agent.metadata).await?;
}
```

---

## Sandbox Tier Selection Guide

| Tier | Technology | Use Case | Performance | Security | Overhead |
|------|------------|----------|-------------|----------|----------|
| **Tier1** | Docker | General workloads | Fast | Good | Low (~100ms) |
| **Tier2** | gVisor | Untrusted code | Medium | High | Medium (~500ms) |
| **Tier3** | Firecracker | Multi-tenant isolation | Slower | Maximum | High (~2s) |
| **Native** | Process only | Development ONLY | Fastest | None | Minimal |

**Selection Guide**:
- **Tier1 (Docker)**: Default choice for most agents
- **Tier2 (gVisor)**: Processing external data, user-provided code
- **Tier3 (Firecracker)**: Highly sensitive, regulatory compliance
- **Native**: NEVER use in production (development/testing only)

---

## DSL Syntax Cheatsheet

### Type System

```dsl
// Primitives
let name: String = "value";
let count: Integer = 42;
let price: Float = 19.99;
let active: Boolean = true;
let data: Bytes = [0x01, 0x02, 0x03];

// Collections
let tags: Array<String> = ["tag1", "tag2"];
let config: Map<String, String> = {"key": "value"};
let unique: Set<Integer> = {1, 2, 3};

// Security-Aware Types
let sensitive: EncryptedData<String> = encrypt("secret");
let private_data: PrivateData<Integer> = private(123);
let verified: VerifiableResult<String> = sign("data");

// Optional Types
let optional: Optional<String> = Some("value");
let none_value: Optional<String> = None;
```

### Control Flow

```dsl
// If/Else
if condition {
    // true branch
} else if other_condition {
    // else if branch
} else {
    // false branch
}

// Match (Pattern Matching)
match value {
    Some(x) => process(x),
    None => default_value,
    Error(e) => handle_error(e)
}

// Loops
for item in collection {
    process(item);
}

while condition {
    do_work();
}

// Error Handling
try {
    risky_operation();
} catch (error) {
    log("ERROR", error.message);
    return error("Operation failed");
}
```

### Policy Language

```dsl
policy policy_name {
    // Allow operations with conditions
    allow: ["operation1", "operation2"] if condition
    allow: "operation3" if complex.condition && other.check

    // Deny operations
    deny: ["dangerous_op"] if true
    deny: "risky_op" if environment == "production"

    // Required conditions
    require: {
        authentication: true,
        authorization: "role:admin",
        encryption: "AES-256-GCM",
        rate_limit: "100/second"
    }

    // Audit specification
    audit: {
        log_level: "info" | "warning" | "error",
        include_input: boolean,
        include_output: boolean,
        retention_days: integer,
        compliance_tags: array<string>
    }
}
```

### With Block (Execution Context)

```dsl
with
    memory = "ephemeral" | "persistent",
    privacy = "strict" | "medium" | "low",
    security = "high" | "medium" | "low",
    sandbox = "Tier1" | "Tier2" | "Tier3",
    timeout = milliseconds,
    requires = ["clearance:level5", "approval:manager"]
{
    // Agent implementation
}
```

---

## Integration Patterns

### 1. Secrets Management (Vault/OpenBao)

```dsl
agent secure_api_caller(endpoint: String) -> String {
    policy secret_access {
        allow: ["read_secret"] if secret.path.starts_with("application/")
        deny: ["write_secret", "delete_secret"] if true

        require: {
            vault_auth: true,
            token_rotation: "1_hour"
        }

        audit: {
            log_level: "warning",
            include_secret_path: true,
            include_secret_value: false  // NEVER log secrets
        }
    }

    with memory = "ephemeral", security = "high" {
        // Reference secrets using vault:// protocol
        let api_key = vault://application/api/key;
        let api_secret = vault://application/api/secret;

        // Use secrets in API call
        let response = http.post(endpoint, {
            headers: {
                "Authorization": "Bearer " + api_key,
                "X-API-Secret": api_secret
            }
        });

        return response.body;
    }
}
```

### 2. MCP Tool Integration (Cryptographic Verification)

```dsl
agent mcp_tool_user(tool_name: String, input: String) -> String {
    capabilities = ["invoke_mcp_tool"]

    policy mcp_security {
        // Only allow verified tools
        allow: ["mcp_invoke"] if tool.verified == true
        deny: ["mcp_invoke"] if tool.signature_invalid

        require: {
            schema_pin_verification: true,  // ECDSA P-256
            tofu_trust_model: true,         // Trust-On-First-Use
            tool_review_required: false     // Auto for signed tools
        }

        audit: {
            log_level: "info",
            include_tool_signature: true,
            include_tool_schema: true
        }
    }

    with security = "high" {
        // Discover and invoke MCP tool
        let tool = mcp.discover(tool_name);

        // Verify cryptographic signature
        if !tool.verify_signature() {
            return error("Tool signature verification failed");
        }

        // Invoke tool
        let result = mcp.invoke(tool, input);
        return result;
    }
}
```

### 3. HTTP Webhook Processing

```dsl
agent webhook_processor(request: HttpRequest) -> HttpResponse {
    capabilities = ["process_webhook", "validate_signature"]

    policy webhook_policy {
        allow: ["parse_json", "validate_data"] if request.size < 1_000_000
        deny: ["execute_code", "file_access"] if true

        require: {
            signature_verification: true,
            rate_limiting: "1000/minute",
            timeout: "5000ms"
        }

        audit: {
            log_level: "info",
            include_request_id: true,
            include_source_ip: true,
            alert_on_invalid_signature: true
        }
    }

    with memory = "ephemeral", timeout = 5000 {
        // Verify webhook signature (e.g., GitHub, Stripe)
        let signature = request.headers["X-Webhook-Signature"];
        let secret = vault://webhooks/secret;

        if !verify_hmac_sha256(request.body, secret, signature) {
            return HttpResponse(401, "Invalid signature");
        }

        // Parse and process webhook
        let data = json.parse(request.body);
        let result = process_event(data);

        return HttpResponse(200, json.stringify(result));
    }
}
```

### 4. Scheduled Execution

```dsl
metadata {
    schedule = "0 */6 * * *"  // Every 6 hours (cron format)
}

agent scheduled_cleanup() -> String {
    capabilities = ["cleanup_data", "archival"]

    policy cleanup_policy {
        allow: ["read_old_data", "archive", "delete"] if data.age > 90_days
        deny: ["delete"] if data.age <= 90_days

        require: {
            backup_verification: true,
            retention_check: true
        }

        audit: {
            log_level: "warning",
            include_deleted_count: true,
            include_archived_count: true
        }
    }

    with memory = "persistent", timeout = 300000 {
        let old_data = query_old_data(90);
        let archived_count = archive_data(old_data);
        let deleted_count = delete_archived_data(old_data);

        return "Archived: " + archived_count + ", Deleted: " + deleted_count;
    }
}
```

### 5. Persistent Memory (DSL Configuration)

```dsl
// Top-level memory block — configures Markdown-backed agent memory
memory agent_memory {
    store    markdown           // Storage backend (markdown only for now)
    path     "data/agents"     // Root directory for memory files
    retention 90d              // How long daily logs are kept
    search {
        vector_weight  0.7     // Semantic similarity weight
        keyword_weight 0.3     // BM25 keyword match weight
    }
}
```

Memory files are human-readable Markdown stored at `data/agents/{agent_id}/memory.md` with sections for Facts, Procedures, and Learned Patterns. Daily interaction logs are appended to `logs/{date}.md` and compacted based on retention policy.

**REPL Commands**:
- `:memory inspect <agent-id>` — Display agent's memory.md
- `:memory compact <agent-id>` — Flush daily logs, remove expired entries
- `:memory purge <agent-id>` — Delete all memory for an agent

### 6. Webhook Endpoints (DSL Configuration)

```dsl
// Top-level webhook block — defines verified webhook endpoints
webhook github_events {
    path     "/hooks/github"
    provider github                              // Preset: github, stripe, slack, custom
    secret   "secret://vault/github-webhook-secret"  // HMAC secret (supports vault refs)
    agent    code_review_agent                   // Route to this agent
    filter {
        json_path "$.action"
        equals    "opened"                       // Only process "opened" events
    }
}
```

Provider presets configure signature verification automatically:
- **github**: `X-Hub-Signature-256` header, `sha256=` prefix, HMAC-SHA256
- **stripe**: `Stripe-Signature` header, HMAC-SHA256
- **slack**: `X-Slack-Signature` header, `v0=` prefix, HMAC-SHA256
- **custom**: `X-Signature` header, HMAC-SHA256

All signatures are verified using constant-time comparison before the request reaches the agent handler. Invalid signatures return HTTP 401.

**REPL Commands**:
- `:webhook list` — Show configured webhook definitions

### 7. Persistent Memory & RAG Engine

```dsl
agent knowledge_assistant(query: String) -> String {
    capabilities = ["semantic_search", "rag_retrieval", "synthesis"]

    policy knowledge_policy {
        allow: [
            "vector_search",
            "knowledge_retrieval",
            "context_synthesis"
        ] if query.length() < 1000

        deny: ["knowledge_modification"] if true

        require: {
            embedding_model: "all-MiniLM-L6-v2",
            similarity_threshold: 0.7,
            max_results: 10
        }

        audit: {
            log_level: "info",
            include_query: true,
            include_relevance_scores: true
        }
    }

    with memory = "persistent", security = "medium" {
        // Semantic search in vector database
        let context = rag.search(query, {
            top_k: 5,
            similarity_threshold: 0.7
        });

        // Synthesize response
        let response = synthesize(query, context);

        // Store interaction for future learning
        memory.store({
            query: query,
            response: response,
            timestamp: now()
        });

        return response;
    }
}
```

### 8. Inter-Agent Communication

```dsl
agent coordinator(task: String) -> String {
    capabilities = ["message_passing", "agent_coordination"]

    policy coordination_policy {
        allow: [
            "send_message",
            "receive_message",
            "invoke_agent"
        ] if coordination.depth < 5

        deny: ["broadcast"] if true  // Prevent message storms

        require: {
            message_encryption: true,  // AES-256-GCM
            message_signing: true,     // Ed25519
            max_concurrent_agents: 10
        }

        audit: {
            log_level: "info",
            include_message_flow: true,
            include_agent_graph: true
        }
    }

    with memory = "persistent" {
        // Invoke specialized agent
        let validator_response = agent.invoke("data_validator", {
            data: task
        });

        // Send encrypted message to another agent
        agent.send_message("processor_agent", {
            type: "process_request",
            payload: validator_response,
            priority: "high"
        });

        // Wait for response
        let result = agent.receive_message(timeout = 10000);

        return result.payload;
    }
}
```

---

## Common Agent Patterns

### Pattern 1: Data Validation Pipeline

```dsl
agent data_validator(data: String, schema: String) -> ValidationResult {
    capabilities = ["schema_validation", "data_quality_check"]

    policy validation_policy {
        allow: ["parse_schema", "validate_data", "quality_scoring"]
        deny: ["modify_data", "execute_code"]
        require: {
            max_data_size: "10MB",
            timeout: "5000ms"
        }
        audit: {
            log_level: "warning",
            include_validation_errors: true
        }
    }

    with memory = "ephemeral", security = "high" {
        try {
            // Parse schema
            let parsed_schema = json.parse(schema);

            // Validate against schema
            let validation = validate(data, parsed_schema);

            // Calculate quality score
            let quality_score = calculate_quality(data);

            return ValidationResult {
                valid: validation.success,
                errors: validation.errors,
                quality_score: quality_score,
                recommendations: generate_recommendations(validation)
            };

        } catch (error) {
            return ValidationResult {
                valid: false,
                errors: [error.message],
                quality_score: 0.0,
                recommendations: []
            };
        }
    }
}
```

### Pattern 2: Format Converter

```dsl
agent format_converter(data: String, from_format: String, to_format: String) -> String {
    capabilities = ["parse_format", "transform_data", "serialize_format"]

    policy conversion_policy {
        allow: ["parse", "transform", "serialize"] if data.size < 50_000_000
        deny: ["execute_code", "file_access"]
        require: {
            supported_formats: ["json", "xml", "yaml", "csv"],
            charset_validation: true
        }
        audit: {
            log_level: "info",
            include_conversion_stats: true
        }
    }

    with memory = "ephemeral", timeout = 10000 {
        // Validate formats
        if !is_supported(from_format) || !is_supported(to_format) {
            return error("Unsupported format");
        }

        // Parse source format
        let parsed = parse(data, from_format);

        // Transform to intermediate representation
        let transformed = normalize(parsed);

        // Serialize to target format
        let result = serialize(transformed, to_format);

        return result;
    }
}
```

### Pattern 3: API Aggregator

```dsl
agent api_aggregator(sources: Array<String>) -> AggregatedData {
    capabilities = ["parallel_requests", "data_normalization", "deduplication"]

    policy aggregation_policy {
        allow: ["https_request"] if url in sources
        deny: ["http_request", "file_access"]
        require: {
            tls_verification: true,
            concurrent_limit: 10,
            timeout_per_request: "3000ms",
            total_timeout: "15000ms"
        }
        audit: {
            log_level: "info",
            include_source_latencies: true,
            alert_on_source_failure: true
        }
    }

    with memory = "ephemeral", timeout = 15000 {
        let results = [];

        // Parallel fetch from all sources
        for source in sources {
            async {
                try {
                    let response = http.get(source, {
                        timeout: 3000,
                        verify_tls: true
                    });
                    results.push(response.json());
                } catch (error) {
                    log("WARNING", "Source failed: " + source);
                }
            }
        }

        // Wait for all requests
        await_all(results);

        // Normalize and deduplicate
        let normalized = normalize_data(results);
        let deduplicated = deduplicate(normalized);

        return AggregatedData {
            sources: sources.length,
            records: deduplicated.length,
            data: deduplicated
        };
    }
}
```

### Pattern 4: Security Scanner

```dsl
agent security_scanner(target: String, scan_type: String) -> ScanReport {
    capabilities = [
        "vulnerability_detection",
        "dependency_analysis",
        "compliance_check"
    ]

    policy scanner_policy {
        allow: [
            "read_files",
            "analyze_dependencies",
            "check_vulnerabilities"
        ] if scan.depth <= 10

        deny: [
            "write_files",
            "execute_code",
            "network_access"
        ]

        require: {
            sandbox_tier: "Tier2",  // gVisor isolation
            cvss_scoring: true,
            cwe_classification: true
        }

        audit: {
            log_level: "warning",
            include_findings: true,
            include_cvss_scores: true,
            compliance_tags: ["OWASP", "CWE"]
        }
    }

    with memory = "ephemeral", security = "high", sandbox = "Tier2" {
        let findings = [];

        // Scan based on type
        match scan_type {
            "dependencies" => {
                findings = scan_dependencies(target);
            },
            "vulnerabilities" => {
                findings = scan_vulnerabilities(target);
            },
            "compliance" => {
                findings = check_compliance(target, ["HIPAA", "SOC2"]);
            },
            _ => {
                return error("Unknown scan type");
            }
        }

        // Calculate risk score
        let risk_score = calculate_risk(findings);

        return ScanReport {
            target: target,
            scan_type: scan_type,
            findings_count: findings.length,
            critical_count: count_by_severity(findings, "CRITICAL"),
            high_count: count_by_severity(findings, "HIGH"),
            risk_score: risk_score,
            findings: findings,
            recommendations: generate_remediation(findings)
        };
    }
}
```

### Pattern 5: Notification Router

```dsl
agent notification_router(event: Event, routing_rules: RoutingRules) -> String {
    capabilities = ["event_filtering", "multi_channel_delivery", "retry_logic"]

    policy notification_policy {
        allow: [
            "send_email",
            "send_slack",
            "send_webhook"
        ] if event.priority != "spam"

        deny: ["send_sms"] if event.priority == "low"  // Cost control

        require: {
            rate_limiting: "100/minute",
            retry_attempts: 3,
            backoff_strategy: "exponential"
        }

        audit: {
            log_level: "info",
            include_delivery_status: true,
            include_retry_count: true
        }
    }

    with memory = "ephemeral" {
        // Filter event
        if !should_notify(event, routing_rules) {
            return "Event filtered";
        }

        // Determine channels
        let channels = select_channels(event, routing_rules);

        // Send notifications with retry
        let results = [];
        for channel in channels {
            let success = send_with_retry(channel, event, max_attempts = 3);
            results.push({channel: channel, success: success});
        }

        return format_results(results);
    }
}
```

### Pattern 6: Workflow Orchestrator

```dsl
agent workflow_orchestrator(workflow_spec: WorkflowSpec) -> WorkflowResult {
    capabilities = [
        "step_execution",
        "dependency_resolution",
        "failure_recovery"
    ]

    policy orchestration_policy {
        allow: [
            "invoke_agent",
            "manage_state",
            "handle_errors"
        ] if workflow.depth < 10

        deny: [
            "recursive_workflows",
            "unlimited_agents"
        ]

        require: {
            max_concurrent_steps: 20,
            total_timeout: "600000ms",  // 10 minutes
            checkpoint_enabled: true,
            circuit_breaker: true
        }

        audit: {
            log_level: "info",
            include_workflow_graph: true,
            include_step_timing: true,
            include_failure_trace: true
        }
    }

    with memory = "persistent", timeout = 600000 {
        let state = WorkflowState.new(workflow_spec);

        try {
            // Execute workflow steps
            for step in workflow_spec.steps {
                // Check dependencies
                if !dependencies_met(step, state) {
                    await_dependencies(step, state);
                }

                // Execute step
                let result = execute_step(step, state);

                // Update state with checkpoint
                state.complete_step(step.id, result);
                checkpoint(state);
            }

            return WorkflowResult {
                status: "completed",
                outputs: state.collect_outputs(),
                execution_time: state.elapsed_time()
            };

        } catch (error) {
            // Attempt recovery
            if can_recover(error, state) {
                let recovered_state = recover_workflow(state);
                return resume_workflow(recovered_state);
            }

            return WorkflowResult {
                status: "failed",
                error: error.message,
                completed_steps: state.completed_steps(),
                checkpoint: state.last_checkpoint()
            };
        }
    }
}
```

---

## Security Anti-Patterns to Avoid

### ❌ Anti-Pattern 1: Missing Policy Definitions

```dsl
// BAD: No policies defined
agent insecure_agent(input: String) -> String {
    with memory = "ephemeral" {
        return process(input);
    }
}
```

✅ **Fix**: Always define explicit policies

```dsl
agent secure_agent(input: String) -> String {
    policy security_policy {
        allow: ["process_data"] if input.length() < 10000
        deny: ["network_access", "file_access"]
        require: {input_validation: true}
        audit: {log_level: "info"}
    }

    with memory = "ephemeral" {
        return process(input);
    }
}
```

### ❌ Anti-Pattern 2: Overly Permissive Policies

```dsl
// BAD: Allows everything
policy bad_policy {
    allow: "*" if true
}
```

✅ **Fix**: Use principle of least privilege

```dsl
policy good_policy {
    // Only allow what's needed
    allow: ["read_data", "write_output"] if authorized
    // Explicitly deny risky operations
    deny: ["execute_code", "network_access", "file_system"]
    require: {authentication: true}
}
```

### ❌ Anti-Pattern 3: No Resource Limits

```dsl
// BAD: No timeout, unlimited memory
with memory = "persistent" {
    // Could run forever or consume unlimited memory
    while true {
        expensive_operation();
    }
}
```

✅ **Fix**: Always set resource limits

```dsl
with
    memory = "ephemeral",       // Use ephemeral when possible
    timeout = 30000,            // 30 second timeout
    max_memory_mb = 512,        // Memory limit
    max_cpu_cores = 1.0         // CPU limit
{
    for item in limited_dataset {
        process(item);
    }
}
```

### ❌ Anti-Pattern 4: Logging Sensitive Data

```dsl
// BAD: Logs passwords and secrets
audit: {
    log_level: "info",
    include_input: true,   // Will log passwords!
    include_output: true
}
```

✅ **Fix**: Never log sensitive data

```dsl
audit: {
    log_level: "info",
    include_input: false,      // Protect PII/secrets
    include_output: false,     // Protect PII/secrets
    include_metadata: true,    // OK to log metadata
    include_timing: true       // OK to log performance
}
```

### ❌ Anti-Pattern 5: Hardcoded Secrets

```dsl
// BAD: API key hardcoded
let api_key = "sk_live_abc123xyz789";
```

✅ **Fix**: Use Vault references

```dsl
// GOOD: Secret from Vault
let api_key = vault://application/api/key;
```

### ❌ Anti-Pattern 6: No Input Validation

```dsl
// BAD: No validation
agent bad_agent(input: String) -> String {
    return execute_command(input);  // Command injection risk!
}
```

✅ **Fix**: Always validate input

```dsl
agent good_agent(input: String) -> String {
    // Validate input
    if !is_valid_input(input) {
        return error("Invalid input");
    }

    // Sanitize before use
    let sanitized = sanitize(input);
    return safe_process(sanitized);
}
```

### ❌ Anti-Pattern 7: Wrong Sandbox Tier

```dsl
// BAD: Processing untrusted code in Tier1
agent code_runner(untrusted_code: String) -> String {
    with sandbox = "Tier1" {  // Not enough isolation!
        return eval(untrusted_code);
    }
}
```

✅ **Fix**: Use appropriate sandbox tier

```dsl
agent code_runner(untrusted_code: String) -> String {
    policy strict_isolation {
        deny: ["file_access", "network_access"]
        require: {sandbox_tier: "Tier3"}
    }

    with sandbox = "Tier3" {  // Firecracker microVM
        return safe_eval(untrusted_code);
    }
}
```

### ❌ Anti-Pattern 8: No Error Handling

```dsl
// BAD: Unhandled errors will crash agent
agent fragile_agent(url: String) -> String {
    let response = http.get(url);  // What if this fails?
    return response.body;
}
```

✅ **Fix**: Always handle errors

```dsl
agent robust_agent(url: String) -> String {
    try {
        let response = http.get(url, timeout = 5000);

        if response.status != 200 {
            return error("HTTP error: " + response.status);
        }

        return response.body;

    } catch (error) {
        log("ERROR", "Request failed: " + error.message);
        return error("Request failed");
    }
}
```

---

## Validation Checklist

Before deploying an agent, verify:

### Security Checklist
- [ ] **Policies defined** for all operations
- [ ] **Principle of least privilege** applied (deny by default)
- [ ] **Sandbox tier** appropriate for workload
- [ ] **Secrets** referenced via Vault (never hardcoded)
- [ ] **Input validation** present for all user inputs
- [ ] **Output sanitization** prevents injection attacks
- [ ] **No sensitive data** in audit logs

### Resource Management
- [ ] **Timeout** configured appropriately
- [ ] **Memory limits** set based on workload
- [ ] **CPU limits** defined
- [ ] **Concurrency limits** for agent invocations
- [ ] **Rate limiting** configured for external calls

### Error Handling
- [ ] **Try/catch blocks** around risky operations
- [ ] **Error messages** are informative but not leaking secrets
- [ ] **Retry logic** for transient failures
- [ ] **Circuit breakers** for cascading failures
- [ ] **Graceful degradation** when dependencies fail

### Compliance & Audit
- [ ] **Audit logging** configured
- [ ] **Compliance tags** added (HIPAA, SOC2, GDPR as needed)
- [ ] **Retention policies** set appropriately
- [ ] **PII handling** follows regulations
- [ ] **Data encryption** at rest and in transit

### Testing
- [ ] **Unit tests** for core functions
- [ ] **Integration tests** with dependencies
- [ ] **Security tests** (injection, overflow, etc.)
- [ ] **Performance tests** (within resource limits)
- [ ] **Chaos tests** (failure scenarios)

---

## Quick Reference

### Built-in Functions

| Category | Function | Purpose |
|----------|----------|---------|
| **String** | `len(s)` | String length |
| | `to_upper(s)` | Convert to uppercase |
| | `to_lower(s)` | Convert to lowercase |
| | `trim(s)` | Remove whitespace |
| | `split(s, delim)` | Split string |
| | `contains(s, substr)` | Check substring |
| **JSON** | `json.parse(s)` | Parse JSON string |
| | `json.stringify(obj)` | Convert to JSON |
| | `json.validate(s, schema)` | Validate against schema |
| **HTTP** | `http.get(url, opts)` | HTTP GET request |
| | `http.post(url, body, opts)` | HTTP POST request |
| | `verify_hmac_sha256(data, secret, sig)` | Verify HMAC signature |
| **Crypto** | `encrypt(data)` | AES-256-GCM encrypt |
| | `decrypt(data)` | AES-256-GCM decrypt |
| | `hash_sha256(data)` | SHA-256 hash |
| | `sign(data)` | Ed25519 signature |
| **Time** | `now()` | Current timestamp |
| | `sleep(ms)` | Sleep for milliseconds |
| | `format_time(ts, fmt)` | Format timestamp |
| **Logging** | `log(level, msg)` | Log message |
| | `debug(msg)` | Debug log |
| | `info(msg)` | Info log |
| | `warn(msg)` | Warning log |
| | `error(msg)` | Error log |
| **Validation** | `is_valid_email(s)` | Email validation |
| | `is_valid_url(s)` | URL validation |
| | `is_valid_json(s)` | JSON validation |
| **Arrays** | `push(arr, item)` | Add to array |
| | `pop(arr)` | Remove from array |
| | `map(arr, fn)` | Map function |
| | `filter(arr, fn)` | Filter array |
| | `reduce(arr, fn, init)` | Reduce array |

### Resource Limit Recommendations

| Workload Type | Memory | CPU | Timeout | Sandbox |
|---------------|--------|-----|---------|---------|
| **Data Validation** | 256MB | 0.5 | 5s | Tier1 |
| **Format Conversion** | 512MB | 1.0 | 10s | Tier1 |
| **API Integration** | 512MB | 1.0 | 15s | Tier1 |
| **Code Analysis** | 1GB | 2.0 | 30s | Tier2 |
| **Security Scan** | 2GB | 2.0 | 60s | Tier2 |
| **ML Inference** | 4GB | 4.0 | 120s | Tier2 |
| **Workflow Orchestration** | 1GB | 1.0 | 600s | Tier1 |
| **Untrusted Code** | 512MB | 1.0 | 10s | Tier3 |

### Common Error Codes

| Code | Meaning | Resolution |
|------|---------|------------|
| `POLICY_VIOLATION` | Operation denied by policy | Check policy allow/deny rules |
| `RESOURCE_EXCEEDED` | Resource limit reached | Increase limits or optimize code |
| `TIMEOUT` | Execution timeout | Increase timeout or optimize |
| `AUTH_FAILED` | Authentication failed | Check Vault credentials |
| `SIGNATURE_INVALID` | Crypto signature invalid | Verify tool signature |
| `SANDBOX_ERROR` | Sandbox isolation failed | Check sandbox tier compatibility |
| `VALIDATION_ERROR` | Input validation failed | Fix input data format |
| `NETWORK_ERROR` | Network request failed | Check endpoint and connectivity |

### Performance Benchmarks (v1.6.1)

Verified performance claims:
- **Policy evaluation**: <1ms (release builds)
- **ECDSA P-256 signing**: <5ms (release builds)
- **SchemaPin verification**: <5ms (release builds)
- **10k agent scheduling**: <2% CPU overhead

*Note: Debug builds have relaxed thresholds due to unoptimized crypto*

### Documentation Links

- **Full DSL Guide**: [docs/dsl-guide.md](https://github.com/thirdkeyai/symbiont/blob/main/docs/dsl-guide.md)
- **DSL Specification**: [docs/dsl-specification.md](https://github.com/thirdkeyai/symbiont/blob/main/docs/dsl-specification.md)
- **Reasoning Loop Guide**: [docs/reasoning-loop.md](https://github.com/thirdkeyai/symbiont/blob/main/docs/reasoning-loop.md)
- **Example Agents**: [agents/README.md](https://github.com/thirdkeyai/symbiont/blob/main/agents/README.md) (8 production examples)
- **Runtime Architecture**: [docs/runtime-architecture.md](https://github.com/thirdkeyai/symbiont/blob/main/docs/runtime-architecture.md)
- **API Reference**: [docs/api-reference.md](https://github.com/thirdkeyai/symbiont/blob/main/docs/api-reference.md)
- **Security Model**: [docs/security-model.md](https://github.com/thirdkeyai/symbiont/blob/main/docs/security-model.md)
- **Getting Started**: [docs/getting-started.md](https://github.com/thirdkeyai/symbiont/blob/main/docs/getting-started.md)

---

## Pro Tips for AI Assistants

1. **Always Start with Security**: Design policies before implementation
2. **Use Example Agents**: Adapt from the 8 production agents in `/agents/`
3. **Validate Early**: Add input validation at the beginning
4. **Handle Errors Gracefully**: Wrap risky operations in try/catch
5. **Log Thoughtfully**: Audit what matters, never log secrets
6. **Choose Right Sandbox**: Match tier to threat model
7. **Test Incrementally**: Start simple, add features with tests
8. **Document Assumptions**: Comment complex policy logic
9. **Monitor Resources**: Set realistic limits based on workload
10. **Review Before Deploy**: Use the validation checklist
11. **Leverage ClawHavoc**: Use built-in security scanner for skill validation
12. **Use Agent Registry**: Track agent lifecycle and metadata properly

---

**End of SKILLS.md**

*This guide prioritizes security, compliance, and best practices for building production-grade Symbiont agents.*

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

symbiont

Directory Structure

SKILL.md

Report

Notice