{"id":32009935,"url":"https://github.com/thirdkeyai/symbiont-sdk-js","last_synced_at":"2026-02-28T10:07:47.829Z","repository":{"id":308056820,"uuid":"1023918341","full_name":"ThirdKeyAI/symbiont-sdk-js","owner":"ThirdKeyAI","description":"Javascript SDK for Symbiont","archived":false,"fork":false,"pushed_at":"2026-02-16T23:06:58.000Z","size":497,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-17T05:37:37.937Z","etag":null,"topics":["agents","ai","autonomous-agents","cybersecurity","javascript","mcp","sandbox","sdk","sdk-js","symbi","symbiont","typescript"],"latest_commit_sha":null,"homepage":"https://symbiont.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ThirdKeyAI.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-21T22:58:26.000Z","updated_at":"2026-02-16T22:56:25.000Z","dependencies_parsed_at":"2025-08-03T22:26:25.614Z","dependency_job_id":"f5d17931-0a23-45eb-803d-bbc62d60f9d9","html_url":"https://github.com/ThirdKeyAI/symbiont-sdk-js","commit_stats":null,"previous_names":["thirdkeyai/symbiont-sdk-js"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/ThirdKeyAI/symbiont-sdk-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThirdKeyAI%2Fsymbiont-sdk-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThirdKeyAI%2Fsymbiont-sdk-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThirdKeyAI%2Fsymbiont-sdk-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThirdKeyAI%2Fsymbiont-sdk-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ThirdKeyAI","download_url":"https://codeload.github.com/ThirdKeyAI/symbiont-sdk-js/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ThirdKeyAI%2Fsymbiont-sdk-js/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29929740,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-28T09:58:13.507Z","status":"ssl_error","status_checked_at":"2026-02-28T09:57:57.047Z","response_time":90,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai","autonomous-agents","cybersecurity","javascript","mcp","sandbox","sdk","sdk-js","symbi","symbiont","typescript"],"created_at":"2025-10-15T20:26:31.950Z","updated_at":"2026-02-28T10:07:47.817Z","avatar_url":"https://github.com/ThirdKeyAI.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Symbiont JavaScript/TypeScript SDK\n\n[![npm version](https://badge.fury.io/js/%40symbiont%2Fcore.svg)](https://badge.fury.io/js/%40symbiont%2Fcore)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA comprehensive, type-safe JavaScript/TypeScript SDK for building and managing AI agents on the Symbiont platform. Get started quickly with full TypeScript support, intelligent caching, and enterprise-grade security.\n\n## 🚀 Quick Start\n\n### Prerequisites\n\nThe Symbiont SDK requires a running Symbiont runtime. Choose one of these options:\n\n#### Option 1: Docker (Recommended)\n```bash\n# Start Symbiont runtime with Docker\ndocker run --rm -p 8080:8080 ghcr.io/thirdkeyai/symbi:latest mcp\n```\n\n#### Option 2: Build from Source\n```bash\n# Clone and build the runtime\ngit clone https://github.com/thirdkeyai/symbiont\ncd symbiont\ncargo build --release\ncargo run -- mcp --port 8080\n```\n\n### Installation\n\n```bash\nnpm install @symbi/core\n```\n\n### Hello World\n\n```typescript\nimport { SymbiontClient } from '@symbi/core';\n\nconst client = new SymbiontClient({\n  apiKey: process.env.SYMBIONT_API_KEY,\n  environment: 'production'\n});\n\nawait client.connect();\n\n// Create and execute your first agent\nconst agent = await client.agents.createAgent({\n  name: 'textProcessor',\n  description: 'Processes and analyzes text input',\n  parameters: [{ name: 'text', type: { name: 'string' }, required: true }],\n  returnType: { name: 'string' },\n  capabilities: ['text_processing']\n});\n\nconst result = await client.agents.executeAgent(\n  agent.id,\n  { text: 'Hello, Symbiont!' }\n);\n\nconsole.log('Result:', result.result);\n```\n\n## ✨ Core Features\n\n- **🤖 AI Agent Management** - Create, deploy, and execute intelligent agents\n- **🔐 Security-First** - Built-in policy management and secrets handling\n- **🔑 AgentPin Integration** - Client-side credential verification, discovery, and trust bundles\n- **🛡️ Type Safety** - Full TypeScript support with runtime validation\n- **⚡ High Performance** - Intelligent caching and optimized networking\n- **🔄 Auto-Authentication** - Seamless token management and refresh\n- **📦 Modular Design** - Use only what you need\n- **🌍 Cross-Platform** - Node.js, browser, and edge runtime support\n\n## 📚 Documentation\n\n### 🎯 **[Getting Started](./apps/docs/guides/getting-started.md)**\nComplete installation guide, configuration options, and your first agent\n\n### 📖 **User Guides**\n- **[Agent Management](./apps/docs/guides/agent-management.md)** - Creating, managing, and executing agents\n- **[Tool Review Workflow](./apps/docs/guides/tool-review-workflow.md)** - Security review process for tools and agents\n- **[Policy Creation](./apps/docs/guides/policy-creation.md)** - Building access control and governance policies\n- **[Secrets Management](./apps/docs/guides/secrets-management.md)** - Secure credential and configuration management\n\n### 🔍 **[API Reference](./apps/docs/api/index.html)**\nComplete API documentation with examples and type definitions\n\n### 🏗️ **Architecture**\n- **[Architecture Overview](./ARCHITECTURE.md)** - Technical design and system architecture\n- **[Implementation Guide](./IMPLEMENTATION_GUIDE.md)** - Development roadmap and implementation details\n\n## 📦 SDK Packages\n\n| Package | Purpose | Installation |\n|---------|---------|--------------|\n| **[@symbi/core](./packages/core)** | Main client and authentication | `npm install @symbi/core` |\n| **[@symbi/agent](./packages/agent)** | Agent lifecycle management | `npm install @symbi/agent` |\n| **[@symbi/policy](./packages/policy)** | Policy creation and validation | `npm install @symbi/policy` |\n| **[@symbi/secrets](./packages/secrets)** | Secure secrets management | `npm install @symbi/secrets` |\n| **[@symbi/tool-review](./packages/tool-review)** | Security review workflow | `npm install @symbi/tool-review` |\n| **[@symbi/mcp](./packages/mcp)** | MCP protocol integration | `npm install @symbi/mcp` |\n\n## 🔑 AgentPin: Credential Verification\n\nThe SDK integrates with [AgentPin](https://github.com/ThirdKeyAI/agentpin) for domain-anchored cryptographic identity verification of AI agents. AgentPin operations run client-side — no Symbiont Runtime required.\n\n### Key Generation \u0026 Credential Issuance\n\n```typescript\nconst { privateKeyPem, publicKeyPem } = client.agentpin.generateKeyPair();\nconst kid = client.agentpin.generateKeyId(publicKeyPem);\n\nconst jwt = client.agentpin.issueCredential({\n  privateKeyPem,\n  kid,\n  issuer: 'example.com',\n  agentId: 'data-analyzer',\n  capabilities: ['read:data', 'write:reports'],\n  ttlSecs: 3600,\n});\n```\n\n### Credential Verification\n\n```typescript\n// Online verification (fetches discovery document automatically)\nconst result = await client.agentpin.verifyCredential(jwt);\nconsole.log(result.valid, result.agent_id, result.capabilities);\n\n// Offline verification with pre-fetched documents\nconst discovery = await client.agentpin.fetchDiscoveryDocument('example.com');\nconst offlineResult = client.agentpin.verifyCredentialOffline(jwt, discovery);\n\n// Trust bundle verification (fully offline, no network)\nconst bundle = client.agentpin.createTrustBundle();\nconst bundleResult = client.agentpin.verifyCredentialWithBundle(jwt, bundle);\n```\n\n### Discovery \u0026 Key Pinning\n\n```typescript\n// Fetch and validate discovery documents\nconst doc = await client.agentpin.fetchDiscoveryDocument('example.com');\nclient.agentpin.validateDiscoveryDocument(doc, 'example.com');\n\n// TOFU key pinning\nconst pinStore = client.agentpin.createPinStore();\n\n// JWK utilities\nconst jwk = client.agentpin.pemToJwk(publicKeyPem, kid);\nconst pem = client.agentpin.jwkToPem(jwk);\n```\n\n## 🛠️ Configuration\n\n### Environment Variables\n```bash\n# Required\nSYMBIONT_API_KEY=your_api_key_here\n\n# Optional\nSYMBIONT_API_URL=https://api.symbiont.dev\nSYMBIONT_ENVIRONMENT=production\n```\n\n### Client Configuration\n```typescript\nconst client = new SymbiontClient({\n  apiKey: process.env.SYMBIONT_API_KEY,\n  environment: 'production',\n  validationMode: 'strict',\n  timeout: 30000,\n  debug: false\n});\n```\n\n## 🎯 Common Use Cases\n\n### Agent Creation and Execution\n```typescript\n// Create a data analysis agent\nconst agent = await client.agents.createAgent({\n  name: 'dataAnalyzer',\n  description: 'Analyzes datasets and generates insights',\n  parameters: [\n    { name: 'dataset', type: { name: 'object' }, required: true },\n    { name: 'analysisType', type: { name: 'string' }, required: false }\n  ],\n  capabilities: ['data_processing', 'visualization'],\n  policies: [dataAccessPolicy]\n});\n\nconst insights = await client.agents.executeAgent(agent.id, {\n  dataset: myData,\n  analysisType: 'trend_analysis'\n});\n```\n\n### Policy Management\n```typescript\nimport { PolicyBuilder } from '@symbi/policy';\n\n// Create access control policy\nconst policy = new PolicyBuilder('dataAccessPolicy')\n  .allow('read', 'analyze')\n    .where('user.department', 'equals', 'analytics')\n    .where('data.classification', 'not-equals', 'restricted')\n  .require('approval')\n    .where('action', 'equals', 'export')\n  .build();\n```\n\n### Secrets Management\n```typescript\nimport { SecretManager } from '@symbi/secrets';\n\nconst secrets = new SecretManager({\n  providers: [\n    { name: 'environment', priority: 100 },\n    { name: 'vault', priority: 200, endpoint: 'https://vault.company.com' }\n  ]\n});\n\nconst apiKey = await secrets.getSecret('EXTERNAL_API_KEY');\n```\n\n## Webhook Verification\n\nVerify inbound webhook signatures from GitHub, Stripe, Slack, or custom providers:\n\n```typescript\nimport {\n    HmacVerifier, JwtVerifier, createProviderVerifier,\n} from '@symbi/core';\n\n// Use a provider preset\nconst verifier = createProviderVerifier('GITHUB', Buffer.from(secret));\nverifier.verify(request.headers, Buffer.from(request.body));\n\n// Manual HMAC with prefix stripping\nconst hmac = new HmacVerifier(\n    Buffer.from(secret), 'X-Hub-Signature-256', 'sha256='\n);\nhmac.verify(headers, body);\n\n// JWT-based verification\nconst jwtVerifier = new JwtVerifier(\n    Buffer.from(secret), 'Authorization', 'expected-issuer'\n);\njwtVerifier.verify(headers, body);\n```\n\nProvider presets: `GITHUB`, `STRIPE`, `SLACK`, `CUSTOM`.\n\n## Markdown Memory Persistence\n\nFile-based agent context that survives restarts:\n\n```typescript\nimport { MarkdownMemoryStore } from '@symbi/core';\n\nconst store = new MarkdownMemoryStore('/data/memory', 30);\n\nawait store.saveContext('agent-1', {\n    agentId: 'agent-1',\n    facts: ['User prefers dark mode', 'Timezone is UTC-5'],\n    procedures: ['Always greet by name'],\n    learnedPatterns: ['Responds better to bullet points'],\n    metadata: { lastSession: '2026-02-15' },\n});\n\nconst context = await store.loadContext('agent-1');\nconst agents = await store.listAgentContexts();\nawait store.compact('agent-1');\nconst stats = await store.getStorageStats();\n```\n\n## Agent Skills (ClawHavoc Scanning)\n\nScan and load agent skill definitions with security scanning:\n\n```typescript\nimport { SkillScanner, SkillLoader } from '@symbi/core';\n\n// Scan for security issues (10 built-in ClawHavoc rules)\nconst scanner = new SkillScanner();\nconst findings = scanner.scanContent(content, 'SKILL.md');\n\n// Scan an entire skill directory\nconst result = scanner.scanSkill('/path/to/skill');\n\n// Load skills from paths\nconst loader = new SkillLoader({\n    loadPaths: ['/skills/verified', '/skills/community'],\n    requireSigned: false,\n    scanEnabled: true,\n});\n\nconst skills = loader.loadAll();\nconst skill = loader.loadSkill('/path/to/skill');\n```\n\nDetects: pipe-to-shell, wget-pipe-to-shell, env file references, SOUL.md/memory.md tampering, eval+fetch, base64-decode-exec, rm-rf, chmod-777.\n\n## Metrics Collection \u0026 Export\n\nRuntime metrics retrieval and local export:\n\n```typescript\nimport {\n    FileMetricsExporter, CompositeExporter, MetricsCollector,\n} from '@symbi/core';\n\n// Fetch from runtime API\nconst snapshot = await client.metricsClient.getSnapshot();\nconst scheduler = await client.metricsClient.getSchedulerMetrics();\nconst system = await client.metricsClient.getSystemMetrics();\n\n// Export to file (atomic JSON write)\nconst exporter = new FileMetricsExporter({ filePath: '/tmp/metrics.json' });\nawait exporter.export(snapshot);\n\n// Fan-out to multiple backends\nconst composite = new CompositeExporter([exporter, otherExporter]);\n\n// Background collection\nconst collector = new MetricsCollector(composite, 60000);\ncollector.start(fetchFn);\ncollector.stop();\n```\n\n## Scheduling\n\n```typescript\nconst schedule = await client.schedules.create({\n    agentId: 'my-agent',\n    cron: '0 */6 * * *',\n    parameters: { task: 'cleanup' },\n});\n\nconst schedules = await client.schedules.list();\nconst health = await client.schedules.getSchedulerHealth();\n```\n\n## Reasoning Loop (v1.6.0)\n\nRun autonomous reasoning loops with policy gates, circuit breakers, and knowledge recall:\n\n```typescript\nimport { SymbiontClient } from '@symbi/core';\n\nconst client = new SymbiontClient({ apiKey: process.env.SYMBIONT_API_KEY });\n\n// Run a reasoning loop\nconst response = await client.reasoning.runLoop('agent-1', {\n  config: { max_iterations: 10, timeout_ms: 60000 },\n  initial_message: 'Analyze the latest sales data and create a report.',\n});\n\nconsole.log('Output:', response.result.output);\nconsole.log('Iterations:', response.result.iterations);\nconsole.log('Termination:', response.result.termination_reason.type);\n\n// Check loop status\nconst status = await client.reasoning.getLoopStatus('agent-1', response.loop_id);\n\n// Read journal entries\nconst journal = await client.reasoning.getJournalEntries('agent-1', { limit: 50 });\n\n// Cedar policy management\nawait client.reasoning.addCedarPolicy('agent-1', {\n  name: 'deny-file-write',\n  source: 'forbid(principal, action == \"tool_call\", resource) when { resource.name == \"write_file\" };',\n  active: true,\n});\nconst policies = await client.reasoning.listCedarPolicies('agent-1');\n\n// Circuit breaker status\nconst breakers = await client.reasoning.getCircuitBreakerStatus('agent-1');\n\n// Knowledge bridge\nawait client.reasoning.storeKnowledge('agent-1', 'sales', 'grew_by', '15%');\nconst facts = await client.reasoning.recallKnowledge('agent-1', 'sales growth');\n```\n\n## What's New in v1.6.0\n\n- **Reasoning Loop** — `client.reasoning.runLoop()`, `getLoopStatus()`, `cancelLoop()` for autonomous ORGA cycles\n- **Journal System** — `getJournalEntries()`, `compactJournal()` for loop event replay and auditing\n- **Cedar Policies** — `listCedarPolicies()`, `addCedarPolicy()`, `evaluateCedarPolicy()` for action-level governance\n- **Circuit Breakers** — `getCircuitBreakerStatus()`, `resetCircuitBreaker()` for tool failure isolation\n- **Knowledge Bridge** — `recallKnowledge()`, `storeKnowledge()` for persistent agent memory\n- **Type Definitions** — Zod schemas for all reasoning types in `@symbi/types`\n\n### Previous Releases\n\n#### v0.6.0\n\n- **Webhook Verification** — `HmacVerifier`, `JwtVerifier`, provider presets (GitHub, Stripe, Slack)\n- **Markdown Memory** — `MarkdownMemoryStore` for file-based agent context persistence\n- **Agent Skills** — `SkillScanner` with 10 ClawHavoc rules, `SkillLoader` with frontmatter parsing\n- **Metrics** — `MetricsApiClient` sub-client, `FileMetricsExporter`, `CompositeExporter`, `MetricsCollector`\n- **Type Definitions** — Zod schemas for webhooks, skills, and metrics in `@symbi/types`\n\n## License\n\nMIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthirdkeyai%2Fsymbiont-sdk-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthirdkeyai%2Fsymbiont-sdk-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthirdkeyai%2Fsymbiont-sdk-js/lists"}