SDK Documentation

claw.guard(context)

Evaluate guard policies for a proposed action. Call this before risky operations. The guard response includes a `learning` field with historical performance context when available (recent scores, drift status, learned patterns, feedback summary).

Returns: Promise<{ decision: string, reasons: string[], risk_score: number, agent_risk_score: number | null }>

const result = await claw.guard({ action_type: 'deploy', risk_score: 85 });

claw.getSignals() / claw.get_signals()

Get current risk signals across all agents.

Returns: Promise<{ signals: Object[] }>

const { signals } = await claw.getSignals();

claw.heartbeat(status, metadata) / claw.heartbeat(status=..., metadata=...)

Report agent presence and health to the control plane. Call periodically to indicate the agent is alive.

await claw.heartbeat('online', { cycle: 42, uptime_ms: 360000 });

claw.reportConnections(connections) / claw.report_connections(connections)

Report active provider connections and their status. Appears in the agent's Fleet profile.

await claw.reportConnections([
  { name: 'OpenAI', type: 'llm', status: 'connected' },
  { name: 'Postgres', type: 'database', status: 'connected' },
]);

claw.registerOpenLoop(actionId, type, desc) / claw.register_open_loop(...)

Register an unresolved dependency for a decision. Open loops track work that must be completed before the decision is fully resolved.

await claw.registerOpenLoop(action_id, 'validation', 'Waiting for PR review');

claw.resolveOpenLoop(loopId, status, res) / claw.resolve_open_loop(...)

Resolve a pending loop.

await claw.resolveOpenLoop(loop_id, 'completed', 'Approved');

claw.recordAssumption(asm) / claw.record_assumption(asm)

Record what the agent believed to be true when making a decision.

await claw.recordAssumption({ action_id, assumption: 'User is authenticated' });

claw.getLearningVelocity() / claw.get_learning_velocity()

Compute learning velocity (rate of score improvement) for agents.

Returns: Promise<{ velocity: Array<Object> }>

const { velocity } = await claw.getLearningVelocity();

claw.getLearningCurves() / claw.get_learning_curves()

Compute learning curves per action type to measure efficiency gains.

const curves = await claw.getLearningCurves();

claw.getLessons({ actionType, limit }) / claw.get_lessons(action_type=..., limit=...)

Fetch consolidated lessons from scored outcomes — what OSuite has learned about this agent's performance patterns.

Returns: Promise<{ lessons: Object[], drift_warnings: Object[], agent_id: string }>

const { lessons, drift_warnings } = await claw.getLessons({ actionType: 'deploy' });
lessons.forEach(l => console.log(l.guidance));

claw.renderPrompt() / claw.render_prompt()

Fetch rendered prompt from OSuite.

const { rendered } = await claw.renderPrompt({
  template_id: 'marketing',
  variables: { company: 'Apple' }
});

claw.createScorer(name, type, config) / claw.create_scorer(...)

Create a reusable scorer definition for automated evaluation.

await claw.createScorer('toxicity', 'regex', { pattern: 'bad-word' });

claw.createScoringProfile(config) / claw.create_scoring_profile(...)

Define weighted quality scoring profiles across multiple scorers.

await claw.createScoringProfile({ 
  name: 'prod-quality', 
  dimensions: [{ scorer: 'toxicity', weight: 0.5 }] 
});

claw.sendMessage(params) / claw.send_message(**kwargs)

Send a point-to-point message or broadcast to all agents in the organization.

await claw.sendMessage({
  to: 'scout-agent-01',
  body: 'I have finished indexing the repository. You can start the analysis.',
  type: 'status'
});

claw.getInbox(options?) / claw.get_inbox(**kwargs)

Retrieve messages from the agent inbox with optional filtering.

Returns: Promise<{ messages, total, unread_count }>

const { messages } = await claw.getInbox({ unread: true, limit: 10 });

claw.createHandoff(handoff) / claw.create_handoff(**kwargs)

Create a session handoff document to persist state between agent sessions or transfer context to another agent.

await claw.createHandoff({
  summary: 'Completed initial data collection from Jira.',
  key_decisions: ['Prioritize high-severity bugs', 'Ignore closed tickets'],
  open_tasks: ['Run security scan on src/', 'Draft fix for #123'],
  next_priorities: ['Security audit']
});

