@cowork-trust/trust

NPM SDK and CLI for the CoWork Trust Engine. Use it to ask a hosted Trust Engine whether an agent action should be allowed, reviewed, approved, or denied before the agent executes external work.

Install

npm install @cowork-trust/trust
npx @cowork-trust/trust --help

SDK: Agent Runtime

For production agent code, use an actor-bound API key. Create the actor and key from the hosted UI or admin API, then give the agent runtime only that actor key.

import { CoworkTrust } from "@cowork-trust/trust";

const trust = new CoworkTrust({
  apiUrl: process.env.COWORK_TRUST_API_URL,
  apiKey: process.env.COWORK_TRUST_AGENT_KEY,
  actor: {
    externalId: "support-bot-1",
    type: "agent",
    platform: "claude",
  },
});

const decision = await trust.evaluate({
  action: {
    type: "commerce.replacement.create",
    category: "write",
    topic: "commerce.replacements",
  },
  resource: {
    type: "order",
    id: "order-123",
  },
});

Decision handling pattern:

allow -> execute
allow_with_review -> execute with audit/review
require_approval -> ask a human first
deny -> block

After execution, send feedback so trust can learn:

await trust.feedback(decision.evaluationId, {
  signalType: "executed_successfully",
});

You can inspect the configured actor without repeating its ID:

await trust.currentActor.score();
await trust.currentActor.score({ topic: "commerce.replacements" });
await trust.currentActor.topics();
await trust.currentActor.history({ topic: "commerce.replacements" });

Actor-Bound Keys

Actor-bound keys are the recommended runtime credential for agents:

workspace
  -> actor-bound API key
    -> actor
      -> topic scores
      -> evaluations/signals

An actor-bound key can only evaluate as, read scores for, and submit feedback for its bound actor. It cannot create workspaces, create actors, manage API keys, mutate policy, or read another actor's trust data.

Workspace admin keys and Clerk dashboard auth are for setup and management flows.

Topic Trust

Add action.topic to make trust contextual. An agent can be trusted for crm.contacts or commerce.replacements while still requiring approval for billing.export or commerce.refunds.

await trust.score("agent-1", { topic: "crm.contacts" });
await trust.actors.topics("agent-1");

Admin Key Creation Helpers

Management should normally happen through the hosted UI or admin API. The SDK still exposes key helpers for server/admin automation:

await trust.keys.create({
  name: "support-bot-1-runtime",
  keyType: "actor",
  actorExternalId: "support-bot-1",
});

Raw API keys are returned only once. Store only the generated key in the agent runtime secret store.

CLI Login

npx @cowork-trust/trust login --api-url https://cowork-hubspot-integration-staging.up.railway.app
npx @cowork-trust/trust whoami
npx @cowork-trust/trust smoke

The CLI stores credentials in ~/.cowork/trust/config.json. You can also pass --api-url and --api-key, or set COWORK_API_URL and COWORK_API_KEY.

CLI Commands

cowork-trust evaluate --category read --action resource.read --resource record:123 --topic crm.contacts
cowork-trust score --actor agent-1 --topic crm.contacts
cowork-trust feedback --evaluation <evaluation-id> --signal approved
cowork-trust actors topics agent-1
cowork-trust actors history agent-1 --topic crm.contacts
cowork-trust keys create --name support-bot-runtime --actor support-bot-1
cowork-trust policy get
cowork-trust evaluations list

Workspace and actor creation are intentionally not CLI-first for V0. Use the hosted UI or admin API so workspace setup stays auditable.

Hosted UI

Open the hosted API root, for example:

https://cowork-hubspot-integration-staging.up.railway.app/dashboard

The UI lets workspace users create API keys, inspect evaluations, review actor/topic scores, send feedback signals, and update policy thresholds.

Security Boundary

CoWork Trust does not execute external actions and does not store connector credentials. Agent tools and connector gateways keep external credentials; the Trust Engine decides, audits, scores, and learns.