From eafa8abc5547a761afb6fbdfb2c86f0abe181fbd Mon Sep 17 00:00:00 2001 From: Jascha Wanger Date: Thu, 23 Apr 2026 12:36:22 -0700 Subject: [PATCH] docs: add per-package READMEs for all symbi-* workspace packages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit npm shows a "No README found" placeholder on each of the 9 published `symbi-*` package pages because the workspace packages have no package-local README.md — only the monorepo root does. Add one focused README per package under packages//README.md: - symbi-types — types + Zod schemas; install notes; "usually re-exported from symbi-core, pull in explicitly for types-only" - symbi-core — main client; quick start; what's exported; companion packages table; links to the SDK README and runtime docs - symbi-agent — AgentClient / ScheduleClient / ChannelClient / WorkflowClient / AgentPinClient; basic example - symbi-policy — PolicyBuilder; allow/deny/audit example - symbi-secrets — SecretManager with Vault / file / env providers - symbi-mcp — McpClient; servers / tools / resources; notes tool calls flow through SchemaPin + Cedar - symbi-tool-review — ToolReviewClient; submit / track / decide - symbi-testing — MockFetch / MockAuthManager / MockSecretManager / TestEnvironment; example with mockResponse + expectCalled - symbi-cli — install via npm i -g; env config; agent/auth/dev commands; distinguishes from the Rust `symbi` runtime binary All follow the Symbiont main-repo voice: short, direct, horizontal rules between sections, no emoji-heavy headers, "official SDK for Symbiont, the policy-governed agent runtime" framing, and pointers to the main SDK README for Trust Stack integration and full examples. npm auto-includes README.md in published tarballs (verified via `npm pack --dry-run` on symbi-types — README.md appears in the tarball contents despite `files: ["dist"]`). --- packages/agent/README.md | 53 ++++++++++++++++++++++++ packages/cli/README.md | 72 ++++++++++++++++++++++++++++++++ packages/core/README.md | 75 ++++++++++++++++++++++++++++++++++ packages/mcp/README.md | 41 +++++++++++++++++++ packages/policy/README.md | 41 +++++++++++++++++++ packages/secrets/README.md | 57 ++++++++++++++++++++++++++ packages/testing/README.md | 60 +++++++++++++++++++++++++++ packages/tool-review/README.md | 58 ++++++++++++++++++++++++++ packages/types/README.md | 45 ++++++++++++++++++++ 9 files changed, 502 insertions(+) create mode 100644 packages/agent/README.md create mode 100644 packages/cli/README.md create mode 100644 packages/core/README.md create mode 100644 packages/mcp/README.md create mode 100644 packages/policy/README.md create mode 100644 packages/secrets/README.md create mode 100644 packages/testing/README.md create mode 100644 packages/tool-review/README.md create mode 100644 packages/types/README.md diff --git a/packages/agent/README.md b/packages/agent/README.md new file mode 100644 index 0000000..b7b072d --- /dev/null +++ b/packages/agent/README.md @@ -0,0 +1,53 @@ +# symbi-agent + +[![npm](https://img.shields.io/npm/v/symbi-agent.svg)](https://www.npmjs.com/package/symbi-agent) +[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](../../LICENSE) + +Agent, schedule, channel, workflow, and AgentPin clients for the [Symbiont JavaScript/TypeScript SDK](https://github.com/ThirdKeyAI/symbiont-sdk-js). + +Most users don't install this directly — the unified `SymbiontClient` in [`symbi-core`](https://www.npmjs.com/package/symbi-core) already exposes these as `client.agents`, `client.schedules`, `client.channels`, `client.workflows`, and `client.agentpin`. Pull `symbi-agent` in explicitly when you want a narrow dependency or you're composing your own client. + +## Install + +```bash +npm install symbi-agent +``` + +## Usage + +```typescript +import { AgentClient, ScheduleClient, ChannelClient, AgentPinClient } from 'symbi-agent'; + +// Given an authenticated Symbiont HTTP transport (see symbi-core for the full client): +const agents = new AgentClient(transport); +const agent = await agents.createAgent({ + name: 'textProcessor', + description: 'Processes text input', + parameters: [{ name: 'text', type: { name: 'string' }, required: true }], + returnType: { name: 'string' }, + capabilities: ['text_processing'], +}); + +const result = await agents.executeAgent(agent.id, { text: 'Hello, Symbiont!' }); +console.log(result.result); +``` + +## Exports + +| Client | Purpose | +|--------|---------| +| `AgentClient` | Agent lifecycle: create, update, execute, re-execute, delete, list, status, history, heartbeat, push events | +| `ScheduleClient` | Cron schedules with pause/resume/trigger and run history | +| `ChannelClient` | Slack / Teams / Mattermost channel adapters, user mappings, audit | +| `WorkflowClient` | Multi-agent workflow execution | +| `AgentPinClient` | Client-side AgentPin — keygen, credential issuance, 12-step verification, discovery, key pinning, trust bundles (no runtime required) | + +## See also + +- [`symbi-core`](https://www.npmjs.com/package/symbi-core) — main client exposing all of these as sub-clients +- [SDK README](https://github.com/ThirdKeyAI/symbiont-sdk-js#readme) — full examples including AgentPin and reasoning loop +- [docs.symbiont.dev](https://docs.symbiont.dev) — runtime documentation + +## License + +Apache 2.0. See [LICENSE](../../LICENSE). diff --git a/packages/cli/README.md b/packages/cli/README.md new file mode 100644 index 0000000..240476e --- /dev/null +++ b/packages/cli/README.md @@ -0,0 +1,72 @@ +# symbi-cli + +[![npm](https://img.shields.io/npm/v/symbi-cli.svg)](https://www.npmjs.com/package/symbi-cli) +[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](../../LICENSE) + +Command-line tooling for the [Symbiont JavaScript/TypeScript SDK](https://github.com/ThirdKeyAI/symbiont-sdk-js). Drive the Symbiont runtime from your shell — manage agents, run development helpers, handle auth. + +> Distinct from [`symbi`](https://crates.io/crates/symbi), the Rust-native runtime binary. `symbi-cli` is a thin Node-based helper that speaks to the runtime over its HTTP API; `symbi` is the runtime itself. + +## Install + +```bash +npm install -g symbi-cli +``` + +Or use `npx`: + +```bash +npx symbi-cli agent list +``` + +## Configuration + +```bash +export SYMBIONT_API_KEY=... +export SYMBIONT_API_URL=http://localhost:8080/api/v1 +``` + +Or create `~/.symbiont/config.json`: + +```json +{ + "apiKey": "...", + "apiUrl": "http://localhost:8080/api/v1" +} +``` + +## Examples + +```bash +# Authenticate and verify the runtime is reachable +symbi-cli auth login +symbi-cli auth whoami + +# Agent lifecycle +symbi-cli agent list +symbi-cli agent create --file ./my-agent.json +symbi-cli agent exec --input '{"text":"hello"}' + +# Development helpers +symbi-cli dev watch ./agents/ +``` + +## Programmatic use + +```typescript +import { program } from 'symbi-cli'; +program.parse(['agent', 'list']); +``` + +Utilities from `symbi-cli/utils/*` — config loading, error handling, output formatting — are re-exportable for downstream tools. + +## See also + +- [`symbi`](https://crates.io/crates/symbi) — the Rust-native Symbiont runtime binary +- [`symbi-core`](https://www.npmjs.com/package/symbi-core) — the programmatic client `symbi-cli` wraps +- [SDK README](https://github.com/ThirdKeyAI/symbiont-sdk-js#readme) +- [docs.symbiont.dev/getting-started](https://docs.symbiont.dev/getting-started) — full installation options + +## License + +Apache 2.0. See [LICENSE](../../LICENSE). diff --git a/packages/core/README.md b/packages/core/README.md new file mode 100644 index 0000000..8dff7fb --- /dev/null +++ b/packages/core/README.md @@ -0,0 +1,75 @@ +# symbi-core + +[![npm](https://img.shields.io/npm/v/symbi-core.svg)](https://www.npmjs.com/package/symbi-core) +[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](../../LICENSE) + +Main client for the [Symbiont JavaScript/TypeScript SDK](https://github.com/ThirdKeyAI/symbiont-sdk-js) — the official client for Symbiont, the policy-governed agent runtime. + +`symbi-core` exposes `SymbiontClient` plus standalone modules (webhook verification, markdown memory, skill scanning, metrics). Types are re-exported from [`symbi-types`](https://www.npmjs.com/package/symbi-types), so most projects only need this one install. + +## Install + +```bash +npm install symbi-core +``` + +A running Symbiont runtime is required for client calls. The fastest way: + +```bash +docker run --rm -p 8080:8080 -p 8081:8081 ghcr.io/thirdkeyai/symbi:latest up +``` + +## Quick start + +```typescript +import { SymbiontClient } from 'symbi-core'; + +const client = new SymbiontClient({ + apiKey: process.env.SYMBIONT_API_KEY, + apiUrl: 'http://localhost:8080/api/v1', +}); + +await client.connect(); + +const agents = await client.agents.listAgents(); +const result = await client.agents.executeAgent(agents[0].id, { text: 'Hello, Symbiont!' }); +console.log(result.result); +``` + +## What's exported + +| Export | Purpose | +|--------|---------| +| `SymbiontClient` | Unified client with namespaced sub-clients for every runtime surface (see SDK README) | +| `AuthenticationManager`, `MemoryTokenCache` | Auth / token refresh | +| `HmacVerifier`, `JwtVerifier`, `createProviderVerifier` | Inbound webhook signature verification (GitHub, Stripe, Slack, custom) | +| `MarkdownMemoryStore` | File-based agent context that survives restarts | +| `SkillScanner`, `SkillLoader` | ClawHavoc security scanning (10 built-in rules) + YAML frontmatter loading | +| `MetricsApiClient`, `FileMetricsExporter`, `CompositeExporter`, `MetricsCollector` | Runtime metrics snapshots + periodic export | +| `SystemClient`, `CommunicationClient`, `ToolCladClient`, `ReasoningClient` | Runtime sub-clients | +| `HttpEndpointManager` | Dynamic HTTP endpoint management | + +All types and Zod schemas from `symbi-types` are re-exported for convenience. + +## Companion packages + +| Package | Purpose | +|---------|---------| +| [`symbi-types`](https://www.npmjs.com/package/symbi-types) | Types + Zod schemas | +| [`symbi-agent`](https://www.npmjs.com/package/symbi-agent) | `AgentClient`, `ScheduleClient`, `ChannelClient`, `WorkflowClient`, `AgentPinClient` | +| [`symbi-policy`](https://www.npmjs.com/package/symbi-policy) | Policy builder | +| [`symbi-secrets`](https://www.npmjs.com/package/symbi-secrets) | Vault / file / env secret backends | +| [`symbi-mcp`](https://www.npmjs.com/package/symbi-mcp) | MCP client | +| [`symbi-tool-review`](https://www.npmjs.com/package/symbi-tool-review) | Tool review workflow | +| [`symbi-testing`](https://www.npmjs.com/package/symbi-testing) | Mocks + test helpers | +| [`symbi-cli`](https://www.npmjs.com/package/symbi-cli) | Command-line tooling | + +## See also + +- [SDK README](https://github.com/ThirdKeyAI/symbiont-sdk-js#readme) — full capabilities, examples, Trust Stack integration +- [docs.symbiont.dev](https://docs.symbiont.dev) — runtime documentation +- [Symbiont runtime](https://github.com/thirdkeyai/symbiont) — the Rust-native runtime this SDK talks to + +## License + +Apache 2.0. See [LICENSE](../../LICENSE). diff --git a/packages/mcp/README.md b/packages/mcp/README.md new file mode 100644 index 0000000..c14242e --- /dev/null +++ b/packages/mcp/README.md @@ -0,0 +1,41 @@ +# symbi-mcp + +[![npm](https://img.shields.io/npm/v/symbi-mcp.svg)](https://www.npmjs.com/package/symbi-mcp) +[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](../../LICENSE) + +MCP (Model Context Protocol) client for the [Symbiont JavaScript/TypeScript SDK](https://github.com/ThirdKeyAI/symbiont-sdk-js). Drives the Symbiont runtime's governed MCP integration — listing connected servers, invoking tools, and surfacing resources under runtime policy. + +Most users install [`symbi-core`](https://www.npmjs.com/package/symbi-core), which exposes this as `client.mcp`. Pull `symbi-mcp` directly when you want a narrow dependency. + +## Install + +```bash +npm install symbi-mcp +``` + +## Usage + +```typescript +import { McpClient } from 'symbi-mcp'; + +const mcp = new McpClient(transport); + +const servers = await mcp.listServers(); +const tools = await mcp.listTools(servers[0].id); +const resources = await mcp.listResources(servers[0].id); + +const result = await mcp.invokeTool(servers[0].id, 'search', { query: 'symbiont' }); +``` + +Tool calls flow through the runtime's SchemaPin verification and Cedar policy gates — unverified or denied tools never execute. + +## See also + +- [`symbi-core`](https://www.npmjs.com/package/symbi-core) — exposes `client.mcp` +- [SDK README](https://github.com/ThirdKeyAI/symbiont-sdk-js#readme) +- [docs.symbiont.dev](https://docs.symbiont.dev) — runtime documentation +- [SchemaPin](https://github.com/ThirdKeyAI/SchemaPin) — the tool-signature verification layer + +## License + +Apache 2.0. See [LICENSE](../../LICENSE). diff --git a/packages/policy/README.md b/packages/policy/README.md new file mode 100644 index 0000000..6957ab6 --- /dev/null +++ b/packages/policy/README.md @@ -0,0 +1,41 @@ +# symbi-policy + +[![npm](https://img.shields.io/npm/v/symbi-policy.svg)](https://www.npmjs.com/package/symbi-policy) +[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](../../LICENSE) + +Policy builder for the [Symbiont JavaScript/TypeScript SDK](https://github.com/ThirdKeyAI/symbiont-sdk-js). Constructs `Policy` objects that the Symbiont runtime evaluates via its built-in DSL and [Cedar](https://www.cedarpolicy.com/) authorization. + +Most users install [`symbi-core`](https://www.npmjs.com/package/symbi-core), which exposes a `policyBuilder` namespace on `SymbiontClient`. Pull this package directly when you want a narrow dependency for agents/services that only need to construct policies. + +## Install + +```bash +npm install symbi-policy +``` + +## Usage + +```typescript +import { PolicyBuilder, createPolicyBuilder } from 'symbi-policy'; + +const policy = createPolicyBuilder() + .allow({ action: 'read', resource: 'documents' }) + .deny({ action: 'write', resource: '*' }) + .audit({ action: '*', resource: '*' }) + .build(); + +// Attach to an agent definition or register with the runtime: +// await client.agents.createAgent({ name, description, policies: [policy], ... }); +``` + +Fluent API supports `allow` / `deny` / `audit` effects, conditions (`when`, `unless`, timeboxed rules), priorities, and action/resource globbing. + +## See also + +- [`symbi-core`](https://www.npmjs.com/package/symbi-core) — exposes `client.policyBuilder` +- [SDK README](https://github.com/ThirdKeyAI/symbiont-sdk-js#readme) +- [docs.symbiont.dev/security-model](https://docs.symbiont.dev/security-model) — how Cedar policies flow through the runtime + +## License + +Apache 2.0. See [LICENSE](../../LICENSE). diff --git a/packages/secrets/README.md b/packages/secrets/README.md new file mode 100644 index 0000000..a5d1651 --- /dev/null +++ b/packages/secrets/README.md @@ -0,0 +1,57 @@ +# symbi-secrets + +[![npm](https://img.shields.io/npm/v/symbi-secrets.svg)](https://www.npmjs.com/package/symbi-secrets) +[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](../../LICENSE) + +Secret management for the [Symbiont JavaScript/TypeScript SDK](https://github.com/ThirdKeyAI/symbiont-sdk-js). Provides a pluggable `SecretManager` with HashiCorp Vault, encrypted-file, and environment-variable backends. + +Most users install [`symbi-core`](https://www.npmjs.com/package/symbi-core), which exposes secrets via `client.secrets`. Pull this package directly when you want a narrow dependency for services that only need secret resolution. + +## Install + +```bash +npm install symbi-secrets +``` + +## Usage + +```typescript +import { + SecretManager, + EnvironmentVariableProvider, + FileProvider, + VaultProvider, +} from 'symbi-secrets'; + +const manager = new SecretManager({ + providers: [ + new EnvironmentVariableProvider({ prefix: 'SYMBIONT_' }), + new FileProvider({ path: '/run/secrets/symbiont.json' }), + new VaultProvider({ endpoint: 'https://vault.internal', token: process.env.VAULT_TOKEN }), + ], +}); + +const apiKey = await manager.get('api-key'); +``` + +The manager tries providers in order. Use it for database credentials, API keys, and signing keys that shouldn't live in config. + +## Providers + +| Provider | Backend | +|----------|---------| +| `EnvironmentVariableProvider` | `process.env` with optional prefix and mapping | +| `FileProvider` | JSON / YAML / flat key-value files with optional AES-256-GCM encryption | +| `VaultProvider` | HashiCorp Vault (Token, Kubernetes, AWS IAM, AppRole auth methods) | + +Implement the `SecretProvider` interface to add more. + +## See also + +- [`symbi-core`](https://www.npmjs.com/package/symbi-core) — exposes `client.secrets` +- [SDK README](https://github.com/ThirdKeyAI/symbiont-sdk-js#readme) +- [docs.symbiont.dev/security-model](https://docs.symbiont.dev/security-model) + +## License + +Apache 2.0. See [LICENSE](../../LICENSE). diff --git a/packages/testing/README.md b/packages/testing/README.md new file mode 100644 index 0000000..5099f4e --- /dev/null +++ b/packages/testing/README.md @@ -0,0 +1,60 @@ +# symbi-testing + +[![npm](https://img.shields.io/npm/v/symbi-testing.svg)](https://www.npmjs.com/package/symbi-testing) +[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](../../LICENSE) + +Mocks and test helpers for applications built on the [Symbiont JavaScript/TypeScript SDK](https://github.com/ThirdKeyAI/symbiont-sdk-js). Lets you test code that talks to Symbiont without standing up the runtime. + +## Install + +```bash +npm install --save-dev symbi-testing +``` + +## Usage + +```typescript +import { + MockFetch, + MockAuthManager, + MockSecretManager, + TestEnvironment, +} from 'symbi-testing'; + +// Full test harness with mocked auth, secrets, and HTTP +const env = new TestEnvironment({ + apiKey: 'test-key', + baseUrl: 'http://mock.symbiont', +}); + +env.fetch.mockResponse('/api/v1/agents', { + status: 200, + body: [{ id: 'agent-1', name: 'Test Agent' }], +}); + +const client = env.createClient(); +const agents = await client.agents.listAgents(); +expect(agents[0].id).toBe('agent-1'); + +env.fetch.expectCalled('/api/v1/agents', { method: 'GET' }); +``` + +## Exports + +| Export | Purpose | +|--------|---------| +| `MockFetch` | Programmable response matcher for HTTP calls | +| `MockAuthManager` | Bypasses real auth; returns pre-seeded tokens | +| `MockSecretManager` | In-memory secret store for tests | +| `TestEnvironment` | Wraps the three above plus a pre-wired `SymbiontClient` | +| `mockData` | Realistic fixtures for agents, executions, policies, schedules | +| `testHelpers` | Assertion + retry + waiting utilities | + +## See also + +- [`symbi-core`](https://www.npmjs.com/package/symbi-core) — main client +- [SDK README](https://github.com/ThirdKeyAI/symbiont-sdk-js#readme) + +## License + +Apache 2.0. See [LICENSE](../../LICENSE). diff --git a/packages/tool-review/README.md b/packages/tool-review/README.md new file mode 100644 index 0000000..8e39fce --- /dev/null +++ b/packages/tool-review/README.md @@ -0,0 +1,58 @@ +# symbi-tool-review + +[![npm](https://img.shields.io/npm/v/symbi-tool-review.svg)](https://www.npmjs.com/package/symbi-tool-review) +[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](../../LICENSE) + +Tool-review workflow client for the [Symbiont JavaScript/TypeScript SDK](https://github.com/ThirdKeyAI/symbiont-sdk-js). Submit tools for security analysis, track review sessions, and act on reviewer decisions before a tool is allowed to execute under the Symbiont runtime. + +Most users install [`symbi-core`](https://www.npmjs.com/package/symbi-core), which exposes this as `client.toolReview`. Pull `symbi-tool-review` directly when you want a narrow dependency for a dashboard or review UI. + +## Install + +```bash +npm install symbi-tool-review +``` + +## Usage + +```typescript +import { ToolReviewClient } from 'symbi-tool-review'; + +const review = new ToolReviewClient(transport); + +// Submit a tool for review +const submission = await review.submitTool({ + name: 'nmap-scan', + manifestPath: '/tools/nmap.clad.toml', + requester: 'team-security', +}); + +// Poll the session +const session = await review.getSession(submission.sessionId); +console.log(session.state, session.analysis?.findings); + +// Record a human reviewer decision +await review.recordDecision(session.id, { + decision: 'approved', + reviewer: 'alice@example.com', + notes: 'Read-only; no external network writes.', +}); +``` + +## Exports + +| Export | Purpose | +|--------|---------| +| `ToolReviewClient` | Submit / get / list review sessions, record decisions, retrieve security analysis results | + +Types re-exported from [`symbi-types`](https://www.npmjs.com/package/symbi-types): `ToolSubmission`, `ReviewSession`, `SecurityAnalysis`, `ReviewDecision`, and related enums. + +## See also + +- [`symbi-core`](https://www.npmjs.com/package/symbi-core) — exposes `client.toolReview` +- [SDK README](https://github.com/ThirdKeyAI/symbiont-sdk-js#readme) +- [docs.symbiont.dev/security-model](https://docs.symbiont.dev/security-model) — where tool review fits in the Trust Stack + +## License + +Apache 2.0. See [LICENSE](../../LICENSE). diff --git a/packages/types/README.md b/packages/types/README.md new file mode 100644 index 0000000..e771926 --- /dev/null +++ b/packages/types/README.md @@ -0,0 +1,45 @@ +# symbi-types + +[![npm](https://img.shields.io/npm/v/symbi-types.svg)](https://www.npmjs.com/package/symbi-types) +[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](../../LICENSE) + +Shared TypeScript interfaces and [Zod](https://zod.dev) schemas for the Symbiont SDK. Part of the [Symbiont JavaScript/TypeScript SDK](https://github.com/ThirdKeyAI/symbiont-sdk-js) — the official client for Symbiont, the policy-governed agent runtime. + +Most users don't install this directly — it's re-exported from [`symbi-core`](https://www.npmjs.com/package/symbi-core). Pull it in explicitly when you want types (and Zod schemas) without any runtime code. + +## Install + +```bash +npm install symbi-types +``` + +## Usage + +```typescript +import type { + Agent, + ExecutionResult, + ToolManifestInfo, + CommunicationRule, + WebhookInvocationResponse, +} from 'symbi-types'; + +// Zod schemas are available for every type: +import { WebhookInvocationResponseSchema } from 'symbi-types'; + +const parsed = WebhookInvocationResponseSchema.parse(await response.json()); +``` + +## Scope + +Types and schemas cover every runtime surface the SDK speaks to: agents, schedules, channels, workflows, reasoning-loop (ORGA, Cedar, journal, circuit breakers, knowledge bridge), ToolClad manifests, Communication Policy Gate, AgentPin credentials, secrets, MCP, HTTP endpoints, webhooks (verification + v1.10.0 HTTP Input invocation responses), skills, memory, metrics. + +## See also + +- [`symbi-core`](https://www.npmjs.com/package/symbi-core) — main client +- [SDK README](https://github.com/ThirdKeyAI/symbiont-sdk-js#readme) — full capabilities, examples, Trust Stack integration +- [docs.symbiont.dev](https://docs.symbiont.dev) — runtime documentation + +## License + +Apache 2.0. See [LICENSE](../../LICENSE).