oceum

Official SDK for Oceum — governed agent infrastructure. Progressive autonomy, zero-knowledge vault, governed execution, and enterprise-grade observability.

Zero dependencies. Works with Node.js 18+, Deno, and Bun.

Install

npm install oceum

Quick Start

const { Oceum } = require('oceum');

const client = new Oceum({
  apiKey: process.env.OCEUM_API_KEY,  // oc_xxx
  agentId: process.env.OCEUM_AGENT_ID, // agt_xxx
});

// Start auto-heartbeat (every 60s)
client.startHeartbeat();

// Wrap tasks with automatic logging
const result = await client.wrap('Process leads', async () => {
  const leads = await fetchLeads();
  await processAll(leads);
  return leads.length;
});

// Report LLM usage for cost tracking
await client.reportUsage({
  model: 'claude-sonnet',
  tokensInput: 1200,
  tokensOutput: 450,
});

// Clean up
client.stopHeartbeat();
await client.setStatus('idle');

No SDK? No Problem

Oceum is just HTTP. Any language, any framework — POST JSON to the webhook endpoint:

# Heartbeat
curl -X POST https://oceum.ai/api/webhook \
  -H "Authorization: Bearer $OCEUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event":"heartbeat","agentId":"agt_xxx"}'

# Report a completed task
curl -X POST https://oceum.ai/api/webhook \
  -H "Authorization: Bearer $OCEUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event":"task_complete","agentId":"agt_xxx","data":{"taskName":"sync-orders"}}'

# Report LLM usage
curl -X POST https://oceum.ai/api/webhook \
  -H "Authorization: Bearer $OCEUM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event":"usage","agentId":"agt_xxx","data":{"model":"gpt-4o","tokensInput":500,"tokensOutput":200}}'

Python:

import requests

API_KEY = "oc_xxx"
AGENT_ID = "agt_xxx"

requests.post("https://oceum.ai/api/webhook",
    headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
    json={"event": "heartbeat", "agentId": AGENT_ID}
)

API

| Method | Description | |--------|-------------| | heartbeat() | Send keep-alive, sets status to active | | taskStart(name, meta?) | Log task initiation | | taskComplete(name, meta?) | Log task completion, increments count | | error(name, opts?) | Log error, { fatal: true } sets error status | | warning(msg, meta?) | Log non-critical warning | | setStatus(status) | Set status: active, idle, paused, offline, error | | startHeartbeat(ms?) | Auto-heartbeat every N ms (default: 60s) | | stopHeartbeat() | Stop auto-heartbeat | | wrap(name, fn, meta?) | Auto start/complete/error around async fn | | reportUsage(opts?) | Report LLM token usage for cost tracking | | memory(content, opts?) | Write shared memory visible to peer agents | | readMemory(opts?) | Read shared memory entries | | vaultStore(data, opts?) | Store sensitive data, returns vault token | | vaultRetrieve(token) | Retrieve data using vault token | | vaultProxy(token, req) | Zero-knowledge API call with vault credential | | vaultRevoke(token) | Permanently revoke a vault token | | vaultList(opts?) | List vault tokens (metadata only) |

Platform Capabilities

The Oceum platform (which this SDK connects to) includes:

• Governed Execution Engine -- Job queue with credential injection, approval workflows, and full audit trail
• Protocol Adapters -- REST, SOAP (WS-Security), SFTP, and JDBC adapters for legacy system integration
• Data Mapping -- Canonical business object translation between legacy formats
• 28 OAuth Integrations -- Pre-built connectors for Slack, Google, Salesforce, Stripe, and more

Agents interact with these capabilities through the webhook API. See oceum.ai/docs-public for full platform documentation.

Cost Tracking

Report LLM token usage per call. Oceum calculates cost using configurable model pricing and enforces budget caps automatically.

// After an LLM call
await client.reportUsage({
  model: 'claude-haiku',
  tokensInput: 800,
  tokensOutput: 200,
});

// Or include usage in task_complete meta for automatic tracking
await client.taskComplete('generate-report', {
  usage: { model: 'gpt-4o', tokensInput: 2000, tokensOutput: 1500 }
});

Budget caps, alert thresholds, and per-model pricing are configured in the Oceum dashboard under Settings > Cost Controls.

Error Handling

const { Oceum, OceumError } = require('oceum');

try {
  await client.heartbeat();
} catch (err) {
  if (err instanceof OceumError) {
    console.log(err.statusCode); // 401, 404, etc.
    console.log(err.body);       // API response
  }
}

Webhook Verification

Verify incoming webhook signatures with HMAC-SHA256:

const valid = Oceum.verifyWebhookSignature(rawBody, signature, secret);

Docs

Full documentation: oceum.ai/docs-public

License

MIT