vocion-core

Vocion (@vocion/core) is an open framework for running AI agent work in production rather than only prototyping it. The README frames the intended user as an engineer or tech lead moving a team of agents into production, and explicitly notes when the project is not a good fit: a single chatbot, a one-off script, or a hosted no-code builder. It assumes you run Postgres, keep configuration in git, and want a human in the loop on actions that matter. The core package is not published to npm; you clone the repository and run it yourself. What the platform combines Vocion is described as a Next.js app plus Postgres schema plus MCP server plus workflow runner. You author Sources, Objects, Skills, Playbooks, Workflows, Missions, Automations, Agents and Teams as YAML and markdown in git, apply them to the database, and get a typed runtime with a unified human-review queue, observability and a plugin ecosystem. Three work modes share one runtime: - Workflows: deterministic steps with approve and ask gates. - Missions: open-ended standing responsibilities, where a team of agents plans, works and produces artifacts under review. - Teams: multiple agents grouped under a lead with an accountable human. Other stated capabilities include a built-in connector pack for Google Ads, GA4, HubSpot, Gmail, Slack and Google Drive on an incremental, client-scoped ingestion pipeline; a multi-tenant control plane with tenant Bearer tokens that resolve to a permission principal; a write API exposing the review queue over REST (review listing and decide endpoints); and MCP over HTTP as the agent and tool plane. Discovery and mutation permissions are separated, an autonomy ladder with approval gates governs execution, and cross-client isolation is enforced at the query level rather than through prompts. Agent execution is configurable through a single setting, harness.runsOn. Documented options are running the agent loop inside the app process, in the project's own container on AWS Bedrock AgentCore Runtime, or handed to AWS's managed harness, with the documentation explaining which AWS account pays for tokens in each case. Layered packages and plugin contract The repository is the core layer of a larger platform. The SDK package defines the stable plugin contract, including Skill and PluginManifest types and LLM client types. Connectors and skills ship as separate plugin npm packages, and a forkable starter install is described as planned in a separate repository. A plugin is an npm package exporting a manifest; core loads manifests at boot via the SDK. The README shows a sample skill definition built with a schema validation library, declaring slug, name, version, provider, an approval requirement, input and output schemas, and a run function, exported as a PluginManifest. A reference transcript-highlights plugin lives in the packages/plugins directory. Workspace as code All tenant context lives in a workspace: a git-tracked directory of YAML and markdown sitting outside the repository checkout, typically its own repo, so client context is reviewable in pull requests and never mixed into core. An environment variable points the app at it; without it no workspace is configured. Documented entity types and their locations include the workspace manifest, agents (a YAML file plus a system-prompt markdown file), teams, skills, playbooks, missions, workflow runs created by the API, workflows, automations as the only place time and events live, object types with source weights and a classification prompt, sources with connector kind and sync cadence, trust rules for which actions may auto-execute, learning steps as named buckets of accumulated rules, eval datasets for per-agent test cases, and tenant-defined dashboard pages. A base pack ships inside core and layers underneath a workspace: you pin it with an extends directive, activate agents with a use list, and override defaults with same-slug files. Applying a workspace to the database records an audit row with a workspace version, and tool calls stamp a workspace hash so outputs trace back to the prompts that produced them. Setup and operations Getting started is documented as clone and install, copy the environment example file and set a database URL, an auth secret and at least one LLM provider key, start the supporting services with a dev:up script (Postgres, Langfuse, Temporal), run migrations, scaffold a workspace, point WORKSPACE_PATH at it, apply it, then start the dev server on localhost port 3000. Project scripts also cover linting, type checking, tests, workspace apply and evaluation runs. For MCP clients such as Claude Code, Cursor or Zed, there is a local stdio command for a single developer install, plus a remote HTTP endpoint where the organisation is derived from a tenant Bearer token and every tool call is scoped to that organisation under the same permission model as a human. Credentials are handled in both directions and managed from a dashboard page. Inbound tokens are minted by Vocion, stored only as a SHA-256 hash, and shown in plaintext once. Outbound vendor keys can be supplied per workspace, encrypted at rest with AES-256-GCM under a per-organisation data encryption key, so the workspace's own vendor account is billed; one live key per platform per organisation. Every outbound vendor call resolves the workspace's stored key first and the server environment variable second, covering chat models, embeddings on ingest and query, reranking, vision and image generation, with two internal paths staying on the server key by design. Encryption configuration offers a local vault mode intended for development and a KMS mode recommended for installs holding real customer keys. Retrieval is first-party: pgvector with HNSW cosine plus Postgres full-text search, fused with reciprocal rank fusion across the two arms, with an optional LLM rerank. Embedding and rerank models are environment-level settings, while per-type and per-agent retrieval weighting is authored in the workspace without code changes. Stack and integrations The stated stack is Next.js 16 with the App Router, React 19 and strict TypeScript, PostgreSQL 16 with an ORM, Auth.js / NextAuth v5 for first-party tenancy with role-based access through account and project membership, OpenAI and Anthropic as swappable LLM providers per skill, Langfuse for LLM traces and OpenTelemetry for spans and metrics, an in-process durable workflow step runner on Postgres, Slack chat surfaces where mentioning an agent produces a threaded reply while the review queue remains the only place anything is approved (behind a feature flag), and an external worker control plane for hours-long runs with leases, heartbeats, per-run cost and a reaper (also behind a feature flag). License The project is source-available under the Mozilla Public License 2.0, described as OSI-approved and file-level copyleft: you may use, self-host, inspect, modify and embed it in a larger proprietary system, and modified Vocion files stay open under the MPL when distributed while surrounding application code remains yours. The README states that data, business context, agent configurations, workflows, evaluation history and operational outputs remain yours, and that the project is deployable in your own environment. Certain uses, such as white-labelling Vocion itself, distributing it under a proprietary license, a vendor-supported managed service, proprietary enterprise modules, or commercial warranties and service levels, require a separate agreement. The name and logos are trademarks of Metacto, Inc., and the MPL does not grant trademark rights. Documentation pointers The README links a getting-started guide that goes from an empty directory to a working agent workforce without code, a file written for coding agents working in the repository, a machine-readable documentation index, a workspace authoring guide, per-entity field references, an object model page describing where every object is authored, stored, executed and shown, a dashboard pages guide, and deployment documentation covering multiple environments and a parent-project pattern. Contributing guidance covers conventional commits enforced by tooling, DCO sign-off, and running type checks, tests and lint before committing.