@pmatrix/core-sdk

P-MATRIX Core SDK — Shared HTTP client + Agent Host-Integration Adapter Contract v0.1 5-layer schemas for cross-vendor neutral runtime trust verification.

What it is

@pmatrix/core-sdk is the single source of truth for:

1. PMatrixHttpClient — HTTP transport to P-MATRIX server (/v1/inspect/stream + /v1/agents/*) with retry / backoff / burst-rate handling / local sidecar fallback. Previously duplicated ~2,966 LOC across 6 monitor SDKs, now extracted.
2. Shared types — SafetyMode, TrustGrade, AxesState, SignalPayload, BatchSendResponse, GradeResponse, PMatrixConfig, and others used uniformly across 6 monitor SDKs.
3. Contract v0.1 5-layer schemas (zod) — AgentEvent → NormalizedActionEvent → ObservableFact → AxisEvidence → PEPEvaluationInput. Powers conformance Tier 1 (schema validation) for any host-integration adapter.

See docs/active/contracts/AGENT_HOST_INTEGRATION_ADAPTER_v0_1.md in the parent repository for the full contract specification.

Architectural Position

[Vendor Runtime Surface]  (CLI / IDE / SDK wrap / subagent)
            ↓ host hook fires
[Agent Host-Integration Adapter]  (per-product, thin translator — no judgment)
            ↓ uses @pmatrix/core-sdk
[@pmatrix/core-sdk]  ← THIS PACKAGE
   - PMatrixHttpClient
   - 5-layer schemas (zod)
   - shared types
            ↓
[P-MATRIX Engine]  (sole judgment authority — R(t) / Mode / Trust Ladder / PEP)

Adapters (6 currently: claude-code / codex / cursor / gemini-cli / hermes / openclaw) depend on @pmatrix/core-sdk for transport + types + schemas. Judgment logic stays in the engine, never in adapters or this package.

Install

npm install @pmatrix/core-sdk

Usage

HTTP Client (adapter perspective)

import { PMatrixHttpClient } from '@pmatrix/core-sdk';
import type { PMatrixConfig } from '@pmatrix/core-sdk';

const config: PMatrixConfig = {
  serverUrl: 'https://api.p-matrix.io',
  agentId: 'my-agent-id',
  apiKey: 'pk_xxx',
  safetyGate: { enabled: true, serverTimeoutMs: 2500 },
  credentialProtection: { enabled: true, customPatterns: [] },
  killSwitch: { autoHaltOnRt: 0.75 },
  dataSharing: false,
  batch: { maxSize: 50, flushIntervalMs: 5000, retryMax: 3 },
  debug: false,
};

// Adapter identity — required (parameterized for cross-vendor neutrality)
const client = new PMatrixHttpClient(config, {
  signalSource: 'my_adapter_hook',
  framework: 'my-adapter',
});

const grade = await client.getAgentGrade('agent-001');

Schema Validation (conformance Tier 1)

import {
  AgentEventSchema,
  ObservableFactSchema,
  PEPEvaluationInputSchema,
} from '@pmatrix/core-sdk/schemas';

const event = adapter.emit(rawVendorEvent);
const parsed = AgentEventSchema.safeParse(event);
if (!parsed.success) {
  console.error('Schema drift:', parsed.error.format());
  process.exit(1);
}

Public API

Client

• PMatrixHttpClient — HTTP transport class
• extractRtFromResponse — static helper for parsing engine response

Shared Types (re-exported across 6 adapters)

• SafetyMode / TrustGrade / ToolRiskTier / GateAction
• AxesState / SignalPayload / SignalMetadata
• BatchSendResponse / GradeResponse / AgentGradeDetail / AgentGradeHistoryItem
• PMatrixConfig and config sub-types (SafetyGateConfig / CredentialProtectionConfig / KillSwitchConfig / BatchConfig)
• AdapterIdentity (new — parameterizes signal_source + framework)
• SessionSummaryInput (generic — vendor branding via client config, not hardcoded)

Contract v0.1 5-layer Schemas (zod)

• AgentEventSchema (Layer 1)
• NormalizedActionEventSchema (Layer 2)
• ObservableFactSchema (Layer 3)
• AxisEvidenceSchema (Layer 4)
• PEPEvaluationInputSchema (Layer 5)

Contract v0.1 5-layer Inferred Types

• AgentEvent / NormalizedActionEvent / ObservableFact / AxisEvidence / PEPEvaluationInput
• AxisName (8-axis enum literal)

Utils

• sleep(ms) — Promise-based delay
• generateRequestId() — UUID v4 with fallback
• parseRetryAfter(header) — RFC 7231 Retry-After parser

Versioning + Lockstep

@pmatrix/core-sdk follows Lockstep §6.3 v0.2 3-layer coupling:

Server (FastAPI)
  ↕ semver compatibility
@pmatrix/core-sdk  (← this package)
  ↕ direct dep, tilde range (pre-1.0 semantics)
6+ Agent Host-Integration Adapter SDK

Pre-1.0 phase (v0.x):

• Minor bump (0.1.0 → 0.2.0) = breaking change (npm convention) → all 6+ adapter SDKs co-bump
• Patch bump (0.1.0 → 0.1.1) = backward compatible
• Adapter dependency spec: "@pmatrix/core-sdk": "~0.1.0" (tilde, NOT caret)

Content-Agnostic Invariant

This SDK and all downstream adapters never read or transmit prompt content, response content, or any user-generated text. Only hashes, state vectors, axis evidence, and structured metadata cross the wire. See content_included: false invariant in the contract spec.

License

Apache-2.0. See LICENSE.

Repository

https://github.com/p-matrix/core-sdk

Security Reporting

See SECURITY.md.