Packages, SDKs, and extensions

This page is synchronized from the canonical English documentation. 한국어 navigation is available; commands and product limits are identical in every locale.

Praetor is a pnpm monorepo. This page lists what each workspace package is for and how to consume it.

Runtime

@praetor/core

The agent runtime: agent loop, orchestration and topologies, memory, security, tools, plugins, LLM providers, and the CLI.

• Binary: commander
• Import: import { Praetor } from '@praetor/core'
• Subpath exports: ./runtime, ./saga, ./security, ./observability, and ./plugins/im/{dingtalk,feishu,wecom,slack,teams,discord}
• Contains 18 built-in tools and 25 LLM providers

Built-in tools: file, memory, web, browser, code, checkpoint, handoff, exec, media, system (the ten STRAP resource tools) plus git, verify, apply_patch, file_hash_edit, lsp, verify_answer, skill_view, search_conversations. Meta-tools are opt-in and not part of the 18.

@praetor/contracts

Versioned shared contracts: types, error codes, state machine, event envelope, JSON schemas, and the OpenAPI V1 spec. Pure — it must not import runtime code from core, kernel, providers, or tools.

@praetor/kernel

Sole authority for durable run and step lifecycle: PostgresKernelRepository, SqliteKernelRepository, migrations, outbox publisher, reclaim/timer workers, capability authority, and the evidence repository.

@praetor/effect-broker

Zero-trust broker for external writes. EffectBroker implements two-phase admit() → executeAdmitted(), verifying Ed25519 capability tokens, request-hash binding, policy decisions, quotas, worker fencing, and fail-closed durable replay/revocation stores. Also issues capability tokens and builds signed evidence bundles.

@praetor/worker-plane

The distributed worker plane and the only place a leased step executes. Provides PostgresWorkerRegistry / InMemoryWorkerRegistry, WorkerService, and pluggable step executors.

• Binary: commander-worker
• Requires PRAETOR_WORKER_BOOTSTRAP pointing at a module that exports createWorkerService(). There is no permissive dev fallback.

@praetor/adapter-ops

Compensation and reconciliation drain daemon, backed by the effect broker. Health server on port 8082.

@praetor/postgres-runtime

Hardened pg.Pool factory: requires sslmode=verify-full, loads a CA from PRAETOR_DATABASE_TLS_CA_FILE, and pins the server SPKI SHA-256.

@praetor/action-adapters

External-mutation adapters (GitHub pull request, ServiceNow incident, Kubernetes deployment rollback), an adapter registry, an environment credential provider, and a reusable conformance suite.

@praetor/shadow-plane

Read-only historical policy evaluation for Shadow pilots: signed policy manifests, NDJSON observation import, batch closure, hypothetical policy evaluation, and signed campaign report export/verification.

• Binary: commander-shadow
• Commands: manifest register, import, batch close, report export, report verify, campaign withdraw, retention run, status

SDKs

@praetor/sdk (TypeScript)

Two clients:

• CommanderGatewayClient — HTTP client for the /v1 Gateway API. No local runtime required. This is the current server path.
• CommanderClient — in-process client that dynamically imports @praetor/core (peer dependency). Alpha.

Also exports verifyActionEvidence() for Ed25519 JWS receipts.

Topology naming: The Topology enum exported by @praetor/sdk retains legacy names for backward compatibility. To use canonical topologies (SINGLE, CHAIN, DISPATCH, ORCHESTRATOR, REVIEW), pass the canonical string value directly when configuring agents or submitting runs.

praetor-ai (Python)

Install with pip install praetor-ai; import as commander. Python ≥ 3.10. Built from packages/python-sdk.

• CommanderGatewayClient — reads PRAETOR_API_URL, defaults to http://127.0.0.1:4000. Use this one.
• CommanderClient / CommanderClientSync — legacy; does not read PRAETOR_API_URL and defaults to port 3001, which is not an API port. Always pass base_url.

Extensions

@praetor/mcp-server

Publishable MCP server that exposes Praetor's Action Gateway tools over stdin/stdout JSON-RPC.

• Binary: commander-mcp-server
• Exposes 8 tools: commander_action_simulate, propose, get, approve, compensation_request, compensation_approve, reconcile, evidence
• Fails closed without PRAETOR_ACTION_GATEWAY_URL
• PRAETOR_MCP_LOCAL_RUNTIME=1 adds dev tools (execute_agent, list_models, route_task)

Client configuration:

{
  "mcpServers": {
    "commander": {
      "command": "commander-mcp-server",
      "args": [],
      "env": {
        "PRAETOR_ACTION_GATEWAY_URL": "https://commander.example",
        "PRAETOR_API_KEY": "replace-with-a-scoped-key"
      }
    }
  }
}

@praetor/plugin-sdk

Plugin authoring surface. A plugin is a default export from createPlugin:

import { createPlugin, defineTool, createHookSubscriptions } from '@praetor/plugin-sdk';

export default createPlugin({
  id: 'my-plugin',
  name: 'My Plugin',
  version: '1.0.0',
  async register(api) {
    api.registerTool(
      defineTool({
        definition: { name: 'greet', description: 'Say hello', inputSchema: {} },
        execute: async () => 'hello',
      }),
    );
    createHookSubscriptions().onAgentComplete(() => {}).subscribeTo(api);
  },
});

Helpers schema(), stringProperty(), numberProperty(), and booleanProperty() build JSON Schemas. Install plugins with commander plugin install <source>.

@praetor/openai-agents-mcp

An independent process boundary that consumes the published Praetor MCP server over stdio using the public @openai/agents SDK. It does not import Praetor packages or call Praetor internals. The deterministic mode is the CI path and makes no model-network request; live mode is opt-in.

Apps and integrations

The workspace globs are apps/*, packages/*, and integrations/*.

App	Package	Purpose
apps/api	@praetor/api	Express 5 HTTP API
apps/web	@praetor/web	React web console

Integration	Package	Purpose
integrations/openai-agents-mcp	@praetor/openai-agents-mcp	Consumes the published Praetor MCP server over stdio

apps/memory/ is a data directory holding JSON memory records (decisions.json, lessons.json, patterns.json, preferences.json, project-context.json, issues.json, index.json). It is not a workspace package and is not built or deployed.