claw.getLatestHandoff() / claw.get_latest_handoff()

Retrieve the most recent handoff for the current agent.

Returns: Promise<Object|null>

const handoff = await claw.getLatestHandoff();

claw.scanPromptInjection(text) / claw.scan_prompt_injection(text)

Scan untrusted input for potential prompt injection or jailbreak attempts.

Returns: Promise<{ clean: boolean, risk_level: string, recommendation: string }>

const result = await claw.scanPromptInjection(userInput);
if (!result.clean) {
  console.warn('Injection risk:', result.risk_level);
}

claw.submitFeedback(params) / claw.submit_feedback(**kwargs)

Submit feedback for a specific agent action. Used for human evaluation of agent performance.

await claw.submitFeedback({
  action_id: 'act_4b2s8...',
  rating: 4,
  comment: 'Action was safe and effective but took longer than expected.',
  category: 'performance_review'
});

claw.createThread(options) / claw.create_thread(**kwargs)

Create a new context thread to track a multi-step reasoning chain or investigation.

Returns: Promise<{ thread, thread_id }>

const { thread } = await claw.createThread({ name: 'Deploy analysis', summary: 'Evaluating safety' });

claw.addThreadEntry(threadId, content, entryType) / claw.add_thread_entry(...)

Append an observation, conclusion, or decision to an existing context thread.

await claw.addThreadEntry('ct_abc123', 'Staging checks passed', 'observation');

claw.closeThread(threadId, summary?) / claw.close_thread(thread_id, summary=None)

Close a context thread, optionally providing a final summary.

await claw.closeThread('ct_abc123', 'Deploy approved after staging check');

claw.syncState(state) / claw.sync_state(**kwargs)

Bulk-sync agent state including decisions, lessons, goals, context, relationships, memory, and preferences in a single call.

await claw.syncState({ decisions: [...], lessons: [...], goals: [...] });

POST /api/pairings

Create an agent pairing request. The agent submits its public key and waits for operator approval.

Returns: { pairing: { id, status, agent_name, created_at } }

// Node SDK (v1 legacy)
import { OSuite } from 'osuite/legacy';
const claw = new OSuite({ baseUrl, apiKey, agentId });

const { pairing } = await claw.createPairing(publicKeyPem, 'RSASSA-PKCS1-v1_5', 'my-agent');
console.log(pairing.id); // pair_...

GET /api/pairings

List all pairing requests for the organization. Admin API key required.

Returns: { pairings: Array<{ id, status, agent_name, created_at, approved_at }> }

const res = await fetch('/api/pairings', {
  headers: { 'x-api-key': adminApiKey }
});
const { pairings } = await res.json();

GET /api/pairings/:id

Get a specific pairing request by ID. Used by agents to poll for approval status.

Returns: { pairing: { id, status, agent_name, created_at, approved_at } }

// Node SDK (v1 legacy)
const status = await claw.getPairing(pairingId);
console.log(status.pairing.status); // pending | approved | expired

POST /api/pairings/:id/approve

Approve a pending pairing request. Admin API key required. On approval, the agent's public key is registered as a trusted identity.

Returns: { pairing: { id, status, approved_at } }

const res = await fetch(`/api/pairings/${pairingId}/approve`, {
  method: 'POST',
  headers: { 'x-api-key': adminApiKey }
});

POST /api/identities

Directly register an agent's public key as a trusted identity. Admin API key required. Bypasses the pairing flow.

Returns: { identity: { agent_id, algorithm, created_at } }

// Node SDK (v1 legacy)
await claw.registerIdentity('agent-007', publicKeyPem, 'RSASSA-PKCS1-v1_5');

GET /api/identities

List all registered agent identities for the organization. Admin API key required.

Returns: { identities: Array<{ agent_id, algorithm, created_at }> }

// Node SDK (v1 legacy)
const { identities } = await claw.getIdentities();

DELETE /api/identities/:agentId

Revoke a registered agent identity. Admin API key required. The agent's public key is removed and signature verification will fail for future actions.

Returns: { success: true }

const res = await fetch(`/api/identities/${agentId}`, {
  method: 'DELETE',
  headers: { 'x-api-key': adminApiKey }
});