Client Reference

Complete reference for the SequencewareClient class.

Constructor

new SequencewareClient(config: ClientConfig)

Parameter	Type	Required	Default	Description
baseUrl	string	Yes	—	Sequenceware API URL
apiKey	string	No	—	API key (acl_...)
agentId	string	Yes	—	Unique agent identifier
apiVersion	string	No	'v1'	API version prefix (e.g., 'v1')
timeout	number	No	10000	Request timeout (ms)
maxRetries	number	No	3	Max retry attempts
retryDelay	number	No	1000	Base retry delay (ms)

The SDK automatically prefixes all API requests with the configured apiVersion (default 'v1'). It also sends an X-SDK-Version header with every request for server-side compatibility tracking.

Event tracking

startRun(runId?, metadata?, reason?, agentContext?)

Start a new agent run.

const runId = await client.startRun(undefined, { task: 'Fix auth bug' });
// or with a reason for the run:
const runId = await client.startRun(undefined, {}, 'Fix the session expiry bug from JIRA-1234');
// or with agent context:
const runId = await client.startRun(
  undefined,
  { task: 'Fix auth bug' },
  'Fix the session expiry bug from JIRA-1234',
  {
    goal: 'Fix the session expiry bug',
    reasoning: 'Session tokens are not being refreshed correctly',
    conversationId: 'conv_abc123',
  },
);

Parameters:

Name	Type	Description
runId	string?	Optional custom run ID. Auto-generated if omitted.
metadata	Record<string, any>?	Optional metadata (task description, context, etc.)
reason	string?	Why the agent is performing this run (shown in dashboard)
agentContext	AgentContext?	Optional context about the agent's goal, reasoning, and conversation (see AgentContext)

Returns: Promise<string> — the run ID.

---

completeRun(runId, metadata?)

Mark a run as successfully completed.

await client.completeRun(runId, { result: 'PR created' });

---

failRun(runId, metadata?)

Mark a run as failed.

await client.failRun(runId, { error: 'Connection timeout' });

---

startStep(runId, stepId?, metadata?)

Start a new step within a run.

const stepId = await client.startStep(runId, undefined, { phase: 'analysis' });

Returns: Promise<string> — the step ID.

---

completeStep(runId, stepId, metadata?)

Complete a step.

await client.completeStep(runId, stepId);

---

trackToolCall(runId, toolName, inputPayload, metadata?, actionHint?, reason?, agentContext?)

Track a tool call. This is where policy evaluation happens.

const tcId = await client.trackToolCall(
  runId,
  'create_pull_request',
  { repo: 'my-org/api', title: 'Add caching' },
  undefined,
  'pr_create',
  'Opening a PR with the caching layer for review',
  {
    goal: 'Improve API response times',
    reasoning: 'Adding a Redis caching layer will reduce DB load by ~60%',
  },
);

Parameters:

Name	Type	Description
runId	string	The run this tool call belongs to
toolName	string	Name of the tool being called
inputPayload	Record<string, any>	The tool's input parameters
metadata	Record<string, any>?	Additional metadata
actionHint	string?	Semantic action hint (e.g., deploy, pr_merge)
reason	string?	Why the agent chose this action (shown in dashboard and approval cards)
agentContext	AgentContext?	Optional context about the agent's goal and reasoning for this action (see AgentContext)

Returns: Promise<string> — the tool call ID.

---

completeToolCall(runId, toolCallId, outputPayload, metadata?)

Report the result of a tool call.

await client.completeToolCall(runId, tcId, { prNumber: 42, url: '...' });

---

trackEvent(runId, eventType, metadata?)

Send a generic event.

import { EventType } from '@sequenceware/sdk';
await client.trackEvent(runId, EventType.RISK_DETECTED, { severity: 'high' });

Read helpers

getRuns()

List all runs.

const runs: RunSummary[] = await client.getRuns();

Returns an array of RunSummary:

interface RunSummary {
  runId: string;
  agentId: string;
  status: string;
  startedAt: string;
  completedAt?: string;
  durationMs?: number;
  highestRiskLevel?: string;
  reason?: string;
  agentContext?: AgentContext;
}

---

getRun(runId)

Get full run details including steps, tool calls, risk events, and approvals.

const run = await client.getRun(runId);

---

getApprovals(status?)

List approval requests, optionally filtered by status.

const pending = await client.getApprovals('pending');
const all = await client.getApprovals();

Returns an array of ApprovalRequest:

interface ApprovalRequest {
  approvalId: string;
  runId: string;
  toolCallId?: string;
  policyId?: string;
  status: ApprovalStatus;  // 'pending' | 'approved' | 'rejected'
  reason: string;
  requestedAt: string;
  resolvedAt?: string;
  resolvedBy?: string;
  decisionReason?: string;
}

---

approveRequest(approvalId, reason?)

Approve a pending approval request.

await client.approveRequest('appr_abc123', 'Reviewed and safe');

---

rejectRequest(approvalId, reason?)

Reject a pending approval request.

await client.rejectRequest('appr_abc123', 'Too risky');

---

getPolicies()

List all policies.

const policies: Policy[] = await client.getPolicies();

---

createPolicy(data)

Create a new policy.

const policy = await client.createPolicy({
  name: 'Block destructive ops',
  description: 'Block rm -rf and similar',
  matchConditions: [
    { field: 'toolName', operator: 'matches', value: 'rm.*-rf' },
  ],
  action: 'block',
  enabled: true,
});

---

getAuditLogs(runId?)

Get audit logs, optionally filtered by run.

const logs: AuditLog[] = await client.getAuditLogs('run_abc123');

Returns an array of AuditLog:

interface AuditLog {
  auditId: string;
  runId?: string;
  entityType: string;
  entityId: string;
  action: string;
  actorType: string;   // 'agent' | 'system' | 'user'
  actorId: string;
  timestamp: string;
  metadata?: Record<string, any>;
}